Epic Orchestrator

Epic Orchestrator

Two roles. Interactive entry point: run epic intake through Gate 1 with the human at the monitor — pickup-epic, assess-epic, the Gate 1 signoff package. Routing contract: this directory is the home of the state-transition tables and the state-reader, evidence-checker, and gate1-package prompts that autonomous delivery routes on.

After Gate 1, advancement is normally driven by the resident driver (drive-epic): one long-lived session per active epic advances tickets on completion events. A manually run orchestrator session remains valid (debugging, pushing a specific epic) and must follow the same claim discipline — including the driver-claim fence — so a manual run and a live driver never act on the same ticket concurrently.

Do not implement product code, review code directly, or run tests as the primary actor. Dispatch bounded lanes and workers and advance state only from durable evidence.

Routine human involvement is exactly two gates: Gate 1 (epic intent approval, up front) and Gate 2 (manual merge of the epic PR into main/master — the production entry point). Everything between is autonomous, with event-driven exceptions.

Contract

Inputs

• epicId
• repoPath
• pmSystem
• mode: start or start-or-resume
• optional baseBranch
• optional humanContact
• optional runLedgerPath

Hard Gates

• Gate 1 — epic intent: no child enters the spec/plan pipeline before the epic carries epic-signed-off (or the child carries an explicit prior human signoff). Gate 1 approval is the recorded delegation for every child; a child labeled needs-human-spec still requires its own per-child spec signoff.
• Gate 2 — production entry: the epic PR into main/master is opened by submit-epic-pr and merged only by a human. Never merge, auto-merge, or enable auto-merge on an epic PR.
• No ticket enters implementation without spec-ready and ready-to-implement.
• Any implementation surprise requiring product, architecture, scope, or plan judgment returns the ticket to the spec lane.

Gate 1 — Epic Intent Signoff

After pickup-epic and assess-epic, dispatch the Gate 1 package worker (gate1-package-prompt.md, Frontier tier; model: fable on Claude Code) to draft the signoff package: epic TL;DR + key points, child list with one-line intents, the dependency map, and the ⚠-flagged assumptions approval will delegate. Resolve the runtime-native executor per execution-model.md § 2. Post it to the epic and notify humanContact. Hold in awaiting-epic-signoff.

On approval: apply epic-signed-off to the epic and post a comment quoting what was approved — that comment is the delegation record mature-ticket relies on. An ambiguous or partial response stays in awaiting-epic-signoff; genuine product questions from any worker still stop and ask regardless of delegation.

State Reconstruction

1. Dispatch a state-reader worker (state-reader-prompt.md) and consume its state map.
2. Read the continuation brief and notes from the epic if this is a resumed session.
3. Prefer PM labels, PM comments, artifact links, and Git state over local ledger entries when they disagree.
4. Choose the next allowed actions.

Allowed Next Actions

Interactive intake (this skill's primary job):

• Run pickup-epic.
• Run assess-epic.
• Request Gate 1 signoff (package → notify → hold).

Post-Gate-1 (normally executed by the resident driver (drive-epic); a manual session may perform them under the same claim discipline — claim the ticket first (minting a session run id), skip live claims from other sessions per the driver-claim-topped liveness hierarchy):

• Run mature-ticket for a child lacking readiness (auto-delegated under Gate 1).
• Execute a deliver-ticket lane inline for a ready child — walk lanes/deliver-playbook.md natively per execution-model.md (one lane in flight; never a nested lane subagent). Exit contract, checkpoint mechanics, and worker-await rules live in the playbook and execution-model, not re-spelled per dispatch.
• Merge a ready-to-merge-child lane result (strictly serial; see Merging).
• Run submit-epic-pr when all children are done.

Stop: awaiting Gate 1, human question, concrete blocker, or epic-pr-open (Gate 2 is human-owned).

Merging

Merges into the epic branch are orchestrator-owned and strictly serial:

1. Take one ready-to-merge-child lane result.
2. Scoped evidence-checker rule (the single source, with § Evidence Rule): dispatch the evidence-checker worker (evidence-checker-prompt.md) iff this session is adopting work it did not execute and directly observe — any Lane Checkpoint in the trail carries a foreign or missing session run id, or any own-run-id checkpoint predates this session's last compaction (a deliberate compaction is a voluntary crash + resume: post-compaction knowledge of prior steps is reconstructed from durable state, not observed — treat those checkpoints as adopted). When every checkpoint was written by this session in its current context window, skip the checker: results were claimed only from leaf digests as the lane was walked, and the merge retains its script-owned postcondition (step 5, verify-merge.sh) and the branch-currency check (step 3). When in doubt, dispatch — the predicate fails closed. (Scope: the merge-slot adoption gate; the janitor's read-only reconciliation checkers in reconcile-tickets are a different context, untouched.)
3. Check the child branch is current with the epic head; if the epic moved, have the lane (re-dispatched if needed) sync and rerun relevant checks per submit-ticket-pr merge rules.
4. Merge-eligibility guard: no merge is eligible while the epic holds coherence-pending (reviews stay serial, the register append-ordered). Apply coherence-pending to the epic before the merge command (fail-closed label-before-merge): the irreversible write is the inlined submit-ticket-pr Merge (gh pr merge) — the sequence contains no push — so a crash between merge and label under the old merge-then-label order left a merged child with no coherence review and no detector.
5. Squash merge via submit-ticket-pr (Merge); verify the postcondition with ${CLAUDE_PLUGIN_ROOT}/scripts/verify-merge.sh, then clean up with ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-branch.sh, passing the merge SHA verify-merge.sh printed as the final argument — squash merges rewrite the SHA, so the cleanup proof requires it; post the done comment.
6. Run the coherence review — full set-difference protocol. The target set is every merged-but-unregistered SHA: fetch all merged child PRs targeting the epic branch (mergeCommit oids) and all coherence-verdict register-entry Merge SHA: keys — verdict entries only, those with no Kind: field (a MODE/CAPACITY_PARK/FABLE_MAKEUP entry is not a verdict) — (a paged register read), review the difference oldest mergedAt first, serially, each dispatch noting that register entries newer than the SHA under review are not precedent. For each SHA, the loop-side idempotence check first (an entry keyed to this SHA ⇒ resume missing routing writes, do not re-dispatch); otherwise dispatch the coherence reviewer (coherence-reviewer-prompt.md, Frontier tier; model: fable on Claude Code, runtime-native executor per execution-model.md § 2), put its dispatcher-authored review-executor: coherence/1 ... record in the verdict's decision-register entry (review § Native Executor Evidence), and perform its verdict-routing writes (register entry comment on the epic ticket + the ## Decision Register — Canon section of the epic description, label changes on affected children, corrective ticket on MATERIAL_DRIFT — all idempotent, keyed to the SHA). Halt after the first pending-human verdict (GATE1_AMENDMENT/GATE1_REFRESH) completes its own routing — review no further SHAs while it stands. The label clears iff the set-difference (over coherence-verdict entries only — no Kind: field) is empty ∧ no register entry over the epic's merged SHAs is unresolved (register-wide, never batch-scoped); zero merged child PRs clears vacuously. On a GATE1_AMENDMENT/GATE1_REFRESH, escalate and leave the label in place: the human resolves by invoking the drive-epic skill with the instruction rule-coherence <sha> approve|reject|redirect (a session run, parsed by drive-epic's Step 0a — not a separate command), and the ruling session performs the routing directly. New lane dispatches, maturation, and the merge slot for this epic stay blocked while coherence-pending.

State Transitions

Use the lane-boundary and epic-level tables and the demotion rules in state-transitions.md (in this skill's directory). Externally tracked child states: spec lane → ready-to-implement → delivering → ready-to-merge-child → done. The intermediate delivery states remain visible as lane checkpoint comments but are not orchestrator transitions.

Context Hygiene

Compact deliberately — a deliberate compaction is a voluntary crash + resume; never drift into harness-forced compaction mid-thought.

• Mandatory reset anchors: after Gate 1 approval is recorded. In the resident driver, every durable lane-progress seam (each child-merge close-out, and each completion-anchored deliver checkpoint / mature state boundary) is a durable-brief anchor point (register + continuation brief kept current), not an unplanned session reset — an actual context reset happens only at park, the planned refresh-park (a planned RESUMABLE exit at a durable seam — the one exception), or bloat (a mandatory unplanned reset per merge would recreate the one-action tick the resident model replaces). At a reset anchor: write the continuation brief (epic comment and ledger), end the session, resume fresh from durable state.
• Emergency valve: if the harness warns context is low between anchors, finish the current step — never abandon a dispatch or merge mid-flight — write the brief, and reset. If a step cannot complete, post an explicit "interrupted at" comment so the resume does not double-execute.
• Continuation brief: current state map reference with evidence links, chosen next action and one line of why, live concerns from notes, and anything in flight that must not be redone (open PRs, running lanes).
• Notes discipline: append soft observations (flaky tests, retried workers, fragile modules) to the epic notes as they occur. When unsure whether to persist an observation: write it.

Evidence Rule

The orchestrator may not advance state from a lane or worker success claim alone. Verify durable PM labels, PM comments, artifact links, branch/worktree state, commits, or command output before advancing. The evidence-checker worker is the adoption instrument — Merging step 2 states the single test with this section: own-session work walked in the current context window advances on its leaf digests and the durable writes made as each boundary was crossed; adopted work (a foreign or missing run id, or own checkpoints predating the last compaction) takes the checker. Non-merge state advances follow the same adoption test. When in doubt, dispatch — the predicate fails closed.

Durable PM state is the source of truth.

Notifications

Interrupt the human only for: Gate 1 request, Gate 2 ready (epic PR open, awaiting manual merge), demotions, QUESTIONS_FOR_HUMAN, and blockers automation cannot resolve. Every notification leads with the artifact's TL;DR + key points and links; routine progress goes to PM comments only.

Stop Conditions

• awaiting-epic-signoff (Gate 1)
• epic-pr-open (Gate 2 — human merges)
• human question or spec input required
• tool or auth failure
• blocked dependency
• implementation surprise requiring spec or plan revision

Progress Record

Emit progress records with epicId, optional ticketId, state, action, evidence, nextAction, and needsHuman.