/ship-issue

1. 0

   Stage 0 — Intake & plan

   Crew: (agent: Plan)

   1. Resolve the number: gh issue view <issue> --json number,title,body,labels,url. If <issue> is a "story number" that differs from the GitHub issue number, map it via the epic checklist issue or the README scope table, then confirm the real issue number.
   2. Spawn ONE Planner (subagent_type: Plan). Give it the full issue body + repo README + CLAUDE.md. Ask it to return, as structured data:
      • a build plan broken into independent work units with non-overlapping file ownership (so builders can run in parallel without collisions),
      • explicit, checkable acceptance criteria (functional + the quality bar above), including the project's Definition of Done where it states one (tests, docs/changelog, non-functional bars),
      • a test/validation plan (the commands the SDET should run: unit tests, lint, type-check, build/compile/import — whatever this repo uses),
      • a list of files expected to change,
      • domain classification flags that decide which specialists the board pulls (set each independently — a story can trip more than one):
        • IS_UI_STORY = yes/no — does it create/modify on-screen UI (screens, HUD, panels, overlays, menus, components, styling)? Gates ux-ui-designer.
        • IS_VISUAL_STORY = yes/no — gate the art-director on the PROJECT'S DOMAIN, not merely on whether a story touches pixels. Set it only when the project's actual deliverable is rendered visual art — a game's world/sprites/shaders, illustration/brand/motion assets, generative imagery — and this story touches it. A conventional app (finance, media, SaaS, dev-tooling) whose only visual surface is its interface is a UI story (ux-ui-designer), NOT an art story: the art-director reviews pictures judged as art, not application chrome. Most projects never set this — when in doubt, prefer IS_UI_STORY and leave the art-director out.
        • IS_ARCH_SIGNIFICANT = yes/no — does it add a new subsystem, change a persisted data/schema format, or cross-cut many modules in a way a narrow code review would miss? Gates architect.
        • IS_SECURITY_SENSITIVE = yes/no — does it touch authn/authz, untrusted input, secrets/credentials, crypto, file/network/OS access, or dependencies? Gates security-engineer.
   3. If the plan reveals the issue is too big/ambiguous to finish autonomously, stop and tell the user what's blocking — otherwise continue.
2. 1

   Stage 1 — Isolate

   Crew: (orchestrator, deterministic — no agent)

   git -C <repo> fetch origin
   git -C <repo> worktree add <WORKTREE_DIR> -b <BRANCH> origin/<BASE_BRANCH>

   All build/fix work happens inside <WORKTREE_DIR> so the base branch and the user's checkout stay clean. Pass the absolute worktree path to every agent.

3. 1.5

   Stage 1.5 — Design specs

   Crew: (specialist agents — each only if its flag is set)

   BEFORE any Builder runs, spawn whichever apply, in parallel (a story can need more than one). Each writes NO code — it returns a spec document, fed verbatim to every Stage 2 Builder whose files its work governs. Skip this stage entirely when none of the flags are set.

   • ux-ui-designer (only if IS_UI_STORY) — a UI design spec: wireframes, a shared-token/theme plan, responsive container layout (no hardcoded positions), focus order + interaction states, and accessibility/contrast, consistent with the project's design system.
   • art-director (only if IS_VISUAL_STORY) — a concrete, numeric art direction (palette values, dimensions, light angle/ratio — whatever the medium needs) held to the project's visual bar, so a Builder implements what's meant, not a guess.
   • architect (only if IS_ARCH_SIGNIFICANT) — the structural approach: module boundaries and ownership, and the schema/versioning/migration strategy if persisted data changes.
4. 2

   Stage 2 — Build

   Crew: senior-engineer (agents: senior-engineer × N, parallel)

   • Spawn one Builder (subagent_type: senior-engineer) per independent work unit from the plan, in a single message so they run concurrently. Each Builder is told: its exact file ownership, the acceptance criteria it must satisfy, the worktree path, any Stage 1.5 spec that governs its files, and to match existing code style/idioms.
   • Builders write code only — they do not commit, push, or open PRs (the orchestrator owns git).
   • After they report done, verify the files on disk yourself (Read/Grep). Never trust a "done" report blindly.
5. 3

   Stage 3 — Self-check before PR

   Crew: sdet (agent: sdet)

   • Spawn the SDET (subagent_type: sdet) to run the test/validation plan against the worktree: unit tests, linters, type-checks, and — if the toolchain exists — a real build/compile step (whatever this repo uses: e.g. npm test && npm run build, cargo test, pytest -q, go build ./..., make check). If the toolchain is absent, it does a rigorous static pass and says so explicitly in the PR.
   • If self-check fails, loop a Fixer (subagent_type: senior-engineer) until green (counts toward MAX_FIX_ROUNDS). Only open a PR once self-check passes — never open a known-red PR.
6. 4

   Stage 4 — Commit, push, open PR (orchestrator)

   git -C <WORKTREE_DIR> add -A
   git -C <WORKTREE_DIR> commit -m "<type>: <summary> (#<issue>)"   # + required trailers
   git -C <WORKTREE_DIR> push -u origin <BRANCH>
   gh pr create --base <BASE_BRANCH> --head <BRANCH> \
     --title "<type>: <issue title> (#<issue>)" \
     --body  "<what changed, how validated, 'Closes #<issue>', trailers>"

   The PR body must include: summary, the acceptance criteria as a checklist, how it was validated (and any validation that could NOT be run locally), and Closes #<issue>.

7. 4.5

   Stage 4.5 — CI gate: wait for green, fix if red (orchestrator + Fixer)

   Gate: ⛔ HARD GATE

   When there is no local toolchain to fully validate, CI is the ONLY real runtime gate — the Stage 3 SDET pass is static and WILL miss things (parse errors, lint-as-error, dependency/version drift). You MUST confirm CI is green on the pushed head before the acceptance board runs. Never assume a push is green. (If the repo has no CI, say so and treat the SDET pass as the gate, explicitly noting the reduced assurance.)

   1. Wait for the checks to finish on the PR head (poll, don't guess):

      until s=$(gh pr checks <PR#> 2>&1 | head -1); st=$(echo "$s" | awk '{print $2}'); \
        [ "$st" != "pending" ]; do sleep 15; done; echo "$s"

      (Long-running: launch as a background command / until-loop so you're notified on completion — do not chain foreground sleeps.)

   2. If any check FAILS, pull the actual failure log — do not speculate:

      gh run view <run-id> --log-failed | grep -iE "FAIL|error|Parse|::error" | head -60

      Diagnose the real cause from the log. Before pushing a fix, grep the whole changeset for sibling instances of the same failure class so you fix them all in one round instead of burning several.

   3. Dispatch a Fixer (subagent_type: senior-engineer; or fix directly if it's a trivial, unambiguous one-liner you've root-caused from the log) in the worktree, commit with the required trailers, push to the same branch. This counts toward MAX_FIX_ROUNDS.
   4. Re-poll CI (back to step 1) on the new head. Repeat until green or MAX_FIX_ROUNDS is exhausted — if still red after that, stop and escalate to the user with the failure log; do not proceed to acceptance on a red PR.
   5. Only once CI is green do you proceed to Stage 5. Carry the confirmed-green run link into the final report.
8. 5

   Stage 5 — Acceptance board

   Crew: (specialist agents, reviewing the PUSHED PR head)

   Spawn these in parallel against the PR head commit (they review exactly what will merge). The two core reviewers always run; each specialist runs only when its flag is set:

   • product-manager (always): checks every acceptance criterion AND the quality bar (from the repo's README/CLAUDE.md). Returns ACCEPT / ACCEPT-WITH-NITS / REJECT with specifics per criterion.
   • sdet (always): re-runs the validation plan against the PR branch; returns PASS / FAIL with a severity-tagged defect list.
   • ux-ui-designer (only if IS_UI_STORY): reviews the pushed head against the Stage 1.5 spec and the UI bar — shared-token/theme usage (not per-component override sprawl), responsive layout, focus navigation, interaction states, contrast/readability. If it cannot actually render the UI, it reviews statically and MUST flag the PR "needs a human visual pass" — carry that into the report.
   • art-director (only if IS_VISUAL_STORY): renders the actual change via the project's render/preview harness (if one exists) and reviews the produced output against the Stage 1.5 direction and the visual bar — the render, not the source. If it cannot render, it says so and flags "needs a human visual pass".
   • architect (only if IS_ARCH_SIGNIFICANT): reviews structural fit, coupling/blast radius, and schema/migration safety.
   • security-engineer (only if IS_SECURITY_SENSITIVE): threat-models the change (STRIDE / OWASP) — broken access control, injection, secrets/crypto, vulnerable deps — and returns severity-ranked findings with the exploit path; a credible Critical/High is a blocking defect.

   Decision (each specialist participates only when its flag is set):

   • All spawned reviewers ACCEPT/PASS (nits allowed) → go to Stage 7.
   • Any REJECT / FAIL → Stage 6.
9. 6

   Stage 6 — Remediation loop

   Crew: senior-engineer (agent: senior-engineer as Fixer)

   • Spawn a Fixer (subagent_type: senior-engineer) to address every blocking item (REJECT reasons from any Stage 5 reviewer + FAIL defects). Commit + push to the same branch. Then re-run Stage 5 on the new head.
   • Repeat up to MAX_FIX_ROUNDS. If still not green after that, stop and escalate to the user with the outstanding blockers — do not merge a failing PR.
10. 7

    Stage 7 — Follow-up issues (orchestrator)

    • Take every non-blocking nit (from any "WITH-NITS" verdict and low-severity SDET findings) and file each as its own GitHub issue: gh issue create with a priority:low / tech-debt label (create the label if missing), a clear title, context, and a link back to this PR.
    • Do NOT let nits block delivery; they become tracked follow-ups.
11. 8

    Stage 8 — Deliver (orchestrator)

    • If MERGE_MODE=manual (default): stop here. Post a completion comment on the PR (what shipped, how validated, the green CI link, follow-ups filed) and hand the user the PR link to merge. Leave the worktree in place, or remove it and keep the branch — your choice, state which.
    • If MERGE_MODE=auto: gh pr merge <BRANCH> --squash --delete-branch, then confirm the issue auto-closed (else gh issue close), tick the epic checklist box if any, remove the worktree (git -C <repo> worktree remove <WORKTREE_DIR>), and post the completion comment.

Final report to the user