/deploy

name: deploy
description: Pre-flight checks then deploy. Validates env vars, migrations, bundle size, runs /ship audit, then deploys via git push or platform CLI.
argument-hint: "<environment>"

Deploy

Full pre-flight validation → deploy pipeline. Closes the audit-to-production loop.

Process

Step 1: Detect Deploy Target

Check project for deploy configuration:

• `vercel.json` or `.vercel/` → Vercel (git push)
• `railway.toml` or `railway.json` → Railway
• `fly.toml` → Fly.io
• `wrangler.toml` → Cloudflare Workers
• `.github/workflows/` with deploy steps → CI/CD pipeline
• `Dockerfile` → Container-based deploy
• None found → ask user for deploy target

Step 2: Pre-Flight Checks

Run these checks BEFORE deploying (fail fast):

**2a. Environment Validation**

node ${CLAUDE_PLUGIN_ROOT}/tools/env-validator.mjs <project-directory>

If `deploy_ready: false` → STOP. Show missing vars. Do not deploy.

**2b. Migration Safety**

node ${CLAUDE_PLUGIN_ROOT}/tools/migration-checker.mjs <project-directory>

If `deploy_safe: false` → WARN. Show pending migrations. Ask user to confirm.

**If a Supabase MCP server is connected** (check your available tools for `supabase`), verify migration state against the *actual* database before deploying, not just the local migration files: list applied migrations and confirm the pending ones aren't already applied or in conflict. This catches the "migration ran on the dashboard but not in the repo" drift that breaks deploys.

If there are pending migrations, verify they are reversible:

• For Drizzle: check that corresponding `down` SQL or rollback logic exists
• For Prisma: confirm `prisma migrate resolve` can undo the migration
• For Knex: verify the `down()` function exists and is not empty
• If the migration is destructive (dropping columns, renaming tables, deleting data) and has no rollback path → STOP. This is not safe to deploy without a manual rollback plan.

**2c. Bundle Size Check**

node ${CLAUDE_PLUGIN_ROOT}/tools/bundle-tracker.mjs <project-directory> --save

If bundle grew >50KB since last check → WARN. Show diff.

**2d. Git Status** Check for uncommitted changes:

git status --porcelain

If dirty working tree → WARN. Suggest committing first.

**2e. Rollback Plan**

Before deploying, establish a rollback plan. Every deploy must have a way back.

Record the current production commit hash:

git rev-parse HEAD

Store this value — it is your safety net. If anything goes wrong after deploy, this is the commit you revert to.

Verify the rollback command is ready:

git revert <commit> --no-edit

Do not execute this yet. Confirm the command is syntactically correct and the commit hash is valid. The goal is to have a copy-paste rollback ready before you need it — not after you're panicking at 2am.

For database changes:

• Confirm the migration has a working `down` migration (checked in Step 2b)
• If the migration drops a column or table, the data is gone. There is no rollback. You need a backup strategy instead: `pg_dump` the affected tables before deploying, or use a feature flag to decouple the schema change from the code change
• For additive-only migrations (new columns, new tables), rollback is safe — the old code simply ignores the new schema

For breaking API changes:

• Confirm that API consumers can handle both the old and new response shapes during the transition window
• If the API serves mobile clients or third-party integrations, a breaking change without versioning is not a rollback — it is a second outage
• Prefer additive changes (new fields) over destructive changes (removed/renamed fields)

Document the rollback steps in a format that can be executed under pressure:

ROLLBACK PLAN:
1. git revert <new-commit-hash> --no-edit
2. git push origin main
3. [If DB migration]: run down migration or restore from backup
4. Verify health check passes after rollback

Step 3: Run Ship Audit

Run the full `/ship` scorecard. If overall score < 60 → WARN but don't block (user decides).

A score below 60 means there are known issues going to production. That is a conscious decision, not an accident. Log it so the post-deploy summary reflects the risk accepted.

Step 4: Deploy

Based on detected target:

**Vercel (git push — REQUIRED for this user):**

git push origin main

NEVER use `vercel` CLI. Always git push.

**Railway:**

railway up

**Fly.io:**

fly deploy

**Cloudflare Workers:**

npx wrangler deploy

**CI/CD:**

git push origin main

Then check CI status:

gh run list --limit 1 --json status,conclusion

Record the deploy start time. You will need this for the post-deploy summary.

Step 4b: Smoke Tests

After deploy lands but before declaring success, verify the application actually works for real users. A successful `git push` is not a successful deploy — it is a successful file transfer.

Hit 3-5 critical user paths against the production URL:

node ${CLAUDE_PLUGIN_ROOT}/tools/api-smoke-test.mjs <production-url>

At minimum, verify: 1. **Homepage** returns 200 (not 500, not a redirect loop, not a blank page) 2. **Login/auth endpoint** responds (does not need to complete auth — just confirm it is not crashing) 3. **Core feature endpoint** returns valid JSON with the expected shape 4. **API health endpoint** (if one exists) returns 200 with a response body 5. **Static assets** load (CSS/JS files return 200, not 404 — a broken asset build is invisible to health checks but catastrophic to users)

Verify response codes and content types:

• 200 responses should return the expected `Content-Type` (HTML for pages, JSON for APIs)
• Watch for soft failures: a 200 that returns an error page, or a JSON response with `{ "error": true }` inside a 200 status code
• Check that responses are not empty (a 200 with a 0-byte body is not healthy)

If Playwright MCP is available, run a quick brows