deploy

Deploy: Structured Deployment Workflow

You are running the Deploy workflow -- a structured deployment process with readiness gating, strategy selection, execution, monitoring, and rollback criteria. Target: $ARGUMENTS

When to Use

• You are ready to ship a feature and want a safe, observable deployment
• You need to choose between deployment strategies (canary, blue-green, rolling, direct)
• You want post-deployment health checks before declaring success
• You need a clear rollback plan if things go wrong

Don't Use When

• No deployment infrastructure exists — this skill detects and drives existing tooling; it cannot provision infrastructure from scratch
• Changes haven't been tested — Phase 0 will catch this, but don't invoke /deploy as a shortcut around a broken test suite
• You need a deployment strategy designed from scratch — use /spec or /consensus to design the strategy first, then come back to /deploy for execution

Overview

Deploy works in 5 phases. The readiness gate (Phase 0) must pass before any deployment begins.

Readiness gate (tests, git, open work)
  -> Strategy selection (direct / canary / blue-green / rolling)
    -> Execution (CI/CD tooling or guided manual steps)
      -> Monitoring (health checks, logs, endpoints)
        -> Rollback criteria (automated triggers + manual guide)

---

Phase 0: Readiness Gate

This phase is a hard gate. If any check fails, stop here and report what must be fixed.

0a. Detect Target

If $ARGUMENTS is empty, ask the user: "What are you deploying, and to which environment (staging, production, etc.)?"

If provided, confirm the target: service name and environment (e.g., "api-gateway to production").

0b. Git Status Check

git status --short
git log --oneline -3

• If there are uncommitted changes, stop. Report the dirty files. Ask the user to commit or stash before deploying.
• Confirm the current branch is the expected deploy branch (typically main or release/*).

0c. Test Status Check

Detect the test runner from project config:

# Check for common test configs
ls package.json Makefile pytest.ini go.mod Cargo.toml 2>/dev/null

• Node.js: npm test or npm run test
• Python: pytest or python -m pytest
• Go: go test ./...
• Rust: cargo test
• Make: make test

If a test command exists, report the last test run result from git log or CI artifacts if available. If tests cannot be verified, warn the user and ask for confirmation before proceeding.

0d. In-Progress Work Check

Check your project's task tracker for open high-priority (P0/P1) work items. If any are open and their scope overlaps with the files changed since last deploy (from git diff --name-only HEAD~1), warn the user: "Open high-priority work touches files in this deploy. Confirm you want to continue."

0e. Gate Summary

Report:

## Readiness Gate: [PASS | FAIL]

- Git: [clean on main | FAIL: dirty files listed]
- Tests: [verified passing | unverified — user confirmed | FAIL: X failures]
- Open high-priority work: [none affecting deploy | WARNING: N items]

[If FAIL]: Fix the above before deploying. Re-run /deploy when ready.
[If PASS]: Proceeding to strategy selection.

---

Phase 1: Strategy Selection

1a. Detect Deployment Tooling

Scan the project root for deployment configuration:

ls .github/workflows/ Dockerfile docker-compose.yml k8s/ helm/ fly.toml railway.json Procfile .heroku/ 2>/dev/null

Build a tooling inventory:

Signal	Tooling Detected
.github/workflows/*.yml with deploy or release	GitHub Actions
Dockerfile + docker-compose.yml	Docker Compose
k8s/ or helm/ directory	Kubernetes / Helm
fly.toml	Fly.io
railway.json	Railway
Procfile	Heroku
Makefile with deploy target	Make-based deploy

Read the detected config files to understand what the deploy pipeline does.

1b. Assess Risk Level

Rate the deployment risk based on:

• Low: Static site, CLI tool, internal service with no external users
• Medium: API with external consumers, feature flag protected, <100 active users
• High: Customer-facing service, >100 active users, data migrations, schema changes, no feature flags

Ask the user if the risk level is unclear.

1c. Recommend Strategy

Based on tooling and risk:

Risk	Recommended Strategy	Why
Low	Direct	Fast, simple. Roll forward if issues appear.
Medium	Canary	Expose a small slice of traffic first. Monitor, then promote.
High	Blue-Green	Two identical environments; instant switch back on failure.
Any with k8s	Rolling	Kubernetes handles this natively; zero-downtime by default.

Present the recommendation with rationale. Show the alternative strategies briefly.

Confirm with the user before proceeding:

"Recommended strategy: [strategy]. Reason: [1 sentence]. Proceed with this strategy, or choose a different one? (direct / canary / blue-green / rolling)"

Wait for confirmation. Proceed with the confirmed strategy.

---

Phase 2: Execution

Execute the deployment using the confirmed strategy and detected tooling. This phase is project-specific -- adapt to what you found in Phase 1.

Direct Deployment

The simplest path: deploy the current build directly to the target environment.

GitHub Actions (push-to-deploy):

git push origin main
# Then monitor the workflow run
gh run list --limit 1
gh run watch <run-id>

Docker Compose:

docker build -t <image>:<tag> .
docker push <registry>/<image>:<tag>
# On the target host:
docker compose pull && docker compose up -d

Fly.io:

fly deploy

Heroku:

git push heroku main

Make:

make deploy

Manual (no tooling detected): Guide the user through their specific deploy steps. Ask: "What command do you use to deploy?" Then execute it.

Canary Deployment

Route a small slice of traffic to the new version before full rollout.

1. Deploy new version alongside existing (e.g., tag as v2-canary)
2. Route ~5-10% of traffic to canary (load balancer, feature flag, or header-based routing)
3. Monitor for 10-30 minutes (see Phase 3 monitoring window)
4. If healthy: promote canary to 100%, retire old version
5. If unhealthy: roll back canary (traffic returns to stable) — see Phase 4

If GitHub Actions or CI handles canary, trigger the canary workflow and monitor:

gh workflow run canary-deploy.yml
gh run watch <run-id>

Blue-Green Deployment

Two identical environments: blue (current stable) and green (new release).

1. Deploy new version to the inactive environment (green)
2. Run smoke tests against green before switching
3. Switch the load balancer/DNS to point to green
4. Keep blue running for immediate rollback window (15-60 minutes)
5. If healthy after monitoring window: tear down blue

If using Kubernetes:

kubectl apply -f k8s/green/
kubectl rollout status deployment/<name>-green
# After smoke tests pass:
kubectl patch service/<name> -p '{"spec":{"selector":{"slot":"green"}}}'

Rolling Deployment

Replace instances one by one. Kubernetes handles this natively.

kubectl set image deployment/<name> <container>=<image>:<tag>
kubectl rollout status deployment/<name>

Monitor: kubectl get pods -w to watch instance replacement.

Execution Status

After executing the deploy command, confirm:

## Execution: [IN PROGRESS | COMPLETE | FAILED]

- Strategy: [direct | canary | blue-green | rolling]
- Tooling: [GitHub Actions | Docker | k8s | Make | manual]
- Deploy command run: [yes | no]
- Build/image: [tag or commit]
- [If CI]: Workflow URL or run ID for monitoring

---

Phase 3: Monitoring

Post-deployment health verification. Duration varies by strategy.

Monitoring Window

Strategy	Minimum Wait	What to Watch
Direct	5 minutes	Error rate, application logs
Canary	15-30 minutes	Canary error rate vs. baseline
Blue-Green	15 minutes after switch	Error rate on green
Rolling	Until all instances replaced	kubectl rollout status

3a. Endpoint Health Checks

If the project exposes HTTP endpoints, check them:

# Basic health endpoint
curl -sf https://<host>/health && echo "OK" || echo "FAIL"

# Or application root
curl -sf https://<host>/ -o /dev/null -w "%{http_code}"

If the URL is not known, ask the user: "What URL should I check to confirm the service is up?"

3b. Log Review

Scan recent logs for error signals:

Docker:

docker logs <container> --tail=50 --since=5m

Kubernetes:

kubectl logs deployment/<name> --tail=50 --since=5m

Fly.io:

fly logs --app <app-name>

Local/manual: Ask the user where logs live and what error patterns to look for.

Look for:

• HTTP 5xx error spikes
• Exception stack traces
• Connection refused / timeout errors
• Out-of-memory signals

3c. Health Summary

Report after the monitoring window:

## Monitoring: [HEALTHY | DEGRADED | FAILED]

Monitoring window: [N minutes]

- Endpoint check: [pass (HTTP 200) | fail (HTTP NNN) | skipped]
- Log signals: [clean | WARNING: N errors | FAIL: error pattern found]
- Error rate: [baseline | elevated — see rollback criteria]

[If HEALTHY]: Deployment successful. Proceed to close out (see Phase 4).
[If DEGRADED or FAILED]: Rollback criteria triggered — see Phase 4.

---

Phase 4: Rollback Criteria

Define what triggers rollback and how to execute it.

4a. Rollback Triggers

Automatic triggers (execute rollback immediately, do not wait for manual review):

• Health endpoint returns non-2xx for 3 consecutive checks
• Log scan finds exception rate >5x baseline in the monitoring window
• Process/pod restart loop detected (crash loop)
• kubectl rollout status reports ErrImagePull or CrashLoopBackOff

Manual triggers (report to user, ask for decision):

• Error rate elevated but below automatic threshold (1-5x baseline)
• Latency increased significantly but no errors
• User reports confirm something is wrong

4b. Rollback Execution

Execute the appropriate rollback based on strategy:

Direct / Git push:

git revert HEAD --no-edit
git push origin main
# Or: redeploy the previous tag
git checkout <previous-tag>
# Then re-run the deploy command

Kubernetes rolling:

kubectl rollout undo deployment/<name>
kubectl rollout status deployment/<name>

Blue-Green:

# Switch load balancer back to blue
kubectl patch service/<name> -p '{"spec":{"selector":{"slot":"blue"}}}'
# Confirm traffic is back on blue

Canary:

# Route 0% traffic to canary
# (tooling-specific — guide the user through their load balancer or feature flag config)

Docker Compose (redeploy previous):

docker compose pull <previous-tag> && docker compose up -d

4c. Post-Rollback

After rollback:

1. Confirm health checks pass on the stable version
2. Create a task for the root cause investigation using your preferred task tracking approach:
   • Title: "[service]: investigate deploy failure [date]"
   • Priority: P1
   • Description: "Rollback triggered during deploy. Error signals: [what you found in Phase 3]. Investigate root cause before next deploy attempt."

4d. Close Out (Successful Deploy)

If no rollback was needed:

## Deploy Complete

- Target: [service / environment]
- Strategy: [direct | canary | blue-green | rolling]
- Version: [git tag, commit hash, or image tag]
- Monitoring window: [N minutes, all checks passed]
- Rolled back: no

Next steps:
- Tag the release if not already tagged: `git tag v<version> && git push origin v<version>`
- Close any related tasks in your task tracker
- Announce to team if applicable

4e. Pipe-Format Summary

After the close-out block, emit a pipe-format summary so downstream skills (/status, /retro) can consume deployment outcomes:

## Deployment outcomes

**Source**: /deploy
**Input**: [service / environment from $ARGUMENTS]
**Pipeline**: (none — working from direct input)

### Items (5)

1. **Deployment strategy** — [direct | canary | blue-green | rolling]
   - tooling: [GitHub Actions | Docker | k8s | Make | manual]
   - target: [service / environment]

2. **Version deployed** — [git tag, commit hash, or image tag]
   - branch: [branch name]
   - commit: [short SHA]

3. **Readiness gate** — [PASS | FAIL]
   - git: [clean on main | dirty — describe]
   - tests: [verified passing | unverified | failed]
   - open high-priority work: [none | N items affecting deploy]

4. **Health check result** — [HEALTHY | DEGRADED | FAILED]
   - endpoint: [pass HTTP 200 | fail HTTP NNN | skipped]
   - logs: [clean | N errors | error pattern found]
   - monitoring window: [N minutes]

5. **Rollback status** — [not triggered | triggered — reason]
   - stable version: [tag or commit if rolled back | n/a]
   - follow-up task: [task ID or "none"]

### Summary

[One paragraph: what was deployed, which strategy was used, whether health checks passed, and whether a rollback occurred.]

---

Guidelines

1. Gate is mandatory. Never skip Phase 0. A failed readiness gate is not a blocker to skip -- it is a signal to fix before deploying.
2. Adapt to the project. This skill detects tooling and adapts. If the project uses a deploy tool not listed, ask the user what command to run and execute it.
3. Strategy selection needs user confirmation. Never proceed with a deployment strategy without explicit user confirmation. Deployment is irreversible on short timescales.
4. Monitoring window is non-negotiable. Do not declare success before the minimum monitoring window elapses. Stay in Phase 3 until the window passes or a rollback trigger fires.
5. Rollback first, investigate second. If rollback triggers fire, execute rollback immediately. Root cause investigation happens after the service is stable.
6. Be conservative with health signals. Ambiguous logs or elevated-but-not-alarming error rates should be escalated to the user, not silently accepted.
7. Compaction resilience. Per rules/memory-layout.md, checkpoint at phase boundaries to .claude/tackline/memory/scratch/deploy-checkpoint.md.
8. Secrets stay out. Never write environment variables, credentials, or API keys into commit messages, log output, or any file. Reference them by name only.

See Also

• /test-strategy — verify tests pass before starting Phase 0
• /tracer — implement the feature end-to-end before deploying
• /premortem — identify deployment failure modes before executing Phase 2
• /review — code review before shipping
• /status — check current backlog and session state before deploying