7 added, 5 removed. Audit A to A.
---
name: ship-item
description: Ship a plan/todo item in a documentation-led repo — run the verify gate, integrate per the repo's model (fast-forward or PR), git mv todo→done with a shipped footer, advance the owning ADR(s) to Implemented, regenerate INDEX. Use when the user says "ship this", "complete the plan item", "mark done", "close out the queue item", or invokes /ship-item.
---
# ship-item
Execute the completion event for one queue item. This is the most
order-sensitive operation in the system — follow the steps exactly.
## Step 0 — Preconditions and context
1. Confirm the repo is bootstrapped with a `plan/` queue.
2. Read `CONVENTIONS.md` and `AGENTS.md` for: the **integration model**
(direct-to-main fast-forward vs. PR-based with required CI), the
**verify gate** command, the **multi-agent mode**, and the Git
contract (signed commits, tags, trailers). Resolve `adr/`, `plan/`, and
`INDEX.md` against the **artefact root** recorded in `CONVENTIONS.md`
(default: repository root).
## Step 1 — Select the item
Default to the lowest-numbered `plan/todo/` file, or the one the user
names. Read it and the owning ADR(s) in full.
## Step 2 — Verify
Run the repo's verify gate. **Require a pass.** Do not bypass with
`--no-verify` or equivalent. If it fails, stop, surface the failure,
fix the root cause, re-run.
## Step 3 — Integrate (per the repo's model)
- **Direct-to-main, fast-forward:** `git merge --ff-only <branch>` (or
the work is already on `main`), then `git push origin main`. The
verify gate ran locally in Step 2.
- **PR-based:** push the branch, `gh pr create --draft --fill`, wait
for CI green (`gh pr checks --watch`), `gh pr ready`, then
`gh pr merge` with the repo's strategy. Confirm the merge landed on
`main` before continuing.
## Step 4 — Move the queue item
Once the change is on `main`:
- `git mv plan/todo/NNNN-<slug>.md plan/done/<YYYY-MM-DD>-<slug>.md`
(today's date prefix).
- Amend the moved file with a footer: **"Shipped at HEAD `<sha>`"** plus
any artefact id, image tag, deploy id, or PR link.
## Step 5 — Advance the ADR(s) and regenerate
- Advance each owning ADR's `status:` from `Accepted` to `Implemented`.
- Append a Revision History row if the status change is substantive
(it is). Regenerate `INDEX.md` to match.
## Step 6 — Record
**Nothing to write.** The completion commit, the moved `plan/done/`
file and its shipped footer are the record; the coordination mode
prescribes no log, dashboard or snapshot to update.
- One exception, and only while it lasts: a repo scaffolded before this
- convention may still carry a `_agent/WORKLOG.md` or
- `_agent/CURRENT_FOCUS.md` from its old layout. Keep such a file
- current if it is there — a half-maintained log is worse than either
- state — and mention that it is legacy. Never create one, in any mode.
+ One transitional exception: a repo scaffolded before this convention
+ may still *record* a log or snapshot step in its own `AGENTS.md` /
+ `CONVENTIONS.md`, alongside the files it wrote for them. Honour what
+ that repo's recorded conventions ask for — a half-maintained log is
+ worse than either state — and say it is a legacy layout. Never create
+ such a file, and never add the step to a repo whose conventions do not
+ already have it.
## Step 7 — Commit
Conventional Commit, `Rationale:` footer (touches an ADR). Group the
move + status advance + INDEX regeneration into one coherent commit
where possible so the completion event is atomic in history.