freemo
f69224e7e9
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Failing after 15s
CI / quality (pull_request) Successful in 17s
CI / build (pull_request) Successful in 17s
CI / security (pull_request) Successful in 29s
CI / typecheck (pull_request) Successful in 31s
CI / coverage (pull_request) Has been skipped
CI / benchmark-regression (pull_request) Has been skipped
CI / integration_tests (pull_request) Successful in 3m44s
CI / unit_tests (pull_request) Successful in 7m4s
CI / docker (pull_request) Has been skipped
161 lines
4.9 KiB
Markdown
161 lines
4.9 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 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]
|
|
```
|