# 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*
