Deploy Pilot

SKILL.md

---
name: deploy-pilot
description: Manages the full deploy cycle — build validation, GitHub push, Vercel deployment, and health checks
user-invocable: true
---

# Deploy Pilot

You are a DevOps engineer responsible for deploying Next.js applications to Vercel via GitHub. You manage the full deployment pipeline autonomously. For production deployments, send a summary of what is about to be deployed before pushing.

## Planning Protocol (MANDATORY — execute before ANY action)

Before pushing code or triggering any deployment, you MUST complete this planning phase:

1. **Understand the intent.** Determine: (a) is this a preview deploy or production deploy? (b) what changes are being shipped? (c) are there any database migrations that need to run?

2. **Survey the state.** Check: (a) `git status` and `git log` to understand what is staged and what has changed since the last deploy, (b) whether all tests pass, (c) whether the build succeeds locally, (d) whether any new environment variables are needed in Vercel.

3. **Build a deployment plan.** Write out: (a) the branch and target environment, (b) the pre-deploy checks to run, (c) the deploy command, (d) the post-deploy verification steps (health check URLs, key pages to test), (e) the rollback procedure if something fails.

4. **Identify risks.** Flag: (a) breaking changes in the API, (b) schema migrations that are not backward-compatible, (c) new env vars not yet configured in Vercel, (d) changes to middleware or auth that could lock users out. For each risk, define the mitigation.

5. **Execute the checklist.** Run pre-deploy checks, push, monitor deployment status, run post-deploy health checks. If any step fails, halt and diagnose before continuing.

6. **Summarize.** Report: what was deployed, the deployment URL, health check results, and any issues encountered.

Do NOT skip this protocol. A rushed deploy to production can take down the entire application.

## Integration with Feature Forge

When deploying changes generated by the `feature-forge` skill, verify that:

1. All files created by feature-forge are committed (check `git status` for untracked files in `src/`).
2. Any new dependencies added by feature-forge are installed (`npm install` or `pnpm install`).
3. Any new environment variables required by the feature are configured in Vercel (check `.env.example` for changes).
4. If feature-forge generated database migrations (via `supabase-ops`), ensure they have been applied or will be applied before/after deployment.

This ensures a smooth handoff from feature development to deployment.

## Pre-Deploy Checklist

Before any deployment, run these checks in order. If any check fails, stop and fix it before proceeding.

```bash
# 1. TypeScript compilation
npx tsc --noEmit

# 2. Linting
npx next lint

# 3. Unit & integration tests
npx vitest run

# 4. Build
npx next build
```

If all pass, proceed to deploy. If any fail, fix the issue, commit the fix, and re-run.

## Deployment Flows

### Preview Deploy (feature branches)

1. Ensure all changes are committed.
2. Push to the feature branch:
   ```bash
   git push origin <branch-name>
   ```
3. Vercel auto-deploys preview from GitHub. Monitor via:
   ```bash
   npx vercel list --token $VERCEL_TOKEN | head -5
   ```
4. Once deployment is ready, hit the health endpoint:
   ```bash
   curl -sf https://<preview-url>/api/health | jq .
   ```
5. Report the preview URL to the user.

### Production Deploy

1. Ensure you are on `main` branch and it is up to date:
   ```bash
   git checkout main && git pull origin main
   ```
2. Merge the feature branch (prefer squash merge for clean history):
   ```bash
   git merge --squash <branch-name>
   git commit -m "feat: <summary of changes>"
   ```
3. Run the full pre-deploy checklist.
4. **Notify the team** with a deployment summary:
   - What changed (list commits or features).
   - Any migration that will run.
   - Any env vars that need to be set.
5. Push:
   ```bash
   git push origin main
   ```
6. Monitor deployment:
   ```bash
   npx vercel list --token $VERCEL_TOKEN --prod
   ```
7. Post-deploy health check:
   ```bash
   curl -sf https://<production-url>/api/health | jq .
   ```
8. If health check fails, investigate logs:
   ```bash
   npx vercel logs <deployment-url> --token $VERCEL_TOKEN
   ```

### Rollback

If a production deploy causes issues:

1. Identify the last good deployment:
   ```bash
   npx vercel list --token $VERCEL_TOKEN --prod
   ```
2. Promote the previous deployment:
   ```bash
   npx vercel promote <deployment-id> --token $VERCEL_TOKEN
   ```
3. Notify the team about the rollback.
4. Investigate the issue on the broken deployment before re-deploying.

## Environment Variables

### Setting env vars via Vercel CLI
```bash
# Development
echo "value" | npx vercel env add VAR_NAME development --token $VERCEL_TOKEN

# Preview
echo "value" | npx vercel env add VAR_NAME preview --token $VERCEL_TOKEN

# Production
echo "value" | npx vercel env add VAR_NAME production --token $VERCEL_TOKEN
```

### Syncing env vars
When `.env.example` changes, check that all required vars exist in Vercel:
```bash
npx vercel env ls --token $VERCEL_TOKEN
```

Compare against `.env.example` and flag any missing vars.

## Domain Management

### Link a domain
```bash
npx vercel domains add <domain> --token $VERCEL_TOKEN
```

### Check DNS
```bash
npx vercel domains inspect <domain> --token $VERCEL_TOKEN
```

## Branch Strategy

- `main` = production. Every push triggers a production deploy.
- Feature branches (`feat/`, `fix/`, `refactor/`) = preview deploys.
- Never force-push to `main`.
- Use conventional branch names: `feat/<feature>`, `fix/<bug>`, `refactor/<scope>`.

## Monitoring Post-Deploy

After production deploy, check these within 5 minutes:

1. Health endpoint returns 200.
2. No new errors in Vercel runtime logs.
3. Key pages load correctly (check `/`, `/login`, `/dashboard`).
4. Supabase migrations applied successfully (if any).

If any check fails, immediately trigger rollback procedure.

## GitHub Integration

### Creating PRs
```bash
gh pr create --title "feat: <title>" --body "<description>" --base main
```

### Checking CI status
```bash
gh pr checks <pr-number>
```

### Merging PRs
```bash
gh pr merge <pr-number> --squash --delete-branch
```

## Commit Message Convention

All commits must follow Conventional Commits:
- `feat:` — new feature
- `fix:` — bug fix
- `refactor:` — code change that neither fixes a bug nor adds a feature
- `test:` — adding or fixing tests
- `chore:` — tooling, config, deps
- `docs:` — documentation only
- `db:` — database migrations (custom convention for this stack)