cleveragents-core/docs/adr/index.md

# Architecture Decision Records

This directory contains the Architecture Decision Records (ADRs) for CleverAgents. Each ADR captures a single significant architectural decision — the context that motivated it, the decision itself, its design implications, constraints, consequences, and how compliance is verified.

All ADRs derive their content from the [CleverAgents Specification](../specification.md), which is the sole source of truth for the system's architecture and behavior.

## ADR Format

Every ADR follows a consistent template with metadata, content, and governance sections:

### Metadata

Presented as plain text fields at the top of each ADR, one per line:

| Field | Purpose |
|-------|---------|
| **Status** | Current state of the decision: `Accepted`, `Proposed`, `Deprecated`, or `Superseded`. |
| **Date** | Date the decision was accepted or last revised. |
| **Supersedes** | Reference to a prior ADR this one replaces, or `None`. |
| **Author(s)** | Contributors who authored or substantially edited the ADR text. |
| **Approver(s)** | Person(s) who verified the voting record and signed off on acceptance. |

### Content Sections

#### Context

Describes the problem, situation, or forces that motivated the decision. This section explains *why* the ADR exists — what technical challenge, scaling concern, or design tension required an explicit architectural choice. It should give a reader who is unfamiliar with the project enough background to understand the decision without reading the full specification.

#### Decision

States the architectural choice that was made, written in declarative form (e.g., "CleverAgents adopts X"). This is the core commitment of the ADR — a concise, authoritative statement of what was decided. Implementation details belong in Design; this section focuses on the *what*, not the *how*.

#### Design

Provides the structural details that realize the decision: components, interfaces, data models, patterns, protocols, and interaction flows. This is typically the longest section of an ADR and may include sub-headings, diagrams, and code-level specifics. The Design section should give an implementer enough information to build the feature correctly without inventing architectural choices on their own.

#### Constraints

Lists the explicit rules and restrictions the decision imposes on the codebase. Constraints are enforceable invariants — statements like "module X must never import from module Y" or "all domain models must use Pydantic strict mode." They serve as guardrails that CI checks, linters, and code review can verify mechanically.

#### Consequences

Documents the outcomes of the decision, organized into three categories: **Positive** (benefits gained), **Negative** (trade-offs accepted), and **Risks** (potential future problems). Honest accounting of trade-offs is essential — an ADR that lists only positive consequences is incomplete. This section helps future readers understand whether the decision's assumptions still hold.

#### Alternatives Considered

Describes other options that were evaluated and explains why they were not chosen. Each alternative should include enough detail for a reader to understand the rejected approach and the reasoning behind the rejection. When the decision is directly prescribed by the specification with no practical alternatives, this section may read "None — specification-driven requirement."

#### Compliance

Specifies how adherence to the decision is verified in practice. This includes CI checks, linting rules, architecture tests, code review expectations, and any other enforcement mechanisms. A decision without a compliance strategy is aspirational rather than architectural — this section ensures every ADR is backed by concrete verification.

#### Related ADRs

A table of cross-references to other ADRs that interact with this decision. Each entry includes a link to the related ADR, its title, and a brief description of the relationship (e.g., "Provides the persistence layer used by this system" or "Defines the validation strategy referenced in the Constraints section"). Cross-references are maintained in both directions — when a new ADR references an existing one, the existing ADR's Related ADRs table is updated as well. This is always the second-to-last section.

#### Acceptance

Records the governance process for the ADR. Contains three sub-tables — **Votes For**, **Votes Against**, and **Abstentions** — each listing the voter's identity, an optional comment, and a total count. The Acceptance section is populated during the review process: votes are cast, recorded, and once the outcome is determined the ADR's status is updated to `Accepted` (or remains `Proposed` if rejected). This is always the last section of every ADR.

## ADR Inventory

### Tier 1 — Foundational

These ADRs establish the structural and technological foundation upon which all other decisions rest.

| ADR | Title | Summary |
|-----|-------|---------|
| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | Four-layer architecture with hexagonal ports/adapters, CQRS, and event-driven patterns. |
| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Universal `[[server:]namespace/]name` naming for all entities. |
| [ADR-003](ADR-003-dependency-injection.md) | Dependency Injection | `dependency-injector` DeclarativeContainer for all service wiring. |
| [ADR-004](ADR-004-data-validation.md) | Data Validation | Pydantic V2 strict mode for all domain models and configuration objects. |
| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | Python 3.13, Typer, LangChain/LangGraph, SQLAlchemy, and supporting libraries. |

### Tier 2 — Core Domain

These ADRs define the domain model — the entities, lifecycles, and relationships that constitute the system's core logic.

| ADR | Title | Summary |
|-----|-------|---------|
| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Action, Strategize, Execute, Apply phases with states and reversion rules. |
| [ADR-007](ADR-007-decision-tree-and-correction.md) | Decision Tree and Correction | Eleven decision types, persistent decision graph, unified correction mechanism. |
| [ADR-008](ADR-008-resource-system.md) | Resource System | Typed resources with DAG relationships, registry, and sandbox strategies. |
| [ADR-009](ADR-009-project-model.md) | Project Model | Named scope linking resources, context configuration, and invariants. |
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actor-as-graph via LangGraph, hierarchical composition, role-based specialization. |
| [ADR-011](ADR-011-tool-system.md) | Tool System | Four-stage lifecycle, dual role, adapter layer, resource bindings. |
| [ADR-012](ADR-012-skill-system.md) | Skill System | Composable tool collections with hierarchical inclusion and flattening. |
| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Tool subtype with structured pass/fail, attachment scoping, and gating semantics. |
| [ADR-033](ADR-033-decision-recording-protocol.md) | Decision Recording Protocol | Tool-based `record_decision` mechanism, system vs. actor creation classification, context snapshot capture. |
| [ADR-034](ADR-034-decision-tree-versioning-and-history.md) | Decision Tree Versioning and History | Dual structure (structural tree + influence DAG), implicit versioning via `superseded_by`, historical reconstruction. |
| [ADR-035](ADR-035-decision-tree-rollback-and-replay.md) | Decision Tree Rollback and Replay | Mid-Strategize replay, Execute-phase decision-aligned checkpoints, three rollback tiers, cross-plan cascading. |

### Tier 3 — Infrastructure and Behavior

These ADRs govern cross-cutting behavioral systems and infrastructure concerns.

| ADR | Title | Summary |
|-----|-------|---------|
| [ADR-014](ADR-014-context-management-acms.md) | Context Management (ACMS) | Unified Knowledge Ontology, Context Retrieval Pipeline, 10-component assembly pipeline. |
| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | Five isolation strategies, lazy sandboxing, checkpoint/restore per tool. |
| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Four scopes with precedence, reconciliation actor, and child plan inheritance. |
| [ADR-017](ADR-017-automation-profiles.md) | Automation Profiles | Confidence thresholds controlling autonomy across eight built-in profiles. |
| [ADR-018](ADR-018-semantic-error-prevention.md) | Semantic Error Prevention | Four prevention layers from decision-time validation to predictive guards. |
| [ADR-019](ADR-019-storage-and-persistence.md) | Storage and Persistence | SQLite/SQLAlchemy with repository pattern, Unit of Work, and Alembic migrations. |
| [ADR-020](ADR-020-session-model.md) | Session Model | Conversation threads with orchestrator binding and session-scoped context. |

### Tier 4 — Integration and Operations

These ADRs address external integrations, operational interfaces, and deployment concerns.

| ADR | Title | Summary |
|-----|-------|---------|
| [ADR-021](ADR-021-cli-and-output-rendering.md) | CLI and Output Rendering | Typer-based `agents <noun> <verb>` pattern with six output formats. |
| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | Provider-agnostic LLM abstraction with StateGraph orchestration. |
| [ADR-023](ADR-023-server-mode.md) | Server Mode | Client/server deployment with shared namespaces and remote execution. |
| [ADR-024](ADR-024-configuration-system.md) | Configuration System | TOML global config with dot-path keys, YAML entity config, resolution chain. |
| [ADR-025](ADR-025-observability-and-logging.md) | Observability and Logging | structlog JSON output with context binding, optional LangSmith tracing. |
| [ADR-026](ADR-026-agent-client-protocol.md) | Agent Client Protocol (ACP) | Versioned client-server contract for sessions, plans, registries, and event streaming. |
| [ADR-027](ADR-027-language-server-protocol.md) | Language Server Protocol (LSP) Integration | Actor-attached language intelligence via LSP servers registered in the LSP Registry. |
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | SKILL.md-based progressive disclosure skills integrated as tool sources and actor graph nodes. |
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tool discovery, registry integration, skill composition, and actor-graph usage. |
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Canonical definition of a skill as a composable collection of tools from four sources (MCP, Agent Skills, built-in, custom). |
| [ADR-031](ADR-031-actor-abstraction-definition.md) | Actor Abstraction Definition | Canonical definition of an actor as anything conversational — single LLM, composed graph, or hierarchical orchestrator. |
| [ADR-032](ADR-032-jinja2-yaml-template-preprocessing.md) | Jinja2 YAML Template Preprocessing | Two-phase YAML processing: sandboxed Jinja2 template rendering followed by environment variable interpolation with type coercion. |

## Creating a New ADR

1. Assign the next sequential number (e.g., `ADR-036`).
2. Create a file named `ADR-0NN-<kebab-case-title>.md` in this directory.
3. Copy the template structure from any existing ADR.
4. Fill in the metadata table with `Status: Proposed`, the current date, author(s), and leave approver(s) blank.
5. Add the Related ADRs table with links, titles, and relationship descriptions.
6. Leave the Acceptance section with empty voting tables — votes are recorded during the review process.
7. Fill in all content sections (Context through Compliance). Every section is required — use "N/A" only if genuinely not applicable.
8. Add the new ADR to the inventory table above and to the `nav` section in `mkdocs.yml`.
9. Cross-reference related ADRs in both directions (update existing ADRs' Related ADRs tables).
10. Once voting concludes and the ADR is accepted, update `Status` to `Accepted`, record all votes, and add the approver(s).