Skip to content
LumenFlow

Lifecycle

LumenFlow separates initiative orchestration into six distinct concerns. Keeping them separate is what lets humans, local agents, and compatible remote orchestration surfaces drive the same initiative without re-deriving the rules.

1. Plan

Section titled “1. Plan”

Compute the logical-wave dependency graph. A WU’s logical wave is its shortest-path distance from any root, and it does not change unless the graph changes.

  • Inputs: initiative YAML, WU YAMLs, lane WIP limits.
  • Output: plan.json in the attempt bundle (see Artifact bundle).
  • Run it with pnpm orchestrate:initiative -i INIT-XXX --dry-run (no handoff files written).

2. Handoff

Section titled “2. Handoff”

Record the intent to launch a WU. This is the step where the orchestrator produces a bootstrap artifact — XML for Claude, markdown for Codex/Gemini, generic prompt for anything else — and writes a launch receipt tying that artifact to (initiative, logical_wave, launch_attempt, handoff_format).

  • Prompt emission is not launch. The receipt in launch.json is the durable record; the prompt is adapter output.
  • wu:brief remains the canonical full handoff surface for a single WU. Launch modes in orchestrate:initiative write the same client-shaped handoff artifacts into the bundle and print the artifact paths by default.
  • --print-handoffs replays the stored handoff artifacts inline when a human needs manual copy/paste output.
  • Clients that can spawn workers directly do so here; clients that cannot leave the handoff as a pending payload the human copies into their agent.

3. Execution

Section titled “3. Execution”

The worker claims the WU (wu:claim), runs wu:brief, implements the change, runs wu:prep, and completes via wu:done. The orchestrator does not participate in this phase — it is pure lifecycle evidence, the same evidence any LumenFlow WU produces whether it came from an initiative or not.

4. Reconciliation

Section titled “4. Reconciliation”

Read the durable evidence and classify every WU into an orchestration state:

  • WU YAML status + .done stamps
  • Worktree presence on disk
  • Launch receipt from launch.json
  • Delegation registry pickup timestamp
  • Checkpoint + signal activity in shared memory
  • WU lease/session evidence and lane branch presence
  • Main-checkout contamination (from git status)
  • Stalled worktrees (no activity past the configured threshold)

Reconciliation is the heart of the control plane. The @lumenflow/initiatives package ships a single classifier that the CLI and MCP tools share, so the answer is the same no matter which surface you look at.

orchestrate:monitor uses this same evidence before calling a delegation stuck. Stale rows for WUs that are already done or otherwise settled become reconciled stale results, while contradictory rows are surfaced as conflicts requiring recovery. A vendor/client/model label is never the lifecycle key.

5. Finish

Section titled “5. Finish”

Drive WUs that are ready_for_finish through wu:prep + wu:done. Completion semantics differ by claimed mode:

  • Worktree mode — wu:done succeeds, the .done stamp exists, the worktree is cleaned up.
  • Branch-PR / cloud mode — wu:done creates a PR and the WU enters awaiting_merge; it becomes done only after the merge and wu:cleanup produce the terminal stamp.

Worker return is not completion. A subagent stopping, a delegation completing, or a prep-ready worktree showing up only mean the classifier now has stronger evidence.

6. Status

Section titled “6. Status”

Project the reconciled truth to humans, agents, and remote surfaces:

  • Stdout — concise human summary + next-step commands.
  • Launch stdout — wave summary, artifact bundle paths, and per-WU handoff file paths by default; --print-handoffs replays stored handoffs inline.
  • --json — authoritative machine-readable state for agents and remote launchers.
  • Artifact bundle — durable files for resume, audit, and adapter generation.
  • Client adapters — optional Claude/Codex/Gemini handoff payloads on top of the control-plane contract.

Every surface answers the same question: what is the next safe action for this initiative?

Section titled “Related”