forked from HAL9000/cleveragents-core
freemo
738c3b5eda
Add domain models, application service, CLI integration, and full test coverage for multi-project subplan orchestration. New components: - MultiProjectMetadata, ProjectScope, ProjectDependency domain models - MultiProjectService for creating/managing multi-project plans - CLI display of multi-project metadata in plan commands - Behave BDD tests (20 scenarios), Robot Framework integration tests, ASV benchmarks, and reference documentation Also fixes pre-existing test flakiness in cli_core, core_cli_commands, cli_plan_context_commands, and helper_server_stubs caused by environment leakage and path-with-spaces issues. ISSUES CLOSED: #199
116 lines
4.0 KiB
Markdown
116 lines
4.0 KiB
Markdown
# Multi-Project Plans
|
|
|
|
## Overview
|
|
|
|
CleverAgents supports plans that target multiple projects simultaneously.
|
|
When a plan is created with more than one `--project` flag (or multiple
|
|
positional project arguments), a **multi-project plan** is formed.
|
|
|
|
Each project receives an isolated **ProjectScope** that tracks:
|
|
|
|
- Which resource IDs belong to the project
|
|
- Whether the project is read-only or writable
|
|
- Per-project changeset summaries during execution
|
|
|
|
## Creating a Multi-Project Plan
|
|
|
|
```bash
|
|
agents plan use local/refactor-api \
|
|
--project api-service \
|
|
--project shared-lib \
|
|
--arg target_coverage=80
|
|
```
|
|
|
|
## Alias Resolution
|
|
|
|
Projects can be given aliases for easier reference in multi-project
|
|
contexts:
|
|
|
|
```bash
|
|
agents plan use local/migrate-schema \
|
|
api-service@api \
|
|
shared-lib@lib
|
|
```
|
|
|
|
The `ProjectScopeResolver.resolve_alias()` method searches aliases first,
|
|
then falls back to project names.
|
|
|
|
## Scope Isolation
|
|
|
|
Each project scope is independently tracked:
|
|
|
|
| Field | Description |
|
|
|---------------------|---------------------------------------------|
|
|
| `project_name` | Namespaced project identifier |
|
|
| `alias` | Optional short name for quick reference |
|
|
| `read_only` | Whether mutations are forbidden |
|
|
| `resource_ids` | Resources belonging to this project |
|
|
| `changeset_summary` | Per-project file change statistics |
|
|
|
|
## Mixed Access Enforcement
|
|
|
|
By default, plans with mixed read-only and writable projects are
|
|
flagged with a warning. To explicitly allow mixed access, set
|
|
`allow_mixed_access=True` on the `MultiProjectMetadata`.
|
|
|
|
When `allow_mixed_access` is `False` (the default), validation returns
|
|
an error listing the read-only and writable projects.
|
|
|
|
## Cross-Project Dependencies
|
|
|
|
The `CrossProjectDependency` model captures directional dependencies
|
|
between projects within a plan:
|
|
|
|
```
|
|
source_project -> target_project (dependency_type)
|
|
```
|
|
|
|
Examples:
|
|
- `api-service -> shared-lib` (imports)
|
|
- `frontend -> api-service` (api-consumer)
|
|
|
|
## Per-Project Changeset Summaries
|
|
|
|
During execution, each project scope records a `ChangeSetSummary`:
|
|
|
|
| Field | Description |
|
|
|----------------------|---------------------------------------|
|
|
| `files_changed` | Number of modified files |
|
|
| `files_added` | Number of created files |
|
|
| `files_deleted` | Number of deleted files |
|
|
| `total_lines_changed`| Total lines added + removed |
|
|
| `validation_passed` | Per-project validation result |
|
|
| `validation_errors` | Error messages from validation |
|
|
|
|
These summaries appear in `agents plan status` output and in the
|
|
`as_cli_dict()` representation under `multi_project.project_scopes`.
|
|
|
|
## Domain Models
|
|
|
|
| Class | Module |
|
|
|---------------------------|-------------------------------------------------|
|
|
| `ProjectScope` | `cleveragents.domain.models.core.multi_project` |
|
|
| `ChangeSetSummary` | `cleveragents.domain.models.core.multi_project` |
|
|
| `MultiProjectMetadata` | `cleveragents.domain.models.core.multi_project` |
|
|
| `CrossProjectDependency` | `cleveragents.domain.models.core.multi_project` |
|
|
| `ProjectScopeResolver` | `cleveragents.domain.models.core.multi_project` |
|
|
|
|
## Service Layer
|
|
|
|
`MultiProjectService` (in `cleveragents.application.services.multi_project_service`)
|
|
provides:
|
|
|
|
- `initialize_scopes(plan, available_resources)` -- Creates metadata
|
|
- `resolve_context_view(plan, name_or_alias)` -- Returns a ProjectScope
|
|
- `record_changeset(plan, project_name, summary)` -- Records changes
|
|
- `validate_cross_project(plan)` -- Validates constraints
|
|
|
|
## Plan Model Extensions
|
|
|
|
The `Plan` model gains:
|
|
|
|
- `multi_project_metadata: MultiProjectMetadata | None` field
|
|
- `is_multi_project: bool` computed property
|
|
- `get_project_scope(name_or_alias)` method
|
|
- Extended `as_cli_dict()` with multi-project section
|