Build Deploy Workflow Skill

Build-Deploy-Workflow Skill

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your implementation
Follow the best practices outlined in this skill

Automated end-to-end workflow: Local build → Cloud Build → GKE deployment → Documentation update.

When to Use

✅ Use this skill when:

Starting a new build (Build #20, #21, #22...) - Full deployment pipeline
Deploying code changes to production GKE (backend or frontend+Theia)
Need consistent documentation of deployments (auto-updates checklist)
Want to reduce manual errors in deploy process (20+ commands → 1 command)
Proven pattern: Used 5+ times (Build #15-19, 100% success rate)
Need time savings: 40 min per build (45 min → 5 min active, 15 min build time)

❌ Don't use this skill when:

Quick local testing (use npm run dev instead)
Hotfix that doesn't require full rebuild (use kubectl set image directly)
Rollback needed (use kubectl rollout undo)
Cloud Build quota exceeded (manual deployment required)

What It Automates

Before: (45+ minutes, 20+ commands)

# Local verification
cd backend && cargo build --release
cd .. && npm run build

# Cloud builds
gcloud builds submit --config backend/cloudbuild-gke.yaml backend/
# Wait 5 min...
gcloud builds submit --config cloudbuild-combined.yaml .
# Wait 10 min...

# Extract build IDs from output
BACKEND_ID="..."
COMBINED_ID="..."

# Deploy to GKE
kubectl set image deployment/coditect-api-v5 api=us-central1-docker.pkg.dev/.../coditect-v5-api:$BACKEND_ID -n coditect-app
kubectl set image deployment/coditect-combined combined=us-central1-docker.pkg.dev/.../coditect-combined:$COMBINED_ID -n coditect-app

# Verify
kubectl rollout status deployment/coditect-api-v5 -n coditect-app
kubectl rollout status deployment/coditect-combined -n coditect-app
kubectl get pods -n coditect-app | grep coditect

# Documentation
# Edit PHASED-DEPLOYMENT-CHECKLIST.md manually
# Add build entries with details
git add docs/10-execution-plans/PHASED-DEPLOYMENT-CHECKLIST.md
git commit -m "..."
git push

After: (5 minutes active, 15 min build time, 1-2 commands)

cd .claude/skills/build-deploy-workflow
./core/deploy.sh --build-num=20 --changes="Feature X implementation" --update-checklist

Usage

Full Build and Deploy

./core/deploy.sh --build-num=20 --changes="Multi-LLM integration" --update-checklist

Backend Only

./core/deploy.sh --build-num=20 --target=backend --changes="API improvements"

Combined Only (requires pre-built dist/)

npm run build
./core/deploy.sh --build-num=20 --target=combined --changes="Frontend fixes"

Skip Local Build (faster, but risky)

./core/deploy.sh --build-num=20 --skip-local-build --changes="Hotfix"

Dry Run (preview only)

./core/deploy.sh --build-num=20 --changes="Test run" --dry-run

Workflow Steps

Phase 1: Local Verification (2 minutes)

✅ Backend: cargo build --release
✅ Frontend: npm run build (creates dist/)
✅ Type check: npm run type-check

Phase 2: Cloud Builds (15 minutes)

☁️ Backend build (5-7 minutes)
☁️ Combined build (10-12 minutes)
📋 Capture build IDs from output

Phase 3: GKE Deployment (2 minutes)

🚀 Update backend deployment image
🚀 Update combined deployment image
⏳ Wait for rollout completion
✅ Verify 3/3 pods running for each

Phase 4: Documentation (1 minute)

📝 Append to PHASED-DEPLOYMENT-CHECKLIST.md
💾 Git commit with standardized message
📤 Git push

Safety Features

Automatic validations:

✅ Local builds pass before triggering Cloud Build
✅ Build IDs captured correctly (regex validation)
✅ Rollout status checked (fails if pods crash)
✅ Pod count verified (must be 3/3 for each service)
✅ Git push only if all steps succeed

Rollback capability:

# If deployment fails, rollback to previous image
kubectl rollout undo deployment/coditect-api-v5 -n coditect-app
kubectl rollout undo deployment/coditect-combined -n coditect-app

Build ID Extraction

Parsing Cloud Build output:

# Example output:
# Created [https://cloudbuild.googleapis.com/v1/.../builds/abc123-def456-...].

BUILD_ID=$(echo "$OUTPUT" | grep -oP 'builds/\K[a-f0-9-]+' | tail -1)

Checklist Entry Template

Generated automatically:

- [x] **Build and deploy Backend Build #${BUILD_NUM}** ✅ COMPLETE (2025-10-19)
  - Build ID: `${BACKEND_BUILD_ID}`
  - Build time: ${BACKEND_DURATION}
  - Image: `us-central1-docker.pkg.dev/.../coditect-v5-api:${BACKEND_BUILD_ID}`
  - Pods: 3/3 running ✅
  - Changes: ${CHANGES}
  - Deployment: Rolled out successfully ✅

- [x] **Build and deploy Combined Build #${BUILD_NUM}** ✅ COMPLETE (2025-10-19)
  - Build ID: `${COMBINED_BUILD_ID}`
  - Build time: ${COMBINED_DURATION}
  - Image: `us-central1-docker.pkg.dev/.../coditect-combined:${COMBINED_BUILD_ID}`
  - Pods: 3/3 running ✅
  - Changes: ${CHANGES}
  - Deployment: Rolled out successfully ✅

Implementation

See: core/deploy.sh for complete implementation

Key functions:

verify_local_builds() - Run cargo/npm builds
trigger_cloud_builds() - Submit to Cloud Build, capture IDs
wait_for_builds() - Poll build status until complete
deploy_to_gke() - kubectl set image + rollout status
verify_deployment() - Check pod counts
update_checklist() - Append to PHASED-DEPLOYMENT-CHECKLIST.md
git_commit_and_push() - Standardized commit message

Validation Checklist

Test 1: Local builds pass before Cloud Build
Test 2: Build IDs extracted correctly
Test 3: Deployment waits for rollout completion
Test 4: Pod counts verified (3/3)
Test 5: Checklist updated with correct details
Test 6: Git commit and push succeed

Metrics

Usage Statistics:

Times used: 5 (Builds #15, #16, #17, #18, #19)
Time saved per build: 40 minutes (45 min → 5 min active)
Total time saved: 200 minutes (3.3 hours)
Errors prevented: 3 (wrong build IDs, missed checklist updates)

Success criteria:

✅ Zero failed deployments due to script errors
✅ 100% documentation coverage (checklist always updated)
✅ 90%+ time savings vs manual workflow

Real-World Example (Build #19, Oct 19, 2025)

Command:

./core/deploy.sh --build-num=19 --changes="Billing fields + skills cleanup" --update-checklist

Execution:

🏗️ Local Verification (2 min)
  ✅ Backend build passed (4.7s, 46 warnings)
  ✅ Frontend build passed (67s)

☁️ Cloud Builds (16 min)
  ✅ Backend: 3489e960-172c-4791-b228-e6dbf9cdab14 (5m7s)
  ✅ Combined: 8860dda8-5443-469f-b690-36d904711d1c (10m47s)

🚀 GKE Deployment (2 min)
  ✅ Backend: Rolled out successfully
  ✅ Combined: Rolled out successfully
  ✅ Pods: 6/6 running

📝 Documentation (1 min)
  ✅ Checklist updated
  ✅ Git commit: f4579db
  ✅ Git push: Success

🎉 Build #19 deployment complete!
Total time: 5 min active, 16 min build time

Troubleshooting

Error: "Local build failed"

Check: cargo build --release output for compilation errors
Fix: Resolve Rust errors before retrying
Skip: Use --skip-local-build (not recommended)

Error: "Could not extract build ID"

Check: Cloud Build output format changed?
Fix: Update regex in extract_build_id() function
Workaround: Manually specify build ID with --backend-id and --combined-id

Error: "Rollout failed"

Check: kubectl get pods -n coditect-app - Are pods crashing?
Check: kubectl logs <POD_NAME> -n coditect-app - What's the error?
Rollback: kubectl rollout undo deployment/<NAME> -n coditect-app

Error: "Pod count mismatch"

Expected: 3/3 running
Actual: 2/3 or 1/3 or CrashLoopBackOff
Action: Script will fail and prevent checklist update
Fix: Debug pod issues, then retry

Multi-Context Window Support

This skill supports long-running deployment workflows across multiple context windows using Claude 4.5's enhanced state management capabilities.

State Tracking

Checkpoint State (JSON):

{
  "deployment_id": "deploy_20251129_build20",
  "build_number": 20,
  "phase": "cloud_builds_complete",
  "local_builds": {
    "backend": {"status": "passed", "duration": "4.7s"},
    "frontend": {"status": "passed", "duration": "67s"}
  },
  "cloud_builds": {
    "backend": {"build_id": "abc123-def456", "duration": "5m7s", "status": "success"},
    "combined": {"build_id": "xyz789-uvw012", "duration": "10m47s", "status": "success"}
  },
  "gke_deployment": {"status": "pending"},
  "checklist_updated": false,
  "token_usage": 6500,
  "created_at": "2025-11-29T15:00:00Z"
}

Progress Notes (Markdown):

# Build & Deploy Progress - Build #20 - 2025-11-29

## Completed
- ✅ Local backend build (4.7s, 46 warnings)
- ✅ Local frontend build (67s)
- ✅ Backend Cloud Build (5m7s, ID: abc123-def456)
- ✅ Combined Cloud Build (10m47s, ID: xyz789-uvw012)

## In Progress
- GKE deployment pending

## Next Actions
- Deploy backend to GKE (kubectl set image)
- Deploy combined to GKE (kubectl set image)
- Verify rollout status (3/3 pods running)
- Update PHASED-DEPLOYMENT-CHECKLIST.md
- Git commit and push

Session Recovery

When starting a fresh context window after deployment work:

Load Checkpoint State: Read .coditect/checkpoints/deployment-build20-latest.json
Review Progress Notes: Check deployment-progress.md for build status
Verify Cloud Builds: Check build IDs are captured correctly
Resume Deployment: Continue from last completed phase (builds → deploy → docs)
Validate Status: Check GKE pod status before marking complete

Recovery Commands:

# 1. Check latest checkpoint
cat .coditect/checkpoints/deployment-build20-latest.json | jq '.cloud_builds'

# 2. Review progress
tail -30 deployment-progress.md

# 3. Verify cloud builds complete
gcloud builds describe abc123-def456 | grep status
gcloud builds describe xyz789-uvw012 | grep status

# 4. Check GKE deployment status
kubectl get deployments -n coditect-app
kubectl get pods -n coditect-app | grep coditect

# 5. Check if checklist updated
git diff docs/10-execution-plans/PHASED-DEPLOYMENT-CHECKLIST.md

State Management Best Practices

Checkpoint Files (JSON Schema):

Store in .coditect/checkpoints/deployment-build{num}.json
Track build phases (local → cloud → gke → docs)
Record build IDs for traceability
Include timing data for metrics

Progress Tracking (Markdown Narrative):

Maintain deployment-progress.md with build results
Document build durations and success/failure
Note any warnings or issues encountered
List next deployment steps with commands

Git Integration:

Commit checklist updates after successful deployment
Tag deployments: git tag build-{num}-deployed
Include build IDs in commit messages

Progress Checkpoints

Natural Breaking Points:

After local builds complete
After each cloud build complete
After GKE deployments complete
After pod verification
After checklist updated and committed

Checkpoint Creation Pattern:

# Automatic checkpoint creation after each phase
if phase in ["local_builds_complete", "cloud_builds_complete", "gke_deployed"]:
    create_checkpoint({
        "build_number": build_num,
        "phase": phase,
        "cloud_builds": build_ids,
        "gke_deployment": deployment_status,
        "tokens": current_token_usage
    })

Example: Multi-Context Deployment

Context Window 1: Builds Complete, Deployment Pending

{
  "checkpoint_id": "ckpt_build20_part1",
  "phase": "cloud_builds_complete",
  "local_builds_passed": true,
  "backend_build_id": "abc123-def456",
  "combined_build_id": "xyz789-uvw012",
  "next_action": "Deploy to GKE",
  "token_usage": 6500
}

Context Window 2: Complete Deployment + Documentation

# Resume from checkpoint
cat .coditect/checkpoints/ckpt_build20_part1.json

# Continue with GKE deployment
# (Context restored in 2 minutes vs 15 minutes from scratch)

{
  "checkpoint_id": "ckpt_build20_complete",
  "phase": "deployment_complete",
  "pods_running": "6/6",
  "checklist_updated": true,
  "git_committed": true,
  "token_usage": 4200
}

Token Savings: 6500 (first context) + 4200 (second context) = 10700 total vs. 18000 without checkpoint = 41% reduction

Reference: See docs/CLAUDE-4.5-BEST-PRACTICES.md for complete multi-context window workflow guidance.

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: build-deploy-workflow

Completed:
- [x] Local builds verified (backend + frontend)
- [x] Cloud Build triggered and completed
- [x] Build IDs extracted successfully
- [x] GKE deployments rolled out
- [x] Pod verification passed (6/6 running)
- [x] Checklist updated with build details
- [x] Git commit and push completed

Build IDs:
- Backend: {BACKEND_BUILD_ID}
- Combined: {COMBINED_BUILD_ID}

Outputs:
- Cloud Build URLs logged
- PHASED-DEPLOYMENT-CHECKLIST.md updated
- Git commit: {COMMIT_HASH}

Total time: {ACTIVE_TIME} active, {BUILD_TIME} build time

Completion Checklist

Before marking this skill as complete, verify:

Failure Indicators

This skill has FAILED if:

❌ Local cargo build fails with compilation errors
❌ Local npm build fails or produces empty dist/
❌ Cloud Build submission returns error
❌ Build ID extraction regex finds no matches
❌ kubectl rollout status returns non-zero exit code
❌ Pod count is less than 3/3 for any deployment
❌ Pods stuck in CrashLoopBackOff or ImagePullBackOff
❌ Checklist update fails due to file not found
❌ Git push fails due to merge conflicts or remote rejection

When NOT to Use

Do NOT use this skill when:

Quick local testing - Use npm run dev and cargo run instead
Single service deployment - Use kubectl set image directly for one service
Rollback needed - Use kubectl rollout undo to revert to previous version
Cloud Build quota exceeded - Wait for quota reset or contact GCP support
Emergency hotfix - Use manual deployment with --skip-local-build flag
No code changes - Don't trigger rebuild if only documentation changed
CI/CD testing - Use dry-run mode or separate test environment

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Running without local verification	Cloud Build fails late, wasting 15 minutes	Always verify local builds first
Skipping pod verification	Deployment succeeds but pods crash silently	Always check `kubectl get pods` after rollout
Manual build ID copy-paste	Typos cause wrong image deployment	Use automated extraction with regex
Deploying without checklist update	Lost deployment history and audit trail	Always use `--update-checklist` flag
Using on wrong branch	Deploys non-production code to prod GKE	Verify git branch before triggering
Ignoring build warnings	Technical debt accumulates, future breaks	Address cargo warnings before deploying
No dry-run validation	Unexpected behavior in production	Use `--dry-run` flag first for risky changes

Principles

This skill embodies:

#1 Recycle → Extend → Re-Use → Create - Reuses proven deployment patterns (5+ successful builds)
#3 Keep It Simple - One command replaces 20+ manual commands
#4 Separation of Concerns - Local verification → Cloud builds → Deployment → Documentation
#5 Eliminate Ambiguity - Explicit build IDs, pod counts, rollout status verification
#6 Clear, Understandable, Explainable - Progress indicators show exactly what's happening
#8 No Assumptions - Validates every step (builds, IDs, rollouts, pods) before proceeding

Full Standard: CODITECT-STANDARD-AUTOMATION.md

How to Use This Skill​

When to Use​

What It Automates​

Usage​

Full Build and Deploy​

Backend Only​

Combined Only (requires pre-built dist/)​

Skip Local Build (faster, but risky)​

Dry Run (preview only)​

Workflow Steps​

Safety Features​

Build ID Extraction​

Checklist Entry Template​

Implementation​

Validation Checklist​

Metrics​

Real-World Example (Build #19, Oct 19, 2025)​

Troubleshooting​

See Also​

Multi-Context Window Support​

State Tracking​

Session Recovery​

State Management Best Practices​

Progress Checkpoints​

Example: Multi-Context Deployment​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​