From db20bb8b17d3482cce203ef735731d9b8ae6e2e8 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Mon, 13 Apr 2026 04:15:37 +0000 Subject: [PATCH] docs: add release notes for v3.0.0 and v3.1.0 milestones [AUTO-DOCS-1] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created comprehensive formal release notes for the v3.0.0 (Minimal Local Source-Code Workflow) and v3.1.0 (Actor Compiler + Full LLM Integration) milestones, along with a release notes index. New files: - docs/release-notes/index.md: Index of all release notes with release series overview and guidance on how to read release notes - docs/release-notes/v3.0.0.md: Full release notes for v3.0.0 covering plan lifecycle (Action→Strategize→Execute→Apply), git worktree sandbox, SQLite persistence, actor-based LLM path, ChangeSet tracking, Pydantic v2 domain models, CLI commands, and ADR references - docs/release-notes/v3.1.0.md: Full release notes for v3.1.0 covering Actor YAML→LangGraph compilation, MCP adapter, validation runner, multi-file generation, skill registry, Agent Skills standard, LSP integration, breaking changes, and migration guide Updated CHANGELOG.md: - Expanded [3.0.0] section with detailed bullet points for each major feature, ADR references, and a link to the full release notes - Expanded [3.1.0] section with detailed bullet points for each major feature, ADR references, breaking changes, and a link to the full release notes --- CHANGELOG.md | 136 +++++++++++++--- docs/release-notes/index.md | 63 ++++++++ docs/release-notes/v3.0.0.md | 233 +++++++++++++++++++++++++++ docs/release-notes/v3.1.0.md | 304 +++++++++++++++++++++++++++++++++++ 4 files changed, 717 insertions(+), 19 deletions(-) create mode 100644 docs/release-notes/index.md create mode 100644 docs/release-notes/v3.0.0.md create mode 100644 docs/release-notes/v3.1.0.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 89d67e2c3..4ef60e1b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -322,31 +322,129 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [3.1.0] — 2025-12-20 +**Milestone:** Actor Compiler + Full LLM Integration + ### Added -- MCP (Model Context Protocol) adapter and client (ADR-029). -- LSP (Language Server Protocol) client integration (ADR-027). -- Agent Skills Standard (AgentSkills.io) support (ADR-028). -- Skill abstraction definition (ADR-030). +- **Actor YAML → LangGraph Compilation** (ADR-031, ADR-032): Actors are now fully declarative. + A YAML configuration file describing an actor's graph topology — nodes, edges, conditional + routing, skill references, and LSP bindings — is compiled by the Actor Compiler into a + LangGraph `StateGraph` at registration time. The compiler validates graph topology (circular + reference detection, node type validation, skill reference checks) before accepting + registration. +- **Jinja2 YAML Template Preprocessing** (ADR-032): Actor YAML files are preprocessed with + Jinja2 before parsing, enabling environment variable interpolation (`{{ env.MY_KEY }}`), + conditional blocks, and template inheritance for shared actor configurations. +- **MCP (Model Context Protocol) Adapter** (ADR-029): `MCPToolAdapter` integrates external MCP + servers as first-class tool sources. Supports `stdio`, `sse`, and `streamable-http` + transports. Capability inference from tool names (overridable in YAML). Transparent sandbox + path rewriting for filesystem-based tools. Dynamic tool refresh via + `notifications/tools/list_changed` events. MCP tools participate in the full four-stage tool + lifecycle. +- **Validation Runner** (ADR-013): Validations are attached to resources and run automatically + during the Execute phase. `ApplyValidationSummary` aggregates results and blocks Apply if any + required validation fails or if no validations were run (empty-run guard). Supported types: + shell command, Python callable, BDD scenario, and custom plugins. +- **Multi-File Generation**: The LLM execution actor can create, modify, and delete multiple + files in a single plan execution via `FILE:` blocks and structured diff output. All operations + are written to the git worktree sandbox during Execute and merged during Apply. +- **Skill Registry** (ADR-012, ADR-028, ADR-030): Central catalog of all skills. Unifies four + tool sources — built-in tools, MCP tools, Agent Skills (AgentSkills.io), and custom tools — + under a single skill abstraction. Flattens all sources into a unified tool surface per actor, + resolving name collisions at registration time. +- **Agent Skills Standard** (ADR-028): Adopts the [AgentSkills.io](https://AgentSkills.io) + standard for packaging instruction-driven workflows as `SKILL.md` files with optional + `scripts/`, `references/`, and `assets/` directories. Three-tier progressive disclosure: + metadata (~50–100 tokens) at registration, full instructions on activation, resources on + demand. +- **LSP (Language Server Protocol) Client Integration** (ADR-027): Actors declare LSP server + bindings in their `lsp:` YAML section. Language intelligence (diagnostics, type information, + completions, symbol references, definition lookups) is exposed as tools via `LSPToolAdapter` + and as ACMS context enrichment. +- **Actor Abstraction Definition** (ADR-031): Formal definition of the actor abstraction. + Actors are YAML-configured conversational units implemented as LangGraph `StateGraph` + instances. The actor/agent distinction is precise: actors are the superset (anything + conversational); agents are a specialized subset (LLM-backed with tool-calling and memory). +- **Skill Abstraction Definition** (ADR-030): Formal definition of the skill abstraction + unifying all four tool sources. Actors acquire capabilities exclusively through skills. +- **Decision Recording Protocol** (ADR-033): Structured protocol for recording decisions at + each phase transition: decision ID (ULID), type, rationale, constraints, and parent + references. +- New CLI commands: `agents tool add/remove/list/show`, `agents validation attach/detach/list/run`, + `agents skill show/remove`. + +### Changed + +- Skill YAML format now requires explicit `source` tags for non-built-in tools; MCP servers + must be declared in the `mcp_servers` section. +- Actor YAML files must include an explicit `nodes` section; implicit single-LLM defaults are + no longer supported. + +### See Also + +- [v3.1.0 Release Notes](docs/release-notes/v3.1.0.md) --- ## [3.0.0] — 2025-12-06 +**Milestone:** Minimal Local Source-Code Workflow (Initial Public Release) + ### Added -- Initial public release of CleverAgents Core. -- Unified `agents` / `cleveragents` CLI entry points. -- Layered architecture: Entry Points → Application → Domain → Infrastructure → Integration → Core. -- Actor system with YAML-defined LangGraph node graphs. -- Tool system with four-stage lifecycle (activate → validate → execute → deactivate). -- Skill system with three-tier progressive disclosure. -- Resource system with DAG and type hierarchy. -- A2A (Agent-to-Agent) protocol facade. -- DI container (`cleveragents.application.container`). -- LangChain/LangGraph integration (ADR-022). -- Provider registry with fallback chain (OpenAI → Anthropic → Google → Azure → OpenRouter → Groq → Together → Cohere). -- Observability: structured logging, metrics, audit trail, token/cost tracking. -- BDD test suite (Behave + Robot Framework). -- Nox automation for lint, typecheck, tests, docs, benchmarks. -- MkDocs-powered documentation with CleverAgents branding. +- **Plan Lifecycle: Action → Strategize → Execute → Apply** (ADR-006): Four-phase structured + workflow for AI-assisted source-code editing. Action defines work templates; Strategize + gathers context and produces a decision tree (read-only); Execute runs in a sandboxed + environment with checkpoints; Apply merges the changeset into real project resources. + Supports phase reversion (Execute → Strategize, Apply → Strategize), hierarchical child + plans, and automation profile-controlled human review gates at every transition. +- **Git Worktree Sandbox**: Changes are isolated in a dedicated git branch and worktree + (`cleveragents/plan-`) during Execute. On Apply, changes are merged via `git merge`. + On rollback, the worktree is discarded entirely. Non-git projects fall back to flat file copy. + Displays spec-aligned Apply Summary (plan ID, artifacts, insertions/deletions, project, + timestamp) and Sandbox Cleanup panel. +- **SQLite Persistence** (ADR-019): All domain entities persisted in a local SQLite database. + Zero-configuration for local mode. WAL mode for concurrent reads. Alembic migrations for + version-controlled schema evolution. ULID identifiers (lexicographically sortable, + time-ordered, globally unique). Repository pattern with Unit of Work for transactional + consistency. Domain code fully decoupled from SQLAlchemy via protocol interfaces. +- **Actor-Based LLM Execution Path** (ADR-010, ADR-022, ADR-031): Actors are YAML-configured + conversational units implemented as LangGraph `StateGraph` instances. Hierarchical + composition (actor graphs referencing other actors by name). Role specialization: strategy, + execution, estimation, and invariant actor roles. Provider registry with fallback chain: + OpenAI → Anthropic → Google → Azure → OpenRouter → Groq → Together → Cohere. +- **ChangeSet from Tool Invocations**: Every tool invocation that modifies a resource during + Execute is tracked in the plan's ChangeSet (files added/modified/deleted, insertion/deletion + counts, per-file diff references, checkpoint associations). The ChangeSet is the input to + Apply and the basis for the Apply Summary. +- **Pydantic v2 Domain Models** (ADR-004): All domain entities (Plan, Decision, Action, + Resource, Actor, Tool, Skill, Session, Invariant, AutomationProfile, Checkpoint, + CorrectionAttempt) are Pydantic v2 `BaseModel` subclasses. Runtime type validation at every + layer boundary. JSON Schema generation for tool-calling protocols. Pydantic Settings for + environment variable loading and configuration validation. +- **Unified `agents` / `cleveragents` CLI entry points** (ADR-021). +- **Layered architecture** (ADR-001): Entry Points → Application → Domain → Infrastructure → + Integration → Core. Domain code never imports from Infrastructure. +- **Tool system** (ADR-011): Four-stage lifecycle (activate → validate → execute → deactivate). + Tool Registry with capability metadata (read-only vs. write) for safety enforcement. +- **Skill system** (ADR-012): Three-tier progressive disclosure. Metadata at registration; + full instructions on activation; resources on demand. +- **Resource system** (ADR-008): Project assets managed through a DAG with dependency tracking. + Supports git-checkout, file, database, and custom resource types. +- **A2A (Agent-to-Agent) protocol facade** (ADR-026). +- **DI container** (`cleveragents.application.container`) (ADR-003). +- **LangChain/LangGraph integration** (ADR-022): LangChain for provider-agnostic LLM + abstraction; LangGraph for stateful workflow orchestration with checkpointing and streaming. +- **Observability** (ADR-025): Structured logging, metrics, audit trail, token/cost tracking. +- **Plan resume** (`agents plan resume`): Resume interrupted plans from their last checkpoint. +- **BDD test suite**: Behave (Gherkin feature files) + Robot Framework for integration and + end-to-end tests. +- **Nox automation**: lint, typecheck, tests, docs, benchmarks. +- **MkDocs-powered documentation** with CleverAgents branding and auto-generated API reference. +- New CLI commands: `agents plan create/use/execute/apply/resume/list/show/tree/correct/cancel`, + `agents actor add/list/show`, `agents resource add/list/stop`, `agents skill add/list`, + `agents init`, `agents project list`. + +### See Also + +- [v3.0.0 Release Notes](docs/release-notes/v3.0.0.md) diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md new file mode 100644 index 000000000..f7781f8d5 --- /dev/null +++ b/docs/release-notes/index.md @@ -0,0 +1,63 @@ +# Release Notes + +This directory contains formal release notes for each CleverAgents Core milestone. +Release notes provide a comprehensive, user-facing record of what was delivered in each +version — including key features, CLI commands, breaking changes, and migration guidance. + +For a condensed changelog following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) +format, see the [CHANGELOG](../../CHANGELOG.md) at the repository root. + +--- + +## Releases + +| Version | Date | Milestone | Notes | +|---------|------|-----------|-------| +| [v3.1.0](./v3.1.0.md) | 2025-12-20 | Actor Compiler + Full LLM Integration | Actor YAML→LangGraph compilation, MCP adapter, validation runner, multi-file generation, skill registry | +| [v3.0.0](./v3.0.0.md) | 2025-12-06 | Minimal Local Source-Code Workflow | Initial public release — plan lifecycle, git worktree sandbox, SQLite persistence, actor-based LLM path, Pydantic v2 domain models | + +--- + +## Release Series + +### v3.x — Core Platform + +The v3.x series establishes the CleverAgents Core platform: the plan lifecycle, actor system, +tool and skill infrastructure, persistence layer, and LLM integration. Each minor release +adds a significant capability layer while maintaining backward compatibility within the series. + +| Version | Focus | +|---------|-------| +| v3.0.0 | Minimal Local Source-Code Workflow — foundational plan lifecycle and execution engine | +| v3.1.0 | Actor Compiler + Full LLM Integration — declarative actors, MCP, skills | +| v3.2.0 | Decisions, Validations, and Invariants | +| v3.3.0 | Corrections, Subplans, Checkpoint/Rollback | +| v3.4.0 | ACMS v1, Resource Type Inheritance, Safety Profiles | +| v3.5.0 | Autonomy Hardening, Resource DAG, Container/LSP Resources | +| v3.6.0 | Advanced Context Management System (ACMS), UKO Runtime | +| v3.7.0 | Interactive TUI | +| v3.8.0 | Invariant Reconciliation, TUI Shell Safety, UKO Provenance, JSON-RPC 2.0 A2A | + +--- + +## How to Read Release Notes + +Each release note document follows a consistent structure: + +1. **Overview** — The milestone goal and what was delivered +2. **Key Features Delivered** — Detailed description of each major feature +3. **CLI Commands Introduced** — New commands available after upgrading +4. **Technical Highlights** — Architecture decisions and implementation details +5. **Breaking Changes** — Any changes that require updates to existing configurations or code +6. **Migration Guide** — Step-by-step instructions for upgrading from the previous version +7. **Architecture Decision Records** — ADRs accepted as part of this milestone + +--- + +## Related Resources + +- [CHANGELOG](../../CHANGELOG.md) — Condensed changelog (Keep a Changelog format) +- [Architecture Overview](../architecture.md) +- [ADR Index](../adr/index.md) +- [API Reference](../api/index.md) +- [Timeline](../timeline.md) diff --git a/docs/release-notes/v3.0.0.md b/docs/release-notes/v3.0.0.md new file mode 100644 index 000000000..d20853147 --- /dev/null +++ b/docs/release-notes/v3.0.0.md @@ -0,0 +1,233 @@ +# Release Notes — v3.0.0 + +**Release Date:** 2025-12-06 +**Milestone:** Minimal Local Source-Code Workflow +**Type:** Major Release (Initial Public Release) + +--- + +## Overview + +v3.0.0 is the initial public release of **CleverAgents Core** — the foundational milestone that +establishes the complete end-to-end workflow for AI-assisted local source-code editing. This +release delivers a production-ready, four-phase plan lifecycle, a git-worktree-based sandbox, +SQLite-backed persistence, an actor-driven LLM execution path, and a full suite of Pydantic v2 +domain models. + +The goal of this milestone was to prove the core loop: a user describes work → the system +strategizes, executes in isolation, and applies changes to the real project — with full +traceability, rollback capability, and human review gates at every transition. + +--- + +## Key Features Delivered + +### Plan Lifecycle: Action → Strategize → Execute → Apply + +Every unit of work in CleverAgents follows a structured four-phase lifecycle (ADR-006): + +| Phase | Description | +|-------|-------------| +| **Action** | A reusable plan template defining work, actors, and invariants — not yet bound to a project | +| **Strategize** | Read-only context gathering; produces a decision tree of approach choices and resource selections | +| **Execute** | Sandboxed execution; actors invoke tools, write changes, and create checkpoints | +| **Apply** | Controlled commit; merges the sandboxed changeset into real project resources | + +Phase transitions are gated by automation profiles, enabling fully autonomous or human-reviewed +workflows. Phase reversion (Execute → Strategize, Apply → Strategize) provides structured +recovery without plan abandonment. + +### Git Worktree Sandbox + +Changes are isolated in a dedicated git branch and worktree (`cleveragents/plan-`) +during execution. On apply, changes are merged back via `git merge`. On rollback, the worktree +is discarded entirely. Non-git projects fall back to a flat file copy strategy. + +See [Git Worktree Sandbox module documentation](../modules/git-worktree-sandbox.md) for full +API reference. + +### SQLite Persistence + +All domain entities — plans, decisions, resources, actors, sessions, checkpoints, and more — +are persisted in a local SQLite database (ADR-019). Key design choices: + +- **Zero-configuration**: no external database server required for local mode +- **WAL mode**: concurrent reads during parallel plan execution +- **Alembic migrations**: version-controlled, reversible schema evolution +- **ULID identifiers**: lexicographically sortable, time-ordered, globally unique entity IDs +- **Repository pattern**: domain code is fully decoupled from SQLAlchemy via protocol interfaces + +### Actor-Based LLM Execution Path + +Actors are YAML-configured conversational units implemented as LangGraph `StateGraph` instances +(ADR-031, ADR-022). Every custom actor is technically a graph — from a single LLM node to a +complex multi-stage orchestrator. Key capabilities: + +- **Hierarchical composition**: actor graphs can reference other actors by name, enabling + "orchestrator of orchestrators" patterns with no depth limit +- **Role specialization**: strategy, execution, estimation, and invariant actor roles +- **Skill-based capability acquisition**: actors gain tool access exclusively through the skill + system — no direct tool references outside skills +- **Provider registry with fallback chain**: OpenAI → Anthropic → Google → Azure → OpenRouter → + Groq → Together → Cohere + +### ChangeSet from Tool Invocations + +During the Execute phase, every tool invocation that modifies a resource is tracked in the +plan's ChangeSet. The ChangeSet records: + +- Files added, modified, and deleted +- Insertion and deletion line counts +- Per-file diff references +- Checkpoint associations for fine-grained rollback + +The ChangeSet is the input to the Apply phase and the basis for the Apply Summary displayed +to the user. + +### Pydantic v2 Domain Models + +All domain entities (Plan, Decision, Action, Resource, Actor, Tool, Skill, Session, Invariant, +AutomationProfile, Checkpoint, CorrectionAttempt) are Pydantic v2 `BaseModel` subclasses +(ADR-004). This provides: + +- Runtime type validation at every layer boundary +- JSON Schema generation for tool-calling protocols +- Structured, actionable validation error messages for CLI display +- Pydantic Settings for environment variable loading and configuration validation + +--- + +## CLI Commands Introduced + +| Command | Description | +|---------|-------------| +| `agents` / `cleveragents` | Unified CLI entry points | +| `agents plan create` | Create a new plan from an action template | +| `agents plan use ` | Bind an action to a project and enter Strategize | +| `agents plan execute ` | Transition a plan from Strategize to Execute | +| `agents plan apply ` | Apply sandboxed changes to the real project | +| `agents plan resume ` | Resume an interrupted plan from its last checkpoint | +| `agents plan list` | List all plans with status | +| `agents plan show ` | Show plan details and decision tree | +| `agents plan tree ` | Display the decision tree for a plan | +| `agents plan correct ` | Correct a decision and revert to Strategize | +| `agents plan cancel ` | Cancel a plan | +| `agents actor add` | Register a new actor from a YAML definition | +| `agents actor list` | List registered actors | +| `agents actor show ` | Show actor details | +| `agents resource add` | Register a project resource | +| `agents resource list` | List registered resources | +| `agents resource stop` | Stop a running resource instance | +| `agents skill add` | Register a skill | +| `agents skill list` | List registered skills | +| `agents init` | Initialize a new CleverAgents project | +| `agents project list` | List configured projects | + +--- + +## Technical Highlights + +### Layered Architecture (ADR-001) + +Six-layer clean architecture enforced at import boundaries: + +``` +Entry Points → Application → Domain → Infrastructure → Integration → Core +``` + +Domain code never imports from Infrastructure. All persistence and LLM calls go through +protocol interfaces injected by the DI container (ADR-003). + +### Tool System (ADR-011) + +Four-stage tool lifecycle: **activate → validate → execute → deactivate**. Tools are +registered in the Tool Registry with capability metadata (read-only vs. write) for safety +enforcement. Tool input/output schemas are Pydantic models that generate JSON Schema for +LLM tool-calling. + +### Skill System (ADR-012) + +Three-tier progressive disclosure: metadata (~50–100 tokens) loads at registration; full +instructions load only when the skill is activated; resources (scripts, references, assets) +load on demand. This keeps startup token cost minimal even with dozens of skills registered. + +### Resource System (ADR-008) + +Resources are project assets managed through a DAG with dependency tracking. The resource +system supports git-checkout, file, database, and custom resource types. Resources are +bound to plans and sandboxed per the lifecycle phases. + +### Observability (ADR-025) + +Structured logging, metrics, audit trail, and token/cost tracking are wired throughout the +execution path. Every tool invocation, phase transition, and decision is recorded. + +### BDD Test Suite + +Behavior-Driven Development with Behave (Gherkin feature files) and Robot Framework for +integration and end-to-end tests. Nox automation for lint, typecheck, tests, docs, and +benchmarks. + +### MkDocs Documentation + +MkDocs-powered documentation with CleverAgents branding, auto-generated API reference pages, +and ADR index. + +--- + +## Breaking Changes + +This is the initial public release. There are no breaking changes from a prior stable version. + +--- + +## Migration Guide + +No migration required. This is the first stable release. + +To get started: + +```bash +pip install cleveragents-core +agents init +agents actor add path/to/my-actor.yaml +agents plan create --action local/my-action --project my-project +``` + +--- + +## Architecture Decision Records + +The following ADRs were accepted as part of this milestone: + +| ADR | Title | +|-----|-------| +| ADR-001 | Layered Architecture | +| ADR-002 | Namespace System | +| ADR-003 | Dependency Injection | +| ADR-004 | Data Validation (Pydantic v2) | +| ADR-005 | Technical Stack | +| ADR-006 | Plan Lifecycle | +| ADR-007 | Decision Tree and Correction | +| ADR-008 | Resource System | +| ADR-009 | Project Model | +| ADR-010 | Actor and Agent Architecture | +| ADR-011 | Tool System | +| ADR-012 | Skill System | +| ADR-015 | Sandbox and Checkpoint | +| ADR-019 | Storage and Persistence | +| ADR-021 | CLI and Output Rendering | +| ADR-022 | LangChain/LangGraph Integration | +| ADR-024 | Configuration System | +| ADR-025 | Observability and Logging | + +--- + +## Related Documentation + +- [Architecture Overview](../architecture.md) +- [Plan Lifecycle (ADR-006)](../adr/ADR-006-plan-lifecycle.md) +- [Actor Abstraction (ADR-031)](../adr/ADR-031-actor-abstraction-definition.md) +- [Storage and Persistence (ADR-019)](../adr/ADR-019-storage-and-persistence.md) +- [Git Worktree Sandbox](../modules/git-worktree-sandbox.md) +- [v3.1.0 Release Notes](./v3.1.0.md) diff --git a/docs/release-notes/v3.1.0.md b/docs/release-notes/v3.1.0.md new file mode 100644 index 000000000..3a93d41c8 --- /dev/null +++ b/docs/release-notes/v3.1.0.md @@ -0,0 +1,304 @@ +# Release Notes — v3.1.0 + +**Release Date:** 2025-12-20 +**Milestone:** Actor Compiler + Full LLM Integration +**Type:** Minor Release + +--- + +## Overview + +v3.1.0 delivers the **Actor Compiler** and **Full LLM Integration** milestone, building directly +on the foundational plan lifecycle and persistence layer introduced in v3.0.0. This release +makes actors fully declarative: a YAML file describing a LangGraph node graph is compiled at +registration time into a runnable `StateGraph` instance. It also integrates the Model Context +Protocol (MCP) adapter, a validation runner, multi-file generation support, and the skill +registry — completing the core capability acquisition pipeline. + +--- + +## Key Features Delivered + +### Actor YAML → LangGraph Compilation + +Actors are now fully declarative. A YAML configuration file describing an actor's graph +topology — nodes, edges, conditional routing, skill references, and LSP bindings — is compiled +by the Actor Compiler into a LangGraph `StateGraph` at registration time (ADR-031, ADR-032). + +**What this means in practice:** + +- No Python code is required to define a new actor +- Actors are registered via `agents actor add path/to/actor.yaml` +- The compiler validates the graph topology (detects circular references, validates node types, + checks skill references) before accepting the registration +- Jinja2 template preprocessing (ADR-032) allows environment variable interpolation and + conditional blocks in actor YAML files + +**Example actor YAML:** + +```yaml +name: local/code-reviewer +description: Reviews code changes for correctness, style, and security issues +skills: + - local/code-analysis + - local/git-tools +nodes: + - id: reviewer + type: agent + model: openai/gpt-4o + system_prompt: | + You are a senior software engineer reviewing code changes. + Use your tools to analyze the diff and provide structured feedback. + - id: format_output + type: tool + tool: local/format-review-output +edges: + - from: reviewer + to: format_output + - from: format_output + to: END +``` + +### MCP Adapter + +The Model Context Protocol (MCP) adapter (`MCPToolAdapter`) integrates external MCP servers +as first-class tool sources (ADR-029). MCP tools are registered in the Tool Registry with +extended capability metadata and are available to any actor assigned a skill that includes them. + +**Key capabilities:** + +- **Transport support**: `stdio`, `sse`, and `streamable-http` transports +- **Capability inference**: tool names are analyzed to infer read-only vs. write capability + (overridable in YAML) +- **Sandbox path rewriting**: file paths in MCP tool arguments are transparently rewritten to + sandbox paths; results are rewritten back to logical paths +- **Dynamic tool refresh**: the adapter subscribes to `notifications/tools/list_changed` events + and updates the Tool Registry without restarting +- **Four-stage lifecycle**: MCP tools participate in the same activate → validate → execute → + deactivate lifecycle as built-in tools + +**Declaring an MCP server in a skill:** + +```yaml +name: local/github-tools +mcp_servers: + - name: github + transport: stdio + command: npx + args: ["-y", "@modelcontextprotocol/server-github"] + env: + GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}" +``` + +### Validation Runner + +The validation runner executes attached validations during the Execute phase and gates the +Apply transition on their results (ADR-013). Validations are attached to resources and run +automatically when the plan's execution actor modifies those resources. + +**Validation types supported:** + +- Shell command validations (exit code 0 = pass) +- Python callable validations +- BDD scenario validations (Behave) +- Custom validation plugins + +The `ApplyValidationSummary` aggregates results across all validations and blocks Apply if +any required validation fails or if no validations were run (empty-run guard). + +### Multi-File Generation + +The Execute phase now supports generating and modifying multiple files in a single plan +execution. The LLM execution actor can: + +- Create new files via `FILE:` blocks in its output +- Modify existing files via structured diff output +- Delete files via explicit deletion markers +- Respect `.gitignore` and project-level exclusion rules + +All file operations are written to the git worktree sandbox during Execute and merged to the +real project during Apply. + +### Skill Registry + +The Skill Registry is the central catalog of all skills available to actors (ADR-012, +ADR-028, ADR-030). In v3.1.0, the registry supports four tool sources unified under a single +skill abstraction: + +| Source | Description | +|--------|-------------| +| **Built-in tools** | Core tools shipped with CleverAgents (file I/O, shell, git) | +| **MCP tools** | External tools discovered from MCP servers | +| **Agent Skills** | Instruction-driven workflows from `SKILL.md` files (AgentSkills.io standard) | +| **Custom tools** | User-defined Python callables registered via YAML | + +The registry flattens all four sources into a unified tool surface for each actor, resolving +name collisions at registration time. + +### Agent Skills Standard (AgentSkills.io) + +CleverAgents adopts the [AgentSkills.io](https://AgentSkills.io) standard for packaging +instruction-driven workflows (ADR-028). Skills are authored as `SKILL.md` files with optional +`scripts/`, `references/`, and `assets/` directories. + +**Progressive disclosure tiers:** + +| Tier | What loads | Token cost | +|------|-----------|------------| +| Metadata | `name` + `description` from frontmatter | ~50–100 tokens per skill | +| Instructions | Full `SKILL.md` Markdown body | Loaded only when skill is activated | +| Resources | `scripts/`, `references/`, `assets/` | Loaded on demand during execution | + +### LSP Integration (ADR-027) + +Language Server Protocol (LSP) client integration gives actors language intelligence +(diagnostics, type information, completions, symbol references, definition lookups) without +coupling to any IDE. LSP servers are declared in actor YAML via the `lsp:` section and +activated at actor startup. + +--- + +## CLI Commands Introduced + +| Command | Description | +|---------|-------------| +| `agents tool add` | Register a new tool from a YAML definition | +| `agents tool remove` | Unregister a tool | +| `agents tool list` | List registered tools | +| `agents tool show ` | Show tool details and schema | +| `agents validation attach` | Attach a validation to a resource | +| `agents validation detach` | Detach a validation from a resource | +| `agents validation list` | List validations attached to a resource | +| `agents validation run` | Run validations manually | +| `agents skill show ` | Show skill details and tool surface | +| `agents skill remove` | Unregister a skill | + +--- + +## Technical Highlights + +### Jinja2 YAML Template Preprocessing (ADR-032) + +Actor YAML files are preprocessed with Jinja2 before parsing. This enables: + +- Environment variable interpolation: `{{ env.MY_API_KEY }}` +- Conditional blocks: `{% if env.DEBUG %}...{% endif %}` +- Template inheritance for shared actor configurations + +### Actor Abstraction Formalization (ADR-031) + +The actor abstraction is formally defined: an actor is a YAML-configured conversational unit +implemented as a LangGraph `StateGraph`. The actor/agent distinction is precise: + +- **Actor**: anything conversational — the general abstraction (superset) +- **Agent**: a specialized actor with LLM reasoning, tool-calling, and memory (subset) + +Every custom actor IS a graph. This unification eliminates separate "workflow," "pipeline," +and "orchestrator" concepts. + +### Skill Abstraction Definition (ADR-030) + +The skill abstraction unifies four tool sources (built-in, MCP, Agent Skills, custom) under +a single interface. Actors acquire capabilities exclusively through skills — there is no +mechanism for an actor to gain tool capabilities outside the skill system. + +### Decision Recording Protocol (ADR-033) + +Decisions are recorded at each phase transition with a structured protocol: decision ID +(ULID), decision type, rationale, constraints, and parent decision references. The decision +tree is the persistent record of why every change was made. + +--- + +## Breaking Changes + +### Skill YAML Format + +The `tools` section in skill YAML now requires explicit `source` tags for non-built-in tools: + +```yaml +# v3.0.0 (implicit source) +tools: + - name: my-tool + +# v3.1.0 (explicit source required for MCP and Agent Skills) +tools: + - name: my-tool + source: builtin + +mcp_servers: + - name: github + transport: stdio + command: npx + args: ["-y", "@modelcontextprotocol/server-github"] +``` + +### Actor YAML: `nodes` Required + +Actor YAML files must now include a `nodes` section. Single-LLM actors that previously +relied on implicit defaults must be updated to declare their node explicitly: + +```yaml +# v3.1.0 minimum actor YAML +name: local/my-actor +description: My actor +skills: + - local/my-skill +nodes: + - id: llm + type: agent + model: openai/gpt-4o +``` + +--- + +## Migration Guide + +### Updating Skill YAML Files + +Add explicit `source` tags to any non-built-in tools in your skill YAML files. MCP servers +should be moved to the `mcp_servers` section. Agent Skills should be declared in the +`agent_skills` section. + +### Updating Actor YAML Files + +Add a `nodes` section to any actor YAML files that relied on implicit single-LLM defaults. +Specify the model, system prompt, and any tool nodes explicitly. + +### Re-registering Actors + +After updating YAML files, re-register actors: + +```bash +agents actor add path/to/updated-actor.yaml --replace +``` + +--- + +## Architecture Decision Records + +The following ADRs were accepted as part of this milestone: + +| ADR | Title | +|-----|-------| +| ADR-013 | Validation Abstraction | +| ADR-027 | Language Server Protocol (LSP) Integration | +| ADR-028 | Agent Skills Standard (AgentSkills.io) | +| ADR-029 | Model Context Protocol (MCP) Adoption | +| ADR-030 | Skill Abstraction Definition | +| ADR-031 | Actor Abstraction Definition | +| ADR-032 | Jinja2 YAML Template Preprocessing | +| ADR-033 | Decision Recording Protocol | + +--- + +## Related Documentation + +- [MCP Adapter (ADR-029)](../adr/ADR-029-model-context-protocol.md) +- [Actor Abstraction (ADR-031)](../adr/ADR-031-actor-abstraction-definition.md) +- [Agent Skills Standard (ADR-028)](../adr/ADR-028-agent-skills-standard.md) +- [Skill Abstraction (ADR-030)](../adr/ADR-030-skill-abstraction-definition.md) +- [API — Actor](../api/actor.md) +- [API — Skills](../api/skills.md) +- [API — MCP](../api/mcp.md) +- [v3.0.0 Release Notes](./v3.0.0.md) -- 2.52.0