Skip to main content
command CX Codex

ship-ticket — Claude Code command for shipping a ticket

The ship-ticket command takes an implemented ticket from branch review through PR creation and merge. Use it when the code is already built in SpecKit Companion.

MIT ★ 110 updated 2026-11-03

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/ship-ticket.md
Open on GitHub

What ship-ticket does

ship-ticket handles an existing feature branch; it does not rebuild the ticket. It checks the Git state, resolves the related open issue, and inspects recorded build and test results. Missing, stale, or failing checks stop the release flow.

The command runs /code-review and applies its findings. Changes to the webview renderer, run-record writer, or a publish command also trigger /codex:review. It then prepares a PR with a changelog entry and merges after checks pass. Add --review-merge to pause before merging for approval.

Run it from the repository root, and not from main. Uncommitted work may need a commit first. A failing build or test blocks shipping, so this command is for finishing a ticket that is already implemented, not for building one.

What it helps with

  • check a completed branch before shipping
  • review a diff and apply its findings
  • link a PR to its issue with Closes #N
  • merge a PR after checks pass

Example prompts for the agent

  • Ship completed issue 292 and open a PR for review.
  • Check the current branch, create its PR, and wait for the checks before merging.
  • Prepare a PR for this branch, but pause before merging with --review-merge.

How to install ship-ticket

Manually: put the files in place

.claude/commands/ship-ticket.md

Call it with /ship-ticket. For all projects use ~/.claude/commands/

Questions about ship-ticket

How do I install ship-ticket in Claude Code?

Copy the command file to .claude/commands/ship-ticket.md.

What does ship-ticket do?

It takes an implemented ticket through build verification, code review, PR creation, and merge. It does not implement the ticket again.

When does ship-ticket use /codex:review?

Only when the diff changes the webview renderer, the run-record writer, or a publish command. Other changes go through /code-review.

Source text

ship-ticket.md · MIT
---
allowed-tools: Bash(git:*), Bash(gh:*), Bash(npm:*), Bash(node:*), Bash(python3:*), Bash(code:*), Bash(sleep:*), Bash(jq:*), Bash(tooling/scripts/merge-pr.sh:*), Bash(tooling/scripts/new-worktree.sh:*), Agent, AskUserQuestion, Read, Write, Edit, Skill, TaskCreate, TaskUpdate
description: Ship an ALREADY-BUILT ticket — code review → PR → merge → learnings → install-local. Skips the build (you built it in SpecKit Companion). The tail of /fix-tickets, no rebuild.
argument-hint: "<issue # e.g. 292>  (optional — defaults to the current branch's NNN-slug)  [--review-merge]"
---

## What this does

The **post-build tail** for a ticket you built yourself in SpecKit Companion (GUI / `/speckit.companion.*`). It does **not** rebuild — it takes the committed work on the current feature branch and ships it: review, PR, merge, learnings, reinstall. It is `/fix-tickets` steps 3–8 with the build skipped.

Use `/fix-tickets` when you want the loop to build the fix too. Use **`/ship-ticket`** when the code already exists on a branch and you just want the review→merge tail. Both are step 2 of `/release-loop`.

## Locked defaults

- **Never rebuild.** The branch already has the work; this command only reviews/ships it.
- **Never merge red or pending checks.** Leave the PR open and report.
- **Auto-merge on** unless `--review-merge` is passed (then pause for a thumbs-up before `gh pr merge`).
- **`/code-review` is the review gate** — high effort, **one pass**, findings applied; re-run it on any fix that itself changes real logic (the fix commit is the least-reviewed code). `/codex:review` joins it only for the webview renderer, the run-record writer, or a publish command.
- **Heavy steps run in subagents** (review, distilling learnings); the main loop only does git/gh/decisions.

## Inputs

`$ARGUMENTS`:
- An issue number (`292`) — preferred.
- Empty → derive from the current branch name (`NNN-slug` → look up the issue), confirm before proceeding.
- `--review-merge` anywhere → pause before merge.

---

## Procedure

> Run from the repo root (`~/dev/GitHub/speckit-companion`). Confirm with `git rev-parse --show-toplevel`.

### 0. Preconditions — main loop
```bash
git rev-parse --show-toplevel                 # must be speckit-companion
git branch --show-current                     # must NOT be main; expect NNN-slug
git status --porcelain                        # work should be committed; a clean tree is ideal
```
- **Refuse if on `main`** — there's nothing to ship. Stop and report.
- Resolve the issue number from `$ARGUMENTS` or the branch's `NNN`. `gh issue view <N>` to capture title/body for the PR + verify it's still open. If you can't resolve an issue, ask (AskUserQuestion) — a PR still wants a `Closes #N`.
- If there are **uncommitted** changes that are the real work, commit them first (real change + `specs/<NNN>/` spec folder); do **not** commit `.specify/` regenerated artifacts (`git checkout origin/main -- .specify/<file>` for any swept in).

### 0b. Verify it actually builds — subagent
- **Read the run the build already recorded before running anything.** The implement step records each check with `--verify-run`, so `specs/<NNN>-<slug>/.spec-context.json` already holds the compile and test entries under `verified`, each with its `exitCode`. If they are there, green, and newer than the last source file written (compare against the modified time of `.spec-context.json`), that is the verification — say so and move on. Run `npm run compile && npm test` yourself only when the record is missing, red, or stale. If `apps/speckit-extension/**` changed, also `python3 apps/speckit-extension/scripts/check_shape_parity.py`. If capture/timing changed, run the capture eval.
- Confirm the spec is in a shippable state: `specs/<NNN>-<slug>/` committed, tasks checked, `.spec-context.json` `specName` real (not a `[FEATURE NAME]` placeholder).
- If anything is red, **stop and report** — don't ship a broken branch.

### 1. Code review — subagent (`/code-review`, and `/codex:review` where it earns its place)
Run `/code-review` on the branch diff vs `main` at **high** effort — **one pass** — and apply findings (`--fix`). Tell the subagent to **read `.claude/review-checklist.md` first** (and honor the `CLAUDE.md` conventions it points to) and check the diff against those known bug classes. Commit fixes; re-run `npm test` if code changed. Record each finding (you'll distill in step 4).

**Codex joins only where a second reviewer has paid for itself.** Launch `/codex:review --base main --scope branch` on the same diff, in parallel and before applying anything, when the diff touches the webview renderer, the writer of the run record, or a publish command. Everywhere else `/code-review` alone is the gate. When both run, reconcile: a finding either reviewer raises gets addressed, and where they disagree the tie-breaker is a test, not an argument.

**Log who found what.** Append one row per finding to `~/dev/GitHub/obsidian-vault/Projects/speckit companion/Review Ledger.md` — date, branch or PR, the finding in a line, found by `code-review` / `codex` / `both`, severity, and whether it changed code. This is the only record of whether the second reviewer earns its place, so it gets written on every run, including the runs where Codex found nothing.

**Re-review the fix, once.** If your applied fixes themselves changed real LOGIC (control flow, a migration, a data-shape writer, an availability/auth gate, a DOM/lifecycle refactor), **re-run `/code-review` on the new commit** — the fix you just wrote is the least-reviewed code in the PR. Docs/CSS/label-only fixes don't need it.

**Two passes is the ceiling.** One review, one re-review, then ship. If the second pass still finds something real, fix it and open a follow-up issue for anything it raises beyond that rather than starting a third. An unbounded loop finds real things and costs more than they are worth: on PR #720 the third pass found a genuine dispatch bug, and the fourth found nothing while the branch sat unmerged. Convergence is a budget, not a proof.

### 2. Open the PR — main loop
A change a user will meet needs its changelog entry on the branch before the PR opens: write it with `/changelog-entry`.

Use `/create-pr` conventions (reads `.claude/pr-profile.md`): conventional-commit title `type(scope): summary`, body with `Closes #N`, summary, technical notes, how-to-verify.
```bash
git push -u origin "$(git branch --show-current)"
gh pr create --title "<title>" --body "<body>" --base main
```
Capture the PR number/URL.

### 3. Merge + cleanup — main loop
**Review-gate:** if `--review-merge` was passed, do **not** merge — post the PR link + a one-line summary, record "merged: NO — awaiting your review," and stop. Otherwise:
```bash
tooling/scripts/merge-pr.sh <PR>      # waits here and merges once every check has passed (auto-merge would skip the test job, which is not required)
gh pr checks <PR> --watch || true     # one wait, to report the outcome
```
Exit 3 means the pull request changes what a person sees and the owner has not looked: record "merged: NO — awaiting your review", show them the change in a note with screenshots, and re-run with `--seen` only after they approve. Never merge around the script with `gh pr merge`.

If checks fail and can't be auto-addressed, leave the PR open, record "merged: NO — checks failing," report.

### 4. Capture learnings + tick the box — distill subagent + main loop
- **Distill — route by shape, don't dump.** A learning earns capture only if it's **checkable, recurring or high-cost, and phrased as a rule/scan**; prefer editing an existing line over adding a near-duplicate; **empty distill is the norm, not the exception.** Route each kept learning to where it fires:
  - a **codebase-specific review check** → `.claude/review-checklist.md`
  - a **universal authoring convention** → the matching `CLAUDE.md` section (Webview & rendering invariants / Code Comments / Design tokens)
  - a **loop-mechanics** improvement → this command file (or `fix-tickets.md`)
  - an **architecture / coverage gap** → a GitHub issue (surface in the report; don't auto-apply)
  - If it can become a test or hook, propose that instead of prose. (`.claude/lessons-learned.md` is retired — don't append to it.)
- **Tick the box:** flip this ticket's line in `~/dev/GitHub/obsidian-vault/Current.md` (and `Projects/speckit companion/composable-workflow/queue.md`) from `- [ ]` to `- [x]` with `→ [PR #NNN](url)`.

### 5. Reinstall + report — main loop
Run `/install-local` so the workspace ends current, then drop the throwaway bump:
```bash
git checkout main && git fetch origin && git pull --ff-only
# /install-local …
git restore package.json package-lock.json .specify/
```
**If the branch touched `apps/speckit-extension/**`** — `/install-local` only refreshes the VS Code extension; the spec-kit extension also needs a `--dev` reinstall so the new `/speckit.companion.*` commands + workflow are resolvable in Claude Code. Check with `git diff --name-only origin/main...HEAD | grep -q '^apps/speckit-extension/'`, and if so:
```bash
specify extension remove companion                # committed stub means a fresh add reports "already installed"
specify extension add ./apps/speckit-extension --dev   # re-copies into .specify/extensions/companion/ + re-emits .claude/ command
specify extension list                            # confirm "companion" at the new state
git restore .specify/                             # gitignored dev-install copies — never commit these
```
The `.claude/` command emissions are **committed real files** (not gitignored like `.specify/`), and the merged PR should already carry the updated ones. If the reinstall leaves `.claude/` dirty (`git status`), that means the PR shipped without re-emitting — **surface it, don't silently restore or commit on main**; the emission belongs in the feature PR.
End with a tight summary: issue shipped, PR link, merged / in-review / blocked, new installed version, **whether the spec-kit extension was reinstalled**, lessons-captured count, and `/release-qa` as the next step for the batch.

## Guardrails

- **Never rebuild** — that's `/fix-tickets`' job. This ships what's already on the branch.
- **Never merge red or pending checks.** Report instead.
- **Never commit version bumps or `.specify/` regenerated artifacts** into the feature PR (install-local's bump is throwaway — restore it).
- **Reinstall the spec-kit extension when the branch touched `apps/speckit-extension/**`** — `/install-local` only covers the VS Code side; `specify extension remove companion && specify extension add ./apps/speckit-extension --dev` is what makes the new `/speckit.companion.*` commands resolvable in Claude Code. Restore the gitignored `.specify/` copies; never commit them on main.
- Always reply to + resolve any PR review threads after fixing.

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for Code review and refactoring →

From the same set83

The whole set →
submit-catalog-update submit-catalog-update is a Claude Code skill that generates and files an Extension Submission issue for the companion extension in spec-kit. It is used for minor and major version updates. CX Codex +1 ★ 110repo stars feature-clip feature-clip builds SpecKit Companion looping clips through capture, composition, rendering, and media sync for the site and documentation. CX Codex +1 ★ 110repo stars publish-speckit-ext publish-speckit-ext — a command to publish the spec-kit extension to a GitHub release. Lets other developers install the extension via catalog without cloning the repository. CX Codex +1 ★ 110repo stars speckit.constitution speckit.constitution is a Claude Code subagent that creates and updates the project constitution at .specify/memory/constitution.md based on team principles. CX Codex +1 ★ 110repo stars speckit.tasks speckit.tasks turns a feature into tasks.md: reads plan.md and spec.md from the feature folder and lays out the work per user story with dependencies. CX Codex +1 ★ 110repo stars speckit.clarify speckit.clarify pins down underspecified details in your feature spec with up to five targeted questions, saving choices directly to disk. CX Codex GP ChatGPT ★ 110repo stars speckit.analyze The speckit.analyze subagent checks spec.md, plan.md, and tasks.md for gaps and conflicts. Run it after task generation, before implementation. CX Codex +1 ★ 110repo stars speckit.implement speckit.implement — a subagent that reads the task list from tasks.md and executes it step by step, checking prerequisites, loading project artifacts, and following the architecture defined in plan.md. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open