stack-ship

Files (7)

• SKILL.md
• decomposition.md · references/
• guardrails.md · references/
• monitor-loop.md · references/
• pr-build-cycle.md · references/
• stacked-mechanics.md · references/
• state-files.md · references/

SKILL.md (first lines)

# 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](references/guardrails.md) 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](references/state-files.md)): 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](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](references/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](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](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:

```bash
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.

From ronaknnathani/relay, MIT.

More from ronaknnathani/relay