cleveragents-core/docs/reference/plan_lifecycle_service.md

Plan Lifecycle Service Reference

Source: src/cleveragents/application/services/plan_lifecycle_service.py

Overview

The PlanLifecycleService manages the v3 plan lifecycle:

Action -> Strategize -> Execute -> Apply

Plans are instantiated from Action templates. Terminal outcomes live in the Apply phase's processing state: applied, constrained, errored, or cancelled.

Action Management

Method	Description
create_action(...)	Create a new action (defaults to available state)
get_action(name)	Get action by namespaced name
get_action_by_name(name)	Alias for get_action with partial name resolution
list_actions(namespace, state)	List actions with optional filtering
make_action_available(name)	No-op (actions are available by default)
archive_action(name)	Set action state to archived

Plan Creation

use_action(action_name, project_links, arguments, ...)

Uses an action on projects to create a plan in Strategize phase.

• Validates action is in available state
• Validates required arguments
• Resolves automation level (explicit > global default)
• Merges invariants (plan > action)
• Creates plan with phase=STRATEGIZE, processing_state=QUEUED
• Archives non-reusable actions after use

Phase Transitions

Method	From	To	Description
execute_plan(plan_id)	Strategize/COMPLETE	Execute/QUEUED	Transition to Execute phase
apply_plan(plan_id)	Execute/COMPLETE	Apply/QUEUED	Transition to Apply phase

Processing State Methods

Strategize Phase

Method	State Transition	Description
start_strategize(plan_id)	QUEUED -> PROCESSING	Begin strategize work
complete_strategize(plan_id)	PROCESSING -> COMPLETE	Finish strategize, may auto-progress
fail_strategize(plan_id, error)	* -> ERRORED	Mark strategize as failed

Execute Phase

Method	State Transition	Description
start_execute(plan_id)	QUEUED -> PROCESSING	Begin execute work
complete_execute(plan_id)	PROCESSING -> COMPLETE	Finish execute, may auto-progress
fail_execute(plan_id, error)	* -> ERRORED	Mark execute as failed

Apply Phase

Method	State Transition	Description
start_apply(plan_id)	QUEUED -> PROCESSING	Begin apply work
complete_apply(plan_id)	PROCESSING -> APPLIED	Terminal success — changes committed
constrain_apply(plan_id, reason)	* -> CONSTRAINED	Cannot complete within constraints; may revert to Strategize
fail_apply(plan_id, error)	* -> ERRORED	Mark apply as failed

Apply Terminal Outcomes

The Apply phase has four terminal outcomes, modeled as ProcessingState values:

Processing State	Meaning	Next Step
APPLIED	Success — changes committed	Done
CONSTRAINED	Cannot proceed within strategy constraints	May revert to Strategize
ERRORED	Failed	May retry or abandon
CANCELLED	User/system cancelled	Done

Cancellation

cancel_plan(plan_id, reason=None)

Cancel any non-terminal plan. Sets processing_state=CANCELLED.

Automation

should_auto_progress(plan)

Pure query — checks if the plan should automatically advance:

• Strategize/COMPLETE with REVIEW_BEFORE_APPLY or FULL_AUTOMATION: auto-execute
• Execute/COMPLETE with FULL_AUTOMATION: auto-apply

auto_progress(plan_id)

Idempotent — advances to next phase if automation permits.

pause_plan(plan_id) / resume_plan(plan_id, level)

Pause halts auto-progression (sets MANUAL). Resume restores level and triggers immediate auto-progress if ready.

set_plan_automation_level(plan_id, level)

Change automation level for non-terminal plans.

Custom Exceptions

Exception	Description
InvalidPhaseTransitionError	Attempted invalid phase transition
ActionNotAvailableError	Action not in available state
PlanNotReadyError	Plan not in expected state for transition