cleveragents-core/docs/adr/ADR-006-plan-lifecycle.md

ADR-006: Plan Lifecycle

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

CleverAgents needs a structured workflow that takes a user's intent (e.g., "increase test coverage to 85%") and transforms it into verified, applied changes across project resources. This workflow must support human review gates, autonomous execution, hierarchical decomposition into child plans, sandboxed execution with rollback, and correction of decisions at any point. A linear "run and hope" approach is insufficient — the system needs distinct phases with clear inputs, outputs, transition rules, and failure handling.

Decision

Every unit of work in CleverAgents follows a four-phase lifecycle: Action → Strategize → Execute → Apply. Each phase has defined inputs, outputs, processing states, and transition rules. The lifecycle supports forward progression, phase reversion (Execute → Strategize, Apply → Strategize), hierarchical decomposition via child plans, and automation profile-controlled autonomy at each transition.

Design

Phase Definitions

Action — A reusable plan template that defines work to be done (description, definition of done, actors, arguments, invariants) without being bound to any project. No significant processing occurs. When used via agents plan use, it spawns a new plan entity that enters Strategize. Actions with reusable: true (default) remain available after use; reusable: false actions are deleted after first use.

Strategize — The first active processing phase. Read-only. The strategy actor gathers context from project resources, collects applicable invariants (reconciled via the Invariant Reconciliation Actor as invariant_enforced decisions), and produces a strategy: a decision tree of approach choices, resource selections, and child plan blueprints (subplan_spawn / subplan_parallel_spawn decisions). No resource modification occurs.

Execute — Work happens in a sandboxed environment. The execution actor follows the strategy, invokes tools to modify resources in the sandbox, spawns child plans from subplan_spawn decisions, and creates checkpoints for rollback. Produces a reviewable changeset. Additional decisions may be created during execution, constrained by Strategize-phase decisions.

Apply — The controlled commit step. Merges the sandboxed changeset into real project resources. Handles diff review gates, conflict resolution, and audit logging. Validation runs during Execute, not during Apply — by the time Apply runs, all required validations have passed.

Phase Transition Verbs

Current Phase	CLI Verb	Next Phase
(none)	create	Action
Action	use	Strategize
Strategize	execute	Execute
Execute	apply	Apply

There is no strategize command. The use verb transitions from Action to Strategize by design — "use" describes the user's intent of applying an action template to a project.

Processing States Per Phase

Action: available, archived.

Strategize / Execute: queued, processing, errored, complete, cancelled.

Apply: queued, processing, errored, applied (terminal success), constrained (terminal — strategy constraints prevent completion), cancelled.

Phase Reversion

Both Execute and Apply may revert to Strategize (never to any other phase):

Execute → Strategize: Triggered when the execution actor discovers that Strategize-phase constraints are too restrictive to complete the work. Rather than violating those constraints, the plan reverts so the strategy actor can adjust the decision tree. Controlled by the auto_strategy_revision automation profile flag.

Apply → Strategize: Triggered when the changeset cannot be applied within the current strategy's constraints (merge conflicts, validation failures at apply time, resource state drift). The plan enters the constrained terminal state, then may revert either automatically or after manual approval. Controlled by the auto_reversion_from_apply flag.

Plan Identity

Every plan carries: plan_id (ULID), parent_plan_id (nullable), root_plan_id, attempt (integer, increments on phase re-runs), created_at, updated_at, completed_at, and created_by.

Plan Hierarchy

Plans are hierarchical. Child plans are full plans with their own lifecycles, decision trees, and sandboxes. Decisions about child plans are made during Strategize (subplan_spawn, subplan_parallel_spawn); actual spawning occurs during Execute. Child plans run sequentially (individual subplan_spawn) or concurrently (grouped under subplan_parallel_spawn). The parent plan merges results.

Child plan result merging depends on resource type: git-style merge for source code, transaction coordination for databases, pluggable strategies for other types.

Hierarchical Decomposition

For large tasks, the system uses hierarchical decomposition — root plan → subsystem plans → module plans → file-level plans. At each level, only relevant context is loaded. The persistent decision graph enables reconstruction of why any particular change was made and what constraints apply from higher levels.

Action Data Model

Actions carry: name (namespaced), short_description, long_description, definition_of_done (required, must be explicit and testable), actors (strategy, execution, estimation, invariant), reusable (boolean), read_only (boolean), inputs_schema, and automation_profile.

Constraints

• Every unit of work must pass through all four phases in order. No phase may be skipped.
• The Strategize phase is strictly read-only. No resource modification is permitted.
• Execute-phase decisions must be constrained by Strategize-phase decisions. If constraints cannot be honored, the correct response is reversion, not violation.
• Validation runs during Execute, not Apply. Apply assumes all validations have passed.
• Child plan maximum nesting depth is controlled by plan.max-child-depth (default: 5).
• Plan concurrency is controlled by plan.concurrency (default: 4). Child plans count toward the parent's allocation, not the global limit.
• definition_of_done is required on every action and must be explicit and testable.

Consequences

Positive

• The phase separation enables human review at any transition point, controlled by automation profiles.
• Sandboxed execution ensures that incomplete or incorrect work never contaminates real project resources.
• Hierarchical decomposition enables tackling tasks of arbitrary scale while keeping each plan's context bounded.
• Phase reversion provides a structured recovery mechanism instead of plan abandonment.
• The persistent decision tree enables selective correction and replay without re-executing the entire plan.

Negative

• Four phases add ceremony for simple tasks that could be done in a single step.
• Phase reversion creates complex state management, especially when child plans are involved.
• Hierarchical decomposition increases the total number of plans and decisions that must be tracked.

Risks

• Deep plan hierarchies could exhaust resources or create coordination bottlenecks during merging.
• Phase reversion loops (Execute → Strategize → Execute → Strategize ...) must be bounded to prevent infinite cycling.

Alternatives Considered

None — specification-driven requirement. The four-phase lifecycle with reversion, hierarchy, and automation-controlled transitions is the core orchestration model prescribed by the specification.

Compliance

• Lifecycle state machine tests: Unit tests verify all valid phase transitions and reject invalid ones (e.g., Action → Execute without passing through Strategize).
• Reversion boundary tests: Tests verify that Execute-phase code cannot modify resources outside the sandbox and that reversion correctly preserves and transmits findings to the strategy actor.
• BDD scenarios: Behave feature files describe end-to-end plan lifecycle scenarios including hierarchical decomposition, parallel child plan execution, and phase reversion.
• Automation profile integration tests: Tests verify that each automation profile correctly gates the appropriate phase transitions.

Related ADRs

ADR	Title	Relationship
ADR-007	Decision Tree and Correction	Decisions are recorded at each phase transition in the plan lifecycle
ADR-008	Resource System	Resources are bound to plans and sandboxed per the lifecycle phases
ADR-009	Project Model	Plans operate within project scope and inherit project-level configuration
ADR-010	Actor and Agent Architecture	Actors drive phase transitions and execute plan steps
ADR-015	Sandbox and Checkpoint	Sandboxes are created per-plan and checkpoints track execution progress
ADR-016	Invariant System	Invariants are reconciled at Strategize entry and enforced throughout the lifecycle
ADR-017	Automation Profiles	Profiles control which phase transitions require human approval
ADR-033	Decision Recording Protocol	Defines how decisions are recorded during Strategize and Execute phases of the plan lifecycle
ADR-034	Decision Tree Versioning and History	Specifies how decision trees are versioned across plan lifecycle transitions
ADR-035	Decision Tree Rollback and Replay	Governs rollback mechanics during mid-phase corrections within the plan lifecycle

Acceptance

Votes For

Voter	Comment
Jeffrey Phillips Freeman Jeffrey.Freeman@CleverThis.com	The four-phase lifecycle with reversion rules gives us the right balance of structure and recovery

Total: 1

Votes Against

Voter	Comment

Total: 0

Abstentions

Voter	Comment

Total: 0