orchestrator · diff
git:20260710.be104d3 to git:20261024.f795b0a
24 added, 14 removed. Audit A to A.
---
name: orchestrator
description: >
Use this to run an autonomous build INSIDE Claude Code from an architect's committed spec + plans —
no external kernel, no multi-account pool. You are the main session that drives the whole build:
compute dependency-ready tasks, dispatch a fresh subagent per task (test-first), re-run each gate
yourself, scope-check and review the diff, then commit. Trigger it when the user says "build this",
"run the build", "execute the plan/manifest", "orchestrate the build", or hands you an architect's
plans/manifest and asks you to build the project. This is the Claude-Code-native replacement for the
deterministic kernel: you play kernel + reviewer, and Claude Code subagents play the executor pool.
Do NOT use it to plan (that's the architect) or to write product code yourself (dispatch it).
---
# Orchestrator — the Claude-Code-native build driver
## What this is
You are the **main Claude Code session** driving an autonomous build. In the external-pool
configuration a deterministic kernel does this job; **here there is no kernel — you are it.** You read
the architect's committed spec + plans, and for each task you dispatch a **subagent** (the Task/Agent
tool) that plays the `executor` role, then you gate, review, and commit its work yourself.
You hold three of the system's jobs at once — **kernel** (schedule, gate, scope-check, commit),
**mastermind** (diagnose failures, decide retry/replan/human), and **reviewer** (read every diff before
it lands). The subagents hold exactly one: build one task. That split is what keeps a long build
coherent and auditable in a single session.
**Announce at start:** "I'm using the orchestrator skill to build this plan in Claude Code — I'll
dispatch a subagent per task, prove each gate, and commit."
**Autopilot campaigns:** the autopilot session (`../autopilot/SKILL.md`) runs this doctrine
**inline** — it is the main session, executors are its subagents, and everything here applies
unchanged except human-gate handling: a gated task whose class the locked campaign contract
enumerates (`../references/campaign-contract.md` — e.g. a testnet deploy with the burner key) is
executed by the autopilot in its concierge capacity, with evidence into the gate ledger; a class
the contract does not enumerate pauses as a hard stop. Executor subagents still never run a gated
step, in either mode.
## Boot (before any task)
1. **Sync the project repo.** Resolve it per `../references/repo-bootstrap.md` (the kickoff's `REPO:`
field, else the working directory's remote — never the build-system kit checkout; by Step 2 it
always exists, so finding none means you're in the wrong directory, not that you should create
one). Fetch and check out the canonical branch; read the spec, plans, `conventions.md`,
and `manifest.json` **if present** — from the synced repo, not stale local files
(`../references/conventions.md`). The project repo is the single source of truth.
2. **Build the task list — prefer the manifest.** If a `manifest.json` exists, load its task DAG (the
validated projection of the plans — `../references/task-contract.md` §2); it also carries the
**`human_gate` flags** (deploy/key/fund tasks), which live only in the manifest, not in the §1 plan
grammar. If there is no manifest, parse the plan docs with the §1 grammar to get each task's
`depends_on`, `files`, `gate`, `provides`, `requires`, `effort`, `model_tier` (optional
`Model tier:` line), and `commit` — but there will be
**no `human_gate` flags to read**, so in that path you must derive human-gating from each task's
content yourself (build loop, step 2). Either source gives you the DAG; the manifest additionally
gives you the pre-validated safety flags — prefer it whenever it exists, and only build without one
when the plan has no deploy/key/fund tasks.
3. **Confirm the plan looks buildable** (quick pass: no placeholders, every `requires` has a provider).
A broken plan is a replan, not something to power through — route it back to the architect.
4. **Probe the tollgate's stack rows** — `docs/tollgate/*-tollgate.md` §Stack requirements (the
architect appended one row per CLI/runtime the plans assume; `../references/tollgate.md`) —
**plus matrix row 9 (Node ≥20 + npm) whenever the stack is JS/TS**, even if the stack section
omitted it. Run
each row's probe, record the results in the report, and **surface any FAIL now** (to the user,
with the row's fix hint — you probe and report, you don't install) before dispatching anything —
a missing toolchain caught at boot is a
five-minute install; caught inside a task it's a gate failure misdiagnosed as a flake. No report
or no stack section (non-campaign build) → skip.
5. **Resolve routing** (`../references/model-routing.md`). Read the tollgate report's **Routing**
- section; if none exists, run the row 18 probe yourself (harness identity via `CLAUDECODE`, one
- trivial subagent per tier reporting its resolved model id) and write the section. Install the
+ section; if none exists, run the row 18 probe yourself (harness identity via `CLAUDECODE`, the
+ effort mechanism — `per-spawn` or `variants-only` — one trivial subagent per tier reporting its
+ resolved model id, and the settings that defeat routing) and write the section. Take the tier
+ bindings, effort floors and ladder from it, and surface its warnings (`variants-only`, a set
+ `CLAUDE_CODE_EFFORT_LEVEL` or `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`) to the user once. Install the
executor effort-variant files into the project repo's `.claude/agents/` if absent (copy from
the kit checkout's `../references/agents/`, commit). A probe FAIL or a non-Claude-Code harness → `routing: inherit`,
- logged — dispatch exactly as before routing existed; never block on it.
+ logged — dispatch exactly as before routing existed; never block on it. Your own seat:
+ §Seat settings' orchestrator row (`../references/model-routing.md`) — state your model id at
+ boot.
## The build loop
Repeat until every task is `done` or the build is blocked on a human:
1. **Pick a ready task** — all its `depends_on` are `done`. (You may dispatch several independent ready
tasks in parallel — see *Parallelism* — but default to one at a time; it's simpler and the commits
serialize anyway.)
2. **Human-gate check FIRST — content-based, never flag-only.** Treat a task as human-gated if EITHER
its manifest `human_gate: true` flag is set **OR** its own steps/files/gate would deploy, broadcast
a signed transaction, move funds, or use a private key / mnemonic / secret. In the no-manifest path
there is no flag, so this content check is the **only** guard — read the steps yourself, the way the
§4 plan-reviewer does. For any human-gated task: do **not** dispatch it to build-and-run — prepare it
if useful, then **pause and hand it to the human** to execute. When unsure whether a task moves funds
or touches a key, pause and ask rather than dispatch. Never move funds, sign, or deploy autonomously
(`../references/conventions.md` §Safety). (In an autopilot campaign, "hand it to the human"
follows the autopilot note above: a contract-enumerated class is executed by the autopilot in
its concierge capacity, evidence into the ledger; any other gated task still pauses.)
3. **Dispatch a subagent as the executor.** Spawn it (Task/Agent tool) with exactly the context
`../references/task-contract.md` §3 specifies — assemble the prompt yourself:
- the `executor` kit (`../executor/SKILL.md`) as its doctrine,
- `conventions.md` inline,
- the **full task block, verbatim** (its steps, `Files:`, `gate`),
- every signature in this task's `requires`, pasted from the providers' `provides`.
Bind the spawn's knobs from the routing resolution (boot 5; `../references/model-routing.md`):
- the agent type is the effort variant `executor-<task.effort>`, and the `model` argument is
+ the **dispatched effort** is `task.effort` raised to the bound tier's floor (never lowered); the
+ agent type is the effort variant `executor-<dispatched effort>`; the `model` argument is
`task.model_tier`'s campaign-verified binding (absent field = `standard`; the pin rule makes
- gated/security/`xhigh|max` tasks `top` regardless). **Log the resolved model in the dispatch
- record** — requested ≠ resolved is drift you want to see. Under `routing: inherit`, spawn the
- plain subagent as before — this is the native-mode equivalent of the kernel's CLI flags
- (`../references/task-contract.md` §6 is the external-pool mapping and does not apply here).
+ gated/security/`xhigh|max` tasks `top` regardless); and when the Routing section shows
+ `per-spawn`, pass the dispatched effort as the per-spawn `effort` too. **Log the requested tier,
+ the resolved model and the dispatched effort in the dispatch record** — requested ≠ resolved is
+ drift you want to see. Under `routing: inherit`, spawn the plain subagent as before — this is
+ the native-mode equivalent of the kernel's CLI flags (`../references/task-contract.md` §6 is the
+ external-pool mapping and does not apply here).
Give it **worktree isolation only when you
are running tasks in parallel**; a single sequential task builds in the working tree.
4. **Read the subagent's `RESULT`.** `DONE` (with `FILES` + `GATE` output) or `BLOCKED` (with `REASON`).
Treat it as **evidence, not authority** — you verify everything yourself next.
5. **Re-run the gate yourself and read the output with your own eyes.** Never trust a claimed pass.
A green you didn't run poisons every dependent task.
6. **Scope-check.** Only the task's declared `Files:` (plus incidental lockfiles) may have changed. Any
other change fails the task — it's a plan gap or executor drift, not something to wave through.
7. **Review the diff.** You are the reviewer: does the code do what the task's steps say, honor the
`requires` signatures exactly, and keep the gate honest (no weakened test, no stubbed module)?
8. **Commit** exactly the declared files with the task's `commit` message (the single authored source
is the plan's Step-5 message). Mark the task `done`. Move on.
## When a task fails (you are the mastermind now)
Don't power through. Classify from evidence (re-read files, re-run the gate) per
`../mastermind/SKILL.md`, then act inline:
- **Flake / environment** (transient, racey, missing toolchain) → re-dispatch as-is, or fix the
environment and re-dispatch.
- **Executor miss** (task is fine, implementation wrong: off-by-one, wrong import, misread signature) →
re-dispatch with a **concrete hint** in the prompt. One good hint beats three blind retries.
When routing is active, retries climb the **escalation ladder**
- (`../references/model-routing.md`): retry 1 = as-is + the hint; retry 2 = +1 effort step;
- final retry = +1 model tier (caps `max`/`top`; the pin rule tracks the *dispatched* effort, so a
- retry escalated to `xhigh|max` runs at `top` immediately). Only this class escalates — flakes
- re-dispatch as-is, and plan bugs go to the architect, never up-tiered through.
+ (`../references/model-routing.md` §Dispatch binding — the authority; this is a summary): retry 1
+ = as-is + the hint; then a `standard` task moves up a model tier before it moves up an effort
+ step (`tier-first`), while `fast` and `top` tasks move up effort first — every rung at the
+ landing tier's floor, and any dispatch at `xhigh|max` runs at `top`. Only this class escalates —
+ flakes re-dispatch as-is, and plan bugs go to the architect, never up-tiered through.
- **Plan bug** (the task block itself is wrong: undeclared file, `requires` that no task `provides`,
steps that contradict the gate) → stop and **route back to the architect** to fix that task, then
re-plan the affected subtree. Never patch the plan freehand mid-build.
- **Needs a human** (secrets, deploy, funds, or genuinely ambiguous spec) → pause and ask.
Give a stuck subagent a bounded number of retries, then escalate rather than loop.
## Mid-build regeneration
If the architect regenerates the plans/manifest during the build, follow the regeneration protocol in
`../references/roles.md`: quiesce in-flight tasks whose `id`/`files`/`gate`/`provides` changed,
re-dispatch them fresh, and rebuild any task that consumed a `provides` signature that just changed.
Prefer to land regenerations at a checkpoint (no task in flight).
## When the build is green (the hand-off you owe the user)
Push, then report: what was built, every gate's proof, and — explicitly — the **human-gated tail**
that remains (paused `human_gate` tasks plus the campaign gates that never enter a manifest: faucets,
provider accounts/API keys, wallet setup, the submission). A concierge **preflight pass** may
already have run in parallel — check `docs/gates/*-gate-ledger.md`: done rows (wallet, faucets,
keys) come off the tail; report only what's genuinely left. Then **offer the two post-build seats**:
**Step 2.5 `demo-studio`** (`../demo-studio/SKILL.md`, kickoff `../prompts/INVOKE_DEMO_STUDIO.md`) to
record the demo video — it must land before the submission, since it fills the demo-video URL — and
**Step 3's closing pass**, the `gate-concierge` (`../gate-concierge/SKILL.md`, kickoff
`../prompts/INVOKE_GATE_CONCIERGE.md`, `MODE: closing`), which
inventories those gates into the committed ledger with the exact tools per gate and executes each only
on the user's per-gate "continue". **Offer them — never launch either or run its gates/recording
yourself**; starting a post-build seat is the user's call, same as every consent in this kit. (In
an autopilot campaign the autopilot dispatches both itself under the locked contract — that start
WAS the user's call, given at lock; the offer step is guide-mode's.)
## Parallelism (optional)
Dispatch independent ready tasks concurrently — spawn each subagent with `isolation: worktree` so their
edits don't collide, then **serialize the gate-and-commit step** (verify and commit one worktree's task
at a time on the canonical branch, re-checking each against current `HEAD`). Only parallelize genuinely
independent tasks (disjoint `files`, no `depends_on` between them). When in doubt, go sequential — a
hackathon build is rarely bottlenecked on task throughput, and sequential keeps the history clean.
## What you do NOT need in this mode
No external kernel binary, no `npm run kernel`, no account rotation (one Claude Code account), no
`provider` pinning (you are the only provider), and no CLI effort flags (effort rides the executor
- effort-variant agent type and the model rides the per-spawn `model` argument — boot 5 and build-loop
- step 3; `../references/model-routing.md`). The `manifest.json`, `mastermind`, and `executor` **headless-delivery** machinery from the
+ effort-variant agent type (plus per-spawn `effort` where available) and the model rides the
+ per-spawn `model` argument — boot 5 and build-loop step 3; `../references/model-routing.md`). The
+ `manifest.json`, `mastermind`, and `executor` **headless-delivery** machinery from the
external-pool config is optional scaffolding — you reuse the `executor` kit as the subagent's doctrine
and the `mastermind` taxonomy as your failure classifier, but nothing is "delivered by a kernel."
## Boundaries
- **You orchestrate and review; subagents write the product code.** Prefer to dispatch even small tasks
— the test-first → prove-gate → scoped-commit discipline is what makes the build trustworthy and
auditable. Reach in to hand-edit only for orchestration glue, never to bypass a gate.
- **Never fake green, never weaken a gate**, in your own verification or a subagent's.
- **Never touch secrets; never run a `human_gate` step.** Same rule as every pipeline role — with
the one scoped exception defined in `../references/conventions.md` §Safety's third form: an
autopilot session executing a contract-enumerated gate class in its concierge capacity (the
autopilot note above). Executor subagents never, in any mode.
- **The repo is the single source of truth.** Commit and push; nothing important stays local.