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

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