cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity
Files
master
cleveragents-core/docs/showcase/cli-tools/action-and-plan-management.md
T
HAL9000 057e3f5bfb
ci.yml / docs: showing off some showcased workflows (push) Failing after 0s
Details
docs: showing off some showcased workflows
2026-04-07 15:27:39 -04:00

40 KiB
Raw Permalink Blame History

Action & Plan Management: The v3 Plan Lifecycle

Overview

CleverAgents uses a v3 plan lifecycle built around reusable Actions — YAML-defined templates that describe what an AI agent should do — and Plans — runtime instances of those actions applied to specific projects. This example walks through the complete workflow: defining actions from YAML files, registering them, creating plans, filtering and inspecting them, and managing their lifecycle.

Prerequisites

  • CleverAgents installed (pip install cleveragents)
  • Python 3.12 or higher
  • The examples/actions/ directory from the CleverAgents repository (included in the repo)

What You'll Learn

  • How to define an Action in YAML and register it with agents action create
  • How to list, filter, and inspect actions with agents action list and agents action show
  • How to archive (soft-delete) an action with agents action archive
  • How to create a Project with agents project create
  • How to instantiate a Plan from an action with agents plan use
  • How to list and filter plans by phase, state, action, and project
  • How to inspect a specific plan with agents plan status
  • How to cancel a plan with agents plan cancel
  • How to use --format json for machine-readable output and scripting

The v3 Plan Lifecycle at a Glance

Action (YAML template)
        │
        ▼
agents action create --config <file>
        │
        ▼
Action registered (state: available)
        │
        ▼
agents plan use <action> <project>
        │
        ▼
Plan created (phase: strategize, state: queued)
        │
        ▼
agents plan execute <plan-id>   ← drives LLM strategy + execution
        │
        ▼
Plan (phase: execute, state: complete)
        │
        ▼
agents plan apply <plan-id>     ← writes changes to disk
        │
        ▼
Plan (phase: apply, state: applied) ← terminal

Step-by-Step Walkthrough

Step 1: Explore the example Action YAML files

The repository ships with five ready-to-use action examples in examples/actions/:

examples/actions/
├── simple.yaml          # Minimal action — required fields only
├── estimation-actor.yaml # Action with cost/risk estimation
├── invariant-heavy.yaml  # Action with multiple safety invariants
├── inputs-schema.yaml    # Action with JSON Schema input validation
└── read-only.yaml        # Read-only investigation/audit action

The simplest action (examples/actions/simple.yaml) looks like this:

# examples/actions/simple.yaml
name: local/lint-check
description: "Run linting checks on the project"

strategy_actor: local/strategist
execution_actor: local/executor

definition_of_done: |
  All linting checks pass with zero errors.

reusable: true
read_only: true

Key fields:

Field Required Description
name ✓ Namespaced name (namespace/short-name)
description ✓ One-line summary
strategy_actor ✓ Actor that creates the execution strategy
execution_actor ✓ Actor that runs the plan
definition_of_done ✓ Completion criteria for the AI
reusable Whether the action can be used multiple times
read_only Prevents the plan from writing files
arguments Typed parameters passed at plan creation time
invariants Hard constraints that must never be violated
estimation_actor Actor for pre-execution cost/risk estimation
invariant_actor Actor for invariant reconciliation
automation_profile manual, supervised, or trusted

Step 2: Register the simple action

$ agents action create --config examples/actions/simple.yaml

Output:

╭──────────────── Action Created ────────────────╮
│ Namespaced Name: local/lint-check              │
│ Short Name: lint-check                         │
│ Description: Run linting checks on the project │
│ State: available                               │
│ Strategy Actor: local/strategist               │
│ Execution Actor: local/executor                │
│ Reusable: yes                                  │
│ Read Only: yes                                 │
│ Definition of Done:                            │
│   All linting checks pass with zero errors.    │
│ Arguments:                                     │
│   (none)                                       │
│ Created: 2026-04-07 09:01:03.641772            │
╰────────────────────────────────────────────────╯

What's Happening:

The action create command reads the YAML file, validates it against the ActionConfigSchema, and persists the action to the database. The action starts in available state and is immediately usable for creating plans.

Step 3: Register the remaining example actions

$ agents action create --config examples/actions/estimation-actor.yaml
$ agents action create --config examples/actions/invariant-heavy.yaml
$ agents action create --config examples/actions/read-only.yaml
$ agents action create --config examples/actions/inputs-schema.yaml

Each command outputs a confirmation panel. After all four commands, you have five actions registered.

Step 4: List all actions

$ agents action list

Output:

                               Actions (5 total)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Namespaced Name            ┃ Short Name          ┃ State     ┃ Strategy Actor     ┃ Execution Actor    ┃ Definition of Done                     ┃ Reusa… ┃ Created          ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ local/architecture-review  │ architecture-review │ available │ local/strategist   │ local/executor     │ Architecture review report generated…  │   ✓    │ 2026-04-07 09:01 │
│ local/data-pipeline        │ data-pipeline       │ available │ local/strategist   │ local/executor     │ Pipeline runs end-to-end successfully… │   ✓    │ 2026-04-07 09:01 │
│ local/large-refactor       │ large-refactor      │ available │ local/strategist   │ local/executor     │ Refactoring complete. All tests pass…  │   ✓    │ 2026-04-07 09:01 │
│ local/lint-check           │ lint-check          │ available │ local/strategist   │ local/executor     │ All linting checks pass with zero err… │   ✓    │ 2026-04-07 09:01 │
│ local/security-audit       │ security-audit      │ available │ local/security-st… │ local/security-sc… │ All critical and high severity finding │   ✓    │ 2026-04-07 09:01 │
└────────────────────────────┴─────────────────────┴───────────┴────────────────────┴────────────────────┴────────────────────────────────────────┴────────┴──────────────────┘

What's Happening:

The table shows all registered actions with their namespaced names, states, assigned actors, and a truncated definition of done. The ✓ in the Reusable column means the action can be used to create multiple plans.

Step 5: Filter actions by namespace and state

# Filter by namespace
$ agents action list --namespace local

# Filter by state
$ agents action list --state available

# Filter by regex pattern (actions matching "audit")
$ agents action list ".*audit.*"

Output for regex filter:

                               Actions (1 total)
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Namespaced Name      ┃ Short Name   ┃ State     ┃ Strategy Actor         ┃ Execution Actor        ┃ Definition of Done                     ┃ Reusa… ┃ Created          ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ local/security-audit │ security-audit│ available │ local/security-strate… │ local/security-scanner │ All critical and high severity finding │   ✓    │ 2026-04-07 09:01 │
└──────────────────────┴──────────────┴───────────┴────────────────────────┴────────────────────────┴────────────────────────────────────────┴────────┴──────────────────┘

Step 6: Inspect a specific action

$ agents action show local/security-audit

Output:

╭──────────────────────── Action Details ─────────────────────────╮
│ Namespaced Name: local/security-audit                           │
│ Short Name: security-audit                                      │
│ Description: Comprehensive security audit of a project          │
│ State: available                                                │
│ Strategy Actor: local/security-strategist                       │
│ Execution Actor: local/security-scanner                         │
│ Reusable: yes                                                   │
│ Read Only: no                                                   │
│ Definition of Done:                                             │
│   All critical and high severity findings have been identified. │
│ A complete security report has been generated with seve...      │
│ Arguments:                                                      │
│   • severity_threshold (string, optional)                       │
│     Minimum severity to include in report                       │
│   • auto_fix (boolean, optional)                                │
│     Automatically create fix plans for critical findings        │
│ Created: 2026-04-07 09:01:28.745244                             │
╰─────────────────────────────────────────────────────────────────╯

What's Happening:

action show displays the full action details including all arguments with their types and whether they are required or optional. Arguments are passed to agents plan use via --arg name=value flags.

Step 7: Get action details as JSON

$ agents action show local/large-refactor --format json

Output:

{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "namespaced_name": "local/large-refactor",
    "short_name": "large-refactor",
    "state": "available",
    "description": "Large-scale code refactoring with cost estimation",
    "definition_of_done": "Refactoring complete. All tests pass. No regressions introduced.\nCode review approved by the review actor.",
    "strategy_actor": "local/strategist",
    "execution_actor": "local/executor",
    "automation_profile": null,
    "arguments": [
      {
        "name": "target_module",
        "type": "string",
        "required": true,
        "description": "Module path to refactor"
      },
      {
        "name": "max_files_changed",
        "type": "integer",
        "required": false,
        "description": "Maximum number of files to modify"
      }
    ],
    "invariants": [],
    "reusable": true,
    "read_only": false,
    "created_at": "2026-04-07T09:01:20.683193"
  },
  "timing": {
    "duration_ms": 0
  },
  "messages": [
    {
      "level": "ok",
      "text": "ok"
    }
  ]
}

What's Happening:

The JSON envelope (command, status, exit_code, data, timing, messages) is the standard output format for all CleverAgents CLI commands. The data field contains the action's full specification, including the arguments array with typed parameter definitions.

Step 8: Archive an action (soft delete)

$ agents action archive local/lint-check

Output:

✓ Action archived: local/lint-check

Archived actions are preserved for history but cannot be used to create new plans. You can still see them with --state archived:

$ agents action list --state archived

Output:

                               Actions (1 total)
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Namespaced Name    ┃ Short Name ┃ State    ┃ Strategy Actor   ┃ Execution Actor  ┃ Definition of Done                     ┃ Reusa… ┃ Created          ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ local/lint-check   │ lint-check │ archived │ local/strategist │ local/executor   │ All linting checks pass with zero err… │   ✓    │ 2026-04-07 09:01 │
└────────────────────┴────────────┴──────────┴──────────────────┴──────────────────┴────────────────────────────────────────┴────────┴──────────────────┘

Step 9: Create a project

Plans require at least one project to operate on. Create one with:

$ agents project create local/my-webapp --description "A sample web application project"

Output:

╭─────────────── Project Created ───────────────╮
│ ✓ Project 'local/my-webapp' created.          │
│ Namespace: local                              │
│ Description: A sample web application project │
│ Resources: 0                                  │
╰───────────────────────────────────────────────╯

Step 10: Create a plan from an action

$ agents plan use local/architecture-review local/my-webapp

Output:

╭──────────────────────────── Plan Created ─────────────────────────────╮
│ ID: 01KNKJZ424C48388RWHW3KY5QZ                                        │
│ Name: local/architecture-review-01knkjz4                              │
│ Action: local/architecture-review                                     │
│ Phase: strategize                                                     │
│ Processing State: queued                                              │
│ Projects: local/my-webapp                                             │
│ Description:                                                          │
│   Analyzes the project structure, dependency graph, and code patterns │
│ to produce an architecture review report. Does not modify any files.  │
│ Strategy Actor: local/strategist                                      │
│ Execution Actor: local/executor                                       │
│ Definition of Done:                                                   │
│   Architecture review report generated covering:                      │
│ - Module dependency graph                                             │
│ - Layer boundary compliance                                           │
│ - Circular dependency detection                                       │
│ - Code duplication analysis                                           │
│ Automation Profile: manual (source: global)                           │
│ Terminal: no                                                          │
│ Created: 2026-04-07 09:04:23.620455                                   │
│ Updated: 2026-04-07 09:04:23.620456                                   │
╰───────────────────────────────────────────────────────────────────────╯

Plan is now in Strategize phase (queued). Run 'agents plan execute <id>' when
ready.

What's Happening:

plan use creates a new plan instance from the action template. The plan receives a ULID identifier (e.g., 01KNKJZ424C48388RWHW3KY5QZ) — a 26-character sortable unique ID used for all subsequent commands. The plan starts in strategize phase with queued state, ready for execution.

Important: All v3 plan commands (plan execute, plan apply, plan status, etc.) require the ULID identifier, not the plan name.

Step 11: Create a plan with arguments and invariants

The security-audit action accepts arguments. Pass them with --arg:

$ agents plan use local/security-audit local/my-webapp \
    --arg severity_threshold=high \
    --arg auto_fix=false \
    --invariant "Never modify production data"

Output:

╭───────────────────────── Plan Created ──────────────────────────╮
│ ID: 01KNKK0MKCDXGP8Z3PZ88S5GGZ                                  │
│ Name: local/security-audit-01knkk0m                             │
│ Action: local/security-audit                                    │
│ Phase: strategize                                               │
│ Processing State: queued                                        │
│ Projects: local/my-webapp                                       │
│ Description:                                                    │
│   Performs a thorough security audit covering:                  │
│ - Dependency vulnerability scanning                             │
│ - Static Application Security Testing (SAST)                    │
│ - Authentication and authorization review                       │
│ - Input validation and injection...                             │
│ Strategy Actor: local/security-strategist                       │
│ Execution Actor: local/security-scanner                         │
│ Definition of Done:                                             │
│   All critical and high severity findings have been identified. │
│ A complete security report has been generated with severity     │
│ classifications and remediation steps for each finding.         │
│ Arguments:                                                      │
│   severity_threshold = high                                     │
│   auto_fix = False                                              │
│ Automation Profile: manual (source: global)                     │
│ Invariants:                                                     │
│    Never modify production data                                 │
│ Terminal: no                                                    │
│ Created: 2026-04-07 09:05:13.325077                             │
│ Updated: 2026-04-07 09:05:13.325079                             │
╰─────────────────────────────────────────────────────────────────╯

Plan is now in Strategize phase (queued). Run 'agents plan execute <id>' when
ready.

What's Happening:

  • --arg severity_threshold=high passes a typed argument to the plan. Arguments are validated against the action's argument definitions.
  • --invariant "Never modify production data" adds a runtime constraint. Invariants are hard rules the AI must never violate during execution.

Step 12: List all plans

$ agents plan list

Output:

                                     Plans
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ ID                         ┃ Name                                   ┃ Phase      ┃ State    ┃ Action                 ┃ Invaria… ┃ Projects           ┃ Updated            ┃ Elapsed       ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ 01KNKJZ44ES00VT8JTRKX1HEQA │ local/architecture-review-01knkjz4    │ strategize │ queued   │ local/architecture-re… │ 0        │ (none)             │ 2026-04-07 09:04   │ 00:00:50      │
│ 01KNKJZ424C48388RWHW3KY5QZ │ local/architecture-review-01knkjz4    │ strategize │ queued   │ local/architecture-re… │ 0        │ local/my-webapp    │ 2026-04-07 09:04   │ 00:00:50      │
│ 01KNKK0MKCDXGP8Z3PZ88S5GGZ │ local/security-audit-01knkk0m         │ strategize │ queued   │ local/security-audit   │ 1        │ local/my-webapp    │ 2026-04-07 09:05   │ 00:00:00      │
└────────────────────────────┴────────────────────────────────────────┴────────────┴──────────┴────────────────────────┴──────────┴────────────────────┴────────────────────┴───────────────┘
╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Total: 3                                                                     │
│ Processing: 0                                                                │
│ Completed: 0                                                                 │
│ Errored: 0                                                                   │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK 3 plans listed

Step 13: Filter plans by phase, state, and action

# Filter by phase
$ agents plan list --phase strategize

# Filter by state
$ agents plan list --state queued

# Filter by action
$ agents plan list --action local/security-audit

Output for --action local/security-audit:

                                     Plans
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ ID                         ┃ Name                                   ┃ Phase      ┃ State    ┃ Action                 ┃ Invaria… ┃ Projects           ┃ Updated            ┃ Elapsed       ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ 01KNKK0MKCDXGP8Z3PZ88S5GGZ │ local/security-audit-01knkk0m         │ strategize │ queued   │ local/security-audit   │ 1        │ local/my-webapp    │ 2026-04-07 09:05   │ 00:00:00      │
└────────────────────────────┴────────────────────────────────────────┴────────────┴──────────┴────────────────────────┴──────────┴────────────────────┴────────────────────┴───────────────┘
╭────────────────────────────────── Filters ───────────────────────────────────╮
│ Phase: (any)                                                                 │
│ State: (any)                                                                 │
│ Project: (any)                                                               │
│ Action: local/security-audit                                                 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Total: 1                                                                     │
│ Processing: 0                                                                │
│ Completed: 0                                                                 │
│ Errored: 0                                                                   │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK 1 plans listed

Step 14: Inspect a specific plan

$ agents plan status 01KNKJZ424C48388RWHW3KY5QZ

Output:

╭───────────────────────────── Plan Status ─────────────────────────────╮
│ ID: 01KNKJZ424C48388RWHW3KY5QZ                                        │
│ Name: local/architecture-review-01knkjz4                              │
│ Action: local/architecture-review                                     │
│ Phase: strategize                                                     │
│ Processing State: queued                                              │
│ Projects: local/my-webapp                                             │
│ Description:                                                          │
│   Analyzes the project structure, dependency graph, and code patterns │
│ to produce an architecture review report. Does not modify any files.  │
│ Strategy Actor: local/strategist                                      │
│ Execution Actor: local/executor                                       │
│ Definition of Done:                                                   │
│   Architecture review report generated covering:                      │
│ - Module dependency graph                                             │
│ - Layer boundary compliance                                           │
│ - Circular dependency detection                                       │
│ - Code duplication analysis                                           │
│ Automation Profile: manual (source: global)                           │
│ Terminal: no                                                          │
│ Created: 2026-04-07 09:04:23.620455                                   │
│ Updated: 2026-04-07 09:04:23.620456                                   │
╰───────────────────────────────────────────────────────────────────────╯

Step 15: Get plan status as JSON

$ agents plan status 01KNKJZ424C48388RWHW3KY5QZ --format json

Output:

{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "01KNKJZ424C48388RWHW3KY5QZ",
    "namespaced_name": "local/architecture-review-01knkjz4",
    "phase": "strategize",
    "processing_state": "queued",
    "state": "queued",
    "project_links": [
      {
        "project_name": "local/my-webapp"
      }
    ],
    "arguments": {},
    "automation_profile": "manual",
    "action_name": "local/architecture-review",
    "description": "Analyzes the project structure, dependency graph, and code patterns\nto produce an architecture review report. Does not modify any files.",
    "definition_of_done": "Architecture review report generated covering:\n- Module dependency graph\n- Layer boundary compliance\n- Circular dependency detection\n- Code duplication analysis",
    "strategy_actor": "local/strategist",
    "execution_actor": "local/executor",
    "estimation_actor": null,
    "invariant_actor": null,
    "created_at": "2026-04-07T09:04:23.620455",
    "updated_at": "2026-04-07T09:04:23.620456",
    "is_terminal": false
  },
  "timing": {
    "duration_ms": 0
  },
  "messages": [
    {
      "level": "ok",
      "text": "ok"
    }
  ]
}

Step 16: Cancel a plan

$ agents plan cancel 01KNKJZ44ES00VT8JTRKX1HEQA

Output:

✓ Plan cancelled: local/architecture-review-01knkjz4

Cancelled plans are terminal — they cannot be resumed. Use plan list to confirm the state change:

$ agents plan list --phase strategize

The cancelled plan will appear with state: cancelled in the list.

Scripting with JSON Output

Because all commands support --format json, you can integrate CleverAgents into shell scripts and CI pipelines:

# Get a plan's current phase
$ agents plan status <PLAN_ID> --format json | jq -r '.data.phase'
strategize

# Check if a plan is terminal
$ agents plan status <PLAN_ID> --format json | jq '.data.is_terminal'
false

# List all available actions as a name array
$ agents action list --format json | jq -r '.data[].namespaced_name'
local/architecture-review
local/data-pipeline
local/large-refactor
local/security-audit

# Count queued plans
$ agents plan list --state queued --format json | jq '.data | length'
3

# Get all plan IDs for a specific action
$ agents plan list --action local/security-audit --format json \
    | jq -r '.data[].plan_id'
01KNKK0MKCDXGP8Z3PZ88S5GGZ

# Check if any plans are in error state
$ agents plan list --format json | jq '.data[] | select(.state == "errored") | .plan_id'

Plan Lifecycle Reference

Phases

Phase Description
strategize AI creates an execution strategy (decisions tree)
execute AI executes the strategy, generating a ChangeSet
apply ChangeSet is written to disk

Processing States

State Description
queued Waiting to be processed
processing Currently being processed by an actor
complete Phase completed successfully
applied Changes written to disk (terminal)
cancelled Cancelled by user (terminal)
errored Failed with an error (recoverable via plan resume)

Action States

State Description
available Ready to use for creating plans
archived Soft-deleted; preserved for history but not usable

Complete Interaction Log

Click to see the full verified command sequence 
# 1. Register actions from YAML files
$ agents action create --config examples/actions/simple.yaml
# → Action Created: local/lint-check (available)

$ agents action create --config examples/actions/estimation-actor.yaml
# → Action Created: local/large-refactor (available)

$ agents action create --config examples/actions/invariant-heavy.yaml
# → Action Created: local/security-audit (available)

$ agents action create --config examples/actions/read-only.yaml
# → Action Created: local/architecture-review (available)

$ agents action create --config examples/actions/inputs-schema.yaml
# → Action Created: local/data-pipeline (available)

# 2. List all actions
$ agents action list
# → Table: 5 actions, all available

# 3. Filter by namespace
$ agents action list --namespace local
# → Table: 5 actions (all in local namespace)

# 4. Filter by regex
$ agents action list ".*audit.*"
# → Table: 1 action (local/security-audit)

# 5. Show action details
$ agents action show local/security-audit
# → Panel: full details including arguments

# 6. Get action as JSON
$ agents action show local/large-refactor --format json
# → JSON envelope with data.arguments array

# 7. Archive an action
$ agents action archive local/lint-check
# → ✓ Action archived: local/lint-check

# 8. List archived actions
$ agents action list --state archived
# → Table: 1 action (local/lint-check, state: archived)

# 9. Create a project
$ agents project create local/my-webapp --description "A sample web application project"
# → Panel: Project Created

# 10. Create a plan from an action
$ agents plan use local/architecture-review local/my-webapp
# → Panel: Plan Created, ID: 01KNKJZ424C48388RWHW3KY5QZ, phase: strategize

# 11. Create a plan with arguments and invariants
$ agents plan use local/security-audit local/my-webapp \
    --arg severity_threshold=high \
    --arg auto_fix=false \
    --invariant "Never modify production data"
# → Panel: Plan Created with arguments and invariants shown

# 12. List all plans
$ agents plan list
# → Table: 3 plans + Summary panel

# 13. Filter plans
$ agents plan list --phase strategize
$ agents plan list --state queued
$ agents plan list --action local/security-audit

# 14. Inspect a plan
$ agents plan status 01KNKJZ424C48388RWHW3KY5QZ
# → Panel: full plan details

# 15. Get plan as JSON
$ agents plan status 01KNKJZ424C48388RWHW3KY5QZ --format json
# → JSON envelope with full plan data

# 16. Cancel a plan
$ agents plan cancel 01KNKJZ44ES00VT8JTRKX1HEQA
# → ✓ Plan cancelled: local/architecture-review-01knkjz4

Key Takeaways

  • Actions are YAML templates — define them once, reuse across projects. The examples/actions/ directory has five ready-to-use examples.
  • Plans are runtime instances — agents plan use <action> <project> creates a plan with a ULID identifier used for all subsequent commands.
  • Plans start in strategize/queued — they need agents plan execute to drive LLM processing.
  • Arguments are typed — pass them with --arg name=value; they are validated against the action's argument definitions.
  • Invariants are hard constraints — add them with --invariant "text"; the AI must never violate them during execution.
  • All commands support --format json — use it for scripting, CI pipelines, and integration with jq.
  • --format json uses an envelope — the payload is always in .data; use jq '.data' to extract it.
  • Archived actions are preserved — use --state archived to see them.
  • Cancelled plans are terminal — they cannot be resumed.

Try It Yourself

# Register all example actions at once
for f in examples/actions/*.yaml; do
    agents action create --config "$f"
done

# Create a project and plan
agents project create local/my-project --description "My project"
agents plan use local/architecture-review local/my-project

# Get the plan ID and check its status
PLAN_ID=$(agents plan list --format json | jq -r '.data[0].plan_id')
agents plan status "$PLAN_ID"

# List only queued plans
agents plan list --state queued

# Script: count available actions
agents action list --format json | jq '.data | map(select(.state == "available")) | length'

Related Examples

  • See docs/showcase/cli-tools/output-format-flags.md for the JSON/YAML envelope format used by all commands
  • See docs/showcase/cli-tools/ for more CLI tool examples

This example was automatically generated and verified by the CleverAgents UAT system. Feature area: Action management and plan lifecycle | Test cycle: 1 | Generated: 2026-04-07

Reference in New Issue View Git Blame Copy Permalink