# Ship

> Opens the review for a built feature branch the way this repo's forge does it - push, title, a description built from the spec, the implementation record and the review walkthrough, then the spec header set to Shipped. Called by /deliver when the ship mode is review or review+watch, or on its own for a branch that is built but not yet up for review. Use for "open the PR", "open the merge request", "ship it", "put it up for review", "finalize". Keywords - ship, open a pull request, merge request, PR description, finalize, push for review.

- Skill: `sascha-gruesshaber/ship` (Agent Skill)
- Install (CLI): `npx get-skill add sascha-gruesshaber/ship`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sascha-gruesshaber/ship/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sascha-gruesshaber (https://skillmd.com/u/sascha-gruesshaber)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/sascha-gruesshaber/ship

---


# Ship (a built branch → an open review)

Opens one review on `.agents/forge.md`'s host, with the commands that file writes down. It never
improvises a forge interaction: **a step `forge.md` does not name is not taken.**

<!-- shared:repo-config:start source=repo-config.md -->
**This repo describes itself in `.agents/`, at the repository root. Read the files that bind your step,
and treat them as authority over anything you would otherwise assume.**

| File | Answers |
|---|---|
| `.agents/lifecycle.md` | which phases run, the review tiers, which reviewers and lenses are in use, how many rounds each loop gets |
| `.agents/gates.md` | the commands that must pass, in order, and what "green" means here |
| `.agents/tracker.md` | where specs live, and what may be written to the board |
| `.agents/forge.md` | the git host, the ship mode, and how a branch becomes a reviewed change |
| `.agents/preview.md` | how to bring the app up, seed a scenario and screenshot a screen, and where the design reference lives |
| `.agents/docs.md` | where architecture truth lives, the glossary, and what "docs are part of done" costs |
| `.agents/naming.md` | branch, commit, directory and test-name grammar |
| `.agents/working-agreement.md` | working hours, what may run unattended, how to report, the walkthrough language, when to stop and ask |

Three rules:

- **A missing file is a real answer: that thing is not configured here.** Say so in one line and take
  the safest reading — do not invent the repo's conventions, and do not fall back on another project's.
  If the whole directory is absent, stop and tell the user to run `/onboard` instead of guessing.
- **`.agents/` beats your own judgement, and loses to the user.** It was written deliberately, so a rule
  you disagree with is reported once, not routed around.
- **Read only what your step needs.** Every line costs on every turn of a long run.
<!-- shared:repo-config:end -->

## When to use

- [`deliver`](../deliver/SKILL.md) finished and the ship mode is `review` or `review+watch`. It hands
  you the facts for the description.
- A branch is built (`**Status:** Built`) and the user says open the review.

Not for: a branch whose tasks are not all checked off (`/deliver` resumes it), or a review that is
already open ([`babysit`](../babysit/SKILL.md)).

## Step 1 — Check it is ready

1. **The spec says `Built`**, every line of `plan.md`'s `## Build` is checked or parked, and
   `implementation-record.md` exists. Otherwise name what is missing and stop.
2. **The tree is clean and the branch is pushed.**
3. **The gates are green on the tip** (below).
4. **The branch merges.** Merge the default branch in if it moved, and run the gates again: a clean
   textual merge can still break the build.
5. **No review is open for this branch already.** Use the listing command `.agents/forge.md` names. One
   open → hand over to `babysit` instead of opening a second.

<!-- shared:gates:start source=gates.md -->
**Run the gates the way CI runs them, before you claim anything passes.** They are recorded in
`.agents/gates.md`, at the repository root — the commands, their order, and which of them a local run
weakens. Read that file; do not reconstruct the gate from what you see in the tree.

- **Run them in the order given.** A formatter after a build check wastes the check, and most orders are
  written down because somebody already lost an hour to the other one.
- **A local command that is not the CI command is not the gate.** Where `.agents/gates.md` says a local
  invocation is softer than CI's — warnings not fatal, a subset of projects, coverage not measured — run
  the CI form or say which one you ran.
- **Generated files are regenerated by the command `.agents/gates.md` names**, never edited by hand.
- **A gate that fails for a reason outside this change is not yours to work around.** Say so and stop.
- **When a gate fails in a way that makes no sense**, read the troubleshooting document
  `.agents/gates.md` points at before debugging your own code.

If `.agents/gates.md` is missing, run the repo's obvious test and build commands, **say which you chose
and that they were not configured**, and do not claim CI parity.
<!-- shared:gates:end -->

## Step 2 — Write the description

Build it from the spec, `git log`, the record and the facts `/deliver` handed over. **Never from
memory.** Use the template `.agents/forge.md` names; without one, this shape:

```markdown
## What this does

<two or three sentences: what a user or another system can do now that it could not before>

## What changed

- <one line per behaviour, never per file>

## How we know it works

- <before → after, as evidence: a test at a named seam, a screenshot, a command and its output>

## What we decided along the way

- <each Confirm? yes decision, with the outcome that is built>

## Merge danger

**Review tier:** <light | medium | heavy — and why, when /deliver raised it>
**Door:** <one-way | two-way — and why>
**Blast radius:** <what breaks, for whom, if this is wrong>

## Worth knowing

- <the record's worth-knowing and deferred items>
- Review walkthrough: `<path>` | none
```

- **What changes, never how many.** No counts of files, tests or commits; the forge shows those.
- **Give each fact once.** Define a shared word where it first appears.
- **Decisions live here and on the walkthrough, never as review threads you open yourself.** A thread
  per decision buries the one comment a human wrote.
- **The trailer and footer rules are `.agents/naming.md`'s.** It overrides any default of your harness.

## Step 3 — Open it

Run the open command `.agents/forge.md` writes, with its target branch, reviewers, draft setting and
any link it requires (a ticket, a label). Read back the review's link from the command's output.

<!-- shared:tracker-limits:start source=tracker-limits.md -->
**Read the issue tracker freely. Write to it only as `.agents/tracker.md` allows** — at the repository
root. That file names the tracker, the project key, and the writes that are standing permission here
— typically none, or a small closed set such as claiming a ticket when work starts and commenting the
agreed design and the shipped link.

Limits that hold for every write, whatever the tracker:

- **Only the writes that file lists.** Anything wider — creating issues, a bulk edit, another field —
  needs a manifest shown to the user and an explicit go-ahead.
- **English, whatever language the session ran in.** A board is read outside the team that fills it.
- **Only ever forwards.** Never drag an item backwards, and never set a status that reports an *outcome*
  — those stay human calls.
- **If it is assigned to somebody else, leave it and say so.** Taking a colleague's ticket silently costs
  more than it saves.
- **Never blocking.** Missing credentials, a 404 or an outage each cost one line, and the run carries on.
  **The committed spec is the authority; the board is a convenience.**

Say in one line what you wrote and where. If `.agents/tracker.md` is missing, **write nothing** and
carry on with the local files.
<!-- shared:tracker-limits:end -->

## Step 4 — Record it

Set the spec header to `**Status:** Shipped` and add `**Review:** <link>`. Commit and push.

Report in three lines: the link, the review walkthrough's path when there is one, and what happens next
(`babysit` is watching, or the review waits for a person).

