195 KiB
CleverAgents Documentation (Detailed Spec)
Source Material
Key themes include:
- A four-phase plan lifecycle (Action → Strategize → Execute → Apply).
- Actors as a unifying abstraction (an LLM/agent or a whole graph).
- A sandbox + diff review workflow and CLI-first interaction model.
- A scalable context/memory architecture (hot/warm/cold tiers, per-actor views).
- A future-facing correction model where the user can "edit the decision tree" and only recompute affected subtrees.
Big Picture: What CleverAgents is
CleverAgents is your command center for AI agents—a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow. The core value proposition is enabling long-running, complex, large-scale tasks to execute autonomously with minimal human intervention, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off.
In server mode, CleverAgents becomes a collaborative hub where teams can share resources—prompts, actors, actions, and projects—while executing plans in the cloud. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine.
While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top:
-
CleverAgents provides:
- A first-class plan lifecycle (Action/Strategize/Execute/Apply) for breaking down and tracking complex work,
- A project + resource model for grounding tasks in real codebases, databases, documents, and infrastructure,
- A consistent actor abstraction for defining and composing intelligent agents,
- A consistent skill abstraction for anything an agent can execute,
- A sandbox + checkpoint safety model for safe, reversible execution,
- A CLI/TUI/Web UX for controlling and monitoring large multi-step autonomous work.
Glossary (Terms Used Precisely)
- Plan: A tracked lifecycle for a single unit-of-work (which may spawn subplans). Plans follow the same namespace rules as actors.
- Action: A reusable plan template not tied to any project yet. Created via CLI commands (not YAML files). Actions follow the same namespace rules as actors.
- Strategize: Read-only planning phase that produces a strategy and subplan blueprint. All decisions are made during this phase.
- Execute: Phase that performs work in a sandbox; spawns subplans (based on decisions made in Strategize); produces artifacts/diffs.
- Apply: Phase that commits sandbox results into the real project (and records an "applied" plan state).
- Project: A collection of resources + configuration that define "where work happens" and "what can be touched." Created via CLI commands. Can be local (contains local-only and remote resources) or remote (all resources remotely accessible).
- Resource: Anything that can be read/written/queried (files, repo trees, DB endpoints, cloud clusters, documents). Extends the MCP resource concept to support both read and write operations. Each resource defines its own sandbox strategy.
- Skill: A callable capability defined inline in actor YAML configuration as tool nodes. Extends the MCP standard and Agent Skills standard. Skills follow the same naming scheme as plans, actions, etc.
- Actor: Anything conversational; may be a single agent/LLM or an entire graph of actors/tools. Defined via YAML configuration files (LangGraph definitions). Always named using
<namespace>/<name>format. - Session: A user interaction context and conversation thread that can span multiple plans.
- Server: Optional shared service for multi-user storage, permissions, and orchestration. Plans on remote projects can execute on the server.
- Namespace: Scoping mechanism for actors, actions, plans, skills, etc.
local/is reserved for local-only items. User namespaces (<username>/) and organization namespaces (<orgname>/) are stored on the server. Built-in LLM actors use provider namespaces (e.g.,openai/,anthropic/). - Decision: A recorded choice point made during Strategize that affects downstream work. Decisions form a tree structure that enables correction and replay.
- ULID: Universally Unique Lexicographically Sortable Identifier. Preferred over UUID for plan and decision IDs due to time-sortability.
CLI Commands
Command Synopsis
agents|cleveragents [--data-dir PATH] [--config-path PATH] [--help] [--version]
[--install-completion [SHELL]] [--show-completion [SHELL]]
<command> [args]
agents version
agents info
agents diagnostics
agents init [--yes]
agents session create [--name NAME] [--actor ACTOR] [--metadata KEY=VALUE ...]
agents session list [--format table|json]
agents session show <SESSION_ID|NAME>
agents session delete <SESSION_ID|NAME> [--yes]
agents session export <SESSION_ID|NAME> --output FILE
agents session import --input FILE [--name NAME]
agents session tell "<prompt>" [--session SESSION_ID|NAME] [--actor ACTOR] [--stream]
agents project create --name/-n NAME [--description/-d TEXT] [--tag/-t TAG ...]
agents project add-resource --project/-p PROJECT --name/-n NAME --type/-t TYPE --location/-l LOCATION
--sandbox-strategy/-s STRATEGY [--read-only] [--metadata/-m KEY=VALUE ...]
agents project remove-resource --project/-p PROJECT --name/-n NAME [--force/-f] [--yes]
agents project list [--namespace/-n NS] [--tag/-t TAG] [--format table|json]
agents project show <NAME> [--format rich|json]
agents project set-validation --project/-p PROJECT [--resource NAME]
[--test-command CMD] [--lint-command CMD]
[--type-check-command CMD] [--build-command CMD]
[--timeout SECONDS] [--clear]
agents project delete <NAME> [--force/-f] [--yes]
agents project context set --project PROJECT
[--view strategize|execute|apply|default]
[--include-resource NAME ...]
[--exclude-resource NAME ...]
[--include-path GLOB ...]
[--exclude-path GLOB ...]
[--hot-max-tokens N]
[--warm-max-decisions N]
[--cold-max-decisions N]
[--query-limit N]
[--max-file-size BYTES]
[--max-total-size BYTES]
[--summarize/--no-summarize]
[--summary-max-tokens N]
[--clear]
agents project context show --project PROJECT [--view strategize|execute|apply|default]
[--format table|json]
agents actor run --config/-c FILE... --prompt/-p TEXT [--output/-o FILE]
[--verbose/-v] [--unsafe/-u] [--context NAME]
[--context-dir PATH] [--load-context FILE]
[--temperature/-t FLOAT] [--allow-rxpy-in-run-mode]
agents actor add <NAME> --config/-c FILE [--unsafe] [--set-default] [--option/-o key=value ...]
agents actor update <NAME> [--config/-c FILE] [--unsafe|--safe] [--set-default]
[--option/-o key=value ...]
agents actor remove <NAME>
agents actor list
agents actor show <NAME>
agents actor set-default <NAME>
agents actor context add --name NAME <PATHS...> [-r/--recursive]
agents actor context load --name NAME <PATHS...> [-r/--recursive]
agents actor context rm --name NAME <PATHS...>
agents actor context list [NAME] [--format table|json]
agents actor context show --name NAME [PATH]
agents actor context export --name NAME --output FILE
agents actor context import --name NAME --input FILE
agents actor context delete --name NAME [--yes]
agents actor context clear --name NAME [--yes]
agents plan list [--phase PHASE] [--state STATE] [--project PROJECT]
[--action ACTION] [--format table|json]
agents plan use <ACTION_NAME> --project/-p PROJECT [--project/-p PROJECT ...]
[--arg/-a name=value ...]
[--automation-level manual|review|auto]
[--safety-profile NAME]
[--require-sandbox/--no-require-sandbox]
[--require-checkpoints/--no-require-checkpoints]
[--require-apply-approval/--no-require-apply-approval]
[--allow-skill-category NAME ...]
[--deny-skill-category NAME ...]
agents plan execute [PLAN_ID]
agents plan apply <PLAN_ID> [--yes]
agents plan status [PLAN_ID]
agents plan cancel <PLAN_ID> [--reason/-r TEXT]
agents plan tree [PLAN_ID] [--format tree|json|flat] [--show-superseded]
agents plan explain <DECISION_ID> [--show-context] [--show-reasoning]
agents plan correct <DECISION_ID> --mode revert|append --guidance/-g TEXT
[--guidance-file/-f PATH|-] [--dry-run] [--yes]
agents plan diff --plan <PLAN_ID>
agents plan diff --correction <CORRECTION_ATTEMPT_ID>
agents plan artifacts <PLAN_ID>
agents plan prompt <PLAN_ID> "<GUIDANCE>"
agents plan resume <PLAN_ID>
agents plan checkpoint <PLAN_ID> [--label TEXT]
agents plan rollback <PLAN_ID> <CHECKPOINT_ID> [--yes]
agents action create <NAME>
--strategy-actor/-s ACTOR
--execution-actor/-e ACTOR
--definition-of-done/-d TEXT
[--description TEXT]
[--long-description TEXT]
[--arg/-a spec ...]
[--reusable/--no-reusable]
[--read-only]
[--tag/-t TAG ...]
[--available]
[--estimation-actor ACTOR]
[--safety-profile NAME]
[--require-sandbox/--no-require-sandbox]
[--require-checkpoints/--no-require-checkpoints]
[--require-apply-approval/--no-require-apply-approval]
[--allow-skill-category NAME ...]
[--deny-skill-category NAME ...]
agents action list [--namespace/-n NS] [--state/-s STATE] [--available]
agents action show <ACTION_ID|NAME>
agents action available <ACTION_ID|NAME>
agents action archive <ACTION_ID|NAME>
agents config set <key> <value>
agents config get <key>
agents config list
agents providers list
Command Reference
Global Options
Purpose Configure global state locations and shell integration for every command.
Arguments
--data-dir PATH: Overrides the global data directory (database, caches, sessions, logs). When omitted, the default data location is used.--config-path PATH: Overrides the global configuration file path. When omitted, the default config path is used.--help,-h: Print help for the current command.--version,-V: Print the version and exit.--install-completion [SHELL]: Install shell completion for the given shell.--show-completion [SHELL]: Show the completion script for the given shell.
Example
agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info
Example Output
<span style="color: cyan; font-weight: 600;">CleverAgents</span> 1.0.0
<span style="color: blue;">Data Dir:</span> /srv/cleveragents
<span style="color: blue;">Config:</span> /srv/cleveragents/config.toml
<span style="color: magenta;">Default Actor:</span> local/orchestrator
<span style="color: green;">Status:</span> ready
agents version
Purpose Print the current CLI version.
Arguments None.
Example
agents version
Example Output
<span style="color: cyan; font-weight: 600;">CleverAgents</span> version <span style="font-weight: 600;">1.0.0</span>
agents info
Purpose Show configuration and runtime information useful for debugging or support.
Arguments None.
Example
agents info
Example Output
<span style="color: cyan; font-weight: 600;">CleverAgents Environment</span>
<span style="color: blue;">Data Dir:</span> /home/alex/.cleveragents
<span style="color: blue;">Config:</span> /home/alex/.cleveragents/config.toml
<span style="color: magenta;">Default Actor:</span> local/orchestrator
<span style="color: magenta;">Automation Level:</span> review
<span style="color: green;">Database:</span> sqlite:///home/alex/.cleveragents/cleveragents.db
<span style="color: yellow;">Server Mode:</span> disabled
agents diagnostics
Purpose Run health checks for configuration, providers, and filesystem permissions.
Arguments None.
Example
agents diagnostics
Example Output
<span style="color: cyan; font-weight: 600;">Diagnostics</span>
<span style="color: green;">OK</span> Config file readable
<span style="color: green;">OK</span> Database writable
<span style="color: yellow;">WARN</span> OPENAI_API_KEY not set
<span style="color: green;">OK</span> Anthropic key present
<span style="color: green;">OK</span> Data dir has 2.1 GB free
agents init
Purpose Initialize or reset the global CleverAgents environment. This wipes any existing data and re-creates the global config and database.
Arguments
--yes: Skip the confirmation prompt and proceed with the wipe.
Example
agents init
Example Output
<span style="color: yellow; font-weight: 600;">Warning</span>: This will remove all data in /home/alex/.cleveragents
Continue? [y/N]: y
<span style="color: green;">OK</span> Created config: /home/alex/.cleveragents/config.toml
<span style="color: green;">OK</span> Initialized database: /home/alex/.cleveragents/cleveragents.db
<span style="color: green;">OK</span> Ready for use
agents session
Purpose Manage interactive sessions that hold a conversation history and orchestrator state.
agents session create
Purpose Create a new session for interactive work.
Arguments
--name NAME: Human-friendly session name.--actor ACTOR: Orchestrator actor to use forsession tell(defaults to configured default).--metadata KEY=VALUE: Attach metadata to the session (repeatable).
Example
agents session create --name weekly-planning --actor local/orchestrator --metadata team=platform
Example Output
<span style="color: green;">OK</span> Session created: <span style="font-weight: 600;">weekly-planning</span>
<span style="color: blue;">Session ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
<span style="color: magenta;">Actor:</span> local/orchestrator
agents session list
Purpose List sessions available on the local machine.
Arguments
--format table|json: Output format.
Example
agents session list --format table
Example Output
<span style="color: cyan; font-weight: 600;">Sessions</span>
ID Name Actor Updated
01HXM2A6 weekly-planning local/orchestrator 2026-02-08 12:44
01HXM1F2 refactor-sprint local/orchestrator 2026-02-07 18:11
agents session show
Purpose Show details and recent messages for a session.
Arguments
<SESSION_ID|NAME>: The session identifier or name.
Example
agents session show weekly-planning
Example Output
<span style="color: cyan; font-weight: 600;">Session</span> weekly-planning
<span style="color: blue;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
<span style="color: magenta;">Actor:</span> local/orchestrator
<span style="color: yellow;">Messages:</span> 6
agents session delete
Purpose Delete a session and its stored conversation history.
Arguments
<SESSION_ID|NAME>: The session identifier or name.--yes: Skip the confirmation prompt.
Example
agents session delete weekly-planning
Example Output
Delete session weekly-planning? [y/N]: y
<span style="color: green;">OK</span> Session deleted
agents session export
Purpose Export a session as a portable JSON file.
Arguments
<SESSION_ID|NAME>: The session identifier or name.--output FILE: Output file path.
Example
agents session export weekly-planning --output /tmp/weekly-planning.json
Example Output
<span style="color: green;">OK</span> Exported session to /tmp/weekly-planning.json
agents session import
Purpose Import a session JSON file.
Arguments
--input FILE: Input JSON file.--name NAME: Optional override for the session name.
Example
agents session import --input /tmp/weekly-planning.json --name weekly-planning-restored
Example Output
<span style="color: green;">OK</span> Session imported: weekly-planning-restored
<span style="color: blue;">Session ID:</span> 01HXM3D3B2W4CQYQ3P4ZB8A5T1
agents session tell
Purpose Send a natural-language request to the orchestrator. The orchestrator can create actions, plans, or project changes by issuing the necessary CleverAgents commands under the hood.
Arguments
"<prompt>": Instruction text.--session SESSION_ID|NAME: Session to use (defaults to the most recent session).--actor ACTOR: Override the session actor for this request.--stream: Stream progress as the orchestrator works.
Example
agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
--session weekly-planning
Example Output
<span style="color: cyan; font-weight: 600;">Orchestrator</span> local/orchestrator
<span style="color: blue;">Plan:</span> Create action + update project
<span style="color: magenta;">Running:</span>
- agents action create local/refresh-locks --strategy-actor local/planner --execution-actor local/executor \
--definition-of-done "Locks updated; tests pass"
- agents project add-resource --project local/platform --name repo --type git_repository \
--location /repos/platform --sandbox-strategy git_worktree
<span style="color: green;">OK</span> Completed 2 commands
agents project
Purpose Manage projects and their resources.
agents project create
Purpose Create a new project record.
Arguments
--name/-n NAME: Namespaced project name.--description/-d TEXT: Optional description.--tag/-t TAG: Project tag (repeatable).
Example
agents project create --name local/api-service --description "Backend API" --tag python --tag backend
Example Output
<span style="color: green;">OK</span> Created project: local/api-service
<span style="color: blue;">Project ID:</span> 01HXM4T08Y0N5R9VZ4QX4BPTZ1
<span style="color: magenta;">Tags:</span> python, backend
agents project add-resource
Purpose Attach a resource to a project with a specific sandbox strategy.
Arguments
--project/-p PROJECT: Project name.--name/-n NAME: Resource name.--type/-t TYPE: Resource type (git_repository, filesystem, database, api_endpoint, cloud_infra, document, repo_tree).--location/-l LOCATION: Path, URL, or connection string.--sandbox-strategy/-s STRATEGY: Sandbox strategy (git_worktree, copy_on_write, overlay, transaction_rollback, terraform_state, none).--read-only: Marks the resource as read-only.--metadata/-m KEY=VALUE: Resource metadata (repeatable).
Example
agents project add-resource --project local/api-service --name repo --type git_repository \
--location /repos/api --sandbox-strategy git_worktree --metadata branch=main
Example Output
<span style="color: green;">OK</span> Added resource repo to project local/api-service
<span style="color: blue;">Type:</span> git_repository
<span style="color: blue;">Sandbox:</span> git_worktree
agents project remove-resource
Purpose Remove a resource from a project.
Arguments
--project/-p PROJECT: Project name.--name/-n NAME: Resource name.--force/-f: Skip additional checks.--yes: Skip confirmation prompt.
Example
agents project remove-resource --project local/api-service --name repo
Example Output
Remove resource repo from local/api-service? [y/N]: y
<span style="color: green;">OK</span> Resource removed
agents project list
Purpose List projects with optional filters.
Arguments
--namespace/-n NS: Filter by namespace.--tag/-t TAG: Filter by tag.--format table|json: Output format.
Example
agents project list --format table
Example Output
<span style="color: cyan; font-weight: 600;">Projects</span>
ID Name Resources Tags Remote
01HXM4T0 local/api-service 2 python, backend No
01HXM4B9 local/docs 1 docs No
agents project show
Purpose Show full project details.
Arguments
<NAME>: Project name.--format rich|json: Output format.
Example
agents project show local/api-service
Example Output
<span style="color: cyan; font-weight: 600;">Project</span> local/api-service
<span style="color: blue;">ID:</span> 01HXM4T08Y0N5R9VZ4QX4BPTZ1
<span style="color: magenta;">Tags:</span> python, backend
<span style="color: yellow;">Resources:</span> 2
<span style="color: cyan; font-weight: 600;">Resources</span>
Name Type Location Sandbox
repo git_repository /repos/api git_worktree
db database postgresql:// transaction_rollback
agents project set-validation
Purpose Set or update validation commands for a project or a specific resource.
Arguments
--project/-p PROJECT: Project name.--resource NAME: Optional resource name.--test-command CMD: Test command.--lint-command CMD: Lint command.--type-check-command CMD: Type-check command.--build-command CMD: Build command.--timeout SECONDS: Timeout per command.--clear: Clear validation config.
Example
agents project set-validation --project local/api-service --resource repo \
--test-command "pytest" --lint-command "ruff check ." --type-check-command "pyright"
Example Output
<span style="color: green;">OK</span> Validation updated for local/api-service (resource: repo)
<span style="color: blue;">Test:</span> pytest
<span style="color: blue;">Lint:</span> ruff check .
<span style="color: blue;">Type Check:</span> pyright
agents project delete
Purpose Delete a project and all associated resources.
Arguments
<NAME>: Project name.--force/-f: Delete even if active plans exist.--yes: Skip confirmation prompt.
Example
agents project delete local/docs
Example Output
Delete project local/docs? This cannot be undone. [y/N]: y
<span style="color: green;">OK</span> Project deleted
agents project context
Purpose Manage context policies for the hot/warm/cold tiers and per-view context selection.
agents project context set
Purpose Set the context policy for a project and (optionally) a specific view.
Arguments
--project PROJECT: Project name.--view strategize|execute|apply|default: Which view this policy applies to.--include-resource NAME: Resource allowlist (repeatable).--exclude-resource NAME: Resource denylist (repeatable).--include-path GLOB: Path allowlist (repeatable).--exclude-path GLOB: Path denylist (repeatable).--hot-max-tokens N: Maximum token budget for hot context. This is a soft cap and may be null. The actor/LLM hard limit can be lower; the effective hot context is the lesser of the two.--warm-max-decisions N: Maximum number of decisions kept in warm context.--cold-max-decisions N: Maximum number of decisions kept in cold context.--query-limit N: Max number of retrieval results per query.--max-file-size BYTES: Max file size included in context.--max-total-size BYTES: Max total size across included files.--summarize/--no-summarize: Enable or disable summarization for large context segments.--summary-max-tokens N: Token limit for generated summaries.--clear: Clear the policy for the selected view.
Example
agents project context set --project local/api-service --view strategize \
--include-resource repo --exclude-path "**/node_modules/**" \
--hot-max-tokens 12000 --warm-max-decisions 50 --cold-max-decisions 200 \
--summarize --summary-max-tokens 800
Example Output
<span style="color: green;">OK</span> Context policy updated for local/api-service (view: strategize)
<span style="color: blue;">Hot Max Tokens:</span> 12000 (soft cap)
<span style="color: blue;">Warm Max Decisions:</span> 50
<span style="color: blue;">Cold Max Decisions:</span> 200
<span style="color: magenta;">Summarize:</span> enabled (max 800 tokens)
agents project context show
Purpose Show the active context policy for a project.
Arguments
--project PROJECT: Project name.--view strategize|execute|apply|default: View to display.--format table|json: Output format.
Example
agents project context show --project local/api-service --view strategize
Example Output
<span style="color: cyan; font-weight: 600;">Context Policy</span> local/api-service (strategize)
Include Resources: repo
Exclude Paths: **/node_modules/**
Hot Max Tokens: 12000 (soft cap)
Warm Max Decisions: 50
Cold Max Decisions: 200
Summarize: enabled (max 800 tokens)
agents actor
Purpose Manage actors and run actor configurations directly.
agents actor run
Purpose Run an actor configuration in isolation with simple, manual context.
Arguments
--config/-c FILE...: YAML or JSON config files.--prompt/-p TEXT: Prompt to send.--output/-o FILE: Output file path.--verbose/-v: Increase verbosity (repeatable).--unsafe/-u: Allow unsafe configs.--context NAME: Named actor context to attach.--context-dir PATH: Context storage location.--load-context FILE: Load context from JSON.--temperature/-t FLOAT: Override temperature.--allow-rxpy-in-run-mode: Allow RxPy routes in run mode.
Example
agents actor run -c ./actors/code_reader.yaml -p "Summarize the README" --context docs
Example Output
<span style="color: cyan; font-weight: 600;">Actor</span> local/code_reader
<span style="color: blue;">Context:</span> docs
<span style="color: green;">OK</span> Summary written to stdout
agents actor add
Purpose Add a new actor configuration.
Arguments
<NAME>: Actor name.--config/-c FILE: Actor config file.--unsafe: Mark actor as unsafe.--set-default: Set as default actor.--option/-o key=value: Option override (repeatable).
Example
agents actor add local/reviewer --config ./actors/reviewer.yaml --set-default
Example Output
<span style="color: green;">OK</span> Actor added: local/reviewer
<span style="color: magenta;">Default Actor:</span> local/reviewer
agents actor update
Purpose Update an existing actor configuration.
Arguments
<NAME>: Actor name.--config/-c FILE: Updated config file.--unsafe: Mark actor as unsafe.--safe: Mark actor as safe.--set-default: Set as default actor.--option/-o key=value: Option override (repeatable).
Example
agents actor update local/reviewer --option temperature=0.2
Example Output
<span style="color: green;">OK</span> Actor updated: local/reviewer
agents actor remove
Purpose Remove a custom actor.
Arguments
<NAME>: Actor name.
Example
agents actor remove local/reviewer
Example Output
<span style="color: green;">OK</span> Actor removed: local/reviewer
agents actor list
Purpose List all actors.
Arguments None.
Example
agents actor list
Example Output
<span style="color: cyan; font-weight: 600;">Actors</span>
Name Provider Model Default Unsafe
local/reviewer openai gpt-4 Yes No
openai/gpt-4 openai gpt-4 No No
agents actor show
Purpose Show details for a single actor.
Arguments
<NAME>: Actor name.
Example
agents actor show local/reviewer
Example Output
<span style="color: cyan; font-weight: 600;">Actor</span> local/reviewer
<span style="color: blue;">Provider:</span> openai
<span style="color: blue;">Model:</span> gpt-4
<span style="color: magenta;">Default:</span> yes
<span style="color: yellow;">Unsafe:</span> no
agents actor set-default
Purpose Set the default actor.
Arguments
<NAME>: Actor name.
Example
agents actor set-default local/reviewer
Example Output
<span style="color: green;">OK</span> Default actor set to local/reviewer
agents actor context
Purpose Manage manual context for actor runs. These commands mirror the legacy context behavior but are scoped to an actor context name.
agents actor context add
Purpose Add files or directories to an actor context.
Arguments
--name NAME: Context name.<PATHS...>: Files or directories to add.-r/--recursive: Add directories recursively.
Example
agents actor context add --name docs README.md docs/
Example Output
<span style="color: green;">OK</span> Added 12 item(s) to context docs
agents actor context load
Purpose
Alias for context add.
Arguments
Same as context add.
Example
agents actor context load --name docs README.md
Example Output
<span style="color: green;">OK</span> Added 1 item(s) to context docs
agents actor context rm
Purpose Remove files or directories from an actor context.
Arguments
--name NAME: Context name.<PATHS...>: Paths to remove.
Example
agents actor context rm --name docs README.md
Example Output
<span style="color: green;">OK</span> Removed 1 item(s) from context docs
agents actor context list
Purpose List files stored in an actor context.
Arguments
[NAME]: Context name (optional to list all contexts).--format table|json: Output format.
Example
agents actor context list docs
Example Output
<span style="color: cyan; font-weight: 600;">Context</span> docs
README.md
docs/overview.md
docs/cli.md
agents actor context show
Purpose Show content of a file in an actor context.
Arguments
--name NAME: Context name.[PATH]: File path (optional for summary).
Example
agents actor context show --name docs README.md
Example Output
<span style="color: cyan; font-weight: 600;">Content</span> README.md
<span style="opacity: 0.7;"># CleverAgents</span>
...
agents actor context export
Purpose Export a context as JSON.
Arguments
--name NAME: Context name.--output FILE: Output file path.
Example
agents actor context export --name docs --output /tmp/docs-context.json
Example Output
<span style="color: green;">OK</span> Exported context docs to /tmp/docs-context.json
agents actor context import
Purpose Import a context from JSON.
Arguments
--name NAME: Context name.--input FILE: Input JSON file.
Example
agents actor context import --name docs --input /tmp/docs-context.json
Example Output
<span style="color: green;">OK</span> Imported context docs
agents actor context delete
Purpose Delete an entire context.
Arguments
--name NAME: Context name.--yes: Skip confirmation.
Example
agents actor context delete --name docs
Example Output
Delete context docs? [y/N]: y
<span style="color: green;">OK</span> Context deleted
agents actor context clear
Purpose Clear all files from a context but keep the context itself.
Arguments
--name NAME: Context name.--yes: Skip confirmation.
Example
agents actor context clear --name docs
Example Output
Clear context docs? [y/N]: y
<span style="color: green;">OK</span> Context cleared
agents plan
Purpose Manage plans through the Action -> Strategize -> Execute -> Apply lifecycle.
agents plan list
Purpose List plans with optional filtering.
Arguments
--phase PHASE: Filter by phase.--state STATE: Filter by processing state.--project PROJECT: Filter by project.--action ACTION: Filter by action name.--format table|json: Output format.
Example
agents plan list --phase execute --format table
Example Output
<span style="color: cyan; font-weight: 600;">Plans</span>
ID Phase State Action Project
01HXM7A9 execute processing local/code-coverage local/api-service
agents plan use
Purpose Apply an action to one or more projects and start the Strategize phase.
Arguments
<ACTION_NAME>: Action name.--project/-p PROJECT: Project name (repeatable).--arg/-a name=value: Action argument (repeatable).--automation-level manual|review|auto: Automation level.--safety-profile NAME: Named safety profile.--require-sandbox/--no-require-sandbox: Enforce sandboxing.--require-checkpoints/--no-require-checkpoints: Enforce checkpoints.--require-apply-approval/--no-require-apply-approval: Require human approval before apply.--allow-skill-category NAME: Allow skill categories (repeatable).--deny-skill-category NAME: Deny skill categories (repeatable).
Example
agents plan use local/code-coverage --project local/api-service \
--arg target_coverage_percent=85 --automation-level review
Example Output
<span style="color: green;">OK</span> Plan created: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
<span style="color: blue;">Phase:</span> strategize
<span style="color: magenta;">Action:</span> local/code-coverage
agents plan execute
Purpose Start or resume execution for a plan.
Arguments
[PLAN_ID]: Plan ID (optional if the most recent plan is unambiguous).
Example
agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Example Output
<span style="color: green;">OK</span> Execution started
<span style="color: blue;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J
<span style="color: yellow;">Sandbox:</span> git_worktree
agents plan apply
Purpose Apply sandboxed changes to real resources.
Arguments
<PLAN_ID>: Plan ID.--yes: Skip confirmation.
Example
agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Example Output
Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
<span style="color: green;">OK</span> Applied changes
<span style="color: blue;">Artifacts:</span> 6 files updated
agents plan status
Purpose Show detailed status for a plan.
Arguments
[PLAN_ID]: Plan ID (optional if the most recent plan is unambiguous).
Example
agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Example Output
<span style="color: cyan; font-weight: 600;">Plan</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J
<span style="color: blue;">Phase:</span> execute
<span style="color: blue;">State:</span> processing
<span style="color: magenta;">Action:</span> local/code-coverage
<span style="color: yellow;">Project:</span> local/api-service
agents plan cancel
Purpose Cancel a plan that is not terminal.
Arguments
<PLAN_ID>: Plan ID.--reason/-r TEXT: Optional reason.
Example
agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
Example Output
<span style="color: yellow;">Cancelled</span> Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J
<span style="opacity: 0.7;">Reason: blocked on credentials</span>
agents plan tree
Purpose Render the decision tree for a plan.
Arguments
[PLAN_ID]: Plan ID (optional if a current plan exists).--format tree|json|flat: Output format.--show-superseded: Include superseded decisions.
Example
agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Example Output
<span style="color: cyan; font-weight: 600;">Decision Tree</span>
- <span style="color: white;">[prompt_definition]</span> "Increase test coverage to 85%"
- <span style="color: blue;">[strategy_choice]</span> "Prioritize auth and payments"
- <span style="color: green;">[subplan_spawn]</span> "Write auth tests" -> 01HXM9F1A
- <span style="color: green;">[subplan_spawn]</span> "Write payment tests" -> 01HXM9F2B
agents plan explain
Purpose Show a detailed explanation for a decision.
Arguments
<DECISION_ID>: Decision ID.--show-context: Include the context snapshot.--show-reasoning: Include raw model reasoning if available.
Example
agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
Example Output
<span style="color: cyan; font-weight: 600;">Decision</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
<span style="color: blue;">Type:</span> strategy_choice
<span style="color: blue;">Question:</span> Which modules should be prioritized?
<span style="color: green;">Chosen:</span> Auth and payments
<span style="color: yellow;">Confidence:</span> 0.82
<span style="color: magenta;">Rationale:</span> High risk modules with low coverage
agents plan correct
Purpose Correct a decision either by reverting and re-executing or by appending a fix.
Arguments
<DECISION_ID>: Decision ID.--mode revert|append: Correction mode.--guidance/-g TEXT: Guidance text.--guidance-file/-f PATH|-: Guidance file (use-for stdin).--dry-run: Show impact without executing.--yes: Skip confirmation for revert mode.
Example
agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert \
--guidance "Prioritize payments first" --yes
Example Output
<span style="color: blue;">Impact:</span> 3 decisions, 2 subplans, 5 artifacts
<span style="color: yellow;">Re-executing...</span>
<span style="color: green;">OK</span> Correction applied
<span style="color: blue;">New Decision:</span> 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
agents plan diff
Purpose Show diffs for a plan or a correction attempt.
Arguments
--plan <PLAN_ID>: Show diff for a plan.--correction <CORRECTION_ATTEMPT_ID>: Compare correction outputs.
Example
agents plan diff --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Example Output
<span style="color: cyan; font-weight: 600;">Diff</span> local/api-service
<span style="color: red;">- import jwt</span>
<span style="color: green;">+ import sessionlib</span>
<span style="color: red;">- def validate_token(...)</span>
<span style="color: green;">+ def validate_session(...)</span>
agents plan artifacts
Purpose List artifacts produced by a plan.
Arguments
<PLAN_ID>: Plan ID.
Example
agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Example Output
<span style="color: cyan; font-weight: 600;">Artifacts</span>
path type size
src/auth/session.py write 2.1 KB
tests/test_session.py write 4.7 KB
agents plan prompt
Purpose Provide additional guidance to a plan, typically when it is errored or awaiting input.
Arguments
<PLAN_ID>: Plan ID."<GUIDANCE>": Guidance text.
Example
agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
Example Output
<span style="color: green;">OK</span> Guidance added
<span style="color: blue;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J
agents plan resume
Purpose Resume an interrupted plan from its last checkpoint.
Arguments
<PLAN_ID>: Plan ID.
Example
agents plan resume 01HXM8C2ZK4Q7C2B3F2R4VYV6J
Example Output
<span style="color: green;">OK</span> Resumed plan
<span style="color: blue;">Checkpoint:</span> cp_01HXM8C2
agents plan checkpoint
Purpose Create an explicit checkpoint in the plan sandbox.
Arguments
<PLAN_ID>: Plan ID.--label TEXT: Optional label.
Example
agents plan checkpoint 01HXM8C2ZK4Q7C2B3F2R4VYV6J --label "before auth refactor"
Example Output
<span style="color: green;">OK</span> Checkpoint created
<span style="color: blue;">ID:</span> cp_01HXM8C2
agents plan rollback
Purpose Rollback a plan sandbox to a checkpoint.
Arguments
<PLAN_ID>: Plan ID.<CHECKPOINT_ID>: Checkpoint ID.--yes: Skip confirmation.
Example
agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
Example Output
Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
<span style="color: green;">OK</span> Rollback complete
agents action
Purpose Manage reusable actions.
agents action create
Purpose Create a new action template.
Arguments
<NAME>: Namespaced action name.--strategy-actor/-s ACTOR: Strategize actor.--execution-actor/-e ACTOR: Execution actor.--definition-of-done/-d TEXT: Completion criteria.--description TEXT: Short description.--long-description TEXT: Long description.--arg/-a spec: Argument definition (repeatable).--reusable/--no-reusable: Keep action after use.--read-only: Read-only action.--tag/-t TAG: Tags (repeatable).--available: Make action available immediately.--estimation-actor ACTOR: Optional estimation actor.--safety-profile NAME: Named safety profile.--require-sandbox/--no-require-sandbox: Enforce sandboxing.--require-checkpoints/--no-require-checkpoints: Enforce checkpoints.--require-apply-approval/--no-require-apply-approval: Require approval before apply.--allow-skill-category NAME: Allow skill categories.--deny-skill-category NAME: Deny skill categories.
Example
agents action create local/code-coverage \
--strategy-actor local/strategist \
--execution-actor local/executor \
--definition-of-done "Coverage reaches 85%" \
--arg "target_coverage_percent:int:required:Target coverage percentage" \
--available
Example Output
<span style="color: green;">OK</span> Action created: local/code-coverage
<span style="color: blue;">State:</span> available
agents action list
Purpose List actions with optional filters.
Arguments
--namespace/-n NS: Filter by namespace.--state/-s STATE: Filter by state.--available: Show only available actions.
Example
agents action list --available
Example Output
<span style="color: cyan; font-weight: 600;">Actions</span>
Name State Strategy Actor Execution Actor
local/code-coverage available local/strategist local/executor
agents action show
Purpose Show details for an action.
Arguments
<ACTION_ID|NAME>: Action ID or name.
Example
agents action show local/code-coverage
Example Output
<span style="color: cyan; font-weight: 600;">Action</span> local/code-coverage
<span style="color: blue;">State:</span> available
<span style="color: blue;">Strategy Actor:</span> local/strategist
<span style="color: blue;">Execution Actor:</span> local/executor
<span style="color: magenta;">Definition of Done:</span> Coverage reaches 85%
agents action available
Purpose Mark a draft action as available.
Arguments
<ACTION_ID|NAME>: Action ID or name.
Example
agents action available 01HXMAY3D1JQ0C3G1H0Q7B2W7M
Example Output
<span style="color: green;">OK</span> Action is now available
agents action archive
Purpose Archive an action.
Arguments
<ACTION_ID|NAME>: Action ID or name.
Example
agents action archive local/old-action
Example Output
<span style="color: yellow;">Archived</span> local/old-action
agents config
Purpose Manage global configuration values.
agents config set
Purpose Set a configuration key.
Arguments
<key>: automation-level, default-actor, log-level.<value>: Value to set.
Example
agents config set automation-level review
Example Output
<span style="color: green;">OK</span> automation-level set to review
agents config get
Purpose Get a configuration value.
Arguments
<key>: Key to read.
Example
agents config get default-actor
Example Output
<span style="color: blue;">default-actor</span> local/orchestrator (source: config)
agents config list
Purpose List all configuration values.
Arguments None.
Example
agents config list
Example Output
<span style="color: cyan; font-weight: 600;">Config</span>
automation-level review source=config
default-actor local/orchestrator source=config
log-level INFO source=default
agents providers
Purpose Inspect provider availability.
agents providers list
Purpose List available providers and whether credentials are configured.
Arguments None.
Example
agents providers list
Example Output
<span style="color: cyan; font-weight: 600;">Providers</span>
openai <span style="color: yellow;">missing key</span>
anthropic <span style="color: green;">configured</span>
openrouter <span style="color: green;">configured</span>
google <span style="color: yellow;">missing key</span>
Components
Plan
A plan is the fundamental unit of orchestration and traceability.
Plan Lifecycle Phases
A plan always moves through the following phases, in order:
Action → Strategize → Execute → Apply → Applied (terminal)
In this spec:
- Strategize is the phase name (the output is a strategy).
- Execute is the phase name (the output is a changeset).
- Apply is the phase name (the output is an applied change).
- Applied is the resulting terminal state after Apply succeeds.
This four-stage model is explicitly called out as the new architecture replacing a prior linear pipeline.
Phase Transition Verbs (CLI / UX Contract)
Verbs that trigger phase transitions. CleverAgents should standardize these verbs as the public API (CLI, TUI, web):
| Current Phase | Command Verb | Next Phase |
|---|---|---|
| (none) | create |
Action |
| Action | use |
Strategize |
| Strategize | execute |
Execute |
| Execute | apply |
Applied |
Important behavioral rule: CleverAgents must support multiple "automation levels" that can automatically progress through these verbs without the user explicitly issuing them, but the verbs remain the conceptual contract.
Plan States (Per Phase)
A plan's phase indicates "what step of the lifecycle it is in." Separately, the plan has a processing state indicating "what is happening right now."
Recommended state model:
-
Action phase states
available(action exists and can be used)draft(action is being authored/edited)archived(soft-deleted or hidden, optional)
-
Strategize / Execute / Apply phase states
queued(waiting for compute/worker)processing(currently running)errored(failed; includes error metadata)complete(finished successfully)cancelled(user/system cancelled; safe terminal for that phase)
Plan Identity and Traceability
Every plan should have:
- plan_id: Unique, immutable ID (UUID or ULID).
- parent_plan_id: Nullable; present for subplans.
- root_plan_id: The top-most plan in the tree.
- attempt: An integer attempt counter that increments when re-running a phase (e.g., re-executing after a fix).
- created_at / updated_at / completed_at timestamps.
- created_by (user identity / session identity).
Plan Hierarchy (Subplans) and Parallelism
A single plan should usually represent the smallest "complete" unit of work (similar to what would fit in one git commit). However:
- Plans are hierarchical.
- Decisions about subplans are made during Strategize (as
subplan_spawndecision types). - Subplans are actually spawned during Execute (based on those decisions).
- Subplans can run in parallel or sequentially.
- The parent plan is responsible for merging results.
This is core to the long-term objective: tackling large tasks while only recomputing parts of the decision tree when corrected.
Hierarchical Decomposition for Scale
When handling massive tasks (e.g., converting Firefox to Rust), the system uses hierarchical decomposition:
-
Root Level: High-level architectural decisions
- "Convert Firefox Renderer to Rust"
- Decision: "Start with leaf modules, work inward"
- Context: Module dependency graph (2,847 modules)
-
Subsystem Level: Major component decisions
- "Phase 1: Convert utility libraries (no external deps)"
- Each subsystem gets its own bounded context
-
Module Level: Individual module conversions
- "Convert string_utils module"
- Context: Only the 47 functions and 12 dependent files
- Decision: "Use Rust's String type"
-
File Level: Specific file changes
- Actual code transformations
- Minimal context needed
At each level, only the relevant context is loaded. The persistent decision graph means we can always reconstruct why we're converting a particular module and what constraints apply from higher-level decisions.
Subplan Spawning Mechanism
In the actor definition for the execution actor, there are nodes that act as skills whose purpose is to generate subplans. The execution actor can call these skills to trigger subplans.
# Example: Execution actor with subplan spawning capability
actors:
code_executor:
type: graph
routes:
execute_workflow:
nodes:
- name: spawn_test_subplan
type: tool
config:
tools:
- name: create_subplan
code: |
# This skill creates a subplan
subplan = context.spawn_subplan(
action="local/write-tests",
target_files=input_data.files_to_test
)
result = subplan.id
Subplan Execution Modes
- Sequential: Subplans execute one after another. If one fails, subsequent subplans are not started.
- Parallel: Subplans execute concurrently. If one fails, others can continue.
Subplan Failure Handling
- Parallel execution: Other parallel subplans continue even if one fails.
- Sequential execution: Subsequent subplans are not called if a prior one fails.
- Note: An "error" only occurs if an exception is thrown by the application (a bug). Plan failures (e.g., tests don't pass) are handled within the plan's logic, not as application errors.
Result Merging
The way results are merged depends on the resource type:
- Git-compatible resources (source code, text files): Git-style merge
- Databases: Transaction coordination or sequential application
- Other resources: Pluggable merge strategies based on resource type
- Non-mergeable resources: May require sequential execution only
The Plan "Decision Tree" and Visualization
CleverAgents intends to record enough information to render:
- an ASCII tree in the TUI, and
- optionally a GUI tree via visualization tools (D3/Cytoscape) once the data exists.
This implies each plan should persist:
- decisions made,
- the rationale (or at least the prompt/context snapshot that produced it),
- dependencies ("this decision influenced these child plans").
This is required for "correcting plans" (see Behavior section).
Decision Data Model
Relationship Between Plan Description and Decisions
Each plan has a description field (inherited from the action's description, potentially with argument substitutions). This description acts as the primary component of the prompt fed to the strategy actor during the Strategize phase.
Decisions are choices that are NOT explicitly defined by the plan description. They represent the gaps, ambiguities, or implementation details that must be resolved to execute the plan.
For example:
- Plan description: "Increase test coverage to 85%"
- Decisions that emerge:
- "Which modules should be prioritized?" (not specified in description)
- "Should we use mocks or integration tests for the database layer?" (not specified)
- "Should we refactor the auth module to make it more testable, or write tests around it as-is?" (not specified)
Decision Making Based on Autonomy Level
Who makes decisions depends on the plan's automation level:
| Automation Level | Who Makes Decisions |
|---|---|
| Manual | User is prompted for each decision point |
| Review-before-apply | Actor makes decisions automatically during Strategize, user reviews before Apply |
| Full automation | Actor makes all decisions automatically |
When automation allows automatic decisions, the strategy actor uses its best judgment based on context, and records its reasoning in the decision's rationale field.
When user input is required, the system pauses and prompts the user:
Decision required: Which modules should be prioritized for test coverage?
Options identified by the strategy actor:
1. auth module (currently 45% coverage, high risk)
2. payment module (currently 52% coverage, high risk)
3. user module (currently 71% coverage, medium risk)
Your choice (or provide custom guidance): _
The Prompt as the Root Decision
The prompt passed to the strategize actor is itself a decision node in the decision tree—specifically, it's the root decision of type prompt_definition.
This is important because:
-
Every plan has its own prompt: The root plan's prompt comes from the action description + user arguments. Subplan prompts are created by parent plans during their execution.
-
Parent plans create subplan prompts: When a parent plan spawns a subplan, it decides what prompt to give that subplan. This is recorded as a
prompt_definitiondecision in the parent's tree, and becomes the root decision of the child plan's tree. -
Unified correction mechanism: Since the prompt is just another decision, correcting it uses the same
agents plan correctcommand as any other decision.
Plan Tree Example:
├── [prompt_definition] "Increase test coverage to 85%" <- Root decision (correctable)
│ ├── [strategy_choice] "Prioritize auth and payment modules"
│ ├── [subplan_spawn] "Write tests for auth module"
│ │ └── Subplan: auth-tests
│ │ ├── [prompt_definition] "Write unit tests for auth module using mocks" <- Created by parent
│ │ ├── [implementation_choice] "Test login flow first"
│ │ └── ...
│ └── [subplan_spawn] "Write tests for payment module"
│ └── Subplan: payment-tests
│ ├── [prompt_definition] "Write unit tests for payment module" <- Created by parent
│ └── ...
Correcting Decisions (Including Prompts)
All corrections use the same unified command:
agents plan correct <decision_id> --mode=<mode> --guidance "<corrected decision text>"
Parameters:
<decision_id>: The ULID of the decision to correct--mode: Eitherrevert(rollback and re-run) orappend(add fix at end)--guidance: Free-form text specifying what the correct decision should be
Examples:
# Correct a strategy choice
agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=revert \
--guidance "Prioritize the payment module first, not auth, due to upcoming deadline"
# Correct the root prompt to be more specific
agents plan tree <plan_id>
# Shows: [prompt_definition] id=01ARZ3NDEKTSV4RRFFQ69G5FAV "Increase test coverage to 85%"
agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=revert \
--guidance "Increase test coverage to 85%, prioritizing auth and payment modules. Use mocks for database tests, not integration tests."
# Correct a subplan's prompt (originally created by parent plan)
agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW --mode=revert \
--guidance "Write unit tests for auth module, focusing on edge cases for token expiration"
# Append a fix rather than rewriting history
agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=append \
--guidance "The previous approach missed error handling tests - add comprehensive error path coverage"
Note: CLI commands should not require interactive input. The --guidance parameter provides the correction inline. For very long guidance text, use a file:
agents plan correct <decision_id> --mode=revert --guidance-file ./correction.txt
When to correct the prompt vs. a specific decision:
| Situation | Correction Approach |
|---|---|
| Original request was too vague | Correct the prompt_definition decision |
| Strategy actor made a bad choice on a specific question | Correct that specific decision |
| Parent plan gave a subplan a bad prompt | Correct the subplan's prompt_definition |
Because the prompt is part of the decision tree, the system automatically knows that correcting it invalidates all downstream decisions in that plan (and its subplans).
Decisions are only created during the Strategize phase. The decision tree captures what choices were made and why, enabling correction and replay.
Decision Record Structure
Decision:
# Identity
decision_id: ULID # Unique identifier
plan_id: ULID # Parent plan this decision belongs to
parent_decision_id: ULID | null # Parent decision (for tree structure)
sequence_number: int # Order within the plan's decisions
# Classification
decision_type: enum
- prompt_definition # The prompt/description for this plan (root decision)
- strategy_choice # High-level approach decision during Strategize
- implementation_choice # How to implement a specific task
- resource_selection # Which resources to read/modify
- subplan_spawn # Decision to create a subplan (spawned later in Execute)
- tool_invocation # Which skill/tool to use
- error_recovery # How to handle a failure
- validation_response # Response to validation failure
- user_intervention # User provided guidance/correction
# The Decision Itself
question: str # What question was being answered
chosen_option: str # What was decided
alternatives_considered: list[str] # Other options that were evaluated
confidence_score: float | null # 0.0-1.0 if the actor provided confidence
# Context Snapshot (for replay)
context_snapshot:
hot_context_hash: str # Cryptographic hash of the exact context
hot_context_ref: str # Pointer to the full stored snapshot
relevant_resources: list[ResourceRef] # Every file/symbol that influenced this decision
actor_state_ref: str # Complete LangGraph checkpoint
# When the system decides "refactor the authentication module to use async patterns,"
# it permanently records:
# - Which files were examined to make that decision
# - What symbols and dependencies were traced
# - The exact code state that was analyzed
# - The reasoning chain that led to this choice
# - Alternative approaches that were considered but rejected
# Rationale
rationale: str # Why this option was chosen
actor_reasoning: str | null # Raw LLM reasoning if available
# Downstream Impact (populated during Execute phase)
downstream_decision_ids: list[ULID] # Decisions that depend on this one
downstream_plan_ids: list[ULID] # Subplans spawned because of this decision
artifacts_produced: list[ArtifactRef] # Files/outputs created under this decision
# Timestamps
created_at: datetime
# Correction Metadata
is_correction: bool # Was this decision a correction of another?
corrects_decision_id: ULID | null # If correction, which decision was replaced
correction_reason: str | null # Why the correction was made
superseded_by: ULID | null # If this decision was later corrected
Decision Timing
| Phase | Decision Activity |
|---|---|
| Strategize | Decisions are created. downstream_plan_ids is empty. |
| Execute | Subplans are spawned. downstream_plan_ids is populated when subplans are created based on subplan_spawn decisions. |
| Apply | No new decisions. History can be flagged for cleanup after successful apply. |
Decision Tree Storage Schema
-- Core decision table
CREATE TABLE decisions (
decision_id TEXT PRIMARY KEY, -- ULID
plan_id TEXT NOT NULL,
parent_decision_id TEXT,
sequence_number INTEGER NOT NULL,
decision_type TEXT NOT NULL,
question TEXT,
chosen_option TEXT NOT NULL,
alternatives_considered TEXT, -- JSON array
confidence_score REAL,
rationale TEXT,
actor_reasoning TEXT,
context_snapshot TEXT NOT NULL, -- JSON blob
is_correction BOOLEAN DEFAULT FALSE,
corrects_decision_id TEXT,
correction_reason TEXT,
superseded_by TEXT,
created_at TEXT NOT NULL,
FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
FOREIGN KEY (parent_decision_id) REFERENCES decisions(decision_id),
FOREIGN KEY (corrects_decision_id) REFERENCES decisions(decision_id),
FOREIGN KEY (superseded_by) REFERENCES decisions(decision_id)
);
-- Downstream relationships (many-to-many for DAG)
CREATE TABLE decision_dependencies (
upstream_decision_id TEXT NOT NULL,
downstream_decision_id TEXT NOT NULL,
dependency_type TEXT NOT NULL, -- 'decision', 'plan', 'artifact'
downstream_ref TEXT NOT NULL, -- The actual ID of decision/plan/artifact
PRIMARY KEY (upstream_decision_id, downstream_decision_id, downstream_ref),
FOREIGN KEY (upstream_decision_id) REFERENCES decisions(decision_id)
);
-- Correction history
CREATE TABLE correction_attempts (
attempt_id TEXT PRIMARY KEY, -- ULID
plan_id TEXT NOT NULL,
original_decision_id TEXT NOT NULL,
new_decision_id TEXT,
original_subtree_snapshot TEXT, -- Reference to archived state
correction_reason TEXT,
status TEXT NOT NULL, -- 'pending', 'executing', 'completed', 'failed'
created_at TEXT NOT NULL,
completed_at TEXT,
FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
FOREIGN KEY (original_decision_id) REFERENCES decisions(decision_id),
FOREIGN KEY (new_decision_id) REFERENCES decisions(decision_id)
);
Action
What an Action Is
An action is a reusable plan template that is not associated with any projects yet.
Important: Actions are created via CLI commands, NOT YAML configuration files. YAML configuration files are only used to define actors.
Examples:
- "Increase test coverage to 80%"
- "Refactor module X to be async-safe"
- "Write an RFC for feature Y"
- "Provision an infra cluster and validate access" (non-code)
Actions are intentionally project-agnostic so they can be reused across projects.
Action Creation (CLI)
Actions are created using the CLI:
agents action create \
--name "local/code-coverage" \
--description "Increase test coverage to target percentage" \
--strategy-actor "local/coverage-strategist" \
--execution-actor "local/coverage-executor" \
--definition-of-done "Coverage reaches target percentage; All new tests pass" \
--arg "target_coverage_percent:int:required:Target coverage percentage (0-100)" \
--arg "test_framework:str:optional:Test framework to use (pytest, unittest, etc.)"
Required parameters:
--name: Namespaced name (e.g.,local/code-coverage,myorg/deploy-action)--strategy-actor: Name of the actor to use for Strategize phase--execution-actor: Name of the actor to use for Execute phase--definition-of-done: Free-form text describing completion criteria
Optional parameters:
--description: Human-readable description--arg: Argument definitions (can be repeated). Format:name:type:required|optional:description--reusable: Whether action remains available after use (default: true)--read-only: Whether action only performs read operations (default: false)
Arguments defined with --arg are values that will be:
- Injected into the description and/or definition of done (via templating)
- Passed into the context of the actors
- Required when using the action on projects
Action Data Model (Expanded)
A plan in the Action phase has:
1) name (namespaced)
Format:
[server:][namespace/]<name>
Rules:
- If server is omitted, default server is assumed unless namespace is
local. - If namespace is omitted, default is
local. - Names should be stable identifiers (kebab-case recommended).
Examples:
local/code-coveragemyusername/code-coveragemyorgname/code-coverageprod:myorgname/code-coverage(server-qualified)
2) short_description
Optional at creation; auto-filled if blank.
3) long_description
Optional but recommended for reusable actions.
4) definition_of_done (DoD)
Required. Must be explicit and testable.
5) actors
Two actors minimum:
- strategy_actor (planner/architect)
- execution_actor (builder/implementer)
Actors can be:
- an LLM agent (built-in),
- a graph (custom yaml, or built-in),
Note: graphs are hierarchical allowing them to reference other actors as nodes.
Actor abstraction is central: an actor may be a single agent or an entire graph.
6) reusable (boolean)
- Default:
true. - If
true: using the action creates a new plan in Strategize while leaving the action available. - If
false: action self-deletes (or auto-archives) after first use.
7) read_only (boolean)
- Default:
false. - If
true: the plan must only use read-only skills and must never modify resources (even in sandbox). - Read-only actions are still useful for "investigation reports," architecture reviews, or dry-run planning.
8) inputs_schema (recommended addition)
To make actions genuinely reusable, actions should declare their inputs:
- required args (e.g., target coverage percent),
- optional args (e.g., test framework),
- validation rules (types, bounds).
Example:
target_coverage_percent: integer 0–100
9) safety_profile (recommended addition)
A policy bundle that can be applied to enforce safe execution:
- allowed skill categories,
- require checkpoints,
- require sandbox,
- require human approval at Apply.
This relates to the "checkpointable skills + sandbox" approach for safe writing.
Strategy (Strategize Phase)
Using an Action (Transition to Strategize)
The use command transitions an Action into the Strategize phase by applying it to one or more projects:
# Basic usage
agents plan use local/code-coverage --project my-api-service
# Multiple projects
agents plan use local/schema-update \
--project api-service \
--project web-frontend \
--project mobile-app
# With action arguments
agents plan use local/code-coverage \
--project my-api-service \
--arg target_coverage_percent=85 \
--arg test_framework=pytest
# With explicit automation level
agents plan use local/deploy-action \
--project staging-env \
--automation-level manual
Parameters:
--project: Project to apply the action to (can be repeated for multi-project plans)--arg: Action argument values (format:name=value)--automation-level: Override automation level for this plan
When the action is used:
- A new plan is created with a unique ULID
- The plan's automation level is determined (plan > session > global)
- The plan enters the Strategize phase
- The
strategy_actorbegins analyzing the project(s)
What Strategize Does
When an action is used on projects, it becomes a plan in Strategize.
Strategize is:
- read-only, producing a plan of attack,
- responsible for gathering context from project resources,
- responsible for generating a strategy and subplan blueprint,
- not allowed to execute subplans or modify resources.
This "architect vs coder" separation is explicitly described as a core motivation.
Resource-aware dependency analysis: During the Strategize phase, the strategy actor employs specialized mechanisms to compute precise dependency closures:
# Pseudocode of what happens inside a strategy actor
def compute_closure_for_refactoring(target_module):
closure = ResourceClosure()
# Direct file dependencies
closure.add_files(find_imports(target_module))
closure.add_files(find_includes(target_module))
# Symbol dependencies
for symbol in extract_exported_symbols(target_module):
closure.add_files(find_symbol_usage(symbol, scope='project'))
# Test dependencies
closure.add_files(find_tests_for_module(target_module))
# Build system dependencies
closure.add_files(find_build_references(target_module))
return closure
The system leverages several key insights:
- Modular boundaries exist: Even in legacy codebases, there are natural boundaries
- Changes are incremental: We don't convert 50,000 files atomically
- Dependencies are sparse: Most modules depend on a small fraction of the codebase
- Interfaces are narrow: Public APIs are much smaller than implementations
Strategize Data Model
A plan in Strategize contains all Action fields plus:
1) projects
A list of projects the plan is used on.
Important: A strategy plan may target multiple projects. Multi-project work in one "window" is considered a major usability advantage over tools that require being run from a single directory.
2) strategy_context
A structured object describing:
- what resources were considered,
- how they were retrieved,
- what filtering/limits were applied,
- what the actor saw.
This matters because a plan must be debuggable and correctable later.
Recommended fields:
resource_refs: IDs of resources usedqueries: search queries performedselected_chunks: chunk IDs + sources + reasonsconstraints: context window limits, file ignore patternsgenerated_summaries: if summarization occurred
3) strategy
The output plan:
- steps (ordered and/or DAG),
- conditions/branches ("if tests fail, do X"),
- subplans to spawn (including which action templates to use),
- evaluation criteria (how to know success),
- risk assessment.
4) execution_blueprint (recommended addition)
Strategize should output not only narrative text but also a machine-usable blueprint:
- list of tasks,
- required skills,
- expected outputs,
- dependencies between tasks.
This blueprint becomes the input to Execute.
5) cost_estimate and risk_estimate (optional)
Cost and risk estimation is optional but recommended for production use.
When enabled, a specialized estimation actor analyzes:
- The initial prompt/request
- The strategy produced by the Strategize phase
- Historical data from similar plans (if available)
And produces estimates for:
- LLM tokens/cost range
- Number of steps/subplans expected
- Expected risk of rollbacks
- Estimated execution time
Implementation: Similar to how there's a strategy_actor and execution_actor for each action, there can be an optional estimation_actor whose entire job is cost/risk estimation. This actor runs after Strategize completes (before Execute) and its output is informational only.
# Example: Action with estimation actor
agents action create \
--name "local/expensive-refactor" \
--strategy-actor "local/refactor-planner" \
--execution-actor "local/refactor-executor" \
--estimation-actor "local/cost-estimator" \
--definition-of-done "All code refactored according to plan"
This becomes critical in server/multi-user usage and cost controls.
Execution (Execute Phase)
What Execute Does
Execute is where the plan actually performs work, but in a sandboxed environment that can later be reviewed and applied.
Key properties:
-
Work happens in a sandbox All file modifications, generated artifacts, and intermediate outputs live in an isolated "execution workspace" until Apply.
-
Execute may spawn subplans Subplans are a first-class behavior of Execute: a parent plan can distribute work to child plans and merge results.
-
Execute must support checkpointing / rollback (when enabled) Checkpointable skills allow rolling back to a checkpoint ID to recover from partial failure or wrong turns.
-
Execute produces a "reviewable diff" Diff review sandbox is described as a differentiating feature: users can inspect changes before applying.
Execution Workspace / Sandbox Model (Detailed)
A sandbox isolates plan execution from the real project resources until Apply.
Key Sandbox Principles
-
Lazy Sandboxing: Resources are sandboxed only when accessed, not upfront.
- A project may have many resources (git repo + 10 databases + cloud accounts)
- A plan may only modify one resource
- Only accessed resources are sandboxed
- Efficient for large projects
-
Per-Plan Sandboxes: Each plan and subplan has its own sandbox containing only the resources it edits.
-
Resource-Defined Strategy: The sandbox strategy is defined on each resource, not by skills or globally.
-
Cleanup Behavior:
- Sandboxes are cleaned up before application exit when possible
- Abandoned sandboxes (from crashes, etc.) are cleaned up on next application run
- Completed plan sandboxes are cleaned or archived based on retention policy
Sandbox Implementation Strategies
Different resource types require different sandbox strategies:
| Resource Type | Strategy | Rollback Mechanism |
|---|---|---|
| Git Repository | git_worktree |
Git reset/checkout |
| Filesystem | copy_on_write or overlay |
Restore from snapshot |
| Database | transaction_rollback |
Transaction rollback |
| Cloud Infra | terraform_state |
Terraform plan (reversed) |
| API Endpoint | none |
Often not sandboxable |
1. Git worktree / branch sandbox (preferred for code)
- Create a worktree or temporary branch
- All modifications are commits or staged changes
- Apply merges/cherry-picks
Pros: natural rollback, diff support, efficient Cons: requires git
2. Filesystem copy sandbox
- Copy project directory to a sandbox directory
- Execute modifies sandbox copy
- Apply syncs diff back
Pros: simple Cons: expensive for huge repos
3. Overlay filesystem sandbox
- Use overlayfs-style "copy-on-write" to avoid full copies
Pros: efficient Cons: more complex, OS-dependent
4. Transaction-based sandbox (for databases)
- Begin transaction at sandbox creation
- All operations within transaction
- Rollback on failure, commit on apply
Pros: native to databases Cons: long-running transactions can cause issues
5. No sandbox (for non-sandboxable resources)
- Some resources cannot be sandboxed (certain APIs, cloud services)
- User proceeds at their own risk
- Plan should warn about non-sandboxable resources
Multi-Resource Sandboxing
When a plan accesses multiple resources:
- Each resource gets its own sandbox (based on its defined strategy)
- Sandboxes are independent
- Apply commits each sandbox separately
- If any sandbox Apply fails, others may still succeed (partial apply)
Complete isolation during execution prevents compound errors: Each plan executes in its own sandbox, which means:
Plan A (refactoring auth module):
- Sandbox A1: Contains only auth/*.cpp, auth_tests/*.cpp
- Cannot see Plan B's intermediate states
- Cannot accidentally depend on Plan B's half-done work
Plan B (updating API endpoints):
- Sandbox B1: Contains only api/*.cpp, api_tests/*.cpp
- Makes changes assuming current auth interface
- Protected from Plan A's intermediate refactoring
Hierarchical merge resolution: When subplans complete, the parent plan performs intelligent merging:
def merge_subplan_results(subplan_results):
# Group by resource type
by_resource = group_by_resource_type(subplan_results)
# Apply resource-specific merge strategies
for resource_type, changes in by_resource:
if resource_type == 'git_repo':
merge_git_changes(changes) # Three-way merge
elif resource_type == 'database':
merge_db_changes(changes) # Sequential application
elif resource_type == 'config_files':
merge_config_changes(changes) # Smart JSON/YAML merge
# Validate merged state
run_integration_tests()
Execution Data Model
A plan in Execute contains:
1) execution_context
The context used for execution (often smaller/more tactical than strategy context).
2) execution_log
Structured timeline of:
- skill calls,
- actor calls,
- outputs,
- errors and retries,
- checkpoints created.
This log is essential for debugging.
3) artifacts
Outputs produced:
- changed files,
- generated files,
- reports,
- diagrams,
- test outputs,
- diffs.
4) sandbox_ref
Pointer to the sandbox location/state:
- path, branch name, workspace ID, container ID, etc.
5) checkpoint_graph (if enabled)
A record of checkpoints:
- checkpoint ID
- timestamp
- skill responsible
- resources affected
- rollback instructions / metadata
Checkpointing in Execute (Core Safety Mechanism)
The intended user-level behavior is:
- "Give me a checkpoint ID."
- Perform additional operations.
- "Roll back to checkpoint X."
Not all skills can support this; checkpointing must be declared per skill.
Skill-level checkpointability
Each skill declares:
checkpointable: true|falserollback_mechanism: how rollback occursscope: what resources it can revert
Examples:
- File skill: snapshot file states pre-modification
- Git skill: create commit or stash; rollback is reset/checkout
- CLI skill inside a container: rollback by restoring filesystem snapshot or reloading base image state
It should be noted that checkpointing is easier when skill scope is constrained (e.g., "only files within a docker image + git").
Plan-level rollback policy
Plans should have an option:
rollback_enabled: true|false
If disabled, the plan may use more generic/unsafe skills with fewer restrictions (useful for low-stakes tasks).
Execution as Transactions (Recommended)
Execution should be treated like a transactional pipeline:
-
Each step either:
- commits a checkpoint on success, or
- rolls back to the previous checkpoint on failure.
This is explicitly motivated by "partial failure leaves codebase inconsistent" and the need for transaction rollback.
Tool-Based Resource Modification (Modern Architecture)
IMPORTANT: CleverAgents does NOT parse LLM output to extract code. Instead, it uses the modern tool-based approach pioneered by Claude Code, Cursor, and Aider where:
- LLMs call tools/skills directly (
edit_file(),write_file(),delete_file(), etc.) - Tools operate on the sandbox - each tool invocation modifies sandbox state directly
- ChangeSet is built from tool invocations - not by parsing LLM text output
- Validation runs on sandbox state - after tools execute, not on parsed output
This architecture provides:
- Atomic operations: Each tool call is a discrete, trackable change
- No parsing ambiguity: Tools have structured parameters (path, content, etc.)
- Resource-agnostic: Same pattern works for files, databases, APIs, any resource type
- Safety by design: Tools run in sandbox with defined capabilities and restrictions
- MCP compatibility: Skills map directly to MCP tools for external integrations
How It Works
LLM Response (with tool calls)
↓
┌─────────────────────────────────────┐
│ Skill/Tool Router │
│ - Routes each tool call to handler │
│ - Validates parameters │
│ - Enforces capability restrictions │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Sandbox Execution │
│ - Tool operates on sandboxed state │
│ - Each invocation recorded │
│ - Checkpoint created if needed │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ ChangeSet Accumulation │
│ - Each resource-modifying call → │
│ becomes a Change record │
│ - ChangeSet = history of changes │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Validation & Review │
│ - Run validators on sandbox state │
│ - Generate diff from ChangeSet │
│ - Present for review before Apply │
└─────────────────────────────────────┘
Built-in Resource Skills
CleverAgents provides these core skills for resource manipulation:
| Skill | Description | Creates Change? |
|---|---|---|
read_file(path) |
Read file contents | No |
write_file(path, content) |
Create/overwrite file | Yes |
edit_file(path, changes) |
Apply targeted edits | Yes |
delete_file(path) |
Remove file | Yes |
move_file(src, dst) |
Rename/move file | Yes |
create_directory(path) |
Create directory | Yes |
list_files(pattern) |
List files matching glob | No |
search_files(pattern, content) |
Search file contents | No |
get_file_info(path) |
Get file metadata | No |
Each skill automatically:
- Operates within sandbox boundaries
- Records changes to the ChangeSet
- Validates parameters against project configuration
- Enforces deny-list patterns (
.git/,node_modules/, etc.)
Why Not Parse LLM Output?
The obsolete approach of parsing markdown code fences has fundamental problems:
- Ambiguity: Is text explanation or code? Where does one file end and another begin?
- Fragility: Models output varying formats; regex parsing is brittle
- Loss of semantics: You lose the intent (create vs modify vs delete)
- No atomicity: Can't rollback individual operations
- Resource-limited: Only works for files, not databases or other resources
The tool-based approach solves all of these by making each operation explicit, typed, and trackable.
Semantic Error Prevention
CleverAgents provides multiple layers of proactive error prevention that catch semantic errors before they can propagate through the system.
Layer 1: Decision-time Validation During Strategize
Every decision includes semantic validation:
Decision: Refactor payment module to async
alternatives_considered:
- "Convert to async/await patterns" (chosen)
- "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem)
- "Keep synchronous with timeout" (rejected: doesn't solve core latency issue)
confidence_score: 0.85
validation_performed:
- Checked all payment API consumers can handle async
- Verified database driver supports async operations
- Confirmed no regulatory requirement for sync processing
Layer 2: Execution-time Semantic Guards
The execution actor configuration includes validation nodes that understand semantics:
actors:
code_executor:
type: graph
nodes:
- name: semantic_validator
type: tool
config:
tools:
- name: validate_api_compatibility
code: |
# Not just syntax checking - semantic validation
old_api = extract_api_signature(previous_version)
new_api = extract_api_signature(current_version)
breaking_changes = find_breaking_changes(old_api, new_api)
if breaking_changes:
# Don't just fail - understand the impact
affected_consumers = find_api_consumers(breaking_changes)
migration_plan = generate_migration(breaking_changes)
if can_auto_migrate(affected_consumers, migration_plan):
apply_migration(migration_plan)
else:
raise SemanticError(
"Breaking API changes require manual review",
changes=breaking_changes,
affected=affected_consumers
)
Layer 3: Invariant Enforcement
The system maintains semantic invariants:
class RefactoringInvariants:
# User-defined invariants for the codebase
invariants = [
"All public APIs must maintain backward compatibility",
"Database transactions must complete within 5 seconds",
"Authentication must always use OAuth2",
"Payment processing must be idempotent"
]
def check_invariant_preservation(self, changes):
for invariant in self.invariants:
if not self.verify_invariant(invariant, changes):
return InvariantViolation(invariant, changes)
return Success()
Layer 4: Predictive Error Prevention
The system learns from past failures:
Error Pattern Database:
- pattern: "Async conversion in payment module"
historical_failures:
- "Race condition in payment confirmation"
- "Timeout handling breaks idempotency"
preventive_checks:
- "Add explicit transaction boundaries"
- "Verify idempotency keys are preserved"
- "Check distributed lock acquisition"
Applied (Apply Phase)
What Apply Does
Apply takes the sandboxed work product and makes it "real" in the project.
Core properties:
-
Apply is a controlled commit step Apply exists specifically to separate "generated work" from "committed work," enabling review and safer automation.
-
Apply is often the highest-risk step It changes real systems. This is where permissions, approvals, and checks matter most.
-
Apply produces a terminal 'applied' plan After successful apply, the plan becomes Applied.
Apply Responsibilities (Recommended Checklist)
Apply should perform (configurable) validations before committing:
-
Diff review gate
-
If automation level requires review, show:
- changed files summary,
- full diff,
- risk warnings.
-
-
Pre-apply tests
- Run validation as defined by the actor and/or project (see below).
-
Conflict resolution
- If applying to a git repo, handle rebase/merge conflicts safely.
-
Audit log
- Record who applied, what changed, when, and why.
Validation Configuration
Validation is defined by the actor configuration and project settings, not hardcoded.
Actor-defined validation: The execution actor's workflow should include validation nodes that:
- Read project-defined test/validation commands from context
- Execute appropriate tests based on resource type
- Handle failures by iterating (attempting fixes) or escalating to user
Project-defined validation: Each project should define how its resources are validated:
# Example: Add validation configuration to a project
agents project set-validation \
--project my-api-service \
--resource api-repo \
--test-command "pytest" \
--lint-command "ruff check ." \
--type-check-command "pyright"
This information is passed into the actor's context, allowing generic actors (not specific to any project) to execute appropriate validation.
Validation Failure Handling
When validation fails:
- Iteration: Actor attempts to fix the issue (e.g., fix failing tests)
- Retry limit: After several failed attempts, iteration stops
- User intervention: User can provide additional instructions
- Resume: Plan continues with new guidance
The user can prompt the plan with additional instructions when stuck:
agents plan prompt <plan_id> "Try using mock objects for the database tests"
Apply Data Model
A plan in Apply includes:
apply_summaryapplied_artifacts(final commit hash, merged PR link, file list)final_validation_results(test outputs, lint outputs)approval_record(if human approvals are required)deployment_record(optional, if apply triggers deploy)
"Applied" Terminal State
When Apply succeeds:
- plan.phase =
applied - plan.state =
complete - the sandbox may be cleaned up or archived depending on retention policy
When Apply fails:
- plan.phase remains Apply
- plan.state =
errored - sandbox remains intact for inspection/retry
Project
A project is the boundary that answers:
- "Where is the work happening?"
- "What can this plan read and write?"
- "What tools can this plan use?"
- "What context is available?"
A project is a collection of resources and configuration.
Important: Projects are created via CLI commands, NOT YAML configuration files.
Project Types: Local vs Remote
Projects are classified based on their resources:
| Type | Definition | Where Plans Can Execute |
|---|---|---|
| Local | Contains at least one local-only resource | Client only |
| Remote | All resources are remotely accessible | Client or Server |
This distinction matters for server mode: the server can only execute plans on remote projects because it needs network access to all resources.
Project Creation (CLI)
# Create a new project
agents project create \
--name "my-api-service" \
--tag "python" \
--tag "backend"
# Add resources to the project
agents project add-resource \
--project "my-api-service" \
--name "api-repo" \
--type "git_repository" \
--location "git@github.com:org/api-service.git" \
--sandbox-strategy "git_worktree"
agents project add-resource \
--project "my-api-service" \
--name "staging-db" \
--type "database" \
--location "postgresql://staging.example.com/mydb" \
--sandbox-strategy "transaction_rollback" \
--read-only
Project Data Model
A project includes:
1) Identity
project_id(ULID)namenamespace(follows same rules as actors:local/,<username>/,<orgname>/)tags(e.g., "python", "infra", "paper", "prod")is_remote(boolean, derived from resources)
2) Resources
Resources are the "things you can act on." Each resource defines its own sandbox strategy.
Resource types include:
- filesystem root(s)
- git repository
- database endpoints
- cloud accounts
- document corpora (papers, PDFs)
- API schemas
Each resource has:
resource_id(ULID)nametype(e.g.,git_repository,database,filesystem,api_endpoint)location(path/url/connection string)is_remote(boolean - can it be accessed over network?)sandbox_strategy(defined on the resource - see Sandboxing section)read_only(boolean - whether writes are allowed)metadata(language, repo size, etc.)
3) Context configuration
Project-level defaults:
- ignore patterns (like
.gitignoresemantics) - max file size
- indexing strategy
- preferred chunking/summarization policy (even if evolving)
- context retention policy
4) Security / permissions defaults
- who can run write plans
- which skills are restricted
- whether apply requires approvals
Multi-Project Operations
A single plan may target multiple projects (e.g., updating shared schemas across services). This is considered a key UX advantage over "run in one directory" systems.
In multi-project execution:
- Strategize must clarify which steps affect which projects.
- Execution must isolate sandboxes per project OR define a composite sandbox.
- Apply must commit changes to each project separately, with separate approval records if necessary.
Namespaces
Namespaces define ownership, scoping, and discoverability of actions, projects, actors, and plans.
All named entities use the format <namespace>/<name>.
Namespace Types
| Namespace | Scope | Storage | Examples |
|---|---|---|---|
local/ |
Current machine only | Local database | local/my-reviewer, local/test-action |
<username>/ |
Personal server namespace | Server database | freemo/code-analyzer, jsmith/deploy-script |
<orgname>/ |
Organization namespace | Server database | cleverthis/standard-review, acme/deploy-action |
openai/, anthropic/, etc. |
Built-in LLM actors | N/A (built-in) | openai/gpt-4, anthropic/claude-3-opus |
Namespace Rules
-
local/- Reserved namespace for local-only items
- Exists only on the current machine
- Stored in local database
- Fast iteration, no sharing
- Default namespace when none specified
-
<username>/(e.g.,freemo/,jsmith/)- Personal namespace on the server
- Created when user registers an account
- Stored on server, synced when connected
- Used for reusable actions/actors a user wants across machines
- Only the owning user can create/modify items
-
<orgname>/(e.g.,cleverthis/,acme/)- Organization namespace on the server
- Created when organization is registered
- Shared across team members
- Permissions and approvals managed at org level
- Actions/actors/projects can be centrally managed
-
Built-in Provider Namespaces (
openai/,anthropic/,google/, etc.)- Reserved for built-in LLM actors
- Automatically available when API keys are configured
- In server mode: available if logged in and server has keys
- In local mode: requires environment variables or app configuration
- Cannot be used for custom actors
Server-qualified Names
To disambiguate between servers (when connected to multiple):
dev:freemo/code-coverage(personal namespace on dev server)prod:cleverthis/deploy-action(org namespace on prod server)
This enables a pattern where:
- local machine runs a lightweight client
- server stores canonical definitions
- multiple servers can coexist
Actor
What an Actor Is
An actor is the abstraction that generalizes "agent" into "anything conversational."
- It can be as small as a single LLM agent.
- It can also be an entire graph that itself calls other actors/tools.
- Actors can be nested/hierarchical, enabling "orchestrator of orchestrators."
Every custom actor IS a graph (a LangGraph defined via YAML configuration). Even a simple actor wrapping a single LLM is technically a graph with one node.
Actor Naming
Actors are always named using <namespace>/<name> format:
local/my-reviewer- Local actorfreemo/code-analyzer- Personal server actorcleverthis/deploy-specialist- Organization actoropenai/gpt-4- Built-in LLM actor
Actor Definition (YAML Configuration)
Actors are defined via YAML configuration files. This is the ONLY place YAML configuration is used (not for actions or projects).
Example actor configuration (see examples/ directory for full examples):
cleveragents:
version: "3.0"
default_actor: workflow_controller
actors:
# Simple LLM actor
my_assistant:
type: llm
config:
actor: openai/gpt-4 # Reference to built-in actor
temperature: 0.7
system_prompt: |
You are a helpful assistant.
Current task: {{ context.task_description }}
# Tool actor with inline Python
data_processor:
type: tool
config:
tools:
- name: process_data
code: |
# Inline Python code
result = do_something(input_data, context)
# Actor referencing another actor
reviewer:
type: llm
config:
actor: local/code-reviewer # Reference to another custom actor
memory_enabled: true
max_history: 20
routes:
main_workflow:
type: graph
entry_point: start
nodes:
- name: analyze
type: agent
agent: my_assistant
- name: process
type: agent
agent: data_processor
edges:
- source: start
target: analyze
- source: analyze
target: process
- source: process
target: end
context:
global:
task_description: "Default task"
Actor Arguments
All actors can receive arguments when invoked, including built-in actors. Arguments are passed when:
- An action is used on projects (arguments flow to strategy/execution actors)
- An actor is directly invoked
Arguments are injected into the actor's context and can be used in Jinja2 templates within prompts.
For built-in actors (like openai/gpt-4), common arguments include:
temperaturemax_tokenssystem_prompt
Actor Composition (Hierarchical References)
Actors can reference other actors by name:
actors:
complex_workflow:
type: llm
config:
actor: local/base-analyzer # References another actor
Load order matters: Referenced actors must be loaded/defined before actors that depend on them.
This enables hierarchical composition where:
- Actor A's graph can include nodes that call Actor B (by name)
- Actor B itself is a graph that might call Actor C
- And so on...
Actor vs Agent (Relationship)
-
Agent: an actor that is specifically an LLM with tools and reasoning behaviors.
-
Actor: may be an agent, but may also be:
- a composite workflow,
- a multi-step graph,
- a wrapper around a third-party system (as long as it's "text in → text out" conversationally).
Actor Definition Fields (From Notes + Extended)
A robust actor schema should include:
name(namespaced)provider(LLM provider or runtime target)modelsystem_prompt(or prompt template)tool_access_policygraph_descriptor(for composite actors)memory_policy(per-plan/per-actor—see memory section)context_view_policy(what context this actor sees)limits(token limits, tool call limits, retries)cost_policy(caps, budgets)metadata(tags, use cases, version)
Actor Composition and Graphs
Actors can reference:
- other actors
- skills (MCP/custom tools)
- subgraphs
This is central to enabling both:
- multi-agent orchestration, and
- modular reuse of workflows.
Nodes in the Graph: Actor, Skill, or Custom Tool
The transcript explicitly frames the graph nodes as being any of:
- an actor,
- an MCP skill,
- a custom tool node (arbitrary python code).
This is a powerful simplification: "everything is a node."
Agent
Agent Definition
In CleverAgents, an agent is a specialized actor with:
- a conversational interface,
- tool-calling capability,
- potentially memory, planning heuristics, and role identity.
Examples of agent roles:
- planner/architect (strategy actor)
- coder/implementer (execution actor)
- reviewer/qa agent
- release/apply agent
The transcript explicitly discusses role separation like planner/coder/reviewer in context views/memory proposals.
Agent Behavior Configuration
Agents should be configurable without code changes:
- prompt templates
- tool sets
- safety constraints
- style constraints (verbosity, code style)
- reliability controls (self-checks, validations)
A design goal is user empowerment: "users customize LLM behavior without modifying core code."
Skills
What a Skill Is
A skill is an executable capability exposed to the system. Skills are defined inline in actor YAML configuration files as tool nodes.
Examples:
- file read/write
- git operations
- shell command execution
- database query execution
- API calls
- vector search / RAG query
- cloud administration actions
Skill Definition
Skills do not have separate names. They are defined as part of actor configurations:
actors:
my_processor:
type: tool
config:
tools:
- name: process_data # Tool name within this actor
code: |
# Inline Python code
result = process(input_data, context)
- name: validate_output
code: |
# Another tool in the same actor
if not is_valid(input_data):
raise ValueError("Invalid output")
result = input_data
To create a "named skill": Define an actor with a single tool node. The actor name then effectively becomes the skill name.
Skill Standards
Skills should extend two complementary standards:
-
MCP (Model Context Protocol): https://modelcontextprotocol.io/
- Tools: Schema-defined operations LLMs can invoke
- Resources: Read-only data sources
- Prompts: User-controlled templates
-
Agent Skills Standard: https://agentskills.io/
- Folders of instructions, scripts, and resources
- Portable procedural knowledge across agent products
CleverAgents extends the MCP resource concept to support both read and write operations.
Skill Sources
Skills come from multiple places:
-
Built-in skills (first-party, when implemented)
- files, git, search, indexing, context mgmt, sandbox ops
-
MCP skills (external MCP servers)
-
Imported skills from other ecosystems
- wrap tools from other agent frameworks as long as interface is compatible
-
Custom tool nodes (most common)
- arbitrary python code embedded in actor configuration
- behaves as a graph node
Skill Capability Metadata (Critical for Safety)
MCP's metadata is not sufficient (read-only/idempotent isn't enough; write scope is unclear). CleverAgents needs extended metadata for each skill.
Required skill metadata:
read_only: bool- Whether skill only performs read operationswrites: bool- Whether skill can modify resourceswrite_scope:- file paths allowed
- resource IDs allowed
- environment boundaries (container only vs host)
idempotent: bool- Whether repeated calls produce same resultcheckpointable: bool- Whether skill supports checkpoint/rollbackcheckpoint_scope- What can be rolled backside_effects- install packages, mutate infra, etc.required_permissions- What permissions needed to userate_limits/cost_profile- Usage constraintshuman_approval_required: bool- Optional approval gate
Read-Only Actions
When an action is marked read_only: true, it can only use skills that have read_only: true in their metadata. This is enforced at runtime.
Skill Registry / Catalog
To scale, CleverAgents should maintain a catalog of skills with metadata:
- auto-extracted from MCP descriptors (where possible)
- refined manually via annotations
- enhanced by CleverAgents-specific extensions
This registry supports:
- plan validation ("this plan requires checkpointable write skills; do we have them?")
- safe automation ("don't ask permission for every tiny command—use sandbox/checkpoints instead")
MCP Integration Architecture
CleverAgents fully integrates with the Model Context Protocol (MCP) while extending it for agentic workflows:
MCP Concepts Mapping
| MCP Concept | CleverAgents Equivalent | Extension |
|---|---|---|
| Tool | Skill | Extended metadata (write_scope, checkpointable) |
| Resource | Resource | Read AND write operations |
| Prompt | Action template | Full plan lifecycle |
| Server | MCP Server (external) | Integrated via skill adapters |
Using External MCP Servers
CleverAgents can connect to any MCP server and expose its tools as skills:
actors:
github_ops:
type: tool
config:
mcp_servers:
- name: github
command: "npx @anthropic/mcp-github"
env:
GITHUB_TOKEN: "${GITHUB_TOKEN}"
- name: filesystem
command: "npx @anthropic/mcp-filesystem"
args: ["--root", "/workspace"]
When an actor specifies mcp_servers, all tools from those servers become available as skills within that actor's execution context.
MCP Tool → Skill Adapter
External MCP tools are automatically wrapped with CleverAgents skill semantics:
┌─────────────────────────────────────┐
│ MCP Server │
│ - Exposes tools via JSON-RPC │
│ - Has MCP metadata (read-only, etc) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ MCPSkillAdapter │
│ - Wraps MCP tool as Skill │
│ - Infers extended metadata │
│ - Intercepts calls for: │
│ - Sandbox path rewriting │
│ - Change tracking │
│ - Permission enforcement │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Skill Execution │
│ - Runs in plan's sandbox context │
│ - Changes recorded to ChangeSet │
│ - Checkpoints created as needed │
└─────────────────────────────────────┘
Skill Execution Flow (Tool-Based Architecture)
When an LLM decides to use a skill, the following flow occurs:
1. LLM generates tool call: edit_file(path="src/main.py", changes=[...])
↓
2. Tool Router receives call
- Validates parameters against schema
- Checks skill capability metadata
- Enforces permission restrictions
↓
3. Sandbox Context Resolution
- Maps logical path to sandbox path
- Ensures sandbox exists for resource
- Creates checkpoint if skill is checkpointable
↓
4. Skill Execution
- Runs skill code (built-in or MCP)
- Operations occur on sandboxed state
- Result captured
↓
5. Change Recording
- If skill modifies resources, create Change record
- Append Change to plan's ChangeSet
- Update sandbox state
↓
6. Return to LLM
- Return skill result
- LLM continues with next action
Built-in Skills (Core Resource Operations)
CleverAgents provides these built-in skills that work with any resource through the unified abstraction layer:
File Operations:
read_file(path: str) -> str
write_file(path: str, content: str) -> None
edit_file(path: str, edits: list[Edit]) -> None
delete_file(path: str) -> None
move_file(source: str, destination: str) -> None
copy_file(source: str, destination: str) -> None
Directory Operations:
create_directory(path: str) -> None
list_directory(path: str, pattern: str = "*") -> list[str]
delete_directory(path: str, recursive: bool = False) -> None
Search Operations:
search_files(pattern: str, content_pattern: str = None) -> list[Match]
find_definition(symbol: str) -> list[Location]
find_references(symbol: str) -> list[Location]
Git Operations (when resource is git repository):
git_status() -> GitStatus
git_diff(path: str = None) -> str
git_log(count: int = 10) -> list[Commit]
git_blame(path: str) -> list[BlameLine]
Each built-in skill:
- Has fully defined capability metadata
- Operates through the resource abstraction layer
- Automatically tracks changes to the ChangeSet
- Respects sandbox boundaries and deny-lists
Change Tracking from Tool Invocations
Critical Architecture Point: The ChangeSet is NOT built by parsing LLM output. It is built by recording the effects of tool/skill invocations:
class SkillExecutionContext:
"""Context provided to skill execution."""
def __init__(self, plan: Plan, sandbox: Sandbox):
self.plan = plan
self.sandbox = sandbox
self.changes: list[Change] = []
def record_change(self, change: Change) -> None:
"""Record a change made by a skill."""
self.changes.append(change)
self.plan.changeset.add_change(change)
class WriteFileSkill:
"""Built-in skill for writing files."""
def execute(self, path: str, content: str, ctx: SkillExecutionContext) -> None:
# Get the resource handler for this path
handler = ctx.sandbox.get_handler(path)
# Perform the write (returns Change record)
change = handler.write(path, content, ctx.sandbox)
# Record the change
ctx.record_change(change)
This approach means:
- Every resource modification is explicit and tracked
- The ChangeSet accurately reflects what was done, not what was said
- Rollback is precise (replay inverse of recorded changes)
- Audit logs show exactly what each skill invocation did
Session
What a Session Is
A session is a user's interactive thread with CleverAgents across time.
A session should:
- maintain conversational continuity,
- store plan references,
- persist memory (if enabled),
- provide a UI anchor (CLI invocation, TUI workspace, web session).
Session and Memory Persistence
The notes include a known issue: conversation history can be lost between CLI invocations depending on connection string configuration, implying the system needs a stable memory service backend.
Therefore, CleverAgents should specify:
- sessions have stable IDs
- sessions can be resumed
- session storage backend is configured explicitly
- if session persistence is disabled, the UX should be explicit about it (no silent history loss)
Server
What a Server Is
A server is an optional mode that enables:
- multi-user access
- shared org namespaces (
<username>/and<orgname>/) - persistent plan records
- remote plan execution
- permissioning and governance
Single-user local mode is the default (so setup is easy), but the architecture anticipates server mode for shared skills and org-level actions.
Client-Only vs Server Mode
| Mode | Description | Plan Execution |
|---|---|---|
| Client-only | No server connection. All data in local database. | Always local |
| Server mode | Connected to a CleverAgents server. Namespaced items sync. | Local or server |
It is possible to run a client with no server at all. Server is optional.
Plan Execution Location
Where a plan executes depends on the project type:
| Project Type | Client Execution | Server Execution |
|---|---|---|
| Local (has local-only resources) | ✅ Yes | ❌ No (server can't access local resources) |
| Remote (all resources remotely accessible) | ✅ Yes | ✅ Yes |
When acting on local projects, the client must be running because only the client can access local resources.
Remote projects can execute on either:
- The client (if user prefers local execution)
- The server (for long-running plans, since client may be transient)
Server Execution Benefits
Server execution is useful when:
- Plans take a long time to execute
- Client may disconnect (laptop closes, network issues)
- Multiple team members need to monitor plan progress
- Centralized logging and auditing required
No Plan Queuing
Plans are not queued. When a plan is used on projects and executed, it runs immediately. There is no worker queue or delayed execution model.
Multi-user Risks and Prompt Injection
Prompt injection isn't critical in single-user mode but becomes important for multi-user server environments.
Server mode must include:
- permission boundaries
- prompt sanitization / safe templating
- resource access controls
- auditing
Permissions
Permissions exist at multiple layers:
1) Namespace-level permissions
- Who can create/edit org actions/actors/projects?
- Who can run them?
2) Project-level permissions
- Who can modify project resources?
- Who can apply changes?
3) Plan-level permissions
- Can this plan write?
- Does it require approvals?
- Can it access restricted skills?
4) Skill-level permissions
-
Some skills should require:
- explicit user approval per call, or
- elevated role membership.
Approval Gates by Phase (Recommended)
A simple and powerful governance model:
- Strategize: generally safe, read-only → minimal restrictions
- Execute: writes occur but sandboxed → moderate restrictions
- Apply: writes are real → strict restrictions + optional mandatory review
This aligns with the four-phase model's safety rationale.
Resources
Resources are any objects a plan can reason about or manipulate.
CleverAgents extends the MCP resource concept to support both read AND write operations (MCP resources are read-only).
Resource Types (Examples)
- FilesystemResource: directories, files
- GitRepoResource: git repos, branches
- DatabaseResource: SQL/NoSQL endpoints
- CloudResource: clusters, accounts, infra configs
- DocumentCorpusResource: PDFs, markdown docs, wikis
- APISpecResource: OpenAPI/Swagger, Postman collections
- IssueTrackerResource: tickets, bugs, tasks (optional)
Resource Sandbox Strategy
Each resource defines its own sandbox strategy. This is critical because:
- The same resource may be accessed through different skills
- Different resource types require different sandboxing approaches
- Some resources cannot be sandboxed at all
| Resource Type | Sandbox Strategy | Rollback Mechanism |
|---|---|---|
| Git Repository | git_worktree |
Git reset/checkout |
| Filesystem | copy_on_write or overlay |
Restore from snapshot |
| Database | transaction_rollback |
Transaction rollback |
| Cloud Infra | terraform_state |
Terraform apply (reversed) |
| API Endpoint | none (often not sandboxable) |
N/A |
Example resource with sandbox strategy:
agents project add-resource \
--project "my-api" \
--name "main-repo" \
--type "git_repository" \
--location "git@github.com:org/api.git" \
--sandbox-strategy "git_worktree"
Lazy Sandboxing
Resources are sandboxed lazily when accessed, not upfront. Note that this is different from indexing - resources are indexed immediately when added to a project, but sandboxes are only created when execution needs to modify a resource:
- A project may contain many resources (e.g., git repo + 10 databases + cloud accounts)
- A plan may only need to modify one resource
- Only the accessed resources are sandboxed
- Each plan/subplan has its own sandbox containing only edited resources
This is efficient for large projects where most resources remain untouched.
Resource Access Tracking
The system needs to know which skills touch which resources to reason about safety and checkpointing.
Every skill call should log:
- resource IDs accessed
- read/write actions
- file paths or object IDs touched
This enables:
- better context assembly
- better rollback feasibility analysis
- better auditing
- accurate sandbox scoping
Unified Resource Abstraction Layer
CleverAgents provides a unified abstraction that allows skills to work with any resource type through a consistent interface. This enables:
- Resource-agnostic skills: A skill like
read_content(path)works whether the path refers to a file, database record, or API endpoint - Consistent sandbox semantics: All resources support the same sandbox lifecycle (create, read, write, checkpoint, rollback)
- Pluggable resource handlers: New resource types can be added without modifying existing skills
- Unified change tracking: All resource modifications flow into the same ChangeSet model
Resource Handler Interface
Every resource type implements this interface:
class ResourceHandler(Protocol):
"""Handler for a specific resource type."""
def read(self, path: str, sandbox: Sandbox) -> Content:
"""Read content from the sandboxed resource."""
...
def write(self, path: str, content: Content, sandbox: Sandbox) -> Change:
"""Write content and return the Change record."""
...
def delete(self, path: str, sandbox: Sandbox) -> Change:
"""Delete resource and return the Change record."""
...
def list(self, pattern: str, sandbox: Sandbox) -> list[str]:
"""List paths matching pattern."""
...
def diff(self, path: str, sandbox: Sandbox) -> str:
"""Generate diff between sandbox and original state."""
...
def supports_operation(self, operation: OperationType) -> bool:
"""Check if this resource supports the given operation."""
...
Built-in Resource Handlers
| Resource Type | Handler | Read | Write | Delete | Sandbox Strategy |
|---|---|---|---|---|---|
| Filesystem | FilesystemHandler |
✓ | ✓ | ✓ | copy_on_write |
| Git Repository | GitHandler |
✓ | ✓ | ✓ | git_worktree |
| PostgreSQL | PostgresHandler |
✓ | ✓ | ✓ | transaction |
| SQLite | SQLiteHandler |
✓ | ✓ | ✓ | copy_on_write |
| HTTP API | HTTPHandler |
✓ | ✓* | ✓* | none |
| S3 Bucket | S3Handler |
✓ | ✓ | ✓ | versioning |
*HTTP writes may not be sandboxable depending on the API
Resource Path Resolution
Paths in skills are resolved through a resource routing system:
path://resource-name/relative/path
↓
┌─────────────────────────────────────┐
│ Resource Router │
│ - Parses path scheme │
│ - Looks up resource by name │
│ - Routes to appropriate handler │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Handler (e.g., GitHandler) │
│ - Resolves relative path │
│ - Operates on sandboxed state │
│ - Returns Change record │
└─────────────────────────────────────┘
For convenience, paths without a scheme default to the project's primary filesystem resource.
Code Intelligence & Context Discovery
Overview
CleverAgents employs a sophisticated multi-layered indexing and discovery system that enables agents to efficiently navigate and understand codebases of any scale. This system goes far beyond simple text search, providing semantic understanding of code structure, dependencies, and relationships through a combination of indexed embeddings, vector search, and an RDF-based graph store.
Critical Design Decision: All indexing happens immediately when resources are added to projects or when code changes. There is no "on-demand" indexing during agent execution. This ensures that agents always have instant access to search capabilities without any indexing delays. The computational cost is paid once upfront, not repeatedly during agent operations.
Key Design Principles:
- Pluggable Architecture: Every component can be extended or replaced
- Progressive Enhancement: System works with basic text search, enhances with advanced features
- Eager Indexing: Indices are built immediately when resources are added and kept continuously up-to-date
- Agent Awareness: Agents understand available indices through skills
- Real-time Synchronization: Indices update immediately as code changes
Architecture Components
1. Multi-Modal Indexing Engine
The indexing engine operates across three complementary modalities:
IndexingEngine:
modalities:
# Traditional text-based indexing
text_index:
type: "full_text_search"
backend: "tantivy" | "elasticsearch" | "sqlite_fts"
features:
- Token-based search
- Regex patterns
- Language-aware tokenization
- File path indexing
# Semantic understanding via embeddings
vector_index:
type: "embedding_search"
backend: "faiss" | "qdrant" | "weaviate" | "pgvector"
models:
- code: "codegen-6B-multi"
- docs: "instructor-xl"
- cross-modal: "clip-code"
features:
- Function-level embeddings
- Class-level embeddings
- Module-level embeddings
- Documentation embeddings
- Cross-language similarity
# Structural understanding via graph
graph_index:
type: "rdf_knowledge_graph"
backend: "blazegraph" | "stardog" | "apache_jena" | "neo4j"
ontology: "CodeOntology"
features:
- AST-based relationships
- Dependency graphs
- Call graphs
- Inheritance hierarchies
- Data flow analysis
2. RDF-Based Code Knowledge Graph
The graph store represents code as a rich semantic network using RDF (Resource Description Framework) triples. This enables sophisticated queries about code structure and relationships.
Core Ontology Design:
# CodeOntology - Core vocabulary for code representation
@prefix code: <https://cleveragents.ai/ontology/code#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
# Core Classes
code:Module a rdfs:Class ;
rdfs:comment "A code module (file, package, namespace)" .
code:Class a rdfs:Class ;
rdfs:comment "A class or similar construct" .
code:Function a rdfs:Class ;
rdfs:comment "A function, method, or procedure" .
code:Variable a rdfs:Class ;
rdfs:comment "A variable, constant, or field" .
code:Type a rdfs:Class ;
rdfs:comment "A type definition" .
# Core Properties
code:contains a rdf:Property ;
rdfs:domain code:Module ;
rdfs:range code:Entity ;
rdfs:comment "Module contains entity" .
code:imports a rdf:Property ;
rdfs:domain code:Module ;
rdfs:range code:Module ;
rdfs:comment "Module imports another module" .
code:extends a rdf:Property ;
rdfs:domain code:Class ;
rdfs:range code:Class ;
rdfs:comment "Class inheritance relationship" .
code:calls a rdf:Property ;
rdfs:domain code:Function ;
rdfs:range code:Function ;
rdfs:comment "Function calls another function" .
code:references a rdf:Property ;
rdfs:domain code:Entity ;
rdfs:range code:Entity ;
rdfs:comment "Entity references another entity" .
code:hasParameter a rdf:Property ;
rdfs:domain code:Function ;
rdfs:range code:Parameter ;
rdfs:comment "Function has parameter" .
code:returns a rdf:Property ;
rdfs:domain code:Function ;
rdfs:range code:Type ;
rdfs:comment "Function return type" .
# Annotations
code:hasDocstring a rdf:Property ;
rdfs:domain code:Entity ;
rdfs:range xsd:string .
code:hasComplexity a rdf:Property ;
rdfs:domain code:Function ;
rdfs:range xsd:integer ;
rdfs:comment "Cyclomatic complexity" .
code:hasTestCoverage a rdf:Property ;
rdfs:domain code:Entity ;
rdfs:range xsd:decimal ;
rdfs:comment "Test coverage percentage" .
Example Knowledge Graph Fragment:
# Concrete example: Authentication module
<file:///src/auth/auth_manager.py> a code:Module ;
code:imports <file:///src/core/user.py> ;
code:imports <file:///src/utils/crypto.py> ;
code:contains <class://AuthManager> .
<class://AuthManager> a code:Class ;
code:hasMethod <method://AuthManager.authenticate> ;
code:hasMethod <method://AuthManager.validate_token> ;
code:extends <class://BaseManager> ;
code:hasDocstring "Manages user authentication and session tokens" .
<method://AuthManager.authenticate> a code:Function ;
code:hasParameter <param://username> ;
code:hasParameter <param://password> ;
code:returns <type://AuthToken> ;
code:calls <method://CryptoUtils.hash_password> ;
code:calls <method://UserDB.find_user> ;
code:hasComplexity 8 ;
code:hasTestCoverage 0.95 .
Advanced Graph Queries:
# Find all functions that manipulate user authentication
PREFIX code: <https://cleveragents.ai/ontology/code#>
SELECT ?function ?module
WHERE {
?function a code:Function ;
code:calls*/code:references ?entity .
?entity rdfs:label ?label .
FILTER(CONTAINS(LCASE(?label), "auth") || CONTAINS(LCASE(?label), "user"))
?module code:contains ?function .
}
# Find circular dependencies
SELECT ?module1 ?module2
WHERE {
?module1 code:imports+ ?module2 .
?module2 code:imports+ ?module1 .
FILTER(?module1 != ?module2)
}
# Find most complex untested functions
SELECT ?function ?complexity
WHERE {
?function a code:Function ;
code:hasComplexity ?complexity ;
code:hasTestCoverage ?coverage .
FILTER(?complexity > 10 && ?coverage < 0.5)
}
ORDER BY DESC(?complexity)
LIMIT 10
3. Intelligent Context Assembly Pipeline
The context assembly pipeline leverages all three indices to build optimal context for each agent:
class ContextAssemblyPipeline:
def assemble_context(self,
query: str,
actor_type: str,
resource_scope: List[Resource],
max_tokens: int) -> Context:
# Stage 1: Query Understanding
intent = self.analyze_query_intent(query)
entities = self.extract_entities(query) # Classes, functions, concepts
# Stage 2: Multi-Modal Search
results = SearchResults()
# Text search for exact matches
if intent.needs_exact_match:
text_results = self.text_index.search(
query=query,
filters={"resources": resource_scope},
limit=100
)
results.add(text_results)
# Vector search for semantic similarity
if intent.needs_semantic_match:
query_embedding = self.embed_query(query, actor_type)
vector_results = self.vector_index.search(
embedding=query_embedding,
filters={"resources": resource_scope},
limit=50
)
results.add(vector_results)
# Graph traversal for structural relationships
if entities:
graph_results = self.graph_index.traverse(
start_nodes=entities,
patterns=self.get_patterns_for_actor(actor_type),
max_depth=3,
limit=50
)
results.add(graph_results)
# Stage 3: Relevance Ranking
ranked_results = self.rank_by_relevance(
results=results,
actor_type=actor_type,
query_intent=intent
)
# Stage 4: Context Optimization
context = self.optimize_context(
ranked_results=ranked_results,
max_tokens=max_tokens,
strategy=self.get_strategy_for_actor(actor_type)
)
return context
def get_patterns_for_actor(self, actor_type: str) -> List[GraphPattern]:
"""Different actors need different traversal patterns"""
patterns = {
"strategist": [
"module_dependencies", # Understand architecture
"interface_boundaries", # Find API surfaces
"test_coverage_gaps" # Identify risks
],
"executor": [
"implementation_details", # Get full function bodies
"local_dependencies", # Find what to change
"usage_patterns" # Understand call sites
],
"reviewer": [
"change_impact_analysis", # What could break
"similar_patterns", # Consistency checks
"test_relationships" # Verification paths
]
}
return patterns.get(actor_type, ["general_traversal"])
4. Plugin Architecture for Extensibility
The system is designed for extensibility at every level:
PluginSystem:
# Language-specific analyzers
analyzers:
python:
class: "PythonAnalyzer"
features:
- AST parsing via ast module
- Type inference via mypy
- Import resolution
- Docstring extraction
typescript:
class: "TypeScriptAnalyzer"
features:
- TSC-based parsing
- Type extraction
- Module resolution
- JSDoc parsing
rust:
class: "RustAnalyzer"
features:
- rust-analyzer integration
- Lifetime analysis
- Trait resolution
- Macro expansion
# Custom analyzer example
custom_dsl:
class: "CustomDSLAnalyzer"
config:
grammar: "path/to/grammar.peg"
semantic_rules: "path/to/rules.yaml"
# Index backend providers
backends:
graph:
- name: "blazegraph"
class: "BlazegraphBackend"
scalability: "billions of triples"
features: ["SPARQL", "reasoning", "geospatial"]
- name: "neo4j"
class: "Neo4jBackend"
scalability: "enterprise"
features: ["Cypher", "APOC", "GDS"]
- name: "custom_graph"
class: "MyCustomGraphDB"
config:
connection: "custom://localhost:7687"
vector:
- name: "faiss"
class: "FaissBackend"
scalability: "100M vectors"
features: ["GPU acceleration", "HNSW"]
- name: "qdrant"
class: "QdrantBackend"
scalability: "distributed"
features: ["filtering", "payloads", "snapshots"]
# Embedding model providers
embedders:
- name: "openai"
class: "OpenAIEmbedder"
models: ["text-embedding-3-large", "text-embedding-3-small"]
- name: "local"
class: "LocalEmbedder"
models: ["all-MiniLM-L6-v2", "instructor-xl"]
- name: "custom"
class: "MyFineTunedEmbedder"
model_path: "path/to/model"
5. Agent Skills for Code Intelligence
Agents interact with the code intelligence system through specialized skills:
actors:
code_explorer:
type: tool
config:
tools:
# Semantic code search
- name: search_code_semantically
code: |
# Find code similar to a concept
results = context.code_intelligence.vector_search(
query="validate user input against schema",
scope=input_data.get("scope", "all"),
limit=input_data.get("limit", 10)
)
# Enrich with graph context
for result in results:
dependencies = context.code_intelligence.get_dependencies(
entity=result.entity_id,
depth=2
)
result.context = dependencies
return results
# Structural analysis
- name: analyze_dependencies
code: |
# Use graph store for dependency analysis
module = input_data["module_path"]
# SPARQL query for full dependency closure
query = f'''
PREFIX code: <https://cleveragents.ai/ontology/code#>
SELECT ?dep ?type
WHERE {{
<{module}> code:imports* ?dep .
?dep a ?type .
}}
'''
deps = context.code_intelligence.graph_query(query)
# Compute metrics
return {
"direct_deps": len([d for d in deps if d.distance == 1]),
"transitive_deps": len(deps),
"circular_deps": context.code_intelligence.find_circular_deps(module),
"dependency_graph": deps
}
# Intelligent refactoring assistant
- name: suggest_refactoring_targets
code: |
# Combine all three indices for comprehensive analysis
# 1. Text search for TODO/FIXME/HACK comments
todos = context.code_intelligence.text_search(
pattern="(TODO|FIXME|HACK):",
scope=input_data["scope"]
)
# 2. Graph analysis for high complexity
complex_functions = context.code_intelligence.graph_query('''
SELECT ?func ?complexity ?coverage
WHERE {
?func a code:Function ;
code:hasComplexity ?complexity ;
code:hasTestCoverage ?coverage .
FILTER(?complexity > 15 || ?coverage < 0.3)
}
ORDER BY DESC(?complexity)
''')
# 3. Vector search for code smells
smells = []
for pattern in ["duplicate code", "long method", "large class"]:
similar = context.code_intelligence.find_similar_code(
pattern=pattern,
threshold=0.8
)
smells.extend(similar)
# Synthesize recommendations
return {
"high_priority": complex_functions[:5],
"technical_debt": todos,
"code_smells": smells,
"suggested_order": context.code_intelligence.rank_by_impact(
complex_functions + todos + smells
)
}
6. Real-time Index Synchronization
The system maintains index freshness through immediate, proactive updates:
class IndexSynchronizer:
def __init__(self):
self.file_watcher = FileSystemWatcher()
self.git_monitor = GitChangeMonitor()
self.incremental_indexer = IncrementalIndexer()
def on_resource_added(self, resource: Resource, project: Project):
"""When a resource is added to a project, index it immediately"""
# Full initial indexing - happens once when resource is added
with self.progress_reporter(f"Indexing {resource.name}") as progress:
files = self.scan_resource(resource)
total = len(files)
# Parallel indexing for performance
with ThreadPoolExecutor(max_workers=cpu_count()) as executor:
futures = []
for i, file in enumerate(files):
future = executor.submit(self.index_file_complete, file)
futures.append(future)
progress.update(i / total)
# Wait for all indexing to complete
for future in futures:
future.result()
# Now set up watchers for incremental updates
self.setup_watchers(resource)
# Mark resource as indexed and ready
resource.indexing_status = "ready"
self.notify_agents_index_ready(resource)
# CRITICAL: Agents can now immediately search this resource
# No "warming up" period - indices are complete and ready
def index_file_complete(self, file_path: str):
"""Comprehensive initial indexing of a file"""
# Parse file once
ast = self.parse_file(file_path)
# Update all indices immediately
self.update_text_index(file_path, ast)
self.update_vector_embeddings(file_path, ast)
self.update_graph_triples(file_path, ast)
# Extract and index all metadata
self.index_symbols(file_path, ast)
self.index_dependencies(file_path, ast)
self.index_complexity_metrics(file_path, ast)
def setup_watchers(self, project: Project):
# File system watching for immediate updates
self.file_watcher.watch(
path=project.root_path,
events=["create", "modify", "delete"],
callback=self.on_file_change
)
# Git monitoring for batch updates
self.git_monitor.watch(
repo=project.git_repo,
events=["commit", "merge", "rebase"],
callback=self.on_git_change
)
def on_file_change(self, event: FileEvent):
# Quick incremental update
if event.type in ["create", "modify"]:
# Parse changed file
ast = self.parse_file(event.path)
# Update indices
self.update_text_index(event.path, ast)
self.update_vector_embeddings(event.path, ast)
self.update_graph_triples(event.path, ast)
elif event.type == "delete":
self.remove_from_indices(event.path)
def on_git_change(self, event: GitEvent):
# Batch update for git operations
changed_files = event.get_changed_files()
# Optimize batch processing
with self.batch_updater() as updater:
for file in changed_files:
updater.queue_update(file)
# Process in parallel
updater.execute(parallel=True)
def update_graph_triples(self, file_path: str, ast: AST):
# Generate RDF triples from AST
triples = []
# Module-level triples
module_uri = self.uri_for_file(file_path)
for import_stmt in ast.imports:
imported_uri = self.resolve_import(import_stmt)
triples.append((module_uri, "code:imports", imported_uri))
# Function-level triples
for func in ast.functions:
func_uri = self.uri_for_function(func)
triples.append((module_uri, "code:contains", func_uri))
triples.append((func_uri, "a", "code:Function"))
triples.append((func_uri, "code:hasComplexity", func.complexity))
# Call relationships
for call in func.calls:
called_uri = self.resolve_call(call)
triples.append((func_uri, "code:calls", called_uri))
# Update graph store
self.graph_store.update_triples(triples)
7. Fallback to Traditional Search
When advanced features are unavailable, the system gracefully degrades:
class FallbackSearchProvider:
def search(self, query: str, resources: List[Resource]) -> SearchResults:
# Try advanced search first
try:
if self.vector_index.is_available():
return self.vector_search(query, resources)
except ServiceUnavailable:
pass
# Fallback to graph search
try:
if self.graph_index.is_available():
return self.graph_search(query, resources)
except ServiceUnavailable:
pass
# Ultimate fallback: grep-like text search
return self.basic_text_search(query, resources)
def basic_text_search(self, query: str, resources: List[Resource]):
# Use ripgrep or similar for fast text search
results = []
for resource in resources:
matches = ripgrep.search(
pattern=query,
path=resource.path,
context_lines=3
)
for match in matches:
results.append(SearchResult(
file=match.file,
line=match.line,
content=match.content,
score=1.0 # Basic scoring
))
return results
Index Lifecycle
The system follows a clear lifecycle for index management:
Index Lifecycle:
1_resource_added:
trigger: "agents project add-resource"
action: "Immediate full indexing"
duration: "Depends on size (10K files ~1 minute)"
result: "All indices ready for instant search"
2_code_changed:
trigger: "File modification detected"
action: "Immediate incremental update"
duration: "Milliseconds per file"
result: "Indices stay synchronized"
3_resource_removed:
trigger: "agents project remove-resource"
action: "Immediate index cleanup"
duration: "Seconds"
result: "No stale data in indices"
4_maintenance:
trigger: "Scheduled or manual"
action: "Reindex for consistency"
duration: "Background process"
result: "Indices optimized and verified"
Key Guarantees:
- "No search happens on stale data"
- "No 'index building' delays during agent execution"
- "Changes visible in search immediately"
- "Initial indexing is a one-time cost per resource"
Integration with Context Tiers
The Code Intelligence system directly feeds into the three-tier context architecture:
Context Tier Integration:
hot_tier:
source: "Real-time results from code intelligence"
content:
- Currently edited files
- Direct dependencies
- Immediately relevant functions
warm_tier:
source: "Indexed embeddings and graph queries"
content:
- Recent search results
- Cached graph traversals
- Vector similarity matches
- Active decision contexts
cold_tier:
source: "Historical indices and compressed data"
content:
- Previous plan analyses
- Archived dependency graphs
- Historical refactoring patterns
- Learned codebase conventions
Performance Characteristics
The system maintains pre-computed indices for instant search performance:
Performance Metrics:
initial_indexing_speed:
text_index: "10,000 files/minute"
vector_index: "1,000 files/minute (with GPU)"
graph_index: "5,000 files/minute"
query_performance:
text_search: "< 100ms for 1M files"
vector_search: "< 200ms for 10M embeddings"
graph_traversal: "< 500ms for 3-hop queries"
storage_requirements:
text_index: "~10% of source size"
vector_index: "~1GB per 100K functions"
graph_store: "~100MB per 10K files"
scalability:
max_files: "No hard limit (tested to 10M files)"
max_graph_size: "1B+ triples"
max_vectors: "100M+ embeddings"
Progressive Enhancement Path
Organizations can adopt Code Intelligence features progressively. At each stage, existing resources are reindexed to take advantage of new capabilities:
adoption_stages:
stage_1_basic:
features: ["text search", "file watching"]
requirements: ["ripgrep", "sqlite"]
initial_setup: "Index all text content on resource add"
benefit: "Instant exact-match search"
stage_2_semantic:
features: ["vector embeddings", "similarity search"]
requirements: ["embedding model", "vector DB"]
initial_setup: "Generate embeddings for all code (one-time cost)"
benefit: "Instant semantic similarity search"
stage_3_structural:
features: ["RDF graph", "relationship queries"]
requirements: ["graph database", "language analyzers"]
initial_setup: "Parse and build complete knowledge graph"
benefit: "Instant relationship queries"
stage_4_intelligent:
features: ["ML-driven ranking", "automated analysis"]
requirements: ["GPU", "training data"]
initial_setup: "Pre-compute ML features and rankings"
benefit: "Instant intelligent suggestions"
stage_5_custom:
features: ["Domain-specific ontologies", "Custom analyzers"]
requirements: ["Domain expertise", "Custom development"]
initial_setup: "Build domain-specific indices"
benefit: "Instant domain-aware intelligence"
This Code Intelligence & Context Discovery system ensures that CleverAgents can efficiently work with codebases of any size, providing agents with the contextual understanding they need to make intelligent decisions about code changes, refactoring, and feature development.
Summary of Timing:
- Indexing: Eager (happens immediately when resources are added/changed)
- Searching: Instant (because indices are pre-computed and ready)
- Sandboxing: Lazy (only when execution needs to modify a resource)
- Context Assembly: Real-time (but fast because it queries ready indices)
This design ensures agents never wait for index building during execution, providing a responsive and predictable experience even on massive codebases.
Context
Note: This section describes the high-level context management system. For details on how context is discovered and indexed, see the Code Intelligence & Context Discovery section above.
Context in CleverAgents is not "dump all files into an LLM." It is a system that:
- finds relevant information from resources,
- injects appropriate subsets into each actor/node,
- and scales to large repositories.
Current Reality and Planned Improvements
key concepts:
- There is a global context concept,
- But nodes only see what is injected into their prompts,
- It's functional but not yet elegant,
- A more advanced automated system is planned.
Tiered Context Architecture (Hot/Warm/Cold)
The system uses a sophisticated three-tier memory architecture that enables working with massive codebases without holding everything in memory:
-
Hot context (hot cache) The small set of immediately relevant chunks injected into the current actor prompt. When working on a 50,000 file codebase, hot context focuses on the immediate task (e.g., 10-20 files for a specific refactoring).
-
Warm context Recent decisions and their contexts from this plan tree - quickly accessible. Includes indexed embeddings, vector search results, and graph store representations. Maintains the decision chain that led to the current work.
-
Cold storage Historical decisions from past plans on this codebase - queryable but not in active memory. Long-term storage in SQLite or caching systems containing prior summaries, older plan artifacts, and historical patterns (e.g., "last time we refactored auth, we also had to update these services").
Promotion/demotion behavior:
- System analyzes current query
- Promotes relevant data upward (cold → warm → hot)
- Demotes stale data out of hot to keep prompts tight
- Preserves complete context snapshots for every decision
This architecture leverages the key insight that software development is inherently local - even in huge codebases, individual changes typically touch a bounded set of files. The Decision Tree captures these localities.
Actor-Specific Context Views
A key missing feature identified in the notes is per-actor context views, filtering, relevance, and actor-aware context limits.
The intended direction:
- global context exists at plan level,
- each actor gets a "view" of that context tuned to their role,
- memory may be shared or per-plan depending on design choices.
Actor Context View Service (Proposed)
A dedicated module/service that:
- maintains actor-specific "context views,"
- tracks actor memory and relevance,
- enforces actor-specific limits (tokens, file types, etc.).
Initial Context vs Deep Context
A practical approach mentioned:
- Initial context is high-level (repo tree, language, overview),
- Then the system searches for relevant details iteratively via RAG.
This strongly suggests CleverAgents should define:
- an "initial context recipe" per project type (codebase vs documents vs infra),
- iterative context refinement loops during strategize/execute.
Behavior
Automation Levels
Automation levels determine which phase transitions happen automatically.
Automation Level Modes
| Mode | Behavior |
|---|---|
| Manual | User explicitly triggers: create → use → execute → apply. Every phase transition requires a command. Every decision point pauses for human input. User sees context, alternatives, and recommendation. User provides explicit choice or custom guidance. |
| Review-before-apply | Strategize + Execute happen automatically. AI makes all decisions autonomously. System pauses before Apply to show diff and ask for approval. User can approve, reject, or correct specific decisions. |
| Full automation | System runs all phases automatically end-to-end. AI makes all decisions. Execution proceeds through apply. Human notified of completion. Rollback available if issues detected. |
Progressive Trust Building
New users typically follow this progression:
- Start with manual mode to understand system behavior
- Move to review-before-apply as confidence builds
- Enable full automation for specific task types
- Gradually expand full automation scope
Semantic Escalation
Even in full automation mode, the system understands when it needs help:
class AutonomyController:
def assess_decision_confidence(self, decision, context):
factors = {
'past_success_rate': self.get_historical_success(decision.type),
'codebase_familiarity': self.get_familiarity_score(context.project),
'risk_assessment': self.evaluate_risk(decision),
'invariant_complexity': self.analyze_invariants(decision)
}
confidence = self.compute_confidence(factors)
if confidence < self.threshold:
if self.automation_level == 'full':
# Even in full automation, critical decisions escalate
return RequestHumanGuidance(decision, factors)
return ProceedAutonomously(decision)
Automation Level Hierarchy
Automation levels are determined using this precedence (highest to lowest):
- Plan-level: Explicitly set when using an action on projects
- Session-level: Set for the current session
- Global-level: Persisted application configuration
# Set global automation level (persists across sessions)
agents config set automation-level review-before-apply
# Set session automation level (overrides global for this session)
agents session set automation-level full-automation
# Use action with explicit automation level (overrides session and global)
agents plan use local/my-action --project my-proj --automation-level manual
Automation Level Persistence Rules
-
Global level: Persisted in application configuration. Default is
manualon fresh install. -
Session level: Lives for the duration of the session. Not persisted.
-
Plan level: Once a plan's automation level is determined (at the moment of
use), it is locked to that plan. Even if the session or global level changes later, the plan retains its original automation level. -
Explicit change: A plan's automation level can be changed explicitly after creation:
agents plan set-automation-level <plan_id> full-automation
Subplan Automation Levels
Subplans inherit the parent plan's automation level.
However, if the parent plan's automation level is changed explicitly mid-execution, new subplans will use the new level while already-completed subplans retain their original level.
Granular Automation Flags
For fine-grained control, additional flags can modify behavior:
auto_strategize- Automatically proceed from Action to Strategizeauto_execute- Automatically proceed from Strategize to Executeauto_apply- Automatically proceed from Execute to Applyauto_retry_on_failure- Automatically retry failed phases
This allows combinations like:
- Auto strategize, manual execute, manual apply (for risky infra tasks)
- Auto strategize + execute, manual apply (the review-before-apply pattern)
Validation and Guardrails
Plan generation validation
The validation logic is stubbed and must be implemented. The spec should require:
- validate action schema
- validate actor availability
- validate required skills exist
- validate permission policy
- validate rollback feasibility (if enabled)
- validate project resource accessibility
This prevents "plan runs with fake providers" and other surprises.
Cost / rate limits
Future concerns:
- API call limits
- cost caps
So CleverAgents should define:
- per-plan budgets
- per-session budgets
- per-org budgets
- per-actor max tool calls / max retries
Correcting Plans (Core Feature)
Correcting plans is where CleverAgents becomes more than "a fancy prompt runner."
The Goal
When a plan makes a wrong decision early, we want to:
- correct the decision,
- recompute only the affected subtree,
- preserve unaffected work.
This is explicitly described: "redo everything below that decision, not the entire code base."
Decision Tree Representation
Every plan records (see Decision Data Model section):
- decisions (choice points) - created during Strategize
- dependencies (which later work depended on that decision)
- child plans spawned because of that decision - populated during Execute
- artifacts generated under that branch
This makes plan runs auditable and correctable.
Two Correction Modes
- Revert-from-history correction (
--mode=revert)
- Find the decision point in the tree
- Roll back all changes (code and non-code) to that point
- Re-run from that decision point forward
- Keep old execution artifacts for comparison
- Potentially expensive if high up in the tree
- Add-at-end correction (
--mode=append)
- Leave history intact
- Append a new plan at the end that fixes the outcome
- Cheaper and safer sometimes
- Does not rewrite history
Correction Flow (Revert Mode)
When user requests correction at Decision B:
-
Mark for Correction
Decision B.superseded_by = new_decision_id -
Identify Downstream Impact
- Recursively collect all decisions that depend on Decision B
- Collect all subplans spawned from those decisions
- These form the "affected subtree"
-
Rollback Resources
- For each affected decision's
artifacts_produced:- Rollback to the checkpoint before that artifact was created
- For affected subplans:
- Rollback their sandboxes entirely
- For each affected decision's
-
Preserve for Comparison
- Archive the original subtree's artifacts
- Create a
CorrectionAttemptrecord linking old and new
-
Re-execute from Decision Point
- Restore context to
Decision B.context_snapshot - User provides new guidance/correction
- Re-run execution from that point
- New decisions get
is_correction: true, corrects_decision_id: B
- Restore context to
-
Apply as Normal
- The corrected plan goes through normal Apply gating
- Diff shows changes from the correction
History Cleanup
History can only be flagged for cleanup after a plan is Applied.
Once a plan is applied:
- It can no longer be rolled back
- Old correction artifacts can be archived or deleted based on retention policy
- The decision tree is preserved for audit purposes
CLI Commands for Correction
# View decision tree
agents plan tree <plan_id>
agents plan tree <plan_id> --format=json # For visualization tools
# Inspect a specific decision
agents plan explain <decision_id>
# Shows: question, chosen option, alternatives, rationale, downstream impact
# Correct via revert-and-replay
agents plan correct <decision_id> --mode=revert --guidance "<what the decision should be>"
# Re-executes from that point with the new guidance
# Correct via append (add fix at end)
agents plan correct <decision_id> --mode=append --guidance "<description of the fix>"
# Creates a new subplan to fix the outcome without rewriting history
# For long guidance text, use a file
agents plan correct <decision_id> --mode=revert --guidance-file ./correction.txt
# Compare old vs new after correction
agents plan diff <correction_attempt_id>
Correction Safety
Corrections always:
- Create a new attempt revision (increment
plan.attempt) - Preserve old artifacts for diff/compare
- Run execute in sandbox again
- Require apply gating again
- Never modify already-applied changes
This keeps history reproducible and prevents accidental destructive edits.
Human-in-the-Loop Collaboration
Even though the direction is "more autonomous," the transcript explicitly recognizes that real workflows require engineers to collaborate with the system, editing code while it works, and using better UX integration (TUI/web/IDE).
So CleverAgents should aim for:
- visibility: what is it doing now?
- interruptibility: pause/cancel/retry
- editability: allow user to modify strategy before execute
- reconciliation: detect if user changed sandbox files mid-run and handle it
UI / Interaction Model
CLI-first + TUI + Web App + IDE
The system intends to be CLI-first, with:
- a TUI built using Textual,
- which can generate a web app "for free,"
- and later an IDE plugin that embeds the TUI in the IDE.
This implies a "single UI codebase" model:
- same underlying view logic,
- multiple frontends.
Plan Tree Visualization
The TUI should show:
- plan list
- plan details
- plan tree (ASCII)
- diff view
- approvals
And should later allow exporting the tree as image (PNG) or JSON for other visualization tools.
Additional Recommended Sections (Missing from Draft but Important)
Storage and Persistence
CleverAgents should define where each concept lives:
- Actions: stored in a registry (local files or server DB)
- Actors: stored similarly (config files + DB indexing)
- Projects: stored locally or on server
- Plans: stored in plan DB with full logs
- Context indexes: vector store / graph store / SQLite
- Artifacts: filesystem or object storage
Observability
To debug large plans:
- every phase should emit events
- every actor call should log prompt/context references
- every skill call should log resource access
- every checkpoint should be recorded
Security Model
- sandbox isolation
- resource-level ACLs
- prompt injection mitigations (server mode)
- secret management (API keys, DB credentials)
- audit logs for apply
Extensibility
- plugin system for skills
- custom node types
- action templates
- actor templates (noted as missing currently)
Summary of Key Intended Behaviors (If You Only Read One Section)
- Plans follow Action → Strategize → Execute → Apply with automation levels controlling transitions.
- Strategize is read-only and produces a strategy + blueprint.
- Execute happens in a sandbox, can spawn subplans, and should support checkpoints/rollback when enabled.
- Apply commits changes from sandbox to real project after review/validation.
- Actors are hierarchical: an actor can be a single agent or an entire graph.
- Graph nodes can be actors, MCP skills, or custom tool nodes.
- Context should evolve toward hot/warm/cold tiers and actor-specific context views.
- The system is designed for large tasks where the user can correct a decision and only recompute downstream work, visualizable as a plan decision tree.
The system can handle Firefox-scale projects not through magic, but through:
- Hierarchical decomposition breaking massive tasks into bounded work
- Persistent decision graphs maintaining context across any scale
- Isolated execution preventing cascading failures
- Semantic validation catching errors before propagation
- Progressive automation building trust through incremental success
Future details to add to this document:
- a canonical JSON/YAML schema for Actions, Actors, Projects, Plans, Skills, and Context Views,
- a CLI command reference (every command, flags, examples),
- and a set of end-to-end example workflows (single project, multi-project, infra task, paper-writing task) consistent with this spec.
Work Remaining to Make CleverAgents Fully Functional
This section describes what remains to be done to bring the current CleverAgents codebase up to the specification.
Last Updated: February 6, 2026
Current State Assessment
What's Implemented
Based on analysis of the current codebase:
- Plan Lifecycle Foundation - The 4-phase lifecycle (Action → Strategize → Execute → Apply) is partially implemented in
plan_lifecycle_service.py - Database Models - Models exist for projects, plans, contexts, changes, and actors
- LangGraph Integration - Graph-based workflow support exists but is not fully connected to the plan workflow
- Reactive System - A reactive system with stream routing is present
- Actor System - Actor models and services exist but lack full behavioral definitions
- Basic Context Analysis - Simple context loading and analysis capabilities
- Change Tracking - Basic
ChangeandChangeSetmodels exist
What's Missing
Critical gaps between the specification and current implementation:
- No Resource Abstraction - The unified resource layer for files, databases, APIs is entirely missing
- No Sandboxing - Execute phase writes directly to files without isolation
- No Decision Tree - No decision tracking, storage, or correction mechanism
- No Skills/MCP Integration - No skill abstraction or MCP protocol support
- Single-File Limitation - Hard-coded to generate exactly one file per plan
- Text-Based Code Generation - Still parsing LLM output instead of tool-based approach
- No Checkpointing - No rollback or checkpoint capabilities
- No Code Intelligence - Missing indexing, vector search, and RDF graph store
- No Context Tiers - No hot/warm/cold memory architecture
- Limited Validation - Basic stub validation instead of semantic checks
Work Items by Priority
1) Implement Tool-Based Resource Modification (Critical Foundation)
Problem
The current system generates code as a single text blob that gets written to one file. The specification requires a modern tool-based approach where LLMs invoke discrete operations on resources.
Implementation Steps
-
Create Resource Abstraction Layer
# New modules needed: src/cleveragents/domain/models/resources.py src/cleveragents/domain/resources/handlers.py src/cleveragents/domain/resources/sandbox.py -
Implement Built-in Skills
# Core file operations read_file(path: str) -> str write_file(path: str, content: str) -> None edit_file(path: str, changes: list[Edit]) -> None delete_file(path: str) -> None move_file(src: str, dst: str) -> None create_directory(path: str) -> None list_files(pattern: str) -> list[str] search_files(pattern: str, content_pattern: str) -> list[Match] -
Connect Skills to ChangeSet
- Each skill invocation that modifies resources creates a
Changerecord - ChangeSet accumulates these changes during execution
- No more parsing LLM text output for code
- Each skill invocation that modifies resources creates a
Estimated Effort: 2-3 weeks
2) Implement Sandbox Infrastructure (Critical for Safety)
Problem
Execute phase currently writes directly to the project. The specification requires all changes happen in an isolated sandbox that can be reviewed before applying.
Implementation Steps
-
Define Sandbox Interface
class Sandbox(Protocol): def create() -> SandboxRef def read(path: str) -> Content def write(path: str, content: Content) -> Change def diff() -> DiffView def commit() -> None def rollback() -> None -
Implement Sandbox Strategies
GitWorktreeSandbox- For git repositories (preferred)FilesystemCopySandbox- For non-git projectsTransactionSandbox- For databasesNoOpSandbox- For non-sandboxable resources
-
Lazy Sandbox Creation
- Only create sandboxes when resources are accessed
- Each plan gets its own sandbox namespace
Estimated Effort: 2 weeks
3) Build Decision Tree System (Core Innovation)
Problem
No decision tracking exists. The specification's key innovation is recording every decision with full context, enabling correction without full re-execution.
Implementation Steps
-
Create Decision Models
-- New tables needed CREATE TABLE decisions ( decision_id TEXT PRIMARY KEY, -- ULID plan_id TEXT NOT NULL, parent_decision_id TEXT, decision_type TEXT NOT NULL, question TEXT NOT NULL, chosen_option TEXT NOT NULL, alternatives_considered TEXT, -- JSON array context_snapshot TEXT NOT NULL, -- JSON created_at TEXT NOT NULL ); -
Implement Decision Recording
- Every choice during Strategize creates a Decision record
- Capture complete context snapshot with each decision
- Track downstream dependencies
-
Build Correction Mechanism
agents plan correct <decision_id> --mode=revert --guidance "<new decision>"- Mark decision as superseded
- Recompute only affected subtree
- Preserve unaffected work
Estimated Effort: 3 weeks
4) Implement Code Intelligence System (Scalability Enabler)
Problem
Current context is limited to a few hundred characters from a few files. Large codebases require intelligent context discovery.
Implementation Steps
-
Eager Indexing on Resource Add
def on_resource_added(resource: Resource): # Index immediately when resource added to project index_text_content(resource) # Full-text search generate_embeddings(resource) # Vector embeddings build_knowledge_graph(resource) # RDF triples -
Three-Index Architecture
- Text Index: Tantivy/SQLite FTS for exact matches
- Vector Index: FAISS/Qdrant for semantic search
- Graph Store: RDF store for relationships
-
Tiered Context System
- Hot: Current working set (in LLM context)
- Warm: Recent decisions and search results
- Cold: Historical data and patterns
Estimated Effort: 4 weeks
5) Complete Actor System with Behavioral Definitions
Problem
Actors exist but don't define behavior beyond model selection. The specification requires actors to be composable graphs with tools, memory, and context policies.
Implementation Steps
-
Extend Actor Configuration
actors: my_strategist: type: graph config: provider: anthropic model: claude-3-opus tools: [read_file, search_code, analyze_dependencies] memory_policy: per_plan context_view: architect # High-level view routes: strategize: entry_point: analyze nodes: - name: analyze type: llm - name: plan type: llm -
Implement Tool Access Policies
- Strategy actors: read-only tools
- Execute actors: read/write within sandbox
- Apply actors: commit tools
-
Actor-Specific Context Views
- Strategist: Architecture, dependencies, patterns
- Executor: Implementation details, specific files
- Reviewer: Diffs, tests, risk analysis
Estimated Effort: 2 weeks
6) MCP Integration and Skill System
Problem
No skill abstraction exists. The specification extends MCP for both read and write operations.
Implementation Steps
-
MCP Tool Adapter
class MCPSkillAdapter: def wrap_mcp_tool(self, tool) -> Skill: # Add sandbox interception # Add change tracking # Add capability metadata -
Skill Capability Metadata
class SkillMetadata: read_only: bool write_scope: list[str] checkpointable: bool idempotent: bool side_effects: list[str] -
External MCP Server Support
mcp_servers: - name: github command: "npx @anthropic/mcp-github" env: {GITHUB_TOKEN: "${GITHUB_TOKEN}"}
Estimated Effort: 2 weeks
7) Implement Validation and Semantic Error Prevention
Problem
Current validation is a stub. The specification requires multi-layer semantic validation.
Implementation Steps
-
Decision-Time Validation
- Validate choices during Strategize
- Check alternatives for feasibility
- Record validation in decision metadata
-
Execution-Time Guards
nodes: - name: semantic_validator type: tool tools: - validate_api_compatibility - check_invariants - verify_test_coverage -
Project-Specific Validation
agents project set-validation \ --project my-api \ --test-command "pytest" \ --lint-command "ruff check ."
Estimated Effort: 2 weeks
8) Connect LangGraph to Plan Lifecycle
Problem
The reactive/LangGraph infrastructure exists but isn't connected to the main plan workflow.
Implementation Steps
-
Create Unified Plan Graph
class PlanLifecycleGraph: def strategize_subgraph(self) -> StateGraph def execute_subgraph(self) -> StateGraph def apply_subgraph(self) -> StateGraph -
Wire Phase Transitions
usecommand triggers strategize graphexecutecommand triggers execute graphapplycommand triggers apply graph
-
Remove Linear Pipeline
- Replace tell/build/apply with graph execution
- Maintain backward compatibility at CLI level
Estimated Effort: 1 week
Implementation Roadmap
Phase 1: Foundation (6-8 weeks)
- Resource abstraction and built-in skills
- Sandbox infrastructure
- Connect LangGraph to lifecycle
Phase 2: Core Features (8-10 weeks)
- Decision tree system
- Code intelligence (basic text/vector search)
- MCP integration
Phase 3: Advanced Features (4-6 weeks)
- Complete actor behavioral system
- Semantic validation layers
- Advanced code intelligence (RDF graph)
Phase 4: Production Hardening (4 weeks)
- Checkpointing and rollback
- Cost controls and rate limiting
- Security fixes (remove eval, fix async)
Total Estimated Timeline: 5-6 months
Key Success Metrics
- Multi-file generation: Can generate a REST API with routes/, models/, tests/
- Safe execution: All changes happen in sandbox, reviewed before apply
- Decision correction: Can correct a decision and recompute only affected work
- Scale to large codebases: Can work with 10K+ file projects efficiently
- Semantic safety: Catches breaking changes before they're applied
Migration Strategy
The implementation can proceed incrementally:
- Start with resource abstraction (enables everything else)
- Add sandboxing to existing execute phase
- Gradually replace text parsing with tool invocations
- Build decision tree alongside existing flow
- Enhance context as indexing comes online
This allows the system to remain functional during development while progressively adding the architectural improvements described in the specification.
CleverAgents Architecture FAQ
Q: How does CleverAgents handle persistent repository knowledge beyond ephemeral context windows?
What exists today architecturally: The specification defines a sophisticated multi-tier memory system that goes far beyond ephemeral context windows. At its core is the Decision Tree structure which provides a durable, queryable record of every choice made during planning, along with the complete context that informed those choices.
How the persistent model works in practice:
When a strategy actor analyzes a codebase during the Strategize phase, it doesn't just make decisions in isolation. Each decision creates a comprehensive Decision record that includes:
context_snapshot:
hot_context_hash: str # Cryptographic hash of the exact context
hot_context_ref: str # Pointer to the full stored snapshot
relevant_resources: list[ResourceRef] # Every file/symbol that influenced this decision
actor_state_ref: str # Complete LangGraph checkpoint
This means when the system decides "refactor the authentication module to use async patterns," it permanently records:
- Which files were examined to make that decision
- What symbols and dependencies were traced
- The exact code state that was analyzed
- The reasoning chain that led to this choice
- Alternative approaches that were considered but rejected
The three-tier memory architecture enables scale:
- Hot tier: Immediate working context (what's in the current LLM context window)
- Warm tier: Recent decisions and their contexts from this plan tree - quickly accessible
- Cold tier: Historical decisions from past plans on this codebase - queryable but not in active memory
When working on a 50,000 file codebase, the system doesn't need to hold all files in memory. Instead:
- Hot context focuses on the immediate task (e.g., 10-20 files for a specific refactoring)
- Warm context maintains the decision chain that got us here
- Cold context provides historical patterns ("last time we refactored auth, we also had to update these services")
Why this scales to massive codebases:
The key insight is that software development is inherently local - even in huge codebases, individual changes typically touch a bounded set of files. The Decision Tree captures these localities. When converting Firefox to Rust (your example), the system would:
- Make high-level architectural decisions (captured as root decision nodes)
- Decompose into major subsystem conversions (each a decision spawning subplans)
- Each subsystem plan makes decisions about its modules
- Module plans make decisions about individual files
At each level, only the relevant context is loaded. The persistent decision graph means we can always reconstruct why we're converting a particular module and what constraints apply from higher-level decisions.
Concrete example of persistence in action:
Plan: Convert Firefox Renderer to Rust
├── [Decision] Architecture approach: Start with leaf modules, work inward
│ Context: Analyzed module dependency graph, 2,847 modules total
│ Resources: module_graph.json, architecture_docs.md
│
├── [Decision] Phase 1: Convert utility libraries (no external deps)
│ └── [Subplan] Convert string_utils module
│ ├── [Decision] Use Rust's String type, not custom implementation
│ │ Context: Analyzed 47 string_utils.cpp functions
│ │ Resources: string_utils.cpp, string_utils.h, 12 dependent files
│ │ Rationale: Rust's String provides same guarantees with better ergonomics
Even months later, we can query: "Why did we use Rust's String type?" and get the exact context and reasoning, without reprocessing the entire codebase.
Q: How does the system compute task-specific dependency closures for large-scale operations?
What exists today architecturally: The specification defines multiple mechanisms for computing and maintaining minimal dependency closures. The execution blueprint produced during the Strategize phase doesn't just list steps - it includes a complete dependency graph with explicit scoping for each operation.
How dependency closure computation works:
During the Strategize phase, the strategy actor employs several mechanisms to compute precise dependency closures:
-
Resource-aware analysis: The actor uses specialized skills to trace dependencies:
# Pseudocode of what happens inside a strategy actor def compute_closure_for_refactoring(target_module): closure = ResourceClosure() # Direct file dependencies closure.add_files(find_imports(target_module)) closure.add_files(find_includes(target_module)) # Symbol dependencies for symbol in extract_exported_symbols(target_module): closure.add_files(find_symbol_usage(symbol, scope='project')) # Test dependencies closure.add_files(find_tests_for_module(target_module)) # Build system dependencies closure.add_files(find_build_references(target_module)) return closure -
Hierarchical scoping: When spawning subplans, each subplan receives:
- An explicit
relevant_resourceslist - A
sandbox_strategyappropriate for those resources - Clear boundaries of what it can and cannot modify
- An explicit
-
Decision-based tracking: Each
subplan_spawndecision records:decision_type: subplan_spawn chosen_option: "Refactor authentication module" downstream_plan_ids: ["plan-auth-refactor-123"] artifacts_produced: - auth_module_files: ["auth.rs", "auth_test.rs", "auth_types.rs"] - api_updates: ["api/v2/login.rs", "api/v2/logout.rs"]
Concrete example - Converting a subsystem to Rust:
Let's trace how the system handles "Convert Firefox's Network Stack to Rust":
STRATEGIZE PHASE:
1. Analyze network stack structure
- Identifies 847 C++ files in netwerk/ directory
- Traces public API surface (237 exported functions)
- Maps internal dependencies (1,432 internal calls)
2. Compute minimal closure for Phase 1 (DNS resolver):
- Core files: dns_resolver.cpp, dns_cache.cpp, dns_config.cpp (3 files)
- Direct dependencies: 12 files in netwerk/base/
- Test files: 8 test files specific to DNS
- Build files: 2 moz.build files
- Total closure: 25 files (not 847!)
3. Generate execution blueprint with subplans:
- convert-dns-types: Closure of 5 files (type definitions)
- convert-dns-cache: Closure of 8 files (cache + tests)
- convert-dns-resolver: Closure of 12 files (resolver + integration)
Why this is tractable even for massive codebases:
The system leverages several key insights about real software:
- Modular boundaries exist: Even in legacy codebases, there are natural boundaries
- Changes are incremental: We don't convert 50,000 files atomically
- Dependencies are sparse: Most modules depend on a small fraction of the codebase
- Interfaces are narrow: Public APIs are much smaller than implementations
The Firefox example would decompose into ~1,000 bounded subplans, each touching 10-100 files. The parent plan tracks the overall architecture, while each subplan maintains its focused closure.
How we prevent closure explosion:
- Lazy expansion: Dependencies are traced only as deep as needed for correctness
- Interface-based boundaries: When possible, work against stable interfaces
- Incremental validation: Each subplan validates its changes don't break dependents
- Hierarchical merge strategies: Parent plans resolve conflicts between subplan changes
Q: What mechanisms enforce global consistency during parallel execution across many files?
What exists today architecturally: The sandbox model combined with hierarchical plan execution provides strong guarantees about consistency during parallel execution. This isn't just process isolation - it's semantic isolation with intelligent merge strategies.
How the coordination mechanism prevents compound errors:
-
Complete isolation during execution: Each plan executes in its own sandbox, which means:
Plan A (refactoring auth module): - Sandbox A1: Contains only auth/*.cpp, auth_tests/*.cpp - Cannot see Plan B's intermediate states - Cannot accidentally depend on Plan B's half-done work Plan B (updating API endpoints): - Sandbox B1: Contains only api/*.cpp, api_tests/*.cpp - Makes changes assuming current auth interface - Protected from Plan A's intermediate refactoring -
Resource-specific sandbox strategies provide natural coordination:
Git repositories: - Strategy: git worktrees - Coordination: Git's three-way merge algorithm - Conflict detection: Built into Git - Rollback: git reset/checkout Databases: - Strategy: Transaction isolation - Coordination: MVCC (multi-version concurrency control) - Conflict detection: Serialization failures - Rollback: Transaction abort Cloud Infrastructure: - Strategy: Terraform workspaces - Coordination: State locking - Conflict detection: Resource conflicts in plan - Rollback: Previous state restoration -
Hierarchical merge resolution: When subplans complete, the parent plan performs intelligent merging:
def merge_subplan_results(subplan_results): # Group by resource type by_resource = group_by_resource_type(subplan_results) # Apply resource-specific merge strategies for resource_type, changes in by_resource: if resource_type == 'git_repo': merge_git_changes(changes) # Three-way merge elif resource_type == 'database': merge_db_changes(changes) # Sequential application elif resource_type == 'config_files': merge_config_changes(changes) # Smart JSON/YAML merge # Validate merged state run_integration_tests()
Concrete example - Preventing cascading failures:
Consider refactoring a shared authentication library used by 15 services:
PARALLEL EXECUTION WITHOUT COORDINATION (what we prevent):
- Service A refactors to async auth → breaks Service B
- Service B compensates with workaround → breaks Service C
- Service C changes error handling → breaks Services D, E, F
- Cascade of failures!
CLEVERAGENTS COORDINATED EXECUTION:
Parent Plan: Refactor auth library
├── Subplan 1: Update auth library interface
│ Sandbox: Only auth library files
│ Output: New interface definition
│
├── Barrier: Wait for Subplan 1 completion
│
├── Parallel Subplans 2-16: Update each service
│ Each sandbox: Only that service's files
│ Each uses: New interface from Subplan 1
│ No inter-service dependencies during execution
│
└── Merge Phase:
- Collect all service updates
- Apply to main branch in order
- Run integration tests
- If conflicts: Parent plan resolves using semantic understanding
Advanced coordination patterns:
-
Optimistic concurrency with semantic conflict resolution:
Two subplans both modify api/user.rs: - Plan A: Adds async fn get_user_profile() - Plan B: Adds fn validate_user_permissions() Merge strategy: - Git merge succeeds (different functions) - Semantic validation ensures both functions work together - Parent plan adds integration glue if needed -
Checkpoint-based coordination:
Execution timeline: T1: Subplan A creates checkpoint before major refactor T2: Subplan B creates checkpoint before API changes T3: Subplan A encounters error, rolls back to T1 T4: Subplan B completes successfully T5: Subplan A retries with knowledge of B's success -
Resource locking for critical sections:
When modifying shared schema files: - Acquire exclusive lock on schema resources - Make changes atomically - Release lock with new version - Other plans rebase on new schema
Q: How does the system proactively prevent semantic errors before they propagate?
What exists today architecturally: The specification defines multiple layers of proactive error prevention that go far beyond traditional testing. This is a comprehensive defense-in-depth approach that catches semantic errors before they can propagate.
Layer 1: Decision-time validation during Strategize:
Every decision includes semantic validation:
Decision: Refactor payment module to async
alternatives_considered:
- "Convert to async/await patterns" (chosen)
- "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem)
- "Keep synchronous with timeout" (rejected: doesn't solve core latency issue)
confidence_score: 0.85
validation_performed:
- Checked all payment API consumers can handle async
- Verified database driver supports async operations
- Confirmed no regulatory requirement for sync processing
Layer 2: Execution-time semantic guards:
The execution actor configuration includes validation nodes that understand semantics:
actors:
code_executor:
type: graph
nodes:
- name: semantic_validator
type: tool
config:
tools:
- name: validate_api_compatibility
code: |
# Not just syntax checking - semantic validation
old_api = extract_api_signature(previous_version)
new_api = extract_api_signature(current_version)
breaking_changes = find_breaking_changes(old_api, new_api)
if breaking_changes:
# Don't just fail - understand the impact
affected_consumers = find_api_consumers(breaking_changes)
migration_plan = generate_migration(breaking_changes)
if can_auto_migrate(affected_consumers, migration_plan):
apply_migration(migration_plan)
else:
raise SemanticError(
"Breaking API changes require manual review",
changes=breaking_changes,
affected=affected_consumers
)
Layer 3: Invariant enforcement through the type system:
# The system maintains semantic invariants
class RefactoringInvariants:
# User-defined invariants for the codebase
invariants = [
"All public APIs must maintain backward compatibility",
"Database transactions must complete within 5 seconds",
"Authentication must always use OAuth2",
"Payment processing must be idempotent"
]
def check_invariant_preservation(self, changes):
for invariant in self.invariants:
if not self.verify_invariant(invariant, changes):
return InvariantViolation(invariant, changes)
return Success()
Layer 4: Predictive error prevention through pattern matching:
The system learns from past failures:
Error Pattern Database:
- pattern: "Async conversion in payment module"
historical_failures:
- "Race condition in payment confirmation"
- "Timeout handling breaks idempotency"
preventive_checks:
- "Add explicit transaction boundaries"
- "Verify idempotency keys are preserved"
- "Check distributed lock acquisition"
Concrete example - Preventing a subtle distributed systems bug:
Scenario: Refactoring a service to use event sourcing:
PROACTIVE CONTAINMENT IN ACTION:
1. Strategy Phase Semantic Analysis:
- Decision: "Convert order service to event sourcing"
- Semantic check: "Event sourcing requires eventual consistency"
- Identifies: 3 services assume immediate consistency
- Adds decision: "Update dependent services for eventual consistency"
2. Execution Phase Invariant Checking:
- Detects: PaymentService.chargeCard() called after OrderCreated event
- Semantic issue: Payment before order confirmation violates business rules
- Automatic fix: Insert OrderConfirmed event requirement
3. Validation Node Catches Edge Case:
- Discovers: Audit service expects synchronous order numbers
- Impact: Async events break compliance reporting
- Resolution: Add audit event buffer with guaranteed ordering
4. Pre-Apply Semantic Verification:
- Simulates production event flow
- Detects: Under high load, events can arrive out of order
- Adds: Event ordering guarantees via vector clocks
Why this prevents issues that traditional testing misses:
Traditional tests check "does the code work?" Our semantic containment asks:
- Does it preserve business invariants?
- Does it maintain architectural patterns?
- Does it respect distributed systems principles?
- Does it handle the edge cases we've seen before?
Integration with Definition of Done (DoD):
Each plan's DoD includes semantic requirements:
definition_of_done:
must:
- "All API changes maintain backward compatibility"
- "No increase in p99 latency"
- "Audit trail remains complete"
should:
- "Improve code coverage by 10%"
- "Reduce cyclomatic complexity"
may:
- "Optimize for memory usage"
The validation nodes enforce these semantics, not just test passage.
Q: How does the system balance human supervision with autonomous operation?
What exists today architecturally: The specification defines a sophisticated gradation of automation levels that precisely controls when human intervention is needed. This isn't a binary human/AI split - it's a spectrum that can be adjusted per task, per project, or per organization.
How the automation levels work in practice:
Manual Mode:
- Every decision point pauses for human input
- User sees: Context, alternatives, recommendation
- User provides: Explicit choice or custom guidance
- Use case: Critical production changes, learning new codebases
Review-before-apply Mode:
- AI makes all decisions autonomously
- Execution completes in sandbox
- Human reviews complete diff before apply
- User can: Approve, reject, or correct specific decisions
- Use case: Normal feature development, refactoring
Full Automation Mode:
- AI makes all decisions
- Execution proceeds through apply
- Human notified of completion
- Rollback available if issues detected
- Use case: Routine updates, test generation, documentation
The decision correction mechanism enables progressive automation:
The agents plan correct command is crucial for building trust:
# User observes AI made suboptimal choice
agents plan tree <plan_id>
# Sees: [Decision] "Use REST API for service communication"
# User knows gRPC would be better for this use case
agents plan correct <decision_id> --mode=revert \
--guidance "Use gRPC instead of REST. This service requires streaming
updates and binary protocol efficiency. Set up protocol
buffer definitions and generate client/server stubs."
# System:
# 1. Marks original decision as superseded
# 2. Creates new decision with user guidance
# 3. Recomputes ONLY affected downstream decisions
# 4. Preserves all unrelated work
Progressive trust building through automation levels:
New users typically follow this progression:
- Start with manual mode to understand system behavior
- Move to review-before-apply as confidence builds
- Enable full automation for specific task types
- Gradually expand full automation scope
Real autonomy through semantic understanding:
True autonomy isn't about removing humans - it's about the system understanding when it needs help:
class AutonomyController:
def assess_decision_confidence(self, decision, context):
factors = {
'past_success_rate': self.get_historical_success(decision.type),
'codebase_familiarity': self.get_familiarity_score(context.project),
'risk_assessment': self.evaluate_risk(decision),
'invariant_complexity': self.analyze_invariants(decision)
}
confidence = self.compute_confidence(factors)
if confidence < self.threshold:
if self.automation_level == 'full':
# Even in full automation, critical decisions escalate
return RequestHumanGuidance(decision, factors)
return ProceedAutonomously(decision)
Concrete example - Autonomous handling of a complex refactoring:
Scenario: "Modernize legacy e-commerce system"
INITIAL PLAN (Full Automation Mode):
1. System analyzes 50,000 line codebase
2. Identifies modernization opportunities
3. Creates plan with 47 subplans
AUTONOMOUS EXECUTION WITH SMART ESCALATION:
Subplan 1-15: Update utility functions (executes autonomously)
- Confidence: 0.95 (straightforward transformations)
- Result: Success
Subplan 16: Refactor payment processing
- Confidence: 0.4 (critical business logic)
- Action: ESCALATES to human
- Human provides: "Preserve exact penny rounding behavior"
- Continues autonomously with constraint
Subplan 17-30: UI component updates (executes autonomously)
- Confidence: 0.9 (isolated changes)
- Result: Success
Subplan 31: Database schema migration
- Detects: Would require 6-hour downtime
- Action: ESCALATES to human
- Human provides: "Use online migration with feature flags"
- Re-plans with zero-downtime approach
Subplan 32-47: Complete autonomously
The path to greater autonomy:
The system becomes more autonomous through:
-
Learning from corrections:
- Every correction teaches the system about user preferences
- Patterns emerge: "This team always prefers gRPC for microservices"
- Future decisions incorporate these learnings
-
Building project-specific context:
- Each successful plan adds to project knowledge
- System learns codebase patterns, team conventions, business rules
- Confidence increases with familiarity
-
Hierarchical delegation:
- Proven subplan patterns become fully autonomous
- Human focuses on high-level decisions
- System handles implementation details
-
Semantic safety nets:
- Comprehensive invariant checking reduces risk
- Rollback capabilities provide recovery path
- Humans can trust system won't cause catastrophic failures
Q: What's actually implemented today versus planned for the future?
Concrete implementations in the architecture:
-
Decision Tree with Complete Context Capture
- Full schema defined
- Storage model specified
- Correction mechanism detailed
- Query patterns established
-
Hierarchical Plan/Subplan System
- Spawning mechanism defined
- Execution semantics specified
- Merge strategies documented
- Failure handling described
-
Resource-Aware Sandbox Isolation
- Multiple strategies defined (git worktree, filesystem overlay, transactions)
- Lazy sandboxing for efficiency
- Resource-specific merge algorithms
- Cleanup behavior specified
-
Multi-Layer Error Prevention
- Decision validation during planning
- Semantic validation nodes
- Invariant enforcement
- Definition of Done checking
-
Graduated Automation Controls
- Three levels clearly defined
- Decision correction without full re-execution
- Confidence-based escalation
- Progressive trust building
Near-term implementations (architecture complete, engineering straightforward):
-
Memory Tier Management
- Hot/warm/cold distinction clear
- Context loading patterns defined
- Just needs LRU cache and storage backend
-
Cross-Plan Learning
- Decision history provides training data
- Pattern extraction is standard ML
- Confidence scoring is well-understood
-
Cost/Risk Estimation
- Dedicated estimation actor role defined
- Historical data provides baselines
- Standard prediction problem
-
Extended Validation Patterns
- Pluggable validation architecture
- Project-specific rules as configuration
- Industry patterns can be packaged
Research territory (requires innovation but architecture supports):
-
Optimal Context Selection for 100K+ file codebases
- Current: Heuristic-based selection
- Research: ML-driven relevance ranking
- Architecture supports: Any selection algorithm can plug in
-
Automated Invariant Discovery
- Current: User-defined invariants
- Research: Mining invariants from code patterns
- Architecture supports: Invariants are just validation rules
-
Cross-Project Knowledge Transfer
- Current: Project-specific learning
- Research: Generalized pattern recognition
- Architecture supports: Cold tier can span projects
-
Fully Autonomous Recovery Strategies
- Current: Rollback and retry with guidance
- Research: Automatic error understanding and fixing
- Architecture supports: Recovery is just another plan type
Why we can confidently handle Firefox-scale projects:
The architecture doesn't require magical AI breakthroughs. It requires:
- Hierarchical decomposition: ✓ Fully specified
- Bounded context operations: ✓ Dependency closure computation defined
- Parallel execution with isolation: ✓ Sandbox model complete
- Semantic validation: ✓ Multi-layer approach specified
- Progressive automation: ✓ Automation levels and correction defined
The difference between handling a 1,000 file project and a 100,000 file project is:
- More subplans (hierarchical decomposition handles this)
- Larger cold storage (standard database scaling)
- Better context selection (improves with use but works with heuristics)
- More validation patterns (accumulate over time)
This isn't speculative architecture astronautics - it's applying proven distributed systems principles to AI agent coordination. The innovation is in the integration, not in requiring fundamental breakthroughs.