cleveragents-core/docs/reference/multi_project_plans.md

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