cleveragents-core/docs/adr/ADR-009-project-model.md

ADR-009: Project Model

Status: Accepted
Date: 2026-02-16
Supersedes: None
Author(s): Jeffrey Phillips Freeman Jeffrey.Freeman@CleverThis.com
Approver(s): Jeffrey Phillips Freeman Jeffrey.Freeman@CleverThis.com

Context

Plans need a defined scope that answers: "Where is the work happening? What can this plan read and write? What skills and tools are available? What context is available?" Without a project abstraction, every plan would need to independently specify its resources, context configuration, and constraints — leading to repetition, inconsistency, and difficulty managing shared configuration across related plans.

Decision

A project is the named scope that binds together a collection of linked resources, context configuration, and invariants. Projects are created via CLI commands (not YAML configuration files). They determine what a plan can access and how context is assembled. A plan targets one or more projects when used.

Design

Project Identity

Projects use the namespace system: name is the namespaced project name (e.g., local/api-service). The name serves as the globally unique identifier — no separate ULID is generated. Projects carry a derived is_remote boolean based on whether all linked resources are remotely accessible.

Project Types

Type	Definition	Plan Execution
Local	Contains at least one local-only resource	Client only
Remote	All resources are remotely accessible	Client or Server

Linked Resources

Projects link to independently registered resources from the Resource Registry. Each link carries:

• resource_id: ULID reference to the registered resource.
• project_read_only: Boolean — project-level read-only override (independent of the resource's own read-only flag).
• alias: Optional short name for use within the project context.

Resources are linked via agents project link and can be linked to multiple projects simultaneously.

Context Configuration

Projects configure how context is assembled for plans targeting them:

• Ignore patterns: File/path patterns excluded from context gathering.
• Max file size: Maximum file size for context inclusion.
• Indexing strategy: Which index backends to use (full-text, vector, graph).
• Chunking/summarization policy: How large files are broken down or summarized.
• Context retention policy: How long context tiers are retained.

These settings override the global context.* configuration keys for plans targeting this project.

Multi-Project Operations

A single plan may target multiple projects. In multi-project execution:

• Strategize clarifies which steps affect which projects.
• Execute isolates sandboxes per project (shared resources get a single sandbox).
• Apply commits changes per project separately.
• Tool resource bindings are resolved per-project.

Project-Scoped Configuration

Many global configuration keys are project-scopable — they can be overridden at the project level. Project-scoped values take precedence over global config but are overridden by plan-level or CLI-level settings. Key project-scopable settings include: sandbox.strategy, sandbox.checkpoint.enabled, plan.concurrency, plan.max-child-depth, core.automation-profile, and all context.* keys.

Constraints

• Projects are created via CLI commands, not YAML configuration files.
• Projects link to resources; they do not define resources inline. Resources must be independently registered before linking.
• The project name (namespaced) is the unique identifier. No two projects may share the same namespace/name.
• A plan targeting a project can only access resources linked to that project. Unlinked resources are invisible to the plan.
• Project-scoped configuration overrides global defaults but does not override plan-level or CLI-level settings.

Consequences

Positive

• Reusable project definitions avoid repetitive resource and context configuration across plans.
• Project-scoped configuration enables different teams or codebases to have different automation profiles, sandbox strategies, and context budgets.
• Multi-project support enables cross-codebase operations (e.g., updating an API and its client library in one plan).
• The link-based model means resource definitions are maintained in one place, even when shared across projects.

Negative

• The indirection between projects and resources (link rather than inline) requires additional setup steps.
• Multi-project plans add complexity to sandbox management, tool binding resolution, and change merging.
• Project-scoped configuration creates another layer in the resolution chain, which may be confusing when debugging effective configuration values.

Risks

• Stale resource links (pointing to resources that have been removed or moved) could cause plan failures at execution time rather than at planning time.
• Multi-project plans with shared resources require careful sandbox coordination to avoid conflicts.

Alternatives Considered

None — specification-driven requirement. The project model as a named scope with linked resources, context configuration, and invariant attachment is prescribed by the specification.

Compliance

• Link validation: agents project link verifies that the target resource exists in the registry and that no duplicate links are created.
• Scope enforcement tests: Tests verify that plans can only access resources linked to their target project(s).
• Multi-project tests: Integration tests exercise plans targeting multiple projects with overlapping and non-overlapping resources.
• Configuration resolution tests: Tests verify the full resolution chain (CLI > plan > action > project > global > default) for project-scopable keys.
• Code review: New project-scopable configuration keys must be documented and tested for correct precedence.

Related ADRs

ADR	Title	Relationship
ADR-002	Namespace System	Projects are namespace-scoped entities using the universal naming convention
ADR-008	Resource System	Projects link and scope the resources available for plan execution
ADR-014	Context Management (ACMS)	Projects configure context retrieval strategies and index scopes
ADR-016	Invariant System	Projects define project-scoped invariants that constrain all plans within

Acceptance

Votes For

Voter	Comment
Jeffrey Phillips Freeman Jeffrey.Freeman@CleverThis.com	Projects as named scopes linking resources, context, and invariants provide a clean organizational boundary

Total: 1

Votes Against

Voter	Comment

Total: 0

Abstentions

Voter	Comment

Total: 0