[AUTO-DOCS-1] MkDocs setup and v3.0.0/v3.1.0 documentation #9957
@@ -0,0 +1,34 @@
|
||||
# Milestones
|
||||
|
||||
This section documents the major milestones in the CleverAgents v3 release series.
|
||||
Each milestone page covers the features delivered, CLI commands introduced, and
|
||||
architectural decisions made during that release cycle.
|
||||
|
||||
## Release Overview
|
||||
|
||||
| Milestone | Version | Title | Status |
|
||||
|-----------|---------|-------|--------|
|
||||
| M1 | [v3.0.0](v3.0.0.md) | Minimal Local Source-Code Workflow | Released |
|
||||
| M2 | [v3.1.0](v3.1.0.md) | Actor Compiler + Full LLM Integration | Released |
|
||||
|
||||
## What Is a Milestone?
|
||||
|
||||
CleverAgents uses **Clever Semantic Versioning** (MAJOR.MINOR.PATCH) where each
|
||||
MINOR version bump corresponds to a planned milestone delivering a coherent set of
|
||||
features. Milestones are tracked as Forgejo milestones and linked to epics
|
||||
in the issue tracker.
|
||||
|
||||
Each milestone page documents:
|
||||
|
||||
- **Goals** — What the milestone set out to achieve
|
||||
- **Delivered Features** — Concrete capabilities added
|
||||
- **CLI Reference** — Commands introduced or changed
|
||||
- **Architecture Notes** — Key design decisions
|
||||
- **Migration Guide** — Breaking changes and upgrade steps (if any)
|
||||
|
||||
## Related Resources
|
||||
|
||||
- [Implementation Timeline](../timeline.md) — Full chronological timeline
|
||||
- [Architecture](../architecture.md) — System architecture overview
|
||||
- [API Reference](../api/index.md) — Module-level API documentation
|
||||
- [CHANGELOG](https://git.cleverthis.com/cleveragents/cleveragents-core/src/branch/master/CHANGELOG.md) — Detailed change log
|
||||
@@ -0,0 +1,142 @@
|
||||
# v3.0.0 — Action, Resource, Project & Plan CLI Reference
|
||||
|
||||
Complete command documentation for all CleverAgents v3.0.0 CLI commands.
|
||||
|
||||
---
|
||||
|
||||
## Action Management (`agents action`)
|
||||
|
||||
Actions are reusable plan templates defined in YAML. They specify which actors
|
||||
handle each phase of the plan lifecycle and what arguments the plan accepts.
|
||||
|
||||
### `agents action create`
|
||||
|
||||
```bash
|
||||
agents action create --config ./my-action.yaml
|
||||
```
|
||||
|
||||
**Minimal action YAML:**
|
||||
|
||||
```yaml
|
||||
name: local/code-coverage
|
||||
description: Increase code coverage to the target percentage
|
||||
strategy_actor: openai/gpt-4
|
||||
execution_actor: openai/gpt-4
|
||||
definition_of_done: |
|
||||
Line coverage reaches the target percentage for all modules under src/.
|
||||
arguments:
|
||||
- name: target_coverage
|
||||
type: integer
|
||||
required: true
|
||||
```
|
||||
|
||||
**Full action YAML:**
|
||||
|
||||
```yaml
|
||||
name: local/refactor
|
||||
description: Refactor a module to follow SOLID principles
|
||||
strategy_actor: openai/gpt-4
|
||||
execution_actor: anthropic/claude-3
|
||||
estimation_actor: openai/gpt-4
|
||||
invariant_actor: anthropic/claude-3
|
||||
automation_profile: trusted
|
||||
definition_of_done: |
|
||||
All classes follow Single Responsibility Principle.
|
||||
No method exceeds 20 lines.
|
||||
invariants:
|
||||
- "No reduction in test coverage"
|
||||
- "All public APIs remain backward compatible"
|
||||
arguments:
|
||||
- name: module_path
|
||||
type: string
|
||||
required: true
|
||||
```
|
||||
|
||||
### `agents action list` / `show` / `archive`
|
||||
|
||||
```bash
|
||||
agents action list # all actions
|
||||
agents action list --namespace local # filter by namespace
|
||||
agents action list --state available # filter by state
|
||||
agents action show local/code-coverage # show action details
|
||||
agents action archive local/old-action # soft-delete action
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resource Management (`agents resource`)
|
||||
|
||||
Resources are external entities (git repos, directories, mounts) that plans
|
||||
can read or modify.
|
||||
|
||||
### `agents resource add`
|
||||
|
||||
```bash
|
||||
agents resource add git-checkout local/my-repo --path /home/user/projects/my-repo
|
||||
agents resource add fs-directory local/data --path /data --read-only
|
||||
```
|
||||
|
||||
**Built-in resource types (v3.0.0):** `git-checkout`, `fs-directory`, `fs-mount`
|
||||
|
||||
### `agents resource list` / `show` / `remove`
|
||||
|
||||
```bash
|
||||
agents resource list # all resources
|
||||
agents resource show local/my-repo # resource details
|
||||
agents resource remove --yes local/my-repo # remove resource
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Management (`agents project`)
|
||||
|
||||
Projects group resources together for plan execution context.
|
||||
|
||||
### `agents project create` / `link-resource` / `list` / `show`
|
||||
|
||||
```bash
|
||||
agents project create local/my-project --description "My application"
|
||||
agents project link-resource local/my-project local/my-repo
|
||||
agents project list
|
||||
agents project show local/my-project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plan Lifecycle (`agents plan`)
|
||||
|
||||
Plans are the central execution unit. Lifecycle: **Strategize -> Execute -> Apply**.
|
||||
|
||||
### `agents plan use` — Create a plan
|
||||
|
||||
```bash
|
||||
agents plan use local/code-coverage my-project --arg target_coverage=80
|
||||
agents plan use local/lint proj-1 proj-2 # multiple projects
|
||||
agents plan use local/refactor my-project \ # with automation profile & invariants
|
||||
--automation-profile trusted --invariant "No new warnings"
|
||||
agents plan use local/code-coverage my-project \ # with actor overrides
|
||||
--strategy-actor openai/gpt-4 --execution-actor anthropic/claude-3
|
||||
```
|
||||
|
||||
### `agents plan execute` / `diff` / `apply` — Run and merge changes
|
||||
|
||||
```bash
|
||||
agents plan execute # Strategize -> Execute phases
|
||||
agents plan diff 01HXYZ... # preview proposed changes
|
||||
agents plan apply --yes # merge changes (skip confirmation)
|
||||
```
|
||||
|
||||
### `agents plan list` / `status` / `cancel` — Manage plans
|
||||
|
||||
```bash
|
||||
agents plan list --state complete # filter plans
|
||||
agents plan status 01HXYZ... # plan details
|
||||
agents plan cancel 01HXYZ... --reason "Requirements changed"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI overview (v3.0.0)](index.md) — Goals, architecture notes, feature table
|
||||
- [Deep Dive](deep-dive.md) — Sandbox, persistence, domain model internals
|
||||
@@ -0,0 +1,95 @@
|
||||
# v3.0.0 — Deep Dive: Sandbox, Persistence & Domain Model
|
||||
|
||||
Internal architecture details for CleverAgents v3.0.0.
|
||||
|
||||
---
|
||||
|
||||
## Git Worktree Sandbox
|
||||
|
||||
The git worktree sandbox isolates LLM-generated changes in a dedicated branch
|
||||
and worktree until the user approves them via `agents plan apply`.
|
||||
|
||||
See the full [Git Worktree Sandbox](../../modules/git-worktree-sandbox.md) module docs.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Plan execute creates branch `cleveragents/plan-<id>` from current HEAD.
|
||||
2. A temporary git worktree is created in a system temp directory.
|
||||
3. The LLM writes changes only inside the worktree (not the real repo).
|
||||
4. `plan diff` shows proposed changes as unified diff.
|
||||
5. `plan apply` merges sandbox into original via `git merge`, then cleans up.
|
||||
6. `plan cancel` discards the worktree — no real repo changes.
|
||||
|
||||
Non-git resources (e.g. `fs-directory`) fall back to `shutil.copy2`.
|
||||
|
||||
### Apply Summary Output
|
||||
|
||||
```
|
||||
╭─ Apply Summary ────────────────────────────────────────╮
|
||||
│ Plan ID: plan-01HZ... │
|
||||
│ Artifacts: 3 files changed │
|
||||
│ Insertions: +142 │
|
||||
│ Deletions: -17 │
|
||||
╰───────────────────────────────────────────────────────╯
|
||||
╭─ Sandbox Cleanup ──────────────────────────────────────╮
|
||||
│ [x] Worktree removed │
|
||||
│ [x] Branch deleted │
|
||||
╰───────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SQLite Persistence with Alembic
|
||||
|
||||
All entities persist in `~/.cleveragents/cleveragents.db`.
|
||||
|
||||
### Managed Tables
|
||||
|
||||
| Table | Description |
|
||||
|-------|-------------|
|
||||
| `actions` | Action templates |
|
||||
| `action_arguments`, `action_invariants` | Per-action metadata |
|
||||
| `resources` | Resource instances |
|
||||
| `projects`, `project_resource_links` | Projects and links |
|
||||
| `plans`, `plan_project_links` | Plans and project bindings |
|
||||
| `decisions` | Decision tree nodes per plan |
|
||||
|
||||
### Migration Commands
|
||||
|
||||
```bash
|
||||
alembic upgrade head # apply pending migrations
|
||||
alembic current # show current revision
|
||||
alembic history # migration history
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Domain Model (Pydantic v2)
|
||||
|
||||
All domain entities use Pydantic v2 with `frozen=True` for immutability.
|
||||
|
||||
```python
|
||||
from cleveragents.domain.models import Action, Resource, Project, Plan
|
||||
|
||||
action = Action(
|
||||
name="local/code-coverage",
|
||||
description="Increase code coverage",
|
||||
strategy_actor="openai/gpt-4",
|
||||
execution_actor="openai/gpt-4",
|
||||
definition_of_done="Coverage reaches target.",
|
||||
)
|
||||
# action.name = "other" # raises ValidationError (frozen)
|
||||
```
|
||||
|
||||
ULIDs (Universally Unique Lexicographically Sortable Identifiers) are the primary keys.
|
||||
|
||||
See [ADR-019](../../adr/ADR-019-storage-and-persistence.md) for storage details.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Reference](cli-reference.md) — All command documentation
|
||||
- [Git Worktree Sandbox](../../modules/git-worktree-sandbox.md)
|
||||
- [ADR-006](../../adr/ADR-006-plan-lifecycle.md): Plan Lifecycle
|
||||
- [ADR-019](../../adr/ADR-019-storage-and-persistence.md): Storage & Persistence
|
||||
@@ -0,0 +1,87 @@
|
||||
# v3.0.0 — Minimal Local Source-Code Workflow (M1) — Overview
|
||||
|
||||
**Released:** v3.0.0
|
||||
**Milestone:** M1 — Minimal Local Source-Code Workflow
|
||||
**Theme:** Establish the foundational CLI, domain model, and persistence layer for local agent-driven code workflows.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
v3.0.0 delivers the first complete end-to-end workflow for using CleverAgents to
|
||||
manage source-code changes on a local machine. It introduces the core CLI command
|
||||
groups (`agents action`, `agents resource`, `agents project`, `agents plan`),
|
||||
a SQLite-backed persistence layer with Alembic migrations, and a git worktree
|
||||
sandbox that isolates LLM-generated changes until the user approves them.
|
||||
|
||||
This milestone establishes the **specification-first** development model: every
|
||||
feature is driven by a YAML-defined action template, executed through a structured
|
||||
plan lifecycle (Strategize -> Execute -> Apply), and persisted in a local SQLite
|
||||
database.
|
||||
|
||||
---
|
||||
|
||||
## Goals
|
||||
|
||||
1. Provide a minimal but complete CLI for local source-code automation.
|
||||
2. Introduce a typed, versioned domain model using Pydantic v2.
|
||||
3. Persist all entities (actions, resources, projects, plans) in SQLite via Alembic.
|
||||
4. Isolate LLM-generated changes in a git worktree sandbox before applying them.
|
||||
5. Enable plan lifecycle management: create, execute, diff, and apply plans.
|
||||
|
||||
---
|
||||
|
||||
## Delivered Features
|
||||
|
||||
v3.0.0 delivers the following feature groups:
|
||||
|
||||
| Feature Group | CLI Commands | Description | Page |
|
||||
|---------------|-------------|-------------|------|
|
||||
| **Action Mgmt** | `agents action` | YAML plan templates | [CLI Reference](cli-reference.md) |
|
||||
| **Resource Mgmt** | `agents resource` | Git repos, filesystems | [CLI Reference](cli-reference.md) |
|
||||
| **Project Mgmt** | `agents project` | Group resources for plans | [CLI Reference](cli-reference.md) |
|
||||
| **Plan Lifecycle** | `agents plan` | Strategy-Execute-Apply cycle | [CLI Reference](cli-reference.md) |
|
||||
| **Git Worktree Sandbox** | (internal) | Isolated LLM change sandbox | [Deep Dive](deep-dive.md) |
|
||||
| **SQLite Persistence** | (internal) | SQLite + Alembic with 9 tables | [Deep Dive](deep-dive.md) |
|
||||
| **Pydantic v2 Domain Model** | (internal) | Frozen=True, ULID keys | [Deep Dive](deep-dive.md) |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
### Layered Architecture
|
||||
|
||||
v3.0.0 follows a strict layered architecture (see [ADR-001](../../adr/ADR-001-layered-architecture.md)):
|
||||
|
||||
```
|
||||
CLI Layer agents action/resource/project/plan
|
||||
|
|
||||
Application Layer PlanLifecycleService, ActionService, ResourceService
|
||||
|
|
||||
Domain Layer Action, Resource, Project, Plan (Pydantic v2, frozen=True)
|
||||
|
|
||||
Infrastructure SQLite + Alembic, GitWorktreeSandbox, ToolRegistry
|
||||
```
|
||||
|
||||
### Dependency Injection
|
||||
|
||||
All services are wired via a DI container (see [ADR-003](../../adr/ADR-003-dependency-injection.md)).
|
||||
|
||||
### Plan Lifecycle State Machine
|
||||
|
||||
Plans follow a strict state machine (see [ADR-006](../../adr/ADR-006-plan-lifecycle.md)):
|
||||
|
||||
```
|
||||
CREATED -> STRATEGIZE/queued -> STRATEGIZE/complete
|
||||
-> EXECUTE/queued -> EXECUTE/complete
|
||||
-> APPLY/queued -> APPLY/complete -> CANCELLED / ERRORED (terminal)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Reference](cli-reference.md) — Full command-by-command documentation
|
||||
- [Deep Dive](deep-dive.md) — Sandbox, persistence, domain model internals
|
||||
- [ADR-001](../../adr/ADR-001-layered-architecture.md): Layered Architecture
|
||||
- [ADR-006](../../adr/ADR-006-plan-lifecycle.md): Plan Lifecycle
|
||||
@@ -0,0 +1,131 @@
|
||||
# v3.1.0 — Actor YAML Format & Compiler
|
||||
|
||||
Declarative actor definitions compiled into LangGraph graphs.
|
||||
|
||||
---
|
||||
|
||||
## Actor YAML Format
|
||||
|
||||
Every actor file must specify `version: "3"` and one of three types: `llm`, `tool`, or `graph`.
|
||||
|
||||
See [Actor YAML Schema Reference](../../reference/actors_schema.md) for full fields.
|
||||
|
||||
### LLM Actor
|
||||
|
||||
```yaml
|
||||
version: "3"
|
||||
name: assistants/code-reviewer
|
||||
type: llm
|
||||
model: gpt-4
|
||||
system_prompt: |
|
||||
You are an expert Python code reviewer.
|
||||
context_view: reviewer
|
||||
memory:
|
||||
enabled: true
|
||||
max_messages: 20
|
||||
```
|
||||
|
||||
### Tool Actor
|
||||
|
||||
```yaml
|
||||
version: "3"
|
||||
name: utilities/file-ops
|
||||
type: tool
|
||||
tools:
|
||||
- files/read_file
|
||||
- files/write_file
|
||||
- files/list_directory
|
||||
```
|
||||
|
||||
### Graph Actor
|
||||
|
||||
```yaml
|
||||
version: "3"
|
||||
name: workflows/tdd-cycle
|
||||
type: graph
|
||||
model: gpt-4
|
||||
route:
|
||||
nodes:
|
||||
- id: planner; type: agent; name: Task Planner
|
||||
config: { model: gpt-4, prompt: "Plan implementation tasks." }
|
||||
- id: implementer; type: agent; name: Code Implementer
|
||||
config: { model: gpt-4, prompt: "Implement planned tasks." }
|
||||
- id: verifier; type: tool; name: Test Runner
|
||||
config: { tool_name: testing/run_pytest }
|
||||
- id: check_results; type: conditional
|
||||
config: { conditions: [{check: "passed==True", route_to: done}, {check: "passed==False", route_to: implementer}] }
|
||||
- id: done; type: agent; name: Summary Writer
|
||||
edges:
|
||||
- {from_node: planner, to_node: implementer}
|
||||
- {from_node: implementer, to_node: verifier}
|
||||
- {from_node: verifier, to_node: check_results}
|
||||
entry_node: planner
|
||||
exit_nodes: [done]
|
||||
```
|
||||
|
||||
### Actor Name Format
|
||||
|
||||
Must use `namespace/name`:
|
||||
- `assistants/code-reviewer` — valid
|
||||
- `code-reviewer` — invalid (no namespace)
|
||||
- `a/b/c` — invalid (too many slashes)
|
||||
|
||||
---
|
||||
|
||||
## Actor Compiler (LangGraph Integration)
|
||||
|
||||
Translates GRAPH-type YAML into LangGraph `StateGraph` structures.
|
||||
|
||||
See [Actor Compiler Reference](../../reference/actor_compiler.md).
|
||||
|
||||
### Compilation Pipeline
|
||||
|
||||
```
|
||||
ActorConfigSchema (type=GRAPH)
|
||||
-> validate type, route
|
||||
-> reference validation (all node IDs exist)
|
||||
-> intra-graph cycle detection
|
||||
-> cross-actor subgraph cycle detection
|
||||
-> node mapping (NodeDef -> LangGraph NodeConfig)
|
||||
-> edge mapping
|
||||
-> metadata assembly
|
||||
=> CompiledActor (nodes, edges, entry_point, metadata)
|
||||
```
|
||||
|
||||
### Node Type Mapping
|
||||
|
||||
| Actor Node | LangGraph Type |
|
||||
|------------|----------------|
|
||||
| `agent` | AGENT |
|
||||
| `tool` | TOOL |
|
||||
| `conditional` | CONDITIONAL |
|
||||
| `subgraph` | SUBGRAPH |
|
||||
|
||||
### Compilation Errors
|
||||
|
||||
| Error | Class | When |
|
||||
|-------|-------|------|
|
||||
| Non-GRAPH type | `ActorCompilationError` | config.type != GRAPH |
|
||||
| Missing route | `ActorCompilationError` | config.route is None |
|
||||
| Missing node | `MissingNodeError` | edge refs unknown node |
|
||||
| Invalid entry/exit | `InvalidEntryExitError` | node not in graph |
|
||||
| Cycle detected | `SubgraphCycleError` | intra or cross-actor cycle |
|
||||
|
||||
### Graph Validation Rules
|
||||
|
||||
1. Unique node IDs within graph
|
||||
2. Entry node exists and is valid
|
||||
3. All exit_nodes reference valid nodes
|
||||
4. All edge from_node/to_node exist
|
||||
5. No cycles (graphs are acyclic)
|
||||
6. All nodes reachable from entry_node
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Actor YAML Schema Reference](../../reference/actors_schema.md)
|
||||
- [Actor Compiler Reference](../../reference/actor_compiler.md)
|
||||
- [ADR-010](../../adr/ADR-010-actor-and-agent-architecture.md): Actor Architecture
|
||||
- [ADR-022](../../adr/ADR-022-langchain-langgraph-integration.md): LangGraph Integration
|
||||
- [ADR-031](../../adr/ADR-031-actor-abstraction-definition.md): Actor Abstraction Definition
|
||||
@@ -0,0 +1,69 @@
|
||||
# v3.1.0 — Actor Compiler + Full LLM Integration (M2) — Overview
|
||||
|
||||
**Released:** v3.1.0
|
||||
**Milestone:** M2 — Actor Compiler + Full LLM Integration
|
||||
**Theme:** Introduce the Actor system, compile YAML-defined actors into executable LangGraph graphs, and wire full LLM integration through MCP adapter, tool router, skill registry, and validation runner.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
v3.1.0 builds on the v3.0.0 foundation by introducing the **Actor system** —
|
||||
declarative YAML definitions for AI agents compiled into LangGraph `StateGraph`
|
||||
structures at runtime. It also delivers MCP adapter (external tool server
|
||||
connectivity), tool router (provider normalization), skill registry (reusable
|
||||
tool collections), and validation runner (pre-apply quality gates).
|
||||
|
||||
---
|
||||
|
||||
## Goals
|
||||
|
||||
1. Define a declarative YAML format for actors (`llm`, `tool`, `graph`).
|
||||
2. Compile GRAPH-type actors into executable LangGraph `StateGraph` structures.
|
||||
3. Connect to external MCP tool servers for tool discovery and invocation.
|
||||
4. Route LLM tool calls across OpenAI, Anthropic, and LangChain formats.
|
||||
5. Manage reusable tool collections via the skill registry.
|
||||
6. Enforce validation gates before plan apply via the validation runner.
|
||||
|
||||
---
|
||||
|
||||
## Feature Index
|
||||
|
||||
| Feature | Description | Documentation |
|
||||
|---------|-------------|---------------|
|
||||
| **Actor YAML** | Declarative defs: llm, tool, graph types | [Actor Format](actor-yaml.md) |
|
||||
| **Actor Compiler** | Compile to LangGraph StateGraph | [Actor Format](actor-yaml.md) |
|
||||
| **MCP Adapter** | External MCP tool server connectivity | [Integration](integration.md) |
|
||||
| **Tool Router** | Normalize across OpenAI/Anthropic/LC formats | [Integration](integration.md) |
|
||||
| **Skill Registry** | Persistent, composable tool collections | [Skills](skills.md) |
|
||||
| **Validation Runner** | Pre-apply required/informational gates | [Skills](skills.md) |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
### Actor System Design
|
||||
|
||||
Follows the **Actor Abstraction Definition** (see [ADR-031](../../adr/ADR-031-actor-abstraction-definition.md)):
|
||||
- **Declarative** — defined in YAML, not code.
|
||||
- **Composable** — GRAPH actors embed other actors as subgraphs.
|
||||
- **Compiled** — validated and compiled to LangGraph at load time.
|
||||
- **Namespaced** — `namespace/name` format required.
|
||||
|
||||
### LangGraph Integration
|
||||
|
||||
See [ADR-022](../../adr/ADR-022-langchain-langgraph-integration.md). The compiler
|
||||
takes GRAPH actors through an 8-step pipeline, producing LangGraph `StateGraph` structures.
|
||||
|
||||
### MCP & Skills
|
||||
|
||||
MCP adapter implements Model Context Protocol (see [ADR-029](../../adr/ADR-029-model-context-protocol.md)). Skill registry implements the Skill Abstraction Definition (see [ADR-030](../../adr/ADR-030-skill-abstraction-definition.md) and [ADR-012](../../adr/ADR-012-skill-system.md)).
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Actor Format & Compiler](actor-yaml.md)
|
||||
- [MCP + Tool Router](integration.md)
|
||||
- [Skills + Validation Runner](skills.md)
|
||||
- [Quick Start Guide](quickstart.md) — common workflows
|
||||
@@ -0,0 +1,91 @@
|
||||
# v3.1.0 — MCP Adapter & Tool Router
|
||||
|
||||
External tool server integration and LLM provider normalization.
|
||||
|
||||
---
|
||||
|
||||
## MCP Adapter
|
||||
|
||||
The Model Context Protocol adapter connects CleverAgents to external tool servers.
|
||||
|
||||
### Supported Transports
|
||||
|
||||
| Transport | Description | Config Required |
|
||||
|-----------|-------------|-----------------|
|
||||
| `stdio` | Spawns subprocess | `command` |
|
||||
| `sse` | Server-Sent Events HTTP | `url` |
|
||||
| `streamable-http` | Streamable HTTP | `url` |
|
||||
|
||||
### Configuration & Usage
|
||||
|
||||
```python
|
||||
from cleveragents.mcp.adapter import MCPToolAdapter, MCPServerConfig
|
||||
|
||||
config = MCPServerConfig(
|
||||
name="my-tools", transport="stdio", command="python",
|
||||
args=["-m", "my_mcp_server"], env={"API_KEY": "secret"},
|
||||
)
|
||||
adapter = MCPToolAdapter(config)
|
||||
adapter.connect(timeout=10.0)
|
||||
tools = adapter.discover_tools()
|
||||
result = adapter.invoke("create_issue", {"title": "Bug"})
|
||||
# result: {success: true, data: {"issue_id": 42}, duration_ms: 145.3}
|
||||
adapter.disconnect()
|
||||
```
|
||||
|
||||
### ToolRegistry Integration
|
||||
|
||||
```python
|
||||
from cleveragents.tool.registry import ToolRegistry
|
||||
registry = ToolRegistry()
|
||||
adapter.register_tools(registry, namespace="my-tools")
|
||||
# Tools available as "my-tools/<tool_name>"
|
||||
```
|
||||
|
||||
### Capability Inference (name-based heuristics)
|
||||
|
||||
- `read`, `get`, `list`, `search`, `find` — inferred as read-only
|
||||
- `write`, `create`, `update`, `delete`, `set` — inferred as writable
|
||||
|
||||
### Reconnect on Failure
|
||||
|
||||
```python
|
||||
try: adapter.invoke("tool", {"arg": "x"})
|
||||
except RuntimeError:
|
||||
adapter.reconnect(timeout=10.0)
|
||||
adapter.discover_tools()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Router
|
||||
|
||||
Normalizes LLM provider tool calls into a unified internal representation.
|
||||
|
||||
### Supported Provider Formats
|
||||
|
||||
| Provider | Shape | Arguments Key | Type |
|
||||
|----------|-------|---------------|------|
|
||||
| OpenAI | `{"name": "...", "arguments": "..."}` | `arguments` | JSON string |
|
||||
| Anthropic | `{"name": "...", "input": {...}}` | `input` | dict |
|
||||
| LangChain | `{"name": "...", "type": "tool_call", "args": {...}}` | `args` | dict |
|
||||
|
||||
### Usage
|
||||
|
||||
```python
|
||||
from cleveragents.tool.router import ToolCallRouter
|
||||
router = ToolCallRouter(registry, runner, plan_id="plan-001")
|
||||
result = router.route({"name": "files/read_file", 'arguments': '{"path": "a.py"}'})
|
||||
# result.provider_format: "openai" result.tool_call_id: "tc_<24-hex>"
|
||||
|
||||
# Stable IDs: generate_tool_call_id("plan-001", 0) always returns same value
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Tool Adapter Reference](../../reference/mcp_adapter.md)
|
||||
- [Tool Call Router Reference](../../reference/tool_router.md)
|
||||
- [ADR-011](../../adr/ADR-011-tool-system.md): Tool System
|
||||
- [ADR-029](../../adr/ADR-029-model-context-protocol.md): MCP Adoption
|
||||
@@ -0,0 +1,66 @@
|
||||
# v3.1.0 — Quick Start Guide
|
||||
|
||||
Common workflows: actor definitions, MCP setup, skills, & validation gates.
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Workflow
|
||||
|
||||
```bash
|
||||
# 1. Define a graph actor YAML
|
||||
cat > actors/tdd.yaml << 'EOF'
|
||||
version: "3"
|
||||
name: assistants/tdd
|
||||
type: graph
|
||||
model: gpt-4
|
||||
route:
|
||||
nodes:
|
||||
- id: planner; type: agent; name: Planner
|
||||
config: { model: gpt-4, prompt: "Plan tasks from requirements." }
|
||||
- id: implementer; type: agent; name: Implementer
|
||||
config: { model: gpt-4, prompt: "Write clean tested code." }
|
||||
edges: [{from_node: planner, to_node: implementer}]
|
||||
entry_node: planner
|
||||
exit_nodes: [implementer]
|
||||
EOF
|
||||
|
||||
# 2. Create an action using the actor
|
||||
cat > review-action.yaml << 'EOF'
|
||||
name: local/code-review
|
||||
description: Review code changes
|
||||
execution_actor: assistants/tdd
|
||||
definition_of_done: |
|
||||
All changes reviewed for correctness and style.
|
||||
EOF
|
||||
agents action create --config review-action.yaml
|
||||
|
||||
# 3. Configure MCP tool server in ~/.cleveragents/config.toml
|
||||
|
||||
# 4. Register a skill
|
||||
agents skill add --config my-skill.yaml
|
||||
|
||||
# 5. Execute plan with validation gate
|
||||
agents plan use local/code-review my-project
|
||||
agents plan execute # runs validation before apply
|
||||
agents plan diff
|
||||
agents plan apply --yes # blocked if required validations fail
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Actor Creation Checklist
|
||||
|
||||
- [ ] `version: "3"` specified
|
||||
- [ ] Valid type: `llm`, `tool`, or `graph`
|
||||
- [ ] Name follows `namespace/name` format
|
||||
- [ ] All referenced actors and tools are resolvable
|
||||
- [ ] Graph actors have valid entry/exit nodes and acyclic edges
|
||||
|
||||
---
|
||||
|
||||
## Skill & Validation Quick Tips
|
||||
|
||||
- Skills can include other skills for composition
|
||||
- Agent Skills Standard discovers skills from filesystem paths in `agent_skills_paths`
|
||||
- Validations run deterministically: alphabetical (resource, mode, name) order
|
||||
- Run with `max_workers=1` in CI for predictable sequential validation
|
||||
@@ -0,0 +1,127 @@
|
||||
# v3.1.0 — Skill Registry & Validation Runner
|
||||
|
||||
Reusable tool collections and pre-apply validation quality gates.
|
||||
|
||||
---
|
||||
|
||||
## Skill Registry
|
||||
|
||||
Persistent storage for named, reusable tool collections in SQLite.
|
||||
|
||||
### Item Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `tool_ref` | Reference to a named tool |
|
||||
| `include` | Recursive inclusion of another skill |
|
||||
| `inline_tool` | Anonymous tool defined inline |
|
||||
| `mcp_source` | MCP server tool source |
|
||||
| `agent_source` | Agent Skills Standard folder source |
|
||||
|
||||
### CLI Commands
|
||||
|
||||
```bash
|
||||
agents skill list # all skills
|
||||
agents skill tools local/devops-toolkit # show skill's tools
|
||||
agents skill add --config ./my-skill.yaml # register from YAML
|
||||
agents skill remove local/my-skill # remove a skill
|
||||
```
|
||||
|
||||
### Service API
|
||||
|
||||
```python
|
||||
from cleveragents.application.services import SkillRegistryService
|
||||
svc = SkillRegistryService(skill_repo=SkillRepository(session_factory))
|
||||
svc.add_skill(skill) # register
|
||||
skill = svc.get_skill("local/code-tools") # retrieve
|
||||
skills = svc.list_skills(namespace="local") # filter
|
||||
svc.remove_skill("local/code-tools") # delete
|
||||
```
|
||||
|
||||
### Agent Skills Standard Integration
|
||||
|
||||
Filesystem-based tool bundles with `SKILL.md` + YAML front-matter.
|
||||
|
||||
**Default discovery path:** `~/.cleveragents/agent_skills`
|
||||
|
||||
**SKILL.md format:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-tool
|
||||
description: A custom agent skill
|
||||
input_schema: {type: object, properties: {query: {type: string}}}
|
||||
---
|
||||
|
||||
# My Tool
|
||||
Additional documentation.
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
```toml
|
||||
[skills]
|
||||
agent_skills_paths = "/home/user/.cleveragents/agent_skills,/opt/skills"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Runner
|
||||
|
||||
Executes validations against plan resources before Apply phase.
|
||||
|
||||
### Modes
|
||||
|
||||
| Mode | Pass Behavior | Fail Behavior |
|
||||
|------|---------------|----------------|
|
||||
| `required` | OK | **Blocks apply** — sets `all_required_passed = False` |
|
||||
| `informational` | Logged | Logged only — does NOT block apply |
|
||||
|
||||
### Attachment Scopes
|
||||
|
||||
| Scope | Active When |
|
||||
|-------|-------------|
|
||||
| direct | Always for the resource |
|
||||
| project | Resource accessed via a project |
|
||||
| plan | Only for specific plan |
|
||||
|
||||
### Apply Validation Gate
|
||||
|
||||
```python
|
||||
from cleveragents.validation.gate import ApplyValidationGate
|
||||
gate = ApplyValidationGate(runner=DefaultValidationRunner())
|
||||
summary = gate.run(plan_id, attachments, context)
|
||||
if gate.should_block_apply(summary):
|
||||
# report failure reasons, block apply
|
||||
else:
|
||||
# proceed
|
||||
```
|
||||
|
||||
### Blocking vs Allowed Output
|
||||
|
||||
**Blocked:**
|
||||
```
|
||||
Validation Gate: BLOCKED
|
||||
Required: 1 passed, 1 failed
|
||||
Failures: lint-check on res-001: 3 lint errors found
|
||||
```
|
||||
|
||||
**Allowed:**
|
||||
```
|
||||
Validation Gate: PASSED
|
||||
Required: 2 passed, 0 failed
|
||||
Informational: 1 passed, 0 failed
|
||||
```
|
||||
|
||||
### Concurrency
|
||||
|
||||
Uses `ThreadPoolExecutor` with configurable `max_workers` (default 4).
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Skill Registry Reference](../../reference/skill_registry.md)
|
||||
- [Validation Pipeline Reference](../../reference/validation_pipeline.md)
|
||||
- [ADR-012](../../adr/ADR-012-skill-system.md): Skill System
|
||||
- [ADR-013](../../adr/ADR-013-validation-abstraction.md): Validation Abstraction
|
||||
+93
-91
@@ -1,13 +1,8 @@
|
||||
# yaml-language-server: $schema=https://json.schemastore.org/mkdocs-1.6.json
|
||||
# yaml-language-server: customTags:
|
||||
# - !ENV scalar
|
||||
# - !ENV sequence
|
||||
site_name: CleverAgents Documentation
|
||||
site_description: Documentation for CleverAgents.
|
||||
site_author: CleverThis, Inc.
|
||||
site_url: https://docs.cleverthis.com/cleveragents
|
||||
site_dir: build/site
|
||||
|
||||
nav:
|
||||
- Specification: specification.md
|
||||
- Architecture: architecture.md
|
||||
@@ -53,6 +48,18 @@ nav:
|
||||
- Custom Sandbox Strategy: development/custom_sandbox_strategy.md
|
||||
- Documentation Writer: development/docs-writer.md
|
||||
- ACP to A2A Migration: development/acp-to-a2a-migration.md
|
||||
- Milestones:
|
||||
- Overview: milestones/index.md
|
||||
- "v3.0.0 \u2014 Minimal Local Source-Code Workflow (M1)":
|
||||
- milestones/v3.0.0/index.md
|
||||
- milestones/v3.0.0/cli-reference.md
|
||||
- milestones/v3.0.0/deep-dive.md
|
||||
- "v3.1.0 \u2014 Actor Compiler + Full LLM Integration (M2)":
|
||||
- milestones/v3.1.0/index.md
|
||||
- milestones/v3.1.0/actor-yaml.md
|
||||
- milestones/v3.1.0/integration.md
|
||||
- milestones/v3.1.0/skills.md
|
||||
- milestones/v3.1.0/quickstart.md
|
||||
- Implementation Timeline: timeline.md
|
||||
- Advanced Concepts (v3.6.0):
|
||||
- Overview & Context Strategies: advanced-concepts/index.md
|
||||
@@ -119,105 +126,100 @@ nav:
|
||||
- ADR-046 TUI Reference and Command System: adr/ADR-046-tui-reference-and-command-system.md
|
||||
- ADR-047 A2A Standard Adoption: adr/ADR-047-acp-standard-adoption.md
|
||||
- ADR-048 Server Application Architecture: adr/ADR-048-server-application-architecture.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
custom_dir: docs/overrides
|
||||
features:
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
- toc.integrate
|
||||
- toc.follow
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
- toc.integrate
|
||||
- toc.follow
|
||||
palette:
|
||||
- scheme: default
|
||||
primary: blue
|
||||
accent: cyan
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
- scheme: slate
|
||||
primary: blue
|
||||
accent: cyan
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to light mode
|
||||
|
||||
- scheme: default
|
||||
primary: blue
|
||||
accent: cyan
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
- scheme: slate
|
||||
primary: blue
|
||||
accent: cyan
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to light mode
|
||||
hooks:
|
||||
- hooks/adr_hooks.py
|
||||
|
||||
- hooks/adr_hooks.py
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
|
||||
- stylesheets/extra.css
|
||||
extra_javascript:
|
||||
- javascripts/adr-page.js
|
||||
- javascripts/toc-collapse.js
|
||||
- javascripts/diagram-lightbox.js
|
||||
|
||||
- javascripts/adr-page.js
|
||||
- javascripts/toc-collapse.js
|
||||
- javascripts/diagram-lightbox.js
|
||||
extra:
|
||||
adr_tiers:
|
||||
1:
|
||||
title: "Foundational"
|
||||
description: "Structural and technological foundation upon which all other decisions rest."
|
||||
title: Foundational
|
||||
description: Structural and technological foundation upon which all other decisions
|
||||
rest.
|
||||
2:
|
||||
title: "Core Domain"
|
||||
description: "Domain model — entities, lifecycles, and relationships that constitute core logic."
|
||||
title: Core Domain
|
||||
description: "Domain model \u2014 entities, lifecycles, and relationships that\
|
||||
\ constitute core logic."
|
||||
3:
|
||||
title: "Infrastructure and Behavior"
|
||||
description: "Cross-cutting behavioral systems and infrastructure concerns."
|
||||
title: Infrastructure and Behavior
|
||||
description: Cross-cutting behavioral systems and infrastructure concerns.
|
||||
4:
|
||||
title: "Integration and Operations"
|
||||
description: "External integrations, operational interfaces, and deployment concerns."
|
||||
|
||||
title: Integration and Operations
|
||||
description: External integrations, operational interfaces, and deployment concerns.
|
||||
plugins:
|
||||
- search
|
||||
- gen-files:
|
||||
scripts:
|
||||
- docs/gen_ref_pages.py
|
||||
- literate-nav:
|
||||
nav_file: SUMMARY.md
|
||||
- mkdocstrings:
|
||||
handlers:
|
||||
python:
|
||||
paths: [src]
|
||||
options:
|
||||
docstring_style: google
|
||||
docstring_section_style: table
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
merge_init_into_class: true
|
||||
separate_signature: true
|
||||
show_signature_annotations: true
|
||||
signature_crossrefs: true
|
||||
summary: true
|
||||
extensions:
|
||||
- griffe_pydantic:
|
||||
schema: true
|
||||
- kroki:
|
||||
server_url: https://kroki.qoto.org
|
||||
#server_url: https://kroki.io
|
||||
enable_mermaid: true
|
||||
fence_prefix: kroki-
|
||||
http_method: POST
|
||||
|
||||
- search
|
||||
- gen-files:
|
||||
scripts:
|
||||
- docs/gen_ref_pages.py
|
||||
- literate-nav:
|
||||
nav_file: SUMMARY.md
|
||||
- mkdocstrings:
|
||||
handlers:
|
||||
python:
|
||||
paths:
|
||||
- src
|
||||
options:
|
||||
docstring_style: google
|
||||
docstring_section_style: table
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
merge_init_into_class: true
|
||||
separate_signature: true
|
||||
show_signature_annotations: true
|
||||
signature_crossrefs: true
|
||||
summary: true
|
||||
extensions:
|
||||
- griffe_pydantic:
|
||||
schema: true
|
||||
- kroki:
|
||||
server_url: https://kroki.qoto.org
|
||||
enable_mermaid: true
|
||||
fence_prefix: kroki-
|
||||
http_method: POST
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.critic
|
||||
- pymdownx.caret
|
||||
- pymdownx.keys
|
||||
- pymdownx.mark
|
||||
- pymdownx.tilde
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- attr_list
|
||||
- def_list
|
||||
- footnotes
|
||||
- md_in_html
|
||||
- tables
|
||||
- codehilite
|
||||
- toc:
|
||||
permalink: true
|
||||
toc_depth: 1-6
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.critic
|
||||
- pymdownx.caret
|
||||
- pymdownx.keys
|
||||
- pymdownx.mark
|
||||
- pymdownx.tilde
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- attr_list
|
||||
- def_list
|
||||
- footnotes
|
||||
- md_in_html
|
||||
- tables
|
||||
- codehilite
|
||||
- toc:
|
||||
permalink: true
|
||||
toc_depth: 1-6
|
||||
|
||||
Reference in New Issue
Block a user