Spec Orchestrate

spec-orchestrate — Spec-to-PR Pipeline Orchestrator

Drive one feature from a request or Issue all the way to a pull request by running a fixed state machine and delegating each phase to a worker skill. This skill is the conductor, not a performer: it reads state, calls a worker, checks the result, updates state, and advances.

Language Rules

1. Auto-detect input language → produce specs, reports, and PR body in the same language.
2. Japanese input → Japanese output, use the *.ja.md phase guides under references/phases/.
3. English input → English output, use the *.md phase guides.
4. Explicit override takes priority. The chosen language is recorded in state so every phase and every worker prompt stays consistent across a multi-hour run.

Role: Orchestrator Only

🚨 BLOCKING — this rule overrides every phase guide.

spec-orchestrate does not write specifications, code, tests, or reviews. It delegates all of them. The only actions it performs directly are:

• Reading and writing pipeline-state.json (state is orchestrator-owned).
• Verifying worker results against machine-checkable evidence (git diff, result files, screenshots) — never trusting a worker's self-report.
• Running gh commands (Issue fetch, PR create, Issue comments).
• Composing and formatting worker prompts.

Worker completion is judged by the result file — its existence and a content check — not by a subagent's completion notice or chat message. Treat notifications as auxiliary: a missing, split, or re-sent completion message does not change the outcome; decide from the result file.

If a phase tempts you to "just fix it yourself", stop — that is a worker's job. If the required worker skill is not installed, show its install step and halt with state preserved (resumable).

Options

Execution Model

The orchestrator runs one loop until the pipeline reaches a terminal state:

1. Read current phase from pipeline-state.json (or start at intake).
2. Open references/phases/<phase>.md and follow its Input → Action →
   Verification → State Update steps.
3. Dispatch the phase's worker (see Phase Index). First choose its `claude` or
   `codex` AI role, then resolve the backend with the recorded `host_runtime`
   and `references/role-dispatch.md`: same role → runtime-native subagent;
   different role → agent-delegate with an explicit target.
4. Verify the worker's result. If it fails machine verification, do not advance.
5. Update pipeline-state.json (completed phase, round counts, fingerprints,
   thread ids, role overrides, review fallbacks), run the state integrity check
   (references/scripts/pipeline-state-check.sh — must exit clean), and refresh
   the run marker (pipeline-config.md §Run Marker and Watchdog).
6. Select the next phase per the Transition Table and dispatch it in this same
   turn. A progress report to the user rides along with that dispatch — state
   first, report second, never a report alone at a phase boundary.

The config file (pipeline.yml), the state file (pipeline-state.json), the run marker, and the integrity check — schemas, the jq/awk read/write idiom, and the orchestrator-only write rule — are specified in references/pipeline-config.md.

Resume is the default. On startup, if pipeline-state.json exists, run the state integrity check first (reconcile any drift to the evidence before trusting the file), then summarize the completed phases and the next action in one short block, and continue from there. A full run spanning several hours and surviving a crash, restart, or deliberate session split is the normal case, not an exception. See the Resume Behavior section of references/pipeline-config.md. When a terminal run is deliberately reopened for non-terminal work, follow the completed-retrospective resume contract there: supersede its metrics projection, mark it stale, and regenerate revision N+1 at the next terminal state.

Turn Discipline and the Watchdog

🚨 BLOCKING — a report is not an exit.

The loop above ends at a terminal state, not at a phase boundary. The failure mode this section kills: finishing a phase, writing a tidy summary, and ending the turn without dispatching the next phase.

• Worker dispatch and its completion wait live in the same turn. For detached runs the only valid way to yield is the registered background wait of role-dispatch.md Step 3 (a 15–30-second expected-run state watcher that validates the report before owner, pid, heartbeat, and process state, then re-invokes the dispatcher, plus waiting_report set in the run marker). An unregistered pause is indistinguishable from a stall.
• Phase results are reported in the same turn as the next phase's dispatch, after the state write — never as a standalone turn-ending message.
• State writes precede user-facing reports, so a turn that dies right after reporting leaves the state already correct.

The watchdog Stop hook (references/scripts/pipeline-watchdog.sh, registered per repository — spec-workflow-init Step 6d, manual snippet in pipeline-config.md) enforces this mechanically: it blocks a turn from ending while the run marker shows a mid-flight run with no registered wait, and echoes the next action back. Treat a watchdog block as the loop reporting its own stall: run the state check, then dispatch the current phase — and if the block says a registered wait has completed, collect that report first. The rules above bind even where the hook is not installed.

Orchestrator Context Economy

A full run spans dozens of worker dispatches, and the orchestrator's context is the scarcest resource in the pipeline. Three rules:

• Delegate verification work. Mutation tests, "does my own correction hold" checks, and read-the-implementation investigations go to a verifier worker whose return is a verdict plus at most three lines of evidence. Verification must happen; it must not happen in the orchestrator's context.
• Never read a result file in full. Judge from structured fields (jq on report.json and state) and the summary section of review / evaluate files. A judgment that genuinely needs full file contents belongs to a worker.
• Split sessions at phase boundaries. With the integrity check clean and the marker in place, ending the session after a phase and resuming in a fresh one is the normal path for long runs — do not plan around finishing a 30-task run in a single context window.

State Machine — Transition Table

Every state transition is listed here. The Guide column is the phase file that carries the detailed Input / Action / Verification / State-Update steps.

Ordering principle: run the cheap machine check (inspect) before the expensive semantic check (adversarial spec_review), so a peer LLM's tokens are never spent on formatting defects.

Arbitration is entered only when a stall signal fires in spec_review or evaluate. Its detection algorithm (fingerprints, class keys, and signals S1–S4, evaluated from state.rounds alone) and adjudication branches (S4 orders a structural redesign from the planner; manual asks the human; auto swaps the owner up to limits.role_swap_max, else lands a draft PR) are defined in references/stall-detection.md.

Phase Index — Worker and Role

Role keys resolve to an AI role first and an execution backend second through references/role-dispatch.md. The same four-row host-aware matrix applies to the spec author, implementer, reviewer, and E2E runner. If pipeline.yml is absent, the default roles apply and the app recipe is empty.

PR Body Contract

The PR body is a review index for a repository-aware reviewer, not a copy of the pipeline's audit trail. Before composing it, read the project's pull request template and body rules; their headings and required fields take priority over orchestrator defaults.

Select behavior changes, design rationale, impact, known constraints, verification outcomes, and review focus. Keep review round counts, every finding, acceptance tables, evidence manifests, and full arbitration history in local run records unless one item changes the review or merge decision. Move deferred findings to follow-up Issues and leave a concise impact summary and link in the PR. A merge-blocking unresolved item remains in a draft PR.

The complete bilingual selection and draft/ready contract is in references/pr-assembly.md and references/pr-assembly.ja.md; the pr phase must use the reference matching state.language.

Intake Summary

The entry phase turns a request into a working spec directory and an initial state file. Full steps live in phases/intake.md; the shape is:

• manual: hand the natural-language request to spec-generator's interactive mode. The human dialogue happens inside the planner run. The feature name is fixed during that dialogue.
• auto: gh issue view <N> --json title,body,labels, reshape the result into a no-dialogue planner input, and derive the feature name as kebab-case from the Issue title.

Both modes then generate one stable run_id, explicitly determine the current host runtime, and write the initial pipeline-state.json (mode, issue, feature, language, run_id, host_runtime, phase: spec_generate) before dispatching the spec author. Preserve run_id on every resume; determine the current host again and refresh only host_runtime before another dispatch.

Error Handling

In every case, state is preserved so the run is resumable.

Usage Examples

# Manual: talk through the spec, approve once, walk away
/spec-orchestrate --mode manual

# Auto: hand over an Issue, come back to a PR (--issue implies auto)
/spec-orchestrate --mode auto --issue 42

# Resume a multi-hour run after a restart (default when state exists)
/spec-orchestrate --resume --spec .specs/user-auth/