Ship

/ship - Production Deployment

Execute safe production deployment directly with comprehensive quality gates and integrated safety audits. All phases run inline — no subagent.

Default behavior: Deploys directly to PRODUCTION

MANDATORY: FIX ALL ISSUES EVERY RUN (ZERO EXCEPTIONS)

Every /ship invocation MUST execute ALL fix phases in order. NEVER skip a phase for efficiency, even if the code change is small or "just a copy change".

If a phase finds issues, FIX THEM INLINE before moving to the next phase. Do not defer. Do not warn-and-continue for fixable issues. The goal is: every /ship run leaves the repo in a strictly better state than it found it.

Warnings are NOT acceptable. biome check . must return 0 errors AND 0 warnings. Fix warnings by: (1) auto-fixing with biome check --fix, (2) manually fixing remaining issues, or (3) suppressing false positives in biome.json overrides with justification. "Pre-existing warnings" is not an excuse — fix them all.

Dependabot is NOT optional. If gh api repos/{owner}/{repo}/dependabot/alerts returns open alerts with available fixes, add overrides to package.json, run install, verify build, commit, and push — all within this run.

Stale lockfile check (MANDATORY). Before fixing Dependabot alerts, check which lockfile(s) the alerts reference (manifest_path in the API response). If alerts reference a lockfile the project doesn't use (e.g., pnpm-lock.yaml when project uses bun.lock), the stale lockfile MUST be deleted from git and added to .gitignore.

# Detect active package manager
ACTIVE_LOCK=""
[ -f bun.lock ] && ACTIVE_LOCK="bun.lock"
[ -f pnpm-lock.yaml ] && ACTIVE_LOCK="pnpm-lock.yaml"
[ -f package-lock.json ] && ACTIVE_LOCK="package-lock.json"

# Remove any OTHER tracked lockfiles that aren't the active one
for STALE in pnpm-lock.yaml package-lock.json bun.lock yarn.lock; do
  if [ "$STALE" != "$ACTIVE_LOCK" ] && git ls-files --error-unmatch "$STALE" 2>/dev/null; then
    git rm --cached "$STALE"
    echo "$STALE" >> .gitignore
    echo "Removed stale lockfile: $STALE (was causing false Dependabot alerts)"
  fi
done

After fixing Dependabot alerts, VERIFY they actually closed. Wait 60s after push, then re-check:

sleep 60
REMAINING=$(gh api "repos/${REPO}/dependabot/alerts" --jq '[.[] | select(.state=="open")] | length')
if [ "$REMAINING" -gt 0 ]; then
  gh api "repos/${REPO}/dependabot/alerts" --jq '.[] | select(.state=="open") | "\(.number): \(.dependency.manifest_path)"'
fi

Usage

/ship [optional instructions]

Deployment Targets

Examples

• /ship — Deploy to production with full verification
• /ship the auth feature — Deploy specific feature to production
• /ship --staging — Deploy to staging first, then promote to prod
• /ship --allow-lint-errors — Override lint failures (with audit trail)
• /ship --audit — Run safety audit only, no deployment
• /ship --audit tier2 — Run Tier 2 investigation audit

Tools Available

osgrep — Code Search During Gates

osgrep query "throw.*module scope" --mode fulltext   # Find risky patterns
osgrep query "validateClientEnv" -n 20               # Find all validation calls

qmd — Documentation Search

qmd query "deployment checklist"    # Search project docs
qmd query "rollback procedure"      # Find rollback docs

bd — Task Tracking (MANDATORY)

bd create --title="Deploy: run quality gates" --type=task --priority=1   # Track deployment
bd update <id> --status=in_progress                                       # Claim
bd close <id> --reason="Deployed to production"                           # Close

Before running /ship: Create a beads issue for the deployment itself (bd create --title="Deploy <feature>" --type=task) if one doesn't already exist. Close it only after post-deploy verification passes.

If .beads/ does not exist and this is a git repo:

git config beads.role maintainer && bd init --quiet --skip-hooks

If bd is not installed, warn the user once and continue (don't block the deploy).

CRITICAL: NO TASK MANAGEMENT TOOLS

DO NOT use TodoWrite, TaskCreate, or TaskUpdate tools. Use bd (beads) for task tracking instead. This is a project-wide rule — see CLAUDE.md "Beads Task Tracking Rule".

Print a short status line when transitioning phases:

-- Phase 0 OK -> Phase 1: Build & Test --

Just execute the phases in order. Do the work, don't track the work in TodoWrite.

DEPLOYMENT TARGET (DEFAULT: PRODUCTION)

Default behavior: Deploy directly to production. The /ship command deploys to production unless explicitly told otherwise.

Staging-first workflow: If user specifies "staging first", "to staging", or --staging:

1. Deploy to staging/preview environment first
2. Display staging URL and verification steps
3. Wait for explicit "promote to production" confirmation
4. Then run production deployment

Flags:

• (default): Deploy to production
• --staging or "to staging first": Deploy to staging, then prompt for production
• --staging-only: Deploy to staging only, skip production
• --prod or --production: Explicit production deploy (same as default)
• --no-babysit: Skip Phase 6 PR babysitter
• --babysit: Force Phase 6 even on default branch (monitor CI after direct push)

EXECUTION PROTOCOL

CODE SEARCH

Use standard tools (Grep, Glob, Read) for code discovery. Use osgrep if available for AST-aware search, but never block on it — fall back to Grep/Glob immediately if unavailable.

Reference Files Index

All reference files are in ~/.claude/skills/ship/references/. Read the relevant ones for each phase.

Phase Execution Order

Read ALL reference files at the start of a /ship run. Execute phases in this exact order:

1. Phase -1: Repository context verification (from pre-deploy-checks.md)
2. Phase -0: Merge conflict auto-resolution (from pre-deploy-checks.md)
3. Phase 0: Code quality / lint auto-fixing (from code-quality.md)
4. Phase 0.5: Deployment rate limit check (from pre-deploy-checks.md)
5. Phase 1: Build & test (from build-and-test.md)
6. Phase 1.1: API contract verification (from build-and-test.md)
7. Phase 1.25: Security audit (from security-audit.md)
8. Phase 1.26: Code scanning hygiene (from security-audit.md)
9. Phase 1.3: React scope & env safety (from react-safety.md)
10. Phase 1.35: useEffect abuse check (from react-safety.md)
11. Phase 1.4: SEO & sitemap consistency (from seo-and-session.md)
12. Phase 1.42: Session invalidation check (from seo-and-session.md)
13. Phase 1.45: Third-party config & infra protection (from infra-and-admin.md) 13.5. Phase 1.27: OWASP Top 10 sweep on changed files (from ant-verification-protocol.md Section 1) 13.6. Phase 1.28: Supply chain & enhanced review on new deps (from ant-verification-protocol.md Section 5)
14. Phase 1.46: Admin-user sync verification (from infra-and-admin.md)
15. Phase 1.5: Deployment verification for risky changes (from infra-and-admin.md)
16. Phase 2: Manual override path (from deployment.md)
17. Phase 3: GitHub deployment (from deployment.md)
18. Phase 3.5: README & changelog auto-update (from deployment.md)
19. Phase 4: Downstream deployments (from deployment.md)
20. Phase 4.1: Post-deploy verification (from post-deploy.md)
21. Phase 4.2: Multi-agent code review (from post-deploy.md)
22. Phase 4.3: Web performance audit (from post-deploy.md)
23. Phase 4.35: Visual regression check (from post-deploy.md)
24. Phase 4.5: Deployment failure rollback (from post-deploy.md)
25. Phase 4.6: GitHub Actions CI gate (from post-deploy.md)
26. Phase 5: Post-deploy monitoring (from post-deploy.md)
27. Phase 6: PR babysitter (from post-deploy.md)

Pre-Ship Verification Checklist (Non-Negotiable)

Before declaring ANY deploy complete, verify ALL of these:

1. Bundle hash changed — curl -s <URL> | grep 'index-' must show a NEW hash vs. previous deploy
2. Page loads correctly — curl the actual page, verify it returns 200 and contains expected content
3. API endpoints work — test at least one authenticated endpoint returns data, not "Unauthorized"
4. New routes reachable — if you added a route, verify it doesn't 404 or get swallowed by a catch-all
5. No stale cache — if cf-cache-status: HIT, verify it's serving the new content not old
6. Clean build — for Cloudflare Workers: rm -rf dist && tsc -b && vite build && wrangler deploy (never just wrangler deploy)
7. Type definitions correct — for CF Workers, edit worker-configuration.d.ts (ambient), not just src/worker/env.d.ts (module)

If ANY check fails: do NOT say "deployed successfully". Fix it first.

Safety Audit Tiers

Tier 1 — Critical (always runs on deploy)

• Silent failure detection — env vars without validation
• Silent React startup failures — env validation throwing before mount
• Security audit — vulnerabilities, exposed secrets
• Test execution verification

Tier 2 — Investigation (--audit tier2)

Uses systematic-debugging:

• Blind spot auditor — edge cases missing test coverage
• Test quality gate — tests that pass but don't verify real behavior
• Rate limit protector — public endpoints missing rate limiting

Tier 3 — Deep Analysis (--audit tier3)

Uses carmack-mode-engineer:

• Code archaeology — "old/legacy" code that's actually critical
• Critical systems guard — unprotected auth/payment/data-deletion paths
• Build reproduction harnesses for complex issues

Full (--audit full)

Runs all three tiers in sequence.

Cross-Platform CI Verification (Rust/Multi-Platform PRs)

For PRs to open source Rust projects with multi-platform CI matrices:

# 1. Format check (CI rejects ANY formatting diff)
cargo fmt --all -- --check

# 2. Clippy with warnings-as-errors
cargo clippy --all-targets --all-features

# 3. Check for conditional compilation blind spots
grep -n "let mut" src/**/*.rs | while read line; do
  file=$(echo "$line" | cut -d: -f1)
  var=$(echo "$line" | grep -oP 'let mut \K\w+')
  if grep -A20 "let mut $var" "$file" | grep -q '#\[cfg(target_os'; then
    echo "WARNING: $file — $var may need #[allow(unused_mut)]"
  fi
done

After push: gh pr checks <PR_NUMBER> --watch

OUTPUT REQUIREMENTS

• Always show clear phase headers marking current stage
• Use visual indicators for success, failure, warnings
• Display progress bars for multi-step operations
• Provide actionable error messages when builds or tests fail
• Show deployment summary table with service name, status, and live URL
• Include estimated time for each phase
• Display comprehensive banners at phase transitions

SAFETY CONSTRAINTS

Critical Rules:

• FAIL FAST: Terminate immediately on build errors or test failures
• GitHub deployment ALWAYS happens before any other platform
• Multiple confirmation gates prevent accidental shipping
• All override actions are permanently logged
• Never silently skip tests or quality checks
• Refuse ambiguous commands that might bypass gates
• Data verification is mandatory for risky changes unless explicitly overridden
• NEVER execute destructive infrastructure commands — these require human execution
• NEVER modify or replace .tfstate files
• ALWAYS show terraform plan output to user before any terraform apply

Phase-Specific Rules:

• Phase -1: NEVER proceed if not in git repo or remote unreachable
• Phase 1: NEVER run npm test or full npx vitest run — always use --changed and timeout
• Phase 1: NEVER retry tests more than 3 times — stop and report failures
• Phase 1: ALWAYS run pkill -f vitest 2>/dev/null after every test invocation
• Phase -0: NEVER push or tag during merge conflict resolution
• Phase 0: NEVER deploy with lint errors unless explicit override
• Phase 0: After Biome auto-fix on inline-HTML projects (CF Workers, SSR), ALWAYS run embedded JS string safety check (Stage 1.7 in code-quality.md) — Biome's noUselessEscapeInString silently breaks JS inside HTML template strings
• Phase 0.5: BLOCK on 20+ deployments unless --force-override
• Phase 1: BLOCK on ANY test failure
• Phase 1.1: BLOCK if frontend calls API endpoints with no backend handler
• Phase 1.25: BLOCK on MODERATE+ vulnerabilities unless override
• Phase 1.26: WARN on TODO/FIXME/HACK comments in changed files (auto-fix to NOTE:)
• Phase 1.26: WARN on workflow files missing top-level permissions (auto-fix to read-only)
• Phase 1.26: BLOCK on permissions: write-all at workflow top level (must narrow to job-level)
• Phase 1.3: BLOCK if env validation throws at module scope without fallbacks
• Phase 1.4: BLOCK if noindex pages appear in sitemap or sitemaps are out of sync
• Phase 1.42: BLOCK if no vite:preloadError handler (deploy will log users out)
• Phase 1.42: BLOCK if no CDN-Cache-Control: no-store header on HTML responses
• Phase 4.2: Run multi-agent review when changes span 3+ files or touch security paths
• Phase 4.2: BLOCK if any reviewer finds CRITICAL security/performance issue
• Phase 4.3: WARN if Lighthouse score drops below 50 (severe perf regression)
• Phase 4.35: BLOCK if mobile screenshot shows blank page (broken rendering)
• Phase 4.35: WARN if mobile screenshot shows horizontal scroll (responsive bug)
• Phase 4: WARN if deployed version.json SHA doesn't match local HEAD (stale deploy)
• Phase 4: BLOCK if CLOUDFLARE_API_TOKEN in .env.local overrides wrangler OAuth (auth conflict)
• Phase 4: Verify version.json is in .gitignore and not git-tracked (prevents stale commits)
• Phase 4: Verify service worker has version.json in NETWORK_ONLY patterns (prevents SW caching)
• Phase 1.46: BLOCK if visibility refetch triggers loading spinner (full-screen flash on tab switch)
• Phase 1.46: WARN if user data hooks lack background refresh (admin changes invisible until reload)
• Phase 1.46: WARN if admin status-change endpoints don't clean up dependent fields
• Phase 1.46: WARN if optimistic updates don't re-sync with server after success
• Phase 1.45: BLOCK if CSP img-src/script-src/connect-src missing third-party CDN domains (broken icons with no console errors)
• Phase 1.45: BLOCK if critical third-party env vars missing from wrangler config
• Phase 1.45: BLOCK if raw .innerHTML = without escapeHtml() (XSS risk — especially entry points outside src/)
• Phase 1.45: BLOCK if dangerouslySetInnerHTML without DOMPurify (XSS risk)
• Phase 1.45: BLOCK if JSON.stringify in script tag without </ escaping (script breakout)
• Phase 1.45: WARN if async onClick without disabled state (double-click risk)
• Phase 1.45: WARN if pages call secureFetch without frontend auth guard (degraded UX)
• Phase 1.45: WARN if admin routes throw Error instead of HTTPException(403)
• Phase 1.5: NEVER skip verification if migrations/backfills detected
• Phase 3.5: NEVER update README if tests didn't pass 100%
• Phase 4: NEVER report success without URL verification
• Phase 4.5: NEVER auto-rollback without user confirmation
• Phase 6: NEVER merge the PR automatically — only humans merge
• Phase 6: NEVER force-push, dismiss reviews, or override branch protection
• Phase 6: NEVER modify files outside the PR's changeset
• Phase 6: Max 5 fix-push cycles, max 30 min runtime — then exit with report
• Phase 1.5: NEVER run terraform destroy or apply -auto-approve
• Phase 1.5: BLOCK if terraform plan shows resources being destroyed

Output Discipline (from internal conciseness anchors)

Between tool calls: max 1-2 sentences explaining the next action. Final deployment summary: concise bullet points, no preamble. When fixing issues inline: state what was wrong and what was done in one line each. Never repeat tool output back to the user — they already see it. Phase transitions: one-line banner only (e.g., -- Phase 0 OK -> Phase 1: Build & Test --).

TONE

Be authoritative and safety-focused. Be firm about quality requirements while remaining helpful when errors occur. Emphasize that quality gates protect the user, their data, and their users. When blocking deployment, clearly explain why and provide specific remediation steps.

Instructions

When this skill is invoked:

STEP 1 — Read all reference files:

Read all 9 reference files from ~/.claude/skills/ship/references/ PLUS ~/.claude/skills/shared/ant-verification-protocol.md (ant-level quality gates) to have full deployment protocol available.

STEP 2 — Execute phases in order:

Follow the Phase Execution Order above, reading the detailed instructions from the corresponding reference file for each phase. Fix all issues inline before advancing to the next phase.

STEP 3 — Verify before declaring success (Ant-Level Truthfulness Protocol):

Run the Pre-Ship Verification Checklist. Apply the Truthfulness Protocol from ant-verification-protocol.md Section 2:

• Every claim must be backed by command output (curl, build log, test result)
• Never say "deployed successfully" without curl evidence of new bundle hash
• If ANY check fails, fix it — don't report success with caveats