msd-core/get-shit-done/workflows/ship.md

Create a pull request from completed phase/milestone work, generate a rich PR body from planning artifacts, optionally run code review, and prepare for merge. Closes the plan → execute → verify → ship loop.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

Parse arguments and load project state:

INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

Parse from init JSON: phase_found, phase_dir, phase_number, phase_name, padded_phase, commit_docs.

Also load config for branching strategy:

CONFIG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)

Extract: branching_strategy, branch_name.

Detect base branch for PRs and merges:

BASE_BRANCH=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get git.base_branch 2>/dev/null || echo "")
if [ -z "$BASE_BRANCH" ] || [ "$BASE_BRANCH" = "null" ]; then
  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
  BASE_BRANCH="${BASE_BRANCH:-main}"
fi

Verify the work is ready to ship:

1. Verification passed?

   VERIFICATION=$(cat ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null)
   

   Check for status: passed or status: human_needed (with human approval). If no VERIFICATION.md or status is gaps_found: warn and ask user to confirm.

2. Clean working tree?

   git status --short
   

   If uncommitted changes exist: ask user to commit or stash first.

3. On correct branch?

   CURRENT_BRANCH=$(git branch --show-current)
   

   If on ${BASE_BRANCH}: warn — should be on a feature branch. If branching_strategy is none: offer to create a branch now.

4. Remote configured?

   git remote -v | head -2
   

   Detect origin remote. If no remote: error — can't create PR.

5. gh CLI available?

   which gh && gh auth status 2>&1
   

   If gh not found or not authenticated: provide setup instructions and exit.

Push the current branch to remote:

git push origin ${CURRENT_BRANCH} 2>&1

If push fails (e.g., no upstream): set upstream:

git push --set-upstream origin ${CURRENT_BRANCH} 2>&1

Report: "Pushed {branch} to origin ({commit_count} commits ahead of ${BASE_BRANCH})"

Auto-generate a rich PR body from planning artifacts:

1. Title:

Phase {phase_number}: {phase_name}

Or for milestone: Milestone {version}: {name}

2. Summary section: Read ROADMAP.md for phase goal. Read VERIFICATION.md for verification status.

## Summary

**Phase {N}: {Name}**
**Goal:** {goal from ROADMAP.md}
**Status:** Verified ✓

{One paragraph synthesized from SUMMARY.md files — what was built}

3. Changes section: For each SUMMARY.md in the phase directory:

## Changes

### Plan {plan_id}: {plan_name}
{one_liner from SUMMARY.md frontmatter}

**Key files:**
{key-files.created and key-files.modified from SUMMARY.md frontmatter}

4. Requirements section:

## Requirements Addressed

{REQ-IDs from plan frontmatter, linked to REQUIREMENTS.md descriptions}

5. Testing section:

## Verification

- [x] Automated verification: {pass/fail from VERIFICATION.md}
- {human verification items from VERIFICATION.md, if any}

6. Decisions section:

## Key Decisions

{Decisions from STATE.md accumulated context relevant to this phase}

Create the PR using the generated body:

gh pr create \
  --title "Phase ${PHASE_NUMBER}: ${PHASE_NAME}" \
  --body "${PR_BODY}" \
  --base ${BASE_BRANCH}

If --draft flag was passed: add --draft.

Report: "PR #{number} created: {url}"

Ask if user wants to trigger a code review:

Text mode (workflow.text_mode: true in config or --text flag): Set TEXT_MODE=true if --text is present in $ARGUMENTS OR text_mode from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where AskUserQuestion is not available.

AskUserQuestion:
  question: "PR created. Run a code review before merge?"
  options:
    - label: "Skip review"
      description: "PR is ready — merge when CI passes"
    - label: "Self-review"
      description: "I'll review the diff in the PR myself"
    - label: "Request review"
      description: "Request review from a teammate"

If "Request review":

gh pr edit ${PR_NUMBER} --add-reviewer "${REVIEWER}"

If "Self-review": Report the PR URL and suggest: "Review the diff at {url}/files"

Update STATE.md to reflect the shipping action:

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state update "Last Activity" "$(date +%Y-%m-%d)"
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_NUMBER}"

If commit_docs is true:

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --files .planning/STATE.md

``` ───────────────────────────────────────────────────────────────

✓ Phase {X}: {Name} — Shipped

PR: #{number} ({url}) Branch: {branch} → ${BASE_BRANCH} Commits: {count} Verification: ✓ Passed Requirements: {N} REQ-IDs addressed

Next steps:

• Review/approve PR
• Merge when CI passes
• /gsd-complete-milestone (if last phase in milestone)
• /gsd-progress (to see what's next)

───────────────────────────────────────────────────────────────

</step>

</process>

<offer_next>
After shipping:

- /gsd-complete-milestone — if all phases in milestone are done
- /gsd-progress — see overall project state
- /gsd-execute-phase {next} — continue to next phase
</offer_next>

<success_criteria>
- [ ] Preflight checks passed (verification, clean tree, branch, remote, gh)
- [ ] Branch pushed to remote
- [ ] PR created with rich auto-generated body
- [ ] STATE.md updated with shipping status
- [ ] User knows PR number and next steps
</success_criteria>