Immutable. This exact content is served forever at /api/v1/blob/45194fe2ddcb373b.
--- 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. ## 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.