| 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, append WORKLOG, update the live snapshot. 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
- Confirm the repo is bootstrapped with a
plan/ queue.
- 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 2b — Execute criterion verification (evidence-adopting repos)
Skip this step when docflow.yml records no evidence-adopted-at: —
pre-adoption behaviour is unchanged.
Otherwise, for each owning record in evidence scope (created or edited
after the adoption commit):
- Run each acceptance criterion's
Verify: method against the change
being shipped.
- Write one bound evidence record per criterion —
evidence/<record-slug>/AC<n>-<seq>.md, next free sequence — per
CONVENTIONS.md §Verification Evidence: the criterion's current
digest, the method/command, the source SHA being shipped, exit code,
output digest, verifier, date. The verifier names the executor:
gate@ship-item for an unattended skill run, gate@ship-item (attended) when the operator supervised the execution (see
CONVENTIONS.md §Verification Evidence). Never edit an
existing record; a correction is a new record naming supersedes:.
manual criteria need the named attestation (verifier ≠ the
implementer, with date and scope). Collect it now; a criterion
without one stays unevidenced — do not invent attestations.
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 owning record(s) and regenerate
- Advance each owning record's status — an ADR from
Accepted to
Implemented, a capability spec from Agreed to Implemented —
in an evidence-adopting repo, only if every current criterion of
that record has valid evidence (exit code 0, or an attested manual
record). Otherwise name the unevidenced criteria, leave the status
where it is, and say so in the ship report. The plan item still
completes on its own exit criteria — a partial contribution
integrates without blocking; the record catches up when the
remaining criteria are evidenced.
- Append a Revision History row if the status change is substantive
(it is). Regenerate
INDEX.md to match (the ADR table, and the
Specs section where the repo has one, and the Goals section
likewise). Where the goals layer is enabled, regenerate
COVERAGE.md the same way — it walks evidence and plan state,
both of which this step just changed.
Step 6 — Record
If _agent/ was omitted at bootstrap (Q5 = None), skip this step — git
history is the record.
- Append a one-line
_agent/WORKLOG.md row: branch, HEAD, verify
result, any deferral.
- Update the live snapshot:
_agent/CURRENT_FOCUS.md in single-checkout
modes; in worktree mode (Q5 mode 3) remove this worktree's row from
_agent/IN_FLIGHT.md instead (CURRENT_FOCUS is local-only there).
Step 7 — Commit
Conventional Commit, Rationale: footer (touches an ADR). Group the
move + status advance + INDEX + WORKLOG into one coherent commit where
possible so the completion event is atomic in history.
