cleveragents-core/docs/reference/automation_profiles.md

Automation Profiles

Automation Profiles control how much autonomy the CleverAgents system has at each phase of plan execution. Each profile defines a set of threshold values and safety requirements that determine when the system may proceed automatically versus when it must wait for human approval.

Threshold Semantics

Each threshold field is a float in the range [0.0, 1.0]:

Value	Meaning
0.0	Fully automatic — no human gate required
1.0	Always requires human approval
0.0 < v < 1.0	Probabilistic — the system may proceed if its confidence exceeds the threshold

Threshold Fields

Field	Category	Description
auto_strategize	Phase transition	Gate before entering the strategy phase
auto_execute	Phase transition	Gate before entering the execution phase
auto_apply	Phase transition	Gate before applying changes
auto_decisions_strategize	Decision autonomy	Gate for decisions during strategy
auto_decisions_execute	Decision autonomy	Gate for decisions during execution
auto_validation_fix	Self-repair	Gate for automatic validation fixes
auto_strategy_revision	Self-repair	Gate for automatic strategy revision
auto_reversion_from_apply	Self-repair	Gate for reverting from the apply phase
auto_child_plans	Child plans	Gate for spawning child plans
auto_retry_transient	Retry	Gate for retrying transient failures
auto_checkpoint_restore	Checkpoint	Gate for automatic checkpoint restoration

Safety Fields

Field	Type	Default	Description
require_sandbox	bool	true	Execution must happen in a sandbox
require_checkpoints	bool	true	Checkpoints must be created before writes
allow_unsafe_tools	bool	false	Tools flagged as unsafe may be invoked

Built-in Profiles

Eight profiles ship with every CleverAgents installation:

Flag	manual	review	supervised	cautious	trusted	auto	ci	full-auto
auto_strategize	1.0	0.0	0.0	0.7	0.0	0.0	0.0	0.0
auto_execute	1.0	0.0	1.0	0.7	0.0	0.0	0.0	0.0
auto_apply	1.0	1.0	1.0	1.0	1.0	1.0	0.0	0.0
auto_decisions_strategize	1.0	1.0	0.0	0.6	0.0	0.0	0.0	0.0
auto_decisions_execute	1.0	1.0	1.0	0.8	0.0	0.0	0.0	0.0
auto_validation_fix	1.0	1.0	1.0	0.7	0.0	0.0	0.0	0.0
auto_strategy_revision	1.0	1.0	1.0	0.8	1.0	0.0	0.0	0.0
auto_reversion_from_apply	1.0	1.0	1.0	0.9	1.0	1.0	0.0	0.0
auto_child_plans	1.0	0.0	1.0	0.7	0.0	0.0	0.0	0.0
auto_retry_transient	1.0	0.0	0.0	0.0	0.0	0.0	0.0	0.0
auto_checkpoint_restore	1.0	1.0	1.0	0.6	1.0	0.0	0.0	0.0
require_sandbox	true	true	true	true	true	true	true	false
require_checkpoints	true	true	true	true	true	true	true	false
allow_unsafe_tools	false	false	false	false	false	false	false	true

Profile Descriptions

• manual — Human approves every action. Maximum safety, minimum autonomy.
• review — Strategy and execution proceed automatically; human reviews before apply. Good default for development.
• supervised — Human reviews strategy and execution decisions. Strategy creation itself is automatic.
• cautious — Probabilistic gates on most actions. The system proceeds when confident, asks when unsure.
• trusted — Automatic for most phases, but human approval required for apply and reversion. Suitable for experienced teams.
• auto — Fully automatic except reversion from apply. Suitable for well-tested pipelines.
• ci — Designed for CI/CD pipelines. All thresholds at 0.0 but sandbox and checkpoints remain required.
• full-auto — No gates, no sandbox, no checkpoints, unsafe tools allowed. Use with extreme caution.

Resolution Precedence

When determining which profile applies to a given plan execution, the system resolves profiles in the following order (highest priority first):

1. Plan-level override — A profile specified directly on the plan.
2. Project-level setting — The default profile configured for the project.
3. Organization-level default — The organization's default profile.
4. System default — Falls back to the review built-in profile.

At each level, the profile may be specified by:

• A built-in name (e.g. cautious)
• A namespaced custom profile (e.g. acme/strict)

Custom Profiles

Custom profiles use a namespace/name naming convention:

name: acme/strict
description: Strict profile for production deployments
schema_version: "1.0"

auto_strategize: 0.9
auto_execute: 0.9
auto_apply: 1.0
auto_decisions_strategize: 0.8
auto_decisions_execute: 0.9
auto_validation_fix: 0.5
auto_strategy_revision: 0.9
auto_reversion_from_apply: 1.0
auto_child_plans: 0.8
auto_retry_transient: 0.3
auto_checkpoint_restore: 0.7

require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false

See docs/schema/automation_profile.schema.yaml for the full YAML schema and examples/profiles/ for example configurations.