Kit Preamble — 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(bash scripts/kit_update_check.py ), Bash(python3 scripts/), Bash(git *), Bash(gh *), Bash(docker *), Bash(docker-compose *), Bash(act *)

Kit Preamble — devops

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

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.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors.

Checkpoint Rules — MANDATORY

Every phase in this skill that has a CHECKPOINT block must be verified. Run the verification command after completing each phase. If the exit code is not 0, STOP immediately and report the failure. Do NOT proceed to the next phase.

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:

   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 — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill devops --phase worktree --issue "$SLUG" If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

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 — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill devops --phase push --issue "$SLUG" If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

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.