cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity
Files
4e64544aaee15f52f2f24db6272fb8200bbacc03
cleveragents-core/docs/reference/plan_cli.md
T
Luis Mendes 59be111e1d fix(plan): complete apply phase inline in auto_progress and lifecycle-apply CLI 
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
2026-03-26 17:35:24 +00:00

282 lines
9.1 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 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
```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 lifecycle-list`
List v3 lifecycle plans with optional filtering.
### Synopsis
```bash
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.
```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 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
```bash
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.
```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