cleveragents-core/docs/reference/plan_cli.md

# Plan CLI Reference

The `agents plan` command group manages plans in the CleverAgents v3 plan lifecycle.

> **Note (v3.8.0+):** Mixing legacy plan commands with v3 plan workflows in the same
> session is no longer permitted. If you attempt to use legacy plan commands alongside
> v3 plan commands, the CLI will detect the conflict and surface a clear error message
> with migration guidance. Migrate fully to the v3 plan workflow before using `agents plan`.

## Commands

| Command                        | Description                             |
|--------------------------------|-----------------------------------------|
| `agents plan use`              | Create plan from action + project(s)    |
| `agents plan list`             | List plans with optional filters        |
| `agents plan status`           | Show plan status / details              |
| `agents plan execute`          | Run Strategize + Execute (auto-apply if profile permits) |
| `agents plan apply`            | Transition to Apply and complete it     |
| `agents plan cancel`           | Cancel a non-terminal plan              |
| `agents plan diff`             | Show ChangeSet as unified diff          |
| `agents plan artifacts`        | Show ChangeSet ID, sandbox refs, summary|
| `agents plan explain`          | Explain a single decision               |
| `agents plan tree`             | Display decision tree for a plan        |

## `agents plan use`

Create a plan from an action template and one or more projects.

### Synopsis

```bash
agents plan use <ACTION_NAME> [PROJECTS...] [OPTIONS]
```

### Options

| Flag                    | Description                                           |
|-------------------------|-------------------------------------------------------|
| `--project`, `-p`      | Project name (repeatable for multiple projects)       |
| `--arg`, `-a`          | Argument value in `name=value` format (repeatable)    |
| `--automation-profile`  | Automation profile name (e.g., `trusted`, `manual`)   |
| `--invariant`          | Invariant constraint text (repeatable)                |
| `--strategy-actor`     | Override strategy actor (`namespace/name` format)     |
| `--execution-actor`    | Override execution actor (`namespace/name` format)    |
| `--estimation-actor`   | Override estimation actor (`namespace/name` format)   |
| `--invariant-actor`    | Override invariant reconciliation actor               |
| `--format`, `-f`       | Output format: json, yaml, plain, table, rich         |

### Actor Override Validation

All actor override flags require **namespaced format**: `namespace/name`
(e.g., `openai/gpt-4`, `anthropic/claude-3`). Invalid formats are
rejected with a descriptive error.

### Examples

```bash
# Basic usage with one project
agents plan use local/code-coverage my-project --arg target_coverage=80

# Multiple projects
agents plan use local/lint proj-1 proj-2

# With automation profile and invariants
agents plan use local/refactor my-project \
  --automation-profile trusted \
  --invariant "No new warnings" \
  --invariant "Maintain backward compatibility"

# With actor overrides
agents plan use local/code-coverage my-project \
  --strategy-actor openai/gpt-4 \
  --execution-actor anthropic/claude-3 \
  --estimation-actor openai/gpt-4

# JSON output
agents plan use local/lint my-project --format json
```

## `agents plan status`

Show status of one or all v3 lifecycle plans.

### Synopsis

```bash
agents plan status [PLAN_ID] [--format FORMAT]
```

When called without a plan ID, displays a summary table of all active
plans including automation profile and invariant count columns.

### Output Fields

- **ID**: Truncated plan ULID
- **Name**: Namespaced plan name
- **Phase**: Current lifecycle phase
- **State**: Processing state
- **Profile**: Automation profile name (if set)
- **Invariants**: Count of attached invariants
- **Terminal**: Whether the plan is in a terminal state

## `agents plan list`

List v3 lifecycle plans with optional filtering.

### Synopsis

```bash
agents plan list [REGEX] [OPTIONS]
```

### Options

| Flag                    | Description                                      |
|-------------------------|--------------------------------------------------|
| `--phase`              | Filter by phase (strategize, execute, apply)      |
| `--state`              | Filter by processing state                        |
| `--processing-state`   | Alias for `--state`                               |
| `--project`, `-p`     | Filter by project name                            |
| `--action`             | Filter by action name                             |
| `--format`, `-f`      | Output format                                     |

### Rich Output

The `rich` format renders a **Plans** table with columns:

| Column | Description |
|--------|-------------|
| ID | Truncated plan ULID (8 chars) |
| Phase | Current lifecycle phase |
| State | Processing state |
| Action | Action name |
| Project | First linked project name (or `(none)`) |
| Elapsed | Wall-clock time since plan creation (`HH:MM:SS`) |

After the table:

- **Filters** panel — shown only when at least one filter (`--phase`, `--state`,
  `--project`, `--action`) is active. Lists the active filter values.
- **Summary** panel — total plans, processing count, completed count, and errored count.

Followed by a `✓ OK N plan(s) listed` success message.

## `agents plan execute`

Run the current plan phase synchronously.  Detects the plan's current
phase and processes it inline:

- **Strategize/queued** — runs the strategize phase to completion, then
  auto-progresses to Execute if the automation profile permits.
- **Strategize/complete** — transitions to Execute and runs it.
- **Execute/queued** — runs the execute phase to completion.

When the automation profile's `auto_apply` threshold is met (< 1.0),
the execute command also drives the plan through the Apply phase to
the terminal `applied` state.  This means `plan execute` with a
`ci` or `full-auto` profile completes the full lifecycle in a single
invocation: Strategize → Execute → Apply.

When no plan ID is given, auto-selects the single eligible plan.

```bash
agents plan execute [PLAN_ID] [--format FORMAT]
```

### Internal Wiring

The CLI handler shares a single `PlanLifecycleService` instance between
the command logic and the `PlanExecutor` to avoid stale in-memory cache
reads after phase transitions.  See
[CLI Executor Wiring](plan_execute.md#cli-executor-wiring-_get_plan_executor)
for details.

## `agents plan apply`

Transition a plan to Apply phase and complete it. Because Apply is a
destructive operation (it merges sandbox changesets into real project
resources), a confirmation prompt is displayed by default. Pass
`--yes` / `-y` to skip the prompt in scripts or CI pipelines.

When the plan is in Execute/complete, transitions to Apply. When the
plan is in Apply/queued (e.g. auto-progressed by `plan execute`),
completes the apply processing, driving the plan to the terminal
`applied` state. Apply is a metadata transition (no LLM call).

### Synopsis

```bash
agents plan apply [--yes|-y] [PLAN_ID] [--format FORMAT]
```

### Options

| Flag                    | Description                                           |
|-------------------------|-------------------------------------------------------|
| `--yes`, `-y`          | Skip the confirmation prompt and apply immediately    |
| `--format`, `-f`       | Output format: json, yaml, plain, table, rich         |

### Arguments

| Argument   | Description                                                    |
|------------|----------------------------------------------------------------|
| `PLAN_ID`  | Plan ID to apply (optional; auto-selects if only one eligible) |

## `agents plan cancel`

Cancel a non-terminal plan.

```bash
agents plan cancel PLAN_ID [--reason REASON] [--format FORMAT]
```

## `agents plan diff`

Show ChangeSet as unified diff for a plan.

```bash
agents plan diff PLAN_ID [--correction ID] [--format FORMAT]
```

## `agents plan artifacts`

Show plan artifacts including ChangeSet ID and sandbox references.

```bash
agents plan artifacts PLAN_ID [--format FORMAT]
```

## `agents plan explain`

Explain a single decision in the plan decision tree.

### Synopsis

```bash
agents plan explain <DECISION_ID> [OPTIONS]
```

### Options

| Flag                    | Description                                      |
|-------------------------|--------------------------------------------------|
| `--format`, `-f`       | Output format: json, yaml, plain, table, rich     |
| `--show-context`       | Include context snapshot details                  |
| `--show-reasoning`     | Include rationale and actor reasoning             |

Alternatives considered are always included in the output.

### Examples

```bash
# Default rich output
agents plan explain 01HXYZ1234567890ABCDEFGH

# JSON with full context
agents plan explain 01HXYZ1234567890ABCDEFGH --format json --show-context

# Show reasoning
agents plan explain 01HXYZ1234567890ABCDEFGH --show-reasoning

# YAML output with all details
agents plan explain 01HXYZ1234567890ABCDEFGH --format yaml \
  --show-context --show-reasoning
```

## `agents plan tree`

Display the decision tree for a plan.

### Synopsis

```bash
agents plan tree <PLAN_ID> [OPTIONS]
```

### Options

| Flag                    | Description                                      |
|-------------------------|--------------------------------------------------|
| `--format`, `-f`       | Output format: json, yaml, plain, table, rich     |
| `--show-superseded`    | Include superseded decisions in the tree          |
| `--depth`              | Maximum tree depth (0 = unlimited, default: 0)    |

### Examples

```bash
# Default rich tree view
agents plan tree 01HXYZ1234567890ABCDEFGH

# Table format
agents plan tree 01HXYZ1234567890ABCDEFGH --format table

# Include superseded decisions
agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded

# Limit depth to 2 levels
agents plan tree 01HXYZ1234567890ABCDEFGH --depth 2

# JSON output for scripting
agents plan tree 01HXYZ1234567890ABCDEFGH --format json
```