@@ -0,0 +1,618 @@
# `cleveragents.action` — Action Configuration Schema API
The `action` package provides the YAML configuration schema, validation
pipeline, and loader for CleverAgents **actions ** — reusable plan templates
that define how a task is strategized, executed, reviewed, and completed.
See [`docs/schema/action.schema.yaml` ](../../schema/action.schema.yaml ) for
the formal schema definition and
[`docs/reference/action_cli.md` ](../reference/action_cli.md ) for the
companion CLI reference.
---
## Overview
Actions are the primary unit of reusable work in CleverAgents. Each action
is defined by a YAML configuration file that specifies:
- **Identity** — a namespaced name, description, and optional long description.
- **Lifecycle actors** — which actors handle each phase (Strategize, Execute,
Estimate, Review, Apply, Invariant reconciliation).
- **Completion criteria** — a testable definition of done.
- **Behaviour flags** — whether the action is reusable and/or read-only.
- **Arguments** — typed, validated parameters supplied at plan-use time.
- **Invariants** — constraints propagated as plan-level invariants.
- **Automation profile** — default profile for derived plans.
- **Inputs schema** — optional JSON Schema for advanced input validation.
Actions are created exclusively via YAML files:
``` bash
agents action create --config action.yaml
```
---
## `ActionConfigSchema`
``` python
from cleveragents . action . schema import ActionConfigSchema
```
Pydantic model representing a fully parsed and validated action YAML file.
Instances are created via the factory class methods below — never
instantiated directly.
### Factory Methods
#### `ActionConfigSchema.from_yaml(yaml_string)`
Parse and validate a raw YAML string.
``` python
config = ActionConfigSchema . from_yaml ( yaml_string )
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `yaml_string` | `str` | Raw YAML content. Must be a non-empty mapping. |
**Returns: ** `ActionConfigSchema`
**Raises: **
| Exception | Condition |
|-----------|-----------|
| `ValueError` | YAML string is `None` , empty, or not a mapping. |
| `pydantic.ValidationError` | One or more fields fail schema validation. |
---
#### `ActionConfigSchema.from_yaml_file(path)`
Load and validate an action YAML file from disk.
``` python
config = ActionConfigSchema . from_yaml_file ( Path ( " examples/actions/simple.yaml " ) )
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `str \| Path` | Path to the YAML file. |
**Returns: ** `ActionConfigSchema`
**Raises: **
| Exception | Condition |
|-----------|-----------|
| `FileNotFoundError` | File does not exist at the given path. |
| `ValueError` | Path is `None` , points to a directory, or content is invalid. |
| `pydantic.ValidationError` | One or more fields fail schema validation. |
---
### Pre-validation Processing
Before Pydantic validation runs, the loader applies three normalisation steps
in order:
1. **camelCase → snake_case key normalisation ** — legacy camelCase keys (e.g.
`strategyActor` ) are silently converted to their snake_case equivalents and
a `WARNING` is emitted via the `cleveragents.action.schema` logger.
2. * * `${ENV_VAR}` interpolation** — any `${VAR}` placeholder in a string value
is replaced with the corresponding environment variable. Missing variables
are left as-is (no error); resolution is deferred to runtime.
3. **Invariant normalisation ** — invariant strings are trimmed, blank entries
are dropped, and duplicates are removed (order-preserving).
---
## Schema Reference
### Identity Fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `schema_version` | `str` | No | `"1"` | Schema version for forward compatibility. |
| `name` | `str` | **Yes ** | — | Namespaced action name: `namespace/name` . Only lowercase alphanumeric, hyphens, and underscores. |
| `description` | `str` | **Yes ** | — | Short, one-line description of the action. |
| `long_description` | `str \| None` | No | `None` | Detailed multi-line description. |
#### `name` format
Names must match `^[a-z0-9][a-z0-9_-]*/[a-z0-9][a-z0-9_-]*$` .
``` yaml
name : local/lint-check # valid
name : myorg/security-audit # valid
name : LintCheck # invalid — missing namespace
name : local/Lint Check # invalid — spaces not allowed
```
---
### Lifecycle Actor Fields
All actor references must follow the same `namespace/name` format as `name` .
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `strategy_actor` | `str` | **Yes ** | — | Actor for the **Strategize ** phase. |
| `execution_actor` | `str` | **Yes ** | — | Actor for the **Execute ** phase. |
| `estimation_actor` | `str \| None` | No | `None` | Actor for pre-execution cost/risk estimation. |
| `review_actor` | `str \| None` | No | `None` | Actor for reviewing execution results. |
| `apply_actor` | `str \| None` | No | `None` | Actor for the **Apply ** phase. |
| `invariant_actor` | `str \| None` | No | `None` | Actor for reconciling conflicting invariants. |
!!! note "camelCase aliases"
The loader accepts legacy camelCase keys for all actor fields and converts
them automatically. See the [Key Normalisation ](#key-normalisation ) table.
---
### Completion Criteria
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `definition_of_done` | `str` | **Yes ** | — | Testable criteria defining when the action's work is complete. Must be non-empty. |
---
### Behaviour Fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `reusable` | `bool` | No | `true` | If `false` , the action is archived after its first use. |
| `read_only` | `bool` | No | `false` | Restricts the action to read-only tool operations. |
| `state` | `str` | No | `"available"` | Lifecycle state: `available` or `archived` . `draft` is an internal-only state and is not valid in YAML configs. |
---
### `arguments`
An optional list of typed parameters that users supply at plan-use time via
`agents plan use --arg name=value` .
``` yaml
arguments :
- name : target_coverage
type : integer
required : true
description : "Target line coverage percentage"
min_value : 0
max_value : 100
- name : report_format
type : string
required : false
default : "text"
validation_pattern : "^(text|json|html)$"
```
#### `ActionArgumentSchema` fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | `str` | **Yes ** | — | Argument name. 1– `--arg name=value` . |
| `type` | `str` | No | `"string"` | Data type: `string` , `integer` , `float` , `boolean` , or `list` . |
| `required` | `bool` | No | `false` | Whether the argument must be provided. |
| `description` | `str` | No | `""` | Human-readable description shown in help text. Max 500 characters. |
| `default` | `str \| int \| float \| bool \| list[str] \| None` | No | `None` | Default value when the argument is not provided. |
| `validation_pattern` | `str \| None` | No | `None` | Regex pattern for validating `string` arguments. |
| `min_value` | `float \| None` | No | `None` | Minimum value for `integer` or `float` arguments. |
| `max_value` | `float \| None` | No | `None` | Maximum value for `integer` or `float` arguments. |
Extra fields on an argument object are **forbidden ** and will raise a
`ValidationError` .
---
### `automation_profile`
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `automation_profile` | `str \| None` | No | `None` | Default automation profile for plans derived from this action (e.g. `trusted` , `supervised` , `local/cautious` ). |
---
### `invariants`
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `invariants` | `list[str]` | No | `[]` | Constraints propagated as plan-level invariants when the action is used. Strings are trimmed, blanks dropped, and duplicates removed. |
``` yaml
invariants :
- "All existing tests must continue to pass"
- "Public API signatures must not change without deprecation"
```
---
### `inputs_schema`
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `inputs_schema` | `dict[str, Any] \| None` | No | `None` | Optional JSON Schema object for advanced input validation beyond basic argument types. |
Use `inputs_schema` when argument types alone are insufficient — for example,
to validate nested objects or enforce enumerated values on complex structures.
``` yaml
inputs_schema :
type : object
properties :
stages :
type : array
items :
type : object
required : [ name, transform]
properties :
name :
type : string
transform :
type : string
output_format :
type : string
enum : [ csv, json, parquet]
required :
- stages
```
---
### Key Normalisation
The loader accepts legacy camelCase keys and converts them to snake_case.
A `WARNING` is logged for each converted key.
| camelCase (deprecated) | snake_case (canonical) |
|------------------------|------------------------|
| `strategyActor` | `strategy_actor` |
| `executionActor` | `execution_actor` |
| `estimationActor` | `estimation_actor` |
| `reviewActor` | `review_actor` |
| `applyActor` | `apply_actor` |
| `invariantActor` | `invariant_actor` |
| `definitionOfDone` | `definition_of_done` |
| `longDescription` | `long_description` |
| `readOnly` | `read_only` |
| `automationProfile` | `automation_profile` |
| `inputsSchema` | `inputs_schema` |
| `validationPattern` | `validation_pattern` |
| `minValue` | `min_value` |
| `maxValue` | `max_value` |
| `schemaVersion` | `schema_version` |
---
## Complete Schema at a Glance
``` yaml
# Required fields only
name : namespace/action-name # required — namespace/name format
description : "Short description" # required
strategy_actor : namespace/actor-name # required — namespace/name format
execution_actor : namespace/actor-name # required — namespace/name format
definition_of_done : | # required — non-empty
Measurable completion criteria.
# Optional fields (shown with defaults)
schema_version : "1"
long_description : null
estimation_actor : null
review_actor : null
apply_actor : null
invariant_actor : null
reusable : true
read_only : false
state : available
automation_profile : null
arguments : [ ]
invariants : [ ]
inputs_schema : null
```
Extra top-level keys are **forbidden ** and will raise a `ValidationError` .
---
## Examples
### Minimal Action
The smallest valid action — only required fields:
``` yaml
# examples/actions/simple.yaml
name : local/lint-check
description : "Run linting checks on the project"
strategy_actor : local/strategist
execution_actor : local/executor
definition_of_done : |
All linting checks pass with zero errors.
reusable : true
read_only : true
```
---
### Action with Estimation and Review Actors
Adds optional `estimation_actor` and `review_actor` , typed `arguments` , an
`automation_profile` , and `invariants` :
``` yaml
# examples/actions/estimation-actor.yaml
name : local/large-refactor
description : "Large-scale code refactoring with cost estimation"
long_description : |
Performs a large-scale refactoring of a codebase module. An estimation
actor runs after Strategize to predict cost, risk, and duration before
execution proceeds.
strategy_actor : local/strategist
execution_actor : local/executor
estimation_actor : local/estimator
review_actor : local/reviewer
definition_of_done : |
Refactoring complete. All tests pass. No regressions introduced.
Code review approved by the review actor.
reusable : true
read_only : false
arguments :
- name : target_module
type : string
required : true
description : "Module path to refactor"
- name : max_files_changed
type : integer
required : false
description : "Maximum number of files to modify"
default : 50
min_value : 1
max_value : 500
automation_profile : trusted
invariants :
- "All existing tests must continue to pass"
- "Public API signatures must not change without deprecation"
```
---
### Read-Only Investigation Action
Suitable for audits and architecture reviews that must not modify any files:
``` yaml
# examples/actions/read-only.yaml
name : local/architecture-review
description : "Review project architecture and produce a report"
long_description : |
Analyzes the project structure, dependency graph, and code patterns
to produce an architecture review report. Does not modify any files.
strategy_actor : local/strategist
execution_actor : local/executor
definition_of_done : |
Architecture review report generated covering:
- Module dependency graph
- Layer boundary compliance
- Circular dependency detection
- Code duplication analysis
reusable : true
read_only : true
state : available
```
---
### Action with `inputs_schema`
Uses `inputs_schema` for complex nested validation beyond basic argument types:
``` yaml
# examples/actions/inputs-schema.yaml
name : local/data-pipeline
description : "Build and validate a data processing pipeline"
strategy_actor : local/strategist
execution_actor : local/executor
definition_of_done : |
Pipeline runs end-to-end successfully. All stages produce valid
output. Data quality checks pass on final output.
arguments :
- name : pipeline_name
type : string
required : true
description : "Name of the pipeline to build"
- name : dry_run
type : boolean
required : false
description : "Run in dry-run mode without writing output"
default : false
inputs_schema :
type : object
properties :
stages :
type : array
items :
type : object
properties :
name :
type : string
transform :
type : string
required : [ name, transform]
output_format :
type : string
enum : [ csv, json, parquet]
required :
- stages
```
---
### Action with Multiple Invariants and `invariant_actor`
Demonstrates `invariant_actor` , `validation_pattern` on a string argument,
and a rich invariant list:
``` yaml
# examples/actions/invariant-heavy.yaml
name : local/security-audit
description : "Comprehensive security audit of a project"
strategy_actor : local/security-strategist
execution_actor : local/security-scanner
invariant_actor : local/invariant-resolver
definition_of_done : |
All critical and high severity findings have been identified.
A complete security report has been generated with severity
classifications and remediation steps for each finding.
arguments :
- name : severity_threshold
type : string
required : false
description : "Minimum severity to include in report"
default : "low"
validation_pattern : "^(critical|high|medium|low|informational)$"
- name : auto_fix
type : boolean
required : false
description : "Automatically create fix plans for critical findings"
default : false
automation_profile : supervised
invariants :
- "Never modify production database schemas during audit"
- "Never execute discovered exploit code against live systems"
- "All findings must include reproducible steps"
- "Secrets found during scanning must be redacted in reports"
- "Remediation fixes must not break existing tests"
```
---
## Python API Usage
``` python
from pathlib import Path
from cleveragents . action . schema import ActionConfigSchema
# Load from a file
config = ActionConfigSchema . from_yaml_file ( Path ( " examples/actions/simple.yaml " ) )
print ( config . name ) # "local/lint-check"
print ( config . strategy_actor ) # "local/strategist"
print ( config . read_only ) # True
print ( config . reusable ) # True
# Load from a YAML string
yaml_str = """
name: local/my-action
description: My action
strategy_actor: local/strategist
execution_actor: local/executor
definition_of_done: Task is complete.
"""
config = ActionConfigSchema . from_yaml ( yaml_str )
# Access arguments
for arg in config . arguments :
print ( arg . name , arg . type , arg . required )
```
### Environment Variable Interpolation
String values may reference environment variables using `${VAR}` syntax.
Unresolved variables are left as-is:
``` yaml
name : local/deploy
description : "Deploy to ${TARGET_ENV}"
strategy_actor : local/strategist
execution_actor : local/executor
definition_of_done : "Deployment to ${TARGET_ENV} complete."
automation_profile : ${DEPLOY_PROFILE}
```
``` python
import os
os . environ [ " TARGET_ENV " ] = " staging "
os . environ [ " DEPLOY_PROFILE " ] = " supervised "
config = ActionConfigSchema . from_yaml_file ( Path ( " deploy.yaml " ) )
# config.description == "Deploy to staging"
# config.automation_profile == "supervised"
```
---
## CLI Usage
Actions are managed through the `agents action` command group. See
[Action CLI Reference ](../reference/action_cli.md ) for full details.
``` bash
# Create an action from a YAML config file
agents action create --config action.yaml
# List all available actions
agents action list
# Filter by namespace or state
agents action list --namespace local
agents action list --state available
# Show full details for an action
agents action show local/lint-check
agents action show local/lint-check --format json
# Archive (soft-delete) an action
agents action archive local/old-action
```
---
## Validation Errors
`ActionConfigSchema` produces clear, actionable error messages. Common
failure modes:
| Scenario | Error |
|----------|-------|
| `name` missing namespace | `Invalid action name '…'. Names must follow the namespace/name format` |
| `strategy_actor` not namespaced | `Invalid actor name '…'. Actor names must follow the namespace/name format` |
| `state` set to `draft` | `Invalid state 'draft'. Allowed states: archived, available` |
| Unknown argument `type` | `Invalid argument type '…'. Allowed types: boolean, float, integer, list, string` |
| Extra top-level key | `Extra inputs are not permitted` |
| Empty YAML | `YAML string is empty. Provide a valid action YAML configuration.` |
| Non-mapping YAML | `Action YAML must be a mapping (key: value), got …` |
---
## See Also
- [`docs/schema/action.schema.yaml` ](../../schema/action.schema.yaml ) — Formal schema definition
- [Action CLI Reference ](../reference/action_cli.md ) — `agents action` command group
- [`cleveragents.actor` ](actor.md ) — Actor system (actors referenced by actions)
- [`cleveragents.config` ](config.md ) — Application configuration
- [ADR-006 Plan Lifecycle ](../adr/ADR-006-plan-lifecycle.md ) — Design rationale for the plan/action model
HAL9000