# Plan CLI Reference

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

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

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

# Projects via --project option
agents plan use local/lint --project proj-a --project proj-b

# With invariants and actor overrides
agents plan use local/refactor proj-1 \
  --invariant "No new warnings" \
  --invariant "Keep backward compat" \
  --strategy-actor openai/gpt-4 \
  --execution-actor anthropic/claude-3

# With automation profile
agents plan use local/code-coverage proj-1 --automation-profile trusted
```

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

### Positional Arguments

| Argument | Description                              |
|----------|------------------------------------------|
| `REGEX`  | Optional regex pattern to filter names   |

### Examples

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

# Filter by phase
agents plan lifecycle-list --phase strategize

# Filter by processing state
agents plan lifecycle-list --state complete

# Combine filters
agents plan lifecycle-list --phase execute --project my-project --action local/lint
```

### Output Columns

| Column   | Description                          |
|----------|--------------------------------------|
| ID       | Truncated plan ULID                  |
| Name     | Full namespaced plan name            |
| Action   | Source action name                    |
| Phase    | Current lifecycle phase              |
| State    | Processing state                     |
| Projects | Linked project names                 |
| Created  | Creation timestamp                   |

## Plan Status

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

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

- **Action**: source action name
- **Phase** and **Processing State**
- **Project links** with aliases and read-only flags
- **Arguments** (ordered)
- **Automation profile** with provenance tag
- **Actor overrides** (strategy, execution, estimation, invariant)
- **Timestamps** (created, updated, phase start/complete times)

## Plan Cancel

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

### Options

| Flag       | Short | Description                |
|------------|-------|----------------------------|
| `--reason` | `-r`  | Reason for cancellation    |

### Example

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

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