khyari hamza
f66cb8d68e
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 16s
CI / build (pull_request) Successful in 16s
CI / quality (pull_request) Successful in 18s
CI / security (pull_request) Successful in 31s
CI / typecheck (pull_request) Successful in 33s
CI / unit_tests (pull_request) Successful in 1m44s
CI / docker (pull_request) Successful in 44s
CI / integration_tests (pull_request) Successful in 2m53s
CI / coverage (pull_request) Successful in 3m51s
CI / benchmark-regression (pull_request) Successful in 24m19s
- Remove global _PLAN_ID; generate per-step plan IDs on context (#8) - Fix sham orphan test; build children_map from all decisions (#1) - Delete dead constants; use _PATCH_RESUME_SVC_MOD in resume steps (#2) - Remove dead _resolve_active_plan_id mock from _invoke_correct (#5) - Make --mode/--guidance required Typer options (#3) - Show alternatives by default; remove --show-alternatives flag (#4) - Strengthen weak assertions on depth-limit and show-superseded (#6) - Add negative assertions for error type conflation (#7) ISSUES CLOSED: #174
237 lines
7.0 KiB
Markdown
237 lines
7.0 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`
|
|
|
|
Transition a plan from Strategize to Execute phase.
|
|
|
|
```bash
|
|
agents plan execute [PLAN_ID] [--format FORMAT]
|
|
```
|
|
|
|
## `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
|
|
```
|