Jeff (CTO)
d98666651f
- Enforce config-only 'action create --config <file>' (remove legacy inline flags: --name, --strategy-actor, --execution-actor, --definition-of-done, --arg) - Load config via ActionConfigSchema.from_yaml_file() then Action.from_config() with clear validation error surfacing - Remove 'action available' subcommand (no draft state; actions are available by default) - Add REGEX positional arg to 'action list' for name filtering - Add Short Name and Definition of Done summary to all CLI outputs - Add 'action list --namespace/-n' and '--state/-s' filters - Update existing tests to match new config-only create flow - Add features/action_cli_spec_alignment.feature (19 scenarios) - Add robot/action_cli_spec.robot smoke tests - Add benchmarks/action_cli_bench.py ASV benchmarks - Add docs/reference/action_cli.md
4.3 KiB
Action CLI Reference
The agents action command group manages actions (reusable plan templates)
in the CleverAgents v3 plan lifecycle.
Config-Only Create
Actions are created exclusively via a YAML configuration file:
agents action create --config ./actions/code-coverage.yaml
Legacy inline flags (--name, --strategy-actor, --execution-actor,
--definition-of-done, --arg) are not supported and will be
rejected with an error.
YAML Configuration File
The configuration file is validated against ActionConfigSchema and must
include the following required fields:
name: local/code-coverage
description: Increase code coverage
strategy_actor: openai/gpt-4
execution_actor: openai/gpt-4
definition_of_done: |
Line coverage reaches the target percentage
for all modules under src/.
Optional fields include: long_description, reusable, read_only,
arguments, invariants, automation_profile, state, tags,
estimation_actor, review_actor, apply_actor, invariant_actor.
See docs/reference/action_model.md for the full schema reference.
Error Handling
| Error | Cause |
|---|---|
Config file error |
File not found or not readable |
Schema validation error |
YAML does not match ActionConfigSchema |
Config validation error |
YAML parses but has invalid content |
Validation Error |
Business rule violation from lifecycle service |
Error |
General service or infrastructure error |
List Actions
agents action list [OPTIONS] [REGEX]
Options
| Flag | Short | Description |
|---|---|---|
--namespace |
-n |
Filter by namespace |
--state |
-s |
Filter by state (available, archived) |
Positional Arguments
| Argument | Description |
|---|---|
REGEX |
Optional regex pattern to filter action names |
Examples
# List all actions
agents action list
# Filter by namespace
agents action list --namespace local
# Filter by state
agents action list --state available
# Filter by name pattern
agents action list "code-.*"
# Combine filters
agents action list --namespace local --state available "lint"
Output Columns
| Column | Description |
|---|---|
| Namespaced Name | Full namespace/name identifier |
| Short Name | Just the name portion |
| State | available or archived |
| Strategy Actor | Actor for the Strategize phase |
| Execution Actor | Actor for the Execute phase |
| Definition of Done | Truncated summary (first 40 chars) |
| Reusable | ✓ if the action persists after use |
| Created | Creation timestamp |
Show Action
agents action show <NAME>
Displays full details for a single action identified by its namespaced
name (e.g., local/code-coverage).
Output Fields
- Namespaced Name: Full identifier
- Short Name: Name portion only
- Description: Short description
- State: Current state
- Strategy Actor: Strategize phase actor
- Execution Actor: Execute phase actor
- Reusable / Read Only: Behavior flags
- Definition of Done: Full completion criteria (truncated at 120 chars in panel)
- Arguments: Typed argument definitions
- Created: Timestamp
Archive Action
agents action archive <NAME>
Soft-deletes an action by transitioning it to archived state.
Archived actions cannot be used for new plans but are preserved
for history.
Removed Commands
action available
The available subcommand has been removed. Actions are created
directly in available state (there is no draft state). To
restore an archived action, recreate it from a YAML config file.
Source Location
- CLI commands:
src/cleveragents/cli/commands/action.py - Config schema:
src/cleveragents/action/schema.py - Domain model:
src/cleveragents/domain/models/core/action.py