Ship Epic

---
description: Ship one build-plan epic end-to-end under the gated TDD pipeline (test-first → implement → make test + >90% coverage → parallel reviewers → PR). Usage: /ship-epic <epic-number>
argument-hint: <epic-number>
allowed-tools: Read, Grep, Glob, Bash, Edit, Write, Task, TodoWrite
---

# Ship Epic $1

You are the orchestrator for **epic $1** of the Cuvée build plan. Run the gated pipeline below in order. The coverage gate is **>90% per branch** and the reviewer gates are **all-must-pass** — **never lower a gate to make it pass.** If you cannot pass a gate, fix the code and re-run; if genuinely blocked, STOP and report the blocker rather than weakening the bar.

Track every step with TodoWrite so progress is visible.

## a. Load the spec
- Read `docs/RUNBOOK.md` "Prompt $1" for the epic's **branch name, scope, and acceptance criteria (AC)**.
- Read `CLAUDE.md` §8 (Domain Invariants), §10 (FR map), and §11 (Build Plan row for epic $1) for the **FRs and invariants** this epic must satisfy.
- Restate, as a checklist: the exact branch name, the enumerated ACs, and the FRs/invariants in scope. Confirm epic $1−1's gates are met before starting (do not skip the dependency spine).

## b. Branch
- Create and switch to the epic's feature branch named exactly as RUNBOOK specifies (e.g. `feat/foundation`). If not in a git repo, STOP and tell the user to `git init` first.

## c. Write failing tests first
- Dispatch the **edge-case-hunter** subagent (Phase 1 only) to enumerate the applicable edge cases + Domain Invariants for epic $1.
- Dispatch the **test-author** subagent with: the ACs, that edge-case list, and the in-scope FRs/invariants. It must write **exactly one test per acceptance criterion and one per applicable edge case**, placed across the pyramid (unit on `packages/core`, integration on `apps/api` via Testcontainers, web component + Playwright e2e + axe a11y where a screen exists), each tagged `// AC-<n>` / `// EDGE:` / `// INVARIANT:`.
- Confirm the new tests **FAIL** for the right reason before proceeding.

## d. Implement to green
- Implement per `CLAUDE.md` standards and "where code goes" (§4): domain logic → `packages/core`; **never business logic in `apps/web`**; **never a vendor SDK outside `packages/adapters`**.
- Use **parallel `implementer` subagents ONLY for genuinely independent modules** within the epic (e.g. a core calculator and an unrelated adapter). If modules share contracts or files, implement directly or sequentially to avoid conflicts. Never let the implementer modify the tests.

## e. Gate 1 — tests + coverage
- Run `make test`. Require **all suites green** (lint + typecheck + build + unit + integration + web + e2e + a11y) AND **coverage >90%** on the branch.
- If red or coverage <90%: fix and re-run. Do not weaken or skip tests; add real tests for any uncovered lines that represent real behavior.

## f. Gate 2 — parallel review
Dispatch IN PARALLEL (single message, multiple Task calls) and collect each PASS/FAIL report:
- **code-reviewer** (org, style, typed errors, idempotent jobs, no N+1, adapter boundaries)
- **security-auditor** (brand-scoped deny-by-default authz on every new endpoint, zod at boundaries, no client-exposed secrets, Redis rate limiting, PII/enrichment encryption, CCPA deletion cascade)
- **edge-case-hunter** (Phase 2: every enumerated edge case + invariant has a PASSING test)
- **ux-a11y-reviewer** — **only if the epic touches `apps/web`** (loading/empty/error, one primary action, design tokens, keyboard nav, axe-clean)

## g. Fix loop
- If ANY reviewer returns FAIL, OR coverage <90%, OR any acceptance criterion / edge case is unmet: fix the code (re-dispatch test-author for missing tests, implementer for fixes) and **repeat from (e)**. Never lower the gate to pass. Loop until everything is green.

## h. Ship
Only when **all suites are green, coverage >90%, and every reviewer PASSES**:
1. Commit with a conventional-commit message referencing the epic and FRs.
2. Open a PR (via `gh`) whose description lists:
   - the **FRs satisfied**,
   - the **coverage number**,
   - a **checklist mapping each acceptance criterion → its test** and **each edge case/invariant → its test**,
   - the reviewer verdicts (all PASS).
3. Report exactly: `EPIC $1 DONE`.

If at any point a gate cannot be met, STOP and report what failed and why — do not ship a partial or gate-lowered epic.