┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Local     │ →  │   Preview   │ →  │   Staging   │ →  │ Production  │
│   Branch    │    │   (PR)      │    │   (main)    │    │  (manual)   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
     Code              Test              UAT             You Approve

┌─────────────────────────────────────────────────────────────────┐
│                    PHASE A: Code Changes                        │
│  1. Create feature branch                                       │
│  2. Make code changes                                           │
│  3. Commit changes                                              │
│                                                                 │
│  🛑 CHECKPOINT 1: "Code ready. OK to push?"                    │
│     └── You verify code diff, say "OK to push"                  │
├─────────────────────────────────────────────────────────────────┤
│                    PHASE B: Pull Request                        │
│  4. Push to GitHub                                              │
│  5. Create PR                                                   │
│  6. Wait for preview (~5 min)                                   │
│                                                                 │
│  🛑 CHECKPOINT 2: "Preview at [URL]. OK to merge?"             │
│     └── You verify preview works, say "OK to merge"             │
├─────────────────────────────────────────────────────────────────┤
│                    PHASE C: Staging                             │
│  7. Merge PR to main                                            │
│  8. Wait for staging (~5 min)                                   │
│                                                                 │
│  🛑 CHECKPOINT 3: "Staging at [URL]. OK to deploy production?" │
│     └── You verify staging works, say "OK to deploy"            │
├─────────────────────────────────────────────────────────────────┤
│                    PHASE D: Production                          │
│  9. Trigger production deployment                               │
│  10. Wait for production (~2 min)                               │
│                                                                 │
│  🛑 CHECKPOINT 4: "Production live. Confirm complete."         │
│     └── You verify production, say "Complete"                   │
└─────────────────────────────────────────────────────────────────┘

# Ensure you're on main and up to date
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/your-feature-name

# Start dev server (hot reload)
npm run dev

# Open browser
open http://localhost:3000

npm run lint        # Run linting
npm run types:check # Type checking
npm run build       # Verify build

# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add deployment workflow documentation"

# Push to remote
git push origin feature/your-feature-name

<type>: <description>

[optional body]

[optional footer]

# Method 1: Bang after type
feat!: redesign authentication API

# Method 2: Footer
feat: redesign authentication API

BREAKING CHANGE: API endpoints have changed

# Good commit messages
git commit -m "feat: add employee dashboard"
git commit -m "fix: resolve login timeout issue"
git commit -m "docs: update deployment guide"
git commit -m "refactor: simplify database queries"

# Bad commit messages (will be rejected)
git commit -m "update stuff"       # Missing type
git commit -m "Feature: add login" # Wrong case (Feature vs feat)
git commit -m "feat add login"     # Missing colon

Commits since last release:
  - feat: add employee dashboard  → minor bump
  - fix: resolve login issue      → patch bump
  - docs: update guide           → patch bump

Result: 1.2.0 → 1.3.0 (feat triggers minor)

# Create PR via CLI
gh pr create --title "feat: your feature" --body "Description"

# Or open in browser
gh pr create --web

🚀 Preview deployed!
URL: https://hrms-docs-pr-42-xxxx.run.app

gh pr merge --squash

gh workflow run deploy.yml -f deploy_production=true

curl -sI https://docs.hrms.bluewoo.com | head -5
open https://docs.hrms.bluewoo.com

# Switch back to main
git checkout main
git pull origin main

# Delete local branch
git branch -d feature/your-feature-name

1. Read PROJECT_STATE.md (current phase/step)
2. Read WHAT_EXISTS.md (built components)
3. Create branch: git checkout -b feature/phase-X-step-Y
4. State understanding: "I'm on Phase X, Step Y. I will do Z."
5. WAIT for approval

1. Make changes
2. Commit frequently with clear messages
3. Push to feature branch
4. Create PR when step is complete

1. Verify preview looks correct
2. Merge PR → Staging deploys
3. If phase complete: trigger production deploy
4. Update PROJECT_STATE.md
5. Commit state file updates

# List recent revisions
gcloud run revisions list --service=hrms-docs --region=europe-west6 --limit=5

# Rollback to previous revision
gcloud run services update-traffic hrms-docs \
  --to-revisions=hrms-docs-PREVIOUS_REVISION=100 \
  --region=europe-west6

git revert HEAD
git push origin main
# Then manually trigger production deploy

# 1. Start fresh
git checkout main && git pull

# 2. Create branch
git checkout -b docs/add-employee-guide

# 3. Develop
npm run dev
# ... make changes ...

# 4. Test
npm run lint && npm run build

# 5. Commit and push
git add .
git commit -m "docs: add employee management guide"
git push origin docs/add-employee-guide

# 6. Create PR
gh pr create --title "docs: add employee management guide"

# 7. Wait for preview, review it
# 8. Merge
gh pr merge --squash

# 9. Verify staging
open https://hrms-docs-staging-446839292792.europe-west6.run.app

# 10. Deploy to production (when ready)
gh workflow run deploy.yml -f deploy_production=true

# 11. Verify production
open https://docs.hrms.bluewoo.com

# 12. Cleanup
git checkout main && git pull
git branch -d docs/add-employee-guide