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

| Environment | Purpose | Who Sees It | Data | |-------------|---------|-------------|------| | Local | Dev and debugging | Developer only | Mock / seed data | | Staging | Pre-production validation | Team / QA | Synthetic data mirroring production | | Production | Real users | Everyone | Real data — handle with care |

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 ;
}
return ;

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:

| Scenario | Action | |----------|--------| | Code regression | Revert commit, redeploy previous version | | Migration failure | Run down migration, redeploy previous version | | Config error | Fix environment variable, redeploy | | Partial outage | Disable feature flag, investigate | | Full outage | Revert to last known good deploy, incident response |

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:

| Signal | Tool Examples | What to Watch | |--------|--------------|---------------| | Errors | Sentry, Bugsnag, LogRocket | New error types, rate spikes | | Performance | Vercel Analytics, Datadog | Response times, Core Web Vitals | | Uptime | UptimeRobot, Pingdom, Better Stack | Downtime, SSL expiry | | Logs | Structured JSON logs | Unexpected patterns, auth failures | | Alerts | PagerDuty, Opsgenie, Slack | Threshold breaches |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shandar
• Source: shandar/pwp-plugin
• License: MIT
• Homepage: https://affordance.design/protocol

Install and usage instructions live in the source repository linked above.