# Plan CLI Reference

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

> **Note:** The legacy commands (`tell`, `build`, `apply`, `new`,
> `current`, `list`, `cd`, `continue`) are deprecated and emit
> deprecation warnings.  Use the v3 lifecycle commands below instead.

## Plan Use

```bash
agents plan use <ACTION> [PROJECT ...] [OPTIONS]
```

Create a plan from an action template.  The first positional argument is
the **action name** (namespaced, e.g. `local/code-coverage`).  All
subsequent positional arguments are **project names** the plan will
operate on.  Projects can also be supplied via the repeatable
`--project` / `-p` option.

### Options

| Flag                    | Short | Description                                              |
|-------------------------|-------|----------------------------------------------------------|
| `--project`             | `-p`  | Project name (repeatable)                                |
| `--arg`                 | `-a`  | Argument value `name=value` (repeatable)                 |
| `--automation-profile`  |       | Automation profile name for this plan                    |
| `--invariant`           |       | Invariant constraint text (repeatable)                   |
| `--strategy-actor`      |       | Override the strategy actor                              |
| `--execution-actor`     |       | Override the execution actor                             |
| `--estimation-actor`    |       | Override the estimation actor                            |
| `--invariant-actor`     |       | Override the invariant reconciliation actor               |
| `--automation-level`    |       | `manual`, `review_before_apply`, or `full_automation`    |
| `--format`              | `-f`  | Output format: json, yaml, plain, table, rich (default: rich) |

### Examples

```bash
# Single project via positional arg
agents plan use local/code-coverage my-project --arg target_coverage=80

# Multiple projects via positional args
agents plan use local/lint proj-a proj-b

# JSON output
agents plan use local/lint proj-a --format json

# YAML output
agents plan use local/lint proj-a --format yaml
```

## Plan List (lifecycle-list)

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

### Options

| Flag                 | Short | Description                                               |
|----------------------|-------|-----------------------------------------------------------|
| `--phase`            |       | Filter by phase (`strategize`, `execute`, `apply`, `applied`) |
| `--state`            |       | Filter by processing state (`queued`, `processing`, `errored`, `complete`, `cancelled`) |
| `--processing-state` |       | Alias for `--state`                                       |
| `--project`          | `-p`  | Filter by project name                                    |
| `--action`           |       | Filter by action name                                     |
| `--format`           | `-f`  | Output format: json, yaml, plain, table, rich (default: rich) |

### Examples

```bash
# List all plans
agents plan lifecycle-list

# JSON output
agents plan lifecycle-list --format json

# YAML output
agents plan lifecycle-list --format yaml

# Filter by phase + JSON output
agents plan lifecycle-list --phase strategize --format json
```

### JSON/YAML Output Keys

| Key                  | Description                          |
|----------------------|--------------------------------------|
| `plan_id`            | Unique ULID identifier               |
| `namespaced_name`    | Full namespaced plan name            |
| `phase`              | Current lifecycle phase              |
| `processing_state`   | Processing state                     |
| `project_links`      | List of linked projects              |
| `arguments`          | Resolved argument values             |
| `automation_profile` | Automation profile name (or null)    |
| `action_name`        | Source action name                   |

## Plan Status

```bash
agents plan status [PLAN_ID] [OPTIONS]
```

### Options

| Flag       | Short | Description                      |
|------------|-------|----------------------------------|
| `--format` | `-f`  | Output format (default: rich)    |

Without a plan ID, shows a summary table of all active plans.
With a plan ID, shows full details.

### Examples

```bash
# Rich panel (default)
agents plan status 01HXYZ...

# JSON output
agents plan status 01HXYZ... --format json

# Plain text output
agents plan status 01HXYZ... --format plain
```

## Plan Execute

```bash
agents plan execute [PLAN_ID] [OPTIONS]
```

### Options

| Flag       | Short | Description                      |
|------------|-------|----------------------------------|
| `--format` | `-f`  | Output format (default: rich)    |

## Plan Lifecycle-Apply

```bash
agents plan lifecycle-apply [PLAN_ID] [OPTIONS]
```

### Options

| Flag       | Short | Description                      |
|------------|-------|----------------------------------|
| `--format` | `-f`  | Output format (default: rich)    |

## Plan Cancel

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

### Options

| Flag       | Short | Description                |
|------------|-------|----------------------------|
| `--reason` | `-r`  | Reason for cancellation    |
| `--format` | `-f`  | Output format (default: rich) |

### Example

```bash
agents plan cancel 01HXYZ... --reason "Requirements changed"
agents plan cancel 01HXYZ... --reason "Changed" --format json
```

## Deprecated Legacy Commands

The following commands are deprecated and will be removed in a future
release.  They emit deprecation warnings at runtime.

| Legacy Command   | Replacement                              |
|------------------|------------------------------------------|
| `plan tell`      | `plan use <action> [project]`            |
| `plan build`     | `plan execute [plan_id]`                 |
| `plan apply`     | `plan lifecycle-apply [plan_id]`         |
| `plan new`       | `plan use <action> [project]`            |
| `plan current`   | `plan status [plan_id]`                  |
| `plan list`      | `plan lifecycle-list`                    |
| `plan cd`        | `plan status <plan_id>`                  |
| `plan continue`  | `plan use <action> [project]`            |

## Source Location

- CLI commands: `src/cleveragents/cli/commands/plan.py`
- Lifecycle service: `src/cleveragents/application/services/plan_lifecycle_service.py`
- Plan model: `src/cleveragents/domain/models/core/plan.py`
- Formatting helpers: `src/cleveragents/cli/formatting.py`