cleveragents-core/docs/milestones

CleverAgents Milestone History & Status

Last updated: 2026-04-13
Maintained by: Documentation automation ([AUTO-DOCS-1])
Source of truth: Forgejo Milestones

This document provides a comprehensive overview of the CleverAgents project milestone history, current status, and planned roadmap. Each milestone corresponds to a tagged release in the cleveragents-core repository and represents a coherent set of capabilities delivered together.

---

Quick Reference — Version History Table

Milestone	Version	Status	Closed	Key Theme
M1: Minimal Local Source-Code Workflow	v3.0.0	✅ Completed	2026-03-16	Local-mode foundation
M2: Actor Compiler + Full LLM Integration	v3.1.0	✅ Completed	2026-03-16	LLM integration & MCP
M3: Decisions + Validations + Invariants	v3.2.0	🔄 Active	—	Plan correctness
M4: Corrections + Subplans + Checkpoints	v3.3.0	🔄 Active	—	Resilience & recovery
M5: ACMS v1 + Context Scaling	v3.4.0	🔄 Active	—	Context at scale
M6: Autonomy Hardening	v3.5.0	🔄 Active	—	Production autonomy
M7: Advanced Concepts	v3.6.0	🔄 Active	—	Extensibility
M8: TUI Implementation	v3.7.0	🔄 Active	—	Interactive interface
M9: Server Implementation	v3.8.0	🔄 Active	—	Distributed deployment

Status legend: ✅ Completed · 🔄 Active (open) · ⏳ Planned

---

Completed Milestones

M1: Minimal Local Source-Code Workflow

Field	Value
Version	v3.0.0
Status	✅ Completed
Closed	2026-03-16
Changelog	v3.0.0

Overview

M1 established the foundational local-mode workflow for CleverAgents. It delivered the minimal viable set of capabilities required for an agent to autonomously read, plan, and apply source-code changes on a developer's local machine — entirely without a remote server or cloud dependency.

Delivered Capabilities

Capability	Description
Action Registration	Declarative registration of agent actions with typed inputs/outputs
Git Checkout Resource	First-class resource type for git repository checkouts
Plan Lifecycle	Full use → execute → diff → apply plan lifecycle with state machine
Git Worktree Sandbox	Isolated git worktree for safe LLM-generated change staging
SQLite Persistence	Lightweight local persistence for plans, decisions, and state
Pydantic v2 Domain Models	Type-safe domain models with full validation throughout
Test Coverage	97%+ test coverage across unit, integration, and BDD suites

Acceptance Criteria (Met)

• agents plan use <actor> initiates a new plan session
• agents plan execute runs the LLM actor and produces file changes
• agents plan diff shows a human-readable diff of proposed changes
• agents plan apply merges changes from the worktree sandbox into the working tree
• All plan state persisted to SQLite; survives process restart
• Pydantic v2 models enforce invariants at domain boundaries
• 97%+ test coverage gate enforced in CI

Related ADRs

• ADR-001 Layered Architecture
• ADR-003 Dependency Injection
• ADR-006 Plan Lifecycle
• ADR-008 Resource System
• ADR-015 Sandbox & Checkpoint
• ADR-019 Storage & Persistence

---

M2: Actor Compiler + Full LLM Integration

Field	Value
Version	v3.1.0
Status	✅ Completed
Closed	2026-03-16
Changelog	v3.1.0

Overview

M2 elevated CleverAgents from a local scripting tool to a fully LLM-integrated agent platform. The Actor Compiler translates declarative YAML actor definitions into executable LangGraph StateGraph objects, enabling arbitrary agent topologies to be described in configuration rather than code. The MCP adapter opened the door to tool ecosystems beyond the built-in tool library.

Delivered Capabilities

Capability	Description
Actor YAML Compiler	Compiles YAML actor definitions to LangGraph StateGraph objects
MCP Adapter	Model Context Protocol client for external tool server integration
Validation Runner	Automated validation pipeline for actor graph correctness
Multi-File Generation	LLM actors can generate and modify multiple files per plan
Tool Router	Dynamic tool dispatch based on actor graph node configuration
LSP Integration	Language Server Protocol client for IDE-grade code intelligence
Agent Skills Standard	AgentSkills.io standard support for portable skill definitions

Acceptance Criteria (Met)

• YAML actor definitions compile to runnable LangGraph graphs without manual Python
• MCP server connections established and tools surfaced to LLM actors
• Validation runner catches malformed actor graphs at compile time
• Multi-file generation produces coherent, syntactically valid output
• Tool router correctly dispatches to built-in and MCP-provided tools
• LSP client provides symbol resolution and diagnostics to actor context

Related ADRs

• ADR-010 Actor & Agent Architecture
• ADR-011 Tool System
• ADR-012 Skill System
• ADR-022 LangChain/LangGraph Integration
• ADR-027 Language Server Protocol
• ADR-028 Agent Skills Standard
• ADR-029 Model Context Protocol
• ADR-030 Skill Abstraction Definition
• ADR-031 Actor Abstraction Definition
• ADR-032 Jinja2 YAML Template Preprocessing

---

Active Milestones

M3: Decisions + Validations + Invariants

Field	Value
Version	v3.2.0
Status	🔄 Active
Target	TBD
Changelog	v3.2.0

Overview

M3 introduces the correctness layer for plan execution. Decisions are first-class domain objects that record why an agent made a choice, enabling auditability and correction. Validations provide a pluggable gate system that blocks plan application when quality criteria are not met. Invariants express system-wide constraints that must hold across all plan phases.

Planned Capabilities

Capability	Description
Decision Recording	Structured recording of agent decisions with rationale and context
plan tree Command	Visual tree display of plan decisions and their relationships
plan explain Command	Human-readable explanation of why a decision was made
Invariant Management	Define, register, and enforce system-wide invariants
Plan Correction — Revert Mode	Roll back a specific decision and re-execute from that point
Plan Correction — Append Mode	Append corrective instructions to an existing plan

Key Acceptance Criteria

• Every LLM decision recorded with ULID, rationale, and context snapshot
• agents plan tree renders a navigable decision tree
• agents plan explain <decision-id> outputs human-readable rationale
• Invariants evaluated at every plan phase transition
• Invariant violations block plan progression with actionable error messages
• agents plan correct --mode revert <decision-id> replays from rollback point
• agents plan correct --mode append appends corrective context and re-executes

Related ADRs

• ADR-007 Decision Tree & Correction
• ADR-013 Validation Abstraction
• ADR-016 Invariant System
• ADR-017 Automation Profiles
• ADR-018 Semantic Error Prevention
• ADR-033 Decision Recording Protocol

---

M4: Corrections + Subplans + Checkpoints

Field	Value
Version	v3.3.0
Status	🔄 Active
Target	TBD
Changelog	v3.3.0

Overview

M4 extends the plan model with hierarchical composition (subplans), robust recovery (checkpoints and rollback), and parallel execution. Child subplans allow complex tasks to be decomposed into independently executable units. Three-way merge resolves conflicts when parallel subplans modify overlapping files.

Planned Capabilities

Capability	Description
Child Subplans	Decompose a parent plan into independently executable child plans
Parallel Execution	Execute independent subplans concurrently
Three-Way Merge	Resolve conflicts between parallel subplan outputs
Checkpoint System	Snapshot plan state at any phase for safe rollback
Rollback	Restore plan to any prior checkpoint on failure or user request

Key Acceptance Criteria

• Parent plan can spawn child subplans with scoped context
• Independent subplans execute in parallel without race conditions
• Three-way merge resolves non-conflicting parallel changes automatically
• Conflicting parallel changes surface as structured merge conflicts
• Checkpoints created automatically at each phase transition
• agents plan rollback <checkpoint-id> restores to any prior checkpoint

Related ADRs

• ADR-007 Decision Tree & Correction
• ADR-015 Sandbox & Checkpoint
• ADR-034 Decision Tree Versioning & History
• ADR-035 Decision Tree Rollback & Replay
• ADR-038 Cross-Mechanism Sandbox Coordination

---

M5: ACMS v1 + Context Scaling

Field	Value
Version	v3.4.0
Status	🔄 Active
Target	TBD
Changelog	v3.4.0

Overview

M5 delivers the Advanced Context Management System (ACMS) v1, enabling CleverAgents to operate effectively on large codebases with 10,000+ files. A three-tier storage model (hot/warm/cold) manages context budget allocation, ensuring the most relevant context is always within the LLM's token window.

Planned Capabilities

Capability	Description
ACMS v1	Advanced Context Management System with tiered context strategies
10,000+ File Indexing	Efficient indexing and retrieval across large repositories
Hot/Warm/Cold Storage Tiers	Tiered context storage with automatic promotion/demotion
Resource Type Inheritance	Hierarchical resource type system with multiple inheritance
Safety Profile Extraction	Automated extraction of safety constraints from resource definitions

Key Acceptance Criteria

• ACMS indexes repositories with 10,000+ files within acceptable startup time
• Hot tier holds actively referenced context within LLM token budget
• Warm tier caches recently accessed context for fast promotion
• Cold tier stores full index for on-demand retrieval
• Context relevance scoring drives automatic tier promotion/demotion
• Resource type inheritance resolves capabilities through type hierarchy

Related ADRs

• ADR-014 Context Management (ACMS)
• ADR-036 Resource DAG Operational Semantics
• ADR-037 Tool Reachability & Access Projection
• ADR-041 Safety Profile Extraction
• ADR-042 Resource Type Inheritance

---

M6: Autonomy Hardening

Field	Value
Version	v3.5.0
Status	🔄 Active
Target	TBD
Changelog	v3.5.0

Overview

M6 hardens CleverAgents for production autonomous operation. The A2A (Agent-to-Agent) facade enables multi-agent coordination. An event queue decouples agent communication. Guard enforcement prevents agents from violating architectural constraints. Hierarchical decomposition supports 4+ levels of nested subplans, and parallel execution scales to 10+ concurrent agents.

Planned Capabilities

Capability	Description
A2A Facade	Agent-to-Agent protocol facade for multi-agent coordination
Event Queue	Asynchronous event queue for decoupled agent communication
Guard Enforcement	Runtime enforcement of architectural and safety guards
Hierarchical Decomposition	4+ levels of nested subplan decomposition
Parallel Execution (10+)	Concurrent execution of 10+ independent agent tasks
Advisory Locking	Distributed advisory locks preventing concurrent resource conflicts
Validation Pipeline	Multi-stage validation pipeline with configurable gates
Definition-of-Done Gating	Automated DoD checks before plan application

Key Acceptance Criteria

• A2A facade routes messages between agents with delivery guarantees
• Event queue handles agent communication without blocking
• Guards block non-compliant operations at runtime with actionable errors
• Hierarchical plans decompose to 4+ levels without performance degradation
• 10+ concurrent agent tasks execute without deadlock or resource starvation
• Advisory locks prevent concurrent modification of shared resources

Related ADRs

• ADR-026 Agent-to-Agent Protocol (A2A)
• ADR-036 Resource DAG Operational Semantics
• ADR-039 Container Resource Types
• ADR-040 LSP Resource Types

---

M7: Advanced Concepts

Field	Value
Version	v3.6.0
Status	🔄 Active
Target	TBD
Changelog	v3.6.0

Overview

M7 introduces advanced extensibility features: sophisticated context strategies powered by the Universal Knowledge Ontology (UKO), additional LLM backends beyond the initial provider set, container-based tool execution for sandboxed operations, and a plugin architecture enabling third-party extensions.

Planned Capabilities

Capability	Description
Advanced Context Strategies	UKO-powered context strategies with semantic reasoning
UKO Runtime	Universal Knowledge Ontology with graph persistence and inference
Additional LLM Backends	Extended provider support beyond the initial eight
Container Tool Execution	Run tools inside isolated containers for security and reproducibility
Plugin Architecture	Third-party extension points for tools, actors, and resources

Key Acceptance Criteria

• UKO runtime indexes project ontology and answers semantic queries
• Context strategies leverage UKO inference for relevance scoring
• At least two additional LLM backends integrated and tested
• Container tool execution runs tools in Docker/Podman with resource limits
• Plugin API documented and at least one reference plugin implemented

Related ADRs

• ADR-014 Context Management (ACMS)
• ADR-039 Container Resource Types
• ADR-043 Devcontainer Integration

---

M8: TUI Implementation

Field	Value
Version	v3.7.0
Status	🔄 Active
Target	TBD
Changelog	v3.7.0

Overview

M8 delivers a full-featured terminal user interface (TUI) built on the Textual framework. The TUI provides an interactive, keyboard-driven interface for all CleverAgents operations, with a persona system for customized agent identities, reference/command input for structured context injection, and session persistence for long-running work.

Planned Capabilities

Capability	Description
Textual-Based TUI	Full-screen terminal UI with multi-session tabs and rich rendering
Persona System	YAML-backed personas binding actors, presets, and scope references
Reference Input (@)	File/resource reference picker for structured context injection
Command Input (/)	Slash command system with 67+ commands across 14 groups
Shell Mode (!)	Inline shell execution with danger detection and user confirmation
Session Persistence	Full JSON export/import and Markdown transcript export
Actor Thought Blocks	Expandable reasoning trace widgets rendered inline
Permission Questions	Inline permission request widgets with single-key shortcuts

Key Acceptance Criteria

• agents tui launches a full-screen Textual application
• Multi-session tabs allow parallel plan sessions in a single terminal
• Persona system loads from ~/.config/cleveragents/personas/
• @ reference picker inserts file/resource references into input
• / command overlay provides searchable access to all 67+ commands
• ! shell mode detects dangerous patterns before execution
• Sessions export to JSON and Markdown formats
• Actor thought blocks render inline and collapse by default

Related ADRs

• ADR-044 TUI Architecture and Framework
• ADR-045 TUI Persona System
• ADR-046 TUI Reference and Command System

---

M9: Server Implementation

Field	Value
Version	v3.8.0
Status	🔄 Active
Target	TBD
Changelog	v3.8.0

Overview

M9 transforms CleverAgents from a local CLI tool into a distributed server platform. A JSON-RPC 2.0 A2A wire format enables standardized agent-to-agent communication over HTTP. A FastAPI server exposes the full CleverAgents API, backed by PostgreSQL for production-grade persistence. Kubernetes deployment manifests and a Helm chart enable cloud-native operation.

Planned Capabilities

Capability	Description
A2A JSON-RPC 2.0	Standard JSON-RPC 2.0 wire format for agent-to-agent communication
HTTP Transport	HTTP/HTTPS transport layer for remote agent connections
FastAPI Server	Production-grade FastAPI application exposing the CleverAgents API
PostgreSQL Backend	PostgreSQL persistence replacing SQLite for multi-user deployments
Kubernetes Deployment	Helm chart and manifests for Kubernetes production deployment
agents server connect	CLI command to configure and connect to a remote server
Database Resource Handler	Full CRUD and checkpoint/rollback for SQL database resources

Key Acceptance Criteria

• agents server connect <url> configures remote server connection
• JSON-RPC 2.0 messages route correctly between client and server
• FastAPI server handles concurrent requests without data races
• PostgreSQL backend supports all plan lifecycle operations
• Kubernetes Helm chart deploys successfully to a standard cluster
• Database resource handler supports SQLite, PostgreSQL, MySQL, and DuckDB

Related ADRs

• ADR-023 Server Mode
• ADR-026 Agent-to-Agent Protocol (A2A)
• ADR-047 A2A Standard Adoption
• ADR-048 Server Application Architecture

---

Milestone Progression Overview

The CleverAgents v3.x series follows a deliberate capability-layering strategy:

M1 (Foundation)
  └─ M2 (LLM Integration)
       └─ M3 (Correctness)
            └─ M4 (Resilience)
                 └─ M5 (Scale)
                      └─ M6 (Autonomy)
                           ├─ M7 (Extensibility)
                           ├─ M8 (Interactive UX)
                           └─ M9 (Distribution)

Each milestone builds on the guarantees established by its predecessors:

• M1–M2 establish the core execution model (plan lifecycle + LLM actors)
• M3–M4 add correctness and resilience (decisions, validations, checkpoints)
• M5–M6 scale the system (context management, autonomy hardening)
• M7–M9 extend the platform (advanced concepts, TUI, server mode)

---

Contributing to Milestone Tracking

Milestone status is tracked in the Forgejo Milestones page. To associate an issue or PR with a milestone:

1. Open the issue or PR in Forgejo
2. In the sidebar, select the appropriate milestone from the Milestone dropdown
3. Issues are automatically counted toward milestone completion percentage

For questions about milestone scope or acceptance criteria, open an issue with the Type/Question label and reference the milestone.

---

Related Documentation

• Architecture Overview — System architecture and layered design
• Architecture Decision Records — All ADRs indexed by tier
• Implementation Timeline — Detailed implementation timeline
• CHANGELOG — Full version-by-version change history
• Development: Automation Tracking — Automation agent tracking system
• Development: CI/CD Pipeline — Continuous integration and delivery

---

This document is automatically maintained by the CleverAgents documentation automation system.

---

Automated by CleverAgents Bot Supervisor: Documentation | Agent: documentation-pool-supervisor Worker: [AUTO-DOCS-1]