Luis Mendes
59be111e1d
Modified auto_progress() to complete the Apply phase immediately after transitioning from Execute to Apply, since Apply is a metadata transition with no LLM processing. This ensures `plan execute` drives the plan to the terminal `applied` state when the automation profile permits (ci, full-auto profiles with auto_apply < 1.0). Extracted `_complete_apply_if_queued()` helper that consolidates the Apply-completion pattern (start_apply + complete_apply) into a single method with error recovery (calls `fail_apply` on failure) and async-job guard (skips inline completion when async execution is enabled to avoid orphaning enqueued jobs). Used by `auto_progress()`, `lifecycle_apply_plan()`, and `try_auto_run()`. Added PlanLifecycleService.try_auto_run() that drives plans through all lifecycle phases (strategize → execute → apply) when automation-profile thresholds allow automatic progression. Each phase checks the profile's auto_* threshold before proceeding; a threshold of 1.0 stops the plan at that phase boundary for human approval. Fixed `lifecycle-apply` CLI leaving plans stuck in `apply/queued` without completing. The command now calls `_complete_apply_if_queued()` when the plan is in Apply/queued, driving it to the terminal `applied` state. Fixed stale RICH output in `lifecycle_apply_plan` that printed "Plan is now in Apply phase (queued)" after the plan had already reached terminal `applied` state; now branches on `plan.is_terminal`. Additional fixes: - SQLite UNIQUE constraint violation in LifecyclePlanRepository.update(): added session.flush() after clear() on child collections (project_links, arguments, invariants) before re-inserting rows - Added 'state' alias in _plan_spec_dict() JSON output for spec §Example 7 jq compatibility - Updated plan execute and lifecycle-apply reference documentation Refs: #753
9.1 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 lifecycle-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 lifecycle-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 lifecycle-list
List v3 lifecycle plans with optional filtering.
Synopsis
agents plan lifecycle-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 lifecycle-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 lifecycle-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