harshanandak/.codex/skills/ship

Push code and create a pull request with full context and documentation links.

Ship

This command creates a PR after validation passes.

Usage

/ship

<HARD-GATE: /ship entry>
Do NOT create PR until:
1. /validate was run in this session with all four outputs shown (type, lint, tests, security)
2. All checks confirmed passing — not assumed, not "was passing earlier"
3. Beads issue is in_progress
4. git branch --show-current output is NOT main or master
</HARD-GATE>

What This Command Does

Step 1: Verify /validate Passed

Ensure all four validation checks completed successfully with fresh output in this session.

Step 2: Freshness Check — Is Branch Still Current?

Even though /validate rebased onto the base branch, time may have passed since then (user reviewed design doc, took a break, etc.). This lightweight check catches staleness before pushing.

BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify freshness"; exit 1; }
BEHIND=$(git rev-list --count HEAD..origin/"$BASE")

• If BEHIND > 0: STOP. Print: "$BASE has advanced since /validate ($BEHIND new commits). Run /validate again to rebase and re-check."
• If BEHIND = 0: Continue to push.
• If fetch fails: the || { ...; exit 1; } guard catches this — STOP. Do NOT push without confirming freshness.

This is NOT a full rebase — just a check. The rebase happens in /validate where the full test suite runs afterward.

Parallel PR coordination (soft block)

Before creating the PR, check merge readiness:

# Run merge simulation against base branch
bash scripts/pr-coordinator.sh merge-sim "$(git branch --show-current)" 2>&1

# Show recommended merge order
bash scripts/pr-coordinator.sh merge-order 2>&1 || true

# Auto-label the PR after creation (called after gh pr create below)
# bash scripts/pr-coordinator.sh auto-label <issue-id>

If merge simulation finds conflicts:

• Display conflicted files
• Ask: "Merge conflicts detected with base branch. These PRs should merge first: [list]. Proceed with PR creation anyway? (y/n)"
• If n: exit cleanly
• If y: log override via bd comments add <id> "Ship override: creating PR despite merge conflicts", then continue

After PR creation completes:

# Auto-label the newly created PR
bash scripts/pr-coordinator.sh auto-label <issue-id>

# Check for stale worktrees (informational)
bash scripts/pr-coordinator.sh stale-worktrees 2>&1 || true

Step 3: Update Beads

bd update <id> --status done
bd sync

Step 4: Push Branch

Use --force-with-lease because /validate may have rebased the branch, rewriting history. This is safe: it only forces the push if the remote branch hasn't been updated by someone else since the last fetch.

git push --force-with-lease -u origin <branch-name>

Step 5: Create PR Using Project's PR Template

CRITICAL: Always use the project's own PR template. Never use a hardcoded body.

Step 5a: Locate the PR template

Check for a PR template in the project (in order of precedence):

# Check standard locations
PR_TEMPLATE=""
for path in .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md docs/pull_request_template.md pull_request_template.md; do
  if [ -f "$path" ]; then
    PR_TEMPLATE="$path"
    break
  fi
done

Step 5b: Read and populate the template

If a PR template exists:

1. Read the template file using the Read tool
2. Fill in every section with actual data from the current PR context:
   • Replace HTML comments (<!-- ... -->) with real content
   • Check applicable checkboxes (- [x])
   • Fill in beads issue IDs (replace beads-xxx with actual ID)
   • Fill in test results, validation status, and other concrete data
   • Reference the design doc: docs/plans/YYYY-MM-DD-<slug>-design.md
3. Do NOT remove any sections — fill them all, even if "N/A"
4. Do NOT restructure the template — keep the project's chosen format

If no PR template exists, use this minimal fallback:

## Summary
[1-3 sentences: what this PR does and why]

## Changes
[Bulleted list of key changes]

## Testing
[How it was tested, test results]

## Beads
Closes beads-xxx

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Step 5c: Create the PR

gh pr create --title "<type>: <concise description>" --body "<populated-template-content>"

Rules for the PR body:

• Use the project's template structure — never substitute your own format
• Fill in concrete data — commit counts, test results, actual file paths, real beads IDs
• Check applicable checkboxes — [x] for items that apply, [ ] for items that don't
• Include "Closes beads-xxx" in the Beads section (required for auto-close in /verify)

Step 6: Validate Context and Record Stage Transition

bash scripts/beads-context.sh validate <id>
bash scripts/beads-context.sh stage-transition <id> ship review \
  --summary "<PR created, checks pending>" \
  --decisions "<template sections filled, beads linked>" \
  --artifacts "<PR URL, branch name>" \
  --next "<review focus areas>"

Team sync after PR

After PR is created, sync issue state to GitHub and verify 1:1 mapping:

# Sync issue state to GitHub
forge team sync 2>&1 || true

# Verify 1:1 mapping
forge team verify 2>&1 || true

Example Output

✓ Validation: /validate passed (all 4 checks — fresh output confirmed)
✓ Freshness: Branch is up-to-date with master
✓ Beads: Marked done & synced (forge-xyz)
✓ Pushed: feat/stripe-billing
✓ PR created: https://github.com/.../pull/123
  - PR body: Problem → Root Cause → Fix → Value (narrative format)
  - Beads linked: forge-xyz
  - Implementation details in collapsible section

⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
   Poll for up to 60 seconds. If checks are still pending, stop here.

Next: /review <pr-number> (when automated checks complete or new feedback appears)

Integration with Workflow

Utility: /status     → Understand current context before starting
Stage 1: /plan       → Design intent → research → branch + worktree + task list
Stage 2: /dev        → Implement each task with subagent-driven TDD
Stage 3: /validate      → Type check, lint, tests, security — all fresh output
Stage 4: /ship       → Push + create PR (you are here)
Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
Stage 6: /premerge   → Update docs, hand off PR to user
Stage 7: /verify     → Post-merge CI check on main

Tips

• Use the project's PR template: Always read .github/pull_request_template.md (or equivalent) and populate it — never substitute your own format
• Fill every section: Even if "N/A" — empty/missing sections cause review friction
• Include "Closes beads-xxx": Required for auto-close in /verify
• Concrete data only: Test counts, file paths, commit SHAs — not placeholder text
• Poll briefly, then stop: Check PR status for up to 60 seconds, then hand off if checks are still pending
• NO auto-merge: Always wait for /review phase