staging-deployment-phase

<quick_start> <staging_deployment_workflow> Prerequisite-driven staging deployment:

1. Verify PR merged: Confirm pull request merged to main branch
2. Run migrations: Execute database migrations if schema changes exist
3. Trigger deployment: Deploy to staging environment via CI/CD or manual trigger
4. Monitor deployment: Watch deployment logs and progress
5. Run health checks: Verify all services and endpoints operational
6. Generate report: Create staging-ship-report.md with deployment metadata

Example workflow:

Verifying PR merged... ✅
  Merge commit: abc123f "Merge pull request #47"

Checking for migrations...
  Found: migrations/2025_11_add_user_profile.sql
  Running migrations... ✅

Triggering staging deployment...
  Platform: Vercel/Netlify/Railway
  Deployment ID: dpl_abc123
  Status: Building... → Deploying... → Live ✅

Running health checks...
  API: https://staging.example.com/health → 200 OK ✅
  Database: Connected ✅
  Cache: Operational ✅

Staging deployment successful!
Ship report: specs/NNN-slug/staging-ship-report.md
Staging URL: https://staging.example.com

</staging_deployment_workflow>

<trigger_conditions> Auto-invoke when:

• /ship-staging command executed
• User mentions "deploy to staging", "ship to staging", "staging deployment"
• state.yaml shows current_phase: ship-staging
• Deployment model is staging-prod (not direct-prod or local-only)

Prerequisites:

• PR successfully merged to main branch
• CI/CD passing on main branch
• Staging environment configured
• Database migrations prepared (if needed) </trigger_conditions> </quick_start>

Confirm pull request successfully merged before deploying.

Validation:

# Check recent commits for merge commit
git log --oneline -10 | grep "Merge pull request"

# Verify feature branch merged
FEATURE_SLUG="user-profile-editing"
git log --oneline --all | grep -i "$FEATURE_SLUG"

# Confirm on main branch
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo "❌ Not on main branch (currently on $CURRENT_BRANCH)"
  echo "Switch to main: git checkout main && git pull"
  exit 1
fi

echo "✅ PR merged to main"

Blocking conditions:

• Not on main branch → Switch to main first
• No recent merge commit → Feature branch not merged yet
• CI failing on main → Fix CI before deploying

Output:

✅ PR merged to main
  Merge commit: abc123f "Merge pull request #47: Add user profile editing"
  Author: @username
  Merged: 2 minutes ago

Execute database migrations if schema changes exist.

Detection:

# Check for migration files (Node.js example)
if [ -d "migrations" ] && [ -n "$(ls -A migrations/*.sql 2>/dev/null)" ]; then
  echo "✅ Migrations detected"

  # List migrations
  ls -1 migrations/*.sql

  # Run migrations
  npm run migrate:staging

  # Or with migration tool
  # knex migrate:latest --env staging
  # prisma migrate deploy --schema=./schema.prisma

  # Verify migrations applied
  echo "✅ Migrations completed"
else
  echo "ℹ️  No migrations to run"
fi

Error handling:

# If migration fails
if [ $? -ne 0 ]; then
  echo "❌ Migration failed"
  echo "Review migration logs for errors"
  echo "DO NOT proceed with deployment"
  echo ""
  echo "Common issues:"
  echo "  - Syntax errors in SQL"
  echo "  - Constraint violations"
  echo "  - Missing columns in dependent tables"
  exit 1
fi

Rollback procedure:

# If deployment fails after migration
# Rollback migrations
npm run migrate:rollback:staging

# Or manually revert last migration
# psql -h staging-db.example.com -d mydb -f migrations/rollback/2025_11_revert.sql