orchestrate-build

name	orchestrate-build
license	MIT
description	Drive a decomposed spec to completion across fresh contexts: SETUP a dedicated worktree, run each ticket end-to-end through implement-spec in a fresh context, update the durable ledger, report progress, pause for intervention at ticket boundaries, and finish with a whole-build capstone verification. The execution half of a multi-session build; pairs with decompose-spec.
inputs	[{"name":"ledger","required":false,"description":"Path to the seeded build ledger (from decompose-spec). One of `ledger` or `spec` is required."},{"name":"spec","required":false,"description":"If no `ledger` is given, the spec to decompose first — orchestrate-build invokes decompose-spec, then drives the resulting ledger. One of `ledger` or `spec` is required."},{"name":"build_worktree","required":false,"description":"Absolute path of the dedicated build worktree, created at SETUP off the pinned base. Never an existing in-use worktree. Default: a sibling `<repo>-<build_name>`."},{"name":"pinned_base_sha","required":false,"description":"The commit the whole build stack forks from. Default: the resolved tip of the repo's default branch. Recorded as a SHA (not a ref) so every ticket forks from a known base."},{"name":"dispatch","required":false,"description":"How each ticket gets its fresh context: 'headless' (a fresh top-level agent process per ticket — the recommended automation on any CLI harness, via scripts/drive-build.sh), 'subagent' (an isolated sub-context per ticket — where the harness has one), or 'manual' (print the fresh-session command; the human runs it). Default: auto-detect down that ladder."},{"name":"agent_cmd","required":false,"description":"For dispatch=headless: the harness's headless-invocation command (e.g. 'claude -p', 'goose run -t', 'codex exec', 'gemini -p'). Default: discovered from PATH by drive-build.sh."},{"name":"autonomy","required":false,"description":"Oversight granularity: 'auto' (advance ticket-to-ticket, report only), 'checkpoint' (auto-advance green tickets; pause at SETUP, CAPSTONE, blocks, and every Nth ticket if set), or 'manual' (approve every ticket). Default 'checkpoint'. Automating fresh sessions is orthogonal to keeping a decision gate — this setting is how the human keeps the keys without re-invoking per ticket."},{"name":"parallel","required":false,"description":"Default false. When false, tickets run strictly one at a time (single-threaded writes). When true, out-of-chain / genuinely disjoint tickets MAY run concurrently — only safe for work that shares no implicit decisions (e.g. a different repo)."}]

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.