CoreRasurae
ff2d824f17
CI / benchmark-publish (pull_request) Has been skipped
CI / build (pull_request) Successful in 16s
CI / lint (pull_request) Successful in 19s
CI / quality (pull_request) Successful in 33s
CI / typecheck (pull_request) Successful in 43s
CI / security (pull_request) Successful in 50s
CI / unit_tests (pull_request) Successful in 3m11s
CI / integration_tests (pull_request) Successful in 3m37s
CI / e2e_tests (pull_request) Successful in 3m52s
CI / docker (pull_request) Successful in 56s
CI / coverage (pull_request) Successful in 5m57s
CI / build (push) Successful in 14s
CI / lint (push) Successful in 20s
CI / quality (push) Successful in 25s
CI / typecheck (push) Successful in 49s
CI / benchmark-regression (push) Has been skipped
CI / security (push) Successful in 52s
CI / unit_tests (push) Successful in 3m18s
CI / integration_tests (push) Successful in 3m31s
CI / docker (push) Successful in 55s
CI / e2e_tests (push) Successful in 4m42s
CI / coverage (push) Successful in 6m0s
CI / benchmark-publish (push) Successful in 20m10s
CI / benchmark-regression (pull_request) Successful in 37m16s
_get_plan_executor() created a second PlanLifecycleService Factory instance with its own in-memory _plans cache. After the executor's run_strategize() advanced the plan to execute/queued (via auto_progress), the CLI handler's separate service instance returned stale strategize/queued state from its cache, causing spurious "Plan is not in an executable state" errors. Fix: _get_plan_executor() now accepts an optional lifecycle_service parameter; the plan execute handler passes its own service instance so both share the same cache. Also addressed review feedback: - Improved type safety: lifecycle_service parameter typed as PlanLifecycleService | None instead of Any | None. - Added BDD regression test verifying the lifecycle service is shared between the CLI handler and the executor. - Updated reference documentation to reflect the type annotation change. ISSUES CLOSED: #1026
253 lines
7.7 KiB
Markdown
253 lines
7.7 KiB
Markdown
# 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` | Transition to Execute phase |
|
|
| `agents plan lifecycle-apply` | Transition to Apply phase |
|
|
| `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 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 from Execute to Apply phase.
|
|
|
|
```bash
|
|
agents plan lifecycle-apply [PLAN_ID] [--format FORMAT]
|
|
```
|
|
|
|
## `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
|
|
```
|