diff --git a/docs/milestones/index.md b/docs/milestones/index.md new file mode 100644 index 000000000..3ed6d8c96 --- /dev/null +++ b/docs/milestones/index.md @@ -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 diff --git a/docs/milestones/v3.0.0/cli-reference.md b/docs/milestones/v3.0.0/cli-reference.md new file mode 100644 index 000000000..9f2680b29 --- /dev/null +++ b/docs/milestones/v3.0.0/cli-reference.md @@ -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 diff --git a/docs/milestones/v3.0.0/deep-dive.md b/docs/milestones/v3.0.0/deep-dive.md new file mode 100644 index 000000000..9271d0ad3 --- /dev/null +++ b/docs/milestones/v3.0.0/deep-dive.md @@ -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-` 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 diff --git a/docs/milestones/v3.0.0/index.md b/docs/milestones/v3.0.0/index.md new file mode 100644 index 000000000..1f0a68254 --- /dev/null +++ b/docs/milestones/v3.0.0/index.md @@ -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 diff --git a/docs/milestones/v3.1.0/actor-yaml.md b/docs/milestones/v3.1.0/actor-yaml.md new file mode 100644 index 000000000..d7b2ff6bb --- /dev/null +++ b/docs/milestones/v3.1.0/actor-yaml.md @@ -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 diff --git a/docs/milestones/v3.1.0/index.md b/docs/milestones/v3.1.0/index.md new file mode 100644 index 000000000..79b7b356a --- /dev/null +++ b/docs/milestones/v3.1.0/index.md @@ -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 diff --git a/docs/milestones/v3.1.0/integration.md b/docs/milestones/v3.1.0/integration.md new file mode 100644 index 000000000..64558fa81 --- /dev/null +++ b/docs/milestones/v3.1.0/integration.md @@ -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/" +``` + +### 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 diff --git a/docs/milestones/v3.1.0/quickstart.md b/docs/milestones/v3.1.0/quickstart.md new file mode 100644 index 000000000..cfd323a7c --- /dev/null +++ b/docs/milestones/v3.1.0/quickstart.md @@ -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 diff --git a/docs/milestones/v3.1.0/skills.md b/docs/milestones/v3.1.0/skills.md new file mode 100644 index 000000000..a006138e0 --- /dev/null +++ b/docs/milestones/v3.1.0/skills.md @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml index 107028bcf..07a5aba3a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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