orchestrate-build

Orchestrate Build

Drive a decomposed spec to completion across fresh contexts — one ticket at a time, each executed end-to-end by implement-spec, with a durable ledger as the only cross-session memory — reporting progress and pausing for intervention, and finishing with a whole-build capstone. This is the execution half of a multi-session build; decompose-spec produced the plan, implement-spec is the per-ticket worker.

The mental model. Three roles, cleanly separated. State lives on disk (the ledger). Cognition lives in fresh, disposable contexts (each ticket, the capstone). Sequencing is a dumb loop that reads the ledger, dispatches the next unit to a fresh context, and writes the ledger back. Because sequencing holds no state and cognition is always fresh, nothing accumulates context across the build — the thing that rots long autonomous runs is designed out, not merely managed.

Why a fresh context per ticket, and the one hard constraint

A fresh context can only be created from outside the context being refreshed — no prose can make a running context clean itself. So "run the next ticket fresh" always binds to one of four external initiators, and this skill degrades gracefully down that ladder to whatever your harness offers (see Dispatch below):

1. a sub-agent primitive (isolated child context), 2. a headless process loop (drive-build.sh),
2. a scheduler re-invoking a headless run, 4. a human re-invoking (the universal floor).

The spine of this skill — the ledger, the loop, the capstone — is harness-agnostic prose that even a human with a terminal can execute. Only the dispatch step binds to harness capability.

0. Orient (every invocation)

• Resolve the ledger. If ledger was given, read it. If only spec was given, invoke the decompose-spec skill (skills/decompose-spec/SKILL.md) first, then use the ledger it seeds.
• Confirm the working checkout. If a buildWorktree is set in the ledger, confirm cwd is it (git rev-parse --show-toplevel); if not, and you are the orchestrator process, cd there — a command run in the wrong worktree corrupts the wrong branch.
• Resolve the memory root + mode. bash <skills>/build-memory/scripts/memory-root.sh "$buildWorktree" prints mode=<committed|scratch> and root=<abs path>. In committed mode the ledger is <root>/LEDGER.md, committed and travelling with the chain tip (a sibling worktree reads its own tip, not the main worktree's copy); in scratch mode it is the legacy gitignored ledger, unchanged.
• Read CURRENT STATE → nextTicket, lastCompleted, blockedOn, pauseRequested, returnPass, manifest, memoryRoot, chainTip, autonomy. The manifest: key names the plan (docs/tickets/00_MANIFEST.md); the tickets themselves are the contracts the worker loads.
  • Legacy ledger (PHASE PLAN present, manifest: absent): drive it from its own PHASE PLAN. On nextTicket: CAPSTONE, run decompose-spec mode=extend tail=full to convert it to v2 (write the manifest if missing, append the standard tail rows) and continue — unless legacy_capstone=true, which runs the one-context procedure retained verbatim in modes/legacy-capstone.md (BM-COMPAT-03).
  • projectStatus: DONE → print the completion summary (every ticket PR + the tail PRs) and STOP.
  • blockedOn non-empty → surface it, ask how to proceed, STOP. Never guess past a block. (A pending gate is NOT a block — it is a RETURN PASS row; §2.1.)
  • pauseRequested: true → report where the build stands and STOP (the human asked to intervene).
  • nextTicket: SETUP → §1. Otherwise → §2 (the tail rows CAP.*, REC.*, DOC.* are ordinary chain tickets; there is no special CAPSTONE unit in v2 — see §3).
• Determine the dispatch tier from dispatch (or auto-detect: headless if a supported agent CLI is on PATH, else subagent if the harness exposes one, else manual). Record it.
• Check dispatch-vs-sizing coherence. Read the ledger's dispatchTarget (what decompose-spec sized the tickets for). A subagent worker cannot compact, so it has a hard one-window ceiling; a headless worker can compact. If the tickets were sized for headless but you can only dispatch via subagent, they may overflow — raise the dispatch tier, or re-run decompose-spec with dispatch_target=subagent. Warn and let the operator decide rather than proceeding into likely overflow.