Devops

---
name: devops
description: Set up or update CI/CD pipelines, Dockerfiles, and deployment configs, then create a GH Issue + PR.
argument-hint: '[target, e.g. "github-actions", "docker", "compose"]'
disable-model-invocation: false
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash scripts/checkpoint.sh *), Bash(bash scripts/wt_setup.sh *), Bash(bash scripts/wt_cleanup.sh *), Bash(bash scripts/registry_edit.sh *), Bash(bash scripts/flock_edit.sh *), Bash(bash scripts/worktree.sh *), Bash(python3 scripts/*), Bash(git *), Bash(gh *), Bash(docker *), Bash(docker-compose *), Bash(act *), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*), Bash(python3 ${CLAUDE_PLUGIN_ROOT}/scripts/*)
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — devops

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.
## Checkpoint Rules — MANDATORY
Every phase in this skill that has a CHECKPOINT block must be verified. Run the verification command after completing each phase. Blocking gates exit non-zero on failure: STOP immediately, report, do NOT proceed. Advisory gates always exit 0 and print an `ADVISORY:` line on failure: report the gap, self-correct, then continue (ISSUE-031). Never skip running either tier.

**Slug convention**: After creating the worktree, store the branch slug (e.g., `devops/github-actions-ci`) for use in checkpoint commands.

Steps:
1) Ensure `gh` authenticated (`gh auth status`).
2) Identify the target from $ARGUMENTS (github-actions, docker, compose, or general).
3) Read the current project structure, tech stack, and existing infra configs.
4) Propose a CI/CD or infrastructure setup appropriate for the project.
5) After user approval, create worktree + auto-freeze in one step:
   ```bash
   WT="$(bash scripts/wt_setup.sh devops/<slug>)"
   ```
   `wt_setup.sh` creates the worktree and writes the freeze marker inside
   `.claude-kit/freeze-dir.txt` atomically. All subsequent file operations
   happen inside `$WT/`.

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill devops --phase worktree --issue "$SLUG"`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

6) Create or update the relevant files inside `$WT/`:
   - Dockerfile / docker-compose.yml
   - .github/workflows/*.yml
   - Scripts (build, deploy, seed, etc.)
7) Validate locally where possible (e.g., docker build, syntax checks).
8) Update README or deployment docs with setup and usage instructions inside `$WT/`.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill devops --phase validate --issue "$SLUG"`
> If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

9) Create GH Issue:
    - `gh issue create --title "devops: <concise infrastructure description>" --body "<body>"`
    - Body must include: what was set up/changed, configuration details, validation results, and usage instructions.
10) Commit + push (from `$WT/`).

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill devops --phase push --issue "$SLUG"`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

11) Create PR:
    - `gh pr create --title "devops: <concise description>" --body "Closes #<issue_number>\n\n<details>"`
12) Report the PR URL to the user — continue with `/review` and `/ship`.

## Error Handling
- If `gh auth status` fails: stop and instruct the user to run `gh auth login`.
- If the target is ambiguous: ask the user to clarify what they need (CI, containerization, deployment, etc.).
- If a build or validation fails: report the error and suggest a fix. Do NOT push broken configs.

## Rollback
- Use `bash scripts/wt_cleanup.sh <branch>` for safe worktree removal —
  the wrapper cd's to main root and removes the worktree in a single subshell.
- If failure occurs after worktree creation but before PR:
  1. `bash scripts/wt_cleanup.sh <branch>`
  2. `git push origin --delete <branch>` (remote cleanup, if pushed)
- If failure occurs after PR creation: `gh pr close <pr_number>` then clean up worktree and branch as above.

## Shared Registry Files
**IMPORTANT**: Never commit `issues.md`, `STATUS.md`, or `CHANGELOG.md` to the feature branch.
These are registry files managed only on main. Always use `bash scripts/registry_edit.sh <file> -- bash -c '<update command>'` — the wrapper resolves the main repo root internally.

## Guidelines
- Follow least-privilege for secrets and permissions — minimum scope needed.
- Use multi-stage Docker builds: build stage with dev deps → runtime stage with production deps only.
- Cache aggressively: dependency layers in Docker, pip/uv cache in CI, action caches.
- Pin every version: base images (`python:3.11.9-slim`), actions (`actions/checkout@v4`), dependencies.
- Never hardcode secrets — always use environment variables or secret stores.
- Add health checks to every service: HTTP endpoint, TCP check, or command-based.
- Test infrastructure changes locally before pushing: `docker build`, `docker compose up`, `act` for GitHub Actions.