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

adr_number, title, status_history, tier, authors, superseded_by, related_adrs, acceptance

adr_number	title	status_history	tier	authors	superseded_by	related_adrs	acceptance
9	Project Model	2026-02-16 Proposed Jeffrey Phillips Freeman 2026-02-16 Accepted Jeffrey Phillips Freeman	2	Jeffrey Phillips Freeman	null	number title relationship 2 Namespace System Projects are namespace-scoped entities using the universal naming convention number title relationship 8 Resource System Projects link and scope the resources available for plan execution number title relationship 14 Context Management (ACMS) Projects configure context retrieval strategies and index scopes number title relationship 16 Invariant System Projects define project-scoped invariants that constrain all plans within	votes_for votes_against abstentions voter comment Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> Projects as named scopes linking resources, context, and invariants provide a clean organizational boundary

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 Drivers

• Plans need a defined scope answering: what resources can be accessed, what tools are available, and how context is assembled
• Without a project abstraction, every plan would independently specify resources, context config, and constraints — causing repetition and inconsistency
• Must support multi-project operations where a single plan targets multiple codebases
• Project-scoped configuration must override global defaults while being overridable by plan-level or CLI-level settings
• Resources should be linked (not defined inline) so resource definitions are maintained in one place even when shared
• Projects must be created via CLI commands to align with the operational workflow, not YAML configuration files

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.