freemo
65988669a6
CI / coverage (push) Blocked by required conditions
CI / build (push) Waiting to run
CI / lint (push) Waiting to run
CI / typecheck (push) Waiting to run
CI / docker (push) Blocked by required conditions
CI / security (push) Waiting to run
CI / quality (push) Waiting to run
CI / unit_tests (push) Waiting to run
CI / integration_tests (push) Waiting to run
CI / lint (pull_request) Successful in 16s
CI / typecheck (pull_request) Successful in 26s
CI / security (pull_request) Successful in 22s
CI / quality (pull_request) Successful in 15s
CI / integration_tests (pull_request) Successful in 4m31s
CI / build (pull_request) Successful in 16s
CI / unit_tests (pull_request) Successful in 9m18s
CI / coverage (pull_request) Successful in 6m54s
CI / docker (pull_request) Successful in 39s
- plan use: accept positional PROJECT args, add --automation-profile, --invariant (repeatable), and actor override flags - lifecycle-list: add --state/--processing-state, --action filters, optional positional REGEX for name filtering, Action column in output - plan status: enhanced detail view with processing state, project links, arguments order, automation profile provenance, actor overrides, automation level, and full timestamps - Add docs/reference/plan_cli.md reference documentation - Add Behave feature (17 scenarios) with mock service steps - Add Robot smoke test (7 cases) with import-safe helper - Add ASV benchmarks for plan use/list/status commands
145 lines
4.9 KiB
Markdown
145 lines
4.9 KiB
Markdown
# Plan CLI Reference
|
|
|
|
The `agents plan` command group manages plans in the CleverAgents v3
|
|
plan lifecycle.
|
|
|
|
## Plan Use
|
|
|
|
```bash
|
|
agents plan use <ACTION> [PROJECT ...] [OPTIONS]
|
|
```
|
|
|
|
Create a plan from an action template. The first positional argument is
|
|
the **action name** (namespaced, e.g. `local/code-coverage`). All
|
|
subsequent positional arguments are **project names** the plan will
|
|
operate on. Projects can also be supplied via the repeatable
|
|
`--project` / `-p` option.
|
|
|
|
### Options
|
|
|
|
| Flag | Short | Description |
|
|
|-------------------------|-------|----------------------------------------------------------|
|
|
| `--project` | `-p` | Project name (repeatable) |
|
|
| `--arg` | `-a` | Argument value `name=value` (repeatable) |
|
|
| `--automation-profile` | | Automation profile name for this plan |
|
|
| `--invariant` | | Invariant constraint text (repeatable) |
|
|
| `--strategy-actor` | | Override the strategy actor |
|
|
| `--execution-actor` | | Override the execution actor |
|
|
| `--estimation-actor` | | Override the estimation actor |
|
|
| `--invariant-actor` | | Override the invariant reconciliation actor |
|
|
| `--automation-level` | | `manual`, `review_before_apply`, or `full_automation` |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Single project via positional arg
|
|
agents plan use local/code-coverage my-project --arg target_coverage=80
|
|
|
|
# Multiple projects via positional args
|
|
agents plan use local/lint proj-a proj-b
|
|
|
|
# Projects via --project option
|
|
agents plan use local/lint --project proj-a --project proj-b
|
|
|
|
# With invariants and actor overrides
|
|
agents plan use local/refactor proj-1 \
|
|
--invariant "No new warnings" \
|
|
--invariant "Keep backward compat" \
|
|
--strategy-actor openai/gpt-4 \
|
|
--execution-actor anthropic/claude-3
|
|
|
|
# With automation profile
|
|
agents plan use local/code-coverage proj-1 --automation-profile trusted
|
|
```
|
|
|
|
## Plan List (lifecycle-list)
|
|
|
|
```bash
|
|
agents plan lifecycle-list [REGEX] [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Flag | Short | Description |
|
|
|----------------------|-------|-----------------------------------------------------------|
|
|
| `--phase` | | Filter by phase (`strategize`, `execute`, `apply`, `applied`) |
|
|
| `--state` | | Filter by processing state (`queued`, `processing`, `errored`, `complete`, `cancelled`) |
|
|
| `--processing-state` | | Alias for `--state` |
|
|
| `--project` | `-p` | Filter by project name |
|
|
| `--action` | | Filter by action name |
|
|
|
|
### Positional Arguments
|
|
|
|
| Argument | Description |
|
|
|----------|------------------------------------------|
|
|
| `REGEX` | Optional regex pattern to filter names |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# List all plans
|
|
agents plan lifecycle-list
|
|
|
|
# Filter by phase
|
|
agents plan lifecycle-list --phase strategize
|
|
|
|
# Filter by processing state
|
|
agents plan lifecycle-list --state complete
|
|
|
|
# Combine filters
|
|
agents plan lifecycle-list --phase execute --project my-project --action local/lint
|
|
```
|
|
|
|
### Output Columns
|
|
|
|
| Column | Description |
|
|
|----------|--------------------------------------|
|
|
| ID | Truncated plan ULID |
|
|
| Name | Full namespaced plan name |
|
|
| Action | Source action name |
|
|
| Phase | Current lifecycle phase |
|
|
| State | Processing state |
|
|
| Projects | Linked project names |
|
|
| Created | Creation timestamp |
|
|
|
|
## Plan Status
|
|
|
|
```bash
|
|
agents plan status [PLAN_ID]
|
|
```
|
|
|
|
Without a plan ID, shows a summary table of all active plans.
|
|
With a plan ID, shows full details including:
|
|
|
|
- **Action**: source action name
|
|
- **Phase** and **Processing State**
|
|
- **Project links** with aliases and read-only flags
|
|
- **Arguments** (ordered)
|
|
- **Automation profile** with provenance tag
|
|
- **Actor overrides** (strategy, execution, estimation, invariant)
|
|
- **Timestamps** (created, updated, phase start/complete times)
|
|
|
|
## Plan Cancel
|
|
|
|
```bash
|
|
agents plan cancel <PLAN_ID> [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Flag | Short | Description |
|
|
|------------|-------|----------------------------|
|
|
| `--reason` | `-r` | Reason for cancellation |
|
|
|
|
### Example
|
|
|
|
```bash
|
|
agents plan cancel 01HXYZ... --reason "Requirements changed"
|
|
```
|
|
|
|
## Source Location
|
|
|
|
- CLI commands: `src/cleveragents/cli/commands/plan.py`
|
|
- Lifecycle service: `src/cleveragents/application/services/plan_lifecycle_service.py`
|
|
- Plan model: `src/cleveragents/domain/models/core/plan.py`
|