# ADR-017: Automation Profiles

**Status:** Accepted  
**Date:** 2026-02-16  
**Supersedes:** None  
**Author(s):** Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>  
**Approver(s):** Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>

## Context

Different tasks require different levels of autonomy. A trusted refactoring in a well-tested codebase can run fully automatically, while a production infrastructure change requires human approval at every step. The system needs a configurable mechanism that controls which phase transitions happen automatically, which decisions require human input, and what safety constraints (sandboxing, checkpoints, approval gates) are enforced — without requiring code changes.

## Decision

CleverAgents uses **automation profiles** — named configuration bundles that control autonomy thresholds across the plan lifecycle. Eight built-in profiles span the spectrum from fully manual to fully autonomous. Custom profiles can be created. The effective profile for a plan is resolved via a precedence chain (plan > action > project > global) and is locked to the plan at `plan use` time.

## Design

### Profile Fields

Each automation profile is a set of confidence thresholds and boolean flags:

| Field | Type | Description |
|-------|------|-------------|
| `auto_strategize` | float (0.0-1.0) | Confidence threshold for automatic entry into Strategize after `plan use`. 0.0 = always auto, 1.0 = always manual. |
| `auto_execute` | float (0.0-1.0) | Confidence threshold for automatic transition from Strategize to Execute. |
| `auto_apply` | float (0.0-1.0) | Confidence threshold for automatic Apply after Execute. |
| `auto_decisions_strategize` | float (0.0-1.0) | Threshold for automatic decision-making during Strategize. |
| `auto_decisions_execute` | float (0.0-1.0) | Threshold for automatic decision-making during Execute. |
| `auto_strategy_revision` | float (0.0-1.0) | Threshold for automatic Execute → Strategize reversion. |
| `auto_reversion_from_apply` | float (0.0-1.0) | Threshold for automatic Apply → Strategize reversion. |
| `require_sandbox` | boolean | Whether sandbox isolation is required. |
| `require_checkpoints` | boolean | Whether checkpointing is required. |
| `max_correction_attempts` | integer | Maximum auto-correction attempts before escalating to user. |

### Threshold Semantics

A threshold of **0.0** means "always proceed automatically." A threshold of **1.0** means "always require human approval." Intermediate values (e.g., 0.7) mean "auto-proceed only when the system's confidence score meets or exceeds the threshold; otherwise prompt the user."

The Semantic Escalation system produces confidence scores for each transition. When the score is below the profile's threshold, the system pauses and prompts the user.

### Eight Built-In Profiles

| Profile | Intent | Key Settings |
|---------|--------|-------------|
| `manual` | Human controls everything | All thresholds 1.0, sandbox required, checkpoints required |
| `review` | Auto-strategize, human reviews before execute and apply | `auto_strategize: 0.0`, execute/apply thresholds high |
| `supervised` | Auto through strategize/execute, human approves apply | `auto_apply: 1.0`, others low |
| `cautious` | Mostly auto with conservative thresholds | Moderate thresholds (~0.7), sandbox required |
| `trusted` | Fully auto for well-tested domains | Low thresholds (~0.3), sandbox required |
| `auto` | Fully automatic with safety nets | All thresholds 0.0, sandbox required, checkpoints required |
| `ci` | CI/CD pipeline automation | All thresholds 0.0, no sandbox required, no checkpoint requirement |
| `full-auto` | Maximum autonomy, minimal guardrails | All thresholds 0.0, no sandbox required, no checkpoints required |

### Profile Resolution

The effective profile for a plan is resolved at `plan use` time using precedence:

```
plan (--automation-profile flag) > action (automation_profile field) > project (core.automation-profile) > global (core.automation-profile)
```

Once resolved, the profile is **locked to the plan** and does not change if the upstream configuration changes.

### Custom Profiles

Custom automation profiles are registered via YAML configuration (`agents automation-profile add --config <FILE>`) with the namespace system. Custom profiles specify all the same fields as built-in profiles and can use any threshold values.

## Constraints

- The effective automation profile is resolved once at `plan use` time and locked to the plan. Changing the profile after plan creation requires creating a new plan.
- Threshold values must be in the range [0.0, 1.0].
- `require_sandbox: false` is only valid if the sandbox strategy is `none`. Plans with `require_sandbox: true` must have a non-none sandbox strategy.
- `require_checkpoints: false` is only valid if `sandbox.checkpoint.enabled` is `false`. Plans with `require_checkpoints: true` reject tools with `checkpointable: false`.
- The default global profile is `supervised` (configurable via `core.automation-profile`).
- Built-in profile names are reserved and cannot be overridden by custom profiles.

## Consequences

### Positive
- A single mechanism controls all autonomy aspects of the plan lifecycle, avoiding ad-hoc per-feature autonomy flags.
- Eight built-in profiles cover the common use cases without requiring custom configuration.
- Profile locking at plan creation prevents mid-execution changes that could invalidate assumptions.
- The precedence chain enables sensible defaults (e.g., project-level profile) with per-plan overrides when needed.

### Negative
- The number of configurable fields (10+) makes profiles complex to understand and tune.
- Profile locking means that if a profile is too restrictive mid-execution, the plan must be recreated with a different profile.
- Confidence score calibration affects the behavior of intermediate thresholds — poorly calibrated scores make thresholds unreliable.

### Risks
- The `full-auto` and `ci` profiles with `require_sandbox: false` remove key safety nets. Misuse could cause unintended resource modifications.
- Custom profiles with overly permissive settings could bypass important safety constraints.
- Users may not understand the interaction between threshold values and confidence scores, leading to unexpected automation behavior.

## Alternatives Considered

**Per-transition boolean flags (auto/manual)** — Simpler but lacks nuance. The confidence threshold approach enables the system to auto-proceed for high-confidence operations while prompting for uncertain ones.

**No built-in profiles (always custom)** — Increases barrier to entry. Built-in profiles provide sensible defaults that cover common use cases.

## Compliance

- **Profile resolution tests**: Tests verify the full precedence chain (plan > action > project > global) and profile locking behavior.
- **Threshold enforcement tests**: Tests verify that each threshold correctly gates or permits its corresponding transition for various confidence scores.
- **Safety constraint tests**: Tests verify that `require_sandbox` and `require_checkpoints` correctly reject non-compliant configurations and tools.
- **Built-in profile tests**: Tests verify that all eight built-in profiles produce the expected behavior for standard plan lifecycles.
- **BDD scenarios**: Behave features exercise plans under different profiles including transitions between manual approval, auto-proceed, and confidence-gated decisions.

## Related ADRs

| ADR | Title | Relationship |
|-----|-------|-------------|
| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Profiles control which lifecycle phase transitions require human approval |
| [ADR-007](ADR-007-decision-tree-and-correction.md) | Decision Tree and Correction | Confidence thresholds determine which decisions require human intervention |
| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Invariant violation escalation is governed by the active automation profile |

## Acceptance

### Votes For

| Voter | Comment |
|-------|---------|
| Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> | Named profiles with confidence thresholds provide a clean spectrum from full manual to full autonomous control |

**Total: 1**

### Votes Against

| Voter | Comment |
|-------|---------|

**Total: 0**

### Abstentions

| Voter | Comment |
|-------|---------|

**Total: 0**
