ship-branch

name	ship-branch
description	Verify, deliver, and close a completed branch. Trigger: When implementation is done and ready to ship or close out.
license	Apache 2.0
metadata	{"version":"1.0","type":"behavioral","skills":["verification-protocol"]}

Ship Branch

Structured close-out for a completed development branch. Verifies tests, presents exactly four delivery options, executes the chosen one, and cleans up.

When to Use

• Implementation on a feature/fix branch is complete
• Ready to deliver or close out the work
• After plan execution finishes

Don't use for:

• Mid-implementation work (use writing-plans or subagent-orchestration)
• Ongoing branches not ready for delivery

---

Critical Patterns

✅ REQUIRED [CRITICAL]: Verify Before Any Delivery Action

Tests must pass before presenting delivery options. Never proceed with failing tests.

# ❌ WRONG — skip verification
Branch is done. Pushing to origin.

# ✅ CORRECT — verify first
Ran: npm test → 18/18 passed ✅
Ran: npm run build → dist/ created ✅
Ready to present delivery options.

✅ REQUIRED [CRITICAL]: Present Exactly Four Options

Always present these four options — no more, no fewer. Let the user decide.

Branch: feature/user-auth — 18/18 tests passing ✅

Delivery options:
1. Merge locally into main (no remote push)
2. Push branch + open PR
3. Keep branch as-is (do nothing)
4. Discard branch (delete all work)

✅ REQUIRED: Require Explicit "discard" Confirmation

Option 4 requires the user to type the word "discard" explicitly. Never delete work on a single confirmation click or ambiguous response.

# ❌ WRONG
User: "yeah go ahead"
Action: Deletes branch.

# ✅ CORRECT
"Type 'discard' to confirm deletion of all work on this branch."
User: "discard"
Action: Deletes branch.

✅ REQUIRED: Clean Up Worktree After Delivery

After merge or discard, remove the worktree directory if one was used.

# After merge or discard:
git worktree remove .worktrees/feature-user-auth
# Verify:
ls .worktrees/ → feature-user-auth no longer present ✅

---

Decision Tree

Implementation complete?
  → Run full verification (tests + build)
  → Verification fails?
      → Stop. Report failures. Do not proceed to delivery.

Verification passes?
  → Present exactly 4 options: merge local / push+PR / keep / discard

User chooses option 1 (merge local)?
  → git checkout main → git merge branch-name → verify merge clean

User chooses option 2 (push + PR)?
  → git push origin branch-name → open PR with summary of changes

User chooses option 3 (keep as-is)?
  → Do nothing. Confirm branch is preserved.

User chooses option 4 (discard)?
  → Require explicit "discard" typed → delete branch → clean up worktree

Worktree was used?
  → Remove worktree after option 1, 2, or 4.

---

Conventions

Delivery summary for PRs

When opening a PR (option 2), include:

• What was implemented (1-3 bullets)
• Tests added or modified
• Any known limitations or follow-up items

Branch naming in options

Always show the actual branch name in the options presentation so the user knows exactly what's being acted on.

---

Example

## Ship Branch: feature/password-reset

### Verification
Ran: npm test → 24/24 passed ✅
Ran: npm run lint → 0 errors ✅
Ran: npm run build → dist/ created ✅

### Delivery options
Branch: feature/password-reset

1. Merge locally into main
2. Push branch + open PR
3. Keep branch as-is
4. Discard branch (type "discard" to confirm)

---

[User selects option 2]

Pushed: git push origin feature/password-reset ✅
PR opened: "Add password reset flow" — 3 commits, 24 tests passing
Worktree removed: .worktrees/feature-password-reset ✅

---

Edge Cases

Merge conflicts on option 1: Stop. Report conflicting files. Do not auto-resolve. Ask user how to proceed.

PR already exists: Notify user. Offer to update the existing PR or open a new one.

No worktree used: Skip cleanup step. Only clean up what was created.

Tests flaky on first run: Re-run once. If still failing, report as failing — do not retry silently until green.

User types something other than "discard" for option 4: Treat as cancel. Return to options menu.