Stack Ship

Stack Ship

Drive a design or feature goal from intake to "all PRs merged" with near-zero steering. The orchestrator is a router, not a worker: it owns the plan, state, delegation, and author-facing decisions; subagents own execution and return structured digests.

The guardrails are non-negotiable — read them before acting.

Throughout this skill master denotes the repository's default branch; substitute the real default (main, etc.). Auto-merge is armed only on a default-branch-based PR — which, in a stack, is exactly the front PR.

The one-paragraph model

You (orchestrator) turn a goal into an acceptance-criteria list and a stacked PR plan (api → utils → stitch, smallest single-intent PRs). You spawn a deliver-pr sub-agent per PR to run the full single-PR pipeline and open the PR. You drive whichever PR currently sits on master (the front of the stack) to merged by pointing the relay pr watch runtime at it with yourself as the owner and running pr-monitor once for each digest it wakes you with, and you add only the stack-specific front-advance and cascade. You never write code, never post in your own voice, never approve, never make author-owned design decisions, and never install unreviewed tooling — you route work and surface questions. You stop when every acceptance criterion is met and every PR is merged.

When to use / not use

• Use for a multi-PR feature with a clear goal and a discoverable current→desired delta.
• Use again / resume for an active stacked delivery run. On resume, reconstruct state, make sure exactly one watcher is running for the current front project, and handle any digest it already recorded — the author should not have to type a special "monitor-tick mode" prompt.
• Don't use for a single small change (just do it), or when the goal/delta is too vague to write acceptance criteria — first run brainstorming / ask the author to sharpen the goal.

Operating principles (the orchestrator's contract)

1. Delegate everything executable. If a step writes code, runs tests, posts a comment, rebases, opens/updates PRs, posts GitHub comments, resolves threads, or reads more than a couple of files, it belongs in a subagent. The orchestrator reads digests, updates state files, and decides what to delegate next. Model: spawn every subagent with the default configured model (inherit it — don't pin a tier); only override the model when the user has stated a preference for these subagents.
2. One state writer. The orchestrator is the canonical writer for the run's state files. Worker subagents return structured digests; they do not append to shared state files directly. If a delegated loop controller owns a tick, it assumes this same singleton state-writer role for that tick.
3. State lives in files, never only in context. Every tick and every PR is idempotent and resumable because the truth is on disk (state files): human-readable Markdown plus machine-readable state.json.
4. One writer per branch, ever. Never run two subagents that push the same branch at once. Serialize. (A concurrent double-push was a real near-miss.)
5. Surface, don't decide. Author design/scope calls get two things: a PR reply asking for input (marked, on the thread), and a row in the pending-decisions table the orchestrator keeps in questions.md. Never a unilateral decision. When unsure whether something is a fix or a decision, treat it as a decision and surface it. The orchestrator shows the author this table — open decisions only — whenever it changes; resolved decisions drop off the table.
6. Never impersonate. Every PR comment is prefixed 🤖 <agent> on behalf of <author>, and PR bodies/status posts disclose agent authorship instead of implying the author wrote them.
7. Approval is the only merge gate. Auto-merge, armed only on master-base PRs, fires on a genuine human code-owner approval. Never self-approve, never gh merge directly.
8. Approved tooling only. Use only approved/verified skills, hooks, MCP integrations, and tools already available in the environment. Never install or run unreviewed third-party plugins/hooks/scripts from the internet during this workflow.
9. Set the goal in every harness. The session's launch input must set /goal <the user's requested outcome> using the original task, not instructions to run the stack-ship workflow. Relay project artifacts and relay state remain the durable source of truth for executing and resuming the workflow. Never replace this native goal with the file-only fallback. Detect recurring-run capabilities once and record them in state.json. Front-PR coverage does not depend on them: relay pr watch observes the front PR and wakes you, so a /loop or an approved scheduler is only ever a convenience for your own orchestration, never the thing that watches the PR.

Workflow

Phase 0 — Intake & decomposition → references/decomposition.md

Input is either a full design doc or a goal + a way to find the current→desired delta. Produce, in the project state dir:

• goal.md — the goal in one paragraph + acceptance criteria (a checklist that defines "done"; this is your /goal and final verification gate).
• plan.md — the stacked PR plan: ordered PRs, each with intent, scope, dependencies, and which layer it is. Decompose along the interface-first seam: api → utils → stitch — define the contract/types/surface first (plumbed but unconsumed), then the logic/helpers that operate on it, then the integration that wires it into the running system, then aggregation/telemetry. Mark which PRs are independent (parallelizable) vs dependent (pipelined). The breakdown is described in full in decomposition.md — it's self-contained, no repo-specific files required.
• Initialize state.json, progress.md, tradeoffs.md, follow-ups.md, questions.md. Record runtime capabilities in state.json (/goal, /loop, scheduler, monitor mode) before building. Decomposition is a planning act — do it yourself or via a single Plan subagent, then get author sign-off on plan.md if the design left genuine ambiguity (use AskUserQuestion); otherwise proceed with the smallest-PRs default and log the call in tradeoffs.md.

Phase 1 — Build the stack → references/pr-build-cycle.md

For each PR, spawn a deliver-pr sub-agent that runs the full single-PR pipeline (clarify → plan → implement → simplify → review → validate → open-pr) in that PR's worktree and opens the PR. You do not re-implement those phases — deliver-pr owns them; you hand it this PR's intent, scope, acceptance criteria, branch, and base. Parallelize independent PRs (one sub-agent each, isolated worktrees); pipeline dependent ones (the API surface must land before consumers compile). deliver-pr surfaces blocking questions back to you rather than guessing; you route them to the pending-decisions table + the author and pause that PR only.

Phase 2 — Monitor the front PR → references/monitor-loop.md

The PR currently based on master (the front of the stack) is watched by the relay pr watch runtime, started by you for the front project and pointed at your session:

relay pr watch start <front-project-slug> --mode stack --owner <stack-orchestrator-slug>

The watcher observes deterministically and wakes you when the front PR needs attention; you then run the pr-monitor skill once for that digest (it triages, delegates remediation to pr-fix, re-arms auto-merge, and re-observes). Exactly one watcher per front PR, and never a watcher on a non-front PR — it cannot merge yet, so no wake would be actionable.

You add only the two stack-specific parts pr-monitor deliberately leaves out:

• Front-advance: when the front PR merges, stop that watcher with relay pr watch stop <front-project-slug> — which also closes its watcher tab — then explicitly rebase/retarget the next PR onto master, verify descendant base refs did not collapse, and start a watcher for the new front project with the same --mode stack --owner flags.
• Cascade: after any content change to a PR that has descendants, rebase each descendant (git rebase --onto <new-tip> <old-tip> <descendant>), build+test, force-push, and verify base refs.

Author decisions that pr-fix surfaces are routed to the pending-decisions table + the author. See stacked-mechanics.md for the rebase/auto-merge machinery.

Phase 3 — Converge & stop

When all acceptance criteria in goal.md are checked and all PRs are merged, run a final verification subagent to confirm the delta is closed, then STOP: write progress.md → "goal delivered — STOPPED", stop any watcher you started (relay pr watch stop <project>), tear down the native loop if you used one, and report. Do not start the next design slice or invent scope — newly discovered work goes to follow-ups.md, not into this run.

State files (single source of truth) → references/state-files.md

goal.md · plan.md · state.json · progress.md · tradeoffs.md · follow-ups.md · questions.md (the pending-decisions table). Keep them current every tick and after every delegated step. Surface the pending-decisions table to the author whenever a decision opens or closes; record closed decisions durably outside questions.md.

Stacked-PR mechanics → references/stacked-mechanics.md

Rebase cascades (--onto), auto-merge rules, merge-queue method quirks, freshness rebases, transient-401 retries — all the GitHub-stacking machinery the subagents need.

Hard guardrails → references/guardrails.md

The non-negotiable invariants. Read first. Violating one is a failure even if the task "works."