cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity
Files
0d5d9cf0516b4368564b1999422f60a82a6002e8
cleveragents-core/docs/reference/plan_cli.md
T
freemo 48cff5cfe0
CI / build (push) Successful in 18s
Details
CI / lint (push) Failing after 31s
Details
CI / helm (push) Successful in 33s
Details
CI / typecheck (push) Successful in 50s
Details
CI / security (push) Failing after 51s
Details
CI / coverage (push) Has been skipped
Details
CI / benchmark-regression (push) Has been skipped
Details
CI / unit_tests (push) Failing after 1m50s
Details
CI / docker (push) Has been skipped
Details
CI / quality (push) Successful in 3m43s
Details
CI / integration_tests (push) Has been cancelled
Details
CI / e2e_tests (push) Has been cancelled
Details
CI / benchmark-publish (push) Has been cancelled
Details
CI / status-check (push) Has been cancelled
Details
refactor(cli): rename plan lifecycle-list and lifecycle-apply to match specification 
Renames `plan lifecycle-list` to `plan list` and `plan lifecycle-apply` to `plan apply` to align with the specification's canonical command names. Removes legacy V2 plan commands that occupied those names.

- Renamed CLI command registrations from lifecycle-list/lifecycle-apply to list/apply
- Removed legacy V2 apply and list commands (~200 lines)
- Updated apply shortcut in main.py to delegate to v3 lifecycle
- Added defensive null check for plan existence in apply command
- Updated 63+ test, doc, and benchmark files for consistency

Closes #881

Co-authored-by: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Co-committed-by: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
2026-04-02 19:09:04 +00:00

282 lines
9.0 KiB
Markdown
Raw Blame History

# Plan CLI Reference
The `agents plan` command group manages plans in the CleverAgents v3 plan lifecycle.
## 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 |
### Output Fields
Includes **Profile** and **Invariants** columns in all output formats
when present on the plan.
## `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
```
Reference in New Issue View Git Blame Copy Permalink