cleveragents-core/docs/specification/examples.md at fe84c6de8b1be706bc9f417fe3fa823ec809e6b2

cleveragents/cleveragents-core

Fork 3

Files

T

HAL9000 fe84c6de8b

CI / lint (pull_request) Successful in 1m19s

Details

CI / typecheck (pull_request) Successful in 1m37s

Details

CI / quality (pull_request) Successful in 1m35s

Details

CI / security (pull_request) Successful in 1m42s

Details

CI / benchmark-publish (pull_request) Has been skipped

Details

CI / push-validation (pull_request) Successful in 30s

Details

CI / helm (pull_request) Successful in 39s

Details

CI / build (pull_request) Successful in 54s

Details

CI / integration_tests (pull_request) Successful in 3m43s

Details

CI / unit_tests (pull_request) Successful in 4m56s

Details

CI / e2e_tests (pull_request) Successful in 4m26s

Details

CI / docker (pull_request) Successful in 2m2s

Details

CI / coverage (pull_request) Successful in 10m51s

Details

CI / status-check (pull_request) Successful in 3s

Details

docs(specification): split monolithic spec into docs/specification/ directory

Split docs/specification.md (48,071 lines) into docs/specification/ with
10 logical sub-documents: overview.md, cli.md, core-concepts.md,
behavior.md, tui.md, configuration.md, examples.md, architecture.md,
milestones.md, and acms.md. Added index.md as the root entry point.

Updated mkdocs.yml navigation, CONTRIBUTING.md, and all .opencode agent
and skill references to point to docs/specification/ instead of the
monolithic docs/specification.md file.

ISSUES CLOSED: #4749

2026-04-28 14:50:40 +00:00

588 KiB

Raw Blame History

Workflow Examples

This section presents complete, end-to-end workflow examples showing how CleverAgents is used in practice. Each example starts from initial setup and walks through every command and decision point. The examples progress from simple single-action workflows to complex multi-project, multi-actor orchestrations.

Example 1: Hello World — Fix a Single Bug

Scenario: A developer finds a bug in their Python web API where the /health endpoint returns a 500 error instead of 200 when the database connection is unavailable. They want CleverAgents to fix it with full human oversight.

Complexity: Beginner. Single project, single action, manual automation profile.

Step 1: Initialize Environment and Register Resources

# Initialize CleverAgents (first-time setup) $ agents init --yes ╭─ Initialized ────────────────────────────────────────────╮ │ Data Dir: /home/dev/.cleveragents (created) │ │ Config: /home/dev/.cleveragents/config.toml │ │ Database: initialized (schema v3) │ │ Directories: logs, cache, sessions, contexts │ ╰──────────────────────────────────────────────────────────╯

✓ OK Initialized (non-interactive)

# Register the git checkout as a resource $ agents resource add git-checkout local/api-repo \ --path /home/dev/projects/api-service \ --branch main ╭─ Resource ──────────────────────────────────────────╮ │ Name: local/api-repo │ │ ID: 01HXR1A1B2C3D4E5F6G7H8J9K0 │ │ Type: git-checkout │ │ Physical/Virtual: physical │ │ Path: /home/dev/projects/api-service │ │ Branch: main │ │ Created: 2026-02-11 09:15 │ ╰─────────────────────────────────────────────────────╯ ╭─ Auto-discovered Children ─────────────────────────────────────────╮ │ ID Type Status │ │ ─────────────── ────────────── ───────────────── │ │ 01HXR1A1B2C3… git created │ │ 01HXR1A1B2C4… git-remote created │ │ 01HXR1A1B2C5… git-branch created │ │ 01HXR1A1B2C6… fs-directory created │ │ + 32 git-commit resources │ │ + 187 git-tree-entry resources │ │ + 5 fs-directory + 41 fs-file │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Capabilities ─────────────────╮ │ Readable: yes │ │ Writable: yes │ │ Sandboxable: yes │ │ Checkpointable: yes │ │ Sandbox Strategy: git_worktree │ ╰────────────────────────────────╯

✓ OK Resource registered (270 child resources discovered)

# Create the project and link the resource $ agents project create \ --description "REST API service" \ --resource local/api-repo \ local/api-service ╭─ Project Created ──────────────────────────╮ │ Name: local/api-service │ │ Description: REST API service │ │ Type: local │ │ Created: 2026-02-11 09:15 │ ╰────────────────────────────────────────────╯ ╭─ Linked Resources ───────────────────────────────────────╮ │ Name Type Read-Only │ │ ───────────────── ────────────── ───────── │ │ local/api-repo git-checkout no │ ╰──────────────────────────────────────────────────────────╯ ╭─ Defaults ──────────────────────────────╮ │ Sandbox: git_worktree │ │ Validations: 0 │ │ Context Filters: none │ │ Automation Profile: (inherits global) │ ╰─────────────────────────────────────────╯

✓ OK Project created

# Register a required validation (tests must pass) $ agents validation add \ --config validations/unit-tests.yaml \ --required ╭─ Validation Registered ─────────────────────────────────────╮ │ Name: local/unit-tests │ │ Command: pytest tests/ │ │ Description: Unit tests │ │ Mode: required │ │ Timeout: 300s (default) │ ╰─────────────────────────────────────────────────────────────╯ ✓ OK Validation registered # Attach the validation to the project $ agents validation attach --project local/api-service local/unit-tests

✓ OK Validation attached to project local/api-service

Step 2: Create an Action

Create a file actions/fix-bug.yaml:


name: local/fix-bug
description: "Fix a reported bug in the codebase"
long_description: |
  Analyze the bug description, locate the relevant code,
  implement a fix, and add or update tests to cover the fix.
definition_of_done: |
  - The described bug no longer reproduces
  - All existing tests pass
  - At least one new test covers the fixed behavior
  - No unrelated code is modified
strategy_actor: anthropic/claude-3.5-sonnet
execution_actor: anthropic/claude-3.5-sonnet
reusable: true
state: available
args:
  - name: bug_description
    type: string
    required: true
    description: "Description of the bug to fix"
  - name: affected_file
    type: string
    required: false
    description: "File path where the bug is suspected (optional hint)"

# Register the action $ agents action create --config ./actions/fix-bug.yaml ╭─ Action Created ─────────────────────────────╮ │ Name: local/fix-bug │ │ ID: 01HXR1B1C2D3E4F5G6H7I8J9K0 │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Created: 2026-02-11 09:16 │ ╰──────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────╮ │ - The described bug no longer reproduces │ │ - All existing tests pass │ │ - At least one new test covers the fixed behavior │ │ - No unrelated code is modified │ ╰───────────────────────────────────────────────────────╯ ╭─ Arguments ───────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ─────────────── ────── ──────── ────────────────────────────────────── │ │ bug_description string yes Description of the bug to fix │ │ affected_file string no File path where the bug is suspected │ ╰───────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: (inherits global) │ │ Source: default │ ╰───────────────────────────────────────╯ ╭─ Usage ──────────────────────────────────────────────────────────────────╮ │ agents plan use local/fix-bug local/api-service │ │ --arg bug_description="..." │ ╰──────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

Step 3: Create and Execute a Plan

# Bind the action to the project with the manual profile for full oversight $ agents plan use \ --automation-profile manual \ --arg bug_description="The /health endpoint returns HTTP 500 when the database \ connection is unavailable. It should return HTTP 200 with {\"status\": \"degraded\", \ \"database\": \"unavailable\"} instead of crashing." \ --arg affected_file="src/routes/health.py" \ local/fix-bug local/api-service ╭─ Plan Created ──────────────────────────╮ │ Plan ID: 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ Phase: strategize │ │ Action: local/fix-bug │ │ Project: local/api-service │ │ Automation: manual │ │ Attempt: 1 │ ╰─────────────────────────────────────────╯ ╭─ Inputs ──────────────────────────────────────────────────────────────╮ │ - bug_description="The /health endpoint returns HTTP 500 when the │ │ database connection is unavailable. It should return HTTP 200 with │ │ {"status": "degraded", "database": "unavailable"} instead │ │ of crashing." │ │ - affected_file="src/routes/health.py" │ │ - automation_profile=manual │ ╰───────────────────────────────────────────────────────────────────────╯ ╭─ Actors ──────────────────────────────────────╮ │ Strategy: anthropic/claude-3.5-sonnet │ │ Execution: anthropic/claude-3.5-sonnet │ │ Estimation: (none) │ ╰───────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: manual │ │ Source: plan override │ │ Read-Only: no │ ╰───────────────────────────────────────╯ ╭─ Context ─────────────────────────╮ │ Resources: 1 (git-checkout) │ │ Indexed Files: 41 │ │ View: strategize │ │ Hot Token Budget: 8,000 │ ╰───────────────────────────────────╯ ╭─ Next Steps ───────────────────────────────────────╮ │ - agents plan execute 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ - agents plan status 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ - agents plan tree 01HXR1C1D2E3F4G5H6I7J8K9L0 │ ╰────────────────────────────────────────────────────╯

✓ OK Plan created

Because the automation profile is manual, the plan stops and waits after creation. The developer must explicitly trigger each phase.

# Manually trigger Strategize → the strategy actor analyzes the codebase $ agents plan execute 01HXR1C1D2E3F4G5H6I7J8K9L0 ╭─ Execution ─────────────────────────────╮ │ Plan: 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ Phase: strategize │ │ Sandbox: git_worktree │ │ Worker: anthropic/claude-3.5-sonnet │ │ Started: 09:17:02 │ │ Attempt: 1 │ ╰─────────────────────────────────────────╯ ╭─ Sandbox ───────────────────────────────────────────────────────╮ │ Strategy: git_worktree │ │ Path: /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │ │ Branch: cleveragents/plan-01HXR1C1D2 │ │ Status: active │ ╰─────────────────────────────────────────────────────────────────╯ ╭─ Strategy Summary ────────────────╮ │ Decisions: 4 │ │ Invariants: 0 │ │ Planned Child Plans: 0 │ │ Estimated Files: ~2 │ │ Risk: low │ ╰───────────────────────────────────╯ ╭─ Progress ────────╮ │ ✓ Collect context │ │ ✓ Build strategy │ │ • Awaiting review │ ╰───────────────────╯

✓ OK Strategize complete — awaiting manual approval

The strategy actor has read the codebase, identified the relevant files, and produced decisions. Since edit_code is 1.0 (manual), the plan pauses for review:


# Review the decision tree
$ agents plan tree 01HXR1C1D2E3F4G5H6I7J8K9L0
╭─ Decision Tree ───────────────────────────────────────────────────────────────────────────╮
│ Plan: 01HXR1C1D2E3F4G5H6I7J8K9L0                                                          │
│ ├─ [prompt_definition] "Fix /health endpoint to return 200 when DB unavailable"           │
│ ├─ [strategy_choice] "Wrap DB call in try/except, return degraded status" (conf: 0.95)    │
│ ├─ [strategy_choice] "Modify src/routes/health.py only" (conf: 0.91)                      │
│ └─ [strategy_choice] "Add test_health_db_unavailable to tests/test_health.py" (conf: 0.93)│
╰───────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tree Summary ─────────────╮
│ Nodes: 4                   │
│ Depth: 1                   │
│ Child Plans: 0             │
│ Invariants: 0              │
│ Superseded: 0 (hidden)     │
╰────────────────────────────╯
╭─ Decision IDs (for correction) ──────────────────╮
│ Root: 01HXR1D1A2B3C4D5E6F7G8H9                   │
│ Strategy 1: 01HXR1D2A2B3C4D5E6F7G8H9             │
│ Strategy 2: 01HXR1D3A2B3C4D5E6F7G8H9             │
│ Strategy 3: 01HXR1D4A2B3C4D5E6F7G8H9             │
╰──────────────────────────────────────────────────╯
✓ OK Decision tree rendered

# Inspect the main strategy decision in detail $ agents plan explain 01HXR1D2A2B3C4D5E6F7G8H9 ╭─ Decision ──────────────────────────────────────────────────────────────╮ │ ID: 01HXR1D2A2B3C4D5E6F7G8H9 │ │ Type: strategy_choice │ │ Question: How should the /health endpoint handle database failures? │ │ Chosen: Wrap DB call in try/except, return degraded status │ │ Confidence: 0.95 │ │ Plan: 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ Sequence: 1 of 3 │ │ Created: 2026-02-11 09:17 │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Alternatives Considered ──────────────────────────────────────────────────╮ │ 1. Wrap DB call in try/except, return degraded status (chosen) │ │ 2. Add a circuit breaker middleware for all DB-dependent routes │ │ 3. Return HTTP 503 Service Unavailable with retry-after header │ ╰────────────────────────────────────────────────────────────────────────────╯ ╭─ Impact ──────────────────────╮ │ Downstream Decisions: 2 │ │ Downstream Child Plans: 0 │ │ Artifacts Produced: 2 │ │ Correction Impact: low │ ╰───────────────────────────────╯ ╭─ Rationale ──────────────────────────────────────────────────╮ │ The bug description explicitly requires HTTP 200 with a │ │ degraded status JSON body. A try/except around the DB call │ │ in the health endpoint is the minimal, targeted fix. A │ │ circuit breaker would be over-engineering for a single │ │ endpoint. HTTP 503 contradicts the requested behavior. │ ╰──────────────────────────────────────────────────────────────╯ ╭─ Correction ─────────────────────────────────────────────────╮ │ agents plan correct 01HXR1D2A2B3C4D5E6F7G8H9 │ │ --mode revert --guidance "Use a different approach..." │ ╰──────────────────────────────────────────────────────────────╯

✓ OK Decision explained

# Approve and proceed to Execute (manual profile requires explicit trigger) $ agents plan execute 01HXR1C1D2E3F4G5H6I7J8K9L0 ╭─ Execution ─────────────────────────────╮ │ Plan: 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ Phase: execute │ │ Sandbox: git_worktree │ │ Worker: anthropic/claude-3.5-sonnet │ │ Started: 09:18:30 │ │ Attempt: 1 │ ╰─────────────────────────────────────────╯ ╭─ Sandbox ───────────────────────────────────────────────────────╮ │ Strategy: git_worktree │ │ Path: /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │ │ Branch: cleveragents/plan-01HXR1C1D2 │ │ Status: active │ ╰─────────────────────────────────────────────────────────────────╯ ╭─ Progress ────────────────────────────────╮ │ ✓ Collect context (0.4s) │ │ ✓ Modify src/routes/health.py (1.2s) │ │ ✓ Add tests/test_health.py test (2.1s) │ │ ✓ Validate: pytest tests/ (3.8s) │ ╰───────────────────────────────────────────╯

✓ OK Execution complete — awaiting apply

The execution actor worked in the sandbox (git worktree), modifying src/routes/health.py and adding a test in tests/test_health.py. Validations ran automatically within the sandbox and passed.

Step 4: Review and Apply


# Review the changes
$ agents plan diff 01HXR1C1D2E3F4G5H6I7J8K9L0
╭─ Diff Summary ──────────────────────────────────╮
│ Plan: 01HXR1C1D2E3F4G5H6I7J8K9L0                │
│ Project: local/api-service                      │
│ Files Changed: 2                                │
│ Insertions: 19                                  │
│ Deletions: 3                                    │
│ Net Change: +16 lines                           │
╰─────────────────────────────────────────────────╯
╭─ Files ────────────────────────────────────╮
│ Path                     Change  Status    │
│ ───────────────────────  ──────  ────────  │
│ src/routes/health.py     +8 -3   modified  │
│ tests/test_health.py     +11 -0  modified  │
╰────────────────────────────────────────────╯
╭─ Patch Preview ───── │ --- a/src/routes/health.py │ +++ b/src/routes/health.py │ @@ │  @app.get("/health") │  def health_check(): │ - │ - │ + │ + │ + │ + │ + │ --- a/tests/test_health.py │ +++ b/tests/test_health.py │ @@ │ +def │ + │ + │ + │ + │ + │ + │ + │ + ╰───────────

─────────────────────────────────────────────╮ │ │ -8,6 +8,11 @@                                                 │ │ │ db_status = check_database_connection()                     │ return {"status": "ok", "database": db_status}              │ try:                                                        │ db_status = check_database_connection()                 │ return {"status": "ok", "database": "available"}        │ except ConnectionError:                                     │ return {"status": "degraded", "database": "unavailable"}│ │ │ -15,0 +16,11 @@                                               │ test_health_db_unavailable(client, monkeypatch):            │ def mock_check():                                           │ raise ConnectionError("DB unreachable")                 │ monkeypatch.setattr("src.routes.health.check_database…")    │ response = client.get("/health")                            │ assert response.status_code == 200                          │ data = response.json()                                      │ assert data["status"] == "degraded"                         │ assert data["database"] == "unavailable"                    │ ───────────────────────────────────────────────────────╯
╭─ Risk Assessment ────────────────╮
│ API Compatibility: preserved     │
│ Test Coverage: increased         │
│ Breaking Changes: none detected  │
╰──────────────────────────────────╯
✓ OK Diff generated

# Check plan status (should be execute/complete, awaiting apply) $ agents plan status 01HXR1C1D2E3F4G5H6I7J8K9L0 ╭─ Plan Status ───────────────────────────╮ │ Plan: 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ Phase: execute │ │ State: complete │ │ Action: local/fix-bug │ │ Project: local/api-service │ │ Automation: manual │ │ Attempt: 1 │ ╰─────────────────────────────────────────╯ ╭─ Progress ───────────╮ │ ✓ Strategize │ │ ✓ Execute │ │ • Apply (awaiting) │ ╰──────────────────────╯ ╭─ Timing ───────────────────────────╮ │ Started: 2026-02-11 09:17:02 │ │ Elapsed: 00:01:42 │ │ ETA: awaiting manual apply │ ╰────────────────────────────────────╯ ╭─ Execution Detail ──────────╮ │ Sandbox: git_worktree │ │ Tool Calls: 5 │ │ Files Modified: 2 │ │ Child Plans: 0 │ │ Checkpoints: 1 created │ ╰─────────────────────────────╯ ╭─ Cost ───────────────╮ │ Tokens Used: 6,840 │ │ Cost So Far: $0.023 │ │ Estimated: $0.025 │ ╰──────────────────────╯

✓ OK Status refreshed

# Apply the changes to the real repository $ agents plan apply --yes 01HXR1C1D2E3F4G5H6I7J8K9L0 ╭─ Apply Summary ──────────────────────────╮ │ Plan: 01HXR1C1D2E3F4G5H6I7J8K9L0 │ │ Artifacts: 2 files updated │ │ Changes: 19 insertions, 3 deletions │ │ Project: local/api-service │ │ Applied At: 2026-02-11 09:19 │ ╰──────────────────────────────────────────╯ ╭─ Validation ───────────────────╮ │ Tests: passed (14/14) │ │ Duration: 3.8s │ ╰────────────────────────────────╯ ╭─ Sandbox Cleanup ──────────────────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰────────────────────────────────────────╯ ╭─ Plan Lifecycle ──────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:01:58 │ │ Total Cost: $0.025 │ │ Decisions Made: 4 │ │ Child Plans: 0 │ ╰───────────────────────────────────────╯ ╭─ Next Steps ──────╮ │ - Review git diff │ │ - Commit changes │ ╰───────────────────╯

✓ OK Changes applied

The sandbox changes are merged into the main working tree. The bug is fixed.

Example 2: Automated Test Generation for a Module

Scenario: A team wants to increase test coverage for their auth module from 45% to 80%. They trust CleverAgents to generate tests autonomously, but want to review before applying.

Complexity: Intermediate. Single project, trusted automation profile, validation-driven.

Step 1: Setup (Assuming Project Exists)

# Register a coverage validation # (project local/api-service and resource local/api-service-repo already exist) $ agents validation add \ --config validations/auth-coverage.yaml \ --required \ local/auth-coverage ╭─ Validation Registered ──────────────────────────────────────╮ │ Name: local/auth-coverage │ │ Command: pytest --cov=src/auth --cov-fail-under=80 │ │ tests/test_auth/ │ │ Description: Coverage must be at least 80% │ │ Mode: required │ │ Timeout: 600s │ ╰──────────────────────────────────────────────────────────────╯ ✓ OK Validation registered $ agents validation attach --project local/api-service local/auth-coverage ✓ OK Validation attached to project local/api-service

# Automation profile will be set per-plan via --automation-profile on plan use

Step 2: Create the Test Generation Action

Create actions/generate-tests.yaml:


name: local/generate-tests
description: "Generate comprehensive tests for a module"
long_description: |
  Analyze the target module's code paths, identify untested branches,
  edge cases, and error conditions, then generate thorough test cases.
  Uses the project's existing test framework and conventions.
definition_of_done: |
  - Coverage of the target module reaches the specified threshold
  - All new tests pass
  - All existing tests continue to pass
  - Tests follow existing project conventions (fixtures, naming, structure)
  - No production code is modified
strategy_actor: anthropic/claude-3.5-sonnet
execution_actor: anthropic/claude-3.5-sonnet
reusable: true
state: available
read_only: false
args:
  - name: target_module
    type: string
    required: true
    description: "Module path to generate tests for (e.g., src/auth)"
  - name: coverage_target
    type: integer
    required: false
    description: "Target coverage percentage"
    default: 80
invariants:
  - "Do not modify any production code — only add or modify test files"
  - "Follow the existing test file naming convention (test_<module>.py)"
  - "Use the project's existing test fixtures and conftest.py patterns"

$ agents action create --config ./actions/generate-tests.yaml ╭─ Action Created ───────────────────────────────────╮ │ Name: local/generate-tests │ │ ID: 01HXR2B1C2D3E4F5G6H7I8J9K0 │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Config: ./actions/generate-tests.yaml │ │ Created: 2026-02-11 09:15 │ ╰────────────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────────────────╮ │ - Coverage of the target module reaches the specified threshold │ │ - All new tests pass │ │ - All existing tests continue to pass │ │ - Tests follow existing project conventions │ │ - No production code is modified │ ╰───────────────────────────────────────────────────────────────────╯ ╭─ Arguments ───────────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ──────────────── ─────── ──────── ─────────────────────────────────────── │ │ target_module string yes Module path to generate tests for │ │ coverage_target integer no Target coverage percentage (default 80) │ ╰───────────────────────────────────────────────────────────────────────────────╯ ╭─ Invariants ──────────────────────────────────────────────────────────────────╮ │ 1. Do not modify any production code — only add or modify test files │ │ 2. Follow the existing test file naming convention (test_<module>.py) │ │ 3. Use the project's existing test fixtures and conftest.py patterns │ ╰───────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: supervised │ │ Source: default │ ╰───────────────────────────────────────╯

✓ OK Action created

Step 3: Execute

# With trusted profile: Strategize and Execute run automatically, # only Apply requires human approval $ agents plan use \ --automation-profile trusted \ --arg target_module="src/auth" \ --arg coverage_target=80 \ local/generate-tests local/api-service ╭─ Plan Created ──────────────────────────────────────╮ │ Plan: 01HXR2B3C4D5E6F7G8H9J0K1L2 │ │ Phase: strategize │ │ State: processing │ │ Action: local/generate-tests │ │ Project: local/api-service │ │ Automation: trusted │ │ Attempt: 1 │ ╰─────────────────────────────────────────────────────╯ ╭─ Inputs ────────────────────────────╮ │ - target_module=src/auth │ │ - coverage_target=80 │ │ - automation_profile=trusted │ ╰─────────────────────────────────────╯ ╭─ Actors ────────────────────────────────────────╮ │ Strategy: anthropic/claude-3.5-sonnet │ │ Execution: anthropic/claude-3.5-sonnet │ │ Estimation: (none) │ ╰─────────────────────────────────────────────────╯ ╭─ Automation ───────────────────────────╮ │ Profile: trusted │ │ Source: plan override │ │ Read-Only: no │ ╰────────────────────────────────────────╯ ╭─ Context ────────────────────────╮ │ Resources: 1 (repo) │ │ Indexed Files: 214 │ │ View: strategize │ │ Hot Token Budget: 8,000 │ ╰──────────────────────────────────╯ ╭─ Next Steps ─────────────────────────────────────────────────────────╮ │ Trusted profile — strategize and execute will proceed automatically. │ │ - agents plan status 01HXR2B3C4D5E6F7G8H9J0K1L2 │ │ - agents plan tree 01HXR2B3C4D5E6F7G8H9J0K1L2 │ ╰──────────────────────────────────────────────────────────────────────╯

✓ OK Plan created

The system runs through Strategize and Execute automatically. The strategy actor analyzes coverage gaps, identifies 12 untested code paths, and plans test cases. The execution actor writes tests in the sandbox. Validations run. If coverage reaches 80%, the plan reaches execute/complete and waits for apply.

# Check progress while it runs $ agents plan status 01HXR2B3C4D5E6F7G8H9J0K1L2 ╭─ Plan Status ───────────────────────────────╮ │ Plan: 01HXR2B3C4D5E6F7G8H9J0K1L2 │ │ Phase: execute │ │ State: processing │ │ Action: local/generate-tests │ │ Project: local/api-service │ │ Automation: trusted │ │ Attempt: 1 │ ╰─────────────────────────────────────────────╯ ╭─ Progress ───────╮ │ ✓ Strategize │ │ ⏳ Execute │ │ • Apply (queued) │ ╰──────────────────╯ ╭─ Timing ──────────╮ │ Started: 09:15:42 │ │ Elapsed: 00:02:18 │ │ ETA: 00:04:30 │ ╰───────────────────╯ ╭─ Execution Detail ──────────╮ │ Sandbox: git_worktree │ │ Tool Calls: 14 │ │ Files Modified: 5 │ │ Child Plans: 0 │ │ Checkpoints: 3 created │ ╰─────────────────────────────╯ ╭─ Cost ───────────────╮ │ Tokens Used: 18,740 │ │ Cost So Far: $0.062 │ │ Estimated: $0.110 │ ╰──────────────────────╯

✓ OK Status refreshed

# When complete, review the generated tests $ agents plan diff 01HXR2B3C4D5E6F7G8H9J0K1L2 ╭─ Diff Summary ─────────────────────────────────────╮ │ Plan: 01HXR2B3C4D5E6F7G8H9J0K1L2 │ │ Project: local/api-service │ │ Files Changed: 5 │ │ Insertions: 287 │ │ Deletions: 3 │ │ Net Change: +284 lines │ ╰────────────────────────────────────────────────────╯ ╭─ Files ────────────────────────────────────────────────╮ │ Path Change Status │ │ ────────────────────────────── ──────── ────────── │ │ tests/test_auth/test_login.py +72 -0 new file │ │ tests/test_auth/test_tokens.py +68 -0 new file │ │ tests/test_auth/test_session.py +54 -0 new file │ │ tests/test_auth/test_rbac.py +41 -0 new file │ │ tests/test_auth/conftest.py +52 -3 modified │ ╰────────────────────────────────────────────────────────╯ ╭─ Patch Preview ───────────────────────────────────────────╮ │ --- /dev/null │ │ +++ b/tests/test_auth/test_login.py │ │ @@ -0,0 +1,72 @@ │ │ + import pytest │ │ + from src.auth.login import authenticate, verify_mfa │ │ + ... │ │ --- a/tests/test_auth/conftest.py │ │ +++ b/tests/test_auth/conftest.py │ │ @@ -1,5 +1,54 @@ │ │ - # minimal fixtures │ │ + # shared auth test fixtures │ │ + @pytest.fixture │ │ + def mock_user_db(): ... │ ╰───────────────────────────────────────────────────────────╯ ╭─ Risk Assessment ────────────────╮ │ API Compatibility: preserved │ │ Test Coverage: 45% → 83% │ │ Breaking Changes: none detected │ ╰──────────────────────────────────╯

✓ OK Diff generated

$ agents plan artifacts 01HXR2B3C4D5E6F7G8H9J0K1L2 ╭─ Artifacts ──────────────────────────────────────────────────────────╮ │ Path Type Size Change Child Plan │ │ ──────────────────────────────── ───── ────── ────── ─────── │ │ tests/test_auth/test_login.py write 3.8 KB +72 -0 root │ │ tests/test_auth/test_tokens.py write 3.4 KB +68 -0 root │ │ tests/test_auth/test_session.py write 2.7 KB +54 -0 root │ │ tests/test_auth/test_rbac.py write 2.1 KB +41 -0 root │ │ tests/test_auth/conftest.py edit 2.6 KB +52 -3 root │ ╰──────────────────────────────────────────────────────────────────────╯ ╭─ Summary ────────────╮ │ Total: 5 │ │ Writes: 4 (new) │ │ Edits: 1 (modified) │ │ Deletes: 0 │ │ Total Size: 14.6 KB │ ╰──────────────────────╯

✓ OK 5 artifacts listed

# Apply the generated tests to the real repository $ agents plan apply --yes 01HXR2B3C4D5E6F7G8H9J0K1L2 ╭─ Apply Summary ──────────────────────────╮ │ Plan: 01HXR2B3C4D5E6F7G8H9J0K1L2 │ │ Artifacts: 5 files updated │ │ Changes: 287 insertions, 3 deletions │ │ Project: local/api-service │ │ Applied At: 2026-02-11 09:22 │ ╰──────────────────────────────────────────╯ ╭─ Validation ──────────────────────────╮ │ ✓ Coverage: passed (83% ≥ 80%) │ │ ✓ All tests: passed (47/47) │ │ Duration: 18.2s │ ╰───────────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ─────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:06:38 │ │ Total Cost: $0.107 │ │ Decisions Made: 12 │ │ Child Plans: 0 │ ╰──────────────────────────────────────────╯ ╭─ Next Steps ──────╮ │ - Review git diff │ │ - Commit changes │ ╰───────────────────╯

✓ OK Changes applied

Example 3: Multi-File Refactoring with Invariants

Scenario: A senior engineer wants to refactor the authentication module to replace raw SQL queries with an ORM. The refactoring must maintain API backward compatibility and all existing tests must pass. Multiple invariants constrain the work.

Complexity: Intermediate-Advanced. Single project, multiple invariants, decision tree review.

Step 1: Define Invariants


$ agents invariant add --global "All public APIs must maintain backward compatibility"
╭─ Invariant Added ──────────────────────────────────────────────────────╮
│ Invariant: All public APIs must maintain backward compatibility        │
│ Scope: global                                                          │
│ ID: inv_01HXR3A1B                                                      │
╰────────────────────────────────────────────────────────────────────────╯
✓ OK Invariant added
$ agents invariant add --project local/api-service 

"Database queries must use the SQLAlchemy ORM, not raw SQL"
╭─ Invariant Added ───────────────────────────────────────────────────────╮
│ Project: local/api-service                                              │
│ Invariant: Database queries must use the SQLAlchemy ORM, not raw SQL    │
│ Scope: project                                                          │
│ ID: inv_01HXR3A2C                                                       │
╰─────────────────────────────────────────────────────────────────────────╯
✓ OK Invariant added
$ agents invariant list --project local/api-service --effective
╭─ Effective Invariants (Project local/api-service) ─────────────────────────────────────╮
│ ID              Source    Text                                                         │
│ ──────────────  ────────  ──────────────────────────────────────────────────────       │
│ inv_01HXR3A1B  global    All public APIs must maintain backward compatibility          │
│ inv_01HXR3A2C  project   Database queries must use the SQLAlchemy ORM, not raw SQL     │
╰────────────────────────────────────────────────────────────────────────────────────────╯
✓ OK 2 effective invariants (1 global, 1 project)

Step 2: Create a Refactoring Action with Custom Actors

Create actors/refactoring-strategist.yaml:

name: local/refactoring-strategist
cleveragents:
  version: "3.0"
actors:
  strategist:
    type: llm
    config:
      provider: anthropic
      model: claude-3.5-sonnet
      temperature: 0.2
      system_prompt: |
        You are an expert software architect specializing in database layer refactoring.
        You analyze codebases to plan safe, incremental refactoring strategies.
        You always preserve backward compatibility and plan for comprehensive testing.
        Project: {{ context.project_name }}
        Resources: {{ context.resources | join(', ') }}
      memory_enabled: true
      max_history: 100

$ agents actor add --config ./actors/refactoring-strategist.yaml ╭─ Actor Added ────────────────────────────────────╮ │ Name: local/refactoring-strategist │ │ Provider: anthropic │ │ Model: claude-3.5-sonnet │ │ Default: yes │ │ Unsafe: no │ │ Type: graph │ ╰──────────────────────────────────────────────────╯ ╭─ Config ────────────────────────────────────────────────────╮ │ Path: ./actors/refactoring-strategist.yaml │ │ Hash: 7a1e4c9 │ │ Options: 3 │ │ Nodes: 1 │ │ Edges: 0 │ ╰─────────────────────────────────────────────────────────────╯ ╭─ Capabilities ────────────────╮ │ - database layer refactoring │ │ - incremental strategy │ │ - backward compatibility │ ╰───────────────────────────────╯

✓ OK Actor added

Create actions/refactor-to-orm.yaml:

name: local/refactor-to-orm
description: "Refactor raw SQL queries to use SQLAlchemy ORM"
long_description: |
  Systematically replace all raw SQL queries in the target module with
  SQLAlchemy ORM equivalents. Create ORM model definitions, replace
  query construction, update transaction handling, and ensure all
  existing behavior is preserved.
definition_of_done: |
  - Zero raw SQL strings remain in the target module
  - All ORM models are defined with proper relationships
  - All existing tests pass without modification
  - New integration tests verify ORM query correctness
  - API response formats are unchanged
  - Database migration script is generated
strategy_actor: local/refactoring-strategist
execution_actor: anthropic/claude-3.5-sonnet
estimation_actor: anthropic/claude-3.5-sonnet
reusable: true
state: available
automation_profile: cautious
args:
  - name: target_module
    type: string
    required: true
    description: "Module to refactor"
invariants:
  - "Each file must be refactored in a separate commit-sized change"
  - "ORM models must be defined before queries are converted"
  - "All raw SQL must be replaced — no partial conversion"

$ agents action create --config ./actions/refactor-to-orm.yaml ╭─ Action Created ─────────────────────────────────────────────╮ │ Name: local/refactor-to-orm │ │ ID: 01HXR3B1D2E3F4G5H6J7K8L9M0 │ │ State: available │ │ Strategy Actor: local/refactoring-strategist │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Created: 2026-02-11 09:14 │ ╰──────────────────────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────────────╮ │ - Zero raw SQL strings remain in the target module │ │ - All ORM models are defined with proper relationships │ │ - All existing tests pass without modification │ │ - New integration tests verify ORM query correctness │ │ - API response formats are unchanged │ │ - Database migration script is generated │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Arguments ──────────────────────────────────────────────╮ │ Name Type Required Description │ │ ────────────── ────── ──────── ───────────────────── │ │ target_module string yes Module to refactor │ ╰──────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: cautious │ │ Source: action config │ ╰───────────────────────────────────────╯ ╭─ Action Invariants ──────────────────────────────────────────────────────╮ │ 1. Each file must be refactored in a separate commit-sized change │ │ 2. ORM models must be defined before queries are converted │ │ 3. All raw SQL must be replaced — no partial conversion │ ╰──────────────────────────────────────────────────────────────────────────╯ ╭─ Usage ───────────────────────────────────────────────────────────────────╮ │ agents plan use local/refactor-to-orm local/api-service │ │ --arg target_module="src/auth" │ ╰───────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

Step 3: Execute with Cautious Profile

$ agents plan use \ --arg target_module="src/auth" \ local/refactor-to-orm local/api-service ╭─ Plan Created ───────────────────────────────────────╮ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ Action: local/refactor-to-orm │ │ Project: local/api-service │ │ Automation: cautious │ │ Attempt: 1 │ ╰──────────────────────────────────────────────────────╯ ╭─ Inputs ────────────────────────╮ │ - target_module="src/auth" │ │ - automation_profile=cautious │ ╰─────────────────────────────────╯ ╭─ Actors ───────────────────────────────────────╮ │ Strategy: local/refactoring-strategist │ │ Execution: anthropic/claude-3.5-sonnet │ │ Estimation: anthropic/claude-3.5-sonnet │ ╰────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────────╮ │ Profile: cautious │ │ Source: action config │ │ Read-Only: no │ ╰───────────────────────────────────────────╯ ╭─ Context ───────────────────────╮ │ Resources: 2 (repo, db) │ │ Indexed Files: 214 │ │ View: strategize │ │ Hot Token Budget: 16,000 │ ╰─────────────────────────────────╯ ╭─ Next Steps ──────────────────────────────────────────╮ │ - agents plan execute 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ - agents plan status 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ - agents plan tree 01HXR3C4D5E6F7G8H9J0K1L2M3 │ ╰───────────────────────────────────────────────────────╯

✓ OK Plan created

Because the cautious profile uses intermediate confidence thresholds, the system:

Enters Strategize automatically (threshold 0.7, confidence is high for well-understood tasks)
Makes strategy decisions automatically when confidence >= 0.6, but pauses for complex architectural choices
The Invariant Reconciliation Actor reconciles global ("backward compatibility"), project ("use ORM"), and action ("separate commits") invariants

# The system pauses at a decision where confidence is below threshold. # Review the decision tree: $ agents plan tree 01HXR3C4D5E6F7G8H9J0K1L2M3 ╭─ Decision Tree ────────────────────────────────────────────────────────────────────────────╮ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ ├─ [prompt_definition] "Refactor raw SQL in src/auth to SQLAlchemy ORM" │ │ ├─ [invariant_enforced] "All public APIs must maintain backward compatibility" │ │ ├─ [invariant_enforced] "Database queries must use the SQLAlchemy ORM" │ │ ├─ [invariant_enforced] "Each file refactored in a separate commit-sized change" │ │ ├─ [invariant_enforced] "ORM models must be defined before queries are converted" │ │ ├─ [strategy_choice] "Define ORM models first, then convert queries" (conf: 0.85) │ │ ├─ [strategy_choice] "Place models inline in route files" (conf: 0.48) ⏸ PAUSED │ │ └─ • (awaiting input — confidence below threshold) │ ╰────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Tree Summary ─────────────╮ │ Nodes: 8 │ │ Depth: 2 │ │ Child Plans: 0 │ │ Invariants: 4 │ │ Superseded: 0 (hidden) │ ╰────────────────────────────╯ ╭─ Decision IDs (for correction) ──────────────────────╮ │ Root: 01HXR3D1A2B3C4D5E6F7G8H9 │ │ Invariant 1: 01HXR3D1B3C4D5E6F7G8H9J0 │ │ Invariant 2: 01HXR3D1C4D5E6F7G8H9J0K1 │ │ Invariant 3: 01HXR3D1D5E6F7G8H9J0K1L2 │ │ Invariant 4: 01HXR3D1E6F7G8H9J0K1L2M3 │ │ Strategy 1: 01HXR3D2E3F4G5H6I7J8K9L0 │ │ Strategy 2: 01HXR3D5F6G7H8I9J0K1L2M3 (paused) │ ╰──────────────────────────────────────────────────────╯ ✓ OK Decision tree rendered # The paused decision is about model placement. Inspect it: $ agents plan explain 01HXR3D5F6G7H8I9J0K1L2M3 ╭─ Decision ──────────────────────────────────────────────╮ │ ID: 01HXR3D5F6G7H8I9J0K1L2M3 │ │ Type: strategy_choice │ │ Question: Where should ORM model classes be placed? │ │ Chosen: Place models inline in route files │ │ Confidence: 0.48 │ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ Sequence: 6 of 7 │ │ Created: 2026-02-11 09:15 │ ╰─────────────────────────────────────────────────────────╯ ╭─ Alternatives Considered ─────────────────────────────────────╮ │ 1. Place models inline in route files (chosen) │ │ 2. Separate models/ directory with one model per file │ │ 3. Single models.py file alongside routes │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Impact ──────────────────────╮ │ Downstream Decisions: 4 │ │ Downstream Child Plans: 0 │ │ Artifacts Produced: 0 │ │ Correction Impact: high │ ╰───────────────────────────────╯ ╭─ Rationale ────────────────────────────────────────────────────────╮ │ Placing models inline minimizes import changes and keeps related │ │ code co-located. However, this conflicts with project conventions │ │ and may make models harder to reuse across modules. The low │ │ confidence reflects genuine uncertainty about the trade-off. │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Correction ───────────────────────────────────────────────────────╮ │ agents plan correct 01HXR3D5F6G7H8I9J0K1L2M3 │ │ --mode revert --guidance "Use separate models/ directory..." │ ╰────────────────────────────────────────────────────────────────────╯ ✓ OK Decision explained # Provide guidance via the plan prompt command $ agents plan prompt 01HXR3C4D5E6F7G8H9J0K1L2M3 "Convert the User model first, then Session, then Token. Use Alembic for the migration script." ╭─ Guidance Added ─────────────────────────────────────────────────────────╮ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ Guidance: Convert the User model first, then Session, then Token. │ │ Use Alembic for the migration script. │ │ Scope: next execution step │ │ Phase: strategize │ │ State: awaiting_input → processing │ ╰──────────────────────────────────────────────────────────────────────────╯ ╭─ Decision Created ───────────────────────────╮ │ Type: user_intervention │ │ ID: 01HXR3E1A2B3C4D5E6F7G8H9 │ │ Parent: 01HXR3D5F6G7H8I9J0K1L2M3 │ ╰──────────────────────────────────────────────╯ ╭─ Queue ────╮ │ Pending: 1 │ │ Applied: 0 │ ╰────────────╯ ✓ OK Guidance queued # Execution continues. Monitor progress: $ agents plan status 01HXR3C4D5E6F7G8H9J0K1L2M3 ╭─ Plan Status ───────────────────────────────────╮ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ Phase: execute │ │ State: processing │ │ Action: local/refactor-to-orm │ │ Project: local/api-service │ │ Automation: cautious │ │ Attempt: 1 │ ╰─────────────────────────────────────────────────╯ ╭─ Progress ───────╮ │ ✓ Strategize │ │ ⏳ Execute │ │ • Apply (queued) │ ╰──────────────────╯ ╭─ Timing ──────────╮ │ Started: 09:14:22 │ │ Elapsed: 00:02:38 │ │ ETA: 00:05:10 │ ╰───────────────────╯ ╭─ Execution Detail ──────────╮ │ Sandbox: git_worktree │ │ Tool Calls: 14 │ │ Files Modified: 4 │ │ Child Plans: 0/0 complete │ │ Checkpoints: 3 created │ ╰─────────────────────────────╯ ╭─ Cost ───────────────╮ │ Tokens Used: 18,740 │ │ Cost So Far: $0.062 │ │ Estimated: $0.128 │ ╰──────────────────────╯

✓ OK Status refreshed

Step 4: Correct a Decision

During execution, you notice the strategy chose to inline the ORM models in the same file as the routes. You want them in a separate models/ directory:

# Find the decision that chose inline models $ agents plan tree --show-superseded 01HXR3C4D5E6F7G8H9J0K1L2M3 ╭─ Decision Tree ────────────────────────────────────────────────────────────────────────────╮ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ ├─ [prompt_definition] "Refactor raw SQL in src/auth to SQLAlchemy ORM" │ │ ├─ [invariant_enforced] "All public APIs must maintain backward compatibility" │ │ ├─ [invariant_enforced] "Database queries must use the SQLAlchemy ORM" │ │ ├─ [invariant_enforced] "Each file refactored in a separate commit-sized change" │ │ ├─ [invariant_enforced] "ORM models must be defined before queries are converted" │ │ ├─ [strategy_choice] "Define ORM models first, then convert queries" (conf: 0.85) │ │ ├─ [strategy_choice] "Place models inline in route files" (superseded) │ │ ├─ [user_intervention] "Convert User first, then Session, then Token" │ │ ├─ [strategy_choice] "Create User ORM model in routes/auth.py" (conf: 0.74) │ │ ├─ [tool_invocation] write_file src/auth/routes/auth.py │ │ └─ [tool_invocation] write_file src/auth/routes/session.py │ ╰────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Tree Summary ─────────────╮ │ Nodes: 11 │ │ Depth: 3 │ │ Child Plans: 0 │ │ Invariants: 4 │ │ Superseded: 1 (shown) │ ╰────────────────────────────╯ ╭─ Decision IDs (for correction) ──────────────────────╮ │ Root: 01HXR3D1A2B3C4D5E6F7G8H9 │ │ Strategy 1: 01HXR3D2E3F4G5H6I7J8K9L0 │ │ Strategy 2: 01HXR3D5F6G7H8I9J0K1L2M3 (superseded) │ │ Intervention: 01HXR3E1A2B3C4D5E6F7G8H9 │ │ Strategy 3: 01HXR3F1A2B3C4D5E6F7G8H9 │ │ Tool 1: 01HXR3F2B3C4D5E6F7G8H9J0 │ │ Tool 2: 01HXR3F3C4D5E6F7G8H9J0K1 │ ╰──────────────────────────────────────────────────────╯ ✓ OK Decision tree rendered # Correct it — revert mode replays from that decision $ agents plan correct 01HXR3F1A2B3C4D5E6F7G8H9 --mode revert --guidance "Place ORM models in src/auth/models/ with one model per file. Import them in src/auth/models/__init__.py." --yes ╭─ Correction ────────────────────────────────────────────────╮ │ Mode: revert │ │ Impact: 2 decisions, 0 child plans, 2 artifacts │ │ New Decision: 01HXR3G1A2B3C4D5E6F7G8H9 │ │ Corrects: 01HXR3F1A2B3C4D5E6F7G8H9 │ │ Attempt: 2 │ │ Correction ID: 01HXR3CORR1A2B3C4D5E6 │ ╰─────────────────────────────────────────────────────────────╯ ╭─ Affected Subtree ──────────────╮ │ Decisions Invalidated: 2 │ │ Child Plans Rolled Back: 0 │ │ Artifacts Archived: 2 │ │ Unaffected Decisions: 6 │ ╰─────────────────────────────────╯ ╭─ Sandbox Rollback ─────────────╮ │ Checkpoint: cp_01HXR3C4 │ │ Files Reverted: 2 │ │ Status: restored │ ╰────────────────────────────────╯ ╭─ Recompute ───────────────╮ │ Queued: re-execute │ │ ETA: 3m │ ╰───────────────────────────╯ ╭─ History ───────────────────────────────────────────────╮ │ - Original decision superseded │ │ - Prior artifacts archived for comparison │ │ - agents plan diff --correction 01HXR3CORR1A2B3C4D5E6 │ ╰─────────────────────────────────────────────────────────╯ ✓ OK Correction applied # The affected subtree is recomputed. Review the new approach: $ agents plan diff --correction 01HXR3CORR1A2B3C4D5E6 ╭─ Correction Diff ────────────────────────────────────────────╮ │ Correction: 01HXR3CORR1A2B3C4D5E6 │ │ Original Decision: 01HXR3F1A2B3C4D5E6F7G8H9 │ │ Mode: revert │ │ Files Changed: 5 │ │ New Insertions: 84 │ │ New Deletions: 36 │ ╰──────────────────────────────────────────────────────────────╯ ╭─ Comparison ──────────────────────────────────────────────────────────────╮ │ File Before (original) After (corrected) │ │ ────────────────────────────── ──────────────── ──────────────────── │ │ src/auth/routes/auth.py +42 -8 (inline) +6 -8 (imports only) │ │ src/auth/routes/session.py +28 -6 (inline) +4 -6 (imports only) │ │ src/auth/models/__init__.py (did not exist) (new file) │ │ src/auth/models/user.py (did not exist) (new file, +38) │ │ src/auth/models/session.py (did not exist) (new file, +26) │ ╰───────────────────────────────────────────────────────────────────────────╯ ╭─ Patch Preview (corrected vs original) ───────────────────────────╮ │ --- a/src/auth/routes/auth.py (original) │ │ +++ b/src/auth/routes/auth.py (corrected) │ │ @@ -1,42 +1,6 @@ │ │ - class User(Base): # was inline │ │ - tablename = "users" │ │ - id = Column(Integer, primary_key=True) │ │ + from src.auth.models import User │ │ ... │ │ +++ b/src/auth/models/user.py (new file) │ │ @@ -0,0 +1,38 @@ │ │ + from sqlalchemy import Column, Integer, String │ │ + from sqlalchemy.orm import relationship │ │ + class User(Base): │ │ + tablename = "users" │ │ ... │ ╰───────────────────────────────────────────────────────────────────╯

✓ OK Correction diff generated

Step 5: Apply

$ agents plan diff 01HXR3C4D5E6F7G8H9J0K1L2M3 ╭─ Diff Summary ───────────────────────────────────────╮ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ Project: local/api-service │ │ Files Changed: 9 │ │ Insertions: 186 │ │ Deletions: 94 │ │ Net Change: +92 lines │ ╰──────────────────────────────────────────────────────╯ ╭─ Files ───────────────────────────────────────────────╮ │ Path Change Status │ │ ────────────────────────────── ──────── ────────── │ │ src/auth/models/__init__.py +8 new file │ │ src/auth/models/user.py +38 new file │ │ src/auth/models/session.py +26 new file │ │ src/auth/models/token.py +22 new file │ │ src/auth/routes/auth.py +12 -28 modified │ │ src/auth/routes/session.py +8 -22 modified │ │ src/auth/routes/token.py +6 -18 modified │ │ src/auth/db.py +14 -26 modified │ │ alembic/versions/001_orm.py +52 new file │ ╰───────────────────────────────────────────────────────╯ ╭─ Risk Assessment ────────────────╮ │ API Compatibility: preserved │ │ Test Coverage: maintained │ │ Breaking Changes: none detected │ ╰──────────────────────────────────╯ ✓ OK Diff generated $ agents plan apply --yes 01HXR3C4D5E6F7G8H9J0K1L2M3 ╭─ Apply Summary ───────────────────────────────────╮ │ Plan: 01HXR3C4D5E6F7G8H9J0K1L2M3 │ │ Artifacts: 9 files updated │ │ Changes: 186 insertions, 94 deletions │ │ Project: local/api-service │ │ Applied At: 2026-02-11 09:23 │ ╰───────────────────────────────────────────────────╯ ╭─ Validation ───────────────────────╮ │ Tests: passed (47/47) │ │ Lint: passed (0 warnings) │ │ Type Check: passed (0 errors) │ │ Duration: 18.6s │ ╰────────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ───────────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:08:42 │ │ Total Cost: $0.128 │ │ Decisions Made: 11 │ │ Corrections: 1 │ │ Child Plans: 0 │ ╰────────────────────────────────────────────────╯ ╭─ Next Steps ──────╮ │ - Review git diff │ │ - Commit changes │ ╰───────────────────╯

✓ OK Changes applied

Example 4: Multi-Project Dependency Update

Scenario: An organization has three microservices that share a common library. The library has a breaking change that requires coordinated updates across all three services. The update must be validated in each service independently before any changes are applied.

Complexity: Advanced. Multiple projects, child plans, coordinated apply.

Step 1: Register All Projects and Resources

# Register the common-lib resource (full output shown) $ agents resource add git-checkout local/common-lib-repo --path /repos/common-lib --branch main ╭─ Resource ──────────────────────────────────────╮ │ Name: local/common-lib-repo │ │ ID: 01HXR4A1B2C3D4E5F6G7H8J9K0 │ │ Type: git-checkout │ │ Physical/Virtual: physical │ │ Path: /repos/common-lib │ │ Branch: main │ │ Created: 2026-02-11 10:00 │ ╰─────────────────────────────────────────────────╯ ╭─ Auto-discovered Children ─────────────────────────────────────────╮ │ ID Type Status │ │ ─────────────── ────────────── ───────────────── │ │ 01HXR4A1B2C3… git created │ │ 01HXR4A1B2C4… git-remote created │ │ 01HXR4A1B2C5… git-branch created │ │ + 31 git-commit resources │ │ + 186 git-tree-entry resources │ │ + 2 fs-directory + 14 fs-file │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Capabilities ─────────────────╮ │ Readable: yes │ │ Writable: yes │ │ Sandboxable: yes │ │ Checkpointable: yes │ │ Sandbox Strategy: git_worktree │ ╰────────────────────────────────╯ ✓ OK Resource registered (236 child resources discovered) # Register the remaining 3 service resources (condensed output) $ agents resource add git-checkout local/user-service-repo --path /repos/user-service --branch main ✓ OK Resource registered — Name: local/user-service-repo (312 children) $ agents resource add git-checkout local/order-service-repo --path /repos/order-service --branch main ✓ OK Resource registered — Name: local/order-service-repo (287 children)

$ agents resource add git-checkout local/billing-service-repo --path /repos/billing-service --branch main ✓ OK Resource registered — Name: local/billing-service-repo (264 children)

# Create the common-lib project (full output shown) $ agents project create -d "Shared common library" --resource local/common-lib-repo local/common-lib ╭─ Project Created ─────────────────────────╮ │ Name: local/common-lib │ │ Description: Shared common library │ │ Type: local │ │ Created: 2026-02-11 10:01 │ ╰───────────────────────────────────────────╯ ╭─ Linked Resources ───────────────────────────────────────╮ │ Resource Type Read-Only │ │ ───────────────────── ────────────── ───────── │ │ local/common-lib-repo git-checkout no │ ╰──────────────────────────────────────────────────────────╯ ╭─ Defaults ──────────────────────────────╮ │ Sandbox: git_worktree │ │ Validations: 0 │ │ Context Filters: none │ │ Automation Profile: (inherits global) │ ╰─────────────────────────────────────────╯ ✓ OK Project created # Create the remaining 3 service projects (condensed output) $ agents project create -d "User microservice" --resource local/user-service-repo local/user-service ✓ OK Project created — Name: local/user-service $ agents project create -d "Order microservice" --resource local/order-service-repo local/order-service ✓ OK Project created — Name: local/order-service

$ agents project create -d "Billing microservice" --resource local/billing-service-repo local/billing-service ✓ OK Project created — Name: local/billing-service

# Register a shared validation — first one with full output $ agents validation add --config validations/pytest-mypy.yaml --required local/pytest-mypy ╭─ Validation Registered ─────────────────────────────╮ │ Name: local/pytest-mypy │ │ Command: pytest tests/ && mypy src/ │ │ Mode: required │ │ Timeout: 300s │ ╰─────────────────────────────────────────────────────╯ ✓ OK Validation registered # Attach the validation to all 4 projects $ agents validation attach --project local/common-lib local/pytest-mypy ✓ OK Validation attached to project local/common-lib $ agents validation attach --project local/user-service local/pytest-mypy ✓ OK Validation attached to project local/user-service $ agents validation attach --project local/order-service local/pytest-mypy ✓ OK Validation attached to project local/order-service

$ agents validation attach --project local/billing-service local/pytest-mypy ✓ OK Validation attached to project local/billing-service

Step 2: Create a Coordinated Update Action

Create actions/coordinated-dependency-update.yaml:

name: local/coordinated-dep-update
description: "Update a shared dependency across multiple projects"
long_description: |
  When a shared library introduces a breaking change, this action coordinates
  the update across all dependent projects. It analyzes the breaking changes,
  creates per-project update plans as child plans, validates each independently,
  and produces a coordinated changeset.
definition_of_done: |
  - The shared library is updated to the target version
  - All dependent projects compile and pass tests with the new version
  - API contracts between services remain compatible
  - Migration guides are generated for each project if needed
  - All changes can be applied atomically or rolled back as a unit
strategy_actor: anthropic/claude-3.5-sonnet
execution_actor: anthropic/claude-3.5-sonnet
automation_profile: supervised
reusable: true
state: available
args:
  - name: library_name
    type: string
    required: true
    description: "Name of the shared library to update"
  - name: target_version
    type: string
    required: true
    description: "Target version to update to"
  - name: changelog_url
    type: string
    required: false
    description: "URL to the library changelog or migration guide"
invariants:
  - "Each dependent project must be updated in its own child plan"
  - "All child plans must pass validation before any can be applied"
  - "The library update in common-lib must be applied first"

$ agents action create --config ./actions/coordinated-dependency-update.yaml ╭─ Action Created ─────────────────────────────────────────────╮ │ Name: local/coordinated-dep-update │ │ ID: 01HXR4B1D2E3F4G5H6J7K8L9M0 │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Created: 2026-02-11 10:02 │ ╰──────────────────────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────────────────────╮ │ - The shared library is updated to the target version │ │ - All dependent projects compile and pass tests with the new version │ │ - API contracts between services remain compatible │ │ - Migration guides are generated for each project if needed │ │ - All changes can be applied atomically or rolled back as a unit │ ╰───────────────────────────────────────────────────────────────────────╯ ╭─ Arguments ──────────────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ────────────── ────── ──────── ────────────────────────────────────────── │ │ library_name string yes Name of the shared library to update │ │ target_version string yes Target version to update to │ │ changelog_url string no URL to the library changelog or migration │ ╰──────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: supervised │ │ Source: action config │ ╰───────────────────────────────────────╯ ╭─ Action Invariants ──────────────────────────────────────────────────────────────╮ │ 1. Each dependent project must be updated in its own child plan │ │ 2. All child plans must pass validation before any can be applied │ │ 3. The library update in common-lib must be applied first │ ╰──────────────────────────────────────────────────────────────────────────────────╯ ╭─ Usage ───────────────────────────────────────────────────────────────────────────╮ │ agents plan use local/coordinated-dep-update local/common-lib │ │ --arg library_name="authlib" --arg target_version="2.0.0" │ ╰───────────────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

Step 3: Execute Across Multiple Projects

# Create a plan targeting all four projects $ agents plan use --automation-profile supervised --arg library_name="authlib" --arg target_version="2.0.0" --arg changelog_url="https://authlib.org/changelog/2.0" local/coordinated-dep-update local/common-lib local/user-service local/order-service local/billing-service ╭─ Plan Created ────────────────────────────────────────────╮ │ Plan: 01HXR4D5E6F7G8H9J0K1L2M3N4 │ │ Action: local/coordinated-dep-update │ │ Projects: local/common-lib, local/user-service, │ │ local/order-service, local/billing-service │ │ Automation: supervised │ │ Attempt: 1 │ ╰───────────────────────────────────────────────────────────╯ ╭─ Inputs ───────────────────────────────────────────────────────────╮ │ - library_name="authlib" │ │ - target_version="2.0.0" │ │ - changelog_url="https://authlib.org/changelog/2.0" │ │ - automation_profile=supervised │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Actors ───────────────────────────────────────╮ │ Strategy: anthropic/claude-3.5-sonnet │ │ Execution: anthropic/claude-3.5-sonnet │ ╰────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────────╮ │ Profile: supervised │ │ Source: CLI override │ │ Read-Only: no │ ╰───────────────────────────────────────────╯ ╭─ Context ──────────────────────────╮ │ Resources: 4 (git-checkout) │ │ Indexed Files: 1,099 │ │ View: strategize │ │ Hot Token Budget: 24,000 │ ╰────────────────────────────────────╯ ╭─ Next Steps ──────────────────────────────────────────────╮ │ - agents plan tree 01HXR4D5E6F7G8H9J0K1L2M3N4 │ │ - agents plan status 01HXR4D5E6F7G8H9J0K1L2M3N4 │ │ - agents plan execute 01HXR4D5E6F7G8H9J0K1L2M3N4 │ ╰───────────────────────────────────────────────────────────╯

✓ OK Plan created

The system creates a parent plan. Strategize runs automatically (supervised profile). It produces a strategy that:

Analyzes the breaking changes in authlib 2.0.0
Plans child plans for each project
Orders the updates: common-lib first, then services in parallel

# Review the strategy before execution begins $ agents plan tree 01HXR4D5E6F7G8H9J0K1L2M3N4 ╭─ Decision Tree ─────────────────────────────────────────────────────────────────────────────────────╮ │ Plan: 01HXR4D5E6F7G8H9J0K1L2M3N4 │ │ ├─ [prompt_definition] "Update authlib to 2.0.0 across 4 projects" │ │ ├─ [invariant_enforced] "Each dependent project must be updated in its own child plan" │ │ ├─ [invariant_enforced] "All child plans must pass validation before any can be applied" │ │ ├─ [invariant_enforced] "The library update in common-lib must be applied first" │ │ ├─ [strategy_choice] "Analyze changelog for breaking API changes" (conf: 0.92) │ │ ├─ [strategy_choice] "Update common-lib first, then services in parallel" (conf: 0.88) │ │ ├─ [strategy_choice] "Create 4 child plans: common-lib, user-svc, order-svc, billing-svc" │ │ │ (conf: 0.90) │ │ └─ • (awaiting execution approval — supervised profile) │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Tree Summary ──────────────╮ │ Nodes: 8 │ │ Depth: 2 │ │ Child Plans: 0 (planned: 4) │ │ Invariants: 3 │ │ Superseded: 0 (hidden) │ ╰─────────────────────────────╯ ╭─ Decision IDs (for correction) ──────────────────────────╮ │ Root: 01HXR4D6A1B2C3D4E5F6G7H8 │ │ Invariant 1: 01HXR4D6B2C3D4E5F6G7H8J9 │ │ Invariant 2: 01HXR4D6C3D4E5F6G7H8J9K0 │ │ Invariant 3: 01HXR4D6D4E5F6G7H8J9K0L1 │ │ Strategy 1: 01HXR4D7E5F6G7H8I9J0K1L2 │ │ Strategy 2: 01HXR4D7F6G7H8I9J0K1L2M3 │ │ Strategy 3: 01HXR4D7G7H8I9J0K1L2M3N4 │ ╰──────────────────────────────────────────────────────────╯ ✓ OK Decision tree rendered $ agents plan status 01HXR4D5E6F7G8H9J0K1L2M3N4 ╭─ Plan Status ──────────────────────────────────────────╮ │ Plan: 01HXR4D5E6F7G8H9J0K1L2M3N4 │ │ Phase: strategize → execute (pending approval) │ │ State: awaiting_input │ │ Action: local/coordinated-dep-update │ │ Projects: 4 │ │ Automation: supervised │ │ Attempt: 1 │ ╰────────────────────────────────────────────────────────╯ ╭─ Progress ────────────────────────────╮ │ ✓ Strategize │ │ ⏸ Execute (awaiting approval) │ │ • Apply (queued) │ ╰───────────────────────────────────────╯ ╭─ Timing ──────────╮ │ Started: 10:02:14 │ │ Elapsed: 00:01:42 │ │ ETA: 00:12:00 │ ╰───────────────────╯ ╭─ Cost ───────────────╮ │ Tokens Used: 8,420 │ │ Cost So Far: $0.028 │ │ Estimated: $0.340 │ ╰──────────────────────╯ ✓ OK Status refreshed # Manually approve execution (supervised requires explicit approval) $ agents plan execute 01HXR4D5E6F7G8H9J0K1L2M3N4 ╭─ Execution Started ──────────────────────────────────────╮ │ Plan: 01HXR4D5E6F7G8H9J0K1L2M3N4 │ │ Phase: execute │ │ State: processing │ │ Automation: supervised │ ╰──────────────────────────────────────────────────────────╯ ╭─ Child Plans Spawned ───────────────────────────────────────────────────╮ │ Plan ID Project Status │ │ ────────────────────────── ─────────────────── ──────────────── │ │ 01HXR4C1D2E3F4G5H6I7J8K9 local/common-lib executing │ │ 01HXR4C2E3F4G5H6I7J8K9L0 local/user-service waiting (common) │ │ 01HXR4C3F4G5H6I7J8K9L0M1 local/order-service waiting (common) │ │ 01HXR4C4G5H6I7J8K9L0M1N2 local/billing-service waiting (common) │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Execution Order ──────────────────────────────────────────╮ │ Phase 1: common-lib (blocking) │ │ Phase 2: user-service, order-service, billing-service │ │ (parallel, after common-lib completes) │ ╰────────────────────────────────────────────────────────────╯

✓ OK Execution started (4 child plans spawned)

Step 4: Review and Apply in Order

Once all child plans complete execution and pass validation, review and apply them in dependency order.

# Review common-lib changes first (must be applied before services) $ agents plan diff 01HXR4C1D2E3F4G5H6I7J8K9 ╭─ Diff Summary ───────────────────────────────────────╮ │ Plan: 01HXR4C1D2E3F4G5H6I7J8K9 │ │ Project: local/common-lib │ │ Files Changed: 4 │ │ Insertions: 62 │ │ Deletions: 38 │ │ Net Change: +24 lines │ ╰──────────────────────────────────────────────────────╯ ╭─ Files ───────────────────────────────────────────────────────╮ │ Path Change Status │ │ ──────────────────────────────── ──────── ────────── │ │ requirements.txt +1 -1 modified │ │ src/common/auth.py +28 -19 modified │ │ src/common/token_validator.py +18 -12 modified │ │ tests/test_auth.py +15 -6 modified │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Patch Preview ───────────────────────────────────────────────────╮ │ --- a/requirements.txt │ │ +++ b/requirements.txt │ │ @@ -3,1 +3,1 @@ │ │ - authlib==1.3.2 │ │ + authlib==2.0.0 │ │ --- a/src/common/auth.py │ │ +++ b/src/common/auth.py │ │ @@ -1,6 +1,8 @@ │ │ - from authlib.integrations.requests_client import OAuth2Session │ │ + from authlib.integrations.httpx_client import AsyncOAuth2Client │ │ ... │ ╰───────────────────────────────────────────────────────────────────╯ ╭─ Validation ────────────────────────╮ │ pytest tests/ && mypy src/: passed │ │ Duration: 12.4s │ ╰─────────────────────────────────────╯ ✓ OK Diff generated $ agents plan apply --yes 01HXR4C1D2E3F4G5H6I7J8K9 ╭─ Apply Summary ──────────────────────────────────────╮ │ Plan: 01HXR4C1D2E3F4G5H6I7J8K9 │ │ Artifacts: 4 files updated │ │ Changes: 62 insertions, 38 deletions │ │ Project: local/common-lib │ │ Applied At: 2026-02-11 10:14 │ ╰──────────────────────────────────────────────────────╯ ╭─ Validation ───────────────────────╮ │ Tests: passed (24/24) │ │ Type Check: passed (0 errors) │ │ Duration: 12.4s │ ╰────────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ───────────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:03:18 │ │ Total Cost: $0.064 │ ╰────────────────────────────────────────────────╯

✓ OK Changes applied

# Once common-lib is applied, review the 3 service child plans. # Full diff shown for user-service; order-service and billing-service condensed. $ agents plan diff 01HXR4C2E3F4G5H6I7J8K9L0 ╭─ Diff Summary ───────────────────────────────────────╮ │ Plan: 01HXR4C2E3F4G5H6I7J8K9L0 │ │ Project: local/user-service │ │ Files Changed: 6 │ │ Insertions: 84 │ │ Deletions: 52 │ │ Net Change: +32 lines │ ╰──────────────────────────────────────────────────────╯ ╭─ Files ───────────────────────────────────────────────────────╮ │ Path Change Status │ │ ──────────────────────────────── ──────── ────────── │ │ requirements.txt +1 -1 modified │ │ src/auth/middleware.py +22 -14 modified │ │ src/auth/oauth.py +18 -12 modified │ │ src/auth/token.py +16 -11 modified │ │ tests/test_middleware.py +14 -8 modified │ │ tests/test_oauth.py +13 -6 modified │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Validation ────────────────────────╮ │ pytest tests/ && mypy src/: passed │ │ Duration: 18.2s │ ╰─────────────────────────────────────╯ ✓ OK Diff generated $ agents plan diff 01HXR4C3F4G5H6I7J8K9L0M1 ╭─ Diff Summary ───────────────────────────────────────╮ │ Plan: 01HXR4C3F4G5H6I7J8K9L0M1 │ │ Project: local/order-service │ │ Files Changed: 5 │ │ Insertions: 71 │ │ Deletions: 46 │ │ Net Change: +25 lines │ ╰──────────────────────────────────────────────────────╯ ╭─ Validation ────────────────────────╮ │ pytest tests/ && mypy src/: passed │ │ Duration: 14.7s │ ╰─────────────────────────────────────╯ ✓ OK Diff generated $ agents plan diff 01HXR4C4G5H6I7J8K9L0M1N2 ╭─ Diff Summary ───────────────────────────────────────╮ │ Plan: 01HXR4C4G5H6I7J8K9L0M1N2 │ │ Project: local/billing-service │ │ Files Changed: 4 │ │ Insertions: 58 │ │ Deletions: 34 │ │ Net Change: +24 lines │ ╰──────────────────────────────────────────────────────╯ ╭─ Validation ────────────────────────╮ │ pytest tests/ && mypy src/: passed │ │ Duration: 11.3s │ ╰─────────────────────────────────────╯ ✓ OK Diff generated # Apply all 3 service child plans $ agents plan apply --yes 01HXR4C2E3F4G5H6I7J8K9L0 ╭─ Apply Summary ──────────────────────────────────────╮ │ Plan: 01HXR4C2E3F4G5H6I7J8K9L0 │ │ Artifacts: 6 files updated │ │ Changes: 84 insertions, 52 deletions │ │ Project: local/user-service │ │ Applied At: 2026-02-11 10:16 │ ╰──────────────────────────────────────────────────────╯ ╭─ Validation ───────────────────────╮ │ Tests: passed (89/89) │ │ Type Check: passed (0 errors) │ │ Duration: 18.2s │ ╰────────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ───────────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:04:12 │ │ Total Cost: $0.082 │ ╰────────────────────────────────────────────────╯ ✓ OK Changes applied $ agents plan apply --yes 01HXR4C3F4G5H6I7J8K9L0M1 ╭─ Apply Summary ──────────────────────────────────────╮ │ Plan: 01HXR4C3F4G5H6I7J8K9L0M1 │ │ Artifacts: 5 files updated │ │ Changes: 71 insertions, 46 deletions │ │ Project: local/order-service │ │ Applied At: 2026-02-11 10:17 │ ╰──────────────────────────────────────────────────────╯ ╭─ Validation ───────────────────────╮ │ Tests: passed (76/76) │ │ Type Check: passed (0 errors) │ │ Duration: 14.7s │ ╰────────────────────────────────────╯ ╭─ Plan Lifecycle ───────────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:03:48 │ │ Total Cost: $0.074 │ ╰────────────────────────────────────────────────╯ ✓ OK Changes applied $ agents plan apply --yes 01HXR4C4G5H6I7J8K9L0M1N2 ╭─ Apply Summary ──────────────────────────────────────╮ │ Plan: 01HXR4C4G5H6I7J8K9L0M1N2 │ │ Artifacts: 4 files updated │ │ Changes: 58 insertions, 34 deletions │ │ Project: local/billing-service │ │ Applied At: 2026-02-11 10:18 │ ╰──────────────────────────────────────────────────────╯ ╭─ Validation ───────────────────────╮ │ Tests: passed (63/63) │ │ Type Check: passed (0 errors) │ │ Duration: 11.3s │ ╰────────────────────────────────────╯ ╭─ Plan Lifecycle ───────────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:03:22 │ │ Total Cost: $0.068 │ ╰────────────────────────────────────────────────╯ ╭─ Parent Plan Complete ──────────────────────────────────╮ │ Plan: 01HXR4D5E6F7G8H9J0K1L2M3N4 │ │ Phase: apply │ │ State: applied │ │ Child Plans: 4/4 complete │ │ Total Duration: 00:16:04 │ │ Total Cost: $0.340 │ │ All Validations: passed │ ╰─────────────────────────────────────────────────────────╯

✓ OK Changes applied

Example 5: Database Schema Migration with Safety Nets

Scenario: A team needs to add a last_login_at column to a users table with 10 million rows, backfill it from an audit log, and update the application code — all without downtime.

Complexity: Advanced. Mixed resource types (git + database), custom tools, checkpointing critical.

Step 1: Register the Database as a Resource

# Register the custom postgres-db resource type $ agents resource type add --config ./resource-types/postgres-db.yaml ╭─ Resource Type ─────────────────────────╮ │ Name: local/postgres-db │ │ Physical/Virtual: physical │ │ User Addable: yes │ │ Registered: 2026-02-11 09:01 │ ╰─────────────────────────────────────────╯ ╭─ CLI Arguments ──────────────────────────────────────────╮ │ Argument Required Description │ │ ──────────── ──────── ────────────────────────────── │ │ --host yes Database hostname │ │ --port no Port (default: 5432) │ │ --database yes Database name │ │ --schema no Schema (default: public) │ ╰──────────────────────────────────────────────────────────╯ ╭─ Sandbox ──────────────────────────────╮ │ Strategy: transaction_rollback │ │ Handler: PostgresHandler (custom) │ ╰────────────────────────────────────────╯

✓ OK Resource type registered ℹ New subcommand available: agents resource add local/postgres-db

# Register the production database instance $ agents resource add local/postgres-db local/prod-users-db \ --host db.internal.example.com \ --port 5432 \ --database users_db \ --schema public ╭─ Resource ───────────────────────────────────────╮ │ Name: local/prod-users-db │ │ ID: 01HXR5D3E4F5G6H7J8K9L0M1N2 │ │ Type: local/postgres-db │ │ Physical/Virtual: physical │ │ Host: db.internal.example.com │ │ Port: 5432 │ │ Database: users_db │ │ Schema: public │ │ Created: 2026-02-11 09:02 │ ╰──────────────────────────────────────────────────╯ ╭─ Capabilities ──────────────────────────╮ │ Readable: yes │ │ Writable: yes │ │ Sandboxable: yes │ │ Checkpointable: yes │ │ Sandbox Strategy: transaction_rollback │ ╰─────────────────────────────────────────╯

✓ OK Resource registered

# Link the database resource to the project $ agents project link-resource local/api-service local/prod-users-db ╭─ Resource Linked ────────────────────────────╮ │ Project: local/api-service │ │ Resource: local/prod-users-db │ │ Type: local/postgres-db │ │ Read-Only: no │ ╰──────────────────────────────────────────────╯ ╭─ Access ─────────────────╮ │ Read: allowed │ │ Write: allowed │ │ Apply: requires approval │ ╰──────────────────────────╯ ╭─ Project Resources ─────────────────────────────────────────────╮ │ ID Type Status │ │ ────────────────────────────── ──────────────── ────────── │ │ 01HXR1A1B2C3D4E5F6G7H8J9K0 git-checkout linked │ │ 01HXR5D3E4F5G6H7J8K9L0M1N2 local/postgres-db linked (new) │ ╰─────────────────────────────────────────────────────────────────╯

✓ OK Resource linked to project

Step 2: Create a Custom Skill with Database Tools

Create skills/database-ops.yaml:


name: local/database-ops
description: "Safe database operations with transaction support"
tools:
  - name: query_db
    description: "Execute a read-only SQL query and return results"
    input_schema:
      type: object
      properties:
        sql:
          type: string
          description: "SQL SELECT query"
        params:
          type: array
          description: "Query parameters"
      required: [sql]
    writes: false
    checkpointable: false
    resource_slots:
      - name: database
        type: local/postgres-db
        binding: contextual


name: execute_migration
description: "Execute a DDL migration within a transaction"
input_schema:
type: object
properties:
up_sql:
type: string
description: "Forward migration SQL"
down_sql:
type: string
description: "Rollback migration SQL"
description:
type: string
description: "Human-readable description"
required: [up_sql, down_sql, description]
writes: true
checkpointable: true
resource_slots:

name: database
type: local/postgres-db
binding: contextual



name: backfill_column
description: "Batch-update a column using a source query"
input_schema:
type: object
properties:
table:
type: string
column:
type: string
source_query:
type: string
description: "Query that returns (id, value) pairs"
batch_size:
type: integer
default: 10000
required: [table, column, source_query]
writes: true
checkpointable: true
resource_slots:

name: database
type: local/postgres-db
binding: contextual

$ agents skill add --config ./skills/database-ops.yaml ╭─ Skill Registered ─────────────────────────────────────────────╮ │ Name: local/database-ops │ │ Description: Safe database operations with transaction support │ │ Config: ./skills/database-ops.yaml │ │ Created: 2026-02-11 09:04 │ ╰────────────────────────────────────────────────────────────────╯ ╭─ Tool Sources ──────────────────────────────────────╮ │ Source Count Details │ │ ──────── ───── ──────────────────────────── │ │ custom 3 query_db, execute_migration, │ │ backfill_column │ │ ──────── ───── ──────────────────────────── │ │ Total: 3 │ ╰─────────────────────────────────────────────────────╯ ╭─ Resource Slots ───────────────────────────────────╮ │ Tool Slot Type │ │ ───────────────── ──────── ────────────────── │ │ query_db database local/postgres-db │ │ execute_migration database local/postgres-db │ │ backfill_column database local/postgres-db │ ╰────────────────────────────────────────────────────╯

✓ OK Skill registered with 3 tools

Step 3: Create the Migration Action and Execute the Plan

Create actions/add-column-with-backfill.yaml:


name: local/add-column-with-backfill
description: "Add a column, backfill data, and update application code"
definition_of_done: |
  - Database migration adds the column with a sensible default
  - Backfill completes for all rows using the specified source
  - Application code reads/writes the new column
  - All tests pass with the new schema
  - A rollback migration is available and tested
strategy_actor: anthropic/claude-3.5-sonnet
execution_actor: anthropic/claude-3.5-sonnet
automation_profile: review
reusable: true
state: available
args:
  - name: table_name
    type: string
    required: true
  - name: column_name
    type: string
    required: true
  - name: column_type
    type: string
    required: true
  - name: backfill_source
    type: string
    required: true
    description: "Description of where to source backfill data"
invariants:
  - "Migration must be backward-compatible (add column, don't rename or drop)"
  - "Backfill must be batched to avoid locking the table"
  - "Rollback migration must be provided and tested"
  - "Application code must handle both old (null) and new values gracefully"

$ agents action create --config ./actions/add-column-with-backfill.yaml ╭─ Action Created ────────────────────────────────────╮ │ Name: local/add-column-with-backfill │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Config: ./actions/add-column-with-backfill.yaml │ │ Created: 2026-02-11 09:05 │ ╰─────────────────────────────────────────────────────╯ ╭─ Definition of Done ─────────────────────────────────────────────╮ │ - Database migration adds the column with a sensible default │ │ - Backfill completes for all rows using the specified source │ │ - Application code reads/writes the new column │ │ - All tests pass with the new schema │ │ - A rollback migration is available and tested │ ╰──────────────────────────────────────────────────────────────────╯ ╭─ Arguments ────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ──────────────── ────── ──────── ───────────────────────────────── │ │ table_name string yes (none) │ │ column_name string yes (none) │ │ column_type string yes (none) │ │ backfill_source string yes Where to source backfill data │ ╰────────────────────────────────────────────────────────────────────────╯ ╭─ Invariants ──────────────────────────────────────────────────────────────────────╮ │ 1. Migration must be backward-compatible (add column, don't rename or drop) │ │ 2. Backfill must be batched to avoid locking the table │ │ 3. Rollback migration must be provided and tested │ │ 4. Application code must handle both old (null) and new values gracefully │ ╰───────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────╮ │ Profile: review │ │ Source: action config │ ╰───────────────────────────────────╯ ╭─ Usage ─────────────────────────────────────────────────────────────────────────╮ │ agents plan use local/add-column-with-backfill local/api-service │ │ --arg table_name=TABLE --arg column_name=COL │ │ --arg column_type=TYPE --arg backfill_source=SOURCE │ ╰─────────────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

$ agents plan use local/add-column-with-backfill local/api-service \ --arg table_name="users" \ --arg column_name="last_login_at" \ --arg column_type="TIMESTAMP WITH TIME ZONE" \ --arg backfill_source="audit_log table, event_type='login', max(created_at) per user_id" ╭─ Plan Created ──────────────────────────────────────╮ │ Plan ID: 01HXR5E6F7G8H9J0K1L2M3N4O5 │ │ Phase: strategize │ │ Action: local/add-column-with-backfill │ │ Project: local/api-service │ │ Automation: review │ │ Attempt: 1 │ ╰─────────────────────────────────────────────────────╯ ╭─ Inputs ────────────────────────────────────────────────────────────────────────────╮ │ - table_name=users │ │ - column_name=last_login_at │ │ - column_type=TIMESTAMP WITH TIME ZONE │ │ - backfill_source=audit_log table, event_type='login', max(created_at) per user_id │ ╰─────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Actors ───────────────────────────────────╮ │ Strategy: anthropic/claude-3.5-sonnet │ │ Execution: anthropic/claude-3.5-sonnet │ │ Estimation: (none) │ ╰────────────────────────────────────────────╯ ╭─ Plan Invariants ──────────────────────────────────────────────────────────────╮ │ Scope Source Invariant │ │ ──────── ─────── ────────────────────────────────────────────────────── │ │ plan action Migration must be backward-compatible │ │ plan action Backfill must be batched to avoid locking the table │ │ plan action Rollback migration must be provided and tested │ │ plan action Application code must handle both old (null) and new values │ ╰────────────────────────────────────────────────────────────────────────────────╯ ╭─ Context ──────────────────────────────╮ │ Resources: 2 (git-checkout, postgres) │ │ Indexed Files: 347 │ │ View: strategize │ │ Hot Token Budget: 12,000 │ ╰────────────────────────────────────────╯ ╭─ Next Steps ───────────────────────────────────────╮ │ - agents plan execute 01HXR5E6F7G8H9J0K1L2M3N4O5 │ │ - agents plan status 01HXR5E6F7G8H9J0K1L2M3N4O5 │ │ - agents plan tree 01HXR5E6F7G8H9J0K1L2M3N4O5 │ ╰────────────────────────────────────────────────────╯

✓ OK Plan created

The strategy produces a phased plan with child plans:

Generate Alembic migration (add column with NULL default)
Generate rollback migration
Backfill from audit_log in batches of 10,000
Update ORM model and application code
Run tests with new schema

Each phase creates checkpoints. If the backfill fails at batch 850 of 1,000, the system can restore to the pre-backfill checkpoint rather than starting over.

Step 4: Monitor Execution and Rollback if Needed

# Monitor the migration execution $ agents plan status 01HXR5E6F7G8H9J0K1L2M3N4O5 ╭─ Plan Status ───────────────────────────────────────╮ │ Plan: 01HXR5E6F7G8H9J0K1L2M3N4O5 │ │ Phase: execute │ │ State: processing │ │ Action: local/add-column-with-backfill │ │ Project: local/api-service │ │ Automation: review │ │ Attempt: 1 │ ╰─────────────────────────────────────────────────────╯ ╭─ Progress ─────────────────╮ │ ✓ Strategize │ │ ⏳ Execute (phase 3 of 5) │ │ • Apply (queued) │ ╰────────────────────────────╯ ╭─ Child Plans ────────────────────────────────────────────────────────────╮ │ Phase Description Status │ │ ───── ─────────────────────────────────── ────────────────────── │ │ 1 Generate Alembic migration ✓ complete │ │ 2 Generate rollback migration ✓ complete │ │ 3 Backfill from audit_log ⏳ batch 620/1,000 │ │ 4 Update ORM model and application code ○ waiting │ │ 5 Run tests with new schema ○ waiting │ ╰──────────────────────────────────────────────────────────────────────────╯ ╭─ Execution Detail ──────────────────────╮ │ Sandbox: transaction_rollback │ │ Tool Calls: 14 │ │ Files Modified: 2 │ │ Rows Backfilled: 6,200,000 / 10,000,000 │ │ Checkpoints: 4 created │ ╰─────────────────────────────────────────╯ ╭─ Timing ──────────────╮ │ Started: 09:06:01 │ │ Elapsed: 00:04:32 │ │ ETA: 00:02:50 │ ╰───────────────────────╯ ╭─ Cost ───────────────╮ │ Tokens Used: 18,940 │ │ Cost So Far: $0.063 │ │ Estimated: $0.110 │ ╰──────────────────────╯

✓ OK Status refreshed

# If something goes wrong during backfill, rollback to the pre-backfill checkpoint $ agents plan rollback --yes 01HXR5E6F7G8H9J0K1L2M3N4O5 cp_01HXR5CP3 ╭─ Rollback Summary ───────────────────────────────────╮ │ Plan: 01HXR5E6F7G8H9J0K1L2M3N4O5 │ │ Checkpoint: cp_01HXR5CP3 │ │ Label: before backfill (after migration applied) │ │ Files: 2 reverted │ ╰──────────────────────────────────────────────────────╯ ╭─ Changes Reverted ──────────────────────────────────────────╮ │ File Action │ │ ─────────────────────────────────────────── ────────── │ │ alembic/versions/20260211_add_last_login.py restored │ │ alembic/versions/20260211_rollback.py restored │ ╰─────────────────────────────────────────────────────────────╯ ╭─ Database Rollback ─────────────────────────────────────────╮ │ Transaction: rolled back │ │ Rows Affected: 6,200,000 updates reverted │ │ Schema State: restored to pre-backfill │ ╰─────────────────────────────────────────────────────────────╯ ╭─ Impact ──────────────────────────────────────╮ │ Child Plans Invalidated: 1 (backfill phase) │ │ Sandbox: restored to cp_01HXR5CP3 │ │ Decisions After CP: 3 discarded │ │ Tool Calls After CP: 8 undone │ ╰───────────────────────────────────────────────╯ ╭─ Post-Rollback State ──────────╮ │ Phase: execute │ │ State: queued (awaiting input) │ │ Checkpoints Remaining: 3 │ ╰────────────────────────────────╯

✓ OK Rollback complete

Example 6: Writing Technical Documentation from Codebase Analysis

Scenario: A project has grown to 50,000 lines of code with minimal documentation. The team wants CleverAgents to generate comprehensive API documentation, architecture guides, and developer onboarding docs by analyzing the actual codebase.

Complexity: Intermediate. Read-only action, large context usage, no sandbox modifications to source code.

Step 1: Create a Read-Only Documentation Action

Create actions/generate-docs.yaml:


name: local/generate-docs
description: "Generate comprehensive documentation from codebase analysis"
long_description: |
  Analyze the project codebase to produce developer documentation:
  API reference, architecture overview, module guides, and onboarding
  material. Uses code intelligence (search, vector similarity, graph
  queries) to understand structure and relationships.
definition_of_done: |
  - API reference covers all public endpoints/functions
  - Architecture document shows module dependencies and data flow
  - Each major module has a developer guide
  - An onboarding document provides setup and contribution instructions
  - All generated docs are accurate to the current codebase
  - Documentation is written in Markdown format
strategy_actor: anthropic/claude-3.5-sonnet
execution_actor: anthropic/claude-3.5-sonnet
read_only: false
reusable: true
state: available
args:
  - name: doc_types
    type: string
    required: true
    description: "Comma-separated list: api-reference, architecture, module-guides, onboarding"
  - name: output_dir
    type: string
    required: false
    default: "docs/"
    description: "Output directory for generated docs"
invariants:
  - "Do not modify any source code files — only create or update files in the output directory"
  - "All code examples in documentation must be actual code from the project, not fabricated"
  - "Architecture diagrams must reflect actual module dependencies, not aspirational ones"

$ agents action create --config ./actions/generate-docs.yaml ╭─ Action Created ──────────────────────────────────────────────────────────────────╮ │ Name: local/generate-docs │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Created: 2026-02-11 10:30 │ ╰───────────────────────────────────────────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────────────────────────────────╮ │ - API reference covers all public endpoints/functions │ │ - Architecture document shows module dependencies and data flow │ │ - Each major module has a developer guide │ │ - An onboarding document provides setup and contribution instructions │ │ - All generated docs are accurate to the current codebase │ │ - Documentation is written in Markdown format │ ╰───────────────────────────────────────────────────────────────────────────────────╯ ╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ────────── ────── ──────── ────────────────────────────────────────────────────────────── │ │ doc_types string yes Comma-separated list: api-reference, architecture, module-guides… │ │ output_dir string no Output directory for generated docs (default: docs/) │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Invariants ───────────────────────────────────────────────────────────────────────────────────────╮ │ 1. Do not modify any source code files — only create or update files in the output directory │ │ 2. All code examples in documentation must be actual code from the project, not fabricated │ │ 3. Architecture diagrams must reflect actual module dependencies, not aspirational ones │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: (inherits global) │ │ Source: default │ ╰───────────────────────────────────────╯ ╭─ Usage ────────────────────────────────────────────────────────────────────────────╮ │ agents plan use local/generate-docs local/api-service │ │ --arg doc_types="api-reference,architecture,module-guides,onboarding" │ ╰────────────────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

Step 2: Configure Context for Large Codebase Analysis

# Set a generous context policy for the strategize view (needs to see architecture) $ agents project context set --view strategize \ --include-resource 01HXR6A1B2C3D4E5F6G7H8J9K0 \ --exclude-path "**/node_modules/**" \ --exclude-path "**/.git/**" \ --exclude-path "**/dist/**" \ --hot-max-tokens 32000 \ --warm-max-decisions 200 \ --query-limit 50 \ --max-file-size 2097152 \ --summarize \ --summary-max-tokens 1500 \ local/api-service ╭─ Context Policy ────────────────────────────────────────╮ │ Project: local/api-service │ │ View: strategize │ │ Include: 01HXR6A1B2C3D4E5F6G7H8J9K0 │ │ Exclude: /node_modules/, /.git/, /dist/ │ ╰─────────────────────────────────────────────────────────╯ ╭─ Limits ──────────────────────────╮ │ Hot Tokens: 32000 (soft cap) │ │ Warm Decisions: 200 │ │ Query Limit: 50 │ │ Max File Size: 2 MB │ │ Max Total Size: 50 MB │ ╰───────────────────────────────────╯ ╭─ Summarization ──────╮ │ Enabled: yes │ │ Max Tokens: 1500 │ ╰──────────────────────╯ ╭─ Other Views ──────────╮ │ execute: (default) │ │ apply: (default) │ │ default: (unset) │ ╰────────────────────────╯

✓ OK Context policy updated

# Execution view can be narrower (writing docs, not analyzing all code) $ agents project context set --view execute \ --include-resource 01HXR6A1B2C3D4E5F6G7H8J9K0 \ --hot-max-tokens 16000 \ --query-limit 30 \ --summarize \ local/api-service ╭─ Context Policy ────────────────────────────────────────╮ │ Project: local/api-service │ │ View: execute │ │ Include: 01HXR6A1B2C3D4E5F6G7H8J9K0 │ ╰─────────────────────────────────────────────────────────╯ ╭─ Limits ──────────────────────────╮ │ Hot Tokens: 16000 (soft cap) │ │ Query Limit: 30 │ │ Max File Size: 1 MB │ │ Max Total Size: 50 MB │ ╰───────────────────────────────────╯ ╭─ Summarization ─╮ │ Enabled: yes │ │ Max Tokens: 800 │ ╰─────────────────╯ ╭─ Other Views ──────────────╮ │ strategize: configured │ │ apply: (default) │ │ default: (unset) │ ╰────────────────────────────╯

✓ OK Context policy updated

Step 3: Execute

$ agents plan use \ --automation-profile trusted \ --arg doc_types="api-reference,architecture,module-guides,onboarding" \ --arg output_dir="docs/generated/" \ local/generate-docs local/api-service ╭─ Plan Created ──────────────────────────────────────╮ │ Plan: 01HXR6F7G8H9J0K1L2M3N4O5P6 │ │ Phase: strategize │ │ State: processing │ │ Action: local/generate-docs │ │ Project: local/api-service │ │ Automation: trusted │ │ Attempt: 1 │ ╰─────────────────────────────────────────────────────╯ ╭─ Inputs ─────────────────────────────────────────────────────────────────────╮ │ - doc_types="api-reference,architecture,module-guides,onboarding" │ │ - output_dir="docs/generated/" │ │ - automation_profile=trusted │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Actors ────────────────────────────────────────╮ │ Strategy: anthropic/claude-3.5-sonnet │ │ Execution: anthropic/claude-3.5-sonnet │ │ Estimation: (none) │ ╰─────────────────────────────────────────────────╯ ╭─ Automation ───────────────────────────╮ │ Profile: trusted │ │ Source: plan override │ │ Read-Only: no │ ╰────────────────────────────────────────╯ ╭─ Context ──────────────────────────╮ │ Resources: 1 (git-checkout) │ │ Indexed Files: 487 │ │ View: strategize │ │ Hot Token Budget: 32,000 │ ╰────────────────────────────────────╯ ╭─ Next Steps ─────────────────────────────────────────────────────────╮ │ Trusted profile — strategize and execute will proceed automatically. │ │ - agents plan status 01HXR6F7G8H9J0K1L2M3N4O5P6 │ │ - agents plan tree 01HXR6F7G8H9J0K1L2M3N4O5P6 │ ╰──────────────────────────────────────────────────────────────────────╯

✓ OK Plan created

The system analyzes the codebase using the code intelligence indexes (full-text, vector, and graph) to understand module relationships, public APIs, and data flows. It generates documentation files in the sandbox.

# Review generated docs $ agents plan artifacts 01HXR6F7G8H9J0K1L2M3N4O5P6 ╭─ Artifacts ───────────────────────────────────────────────────────────────────────────╮ │ Path Type Size Change Child Plan │ │ ──────────────────────────────────────── ───── ─────── ──────── ─────── │ │ docs/generated/api-reference.md write 18.2 KB +412 -0 root │ │ docs/generated/architecture.md write 12.6 KB +284 -0 root │ │ docs/generated/modules/auth.md write 6.4 KB +148 -0 root │ │ docs/generated/modules/billing.md write 5.8 KB +131 -0 root │ │ docs/generated/modules/notifications.md write 4.2 KB +97 -0 root │ │ docs/generated/modules/data-pipeline.md write 5.1 KB +118 -0 root │ │ docs/generated/onboarding.md write 8.9 KB +201 -0 root │ ╰───────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Summary ─────────────╮ │ Total: 7 │ │ Writes: 7 (new) │ │ Edits: 0 │ │ Deletes: 0 │ │ Total Size: 61.2 KB │ ╰───────────────────────╯

✓ OK 7 artifacts listed

$ agents plan diff 01HXR6F7G8H9J0K1L2M3N4O5P6 ╭─ Diff Summary ─────────────────────────────────────╮ │ Plan: 01HXR6F7G8H9J0K1L2M3N4O5P6 │ │ Project: local/api-service │ │ Files Changed: 7 │ │ Insertions: 1,391 │ │ Deletions: 0 │ │ Net Change: +1,391 lines │ ╰────────────────────────────────────────────────────╯ ╭─ Files ──────────────────────────────────────────────────────────╮ │ Path Change Status │ │ ──────────────────────────────────────── ───────── ───────── │ │ docs/generated/api-reference.md +412 -0 new file │ │ docs/generated/architecture.md +284 -0 new file │ │ docs/generated/modules/auth.md +148 -0 new file │ │ docs/generated/modules/billing.md +131 -0 new file │ │ docs/generated/modules/notifications.md +97 -0 new file │ │ docs/generated/modules/data-pipeline.md +118 -0 new file │ │ docs/generated/onboarding.md +201 -0 new file │ ╰──────────────────────────────────────────────────────────────────╯ ╭─ Patch Preview ───────────────────────────────────────────────────────╮ │ --- /dev/null │ │ +++ b/docs/generated/api-reference.md │ │ @@ -0,0 +1,412 @@ │ │ + # API Reference │ │ + ## Authentication │ │ + ### POST /auth/login │ │ + ... │ │ --- /dev/null │ │ +++ b/docs/generated/architecture.md │ │ @@ -0,0 +1,284 @@ │ │ + # Architecture Overview │ │ + ## Module Dependency Graph │ │ + ... │ ╰───────────────────────────────────────────────────────────────────────╯ ╭─ Risk Assessment ─────────────────╮ │ Source Code: unmodified │ │ Breaking Changes: none detected │ │ New Files Only: yes │ ╰───────────────────────────────────╯

✓ OK Diff generated

# Apply the documentation to the project $ agents plan apply --yes 01HXR6F7G8H9J0K1L2M3N4O5P6 ╭─ Apply Summary ──────────────────────────────╮ │ Plan: 01HXR6F7G8H9J0K1L2M3N4O5P6 │ │ Artifacts: 7 files created │ │ Changes: 1,391 insertions, 0 deletions │ │ Project: local/api-service │ │ Applied At: 2026-02-11 10:38 │ ╰──────────────────────────────────────────────╯ ╭─ Validation ────────────────────────────────╮ │ ✓ Invariant: no source files modified │ │ ✓ Invariant: code examples verified │ │ ✓ Invariant: architecture matches codebase │ │ Duration: 4.1s │ ╰─────────────────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ─────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:08:12 │ │ Total Cost: $0.184 │ │ Decisions Made: 18 │ │ Child Plans: 0 │ ╰──────────────────────────────────────────╯ ╭─ Next Steps ──────╮ │ - Review git diff │ │ - Commit changes │ ╰───────────────────╯

✓ OK Changes applied

Example 7: CI/CD Integration — Automated PR Review and Fix

Scenario: A CI pipeline triggers CleverAgents to automatically review incoming pull requests, run analysis, and if issues are found, create fix commits. This runs headlessly without human intervention.

Complexity: Advanced. Non-interactive (CI profile), headless execution, full automation.

Step 1: Configure for CI

# Set CI-appropriate configuration $ agents config set core.automation-profile ci ╭─ Config Updated ───────────────────────────╮ │ Key: core.automation-profile │ │ Value: ci │ │ Previous: (not set) │ │ Source: config │ │ Scope: global │ ╰────────────────────────────────────────────╯ ╭─ Effective ────────────────────────╮ │ Sessions: new sessions │ │ Plans: future plans (unless set) │ │ Existing: unchanged │ ╰────────────────────────────────────╯ ╭─ Saved To ──────────────────────────╮ │ File: ~/.cleveragents/config.toml │ │ Line: 3 │ ╰─────────────────────────────────────╯ ✓ OK Config updated $ agents config set core.format json ╭─ Config Updated ─────────────────╮ │ Key: core.format │ │ Value: json │ │ Previous: (not set) │ │ Source: config │ │ Scope: global │ ╰──────────────────────────────────╯ ╭─ Saved To ──────────────────────────╮ │ File: ~/.cleveragents/config.toml │ │ Line: 4 │ ╰─────────────────────────────────────╯ ✓ OK Config updated $ agents config set core.log.level WARN ╭─ Config Updated ──────────────────╮ │ Key: core.log.level │ │ Value: WARN │ │ Previous: FATAL │ │ Source: config │ │ Scope: global │ ╰───────────────────────────────────╯ ╭─ Saved To ──────────────────────────╮ │ File: ~/.cleveragents/config.toml │ │ Line: 5 │ ╰─────────────────────────────────────╯

✓ OK Config updated

Step 2: Create the PR Review Action

Create actions/review-pr.yaml:


name: local/review-pr
description: "Automatically review a PR and fix issues"
definition_of_done: |
  - All lint issues are resolved
  - Type checking passes
  - Test coverage does not decrease
  - Security scan passes
  - All fixes are committed to the PR branch
strategy_actor: anthropic/claude-3.5-sonnet
execution_actor: anthropic/claude-3.5-sonnet
automation_profile: ci
reusable: true
state: available
args:
  - name: pr_branch
    type: string
    required: true
    description: "Branch name of the PR"
  - name: base_branch
    type: string
    required: false
    default: "main"
    description: "Base branch to compare against"
invariants:
  - "Only modify files that are already changed in the PR"
  - "Do not change the intent of any code — only fix style, types, and test issues"
  - "All fixes must include a comment explaining what was changed and why"

$ agents action create --config ./actions/review-pr.yaml ╭─ Action Created ──────────────────────────────╮ │ Name: local/review-pr │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Created: 2026-02-11 14:00 │ ╰───────────────────────────────────────────────╯ ╭─ Definition of Done ─────────────────────────────────────╮ │ - All lint issues are resolved │ │ - Type checking passes │ │ - Test coverage does not decrease │ │ - Security scan passes │ │ - All fixes are committed to the PR branch │ ╰──────────────────────────────────────────────────────────╯ ╭─ Arguments ──────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ────────── ────── ──────── ────────────────────────────────── │ │ pr_branch string yes Branch name of the PR │ │ base_branch string no Base branch to compare against │ ╰──────────────────────────────────────────────────────────────────╯ ╭─ Invariants ─────────────────────────────────────────────────────────────────────╮ │ 1. Only modify files that are already changed in the PR │ │ 2. Do not change the intent of any code — only fix style, types, and test │ │ issues │ │ 3. All fixes must include a comment explaining what was changed and why │ ╰──────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────╮ │ Profile: ci │ │ Source: action config │ ╰───────────────────────────────╯ ╭─ Usage ──────────────────────────────────────────────────────────────────╮ │ agents plan use local/review-pr <PROJECT> │ │ --arg pr_branch="..." │ ╰──────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

Step 3: CI Pipeline Script


#!/bin/bash
# ci-review.sh — called by CI when a PR is opened or updated
set -euo pipefail
PR_BRANCH="${1:?Usage: ci-review.sh <branch>}"
BASE_BRANCH="${2:-main}"
# Register the resource pointing to the CI workspace.
RESOURCE_NAME="local/ci-${PR_BRANCH}"
agents resource add git-checkout "$RESOURCE_NAME" 

--path "$GITHUB_WORKSPACE" 

--branch "$PR_BRANCH"
echo "Registered resource: $RESOURCE_NAME"
# Create a project for this CI run, linking the resource by name.
# If the project already exists from a previous run, ignore the error.
agents --format json project create -d "CI workspace for PR $PR_BRANCH" 

--resource "$RESOURCE_NAME" 

local/ci-workspace 2>/dev/null || true
# Register and attach validations (idempotent — duplicates are ignored)
agents --format json validation add 

--config validations/lint.yaml --required local/ci-lint 2>/dev/null || true
agents --format json validation add 

--config validations/typecheck.yaml --required local/ci-typecheck 2>/dev/null || true
agents --format json validation add 

--config validations/tests.yaml --required local/ci-tests 2>/dev/null || true
agents --format json validation attach 

--project local/ci-workspace local/ci-lint 2>/dev/null || true
agents --format json validation attach 

--project local/ci-workspace local/ci-typecheck 2>/dev/null || true
agents --format json validation attach 

--project local/ci-workspace local/ci-tests 2>/dev/null || true
# Run the plan — ci profile means full automation including apply
PLAN_OUTPUT=$(agents --format json plan use 

--automation-profile ci 

--arg pr_branch="$PR_BRANCH" 

--arg base_branch="$BASE_BRANCH" 

local/review-pr local/ci-workspace)
PLAN_ID=$(echo "$PLAN_OUTPUT" | jq -r '.plan_id')
echo "Plan started: $PLAN_ID"
# Wait for completion (ci profile runs everything automatically)
while true; do
STATUS=$(agents --format json plan status "$PLAN_ID" | jq -r '.state')
case "$STATUS" in
applied)
echo "PR review complete. Changes applied."
break
;;
failed|cancelled)
echo "PR review failed."
agents --format json plan status "$PLAN_ID"
exit 1
;;
*)
sleep 10
;;
esac
done
# Output the diff for the CI log
agents --format json plan diff "$PLAN_ID"

Sample --format json output from resource add (captured into $RESOURCE_JSON):


{
  "id": "01HXR7G1A2B3C4D5E6F7H8J9K0",
  "type": "git-checkout",
  "physical": true,
  "path": "/home/runner/work/acme-api/acme-api",
  "branch": "fix/handle-null-users",
  "created": "2026-02-11T14:05:32Z",
  "children_discovered": 247,
  "capabilities": {
    "readable": true,
    "writable": true,
    "sandboxable": true,
    "checkpointable": true,
    "sandbox_strategy": "git_worktree"
  }
}

Sample --format json output from plan use (captured into $PLAN_OUTPUT):


{
  "plan_id": "01HXR7H2B3C4D5E6F7G8J9K0L1",
  "phase": "strategize",
  "action": "local/review-pr",
  "project": "local/ci-workspace",
  "automation_profile": "ci",
  "attempt": 1,
  "args": {
    "pr_branch": "fix/handle-null-users",
    "base_branch": "main"
  },
  "resources": ["01HXR7G1A2B3C4D5E6F7H8J9K0"]
}

Example 8: Cloud Infrastructure Management

Scenario: A DevOps team manages Terraform infrastructure. They want CleverAgents to analyze their current infrastructure, propose optimizations (right-sizing, unused resources), and generate the Terraform changes.

Complexity: Advanced. Custom resource types, custom skills, infrastructure domain.

Step 1: Register Custom Resource Types and Skills

Create resource-types/terraform-state.yaml:


name: local/terraform-state
description: "Terraform state file resource type"
physical: true
user_addable: true
sandbox_strategy: filesystem_copy
cli_args:
  - name: state-path
    type: string
    required: true
    description: "Path to terraform.tfstate or remote state configuration"
  - name: workspace
    type: string
    required: false
    default: "default"
    description: "Terraform workspace name"
handler: local/terraform-state-handler
child_types:
  - type: fs-file
    relationship: contains

Create skills/terraform-ops.yaml:


name: local/terraform-ops
description: "Terraform infrastructure operations"
tools:
  - name: terraform_plan
    description: "Run terraform plan and return the execution plan"
    input_schema:
      type: object
      properties:
        target:
          type: string
          description: "Specific resource to target (optional)"
      required: []
    writes: false
    checkpointable: false


name: terraform_show
description: "Show current state of a Terraform resource"
input_schema:
type: object
properties:
resource_address:
type: string
description: "Terraform resource address (e.g., aws_instance.web)"
required: [resource_address]
writes: false
checkpointable: false


name: cloud_metrics
description: "Fetch CloudWatch/cloud monitoring metrics for a resource"
input_schema:
type: object
properties:
resource_id:
type: string
metric:
type: string
description: "e.g., CPUUtilization, NetworkIn, RequestCount"
period_days:
type: integer
default: 30
required: [resource_id, metric]
writes: false
checkpointable: false


include_skills:

local/file-ops

$ agents resource type add --config ./resource-types/terraform-state.yaml ╭─ Resource Type ──────────────────────────────╮ │ Name: local/terraform-state │ │ Physical/Virtual: physical │ │ User Addable: yes │ │ Registered: 2026-02-11 14:30 │ ╰──────────────────────────────────────────────╯ ╭─ CLI Arguments ──────────────────────────────────────────────────────────────╮ │ Argument Required Description │ │ ────────────── ──────── ────────────────────────────────────────────── │ │ --state-path yes Path to terraform.tfstate or remote state config │ │ --workspace no Terraform workspace name (default: "default") │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Child Types ──────────────╮ │ Auto-discover: fs-file │ ╰────────────────────────────╯ ╭─ Sandbox ───────────────────────────────────────────╮ │ Strategy: filesystem_copy │ │ Handler: local/terraform-state-handler (custom) │ ╰─────────────────────────────────────────────────────╯

✓ OK Resource type registered ℹ New subcommand available: agents resource add local/terraform-state

$ agents skill add --config ./skills/terraform-ops.yaml ╭─ Skill ──────────────────────────────────────────╮ │ Name: local/terraform-ops │ │ Description: Terraform infrastructure operations │ │ Config: ./skills/terraform-ops.yaml │ │ Created: 2026-02-11 14:31 │ ╰──────────────────────────────────────────────────╯ ╭─ Includes ────────────────────╮ │ local/file-ops (registered) │ ╰───────────────────────────────╯ ╭─ Tool Sources ───────────────────────────────────────────────────────╮ │ Source Count Details │ │ ──────── ───── ────────────────────────────────────────────── │ │ custom 3 terraform_plan, terraform_show, cloud_metrics │ │ included 5 local/file-ops (5) │ │ ──────── ───── ────────────────────────────────────────────── │ │ Total: 8 │ ╰──────────────────────────────────────────────────────────────────────╯

✓ OK Skill registered with 8 tools

Step 2: Set Up the Project

# Register the infrastructure git checkout $ agents resource add git-checkout local/infra-repo \ --path /repos/infrastructure --branch main ╭─ Resource ──────────────────────────────────────╮ │ Name: local/infra-repo │ │ ID: 01HXR8A1B2C3D4E5F6G7H8J9K0 │ │ Type: git-checkout │ │ Physical/Virtual: physical │ │ Path: /repos/infrastructure │ │ Branch: main │ │ Created: 2026-02-11 14:32 │ ╰─────────────────────────────────────────────────╯ ╭─ Auto-discovered Children ─────────────────────────────────────────╮ │ ID Type Status │ │ ─────────────── ────────────── ───────────────── │ │ 01HXR8A1B2C3… git created │ │ 01HXR8A1B2C4… git-remote created │ │ 01HXR8A1B2C5… git-branch created │ │ 01HXR8A1B2C6… fs-directory created │ │ + 18 git-commit resources │ │ + 84 git-tree-entry resources │ │ + 6 fs-directory + 42 fs-file │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Capabilities ─────────────────╮ │ Readable: yes │ │ Writable: yes │ │ Sandboxable: yes │ │ Checkpointable: yes │ │ Sandbox Strategy: git_worktree │ ╰────────────────────────────────╯

✓ OK Resource registered (155 child resources discovered)

# Register the Terraform state for the production workspace $ agents resource add local/terraform-state local/prod-tfstate \ --state-path /repos/infrastructure/environments/prod/terraform.tfstate \ --workspace production ╭─ Resource ──────────────────────────────────────────────────────────────────╮ │ Name: local/prod-tfstate │ │ ID: 01HXR8B2C3D4E5F6G7H8J9K0L1 │ │ Type: local/terraform-state │ │ Physical/Virtual: physical │ │ State Path: /repos/infrastructure/environments/prod/terraform.tfstate │ │ Workspace: production │ │ Created: 2026-02-11 14:32 │ ╰─────────────────────────────────────────────────────────────────────────────╯ ╭─ Auto-discovered Children ─────────────╮ │ + 1 fs-file (terraform.tfstate) │ ╰────────────────────────────────────────╯ ╭─ Capabilities ──────────────────────╮ │ Readable: yes │ │ Writable: yes │ │ Sandboxable: yes │ │ Checkpointable: yes │ │ Sandbox Strategy: filesystem_copy │ ╰─────────────────────────────────────╯

✓ OK Resource registered (1 child resource discovered)

# Create the project, linking both resources by name $ agents project create -d "Production infrastructure" \ --resource local/infra-repo \ --resource local/prod-tfstate \ --invariant "Never delete or modify resources tagged with 'critical: true'" \ --invariant "All changes must be backward-compatible with running services" \ --invariant "Cost changes must be documented in the PR description" \ local/infra-prod ╭─ Project Created ─────────────────────────────╮ │ Name: local/infra-prod │ │ Description: Production infrastructure │ │ Remote: no │ ╰───────────────────────────────────────────────╯ ╭─ Linked Resources ──────────────────────────────────────────────────╮ │ Resource Type Read-Only │ │ ──────────────────────────── ────────────────────── ───────── │ │ local/infra-repo git-checkout no │ │ local/prod-tfstate local/terraform-state no │ ╰─────────────────────────────────────────────────────────────────────╯ ╭─ Invariants ──────────────────────────────────────────────────────────────╮ │ 1. Never delete or modify resources tagged with 'critical: true' │ │ 2. All changes must be backward-compatible with running services │ │ 3. Cost changes must be documented in the PR description │ ╰───────────────────────────────────────────────────────────────────────────╯

✓ OK Project created

$ agents validation add --config validations/tf-validate.yaml --required local/tf-validate ╭─ Validation Registered ────────────────────────────────────────────╮ │ Name: local/tf-validate │ │ Command: cd environments/prod && terraform validate │ │ Mode: required │ │ Timeout: 300s │ ╰────────────────────────────────────────────────────────────────────╯ ✓ OK Validation registered

$ agents validation attach --project local/infra-prod local/tf-validate ✓ OK Validation attached to project local/infra-prod

$ agents validation add --config validations/tf-plan.yaml --informational local/tf-plan ╭─ Validation Registered ─────────────────────────────────────────────────────────╮ │ Name: local/tf-plan │ │ Command: cd environments/prod && terraform plan -detailed-exitcode │ │ Mode: informational │ │ Timeout: 300s │ ╰─────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Validation registered

$ agents validation attach --project local/infra-prod local/tf-plan ✓ OK Validation attached to project local/infra-prod

Step 3: Create and Run the Optimization Action

Create actions/infra-optimize.yaml:


name: local/infra-optimize
description: "Analyze and optimize cloud infrastructure costs"
definition_of_done: |
  - Unused resources are identified and removal plans generated
  - Over-provisioned resources are identified with right-sizing recommendations
  - Terraform changes implement the approved optimizations
  - terraform validate passes on all changes
  - terraform plan shows no unexpected resource deletions
  - Estimated monthly cost savings are documented
strategy_actor: local/refactoring-strategist
execution_actor: anthropic/claude-3.5-sonnet
automation_profile: supervised
reusable: true
state: available
args:
  - name: optimization_targets
    type: string
    required: false
    default: "all"
    description: "Comma-separated: compute, storage, networking, database, all"
  - name: min_savings_threshold
    type: float
    required: false
    default: 10.0
    description: "Minimum monthly savings (USD) to include an optimization"
invariants:
  - "Changes to production databases require manual approval regardless of profile"
  - "Instance type downgrades must verify current peak CPU < 70% of new capacity"

$ agents action create --config ./actions/infra-optimize.yaml ╭─ Action Created ──────────────────────────────────────╮ │ Name: local/infra-optimize │ │ ID: 01HXR8C3D4E5F6G7H8J9K0L1M2 │ │ State: available │ │ Strategy Actor: local/refactoring-strategist │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Config: ./actions/infra-optimize.yaml │ │ Created: 2026-02-11 14:33 │ ╰───────────────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────────────────────╮ │ - Unused resources are identified and removal plans generated │ │ - Over-provisioned resources identified with right-sizing recs │ │ - Terraform changes implement the approved optimizations │ │ - terraform validate passes on all changes │ │ - terraform plan shows no unexpected resource deletions │ │ - Estimated monthly cost savings are documented │ ╰───────────────────────────────────────────────────────────────────────╯ ╭─ Arguments ───────────────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ────────────────────── ────── ──────── ────────────────────────────────── │ │ optimization_targets string no Comma-separated: compute, storage, … │ │ min_savings_threshold float no Min monthly savings (USD) to include │ ╰───────────────────────────────────────────────────────────────────────────────────╯ ╭─ Invariants ──────────────────────────────────────────────────────────────────────────╮ │ 1. Changes to production databases require manual approval regardless of profile │ │ 2. Instance type downgrades must verify current peak CPU < 70% of new capacity │ ╰───────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: supervised │ │ Source: action config │ ╰───────────────────────────────────────╯ ╭─ Usage ─────────────────────────────────────────────────────────────╮ │ agents plan use local/infra-optimize local/infra-prod │ │ --arg optimization_targets=TARGET --arg min_savings_threshold=N │ ╰─────────────────────────────────────────────────────────────────────╯

✓ OK Action created

$ agents plan use \ --arg optimization_targets="compute,storage" \ --arg min_savings_threshold=25.0 \ local/infra-optimize local/infra-prod ╭─ Plan Created ─────────────────────────────────────────╮ │ Plan ID: 01HXR8D4E5F6G7H8J9K0L1M2N3 │ │ Phase: strategize │ │ Action: local/infra-optimize │ │ Project: local/infra-prod │ │ Automation: supervised │ │ Attempt: 1 │ ╰────────────────────────────────────────────────────────╯ ╭─ Inputs ──────────────────────────────────────╮ │ - optimization_targets=compute,storage │ │ - min_savings_threshold=25.0 │ ╰───────────────────────────────────────────────╯ ╭─ Actors ─────────────────────────────────────╮ │ Strategy: local/refactoring-strategist │ │ Execution: anthropic/claude-3.5-sonnet │ │ Estimation: (none) │ ╰──────────────────────────────────────────────╯ ╭─ Plan Invariants ──────────────────────────────────────────────────────────────────╮ │ Scope Source Invariant │ │ ──────── ──────── ───────────────────────────────────────────────────────── │ │ plan action Prod DB changes require manual approval regardless │ │ plan action Instance downgrades must verify peak CPU < 70% of new cap │ │ project config Never delete or modify resources tagged 'critical: true' │ │ project config All changes must be backward-compatible with running svcs │ │ project config Cost changes must be documented in PR description │ ╰────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Context ──────────────────────────────────────────╮ │ Resources: 2 (git-checkout, terraform-state) │ │ Indexed Files: 156 │ │ View: strategize │ │ Hot Token Budget: 12,000 │ ╰────────────────────────────────────────────────────╯ ╭─ Next Steps ──────────────────────────────────────────╮ │ - agents plan execute 01HXR8D4E5F6G7H8J9K0L1M2N3 │ │ - agents plan status 01HXR8D4E5F6G7H8J9K0L1M2N3 │ │ - agents plan tree 01HXR8D4E5F6G7H8J9K0L1M2N3 │ ╰───────────────────────────────────────────────────────╯

✓ OK Plan created

The strategy actor queries cloud metrics via the cloud_metrics tool, analyzes the Terraform state using terraform_show, and proposes optimizations with cost estimates. Because the automation profile is supervised, the engineer reviews the full strategy — including any proposed instance downgrades or resource removals — before execution modifies any Terraform files. The execution actor then generates the .tf changes, and both validations (terraform validate and terraform plan -detailed-exitcode) run automatically before the plan can be applied.

Example 9: Session-Driven Interactive Exploration

Scenario: A developer uses a CleverAgents session to interactively explore a new codebase, ask questions, and gradually build up an action to automate a recurring task.

Complexity: Beginner-Intermediate. Session-based, conversational, action creation through natural language.

Step 1: Start a Session

$ agents session create --actor anthropic/claude-3.5-sonnet ╭─ Session ────────────────────────────────╮ │ ID: 01HXR9A1B2C3D4E5F6G7H8I9J0 │ │ Actor: anthropic/claude-3.5-sonnet │ │ Created: 2026-02-11 09:15 │ │ Namespace: local │ ╰──────────────────────────────────────────╯ ╭─ Settings ─────────────╮ │ Automation: review │ │ Streaming: off │ │ Context: default │ │ Memory: enabled │ │ Max History: 50 turns │ ╰────────────────────────╯ ╭─ Actor Details ────────────────────────╮ │ Provider: anthropic │ │ Model: claude-3.5-sonnet │ │ Temperature: 0.7 │ │ Context Window: 200K tokens │ ╰────────────────────────────────────────╯

✓ OK Session created

Step 2: Explore the Codebase Interactively

$ agents session tell --session 01HXR9A1B2C3D4E5F6G7H8I9J0 \ "I just joined the team and need to understand the api-service project. What are the main modules and how do they interact?" ╭─ Plan Request ──────────────────────────────────────────────────────────────────────────╮ │ Actor: anthropic/claude-3.5-sonnet │ │ Session: 01HXR9A1B2C3D4E5F6G7H8I9J0 │ │ Automation: review │ │ Prompt: I just joined the team and need to understand the api-service project. Wha... │ ╰─────────────────────────────────────────────────────────────────────────────────────────╯ ▍ The api-service project is organized into 5 core modules: src/api/routes/ — HTTP route definitions (REST + GraphQL). Each domain entity has its own router file (e.g. users.py, orders.py, products.py). src/api/services/ — Business logic layer. Services are injected into routes via dependency injection. Key files: user_service.py, order_service.py, notification_service.py. src/api/models/ — SQLAlchemy ORM models and Pydantic schemas. The models map 1:1 to database tables; schemas handle request/response validation. src/api/auth/ — Authentication and authorization. Implements JWT-based auth with role-based access control. Middleware in auth_middleware.py intercepts every request before it reaches a route handler. src/api/workers/ — Background task processors using Celery. Handles async jobs like email dispatch, report generation, and webhook delivery. Data flow: Routes → Services → Models → Database. Auth middleware gates every route. Workers are dispatched by services for async operations. ╭─ Commands Executed ──────────────────────────────────────────────────────────────╮ │ - agents resource inspect local/api-service-repo --tree │ │ - agents resource inspect local/api-service-repo --file src/api/__init__.py │ ╰──────────────────────────────────────────────────────────────────────────────────╯ ╭─ Usage ─────────────────────╮ │ Input Tokens: 2,480 │ │ Output Tokens: 846 │ │ Cost: $0.0128 │ │ Duration: 4.1s │ │ Tool Calls: 2 │ ╰─────────────────────────────╯

✓ OK Orchestrator completed 2 commands

$ agents session tell --session 01HXR9A1B2C3D4E5F6G7H8I9J0 \ "Show me how authentication works. What's the flow from request to response?" ╭─ Plan Request ───────────────────────────────────────────────────────────────────╮ │ Actor: anthropic/claude-3.5-sonnet │ │ Session: 01HXR9A1B2C3D4E5F6G7H8I9J0 │ │ Automation: review │ │ Prompt: Show me how authentication works. What's the flow from request to res... │ ╰──────────────────────────────────────────────────────────────────────────────────╯ ▍ Here is the authentication flow in api-service: 1. Request arrives → auth_middleware.py:34 extracts the Authorization header and parses the Bearer token. 2. Token validation → token_service.py:71 decodes the JWT using the public key from config.AUTH_PUBLIC_KEY. It verifies: - Signature (RS256) - Expiry (exp claim, default 3600s) - Issuer (iss must match api-service) 3. User resolution → user_service.py:45 loads the user record from the database using the sub claim. Returns 401 if the user is inactive or deleted. 4. Permission check → rbac.py:22 evaluates the user's roles against the endpoint's required permissions (defined as decorators on each route, e.g. @require_role("admin")). Returns 403 on insufficient permissions. 5. Context injection → The authenticated user object is attached to request.state.user so downstream route handlers can access it without repeating lookups. Key files: src/api/auth/auth_middleware.py, src/api/auth/token_service.py, src/api/auth/rbac.py, src/api/services/user_service.py. ╭─ Commands Executed ──────────────────────────────────────────────────────────────────────╮ │ - agents resource inspect local/api-service-repo --file src/api/auth/auth_middleware.py │ │ - agents resource inspect local/api-service-repo --file src/api/auth/token_service.py │ │ - agents resource inspect local/api-service-repo --file src/api/auth/rbac.py │ ╰──────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Usage ─────────────────────╮ │ Input Tokens: 3,960 │ │ Output Tokens: 1,024 │ │ Cost: $0.0187 │ │ Duration: 5.3s │ │ Tool Calls: 3 │ ╰─────────────────────────────╯

✓ OK Orchestrator completed 3 commands

$ agents session tell --session 01HXR9A1B2C3D4E5F6G7H8I9J0 \ "I notice the team manually runs a dependency lock refresh every week. Can you create an action that automates this?" ╭─ Plan Request ──────────────────────────────────────────────────────────────────────────╮ │ Actor: anthropic/claude-3.5-sonnet │ │ Session: 01HXR9A1B2C3D4E5F6G7H8I9J0 │ │ Automation: review │ │ Prompt: I notice the team manually runs a dependency lock refresh every week. Can... │ ╰─────────────────────────────────────────────────────────────────────────────────────────╯ ▍ I've created a local/refresh-locks action that automates the weekly dependency lock refresh. Here's what it does: Checks out the target project's repository Runs pip compile / poetry lock (auto-detected from project config) Runs the test suite to verify nothing broke Commits the updated lock files on a new branch Opens a pull request for review The action is now available. You can review the generated config with agents action show local/refresh-locks. ╭─ Commands Executed ──────────────────────────────────────────────────────╮ │ - agents action create --config ./actions/refresh-locks.yaml │ ╰──────────────────────────────────────────────────────────────────────────╯ ╭─ Result ──────────────────────────────╮ │ Action: local/refresh-locks │ │ Steps: 5 │ │ Trigger: manual │ ╰───────────────────────────────────────╯ ╭─ Usage ─────────────────────╮ │ Input Tokens: 5,210 │ │ Output Tokens: 1,380 │ │ Cost: $0.0249 │ │ Duration: 6.7s │ │ Tool Calls: 1 │ ╰─────────────────────────────╯

✓ OK Orchestrator completed 1 command

Step 3: Review Session History

$ agents session show 01HXR9A1B2C3D4E5F6G7H8I9J0 ╭─ Session Summary ─────────────────────────────╮ │ ID: 01HXR9A1B2C3D4E5F6G7H8I9J0 │ │ Actor: anthropic/claude-3.5-sonnet │ │ Messages: 6 │ │ Created: 2026-02-11 09:15 │ │ Updated: 2026-02-11 09:28 │ │ Automation: review │ ╰───────────────────────────────────────────────╯ ╭─ Recent Messages ──────────────────────────────────────────────────────────────────────╮ │ user I just joined the team and need to understand the api-service project... │ │ assistant The api-service project is organized into 5 core modules... │ │ user Show me how authentication works... │ │ assistant Here is the authentication flow in api-service... │ │ user I notice the team manually runs a dependency lock refresh... │ │ assistant I've created a local/refresh-locks action that automates... │ ╰────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Linked Plans ──────────────────────────────────╮ │ Plan ID Phase State │ │ ─────────────────────────── ─────── ──────── │ │ 01HXR9K4M7N2P3Q5R6S8T9U0V1 execute complete │ ╰─────────────────────────────────────────────────╯ ╭─ Token Usage ──────────────╮ │ Input Tokens: 11,650 │ │ Output Tokens: 3,250 │ │ Estimated Cost: $0.0564 │ ╰────────────────────────────╯

✓ OK Session details loaded

$ agents session export --output /tmp/onboarding-session.json 01HXR9A1B2C3D4E5F6G7H8I9J0 ╭─ Session Export ────────────────────────────╮ │ Session: 01HXR9A1B2C3D4E5F6G7H8I9J0 │ │ Output: /tmp/onboarding-session.json │ │ Messages: 6 │ │ Size: 38 KB │ │ Format: JSON │ ╰─────────────────────────────────────────────╯ ╭─ Contents ─────────────────╮ │ Messages: 6 │ │ Plan References: 1 │ │ Metadata Keys: 3 │ │ Actor Config: included │ │ Schema Version: v3 │ ╰────────────────────────────╯ ╭─ Integrity ──────────────────╮ │ Checksum: sha256:3e8f...b7d2 │ │ Encrypted: no │ ╰──────────────────────────────╯

✓ OK Export completed

Example 10: Full-Auto Batch Operations — Formatting and Linting

Scenario: A team has 15 Python packages in a monorepo that need to be reformatted with ruff format and have their imports sorted. This is low-risk and can be fully automated.

Complexity: Simple. Full-auto profile, batch execution, minimal risk.

Step 1: Create a Formatting Action

Create actions/format-codebase.yaml:


name: local/format-codebase
description: "Apply code formatting and import sorting"
definition_of_done: |
  - ruff format passes with zero changes remaining
  - ruff check --select I passes (imports sorted)
  - All existing tests pass
  - No semantic changes to any code
strategy_actor: anthropic/claude-3.5-sonnet
execution_actor: anthropic/claude-3.5-sonnet
automation_profile: full-auto
reusable: true
state: available
args:
  - name: formatter_config
    type: string
    required: false
    default: "pyproject.toml"
    description: "Path to the formatter configuration file"
invariants:
  - "Only whitespace and import ordering changes — no semantic modifications"
  - "Every package must pass its own test suite after formatting"

$ agents action create --config ./actions/format-codebase.yaml ╭─ Action Created ─────────────────────────────────╮ │ Name: local/format-codebase │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Created: 2026-02-11 14:00 │ ╰──────────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────────╮ │ - ruff format passes with zero changes remaining │ │ - ruff check --select I passes (imports sorted) │ │ - All existing tests pass │ │ - No semantic changes to any code │ ╰───────────────────────────────────────────────────────────╯ ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ──────────────── ────── ──────── ────────────────────────────────────── │ │ formatter_config string no Path to the formatter configuration file │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Invariants ──────────────────────────────────────────────────────────────────────╮ │ 1. Only whitespace and import ordering changes — no semantic modifications │ │ 2. Every package must pass its own test suite after formatting │ ╰───────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: full-auto │ │ Source: action │ ╰───────────────────────────────────────╯ ╭─ Usage ─────────────────────────────────────────────────────────╮ │ agents plan use local/format-codebase local/<project> │ │ --arg formatter_config="pyproject.toml" (optional) │ ╰─────────────────────────────────────────────────────────────────╯

✓ OK Action created

Step 2: Register All Packages and Run in Batch


# Register all 15 packages as resources and projects.
# resource add accepts a name — use it to link to project create.
for pkg in auth billing common gateway inventory notifications 

orders payments reporting search shipping users webhooks 

workers analytics; do
agents resource add git-checkout "local/pkg-${pkg}-repo" 

--path "/repos/monorepo/packages/${pkg}" --branch main
agents project create -d "Package: ${pkg}" 

--resource "local/pkg-${pkg}-repo" 

"local/pkg-${pkg}"
agents validation add --config "validations/pkg-${pkg}.yaml" --required "local/pkg-${pkg}-test"
agents validation attach --project "local/pkg-${pkg}" "local/pkg-${pkg}-test"
done

# Loop output — first 2 iterations shown, remaining 13 condensed # --- auth --- $ agents resource add git-checkout local/pkg-auth-repo --path /repos/monorepo/packages/auth --branch main ╭─ Resource ──────────────────────────────────────────╮ │ Name: local/pkg-auth-repo │ │ ID: 01HXR7B1A2B3C4D5E6F7G8H9J0 │ │ Type: git-checkout │ │ Physical/Virtual: physical │ │ Path: /repos/monorepo/packages/auth │ │ Branch: main │ │ Created: 2026-02-11 14:01 │ ╰─────────────────────────────────────────────────────╯ ╭─ Auto-discovered Children ─────────────────────────────────────────╮ │ ID Type Status │ │ ─────────────── ────────────── ───────────────── │ │ 01HXR7B1A2B3… git created │ │ 01HXR7B1A2B4… git-remote created │ │ 01HXR7B1A2B5… git-branch created │ │ + 22 git-commit resources │ │ + 134 git-tree-entry resources │ │ + 2 fs-directory + 11 fs-file │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Capabilities ─────────────────╮ │ Readable: yes │ │ Writable: yes │ │ Sandboxable: yes │ │ Checkpointable: yes │ │ Sandbox Strategy: git_worktree │ ╰────────────────────────────────╯ ✓ OK Resource registered (172 child resources discovered) $ agents project create -d "Package: auth" --resource local/pkg-auth-repo local/pkg-auth ╭─ Project Created ──────────────────────────────╮ │ Name: local/pkg-auth │ │ Description: Package: auth │ │ Type: local │ │ Created: 2026-02-11 14:01 │ ╰────────────────────────────────────────────────╯ ╭─ Linked Resources ───────────────────────────────────────╮ │ Resource Type Read-Only │ │ ───────────────── ────────────── ───────── │ │ local/pkg-auth-repo git-checkout no │ ╰──────────────────────────────────────────────────────────╯ ╭─ Defaults ──────────────────────────────╮ │ Sandbox: git_worktree │ │ Validations: 0 │ │ Context Filters: none │ │ Automation Profile: (inherits global) │ ╰─────────────────────────────────────────╯ ✓ OK Project created $ agents validation add --config validations/pkg-auth.yaml --required local/pkg-auth-test ╭─ Validation Registered ─────────────────────────────────────────────────╮ │ Name: local/pkg-auth-test │ │ Command: cd /repos/monorepo/packages/auth && pytest tests/ │ │ Mode: required │ │ Timeout: 300s │ ╰─────────────────────────────────────────────────────────────────────────╯ ✓ OK Validation registered $ agents validation attach --project local/pkg-auth local/pkg-auth-test ✓ OK Validation attached to project local/pkg-auth # --- billing --- $ agents resource add git-checkout local/pkg-billing-repo --path /repos/monorepo/packages/billing --branch main ✓ OK Resource registered — Name: local/pkg-billing-repo (189 children) $ agents project create -d "Package: billing" --resource local/pkg-billing-repo local/pkg-billing ✓ OK Project created — Name: local/pkg-billing $ agents validation add --config validations/pkg-billing.yaml --required local/pkg-billing-test ✓ OK Validation registered — Name: local/pkg-billing-test $ agents validation attach --project local/pkg-billing local/pkg-billing-test ✓ OK Validation attached to project local/pkg-billing

# ... (common, gateway, inventory, notifications, orders, payments, # reporting, search, shipping, users, webhooks, workers, analytics) # Each iteration: resource add → project create → validation add → validation attach # All 15 packages registered.


# Run formatting across all packages.
# full-auto: Strategize, Execute, AND Apply all run without human intervention.
# Capture plan IDs so we can check results afterward.
PLAN_IDS=()
for pkg in auth billing common gateway inventory notifications 

orders payments reporting search shipping users webhooks 

workers analytics; do
PID=$(agents --format json plan use 

--automation-profile full-auto 

local/format-codebase "local/pkg-${pkg}" 

| jq -r '.data.plan_id')
PLAN_IDS+=("$PID")
done

# Plan creation output — first 2 shown, remaining condensed # --- auth --- $ agents plan use --automation-profile full-auto local/format-codebase local/pkg-auth ╭─ Plan Created ───────────────────────────────────╮ │ Plan ID: 01HXR7D1A2B3C4D5E6F7G8H9J0 │ │ Phase: strategize (running) │ │ Action: local/format-codebase │ │ Project: local/pkg-auth │ │ Automation: full-auto │ │ Attempt: 1 │ ╰──────────────────────────────────────────────────╯ ╭─ Invariants ─────────────────────────────────────────────────────────────╮ │ Scope Source Invariant │ │ ────── ────── ───────────────────────────────────────────────────── │ │ plan action Only whitespace and import ordering changes — no se… │ │ plan action Every package must pass its own test suite after fo… │ ╰──────────────────────────────────────────────────────────────────────────╯ ✓ OK Plan created — full-auto: strategize → execute → apply will proceed automatically # --- billing --- $ agents plan use --automation-profile full-auto local/format-codebase local/pkg-billing ╭─ Plan Created ───────────────────────────────────╮ │ Plan ID: 01HXR7D2B3C4D5E6F7G8H9J0K1 │ │ Phase: strategize (running) │ │ Action: local/format-codebase │ │ Project: local/pkg-billing │ │ Automation: full-auto │ │ Attempt: 1 │ ╰──────────────────────────────────────────────────╯ ✓ OK Plan created — full-auto: strategize → execute → apply will proceed automatically

# ... (common, gateway, inventory, notifications, orders, payments, # reporting, search, shipping, users, webhooks, workers, analytics) # 15 plans launched — all running full-auto in background.

# Wait for all plans to finish, then check results $ agents plan list --state applied ╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────────────╮ │ ID Phase State Action Project Elapsed │ │ ──────── ─────── ──────── ───────────────────── ───────────────────── ───────── │ │ 01HXR7D1 apply applied local/format-codebase local/pkg-auth 00:02:14 │ │ 01HXR7D2 apply applied local/format-codebase local/pkg-billing 00:02:31 │ │ 01HXR7D3 apply applied local/format-codebase local/pkg-common 00:01:47 │ │ 01HXR7D4 apply applied local/format-codebase local/pkg-gateway 00:02:08 │ │ 01HXR7D5 apply applied local/format-codebase local/pkg-inventory 00:01:55 │ │ 01HXR7D6 apply applied local/format-codebase local/pkg-notifications 00:02:42 │ │ 01HXR7D7 apply applied local/format-codebase local/pkg-orders 00:02:19 │ │ 01HXR7D8 apply applied local/format-codebase local/pkg-payments 00:01:58 │ │ 01HXR7D9 apply applied local/format-codebase local/pkg-reporting 00:02:36 │ │ 01HXR7DA apply applied local/format-codebase local/pkg-search 00:01:41 │ │ 01HXR7DB apply applied local/format-codebase local/pkg-shipping 00:02:22 │ │ 01HXR7DC apply applied local/format-codebase local/pkg-users 00:01:49 │ │ 01HXR7DD apply applied local/format-codebase local/pkg-webhooks 00:02:05 │ │ 01HXR7DE apply applied local/format-codebase local/pkg-analytics 00:02:11 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Filters ───────────────────╮ │ Phase: (any) │ │ State: applied │ │ Project: (any) │ │ Action: (any) │ ╰─────────────────────────────╯ ╭─ Summary ─────────────╮ │ Total: 14 │ │ Processing: 0 │ │ Completed: 14 │ │ Errored: 0 │ ╰───────────────────────╯ ✓ OK 14 plans listed $ agents plan list --state failed ╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────────────╮ │ ID Phase State Action Project Elapsed │ │ ──────── ─────── ─────── ───────────────────── ─────────────────── ───────── │ │ 01HXR7DF execute errored local/format-codebase local/pkg-workers 00:03:07 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Filters ───────────────────╮ │ Phase: (any) │ │ State: failed │ │ Project: (any) │ │ Action: (any) │ ╰─────────────────────────────╯ ╭─ Summary ─────────────╮ │ Total: 1 │ │ Processing: 0 │ │ Completed: 0 │ │ Errored: 1 │ ╰───────────────────────╯

✓ OK 1 plan listed

Example 11: Complex Graph Actor for Multi-Stage Code Review

Scenario: A team builds a custom multi-stage code review actor that performs security analysis, performance analysis, and style checking in a graph topology — with each stage running a different specialized sub-actor.

Complexity: Expert. Custom actor graph, multiple sub-actors, advanced actor configuration.

Step 1: Define Specialized Sub-Actors

Create actors/review-pipeline.yaml:

name: local/review-pipeline cleveragents: version: "3.0" template_engine: JINJA2 default_actor: orchestrator global_context: review_standards: "Google Python Style Guide" severity_levels: "critical, high, medium, low, info" actors: orchestrator: type: llm config: actor: anthropic/claude-3.5-sonnet temperature: 0.1 system_prompt: | You are a code review orchestrator. You coordinate specialized reviewers and synthesize their findings into a unified review report. Standards: {{ context.review_standards }} Severity levels: {{ context.severity_levels }} memory_enabled: true security_reviewer: type: llm config: actor: anthropic/claude-3.5-sonnet temperature: 0.0 system_prompt: | You are a security-focused code reviewer. Analyze code for: - Injection vulnerabilities (SQL, command, XSS) - Authentication and authorization flaws - Sensitive data exposure - Insecure cryptographic practices - Dependency vulnerabilities Report findings with severity levels: {{ context.severity_levels }} performance_reviewer: type: llm config: actor: anthropic/claude-3.5-sonnet temperature: 0.0 system_prompt: | You are a performance-focused code reviewer. Analyze code for: - N+1 query patterns - Unbounded loops or recursion - Memory leaks and excessive allocation - Missing caching opportunities - Blocking operations in async contexts Report findings with severity levels: {{ context.severity_levels }} style_reviewer: type: llm config: actor: anthropic/claude-3.5-sonnet temperature: 0.0 system_prompt: | You are a code style and maintainability reviewer. Standards: {{ context.review_standards }} Analyze code for: - Naming conventions - Function/class design - Documentation completeness - Test coverage patterns - Code duplication

routes: review_graph: type: graph entry_point: dispatch checkpointing: true nodes: dispatch: type: agent agent: orchestrator security: type: agent agent: security_reviewer performance: type: agent agent: performance_reviewer style: type: agent agent: style_reviewer synthesize: type: agent agent: orchestrator edges: - from: dispatch to: security - from: dispatch to: performance - from: dispatch to: style - from: security to: synthesize - from: performance to: synthesize - from: style to: synthesize parallel_execution: true

$ agents actor add --config ./actors/review-pipeline.yaml \ --skill local/code-analysis \ --skill local/file-ops ╭─ Actor Added ──────────────────────────────────╮ │ Name: local/review-pipeline │ │ Provider: anthropic │ │ Model: claude-3.5-sonnet │ │ Default: yes │ │ Unsafe: no │ │ Type: graph │ ╰────────────────────────────────────────────────╯ ╭─ Config ─────────────────────────────────────────────╮ │ Path: ./actors/review-pipeline.yaml │ │ Hash: 4f7a1e3 │ │ Options: 6 │ │ Nodes: 5 │ │ Edges: 6 │ ╰──────────────────────────────────────────────────────╯ ╭─ Graph ────────────────────────────────────────────────────╮ │ Route: review_graph │ │ Entry Point: dispatch │ │ Checkpointing: yes │ │ Parallel Execution: yes │ │ │ │ Node Type Agent │ │ ─────────── ───── ────────────────────────────── │ │ dispatch agent orchestrator │ │ security agent security_reviewer │ │ performance agent performance_reviewer │ │ style agent style_reviewer │ │ synthesize agent orchestrator │ │ │ │ From To │ │ ─────────── ─────────── │ │ dispatch security │ │ dispatch performance │ │ dispatch style │ │ security synthesize │ │ performance synthesize │ │ style synthesize │ ╰────────────────────────────────────────────────────────────╯ ╭─ Capabilities ──────────────────────╮ │ - multi-stage code review │ │ - security analysis │ │ - performance analysis │ │ - style and maintainability checks │ │ - unified report synthesis │ ╰─────────────────────────────────────╯ ╭─ Skills ──────────────────────────────────────────╮ │ Skill Status │ │ ─────────────────── ──────────────────────── │ │ local/code-analysis attached │ │ local/file-ops attached │ ╰───────────────────────────────────────────────────╯

✓ OK Actor added

Step 2: Create the Review Action Using the Graph Actor

Create actions/deep-review.yaml:


name: local/deep-review
description: "Multi-stage deep code review with specialized reviewers"
definition_of_done: |
  - Security analysis complete with all findings classified by severity
  - Performance analysis complete with all findings classified by severity
  - Style analysis complete with all findings classified by severity
  - Unified review report generated with prioritized action items
  - Critical and high-severity issues have suggested fixes
strategy_actor: local/review-pipeline
execution_actor: local/review-pipeline
read_only: true
reusable: true
state: available
args:
  - name: target_paths
    type: string
    required: true
    description: "Comma-separated file or directory paths to review"
  - name: review_depth
    type: string
    required: false
    default: "standard"
    description: "Review depth: quick, standard, thorough"

$ agents action create --config ./actions/deep-review.yaml ╭─ Action Created ─────────────────────────────────────────────╮ │ Name: local/deep-review │ │ State: available │ │ Strategy Actor: local/review-pipeline │ │ Execution Actor: local/review-pipeline │ │ Reusable: yes │ │ Read Only: yes │ │ Created: 2026-02-11 16:30 │ ╰──────────────────────────────────────────────────────────────╯ ╭─ Definition of Done ──────────────────────────────────────────────────────╮ │ - Security analysis complete with all findings classified by severity │ │ - Performance analysis complete with all findings classified by severity │ │ - Style analysis complete with all findings classified by severity │ │ - Unified review report generated with prioritized action items │ │ - Critical and high-severity issues have suggested fixes │ ╰───────────────────────────────────────────────────────────────────────────╯ ╭─ Arguments ───────────────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ──────────── ────── ──────── ────────────────────────────────────────────── │ │ target_paths string yes Comma-separated file or directory paths to review │ │ review_depth string no Review depth: quick, standard, thorough │ ╰───────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: supervised │ │ Source: default │ ╰───────────────────────────────────────╯ ╭─ Usage ────────────────────────────────────────────────────────────────────────╮ │ agents plan use local/deep-review local/<project> │ │ --arg target_paths="src/auth/,src/routes/" │ │ --arg review_depth="thorough" (optional, default: "standard") │ ╰────────────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

$ agents plan use \ --automation-profile trusted \ --arg target_paths="src/auth/,src/routes/" \ --arg review_depth="thorough" \ local/deep-review local/api-service ╭─ Plan Created ───────────────────────────────────────╮ │ Plan: 01HXR8D2E3F4G5H6J7K8L9M0N1 │ │ Phase: strategize │ │ State: processing │ │ Action: local/deep-review │ │ Project: local/api-service │ │ Automation: trusted │ │ Attempt: 1 │ ╰──────────────────────────────────────────────────────╯ ╭─ Inputs ───────────────────────────────────────╮ │ - target_paths="src/auth/,src/routes/" │ │ - review_depth="thorough" │ │ - automation_profile=trusted │ ╰────────────────────────────────────────────────╯ ╭─ Actors ────────────────────────────────────────╮ │ Strategy: local/review-pipeline │ │ Execution: local/review-pipeline │ │ Estimation: (none) │ │ Actor Type: graph (5 nodes, 6 edges) │ ╰─────────────────────────────────────────────────╯ ╭─ Automation ───────────────────────────╮ │ Profile: trusted │ │ Source: plan override │ │ Read-Only: yes │ ╰────────────────────────────────────────╯ ╭─ Context ──────────────────────────╮ │ Resources: 1 (git-checkout) │ │ Indexed Files: 312 │ │ View: strategize │ │ Hot Token Budget: 24,000 │ ╰────────────────────────────────────╯ ╭─ Next Steps ─────────────────────────────────────────────────────────╮ │ Trusted profile — strategize and execute will proceed automatically. │ │ - agents plan status 01HXR8D2E3F4G5H6J7K8L9M0N1 │ │ - agents plan tree 01HXR8D2E3F4G5H6J7K8L9M0N1 │ ╰──────────────────────────────────────────────────────────────────────╯

✓ OK Plan created

The graph actor executes review_graph with parallel fan-out. The dispatch node (orchestrator) analyzes the target paths and prepares review context, then three edges fire concurrently: security, performance, and style nodes each run their specialized sub-actor in parallel. Once all three complete, their outputs converge at the synthesize node, where the orchestrator merges findings into a single prioritized report. Because read_only: true, no file modifications are produced — only the review report.

Example 12: Large-Scale Feature Implementation with Hierarchical Decomposition

Scenario: A startup is building a new notification system that spans the backend API, a message queue, a worker service, and a frontend dashboard. The feature requires changes across 4 projects and should decompose into manageable child plans.

Complexity: Expert. Multi-project, hierarchical child plans, deep decision tree, invariant reconciliation, full plan lifecycle.

Step 1: Set Up All Projects

# Register the API repo resource (full output shown) $ agents resource add git-checkout local/api-repo --path /repos/api --branch main ╭─ Resource ──────────────────────────────────────╮ │ Name: local/api-repo │ │ ID: 01HXRA1A2B3C4D5E6F7G8H9J0K │ │ Type: git-checkout │ │ Physical/Virtual: physical │ │ Path: /repos/api │ │ Branch: main │ │ Created: 2026-02-11 14:00 │ ╰─────────────────────────────────────────────────╯ ╭─ Auto-discovered Children ─────────────────────────────────────────╮ │ ID Type Status │ │ ─────────────── ────────────── ───────────────── │ │ 01HXRA1A2B3C… git created │ │ 01HXRA1A2B3D… git-remote created │ │ 01HXRA1A2B3E… git-branch created │ │ + 48 git-commit resources │ │ + 312 git-tree-entry resources │ │ + 6 fs-directory + 42 fs-file │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Capabilities ─────────────────╮ │ Readable: yes │ │ Writable: yes │ │ Sandboxable: yes │ │ Checkpointable: yes │ │ Sandbox Strategy: git_worktree │ ╰────────────────────────────────╯ ✓ OK Resource registered (412 child resources discovered) # Register the remaining 3 resources (condensed output) $ agents resource add git-checkout local/worker-repo --path /repos/worker --branch main ✓ OK Resource registered — Name: local/worker-repo (278 children) $ agents resource add git-checkout local/frontend-repo --path /repos/frontend --branch main ✓ OK Resource registered — Name: local/frontend-repo (524 children)

$ agents resource add git-checkout local/protos-repo --path /repos/protos --branch main ✓ OK Resource registered — Name: local/protos-repo (96 children)

# Create the Backend API project (full output shown) $ agents project create -d "Backend API" --resource local/api-repo --resource local/protos-repo --invariant "All new endpoints must have OpenAPI docs" --invariant "All database changes require migration scripts" local/api ╭─ Project Created ─────────────────────────╮ │ Name: local/api │ │ Description: Backend API │ │ Type: local │ │ Created: 2026-02-11 14:01 │ ╰───────────────────────────────────────────╯ ╭─ Linked Resources ───────────────────────────────────────╮ │ Resource Type Read-Only │ │ ───────────────── ────────────── ───────── │ │ local/api-repo git-checkout no │ │ local/protos-repo git-checkout no │ ╰──────────────────────────────────────────────────────────╯ ╭─ Invariants ─────────────────────────────────────────────╮ │ 1. All new endpoints must have OpenAPI docs │ │ 2. All database changes require migration scripts │ ╰──────────────────────────────────────────────────────────╯ ╭─ Defaults ──────────────────────────────╮ │ Sandbox: git_worktree │ │ Validations: 0 │ │ Context Filters: none │ │ Automation Profile: (inherits global) │ ╰─────────────────────────────────────────╯ ✓ OK Project created # Create the remaining 3 projects (condensed output) $ agents project create -d "Background worker service" --resource local/worker-repo --resource local/protos-repo --invariant "Workers must be idempotent" --invariant "All queue consumers must implement dead-letter handling" local/worker ✓ OK Project created — Name: local/worker $ agents project create -d "Frontend dashboard" --resource local/frontend-repo --invariant "All components must have Storybook stories" --invariant "Accessibility: WCAG 2.1 AA compliance required" local/frontend ✓ OK Project created — Name: local/frontend

$ agents project create -d "Shared protobuf definitions" --resource local/protos-repo --invariant "Proto changes must be backward-compatible (no field renumbering)" local/protos ✓ OK Project created — Name: local/protos

# Register validations — first one with full output $ agents validation add --config validations/api-tests.yaml --required local/api-tests ╭─ Validation Registered ─────────────────────────────╮ │ Name: local/api-tests │ │ Command: pytest tests/ && mypy src/ │ │ Mode: required │ │ Timeout: 300s │ ╰─────────────────────────────────────────────────────╯ ✓ OK Validation registered $ agents validation add --config validations/worker-tests.yaml --required local/worker-tests ✓ OK Validation registered — Name: local/worker-tests $ agents validation add --config validations/frontend-tests.yaml --required local/frontend-tests ✓ OK Validation registered — Name: local/frontend-tests $ agents validation add --config validations/proto-lint.yaml --required local/proto-lint ✓ OK Validation registered — Name: local/proto-lint # Attach validations to their respective projects $ agents validation attach --project local/api local/api-tests ✓ OK Validation attached to project local/api $ agents validation attach --project local/worker local/worker-tests ✓ OK Validation attached to project local/worker $ agents validation attach --project local/frontend local/frontend-tests ✓ OK Validation attached to project local/frontend

$ agents validation attach --project local/protos local/proto-lint ✓ OK Validation attached to project local/protos

# Global invariant for this effort $ agents invariant add --global "All inter-service communication must use the shared proto definitions" ╭─ Invariant Added ──────────────────────────────────────────────────────────────╮ │ Invariant: All inter-service communication must use the shared proto defs. │ │ Scope: global │ │ ID: inv_01HXRI1A │ ╰────────────────────────────────────────────────────────────────────────────────╯

✓ OK Invariant added

Step 2: Create the Feature Action

Create actions/build-notification-system.yaml:


name: local/build-notification-system
description: "Build a complete notification system spanning multiple services"
long_description: |
  Implement a full notification system with:
  - Backend API: notification preferences, send endpoints, delivery tracking
  - Message Queue: notification event schemas, routing rules
  - Worker: email/SMS/push delivery workers with retry logic
  - Frontend: notification center UI, preference settings, real-time updates
The system must be designed for reliability (at-least-once delivery),
scalability (async processing via queue), and user control (per-channel
preferences with quiet hours).
definition_of_done: |

Proto definitions for notification events are complete and compatible
API endpoints: CRUD for preferences, send notification, list history
Worker processes: email, SMS, push delivery with retry and dead-letter
Frontend: notification center, preference settings, real-time badge
Integration tests verify end-to-end notification flow
All per-project validations pass
API docs updated, Storybook stories added
strategy_actor: local/refactoring-strategist
execution_actor: anthropic/claude-3.5-sonnet
estimation_actor: anthropic/claude-3.5-sonnet
invariant_actor: local/invariant-resolver
automation_profile: cautious
reusable: false
state: available
args:
name: notification_channels
type: string
required: true
description: "Comma-separated: email, sms, push, in-app"
name: priority_levels
type: string
required: false
default: "critical,high,normal,low"
name: max_retry_attempts
type: integer
required: false
default: 5
invariants:
"Proto definitions must be implemented and reviewed before any service code"
"Each service must be deployable independently after its changes"
"Frontend must gracefully degrade if the notification API is unavailable"
"All notification delivery must be async — API endpoints return immediately"

$ agents action create --config ./actions/build-notification-system.yaml ╭─ Action Created ──────────────────────────────────────────────────╮ │ Name: local/build-notification-system │ │ ID: 01HXRB1A2B3C4D5E6F7G8H9J0 │ │ State: available │ │ Strategy Actor: local/refactoring-strategist │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Estimation Actor: anthropic/claude-3.5-sonnet │ │ Invariant Actor: local/invariant-resolver │ │ Reusable: no │ │ Read Only: no │ │ Created: 2026-02-11 14:02 │ ╰───────────────────────────────────────────────────────────────────╯ ╭─ Definition of Done ───────────────────────────────────────────────────╮ │ - Proto definitions for notification events are complete/compatible │ │ - API endpoints: CRUD for preferences, send notification, list hist. │ │ - Worker: email, SMS, push delivery with retry and dead-letter │ │ - Frontend: notification center, preference settings, real-time badge │ │ - Integration tests verify end-to-end notification flow │ │ - All per-project validations pass │ │ - API docs updated, Storybook stories added │ ╰────────────────────────────────────────────────────────────────────────╯ ╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ────────────────────── ──────── ──────── ────────────────────────────────── │ │ notification_channels string yes Comma-separated: email, sms, push │ │ priority_levels string no (default: critical,high,normal,low) │ │ max_retry_attempts integer no (default: 5) │ ╰──────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────╮ │ Profile: cautious │ │ Source: action config │ ╰───────────────────────────────────────╯ ╭─ Action Invariants ───────────────────────────────────────────────────────────────────╮ │ 1. Proto definitions must be implemented and reviewed before any service code │ │ 2. Each service must be deployable independently after its changes │ │ 3. Frontend must gracefully degrade if the notification API is unavailable │ │ 4. All notification delivery must be async — API endpoints return immediately │ ╰───────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Usage ────────────────────────────────────────────────────────────────────────────╮ │ agents plan use local/build-notification-system local/protos │ │ --arg notification_channels="email,push,in-app" │ ╰────────────────────────────────────────────────────────────────────────────────────╯

✓ OK Action created

Step 3: Initiate the Plan

$ agents plan use \ --arg notification_channels="email,push,in-app" \ --arg priority_levels="critical,high,normal,low" \ --arg max_retry_attempts=5 \ local/build-notification-system \ local/protos local/api local/worker local/frontend ╭─ Plan Created ────────────────────────────────────────────────╮ │ Plan: 01HXRF1A2B3C4D5E6F7G8H9J0 │ │ Action: local/build-notification-system │ │ Projects: local/protos, local/api, │ │ local/worker, local/frontend │ │ Automation: cautious │ │ Attempt: 1 │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Inputs ───────────────────────────────────────────────────────────╮ │ - notification_channels="email,push,in-app" │ │ - priority_levels="critical,high,normal,low" │ │ - max_retry_attempts=5 │ │ - automation_profile=cautious │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Actors ────────────────────────────────────────────╮ │ Strategy: local/refactoring-strategist │ │ Execution: anthropic/claude-3.5-sonnet │ │ Estimation: anthropic/claude-3.5-sonnet │ │ Invariant: local/invariant-resolver │ ╰─────────────────────────────────────────────────────╯ ╭─ Automation ──────────────────────────────╮ │ Profile: cautious │ │ Source: action config │ │ Read-Only: no │ ╰───────────────────────────────────────────╯ ╭─ Context ──────────────────────────╮ │ Resources: 4 (git-checkout) │ │ Indexed Files: 1,310 │ │ View: strategize │ │ Hot Token Budget: 32,000 │ ╰────────────────────────────────────╯ ╭─ Next Steps ──────────────────────────────────────────────╮ │ - agents plan tree 01HXRF1A2B3C4D5E6F7G8H9J0 │ │ - agents plan status 01HXRF1A2B3C4D5E6F7G8H9J0 │ │ - agents plan execute 01HXRF1A2B3C4D5E6F7G8H9J0 │ ╰───────────────────────────────────────────────────────────╯

✓ OK Plan created

The plan (01HXRF1A2B3C4D5E6F7G8H9J0) enters Strategize. The strategy actor:

Reconciles invariants from all four projects plus global plus action-level
Decomposes the work into ordered child plans:
- Phase 1: Proto definitions (local/protos)
- Phase 2 (parallel): API endpoints (local/api) + Worker skeleton (local/worker)
- Phase 3 (parallel): Worker delivery logic (local/worker) + Frontend notification center (local/frontend)
- Phase 4: Integration wiring and end-to-end tests

Because the cautious profile uses confidence thresholds, the system pauses on complex architectural decisions (e.g., "Should notifications use a fan-out or point-to-point queue topology?") but proceeds automatically on routine decisions.

Step 4: Monitor and Guide the Hierarchical Execution

# View the full plan tree with child plans $ agents plan tree 01HXRF1A2B3C4D5E6F7G8H9J0 ╭─ Decision Tree ─────────────────────────────────────────────────────────────────────────────────────────╮ │ Plan: 01HXRF1A2B3C4D5E6F7G8H9J0 │ │ ├─ [prompt_definition] "Build notification system across 4 projects" │ │ ├─ [invariant_enforced] "All inter-service communication must use shared proto defs" │ │ ├─ [invariant_enforced] "Proto definitions must be implemented before any service code" │ │ ├─ [invariant_enforced] "Each service must be deployable independently after its changes" │ │ ├─ [invariant_enforced] "Frontend must gracefully degrade if notification API unavailable" │ │ ├─ [invariant_enforced] "All notification delivery must be async" │ │ ├─ [strategy_choice] "Phase 1: proto definitions first (blocking)" (conf: 0.95) │ │ ├─ [strategy_choice] "Phase 2: API + worker skeleton in parallel" (conf: 0.88) │ │ ├─ [strategy_choice] "Phase 3: worker delivery + frontend UI in parallel" (conf: 0.84) │ │ ├─ [strategy_choice] "Phase 4: integration wiring and e2e tests" (conf: 0.90) │ │ ├─ [strategy_choice] "Queue topology: fan-out vs point-to-point?" (conf: 0.55 — PAUSED) │ │ ├─ [child_plan] 01HXRC1A2B3C4D5E6F7G8H9J0 (Phase 1: proto defs) [execute/complete] │ │ ├─ [child_plan] 01HXRC2B3C4D5E6F7G8H9J0K1 (Phase 2a: API endpoints) [execute/processing] │ │ ├─ [child_plan] 01HXRC3C4D5E6F7G8H9J0K1L2 (Phase 2b: worker skeleton) [execute/processing] │ │ ├─ [child_plan] 01HXRC4D5E6F7G8H9J0K1L2M3 (Phase 3a: worker delivery) [strategize/pending] │ │ ├─ [child_plan] 01HXRC5E6F7G8H9J0K1L2M3N4 (Phase 3b: frontend UI) [strategize/pending] │ │ └─ [child_plan] 01HXRC6F7G8H9J0K1L2M3N4P5 (Phase 4: integration) [strategize/pending] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Tree Summary ──────────────────╮ │ Nodes: 17 │ │ Depth: 2 │ │ Child Plans: 6 (1 done, 2 exec) │ │ Invariants: 5 │ │ Superseded: 0 (hidden) │ ╰─────────────────────────────────╯ ╭─ Decision IDs (for correction) ──────────────────────────╮ │ Root: 01HXRD1A2B3C4D5E6F7G8H9J │ │ Invariant 1: 01HXRD1B3C4D5E6F7G8H9J0 │ │ Invariant 2: 01HXRD1C4D5E6F7G8H9J0K1 │ │ Invariant 3: 01HXRD1D5E6F7G8H9J0K1L2 │ │ Invariant 4: 01HXRD1E6F7G8H9J0K1L2M3 │ │ Invariant 5: 01HXRD1F7G8H9J0K1L2M3N4 │ │ Strategy 1: 01HXRD2A3B4C5D6E7F8G9H0 │ │ Strategy 2: 01HXRD2B4C5D6E7F8G9H0J1 │ │ Strategy 3: 01HXRD2C5D6E7F8G9H0J1K2 │ │ Strategy 4: 01HXRD2D6E7F8G9H0J1K2L3 │ │ Paused: 01HXRD2E7F8G9H0J1K2L3M4 │ ╰──────────────────────────────────────────────────────────╯

✓ OK Decision tree rendered

# The system paused at a decision about queue topology (confidence 0.55 < threshold 0.7) $ agents plan explain 01HXRD2E7F8G9H0J1K2L3M4 ╭─ Decision ──────────────────────────────────────────────────╮ │ ID: 01HXRD2E7F8G9H0J1K2L3M4 │ │ Type: strategy_choice │ │ Question: Queue topology for notification delivery │ │ Chosen: (none — paused for user input) │ │ Confidence: 0.55 │ │ Plan: 01HXRF1A2B3C4D5E6F7G8H9J0 │ │ Sequence: 5 of 5 strategy choices │ │ Created: 2026-02-11 14:04 │ ╰─────────────────────────────────────────────────────────────╯ ╭─ Alternatives Considered ──────────────────────────────────────────────────────╮ │ 1. Fan-out exchange: one exchange per event type, separate queues per channel │ │ 2. Point-to-point: single queue, worker routes by notification type │ │ 3. Topic-based: single exchange with routing keys for channel + priority │ ╰────────────────────────────────────────────────────────────────────────────────╯ ╭─ Impact ─────────────────────────╮ │ Downstream Decisions: 4 │ │ Downstream Child Plans: 3 │ │ Artifacts Produced: 0 (pending) │ │ Correction Impact: high │ ╰──────────────────────────────────╯ ╭─ Rationale ──────────────────────────────────────────────────────────╮ │ The confidence is low because both fan-out and topic-based patterns │ │ are viable. Fan-out gives independent scaling per channel but adds │ │ more exchanges. Topic-based is simpler but couples routing logic. │ │ The existing codebase uses RabbitMQ but has no precedent for this │ │ pattern — no strong signal either way. │ ╰──────────────────────────────────────────────────────────────────────╯ ╭─ Correction ──────────────────────────────────────────────────╮ │ agents plan correct 01HXRD2E7F8G9H0J1K2L3M4 │ │ --mode revert --guidance "Use fan-out exchange pattern..." │ ╰───────────────────────────────────────────────────────────────╯

✓ OK Decision explained

# Provide guidance to resolve the paused decision $ agents plan prompt 01HXRF1A2B3C4D5E6F7G8H9J0 "Use a fan-out exchange pattern: one exchange per notification event type, with separate queues per delivery channel. This matches our existing RabbitMQ setup in the order service." ╭─ Guidance Added ────────────────────────────────────────────────────────╮ │ Plan: 01HXRF1A2B3C4D5E6F7G8H9J0 │ │ Guidance: Use a fan-out exchange pattern: one exchange per │ │ notification event type, with separate queues per delivery │ │ channel. This matches our existing RabbitMQ setup. │ │ Scope: next execution step │ │ Phase: strategize │ │ State: awaiting_input → processing │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Decision Created ────────────────────────╮ │ Type: user_intervention │ │ ID: 01HXRD3A2B3C4D5E6F7G8H9J │ │ Parent: 01HXRD2E7F8G9H0J1K2L3M4 │ ╰───────────────────────────────────────────╯ ╭─ Queue ────╮ │ Pending: 1 │ │ Applied: 0 │ ╰────────────╯

✓ OK Guidance queued

Step 5: Handle a Failure in One Child Plan

The worker delivery child plan fails validation because the SMS provider SDK is not installed. Rather than failing the entire tree:

# Check which child plan failed $ agents plan status 01HXRC4D5E6F7G8H9J0K1L2M3 ╭─ Plan Status ──────────────────────────────────────────────╮ │ Plan: 01HXRC4D5E6F7G8H9J0K1L2M3 │ │ Phase: execute │ │ State: errored │ │ Action: local/build-notification-system (child plan) │ │ Project: local/worker │ │ Automation: cautious │ │ Attempt: 1 │ │ Parent: 01HXRF1A2B3C4D5E6F7G8H9J0 │ ╰────────────────────────────────────────────────────────────╯ ╭─ Progress ───────────╮ │ ✓ Strategize │ │ ✗ Execute │ │ ○ Apply (skipped) │ ╰──────────────────────╯ ╭─ Error Detail ──────────────────────────────────────────────────────────╮ │ Error: Validation failed: ModuleNotFoundError: No module named │ │ 'twilio' — SMS provider SDK not installed │ │ Tool: execute_command (pip install check) │ │ Step: 3 of 8 │ │ Checkpoint: cp_01HXRC4D (sandbox state preserved) │ │ Recoverable: yes — use "agents plan prompt" to provide guidance │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Cost ───────────────╮ │ Tokens Used: 14,280 │ │ Cost So Far: $0.048 │ ╰──────────────────────╯

✗ ERROR Plan errored — use agents plan prompt to resume or agents plan cancel to abort

# Correct the strategy — tell it to skip SMS for now $ agents plan correct 01HXRD4A2B3C4D5E6F7G8H9J --mode append --guidance "Skip SMS delivery for the initial implementation. Add a placeholder worker that logs a warning. SMS support will be added in a follow-up action." ╭─ Correction ─────────────────────────────────────────────────╮ │ Mode: append │ │ Impact: adds to existing subtree, no rollback │ │ New Decision: 01HXRD5A2B3C4D5E6F7G8H9J │ │ Appended After: 01HXRD4A2B3C4D5E6F7G8H9J │ │ Attempt: 2 │ ╰──────────────────────────────────────────────────────────────╯ ╭─ Append Detail ────────────────────────────────────────────────────╮ │ Original decision preserved: yes │ │ Existing artifacts kept: yes │ │ Additional work: re-execute with SMS placeholder │ │ The worker delivery plan will be re-executed. Email and push │ │ workers are kept; SMS worker replaced with a logging stub. │ │ Other child plans (API, frontend, integration) are unaffected. │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Queued ──────────────╮ │ Re-execute: 1 child │ │ ETA: 3m │ ╰───────────────────────╯

✓ OK Append correction queued

Step 6: Apply in Phases

# Apply proto definitions first (other plans depend on this) $ agents plan apply --yes 01HXRC1A2B3C4D5E6F7G8H9J0 ╭─ Apply Summary ──────────────────────────────────────────╮ │ Plan: 01HXRC1A2B3C4D5E6F7G8H9J0 │ │ Artifacts: 3 files updated │ │ Changes: 84 insertions, 0 deletions │ │ Project: local/protos │ │ Applied At: 2026-02-11 14:18 │ ╰──────────────────────────────────────────────────────────╯ ╭─ Validation ──────────────────────────────────────────╮ │ buf lint: passed │ │ buf breaking: passed (no breaking changes) │ │ Duration: 2.1s │ ╰───────────────────────────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ─────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:02:41 │ │ Total Cost: $0.024 │ │ Decisions Made: 4 │ │ Child Plans: 0 │ ╰──────────────────────────────────────────╯ ✓ OK Changes applied # Apply API and worker in parallel $ agents plan apply --yes 01HXRC2B3C4D5E6F7G8H9J0K1 ✓ OK Changes applied — Plan: 01HXRC2B...J0K1 Project: local/api (8 files, +246 -12) $ agents plan apply --yes 01HXRC3C4D5E6F7G8H9J0K1L2 ✓ OK Changes applied — Plan: 01HXRC3C...K1L2 Project: local/worker (5 files, +178 -4) # Apply worker delivery and frontend $ agents plan apply --yes 01HXRC4D5E6F7G8H9J0K1L2M3 ✓ OK Changes applied — Plan: 01HXRC4D...L2M3 Project: local/worker (6 files, +312 -18) $ agents plan apply --yes 01HXRC5E6F7G8H9J0K1L2M3N4 ✓ OK Changes applied — Plan: 01HXRC5E...M3N4 Project: local/frontend (12 files, +487 -22) # Apply integration tests $ agents plan apply --yes 01HXRC6F7G8H9J0K1L2M3N4P5 ✓ OK Changes applied — Plan: 01HXRC6F...N4P5 Projects: local/api, local/worker (4 files, +156 -0) # Apply the parent plan (finalizes everything) $ agents plan apply --yes 01HXRF1A2B3C4D5E6F7G8H9J0 ╭─ Apply Summary ───────────────────────────────────────────╮ │ Plan: 01HXRF1A2B3C4D5E6F7G8H9J0 │ │ Artifacts: 38 files across 4 projects │ │ Changes: 1,463 insertions, 56 deletions │ │ Projects: local/protos, local/api, │ │ local/worker, local/frontend │ │ Applied At: 2026-02-11 14:32 │ ╰───────────────────────────────────────────────────────────╯ ╭─ Validation ─────────────────────────────────────────╮ │ local/protos: passed (buf lint + breaking) │ │ local/api: passed (pytest 48/48, mypy 0 err) │ │ local/worker: passed (pytest 31/31, mypy 0) │ │ local/frontend: passed (tests + lint) │ │ Duration: 34.2s │ ╰──────────────────────────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktrees: 4 removed │ │ Branches: merged to main │ │ Checkpoints: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:30:14 │ │ Total Cost: $0.847 │ │ Decisions Made: 42 │ │ Child Plans: 6 (all completed) │ │ Corrections: 1 │ ╰─────────────────────────────────────────╯ ╭─ Next Steps ──────╮ │ - Review git diff │ │ - Commit changes │ ╰───────────────────╯

✓ OK Changes applied

Example 13: Custom Automation Profile with Semantic Escalation

Scenario: A team wants fine-grained automation control. They trust the system with routine planning but want human oversight on any decision involving database schema changes or security-sensitive code, regardless of confidence.

Complexity: Intermediate. Custom profile, invariant-driven escalation.

Step 1: Create a Custom Profile

Create profiles/db-cautious.yaml:

name: local/db-cautious description: "Auto for most tasks, manual for database and security decisions" decompose_task: 0.0 create_tool: 0.3 select_tool: 1.0 edit_code: 0.4 execute_command: 0.6 create_file: 0.5 delete_content: 0.8 access_network: 0.9 install_dependency: 0.3 modify_config: 0.0 approve_plan: 0.0

require_sandbox: true require_checkpoints: true allow_unsafe_tools: false

$ agents automation-profile add --config ./profiles/db-cautious.yaml ╭─ Profile Registered ──────────────────────────────────────────────────────╮ │ Name: local/db-cautious │ │ Description: Auto for most tasks, manual for database and security │ │ decisions │ │ Created: 2026-02-11 09:00 │ ╰───────────────────────────────────────────────────────────────────────────╯ ╭─ Confidence Thresholds ────────────────╮ │ decompose_task: 0.0 │ │ create_tool: 0.3 │ │ select_tool: 1.0 │ │ edit_code: 0.4 │ │ execute_command: 0.6 │ │ create_file: 0.5 │ │ delete_content: 0.8 │ │ install_dependency: 0.3 │ │ modify_config: 0.0 │ │ approve_plan: 0.0 │ │ require_sandbox: true │ │ require_checkpoints: true │ │ allow_unsafe_tools: false │ ╰────────────────────────────────────────╯

✓ OK Profile registered

Step 2: Apply to a Project with Database Resources

$ agents config set core.automation-profile local/db-cautious --project local/api-service ╭─ Config Updated ─────────────────────────────────╮ │ Key: core.automation-profile │ │ Value: local/db-cautious │ │ Previous: review │ │ Source: config │ │ Scope: project (local/api-service) │ ╰──────────────────────────────────────────────────╯ ╭─ Effective ────────────────────────────────────╮ │ Sessions: new sessions on local/api-service │ │ Plans: future plans (unless overridden) │ │ Existing: unchanged │ ╰────────────────────────────────────────────────╯ ╭─ Saved To ──────────────────────────╮ │ File: ~/.cleveragents/config.toml │ │ Line: 24 │ ╰─────────────────────────────────────╯

✓ OK Config updated

# Add invariants that force escalation on sensitive operations $ agents invariant add --project local/api-service \ "Any change to database migration files requires explicit human approval" ╭─ Invariant Added ───────────────────────────────────────────────────────────────╮ │ Project: local/api-service │ │ Invariant: Any change to database migration files requires explicit human │ │ approval │ │ Scope: project │ │ ID: inv_01HXRBA1A │ ╰─────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Invariant added $ agents invariant add --project local/api-service "Changes to authentication or authorization logic require security review" ╭─ Invariant Added ───────────────────────────────────────────────────────────────╮ │ Project: local/api-service │ │ Invariant: Changes to authentication or authorization logic require │ │ security review │ │ Scope: project │ │ ID: inv_01HXRBA2B │ ╰─────────────────────────────────────────────────────────────────────────────────╯

✓ OK Invariant added

Step 3: Run a Plan and Observe Escalation

$ agents plan use \ --arg target_module="src/auth" \ local/refactor-to-orm local/api-service ╭─ Plan Created ─────────────────────────────────────╮ │ Plan ID: 01HXRBG1H2I3J4K5L6M7N8O9P0 │ │ Phase: strategize (running) │ │ Action: local/refactor-to-orm │ │ Project: local/api-service │ │ Automation: local/db-cautious │ │ Attempt: 1 │ ╰────────────────────────────────────────────────────╯ ╭─ Inputs ─────────────────────╮ │ - target_module=src/auth │ ╰──────────────────────────────╯ ╭─ Actors ───────────────────────────────╮ │ Strategy: anthropic/claude-3.5-sonnet │ │ Execution: anthropic/claude-3.5-sonnet │ │ Invariant: local/invariant-resolver │ ╰────────────────────────────────────────╯ ╭─ Plan Invariants ──────────────────────────────────────────────────────────────╮ │ Scope Source Invariant │ │ ──────── ─────── ────────────────────────────────────────────────────── │ │ project config Any change to database migration files requires explicit │ │ human approval │ │ project config Changes to authentication or authorization logic require │ │ security review │ ╰────────────────────────────────────────────────────────────────────────────────╯ ╭─ Next Steps ─────────────────────────────────────────╮ │ - agents plan status 01HXRBG1H2I3J4K5L6M7N8O9P0 │ │ - agents plan tree 01HXRBG1H2I3J4K5L6M7N8O9P0 │ ╰──────────────────────────────────────────────────────╯

✓ OK Plan created — strategize in progress

During execution, the system encounters a decision to create a new Alembic migration. The confidence score is 0.82 (the system is fairly confident), but the invariant "database migration files require explicit human approval" causes the Invariant Reconciliation Actor to enforce escalation regardless. The system pauses:

# The plan pauses — check why $ agents plan status 01HXRBG1H2I3J4K5L6M7N8O9P0 ╭─ Plan Status ───────────────────────────────────────╮ │ Plan: 01HXRBG1H2I3J4K5L6M7N8O9P0 │ │ Phase: execute │ │ State: awaiting_input │ │ Action: local/refactor-to-orm │ │ Project: local/api-service │ │ Automation: local/db-cautious │ │ Attempt: 1 │ ╰─────────────────────────────────────────────────────╯ ╭─ Progress ────────────────╮ │ ✓ Strategize │ │ ⏸ Execute (paused) │ │ ○ Apply (waiting) │ ╰───────────────────────────╯ ╭─ Escalation ───────────────────────────────────────────────────────────────╮ │ ⚠ Decision paused — invariant forced escalation │ │ Decision: 01HXRBD1E2F3G4H5I6J7K8L9 │ │ Type: implementation_choice │ │ Question: Create Alembic migration for users table schema change? │ │ Confidence: 0.82 (would auto-proceed, but invariant overrides) │ │ Invariant: "Any change to database migration files requires explicit │ │ human approval" │ ╰────────────────────────────────────────────────────────────────────────────╯ ╭─ Timing ───────────╮ │ Started: 09:05:12 │ │ Elapsed: 00:02:48 │ │ ETA: (paused) │ ╰────────────────────╯ ╭─ Cost ───────────────╮ │ Tokens Used: 18,740 │ │ Cost So Far: $0.062 │ │ Estimated: $0.095 │ ╰──────────────────────╯

⚠ WARN Plan paused — awaiting human input for escalated decision

# Review the decision requiring approval $ agents plan explain 01HXRBD1E2F3G4H5I6J7K8L9 ╭─ Decision ───────────────────────────────────────────────────────────╮ │ ID: 01HXRBD1E2F3G4H5I6J7K8L9 │ │ Type: implementation_choice │ │ Question: Create Alembic migration for users table schema change? │ │ Chosen: Add nullable orm_version column with migration │ │ Confidence: 0.82 │ │ Plan: 01HXRBG1H2I3J4K5L6M7N8O9P0 │ │ Sequence: 4 of 7 │ │ Created: 2026-02-11 09:07 │ ╰──────────────────────────────────────────────────────────────────────╯ ╭─ Alternatives Considered ────────────────────────────────────────────╮ │ 1. Add nullable orm_version column with migration (chosen) │ │ 2. Use a shadow table approach (no schema change) │ │ 3. In-place column rename via ALTER (risky in production) │ ╰──────────────────────────────────────────────────────────────────────╯ ╭─ Escalation Reason ──────────────────────────────────────────────────╮ │ Invariant Override: inv_01HXRBA1A │ │ Text: "Any change to database migration files requires explicit │ │ human approval" │ │ Effect: Confidence 0.82 would normally auto-proceed (threshold │ │ 0.6), but invariant forces manual escalation regardless │ ╰──────────────────────────────────────────────────────────────────────╯ ╭─ Impact ─────────────────────────╮ │ Downstream Decisions: 3 │ │ Downstream Child Plans: 0 │ │ Artifacts Produced: 2 │ │ Correction Impact: medium │ ╰──────────────────────────────────╯ ╭─ Rationale ──────────────────────────────────────────────────────────╮ │ The auth module currently uses raw SQL queries. Refactoring to ORM │ │ requires an orm_version tracking column on the users table. │ │ Adding as nullable first avoids downtime; the backfill + NOT NULL │ │ constraint can follow in a second migration after data is populated. │ ╰──────────────────────────────────────────────────────────────────────╯ ╭─ Correction ────────────────────────────────────────────────╮ │ agents plan prompt 01HXRBG1H2I3J4K5L6M7N8O9P0 │ │ "Approved. <guidance>" │ │ agents plan correct 01HXRBD1E2F3G4H5I6J7K8L9 │ │ --mode revert --guidance "Use approach 2 instead..." │ ╰─────────────────────────────────────────────────────────────╯

✓ OK Decision explained

# Approve the migration approach with specific guidance $ agents plan prompt 01HXRBG1H2I3J4K5L6M7N8O9P0 \ "Approved. Use a two-phase migration: first add the column as nullable, \ then in a separate migration add the NOT NULL constraint after backfill." ╭─ Guidance Added ──────────────────────────────────────────────────────────╮ │ Plan: 01HXRBG1H2I3J4K5L6M7N8O9P0 │ │ Guidance: Approved. Use a two-phase migration: first add the column as │ │ nullable, then in a separate migration add the NOT NULL │ │ constraint after backfill. │ │ Scope: next execution step │ │ Phase: execute │ │ State: awaiting_input → processing │ ╰───────────────────────────────────────────────────────────────────────────╯ ╭─ Decision Created ──────────────────────────────╮ │ Type: user_intervention │ │ ID: 01HXRBE2F3G4H5I6J7K8L9M0 │ │ Parent: 01HXRBD1E2F3G4H5I6J7K8L9 │ ╰─────────────────────────────────────────────────╯ ╭─ Queue ────╮ │ Pending: 1 │ │ Applied: 0 │ ╰────────────╯

✓ OK Guidance queued — execution resuming

Example 14: Server Mode — Team Collaboration

Scenario: A distributed team uses CleverAgents in server mode. Multiple engineers share actions, actors, and projects while working on the same codebase from different machines.

Complexity: Intermediate. Server mode, multi-user, namespace management.

Step 1: Connect to the Server

# Configure server connection $ agents config set server.url https://agents.example.com ╭─ Config Updated ──────────────────────────────╮ │ Key: server.url │ │ Value: https://agents.example.com │ │ Previous: (not set) │ │ Source: config │ │ Scope: global │ ╰───────────────────────────────────────────────╯ ╭─ Saved To ──────────────────────────╮ │ File: ~/.cleveragents/config.toml │ │ Line: 3 │ ╰─────────────────────────────────────╯ ✓ OK Config updated $ agents config set server.token "tok_01HXR..." ╭─ Config Updated ──────────────────────────╮ │ Key: server.token │ │ Value: tok_01HXR... (redacted) │ │ Previous: (not set) │ │ Source: config │ │ Scope: global │ ╰───────────────────────────────────────────╯ ╭─ Saved To ──────────────────────────╮ │ File: ~/.cleveragents/config.toml │ │ Line: 4 │ ╰─────────────────────────────────────╯ ✓ OK Config updated $ agents config set core.namespace myteam ╭─ Config Updated ──────────────────────╮ │ Key: core.namespace │ │ Value: myteam │ │ Previous: local │ │ Source: config │ │ Scope: global │ ╰───────────────────────────────────────╯ ╭─ Saved To ──────────────────────────╮ │ File: ~/.cleveragents/config.toml │ │ Line: 5 │ ╰─────────────────────────────────────╯

✓ OK Config updated

# Verify connection $ agents diagnostics ╭─ Checks ────────────────────────────────────────────────╮ │ Check Status Details │ │ ─────────────── ────── ─────────────────────── │ │ Config file OK readable │ │ Database OK writable │ │ Anthropic key OK configured │ │ OPENAI_API_KEY WARN missing │ │ Disk space OK 4.8 GB free │ │ Text index OK tantivy 0.22 │ │ Vector index OK faiss (CPU) │ │ Graph store OK neo4j 5.15 │ │ File permissions OK data dir r/w │ │ Git OK git 2.43.0 │ │ Server OK connected (agents.example.com) │ │ Namespace OK myteam (4 members) │ ╰─────────────────────────────────────────────────────────╯ ╭─ Summary ─────────╮ │ Checks: 12 total │ │ Warnings: 1 │ │ Errors: 0 │ │ Duration: 0.8s │ ╰───────────────────╯ ╭─ Server ────────────────────────────╮ │ URL: https://agents.example.com │ │ Auth: valid (tok_01HXR...) │ │ Namespace: myteam │ │ Members: 4 │ │ Shared Actions: 7 │ │ Shared Actors: 3 │ │ Latency: 42ms │ ╰─────────────────────────────────────╯ ╭─ Recommendations ──────────────────────────────╮ │ - Set OPENAI_API_KEY to enable OpenAI models │ ╰────────────────────────────────────────────────╯

⚠ WARN 1 warning requires attention

Step 2: Publish Shared Resources

# Publish an action to the team namespace (visible to all team members) $ agents action create --config ./actions/generate-tests.yaml ╭─ Action Created ──────────────────────────────────────╮ │ Name: myteam/generate-tests │ │ ID: 01HXRC1A2B3C4D5E6F7G8H9J0K │ │ State: available │ │ Strategy Actor: anthropic/claude-3.5-sonnet │ │ Execution Actor: anthropic/claude-3.5-sonnet │ │ Reusable: yes │ │ Read Only: no │ │ Created: 2026-02-11 09:15 │ ╰───────────────────────────────────────────────────────╯ ╭─ Definition of Done ───────────────────────────────────╮ │ All target modules have test coverage above 80% │ │ Tests pass in CI without flaky failures │ ╰────────────────────────────────────────────────────────╯ ╭─ Arguments ─────────────────────────────────────────────────────╮ │ Name Type Required Description │ │ ────────────── ────── ──────── ─────────────────────── │ │ target_module string yes Module path to generate tests │ ╰─────────────────────────────────────────────────────────────────╯ ╭─ Automation ────────────────────────╮ │ Profile: supervised │ │ Source: action default │ ╰─────────────────────────────────────╯ ╭─ Usage ───────────────────────────────────────────────────────────╮ │ agents plan use myteam/generate-tests local/my-project │ │ --arg target_module="src/payments" │ ╰───────────────────────────────────────────────────────────────────╯

✓ OK Action created

# Publish a shared actor $ agents actor add --config ./actors/review-pipeline.yaml ╭─ Actor Added ──────────────────────────────────╮ │ Name: myteam/review-pipeline │ │ Provider: anthropic │ │ Model: claude-3.5-sonnet │ │ Default: no │ │ Unsafe: no │ │ Type: graph │ ╰────────────────────────────────────────────────╯ ╭─ Config ───────────────────────────────╮ │ Path: ./actors/review-pipeline.yaml │ │ Hash: 5a7c2e1 │ │ Options: 3 │ │ Nodes: 5 │ │ Edges: 6 │ ╰────────────────────────────────────────╯ ╭─ Capabilities ──────────────────╮ │ - multi-stage code review │ │ - security analysis │ │ - performance analysis │ │ - style checking │ ╰─────────────────────────────────╯ ╭─ Tools ────────────────────────╮ │ Tool Read-Only Safe │ │ ──────────── ───────── ──── │ │ read_file yes yes │ │ search_files yes yes │ │ git_diff yes yes │ │ run_tests yes yes │ ╰────────────────────────────────╯

✓ OK Actor added

# List available actions (team namespace) $ agents action list --namespace myteam ╭─ Actions ────────────────────────────────────────────────────────────────────────────────────────────────╮ │ Name State Strategy Actor Execution Actor Reusable │ │ ──────────────────────── ───────── ─────────────────────────── ─────────────────────────── ──────── │ │ myteam/generate-tests available anthropic/claude-3.5-sonnet anthropic/claude-3.5-sonnet ✓ │ │ myteam/deep-review available myteam/review-pipeline myteam/review-pipeline ✓ │ │ myteam/format-codebase available anthropic/claude-3.5-sonnet anthropic/claude-3.5-sonnet ✓ │ │ myteam/security-audit available anthropic/claude-3.5-sonnet anthropic/claude-3.5-sonnet ✓ │ │ myteam/refactor-to-orm available anthropic/claude-3.5-sonnet anthropic/claude-3.5-sonnet ✗ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Filters ──────────────────╮ │ State: (any) │ │ Namespace: myteam │ ╰────────────────────────────╯ ╭─ Summary ──────────────────╮ │ Total: 5 │ │ Available: 5 │ │ Archived: 0 │ ╰────────────────────────────╯

✓ OK 5 actions listed

Step 3: Use Shared Resources from Another Machine

On a different developer's machine:


# Configure server connection
$ agents config set server.url https://agents.example.com
╭─ Config Updated ──────────────────────────────╮
│ Key: server.url                               │
│ Value: https://agents.example.com             │
│ Previous: (not set)                           │
│ Source: config                                │
│ Scope: global                                 │
╰───────────────────────────────────────────────╯
✓ OK Config updated
$ agents config set server.token "tok_01HXS..."
╭─ Config Updated ──────────────────────────╮
│ Key: server.token                         │
│ Value: tok_01HXS... (redacted)            │
│ Previous: (not set)                       │
│ Source: config                            │
│ Scope: global                             │
╰───────────────────────────────────────────╯
✓ OK Config updated
$ agents config set core.namespace myteam
╭─ Config Updated ──────────────────────╮
│ Key: core.namespace                   │
│ Value: myteam                         │
│ Previous: local                       │
│ Source: config                        │
│ Scope: global                         │
╰───────────────────────────────────────╯
✓ OK Config updated

# Use the team's shared action $ agents plan use \ --arg target_module="src/payments" \ myteam/generate-tests local/payment-service ╭─ Plan Created ─────────────────────────────────────────╮ │ Plan ID: 01HXRC2B3C4D5E6F7G8H9J0K1L2 │ │ Phase: strategize (running) │ │ Action: myteam/generate-tests │ │ Project: local/payment-service │ │ Automation: supervised │ │ Attempt: 1 │ ╰────────────────────────────────────────────────────────╯ ╭─ Inputs ──────────────────────╮ │ - target_module=src/payments │ ╰───────────────────────────────╯ ╭─ Actors ──────────────────────────────────╮ │ Strategy: anthropic/claude-3.5-sonnet │ │ Execution: anthropic/claude-3.5-sonnet │ │ Source: server (myteam) │ ╰───────────────────────────────────────────╯ ╭─ Context ───────────────────────╮ │ Resources: 1 (repo) │ │ Indexed Files: 189 │ │ View: strategize │ │ Hot Token Budget: 12,000 │ ╰─────────────────────────────────╯ ╭─ Next Steps ──────────────────────────────────────────────╮ │ - agents plan status 01HXRC2B3C4D5E6F7G8H9J0K1L2 │ │ - agents plan tree 01HXRC2B3C4D5E6F7G8H9J0K1L2 │ ╰───────────────────────────────────────────────────────────╯

✓ OK Plan created — strategize in progress

Step 4: Monitor Across the Team

# List all plans across the team $ agents plan list --namespace myteam ╭─ Plans ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ID Phase State Action Project User Elapsed │ │ ──────── ──────── ────────── ────────────────────── ───────────────────── ─────── ───────── │ │ 01HXRC2B execute processing myteam/generate-tests local/payment-service jdoe 00:04:12 │ │ 01HXRC3C apply applied myteam/deep-review local/api-service asmith 00:08:47 │ │ 01HXRC4D execute processing myteam/generate-tests local/api-service mwong 00:02:35 │ │ 01HXRC5E apply applied myteam/format-codebase local/frontend blee 00:01:58 │ │ 01HXRC6F execute awaiting myteam/security-audit local/worker-service asmith 00:06:20 │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Filters ──────────────────╮ │ Phase: (any) │ │ State: (any) │ │ Namespace: myteam │ │ Project: (any) │ │ Action: (any) │ ╰────────────────────────────╯ ╭─ Summary ─────────────╮ │ Total: 5 │ │ Processing: 2 │ │ Completed: 2 │ │ Awaiting: 1 │ │ Errored: 0 │ ╰───────────────────────╯

✓ OK 5 plans listed

# See who is running what — filter to executing state $ agents plan list --namespace myteam --state processing ╭─ Plans ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ID Phase State Action Project User Elapsed │ │ ──────── ─────── ────────── ───────────────────── ───────────────────── ─────── ───────── │ │ 01HXRC2B execute processing myteam/generate-tests local/payment-service jdoe 00:04:12 │ │ 01HXRC4D execute processing myteam/generate-tests local/api-service mwong 00:02:35 │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Filters ──────────────────────╮ │ Phase: (any) │ │ State: processing │ │ Namespace: myteam │ │ Project: (any) │ │ Action: (any) │ ╰────────────────────────────────╯ ╭─ Summary ─────────────╮ │ Total: 2 │ │ Processing: 2 │ │ Completed: 0 │ │ Errored: 0 │ ╰───────────────────────╯

✓ OK 2 plans listed

Example 15: Disaster Recovery — Rollback a Failed Apply

Scenario: A plan was applied, but the changes broke production. The team needs to understand what happened and roll back.

Complexity: Intermediate. Rollback, checkpoint restore, post-mortem analysis.

Step 1: Investigate the Failed Apply

# Check the plan status $ agents plan status 01HXRCF1G2H3I4J5K6L7M8N9O0 ╭─ Plan Status ───────────────────────────────────────╮ │ Plan: 01HXRCF1G2H3I4J5K6L7M8N9O0 │ │ Phase: apply │ │ State: errored │ │ Action: local/optimize-db-connections │ │ Project: local/api-service │ │ Automation: trusted │ │ Attempt: 1 │ ╰─────────────────────────────────────────────────────╯ ╭─ Progress ─────────────────────╮ │ ✓ Strategize │ │ ✓ Execute │ │ ✗ Apply (post-apply failure) │ ╰────────────────────────────────╯ ╭─ Timing ──────────────────────────╮ │ Started: 2026-02-11 08:30:00 │ │ Applied At: 2026-02-11 08:42:18 │ │ Failed At: 2026-02-11 08:44:05 │ │ Total Duration: 00:14:05 │ ╰───────────────────────────────────╯ ╭─ Result ───────────────────────────────────────────────╮ │ Decisions Made: 6 │ │ Child Plans: 0 │ │ Artifacts: 4 files updated │ │ Validations: 2/3 passed (1 FAILED post-apply) │ │ Total Cost: $0.072 │ ╰────────────────────────────────────────────────────────╯ ╭─ Error ──────────────────────────────────────────────────────────────────────╮ │ Post-apply health check failed: connection pool exhaustion detected │ │ Impact: API response times increased 10x, 503 errors in production │ │ Root Cause Decision: 01HXRCD3E4F5G6H7I8J9K0L1 │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Recovery Options ──────────────────────────────────────────────────╮ │ - agents plan rollback — restore to a previous checkpoint │ │ - agents plan correct — revert and re-execute with guidance │ │ - agents plan explain — investigate the root cause decision │ ╰─────────────────────────────────────────────────────────────────────╯

✗ ERROR Plan applied but post-apply validation failed

# Review the decision tree to understand what was done $ agents plan tree 01HXRCF1G2H3I4J5K6L7M8N9O0 ╭─ Decision Tree ────────────────────────────────────────────────────────────────────────────────╮ │ Plan: 01HXRCF1G2H3I4J5K6L7M8N9O0 │ │ ├─ [prompt_definition] "Optimize database connection handling" │ │ ├─ [invariant_enforced] "All DB config changes must preserve existing pool limits" │ │ ├─ [strategy_choice] "Refactor connection pool configuration" (confidence: 0.91) │ │ ├─ [tool_invocation] write_file: src/db/pool_config.py │ │ ├─ [implementation_choice] "Increase pool size to 100" (confidence: 0.78) ← ROOT CAUSE │ │ └─ [tool_invocation] write_file: src/db/health_check.py │ ╰────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Tree Summary ──────────────────╮ │ Nodes: 6 │ │ Depth: 2 │ │ Child Plans: 0 │ │ Invariants: 1 │ │ Superseded: 0 (hidden) │ ╰─────────────────────────────────╯ ╭─ Decision IDs (for correction) ──────────────────────╮ │ Root: 01HXRCC1D2E3F4G5H6I7J8K9 │ │ Invariant 1: 01HXRCC2E3F4G5H6I7J8K9L0 │ │ Strategy: 01HXRCC3F4G5H6I7J8K9L0M1 │ │ Tool 1: 01HXRCC4G5H6I7J8K9L0M1N2 │ │ Pool Size (root cause): 01HXRCD3E4F5G6H7I8J9K0L1 │ │ Tool 2: 01HXRCE4F5G6H7I8J9K0L1M2 │ ╰──────────────────────────────────────────────────────╯

✓ OK Decision tree rendered

# Look at the specific changes that were applied $ agents plan diff 01HXRCF1G2H3I4J5K6L7M8N9O0 ╭─ Diff Summary ─────────────────────────────────────╮ │ Plan: 01HXRCF1G2H3I4J5K6L7M8N9O0 │ │ Project: local/api-service │ │ Files Changed: 4 │ │ Insertions: 38 │ │ Deletions: 12 │ │ Net Change: +26 lines │ ╰────────────────────────────────────────────────────╯ ╭─ Files ──────────────────────────────────────╮ │ Path Change Status │ │ ──────────────────────── ────── ──────── │ │ src/db/pool_config.py +14 -6 modified │ │ src/db/health_check.py +18 -0 new file │ │ src/db/__init__.py +4 -4 modified │ │ config/database.toml +2 -2 modified │ ╰──────────────────────────────────────────────╯ ╭─ Patch Preview ──────────────────────────────────╮ │ --- a/src/db/pool_config.py │ │ +++ b/src/db/pool_config.py │ │ @@ -8,6 +8,14 @@ │ │ - POOL_SIZE = 20 │ │ - POOL_MAX_OVERFLOW = 10 │ │ + POOL_SIZE = 100 │ │ + POOL_MAX_OVERFLOW = 50 │ │ + POOL_RECYCLE = 3600 │ │ + POOL_PRE_PING = True │ │ --- a/config/database.toml │ │ +++ b/config/database.toml │ │ @@ -3,2 +3,2 @@ │ │ - pool_size = 20 │ │ + pool_size = 100 │ ╰──────────────────────────────────────────────────╯ ╭─ Risk Assessment ──────────────────────────╮ │ API Compatibility: preserved │ │ Test Coverage: maintained │ │ Breaking Changes: pool size 5x increase │ │ Resource Impact: high (connection limit) │ ╰────────────────────────────────────────────╯

✓ OK Diff generated

# Examine the decision that led to the problematic change $ agents plan explain 01HXRCD3E4F5G6H7I8J9K0L1 --show-context --show-reasoning ╭─ Decision ───────────────────────────────────────────────────────────╮ │ ID: 01HXRCD3E4F5G6H7I8J9K0L1 │ │ Type: implementation_choice │ │ Question: What pool size should be configured? │ │ Chosen: Increase pool size from 20 to 100 │ │ Confidence: 0.78 │ │ Plan: 01HXRCF1G2H3I4J5K6L7M8N9O0 │ │ Sequence: 5 of 6 │ │ Created: 2026-02-11 08:38 │ ╰──────────────────────────────────────────────────────────────────────╯ ╭─ Alternatives Considered ─────────────────────────────────────╮ │ 1. Increase pool size from 20 to 100 (chosen) │ │ 2. Keep pool at 20, add connection health checks only │ │ 3. Increase to 50 with overflow to 75 │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Impact ─────────────────────────╮ │ Downstream Decisions: 1 │ │ Downstream Child Plans: 0 │ │ Artifacts Produced: 2 │ │ Correction Impact: low │ ╰──────────────────────────────────╯ ╭─ Context Snapshot ────────────────────────────────────────────────╮ │ - Current pool_size=20 in config/database.toml │ │ - Database server: PostgreSQL 15, max_connections=150 │ │ - 3 application replicas running (total: 60 connections used) │ │ - Slow query logs show connection wait times of 200-500ms │ │ Hot Context Hash: sha256:9c4f...a1b2 │ ╰───────────────────────────────────────────────────────────────────╯ ╭─ Rationale ─────────────────────────────────────────────────────╮ │ Connection wait times of 200-500ms suggest pool exhaustion. │ │ Increasing to 100 connections per replica provides headroom │ │ for burst traffic and eliminates the queueing bottleneck. │ ╰─────────────────────────────────────────────────────────────────╯ ╭─ Model Reasoning (raw) ────────────────────────────────────────────────╮ │ The slow query logs show connection acquisition delays of 200-500ms │ │ which indicates the pool is frequently exhausted. Current config: │ │ pool_size=20, max_overflow=10 (total 30 per replica). │ │ │ │ With 3 replicas that's 90 connections max. The PostgreSQL server │ │ allows 150. I'll increase to 100 per replica (300 total with │ │ overflow). This exceeds the server's max_connections=150 but │ │ overflow connections are temporary and unlikely to all be active │ │ simultaneously. │ │ │ │ [NOTE: The model failed to account for 3 replicas × 100 = 300 │ │ exceeding PostgreSQL max_connections=150] │ ╰────────────────────────────────────────────────────────────────────────╯ ╭─ Correction ─────────────────────────────────────────────────╮ │ agents plan correct 01HXRCD3E4F5G6H7I8J9K0L1 │ │ --mode revert --guidance "Keep pool at 20, add health..." │ ╰──────────────────────────────────────────────────────────────╯

✓ OK Decision explained

Step 2: Roll Back to a Checkpoint

# List available checkpoints for this plan $ agents plan artifacts 01HXRCF1G2H3I4J5K6L7M8N9O0 ╭─ Artifacts ────────────────────────────────────────────────────────╮ │ Path Type Size Change Child Plan │ │ ─────────────────────── ───── ────── ─────── ────────── │ │ src/db/pool_config.py edit 1.4 KB +14 -6 root │ │ src/db/health_check.py write 2.1 KB +18 -0 root │ │ src/db/__init__.py edit 0.8 KB +4 -4 root │ │ config/database.toml edit 0.3 KB +2 -2 root │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ Summary ───────────╮ │ Total: 4 │ │ Writes: 1 (new) │ │ Edits: 3 (modified) │ │ Deletes: 0 │ │ Total Size: 4.6 KB │ ╰─────────────────────╯ ╭─ Checkpoints ──────────────────────────────────────────────────────╮ │ ID Label Created │ │ ──────────────────── ─────────────────────────── ────────────── │ │ checkpoint_01HXRCP1 before pool config changes 08:36:12 │ │ checkpoint_01HXRCP2 before health check addition 08:39:45 │ │ checkpoint_01HXRCP3 pre-apply snapshot 08:42:00 │ ╰────────────────────────────────────────────────────────────────────╯ ╭─ By Plan ──────────────╮ │ Root Plan: 4 artifacts │ ╰────────────────────────╯

✓ OK 4 artifacts listed

# Roll back to the checkpoint before the problematic pool config change $ agents plan rollback --yes 01HXRCF1G2H3I4J5K6L7M8N9O0 checkpoint_01HXRCP1 ╭─ Rollback Summary ─────────────────────────────────╮ │ Plan: 01HXRCF1G2H3I4J5K6L7M8N9O0 │ │ Checkpoint: checkpoint_01HXRCP1 │ │ Label: before pool config changes │ │ Files: 4 reverted │ ╰────────────────────────────────────────────────────╯ ╭─ Changes Reverted ──────────────────────╮ │ File Action │ │ ──────────────────────── ────────── │ │ src/db/pool_config.py restored │ │ src/db/health_check.py removed │ │ src/db/__init__.py restored │ │ config/database.toml restored │ ╰─────────────────────────────────────────╯ ╭─ Impact ──────────────────────────────────╮ │ Child Plans Invalidated: 0 │ │ Sandbox: restored to checkpoint_01HXRCP1 │ │ Decisions After CP: 2 discarded │ │ Tool Calls After CP: 3 undone │ ╰───────────────────────────────────────────╯ ╭─ Post-Rollback State ──────────╮ │ Phase: execute │ │ State: queued (awaiting input) │ │ Checkpoints Remaining: 1 │ ╰────────────────────────────────╯

✓ OK Rollback complete

Step 3: Correct and Re-Execute

# Correct the decision that caused the issue $ agents plan correct 01HXRCD3E4F5G6H7I8J9K0L1 \ --mode revert \ --guidance "The connection pool size change caused the outage. \ Keep the pool at 20 connections maximum and add \ connection health checks instead." --yes ╭─ Correction ──────────────────────────────────────────────╮ │ Mode: revert │ │ Impact: 1 decision, 0 child plans, 2 artifacts │ │ New Decision: 01HXRCCORR1A2B3C4D5 │ │ Corrects: 01HXRCD3E4F5G6H7I8J9K0L1 │ │ Attempt: 2 │ ╰───────────────────────────────────────────────────────────╯ ╭─ Affected Subtree ──────────────╮ │ Decisions Invalidated: 1 │ │ Child Plans Rolled Back: 0 │ │ Artifacts Archived: 2 │ │ Unaffected Decisions: 4 │ ╰─────────────────────────────────╯ ╭─ Sandbox Rollback ──────────────────╮ │ Checkpoint: checkpoint_01HXRCP1 │ │ Files Reverted: 2 │ │ Status: restored │ ╰─────────────────────────────────────╯ ╭─ Recompute ───────────╮ │ Queued: 1 re-execute │ │ ETA: 2m │ ╰───────────────────────╯ ╭─ History ───────────────────────────────────────────────╮ │ - Original decision superseded │ │ - Prior artifacts archived for comparison │ │ - agents plan diff --correction 01HXRCCORR1A2B3C4D5 │ ╰─────────────────────────────────────────────────────────╯

✓ OK Correction applied — re-executing affected subtree

# The affected subtree is re-executed. Review the new changes. $ agents plan diff --correction 01HXRCCORR1A2B3C4D5 ╭─ Correction Diff ────────────────────────────────────╮ │ Correction: 01HXRCCORR1A2B3C4D5 │ │ Original Decision: 01HXRCD3E4F5G6H7I8J9K0L1 │ │ Mode: revert │ │ Files Changed: 3 │ │ New Insertions: 32 │ │ New Deletions: 4 │ ╰──────────────────────────────────────────────────────╯ ╭─ Comparison ─────────────────────────────────────────────────────────────╮ │ File Before (original) After (corrected) │ │ ──────────────────────── ────────────────── ────────────────────── │ │ src/db/pool_config.py +14 -6 (pool=100) +8 -2 (pool=20, checks) │ │ src/db/health_check.py +18 -0 (basic) +24 -0 (robust checks) │ │ config/database.toml +2 -2 (pool=100) (unchanged — pool=20) │ ╰──────────────────────────────────────────────────────────────────────────╯ ╭─ Patch Preview (corrected vs original) ───────────────────────╮ │ --- a/src/db/pool_config.py (original) │ │ +++ b/src/db/pool_config.py (corrected) │ │ @@ -8,6 +8,10 @@ │ │ - POOL_SIZE = 100 │ │ - POOL_MAX_OVERFLOW = 50 │ │ + POOL_SIZE = 20 │ │ + POOL_MAX_OVERFLOW = 10 │ │ + POOL_PRE_PING = True │ │ + POOL_HEALTH_CHECK_INTERVAL = 30 │ │ --- a/src/db/health_check.py (original) │ │ +++ b/src/db/health_check.py (corrected) │ │ @@ -1,18 +1,24 @@ │ │ + # Added: connection validation, stale connection eviction, │ │ + # periodic health probes, and circuit breaker pattern │ │ ... │ ╰───────────────────────────────────────────────────────────────╯

✓ OK Correction diff generated

# Re-apply with the fix $ agents plan apply --yes 01HXRCF1G2H3I4J5K6L7M8N9O0 ╭─ Apply Summary ──────────────────────────╮ │ Plan: 01HXRCF1G2H3I4J5K6L7M8N9O0 │ │ Artifacts: 3 files updated │ │ Changes: 32 insertions, 4 deletions │ │ Project: local/api-service │ │ Applied At: 2026-02-11 09:02 │ ╰──────────────────────────────────────────╯ ╭─ Validation ───────────────────╮ │ Tests: passed (31/31) │ │ Lint: passed (0 warnings) │ │ Type Check: passed (0 errors) │ │ Health Check: passed │ │ Duration: 18.6s │ ╰────────────────────────────────╯ ╭─ Sandbox Cleanup ─────────╮ │ Worktree: removed │ │ Branch: merged to main │ │ Checkpoint: archived │ ╰───────────────────────────╯ ╭─ Plan Lifecycle ──────────────────────────╮ │ Phase: apply │ │ State: applied │ │ Total Duration: 00:32:02 (incl. rollback) │ │ Total Cost: $0.118 │ │ Decisions Made: 7 (1 corrected) │ │ Child Plans: 0 │ ╰───────────────────────────────────────────╯ ╭─ Next Steps ──────╮ │ - Review git diff │ │ - Commit changes │ ╰───────────────────╯

✓ OK Changes applied

Example 16: Devcontainer-Driven Development

Scenario: A developer registers a git checkout that contains a .devcontainer/ directory. The system auto-detects the devcontainer, creates it in detected state, then lazily builds and starts it when a plan executes. All tool invocations route to the container via execution environment routing.

What this example demonstrates:

Devcontainer auto-discovery during agents resource add
Lazy activation (container not built until first plan execution)
Execution environment routing selecting the nearest-ancestor devcontainer (precedence level 3)
Tool invocations running inside the container
Apply phase writing changes back to host via bind mount

Step 1 — Register the git checkout (devcontainer auto-detected):

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/webapp --path /home/user/projects/webapp

╭─ Resource ──────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/webapp                                  │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01J0A1B2C3D4E5F6G7H8J9K0L1                      │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout                                  │
│ <span style="color: #66cc66; font-weight: 600;">Path:</span> /home/user/projects/webapp                    │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> main                                        │
╰─────────────────────────────────────────────────────╯

╭─ Auto-discovered Children ─────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">ID</span>               <span style="color: cyan; font-weight: 600;">Type</span>                    <span style="color: cyan; font-weight: 600;">Status</span>                    │
│ <span style="opacity: 0.7;">───────────────  ──────────────────────  ─────────────────</span>         │
│ 01J0A1B2C3D5…   git                     <span style="color: #66cc66; font-weight: 600;">created</span>                    │
│ 01J0A1B2C3D6…   <span style="color: yellow; font-weight: 600;">devcontainer-instance</span>   <span style="color: yellow; font-weight: 600;">detected (not built)</span>       │
│ 01J0A1B2C3D7…   fs-directory            <span style="color: #66cc66; font-weight: 600;">created</span>                    │
│   + 38 git-commit, 205 git-tree-entry, 12 fs-file                  │
╰────────────────────────────────────────────────────────────────────╯

<span style="color: yellow; font-weight: 600;">⚠ Devcontainer detected</span> at .devcontainer/devcontainer.json
  Container will be built lazily on first access.

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered (259 child resources discovered)
</code></pre></div>

=== "Plain"

```
$ agents resource add git-checkout local/webapp --path /home/user/projects/webapp

Resource
  Name: local/webapp
  ID: 01J0A1B2C3D4E5F6G7H8J9K0L1
  Type: git-checkout
  Path: /home/user/projects/webapp
  Branch: main

Auto-discovered Children
ID               Type                    Status
---------------  ----------------------  -----------------
01J0A1B2C3D5..   git                     created
01J0A1B2C3D6..   devcontainer-instance   detected (not built)
01J0A1B2C3D7..   fs-directory            created
  + 38 git-commit, 205 git-tree-entry, 12 fs-file

[WARN] Devcontainer detected at .devcontainer/devcontainer.json
  Container will be built lazily on first access.

[OK] Resource registered (259 child resources discovered)
```

Step 2 — Create project and link the resource:

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project create local/webapp-project
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project created: local/webapp-project

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project link-resource local/webapp-project local/webapp
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource local/webapp linked to project local/webapp-project
</code></pre></div>

=== "Plain"

```
$ agents project create local/webapp-project
[OK] Project created: local/webapp-project

$ agents project link-resource local/webapp-project local/webapp
[OK] Resource local/webapp linked to project local/webapp-project
```

Step 3 — Start a plan (devcontainer lazily built):

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/add-dark-mode local/webapp-project \
  <span style="color: cyan;">--arg</span> feature=dark-mode <span style="color: cyan;">--automation-profile</span> supervised

╭─ Plan Created ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Plan ID:</span> 01J0B2C3D4E5F6G7H8J9K0L1M2                 │
│ <span style="color: yellow; font-weight: 600;">Phase:</span> strategize                                   │
│ <span style="color: magenta; font-weight: 600;">Action:</span> local/add-dark-mode                         │
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/webapp-project                       │
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> supervised                              │
╰─────────────────────────────────────────────────────╯

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan created — strategize phase starting
</code></pre></div>

=== "Plain"

```
$ agents plan use local/add-dark-mode local/webapp-project \
  --arg feature=dark-mode --automation-profile supervised

Plan Created
  Plan ID: 01J0B2C3D4E5F6G7H8J9K0L1M2
  Phase: strategize
  Action: local/add-dark-mode
  Project: local/webapp-project
  Automation: supervised

[OK] Plan created — strategize phase starting
```

Step 4 — Execute the plan (devcontainer activation + tool routing):

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan execute 01J0B2C3D4E5F6G7H8J9K0L1M2

<span style="color: yellow; font-weight: 600;">⏳ Building devcontainer</span> from .devcontainer/devcontainer.json …
  Image: mcr.microsoft.com/devcontainers/typescript-node:1-20
  Features: ghcr.io/devcontainers/features/git:1
  Running postCreateCommand: npm install
<span style="color: #66cc66; font-weight: 600;">✓ Devcontainer ready</span> (01J0A1B2C3D6…) in 42s

╭─ Execution Environment ───────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Resolved via:</span> nearest-ancestor devcontainer       │
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> 01J0A1B2C3D6… (devcontainer-instance)   │
│ <span style="color: #66cc66; font-weight: 600;">Workspace:</span> /workspaces/webapp                     │
│ <span style="color: #5599ff; font-weight: 600;">Precedence:</span> level 3 of 6                          │
╰───────────────────────────────────────────────────╯

<span style="color: #5599ff; font-weight: 600;">▸ Decision 1/3:</span> Create src/theme/dark-mode.ts
  <span style="color: #66cc66; font-weight: 600;">→ write_file()</span> in <span style="color: yellow;">container</span> /workspaces/webapp/src/theme/dark-mode.ts
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-001

<span style="color: #5599ff; font-weight: 600;">▸ Decision 2/3:</span> Update src/App.tsx to import ThemeProvider
  <span style="color: #66cc66; font-weight: 600;">→ edit_file()</span> in <span style="color: yellow;">container</span> /workspaces/webapp/src/App.tsx
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-002

<span style="color: #5599ff; font-weight: 600;">▸ Decision 3/3:</span> Run tests
  <span style="color: #66cc66; font-weight: 600;">→ run_command()</span> in <span style="color: yellow;">container</span> npm test
  <span style="color: #66cc66; font-weight: 600;">✓</span> All 47 tests passed
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-003

╭─ Execution Complete ──────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Decisions:</span> 3/3 succeeded              │
│ <span style="color: #66cc66; font-weight: 600;">Checkpoints:</span> 3                        │
│ <span style="color: #5599ff; font-weight: 600;">Environment:</span> devcontainer             │
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 1m 12s (incl. 42s build)    │
╰───────────────────────────────────────╯

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Execution complete — ready for apply
</code></pre></div>

=== "Plain"

```
$ agents plan execute 01J0B2C3D4E5F6G7H8J9K0L1M2

[WAIT] Building devcontainer from .devcontainer/devcontainer.json …
  Image: mcr.microsoft.com/devcontainers/typescript-node:1-20
  Features: ghcr.io/devcontainers/features/git:1
  Running postCreateCommand: npm install
[OK] Devcontainer ready (01J0A1B2C3D6…) in 42s

Execution Environment
  Resolved via: nearest-ancestor devcontainer
  Resource: 01J0A1B2C3D6… (devcontainer-instance)
  Workspace: /workspaces/webapp
  Precedence: level 3 of 6

Decision 1/3: Create src/theme/dark-mode.ts
  -> write_file() in container /workspaces/webapp/src/theme/dark-mode.ts
  [OK] Checkpoint cp-001

Decision 2/3: Update src/App.tsx to import ThemeProvider
  -> edit_file() in container /workspaces/webapp/src/App.tsx
  [OK] Checkpoint cp-002

Decision 3/3: Run tests
  -> run_command() in container npm test
  [OK] All 47 tests passed
  [OK] Checkpoint cp-003

Execution Complete
  Decisions: 3/3 succeeded
  Checkpoints: 3
  Environment: devcontainer
  Duration: 1m 12s (incl. 42s build)

[OK] Execution complete — ready for apply
```

Step 5 — Apply changes to host:

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan apply --yes 01J0B2C3D4E5F6G7H8J9K0L1M2

╭─ Apply ──────────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Files modified:</span> 2                                │
│   <span style="color: #66cc66;">+ src/theme/dark-mode.ts</span> (new)                 │
│   <span style="color: yellow;">~ src/App.tsx</span> (modified)                       │
│ <span style="color: #5599ff; font-weight: 600;">Target:</span> /home/user/projects/webapp (host)        │
│ <span style="color: #5599ff; font-weight: 600;">Via:</span> bind mount sync from container workspace    │
╰──────────────────────────────────────────────────╯

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Changes applied to host filesystem
</code></pre></div>

=== "Plain"

```
$ agents plan apply --yes 01J0B2C3D4E5F6G7H8J9K0L1M2

Apply
  Files modified: 2
    + src/theme/dark-mode.ts (new)
    ~ src/App.tsx (modified)
  Target: /home/user/projects/webapp (host)
  Via: bind mount sync from container workspace

[OK] Changes applied to host filesystem
```

Example 17: Explicit Container with Directory Mount

Scenario: A team uses a custom container image (not a devcontainer) for development. The operator explicitly creates a container-instance resource with --mount to bind a local directory into the container, then sets it as the project's execution environment with override priority.

What this example demonstrates:

Explicit container-instance creation via agents resource add with --mount flags
Both resource-reference and raw host-path mount styles
Project-level execution_environment with priority: override (precedence level 2)
Container started on first plan execution, no devcontainer.json needed

Step 1 — Register the code repository and container:

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/api-repo --path /home/user/projects/api
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered: local/api-repo (127 children)

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add container-instance local/api-container \
  <span style="color: cyan;">--mount</span> local/api-repo:/workspace \
  <span style="color: cyan;">--mount</span> /home/user/.ssh:/home/dev/.ssh:ro

╭─ Resource ──────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-container                       │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01J0C3D4E5F6G7H8J9K0L1M2N3                  │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> container-instance                        │
│ <span style="color: #66cc66; font-weight: 600;">State:</span> created (not started)                    │
╰─────────────────────────────────────────────────╯

╭─ Mounts ──────────────────────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Source</span>                    <span style="color: cyan; font-weight: 600;">Container Path</span>       <span style="color: cyan; font-weight: 600;">Kind</span>    <span style="color: cyan; font-weight: 600;">Mode</span>       │
│ <span style="opacity: 0.7;">────────────────────────  ──────────────────   ──────  ────</span>       │
│ local/api-repo            /workspace           res-ref rw         │
│ /home/user/.ssh           /home/dev/.ssh       host    ro         │
╰───────────────────────────────────────────────────────────────────╯

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Container resource registered
</code></pre></div>

=== "Plain"

```
$ agents resource add git-checkout local/api-repo --path /home/user/projects/api
[OK] Resource registered: local/api-repo (127 children)

$ agents resource add container-instance local/api-container \
  --mount local/api-repo:/workspace \
  --mount /home/user/.ssh:/home/dev/.ssh:ro

Resource
  Name: local/api-container
  ID: 01J0C3D4E5F6G7H8J9K0L1M2N3
  Type: container-instance
  State: created (not started)

Mounts
Source                    Container Path       Kind     Mode
------------------------  ------------------   ------   ----
local/api-repo            /workspace           res-ref  rw
/home/user/.ssh           /home/dev/.ssh       host     ro

[OK] Container resource registered
```

Step 2 — Create project, link resources, set execution environment:

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project create local/api-project
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project created

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project link-resource local/api-project local/api-repo
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource linked

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project link-resource local/api-project local/api-container
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource linked

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context set \
  <span style="color: cyan;">--execution-environment</span> local/api-container \
  <span style="color: cyan;">--execution-env-priority</span> override \
  local/api-project

╭─ Context Policy Updated ──────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Execution Environment:</span> local/api-container        │
│ <span style="color: #5599ff; font-weight: 600;">Priority:</span> override (precedence level 2)           │
│ <span style="color: yellow; font-weight: 600;">Note:</span> All tool invocations will route to this     │
│       container, bypassing devcontainer detection │
╰───────────────────────────────────────────────────╯

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context policy updated
</code></pre></div>

=== "Plain"

```
$ agents project create local/api-project
[OK] Project created

$ agents project link-resource local/api-project local/api-repo
[OK] Resource linked

$ agents project link-resource local/api-project local/api-container
[OK] Resource linked

$ agents project context set \
  --execution-environment local/api-container \
  --execution-env-priority override \
  local/api-project

Context Policy Updated
  Execution Environment: local/api-container
  Priority: override (precedence level 2)
  Note: All tool invocations will route to this
        container, bypassing devcontainer detection

[OK] Context policy updated
```

Step 3 — Execute a plan (container started, tools routed):

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/fix-auth-bug local/api-project --automation-profile trusted

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan 01J0D4E5F6G7H8J9K0L1M2N3O4 created — strategize phase starting

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan execute 01J0D4E5F6G7H8J9K0L1M2N3O4

<span style="color: yellow; font-weight: 600;">⏳ Starting container</span> local/api-container …
<span style="color: #66cc66; font-weight: 600;">✓ Container ready</span> in 3s

╭─ Execution Environment ───────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Resolved via:</span> project override                    │
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> local/api-container                     │
│ <span style="color: #66cc66; font-weight: 600;">Workspace:</span> /workspace                             │
│ <span style="color: #5599ff; font-weight: 600;">Precedence:</span> level 2 of 6                          │
╰───────────────────────────────────────────────────╯

<span style="color: #5599ff; font-weight: 600;">▸ Decision 1/2:</span> Fix token validation in src/auth/jwt.ts
  <span style="color: #66cc66; font-weight: 600;">→ edit_file()</span> in <span style="color: yellow;">container</span> /workspace/src/auth/jwt.ts
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-001

<span style="color: #5599ff; font-weight: 600;">▸ Decision 2/2:</span> Run auth test suite
  <span style="color: #66cc66; font-weight: 600;">→ run_command()</span> in <span style="color: yellow;">container</span> npm test -- --grep auth
  <span style="color: #66cc66; font-weight: 600;">✓</span> 12/12 tests passed
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-002

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Execution complete — ready for apply
</code></pre></div>

=== "Plain"

```
$ agents plan use local/fix-auth-bug local/api-project --automation-profile trusted
[OK] Plan 01J0D4E5F6G7H8J9K0L1M2N3O4 created — strategize phase starting

$ agents plan execute 01J0D4E5F6G7H8J9K0L1M2N3O4

[WAIT] Starting container local/api-container …
[OK] Container ready in 3s

Execution Environment
  Resolved via: project override
  Resource: local/api-container
  Workspace: /workspace
  Precedence: level 2 of 6

Decision 1/2: Fix token validation in src/auth/jwt.ts
  -> edit_file() in container /workspace/src/auth/jwt.ts
  [OK] Checkpoint cp-001

Decision 2/2: Run auth test suite
  -> run_command() in container npm test -- --grep auth
  [OK] 12/12 tests passed
  [OK] Checkpoint cp-002

[OK] Execution complete — ready for apply
```

Example 18: Container with Remote Repo Clone

Scenario: A CI/CD pipeline creates a container-instance that clones a remote repository on first start. There is no local checkout — the code lives entirely inside the container. This pattern is useful for cloud-based or ephemeral build environments where the operator has no local filesystem access to the repository.

What this example demonstrates:

--clone-into flag on agents resource add container-instance
Remote repository cloned lazily on container first start
Plan-level execution environment with fallback priority (precedence level 4)
No local git-checkout or devcontainer involved

Step 1 — Create container resource with clone-into:

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add container-instance cloud/build-env \
  <span style="color: cyan;">--clone-into</span> https://github.com/acme/billing-api.git:/workspace

╭─ Resource ──────────────────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Name:</span> cloud/build-env                               │
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01J0E5F6G7H8J9K0L1M2N3O4P5                      │
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> container-instance                            │
│ <span style="color: #66cc66; font-weight: 600;">State:</span> created (not started)                        │
│ <span style="color: #66cc66; font-weight: 600;">Clone:</span> https://github.com/acme/billing-api.git      │
│ <span style="color: #66cc66; font-weight: 600;">Clone Target:</span> /workspace                            │
╰─────────────────────────────────────────────────────╯

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Container resource registered (repo will be cloned on first start)
</code></pre></div>

=== "Plain"

```
$ agents resource add container-instance cloud/build-env \
  --clone-into https://github.com/acme/billing-api.git:/workspace

Resource
  Name: cloud/build-env
  ID: 01J0E5F6G7H8J9K0L1M2N3O4P5
  Type: container-instance
  State: created (not started)
  Clone: https://github.com/acme/billing-api.git
  Clone Target: /workspace

[OK] Container resource registered (repo will be cloned on first start)
```

Step 2 — Create project and link the container:

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project create cloud/billing-api
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project created

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project link-resource cloud/billing-api cloud/build-env
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource linked
</code></pre></div>

=== "Plain"

```
$ agents project create cloud/billing-api
[OK] Project created

$ agents project link-resource cloud/billing-api cloud/build-env
[OK] Resource linked
```

Step 3 — Execute plan with plan-level execution environment:

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/add-pagination cloud/billing-api \
  <span style="color: cyan;">--execution-environment</span> cloud/build-env \
  <span style="color: cyan;">--execution-env-priority</span> fallback \
  <span style="color: cyan;">--automation-profile</span> trusted

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan 01J0F6G7H8J9K0L1M2N3O4P5Q6 created

<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan execute 01J0F6G7H8J9K0L1M2N3O4P5Q6

<span style="color: yellow; font-weight: 600;">⏳ Starting container</span> cloud/build-env …
<span style="color: yellow; font-weight: 600;">⏳ Cloning</span> https://github.com/acme/billing-api.git into /workspace …
<span style="color: #66cc66; font-weight: 600;">✓ Clone complete</span> (1.2 GB, 47s)
<span style="color: #66cc66; font-weight: 600;">✓ Container ready</span> in 52s

╭─ Execution Environment ─────────────────────────────╮
│ <span style="color: cyan; font-weight: 600;">Resolved via:</span> plan fallback                         │
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> cloud/build-env                           │
│ <span style="color: #66cc66; font-weight: 600;">Workspace:</span> /workspace                               │
│ <span style="color: #5599ff; font-weight: 600;">Precedence:</span> level 4 of 6                            │
│ <span style="color: yellow; font-weight: 600;">Note:</span> No devcontainer detected; using plan fallback │
╰─────────────────────────────────────────────────────╯

<span style="color: #5599ff; font-weight: 600;">▸ Decision 1/4:</span> Add cursor-based pagination to /workspace/src/api/invoices.ts
  <span style="color: #66cc66; font-weight: 600;">→ edit_file()</span> in <span style="color: yellow;">container</span>
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-001

<span style="color: #5599ff; font-weight: 600;">▸ Decision 2/4:</span> Add pagination types to /workspace/src/types/pagination.ts
  <span style="color: #66cc66; font-weight: 600;">→ write_file()</span> in <span style="color: yellow;">container</span>
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-002

<span style="color: #5599ff; font-weight: 600;">▸ Decision 3/4:</span> Update API tests
  <span style="color: #66cc66; font-weight: 600;">→ edit_file()</span> in <span style="color: yellow;">container</span>
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-003

<span style="color: #5599ff; font-weight: 600;">▸ Decision 4/4:</span> Run test suite
  <span style="color: #66cc66; font-weight: 600;">→ run_command()</span> in <span style="color: yellow;">container</span> npm test
  <span style="color: #66cc66; font-weight: 600;">✓</span> 89/89 tests passed
  <span style="color: #66cc66; font-weight: 600;">✓</span> Checkpoint cp-004

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Execution complete — ready for apply
</code></pre></div>

=== "Plain"

```
$ agents plan use local/add-pagination cloud/billing-api \
  --execution-environment cloud/build-env \
  --execution-env-priority fallback \
  --automation-profile trusted

[OK] Plan 01J0F6G7H8J9K0L1M2N3O4P5Q6 created

$ agents plan execute 01J0F6G7H8J9K0L1M2N3O4P5Q6

[WAIT] Starting container cloud/build-env …
[WAIT] Cloning https://github.com/acme/billing-api.git into /workspace …
[OK] Clone complete (1.2 GB, 47s)
[OK] Container ready in 52s

Execution Environment
  Resolved via: plan fallback
  Resource: cloud/build-env
  Workspace: /workspace
  Precedence: level 4 of 6
  Note: No devcontainer detected; using plan fallback

Decision 1/4: Add cursor-based pagination to /workspace/src/api/invoices.ts
  -> edit_file() in container
  [OK] Checkpoint cp-001

Decision 2/4: Add pagination types to /workspace/src/types/pagination.ts
  -> write_file() in container
  [OK] Checkpoint cp-002

Decision 3/4: Update API tests
  -> edit_file() in container
  [OK] Checkpoint cp-003

Decision 4/4: Run test suite
  -> run_command() in container npm test
  [OK] 89/89 tests passed
  [OK] Checkpoint cp-004

[OK] Execution complete — ready for apply
```

Step 4 — Apply (changes committed inside container, pushed to remote):

=== "Rich"

<div class="highlight"><pre><code>
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan apply --yes 01J0F6G7H8J9K0L1M2N3O4P5Q6

╭─ Apply ──────────────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">Files modified:</span> 3                                │
│   <span style="color: yellow;">~ src/api/invoices.ts</span> (modified)               │
│   <span style="color: #66cc66;">+ src/types/pagination.ts</span> (new)                │
│   <span style="color: yellow;">~ tests/api/invoices.test.ts</span> (modified)        │
│ <span style="color: #5599ff; font-weight: 600;">Target:</span> container /workspace                     │
│ <span style="color: #5599ff; font-weight: 600;">Apply mode:</span> commit + push to origin/main         │
╰──────────────────────────────────────────────────╯

<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Changes applied (committed as abc1234, pushed to origin/main)
</code></pre></div>

=== "Plain"

```
$ agents plan apply --yes 01J0F6G7H8J9K0L1M2N3O4P5Q6

Apply
  Files modified: 3
    ~ src/api/invoices.ts (modified)
    + src/types/pagination.ts (new)
    ~ tests/api/invoices.test.ts (modified)
  Target: container /workspace
  Apply mode: commit + push to origin/main

[OK] Changes applied (committed as abc1234, pushed to origin/main)
```

588 KiB Raw Blame History Unescape Escape

Workflow Examples

Example 1: Hello World — Fix a Single Bug

Step 1: Initialize Environment and Register Resources

Step 2: Create an Action

Step 3: Create and Execute a Plan

Step 4: Review and Apply

Example 2: Automated Test Generation for a Module

Step 1: Setup (Assuming Project Exists)

Step 2: Create the Test Generation Action

Step 3: Execute

Example 3: Multi-File Refactoring with Invariants

Step 1: Define Invariants

Step 2: Create a Refactoring Action with Custom Actors

Step 3: Execute with Cautious Profile

Step 4: Correct a Decision

Step 5: Apply

Example 4: Multi-Project Dependency Update

Step 1: Register All Projects and Resources

Step 2: Create a Coordinated Update Action

Step 3: Execute Across Multiple Projects

Step 4: Review and Apply in Order

Example 5: Database Schema Migration with Safety Nets

Step 1: Register the Database as a Resource

Step 2: Create a Custom Skill with Database Tools

Step 3: Create the Migration Action and Execute the Plan

Step 4: Monitor Execution and Rollback if Needed

Example 6: Writing Technical Documentation from Codebase Analysis

Step 1: Create a Read-Only Documentation Action

Step 2: Configure Context for Large Codebase Analysis

Step 3: Execute

Example 7: CI/CD Integration — Automated PR Review and Fix

Step 1: Configure for CI

Step 2: Create the PR Review Action

Step 3: CI Pipeline Script

Example 8: Cloud Infrastructure Management

Step 1: Register Custom Resource Types and Skills

Step 2: Set Up the Project

Step 3: Create and Run the Optimization Action

Example 9: Session-Driven Interactive Exploration

Step 1: Start a Session

Step 2: Explore the Codebase Interactively

Step 3: Review Session History

Example 10: Full-Auto Batch Operations — Formatting and Linting

Step 1: Create a Formatting Action

Step 2: Register All Packages and Run in Batch

Example 11: Complex Graph Actor for Multi-Stage Code Review

Step 1: Define Specialized Sub-Actors

Step 2: Create the Review Action Using the Graph Actor

Example 12: Large-Scale Feature Implementation with Hierarchical Decomposition

Step 1: Set Up All Projects

Step 2: Create the Feature Action

Step 3: Initiate the Plan

Step 4: Monitor and Guide the Hierarchical Execution

Step 5: Handle a Failure in One Child Plan

Step 6: Apply in Phases

Example 13: Custom Automation Profile with Semantic Escalation

Step 1: Create a Custom Profile

Step 2: Apply to a Project with Database Resources

Step 3: Run a Plan and Observe Escalation

Example 14: Server Mode — Team Collaboration

Step 1: Connect to the Server

Step 2: Publish Shared Resources

Step 3: Use Shared Resources from Another Machine

Step 4: Monitor Across the Team

Example 15: Disaster Recovery — Rollback a Failed Apply

Step 1: Investigate the Failed Apply

Step 2: Roll Back to a Checkpoint

Step 3: Correct and Re-Execute

Example 16: Devcontainer-Driven Development

Example 17: Explicit Container with Directory Mount

Example 18: Container with Remote Repo Clone

588 KiB

Raw Blame History