# 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](ADR-002-namespace-system.md) | Namespace System | Projects are namespace-scoped entities using the universal naming convention |
| [ADR-008](ADR-008-resource-system.md) | Resource System | Projects link and scope the resources available for plan execution |
| [ADR-014](ADR-014-context-management-acms.md) | Context Management (ACMS) | Projects configure context retrieval strategies and index scopes |
| [ADR-016](ADR-016-invariant-system.md) | 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**
