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, 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	Layered Architecture	Four-layer architecture with hexagonal ports/adapters, CQRS, and event-driven patterns.
ADR-002	Namespace System	Universal [[server:]namespace/]name naming for all entities.
ADR-003	Dependency Injection	dependency-injector DeclarativeContainer for all service wiring.
ADR-004	Data Validation	Pydantic V2 strict mode for all domain models and configuration objects.
ADR-005	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	Plan Lifecycle	Action, Strategize, Execute, Apply phases with states and reversion rules.
ADR-007	Decision Tree and Correction	Eleven decision types, persistent decision graph, unified correction mechanism.
ADR-008	Resource System	Typed resources with DAG relationships, registry, and sandbox strategies.
ADR-009	Project Model	Named scope linking resources, context configuration, and invariants.
ADR-010	Actor and Agent Architecture	Actor-as-graph via LangGraph, hierarchical composition, role-based specialization.
ADR-011	Tool System	Four-stage lifecycle, dual role, adapter layer, resource bindings.
ADR-012	Skill System	Composable tool collections with hierarchical inclusion and flattening.
ADR-013	Validation Abstraction	Tool subtype with structured pass/fail, attachment scoping, and gating semantics.
ADR-033	Decision Recording Protocol	Tool-based record_decision mechanism, system vs. actor creation classification, context snapshot capture.
ADR-034	Decision Tree Versioning and History	Dual structure (structural tree + influence DAG), implicit versioning via superseded_by, historical reconstruction.
ADR-035	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	Context Management (ACMS)	Unified Knowledge Ontology, Context Retrieval Pipeline, 10-component assembly pipeline.
ADR-015	Sandbox and Checkpoint	Five isolation strategies, lazy sandboxing, checkpoint/restore per tool.
ADR-016	Invariant System	Four scopes with precedence, reconciliation actor, and child plan inheritance.
ADR-017	Automation Profiles	Confidence thresholds controlling autonomy across eight built-in profiles. Composes a SafetyProfile sub-model (ADR-041).
ADR-018	Semantic Error Prevention	Four prevention layers from decision-time validation to predictive guards.
ADR-041	Safety Profile Extraction	Safety constraints extracted into a composed SafetyProfile sub-model within AutomationProfile.
ADR-019	Storage and Persistence	SQLite/SQLAlchemy with repository pattern, Unit of Work, and Alembic migrations.
ADR-020	Session Model	Conversation threads with orchestrator binding and session-scoped context.
ADR-036	Resource DAG Operational Semantics	Ten operational purposes of the resource DAG with sandbox boundary algebra, checkpoint boundaries, and dependency ordering.
ADR-037	Tool Reachability and Access Projection	Forward, inverse, and cross-equivalence reachability with AccessProjection protocol and read/write routing.
ADR-038	Cross-Mechanism Sandbox Coordination	Coherence properties, write-then-sync protocol, conflict resolution, and lazy virtual node materialization.
ADR-042	Resource Type Inheritance	Single-inheritance inherits field on resource type definitions with polymorphic tool binding, auto-discovery, and DAG queries.

Tier 4 — Integration and Operations

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

ADR	Title	Summary
ADR-021	CLI and Output Rendering	Typer-based agents <noun> <verb> pattern with six output formats.
ADR-022	LangChain/LangGraph Integration	Provider-agnostic LLM abstraction with StateGraph orchestration.
ADR-023	Server Mode	Client/server deployment with shared namespaces and remote execution.
ADR-024	Configuration System	TOML global config with dot-path keys, YAML entity config, resolution chain.
ADR-025	Observability and Logging	structlog JSON output with context binding, optional LangSmith tracing.
ADR-026	Agent Client Protocol (ACP)	Versioned client-server contract for sessions, plans, registries, and event streaming.
ADR-027	Language Server Protocol (LSP) Integration	Actor-attached language intelligence via LSP servers registered in the LSP Registry.
ADR-028	Agent Skills Standard (AgentSkills.io)	SKILL.md-based progressive disclosure skills integrated as tool sources and actor graph nodes.
ADR-029	Model Context Protocol (MCP) Adoption	MCP tool discovery, registry integration, skill composition, and actor-graph usage.
ADR-030	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	Actor Abstraction Definition	Canonical definition of an actor as anything conversational — single LLM, composed graph, or hierarchical orchestrator.
ADR-032	Jinja2 YAML Template Preprocessing	Two-phase YAML processing: sandboxed Jinja2 template rendering followed by environment variable interpolation with type coercion.
ADR-039	Container and Execution Environment Resource Types	Seven engine-agnostic container resource types plus executable discovery for tool/LSP dependency resolution.
ADR-040	LSP Resource Types	Three LSP resource types (lsp-server, lsp-workspace, lsp-document) for language intelligence integration.
ADR-043	Devcontainer Integration and Container-Project Association	Auto-detected devcontainer-instance subtype, container-project association patterns, and execution environment routing with precedence.

Creating a New ADR

1. Assign the next sequential number (e.g., ADR-044).
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).