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

Section	Purpose
Context	The problem or situation that motivated this decision. Why it exists.
Decision	The architectural choice that was made, stated declaratively.
Design	Structural details — components, interfaces, patterns, data models, protocols.
Constraints	Explicit rules and restrictions imposed on the codebase. Enforceable invariants.
Consequences	Positive outcomes, negative trade-offs, and risks introduced by the decision.
Alternatives Considered	Other options evaluated and why they were not chosen. May be "None — specification-driven requirement."
Compliance	How adherence to this decision is verified (CI checks, linting, code review, test patterns).

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. This is always the second-to-last section.

Acceptance

Records the governance process for the ADR. This is always the last section.

Section	Purpose
Votes For	Table of voters who voted in favor, with optional comments and a total count.
Votes Against	Table of voters who voted against, with optional comments and a total count.
Abstentions	Table of voters who abstained, with optional comments and a total count.

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.

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.
ADR-018	Semantic Error Prevention	Four prevention layers from decision-time validation to predictive guards.
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.

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.

Creating a New ADR

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