# Epic Orchestrator > Interactive epic intake through Gate 1 signoff, and the shared routing contract (state tables, worker prompts) the resident driver and manual sessions route on - Skill: `dodi-hq/epic-orchestrator` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add dodi-hq/epic-orchestrator` - Raw SKILL.md: https://api.skillmd.com/api/skills/dodi-hq/epic-orchestrator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: dodi-hq (https://skillmd.com/u/dodi-hq) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/dodi-hq/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 | Trigger | Inputs | Outputs | Durable writes | Allowed delegation | Failure states | | --- | --- | --- | --- | --- | --- | | interactive epic intake, or a manual session pushing an epic along | epic id, repo path, PM system context | next state decision, inline lane playbooks and phase work, epic progress summary | epic comments, child ticket comments, labels, claim comments, artifact links | deliver-ticket / mature-ticket playbooks executed inline (per `execution-model.md` — never nested lane subagents), phase skills, leaf workers, reviewers, test runners | awaiting epic signoff, human question, blocked dependency, tool/auth failure | ## 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 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`.