issue-ship

name	issue-ship
description	Ship a GitHub Issue end-to-end: fetch the issue as the spec, implement via a worktree-isolated subagent, open a PR that closes the issue, then watch CI through merge. GitHub Issues is the single source of truth.
argument-hint	<issue-number> [--plan]
arguments	["issue"]
disable-model-invocation	true

Issue Ship

/issue-ship 123          # fetch → implement → PR (gated) → CI watch → close
/issue-ship 123 --plan   # plan-mode approval gate before implementation

Invariants

• GitHub Issues is the only tracker in this loop. Never read from or write to any other issue tracker inside this workflow — that boundary is human-owned.
• The issue body is the spec. If it is too thin to implement from, ask the user; do not guess requirements.
• The first push / PR creation requires explicit user confirmation. Follow-up pushes to the same, already-approved PR (CI fixes) do not.
• The main session is the evaluator; it never writes the implementation itself.

Steps

1. Fetch the issue

gh issue view $issue --json number,title,body,labels,assignees,state,url

• No argument → ask which issue to ship.
• state is CLOSED → report and stop.

2. Claim it

gh issue edit $issue --add-assignee @me

Fail-soft: if assignment fails, note it and continue.

3. Plan gate (--plan only)

Analyze the issue body and the relevant code, present an implementation plan, and wait for approval before continuing.

4. Implement via subagent

Dispatch the implementer agent with isolation: "worktree". The brief must inline the full issue spec (number, title, body, acceptance criteria) — the agent has no conversation history. TDD applies where a test harness exists.

When it returns:

• Review the diff yourself as the evaluator (behavior over implementation).
• Verify placement: git worktree list + git branch -v show the main tree untouched and the feature branch at the agent's commits.

5. Open the PR (confirmation gate)

Present the diff summary and proposed PR title/body to the user and wait for explicit approval before pushing or creating the PR. The PR body must contain Closes #$issue so the merge auto-closes the issue.

6. Watch CI through merge

Delegate the watch to the pr-monitor skill's bundled script (shared poller — state-change emission, full failure coverage, approval-gated checks excluded):

Monitor:
  persistent: true
  description: "PR #<pr> — CI + review threads (issue #$issue)"
  command: bash "$HOME/.claude/skills/pr-monitor/scripts/pr-monitor.sh" <pr> <owner> <repo> "require-approval,check-approval" merged

This is /pr-monitor <pr> --until merged --auto-fix in spirit: the PR was already approved in step 5, so CI-fix pushes need no further confirmation.

React to events:

• failures non-empty → fetch the failing log (gh run view --log-failed), reproduce on the PR branch, fix, push, keep watching. Max 3 fix attempts per check name, then stop and re-plan with the user. Never force-push.
• DONE: merged → verify the issue auto-closed; if not: gh issue close $issue --comment "Shipped in <PR URL>". Then clean up: delete the local branch (git branch -D — squash merges are not detected by -d) and remove the implementer worktree if it remains (git worktree remove <path>).
• DONE: closed without merge → report to the user; do not close the issue.
• [POLL_ERROR] repeating → stop the watch (TaskStop) and tell the user to check gh auth status / network.

Out of scope (v1)

• Multi-issue parallel shipping (Agent Teams fleet) — future separate skill.
• Drafting ticket text for external trackers — separate concern, human-owned.