build-epic

build-epic

buildwriteseither

Use this when: you want to build a whole epic, sprint by sprint

Problem it solves — An epic is too big to hold in one head. This executes it sprint by sprint — running each via build-sprint, verifying between, shipping each sprint's own PR — and closes the epic only when the last sprint lands.

Used in workflows: Build the epic

Build epic

Execute an epic to completion — sprint by sprint, never as one giant batch (too big, and it skips the per-sprint verify that stops a broken sprint burying the rest). build- here means build the implementation; the epic's tree was already created by to-issues and placed/ordered by organise.

The epic is a tracking parent issue, not a git branch — it never merges (ADR-0005). Each sprint cuts its own sprint/<slug> branch off main, ships its own Sprint PR to main, and is independently shippable; the epic's progress bar advances as its sprints close. So an epic can be run start-to-finish here, or left open while you ship one sprint now and the rest later.

Task class: execute. Tools: gh, git/PRs, and build-sprint (delegated per sprint). Runs in-thread (orchestrates one sprint at a time). Artifact: every sprint in the epic built, verified, and shipped to main; the epic issue closed.

PLAN — set the cadence once (front-load)

Ask up front: hands-on or hands-off? (be-caveman + be-complete stay on either way.)

• Hands-on — review each Sprint PR (→ main) as it lands (you QA each layer).
• Hands-off — auto-merge each gated Sprint PR into main on a green gate, then move to the next sprint. (Auto-merge only on a green gate — there is no epic branch to stage on; each sprint ships to main on its own.)

This is the skill — sequential, verify between

1. Take the epic's sprints in dependency order (organise set order + deps).
2. Run each via build-sprint → its Sprint PR (base main) → verify. (build-sprint's pre-PR QA gate runs qa-everything over each sprint's diff and fixes findings before its PR — inherited per sprint, not repeated at the epic level.) Each Sprint PR body follows docs/agents/pr-writing.md — plain lead, a > [!IMPORTANT] decision alert when the sprint made a decision, emoji-anchored ## headings, and footnote attribution (never an inline line).
3. Verify between sprints — never stack the next on an unverified one. Stop on a red gate and surface it (circuit-breaker), don't grind past it.
4. Apply the cadence: hands-off auto-merges the gated Sprint PR to main; hands-on pauses for your review. (A sprint's Task issues close on the sprint-branch merge via the close-sprint-tasks Action; the Sprint issue closes natively when its Sprint PR reaches main.)
5. At epic done → close the epic. After the last sprint merges, confirm every child sprint is closed (gh api repos/{o}/{r}/issues/<epic>/sub_issues) and close the epic (gh issue close <epic>). The epic is closed only by completing it here — never auto-closed by a mechanical trigger, since an open-ended epic must not slam shut mid-flight (ADR-0005).

Hands-off — Workflow (when appropriate)

In hands-off mode you may orchestrate the epic via a Workflow — running build-sprint per sprint, verifying between, and auto-merging each gated Sprint PR to main before the next. Hands-on stays sequential — you review each Sprint PR.

Epic-level stays sequential (sprints have dependencies — verify between, never parallel). The model-tiered fan-out of cheap workers happens inside a sprint, owned by build-sprint per the orchestration contract (docs/agents/orchestration.md); the epic just sequences the sprints.

Where it sits

Upstream: to-issues (creates the typed tree) + organise (places, orders, deps). This executes; build-sprint runs one sprint. NOT to-issues / organise / find-untracked-work. Model + native-GitHub mapping: docs/brainstorms/2026-06-04-backlog-organisation-model.md; branch flow + completion semantics: docs/adr/0005-sprint-epic-branch-flow-and-completion.md. </content>