AGENTS/.pi/gsd/workflows/ship.md

Context (pre-injected)

State:

Health:

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:

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

Also load config for branching strategy:

CONFIG=$(pi-gsd-tools state load)

Extract: branching_strategy, branch_name.

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 main/master: 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 main)"

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 main

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

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

Ask if user wants to trigger a code review:

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:

pi-gsd-tools state update "Last Activity" "$(date +%Y-%m-%d)"
pi-gsd-tools state update "Status" "Phase ${PHASE_NUMBER} shipped - PR #${PR_NUMBER}"

If commit_docs is true:

pi-gsd-tools commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} - PR #${PR_NUMBER}" --files .planning/STATE.md

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

✓ Phase {X}: {Name} - Shipped

PR: #{number} ({url}) Branch: {branch} → main 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>