/ship

description: Complete PR workflow from commit to production with validation
argument-hint: "[--strategy STRATEGY] [--skip-tests] [--dry-run] [--state-file PATH]"
allowed-tools: Bash(git:*), Bash(gh:*), Bash(npm:*), Bash(node:*), Read, Write, Edit, Glob, Grep, Task

/ship - Complete PR Workflow

End-to-end workflow: commit - PR - CI - review - merge - deploy - validate - production.

Auto-adapts to your project's CI platform, deployment platform, and branch strategy.

---

<mandatory-steps>

Mandatory Steps - No Shortcuts

Phase 4 (CI & Review Monitor Loop) is mandatory even when called from /next-task.

| Step | Requirement | Why It Matters | |------|-------------|----------------| | 3-minute initial wait | Must wait after PR creation | Auto-reviewers need time to analyze | | Monitor loop iterations | Must run the full loop | Catches issues humans miss | | Address all comments | Zero unresolved threads | Quality gate, blocks merge otherwise |

Forbidden Actions

• Checking CI once and proceeding to merge
• Skipping the 3-minute initial wait for auto-reviewers
• Ignoring "minor" or "nit" comments
• Merging with unresolved comment threads
• Rationalizing "no comments yet means ready to merge"

Required Verification Output

Before proceeding to merge, output:

[VERIFIED] Phase 4: wait=180s, iterations=N, unresolved=0

</mandatory-steps>

---

Quick Reference

| Phase | Description | Details | |-------|-------------|---------| | 1-3 | Pre-flight, Commit, Create PR | This file | | 4 | CI & Review Monitor Loop | See `ship-ci-review-loop.md` | | 5 | Subagent Review (standalone) | This file | | 6 | Merge PR | This file | | 7-10 | Deploy & Validate | See `ship-deployment.md` | | 11-12 | Cleanup & Report | This file | | Errors | Error handling & rollback | See `ship-error-handling.md` |

Integration with /next-task

When called from `/next-task` workflow (via `--state-file`):

• **SKIPS Phase 5** internal review agents (already done by Phase 9 review loop)
• **SKIPS deslop/docs** (already done by deslop-work, docs-updater)
• **Trusts** that all quality gates passed

**CRITICAL: Phase 4 ALWAYS runs** - even from /next-task. External auto-reviewers (Gemini, Copilot, CodeRabbit) comment AFTER PR creation and must be addressed.

When called standalone, runs full workflow including review.

Arguments

Parse from $ARGUMENTS:

• **--strategy**: Merge strategy: `squash` (default) | `merge` | `rebase`
• **--skip-tests**: Skip test validation (dangerous)
• **--dry-run**: Show what would happen without executing
• **--state-file**: Path to workflow state file (for /next-task integration)

State Integration

const { getPluginRoot } = require('@awesome-slash/lib/cross-platform');
const pluginRoot = getPluginRoot('ship');
if (!pluginRoot) { console.error('Error: Could not locate ship plugin root'); process.exit(1); }

const args = '$ARGUMENTS'.split(' ');
const stateIdx = args.indexOf('--state-file');
let workflowState = null;
if (stateIdx >= 0) {
  workflowState = require(`${pluginRoot}/lib/state/workflow-state.js`);
}

function updatePhase(phase, result) {
  if (!workflowState) return;
  workflowState.startPhase(phase);
  if (result) workflowState.completePhase(result);
}

Phase 1: Pre-flight Checks

# Detect platform and project configuration
PLUGIN_PATH=$(node -e "const { getPluginRoot, normalizePathForRequire } = require('@awesome-slash/lib/cross-platform'); const root = getPluginRoot('ship'); if (!root) { console.error('Error: Could not locate ship plugin root'); process.exit(1); } console.log(normalizePathForRequire(root));")
PLATFORM=$(node "$PLUGIN_PATH/lib/platform/detect-platform.js")
TOOLS=$(node "$PLUGIN_PATH/lib/platform/verify-tools.js")

# Extract critical info
CI_PLATFORM=$(echo $PLATFORM | jq -r '.ci')
DEPLOYMENT=$(echo $PLATFORM | jq -r '.deployment')
BRANCH_STRATEGY=$(echo $PLATFORM | jq -r '.branchStrategy')
MAIN_BRANCH=$(echo $PLATFORM | jq -r '.mainBranch')

# Check required tools
GH_AVAILABLE=$(echo $TOOLS | jq -r '.gh.available')
if [ "$GH_AVAILABLE" != "true" ]; then
  echo "ERROR: GitHub CLI (gh) required for PR workflow"
  exit 1
fi

# Determine workflow type
if [ "$BRANCH_STRATEGY" = "multi-branch" ]; then
  WORKFLOW="dev-prod"
  PROD_BRANCH="stable"
else
  WORKFLOW="single-branch"
fi

Verify Git Status

# Check for uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  NEEDS_COMMIT="true"
else
  NEEDS_COMMIT="false"
fi

# Must be on feature branch
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
  echo "ERROR: Cannot ship from $MAIN_BRANCH, must be on feature branch"
  exit 1
fi

Dry Run Mode

If `--dry-run` provided, show plan and exit:

## Dry Run: What Would Happen
**Branch**: ${CURRENT_BRANCH} → **Target**: ${MAIN_BRANCH}
**Workflow**: ${WORKFLOW} | **CI**: ${CI_PLATFORM} | **Deploy**: ${DEPLOYMENT}

Phase 2: Commit Current Work

Only if `NEEDS_COMMIT=true`:

# Stage relevant files (exclude secrets)
git status --porcelain | awk '{print $2}' | grep -v '\.env' | xargs git add

# Generate semantic commit message
# Format: <type>(<scope>): <subject>
# Types: feat, fix, docs, refactor, test, chore

git commit -m "$(cat <<'EOF'
${COMMIT_MESSAGE}
EOF
)"

COMMIT_SHA=$(git rev-parse HEAD)
echo "[OK] Committed: $COMMIT_SHA"

Phase 3: Create Pull Request

# Push to remote
git push -u origin $CURRENT_BRANCH

# Create PR
PR_URL=$(gh pr create \
  --base "$MAIN_BRANCH" \
  --title "$PR_TITLE" \
  --body "$(cat <<'EOF'
## Summary
- Bullet points of changes

## Test Plan
- How to test

## Related Issues
Closes #X
EOF
)")

PR_NUMBER=$(echo $PR_URL | grep -oP '/pull/\K\d+')
echo "[OK] Created PR #$PR_NUMBER: $PR_URL"

<phase-4>

Phase 4: CI & Review Monitor Loop

**Blocking gate** - This phase is mandatory. Cannot proceed to merge without completing.

See `ship-ci-review-loop.md` for full implementation detail