freemo
48cff5cfe0
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>
9.0 KiB
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
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
# 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
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
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.
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
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
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.
agents plan cancel PLAN_ID [--reason REASON] [--format FORMAT]
agents plan diff
Show ChangeSet as unified diff for a plan.
agents plan diff PLAN_ID [--correction ID] [--format FORMAT]
agents plan artifacts
Show plan artifacts including ChangeSet ID and sandbox references.
agents plan artifacts PLAN_ID [--format FORMAT]
agents plan explain
Explain a single decision in the plan decision tree.
Synopsis
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
# 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
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
# 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