Pwp Deploy

PWP Deployment Protocol

You are now operating under the Project Workflow Protocol's deployment discipline. Follow this structured approach for every deployment task.

Context: $ARGUMENTS

Phase 1: Environment Awareness

Understand the environment ladder:

local → staging → production

Rules

• Code flows one direction: local → staging → production. Never hotfix production directly.
• Staging must mirror production config (same env vars shape, services, region).
• Database migrations run on staging first. Always.

Phase 2: Pre-Deploy Checklist

Before deploying to production, verify ALL items:

- [ ] All pre-merge verification passed (tsc, build, tests)
- [ ] Staging deployment succeeded
- [ ] Staging smoke test passed (critical user journey works)
- [ ] Database migrations tested on staging
- [ ] Environment variables verified (no missing keys)
- [ ] Feature flags configured (if progressive rollout)
- [ ] Rollback plan documented (what to revert and how)
- [ ] Team notified of deploy window

Phase 3: Choose Deployment Strategy

Direct Deploy (Solo / Small Team)

git push origin main → CI builds → auto-deploy → smoke test

When: Solo builders, early-stage, low-traffic apps.

Staged Rollout (Growth / Enterprise)

main → staging deploy → smoke test → canary (5%) → monitor → full rollout

When: Significant user base, changes with behavioral risk.

Blue-Green Deployment (Zero Downtime)

Two identical environments. Switch traffic from old (blue) to new (green). When: Zero-downtime requirement, critical production services.

Phase 4: Database Migration Safety

Migrations are the highest-risk part of deployment:

1. Reversible always. Every up has a corresponding down.
2. Two-phase column drops. Deploy code that stops using the column first. Drop column in next deploy.
3. Test on production-shaped data. Not empty databases.
4. Backup before migration. Automated or manual — but always before.
5. Separate migration deploys from feature deploys. Don't combine schema changes with app logic.

Phase 5: Feature Flags

For changes with behavioral risk:

if (featureFlags.isEnabled('new-checkout-flow')) {
  return <NewCheckout />;
}
return <LegacyCheckout />;

Rules

• Flags are temporary. Set a removal date when creating.
• Dead flags (>30 days post-full-rollout) must be cleaned up.
• Flag state tracked in central config, not scattered across code.

Phase 6: Rollback Strategy

Every deploy must have a documented rollback plan:

Speed Targets

• Code revert: Under 5 minutes (automated CI/CD redeploy)
• Migration revert: Under 15 minutes (tested down migration)
• Full rollback: Under 30 minutes (restore from backup if needed)

Phase 7: Post-Deploy Verification

After every production deploy:

- [ ] Application loads without errors
- [ ] Critical user journey works (signup, core action, payment)
- [ ] No new errors in monitoring / error tracking
- [ ] No performance regression (response times, page load)
- [ ] Database is healthy (no locked queries, no pool exhaustion)
- [ ] Logs show expected behavior (no unexpected warnings)

Phase 8: Monitoring & Observability

Set up BEFORE you need it:

Alert Thresholds

• Error rate > 2x baseline → Slack notification
• Error rate > 5x baseline → Pager alert
• Uptime check fails → Immediate alert
• Response time > 3x baseline → Warning

Quick Checklist

• Environment ladder defined
• Pre-deploy checklist completed
• Database migrations tested on staging
• Rollback plan documented
• Post-deploy verification passed
• Monitoring active and alerting configured
• Feature flags have removal dates