849 lines
40 KiB
Markdown
849 lines
40 KiB
Markdown
# 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:
|
|
|
|
```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 <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`:
|
|
|
|
```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 <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
|
|
|
|
```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 <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
|
|
|
|
<details>
|
|
<summary>Click to see the full verified command sequence</summary>
|
|
|
|
```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
|
|
```
|
|
</details>
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```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*
|