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.
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.
When to use
deliver 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).
Step 1 — Check it is ready
- 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.
- The tree is clean and the branch is pushed.
- The gates are green on the tip (below).
- 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.
- 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.
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.
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:
## 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.
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.
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).
1---2name: ship3description: 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.4metadata:5 source: https://skillmd.com/skills/sascha-gruesshaber/ship6---78# Ship (a built branch → an open review)910Opens one review on `.agents/forge.md`'s host, with the commands that file writes down. It never11improvises a forge interaction: **a step `forge.md` does not name is not taken.**1213<!-- shared:repo-config:start source=repo-config.md -->14**This repo describes itself in `.agents/`, at the repository root. Read the files that bind your step,15and treat them as authority over anything you would otherwise assume.**1617| File | Answers |18|---|---|19| `.agents/lifecycle.md` | which phases run, the review tiers, which reviewers and lenses are in use, how many rounds each loop gets |20| `.agents/gates.md` | the commands that must pass, in order, and what "green" means here |21| `.agents/tracker.md` | where specs live, and what may be written to the board |22| `.agents/forge.md` | the git host, the ship mode, and how a branch becomes a reviewed change |23| `.agents/preview.md` | how to bring the app up, seed a scenario and screenshot a screen, and where the design reference lives |24| `.agents/docs.md` | where architecture truth lives, the glossary, and what "docs are part of done" costs |25| `.agents/naming.md` | branch, commit, directory and test-name grammar |26| `.agents/working-agreement.md` | working hours, what may run unattended, how to report, the walkthrough language, when to stop and ask |2728Three rules:2930- **A missing file is a real answer: that thing is not configured here.** Say so in one line and take31 the safest reading — do not invent the repo's conventions, and do not fall back on another project's.32 If the whole directory is absent, stop and tell the user to run `/onboard` instead of guessing.33- **`.agents/` beats your own judgement, and loses to the user.** It was written deliberately, so a rule34 you disagree with is reported once, not routed around.35- **Read only what your step needs.** Every line costs on every turn of a long run.36<!-- shared:repo-config:end -->3738## When to use3940- [`deliver`](../deliver/SKILL.md) finished and the ship mode is `review` or `review+watch`. It hands41 you the facts for the description.42- A branch is built (`**Status:** Built`) and the user says open the review.4344Not for: a branch whose tasks are not all checked off (`/deliver` resumes it), or a review that is45already open ([`babysit`](../babysit/SKILL.md)).4647## Step 1 — Check it is ready48491. **The spec says `Built`**, every line of `plan.md`'s `## Build` is checked or parked, and50 `implementation-record.md` exists. Otherwise name what is missing and stop.512. **The tree is clean and the branch is pushed.**523. **The gates are green on the tip** (below).534. **The branch merges.** Merge the default branch in if it moved, and run the gates again: a clean54 textual merge can still break the build.555. **No review is open for this branch already.** Use the listing command `.agents/forge.md` names. One56 open → hand over to `babysit` instead of opening a second.5758<!-- shared:gates:start source=gates.md -->59**Run the gates the way CI runs them, before you claim anything passes.** They are recorded in60`.agents/gates.md`, at the repository root — the commands, their order, and which of them a local run61weakens. Read that file; do not reconstruct the gate from what you see in the tree.6263- **Run them in the order given.** A formatter after a build check wastes the check, and most orders are64 written down because somebody already lost an hour to the other one.65- **A local command that is not the CI command is not the gate.** Where `.agents/gates.md` says a local66 invocation is softer than CI's — warnings not fatal, a subset of projects, coverage not measured — run67 the CI form or say which one you ran.68- **Generated files are regenerated by the command `.agents/gates.md` names**, never edited by hand.69- **A gate that fails for a reason outside this change is not yours to work around.** Say so and stop.70- **When a gate fails in a way that makes no sense**, read the troubleshooting document71 `.agents/gates.md` points at before debugging your own code.7273If `.agents/gates.md` is missing, run the repo's obvious test and build commands, **say which you chose74and that they were not configured**, and do not claim CI parity.75<!-- shared:gates:end -->7677## Step 2 — Write the description7879Build it from the spec, `git log`, the record and the facts `/deliver` handed over. **Never from80memory.** Use the template `.agents/forge.md` names; without one, this shape:8182```markdown83## What this does8485<two or three sentences: what a user or another system can do now that it could not before>8687## What changed8889- <one line per behaviour, never per file>9091## How we know it works9293- <before → after, as evidence: a test at a named seam, a screenshot, a command and its output>9495## What we decided along the way9697- <each Confirm? yes decision, with the outcome that is built>9899## Merge danger100101**Review tier:** <light | medium | heavy — and why, when /deliver raised it>102**Door:** <one-way | two-way — and why>103**Blast radius:** <what breaks, for whom, if this is wrong>104105## Worth knowing106107- <the record's worth-knowing and deferred items>108- Review walkthrough: `<path>` | none109```110111- **What changes, never how many.** No counts of files, tests or commits; the forge shows those.112- **Give each fact once.** Define a shared word where it first appears.113- **Decisions live here and on the walkthrough, never as review threads you open yourself.** A thread114 per decision buries the one comment a human wrote.115- **The trailer and footer rules are `.agents/naming.md`'s.** It overrides any default of your harness.116117## Step 3 — Open it118119Run the open command `.agents/forge.md` writes, with its target branch, reviewers, draft setting and120any link it requires (a ticket, a label). Read back the review's link from the command's output.121122<!-- shared:tracker-limits:start source=tracker-limits.md -->123**Read the issue tracker freely. Write to it only as `.agents/tracker.md` allows** — at the repository124root. That file names the tracker, the project key, and the writes that are standing permission here125— typically none, or a small closed set such as claiming a ticket when work starts and commenting the126agreed design and the shipped link.127128Limits that hold for every write, whatever the tracker:129130- **Only the writes that file lists.** Anything wider — creating issues, a bulk edit, another field —131 needs a manifest shown to the user and an explicit go-ahead.132- **English, whatever language the session ran in.** A board is read outside the team that fills it.133- **Only ever forwards.** Never drag an item backwards, and never set a status that reports an *outcome*134 — those stay human calls.135- **If it is assigned to somebody else, leave it and say so.** Taking a colleague's ticket silently costs136 more than it saves.137- **Never blocking.** Missing credentials, a 404 or an outage each cost one line, and the run carries on.138 **The committed spec is the authority; the board is a convenience.**139140Say in one line what you wrote and where. If `.agents/tracker.md` is missing, **write nothing** and141carry on with the local files.142<!-- shared:tracker-limits:end -->143144## Step 4 — Record it145146Set the spec header to `**Status:** Shipped` and add `**Review:** <link>`. Commit and push.147148Report in three lines: the link, the review walkthrough's path when there is one, and what happens next149(`babysit` is watching, or the review waits for a person).