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