## 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
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
# 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
# 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
# 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
# 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 │
│ @@ -8,6 +8,11 @@ │
│ @app.get("/health") │
│ def health_check(): │
│ - 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"}│
│ --- a/tests/test_health.py │
│ +++ b/tests/test_health.py │
│ @@ -15,0 +16,11 @@ │
│ +def 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
# 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
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
# 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
# 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
$ 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)
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
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
$ 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
# 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
# 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
$ 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
# 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
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
# 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
# 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)
# 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
# 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
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
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
# 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
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
# 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
$ 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
# 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
# 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
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
#!/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"
{
"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"
}
}
{
"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"]
}
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
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
# 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
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
$ 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
$ 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:
1. **`src/api/routes/`** — HTTP route definitions (REST + GraphQL). Each domain
entity has its own router file (e.g. `users.py`, `orders.py`, `products.py`).
2. **`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`.
3. **`src/api/models/`** — SQLAlchemy ORM models and Pydantic schemas. The
models map 1:1 to database tables; schemas handle request/response validation.
4. **`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.
5. **`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:
1. Checks out the target project's repository
2. Runs `pip compile` / `poetry lock` (auto-detected from project config)
3. Runs the test suite to verify nothing broke
4. Commits the updated lock files on a new branch
5. 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
$ 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
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
# 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
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
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
# 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
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
$ 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
# 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
# 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
# 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
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
$ 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
$ 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
$ 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 │
╰────────────────────────────────────────────────────────────────────╯
⚠ Devcontainer detected at .devcontainer/devcontainer.json
Container will be built lazily on first access.
✓ OK Resource registered (259 child resources discovered)
$ 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
$ 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
$ agents plan execute 01J0B2C3D4E5F6G7H8J9K0L1M2
⏳ 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
✓ 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
✓ Checkpoint cp-001
▸ Decision 2/3: Update src/App.tsx to import ThemeProvider
→ edit_file() in container /workspaces/webapp/src/App.tsx
✓ Checkpoint cp-002
▸ Decision 3/3: Run tests
→ run_command() in container npm test
✓ All 47 tests passed
✓ 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
$ 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
$ 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
$ 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
$ agents plan use local/fix-auth-bug local/api-project --automation-profile trusted
✓ OK Plan 01J0D4E5F6G7H8J9K0L1M2N3O4 created — strategize phase starting
$ agents plan execute 01J0D4E5F6G7H8J9K0L1M2N3O4
⏳ Starting container local/api-container …
✓ 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
✓ Checkpoint cp-001
▸ Decision 2/2: Run auth test suite
→ run_command() in container npm test -- --grep auth
✓ 12/12 tests passed
✓ Checkpoint cp-002
✓ OK Execution complete — ready for apply
$ 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)
$ agents project create cloud/billing-api
✓ OK Project created
$ agents project link-resource cloud/billing-api cloud/build-env
✓ OK Resource linked
$ 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
⏳ Starting container cloud/build-env …
⏳ Cloning https://github.com/acme/billing-api.git into /workspace …
✓ Clone complete (1.2 GB, 47s)
✓ 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
✓ Checkpoint cp-001
▸ Decision 2/4: Add pagination types to /workspace/src/types/pagination.ts
→ write_file() in container
✓ Checkpoint cp-002
▸ Decision 3/4: Update API tests
→ edit_file() in container
✓ Checkpoint cp-003
▸ Decision 4/4: Run test suite
→ run_command() in container npm test
✓ 89/89 tests passed
✓ Checkpoint cp-004
✓ OK Execution complete — ready for apply
$ 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)