claudekit/skills/condition-based-waiting/SKILL.md

name, user-invocable, description

name	user-invocable	description
condition-based-waiting	false	Use when waiting on external conditions like CI pipeline runs, deployments, long builds, database migrations, or test suites. Trigger for keywords like "wait for", "check status", "poll", "monitor", "is it done", "build running", "deploy in progress", or when a background process needs to complete before the next step. Also activate when using run_in_background or Monitor tools in Claude Code.

Condition-Based Waiting

When to Use

• CI/CD pipeline is running and you need results before proceeding
• Deployment is in progress and you need to verify it succeeded
• Long-running build (Next.js, Docker) is executing
• Database migration is applying
• Test suite takes more than 30 seconds

When NOT to Use

• Commands that complete in under 10 seconds (just run them normally)
• Checking static state that won't change (read the file instead)
• Polling for human action (ask the user instead)

---

Claude Code Patterns

Background execution for long commands

Use run_in_background when a command takes more than ~30 seconds:

# Long test suite — run in background, get notified when done
pytest -v --cov=src                    # run_in_background: true

# Docker build
docker build -t myapp .                # run_in_background: true

# Next.js production build
next build                             # run_in_background: true

# NestJS build + test
npm run build && npm test              # run_in_background: true

You'll be notified automatically when the command completes — do not poll or sleep.

Monitor tool for streaming output

Use Monitor when you need to watch for specific output patterns:

# Watch for build completion
until curl -sf http://localhost:3000/health; do sleep 2; done

# Watch for migration completion
until alembic check 2>&1 | grep -q "No new upgrade"; do sleep 5; done

---

Checking CI/CD Status

GitHub Actions

# Watch a running workflow (blocks until complete)
gh run watch

# Check status of the latest run
gh run view --json status,conclusion

# Check specific workflow
gh run list --workflow=ci.yml --limit=1 --json status,conclusion

# Wait for all checks on a PR
gh pr checks --watch

After CI completes

# Get detailed results
gh run view <run-id> --log-failed

# Re-run failed jobs only
gh run rerun <run-id> --failed

---

Checking Deployments

Health check polling

# Wait for deployment to be healthy
until curl -sf https://staging.example.com/health | grep -q '"status":"ok"'; do
  sleep 5
done
echo "Deployment is healthy"

Vercel / Cloudflare

# Vercel — check latest deployment status
npx vercel ls --limit=1

# Cloudflare Pages — check deployment
npx wrangler pages deployment list --project-name=myapp

---

Checking Build Output

Framework-specific patterns

# Next.js — watch for "Compiled successfully"
# (use run_in_background for `next build`, read output when notified)

# Python — watch for test results
pytest -v --tb=short    # run_in_background: true

# Docker — watch for "Successfully built"
docker build -t myapp . # run_in_background: true

Database migrations

# Alembic (Python)
alembic upgrade head    # run_in_background: true for large migrations

# Prisma (TypeScript)
npx prisma migrate deploy  # run_in_background: true

# Verify migration status
alembic check              # Python
npx prisma migrate status  # TypeScript

---

Anti-Patterns

Don't: Sleep loops

# BAD — burns cache, wastes tokens
sleep 60 && check_status
sleep 60 && check_status
sleep 60 && check_status

# GOOD — use run_in_background or until-loop with Monitor

Don't: Poll too frequently

# BAD — checking every second
while true; do curl localhost:3000/health; sleep 1; done

# GOOD — reasonable interval based on expected duration
until curl -sf localhost:3000/health; do sleep 5; done

Don't: Wait without timeouts

# BAD — waits forever
until curl -sf localhost:3000/health; do sleep 5; done

# GOOD — timeout after 5 minutes
timeout 300 bash -c 'until curl -sf localhost:3000/health; do sleep 5; done'

Don't: Guess completion

BAD: "The build probably finished by now, let's proceed"
GOOD: "Let me check the build status before proceeding"

---

Timing Guide

Operation	Expected Duration	Check Interval	Approach
Unit tests (small)	5-30s	N/A	Run inline
Unit tests (large)	30s-5m	N/A	run_in_background
next build	30s-3m	N/A	run_in_background
Docker build	1-10m	N/A	run_in_background
CI pipeline	2-15m	30s	gh run watch
Deployment	1-10m	5s	Health check poll
DB migration (small)	5-30s	N/A	Run inline
DB migration (large)	1-30m	N/A	run_in_background

---

Related Skills

• verification-before-completion — After waiting, verify the result before claiming success
• github-actions — CI/CD workflow patterns
• docker — Container build patterns
• systematic-debugging — When the thing you're waiting for fails