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

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:

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

4.0 KiB Raw Permalink Blame History