Lifecycle Chain Engine

Orchestrates multi-step lifecycle workflows with checkpointing, condition evaluation, and pause/resume.

Synopsis

Chains are managed through MCP tools:

define_chain(chain_type="feature", feature_slug="my-feature")
execute_chain(action="next", chain_handle="...")
checkpoint_chain(session_id="...")
resume_chain(state_path="...")

Description

The chain engine sequences lifecycle steps (feature design, review, implementation, verification) with conditional branching, gate insertion, and durable checkpoints.

Checkpointing: chain state is serialized to disk and can be resumed across sessions. The ChainHandle fingerprint validates that the resumed chain matches the original.

Chain Types

Type

Purpose

Typical use

plan

Execute implementation plans for a feature

Per-feature plan execution

feature

Single feature lifecycle

Design, implement, review

series

Batch of features in a series

Multi-feature coordination

tier

Group of features at same dependency level

Tier-level review gate

release

Full release verification

Release readiness check

finalize

Archive and commit after release

Post-release cleanup

port

Code porting workflow

Cross-repo migration

workflow

Custom numbered workflow collection

User-defined sequences

Each chain is derived from artifact structure — the engine reads plans.md, design.md, and IMPLEMENTATION-ORDER.md to build the step sequence automatically. The workflow type is an exception: it derives steps from a numbered workflow collection (e.g. multi_feature_design, code_porting) without requiring IMPLEMENTATION-ORDER.md — pass the collection name as series_name.

Conditions

Steps can declare conditions that gate execution based on project state. The engine evaluates conditions before advancing to a gated step; if the condition is not met, the chain pauses with an advisory message.

Condition

Evaluation rule

tier_complete

All features in the current tier must have completed their plan/feature chains before the engine advances past this gate. Evaluated by checking that every feature slug in the tier has a completed status in the chain session store.

release_boundary

All tiers must be complete, and the release chain must reach this step before finalization steps become eligible. Acts as a hard boundary preventing premature finalize or archive operations.

ChainHandle Validation

When resuming a chain from a checkpoint, the engine validates the ChainHandle fingerprint to ensure the chain definition has not changed since the checkpoint was saved. If the fingerprint does not match (e.g. because a plan file was edited), the resume is rejected:

# Attempt to resume a chain whose plan was modified after checkpoint
result = resume_chain(state_path=".apogee/chains/checkpoint.json")

# Response on fingerprint mismatch:
# {
#   "status": "error",
#   "reason": "fingerprint_mismatch",
#   "message": "Chain definition changed since checkpoint. "
#              "Expected fingerprint a3f8c1..., got b7d2e4.... "
#              "Use force=True to override, or define_chain() to "
#              "start a fresh session.",
#   "checkpoint_fingerprint": "a3f8c1...",
#   "current_fingerprint": "b7d2e4..."
# }

# Force resume (skips fingerprint check):
result = resume_chain(
    state_path=".apogee/chains/checkpoint.json",
    force=True
)

Reference

Key classes

  • ChainSpec — immutable chain specification (version, type, steps, on-failure policy, max retries)

  • ChainStep — individual step (type: plan/review/task/approval/ write_verification; condition, on_success target)

  • ChainHandle — stable fingerprint for resumption validation

  • InMemoryChainExecutor — runtime session manager

MCP tools

  • define_chain — derive canonical chain from artifacts

  • execute_chain — start, pause, resume, skip, report

  • checkpoint_chain — persist session to disk

  • resume_chain — restore from checkpoint

Actions for execute_chain

Action

Description

start

Begin chain execution from first step

next

Advance to next step

status

Report current chain state

pause

Pause execution (resumable)

skip

Skip current step with reason

Examples

# Define a feature chain
handle = define_chain(
    chain_type="feature",
    feature_slug="doc-restructure-apogee",
    series_name="series27-docs-architecture"
)

# Execute steps
execute_chain(action="start", chain_handle=handle)
execute_chain(action="next", chain_handle=handle)

# Save and resume later
checkpoint_chain(session_id=handle)
resume_chain(state_path=".apogee/chains/checkpoint.json")

Note

This page is also available as a man page: man apogee-chain

See Also