# 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 │ ▼ Action registered (state: available) │ ▼ agents plan use │ ▼ Plan created (phase: strategize, state: queued) │ ▼ agents plan execute ← drives LLM strategy + execution │ ▼ Plan (phase: execute, state: complete) │ ▼ agents plan apply ← 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: ```yaml # 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 ```bash $ 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 ```bash $ 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 ```bash $ 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 ```bash # 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 ```bash $ 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 ```bash $ agents action show local/large-refactor --format json ``` **Output:** ```json { "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) ```bash $ 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`: ```bash $ 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: ```bash $ 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 ```bash $ 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 ' 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`: ```bash $ 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 ' 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 ```bash $ 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 ```bash # 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 ```bash $ 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 ```bash $ agents plan status 01KNKJZ424C48388RWHW3KY5QZ --format json ``` **Output:** ```json { "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 ```bash $ 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: ```bash $ 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: ```bash # Get a plan's current phase $ agents plan status --format json | jq -r '.data.phase' strategize # Check if a plan is terminal $ agents plan status --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 ```bash # 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 ` 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 ```bash # 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*