@slamb2k/mad-skills 2.0.14 → 2.0.16

package/skills/dock/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: dock
+description: >-
+  Generate container-based release pipelines that build once and promote immutable
+  artifacts through environments (dev → staging → prod). Detects your stack, interviews
+  for infrastructure choices, then outputs deterministic CI/CD files (Dockerfile,
+  workflows, deployment manifests) that run without an LLM. Use when setting up
+  deployment pipelines, containerizing an app, creating release workflows, or
+  connecting CI to container-friendly infrastructure (Azure Container Apps, AWS Fargate,
+  Google Cloud Run, Kubernetes, Dokku, Coolify, CapRover, etc.).
+argument-hint: "--registry-only, --skip-interview, --dry-run"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, Agent
+---
+
+# Dock - Container Release Pipelines
+
+When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character. The first line of the art has 4 leading spaces — you MUST preserve them.
+
+```
+{tagline}
+
+⠀   ██╗██████╗  ██████╗  ██████╗██╗  ██╗
+   ██╔╝██╔══██╗██╔═══██╗██╔════╝██║ ██╔╝
+  ██╔╝ ██║  ██║██║   ██║██║     █████╔╝
+ ██╔╝  ██║  ██║██║   ██║██║     ██╔═██╗
+██╔╝   ██████╔╝╚██████╔╝╚██████╗██║  ██╗
+╚═╝    ╚═════╝  ╚═════╝  ╚═════╝╚═╝  ╚═╝
+```
+
+Taglines:
+- 🐳 Containerize all the things!
+- 📦 Build once, deploy everywhere!
+- 🚀 From code to container in one shot!
+- ⚓ Anchoring your release pipeline!
+- 🏗️ Immutable artifacts, mutable environments!
+- 🔒 Same image, every stage, every time!
+- 🌊 Shipping containers since... just now!
+- 🎯 One build to rule them all!
+
+---
+
+Generate container-based release pipelines following the **build-once, promote-everywhere**
+philosophy. Every artifact is built exactly once, tested, tagged with git SHA + semver,
+pushed to a registry, and promoted through environments without rebuilding.
+
+All generated files are deterministic — no LLM required at runtime.
+
+## Flags
+
+Parse optional flags from the request:
+- `--registry-only`: Only generate Dockerfile, .dockerignore, and registry config (skip deployment)
+- `--skip-interview`: Use detected defaults without interactive prompts
+- `--dry-run`: Show what would be generated without writing files
+
+---
+
+## Pre-flight
+
+Before starting, check dependencies:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| docker | cli | `docker --version` | no | ask | Needed for local build verification; skip verify phase if absent |
+| git | cli | `git --version` | yes | stop | Install from https://git-scm.com |
+| sync | skill | `.claude/skills/sync/SKILL.md` | no | fallback | Repo sync; falls back to manual git pull |
+
+For each row:
+1. Run the Check command
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+4. After all checks: summarize availability
+
+---
+
+## Phase 0: Sync
+
+Invoke `/sync` to ensure the working tree is up to date with origin/main before
+scanning. If /sync is unavailable, run `git pull` manually. This prevents
+generating pipelines against stale code.
+
+---
+
+## Phase 1: Detection
+
+Launch an **Explore subagent** to scan the codebase and produce a DETECTION_REPORT.
+
+```
+Task(
+  subagent_type: "Explore",
+  description: "Detect stack and existing infrastructure",
+  prompt: <read from references/interview-guide.md#detection-prompt>
+)
+```
+
+The detection prompt scans for:
+- **Language & framework**: package.json, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml, etc.
+- **Existing Dockerfile**: Dockerfile, Dockerfile.*, docker-compose.yml
+- **Existing CI**: .github/workflows/, azure-pipelines.yml, .gitlab-ci.yml
+- **Existing deploy config**: Helm charts, Kubernetes manifests, Procfile, app.json, fly.toml, dokku config
+- **Package manager**: npm/yarn/pnpm/bun, pip/uv/poetry, go modules, cargo, bundler, maven/gradle
+- **Entry point**: main file, start scripts, Procfile commands
+- **Port**: exposed ports in existing config or framework defaults
+- **Environment files**: .env, .env.example, .env.* patterns
+
+Parse DETECTION_REPORT. This feeds into the interview phase.
+
+---
+
+## Phase 2: Interview
+
+Present the detection results to the user and fill in gaps through guided questions.
+Read the full interview flow from `references/interview-guide.md#interview-questions`.
+
+The interview covers these topics in order. Skip questions where detection already
+provided a confident answer (but confirm with the user).
+
+### 2.1 — Stack Confirmation
+
+Confirm detected language, framework, and entry point. Ask only if detection was
+ambiguous (e.g., monorepo with multiple stacks).
+
+### 2.2 — Container Registry
+
+Detect from existing CI config or ask:
+- GitHub Container Registry (ghcr.io) — default for GitHub repos
+- Azure Container Registry
+- AWS ECR
+- Google Artifact Registry
+- Docker Hub
+- Self-hosted registry
+
+### 2.3 — Environment Topology
+
+Ask how many deployment stages and the promotion model:
+- **Simple**: dev → prod (2-stage)
+- **Standard**: dev → staging → prod (3-stage, default)
+- **Custom**: user-defined stages
+
+For each environment, ask the deployment target:
+- Azure App Service for Containers
+- Azure Container Apps
+- AWS Fargate
+- Google Cloud Run
+- Kubernetes (any distribution)
+- Dokku
+- Coolify
+- CapRover
+- Other (user-specified)
+
+Different environments can use different targets (e.g., dev=Dokku, prod=Azure Container Apps).
+
+### 2.4 — Testing Gates
+
+For each environment promotion, ask what tests gate the promotion:
+- **Build gate** (before registry push): unit tests, linting, type checks
+- **Dev gate**: smoke tests, health check verification
+- **Staging gate**: integration tests, e2e tests
+- **Prod gate**: final smoke test post-deploy
+
+### 2.5 — Secrets & Configuration
+
+How environment-specific config is managed:
+- GitHub Secrets / Variables (default for GitHub Actions)
+- Azure Key Vault
+- AWS Secrets Manager
+- Environment variables in deployment platform
+- Doppler / 1Password / Vault
+
+### 2.6 — Networking & Domains
+
+Optional — ask only if deploying to platforms that need this:
+- Custom domain per environment?
+- TLS certificate management (auto via platform, Let's Encrypt, manual)
+- Load balancer or ingress configuration
+
+### 2.7 — Rollback Strategy
+
+- **Simple rollback** (default): redeploy previous image tag on failure
+- **Blue-green**: maintain two environments, swap traffic
+- **Canary**: gradual traffic shift with automatic rollback on error thresholds
+
+**If `--skip-interview` flag**: Use detected defaults + sensible defaults for
+everything else (ghcr.io, 3-stage, GitHub Secrets, simple rollback).
+
+Compile all answers into a DOCK_CONFIG object for Phase 3.
+
+---
+
+## Phase 3: Generate Artifacts
+
+Based on DETECTION_REPORT and DOCK_CONFIG, generate all pipeline files.
+Use templates from `references/` as starting points and customize for the
+detected stack and chosen platforms.
+
+### 3.1 — Dockerfile & .dockerignore
+
+Read `references/dockerfile-templates.md` for the detected stack.
+
+Generate a multi-stage Dockerfile:
+- **Stage 1 — deps**: Install dependencies only (maximizes cache hits)
+- **Stage 2 — build**: Copy source, run build step
+- **Stage 3 — test**: Run unit tests against the build
+- **Stage 4 — production**: Minimal runtime image with built artifacts only
+
+Generate `.dockerignore` excluding: `.git`, `node_modules`, `__pycache__`, `.env*`,
+test fixtures, documentation, IDE config.
+
+### 3.2 — docker-compose.yml
+
+Generate a local development compose file that mirrors the production image
+with development overrides (volume mounts, hot reload, debug ports).
+
+### 3.3 — CI/CD Workflow
+
+Detect CI system from Phase 1 (GitHub Actions / Azure Pipelines / GitLab CI).
+Read the appropriate template from `references/pipeline-templates.md`.
+
+Generate a workflow that implements:
+
+**On pull request:**
+1. Build image tagged with `pr-{number}-{sha:7}`
+2. Run test stage inside the image
+3. Push to registry (optional — configurable)
+4. Comment build status on PR
+
+**On merge to main (or default branch):**
+1. Build image tagged with `{sha:7}` and `latest`
+2. Run full test suite inside the image
+3. Push to registry
+4. Deploy to dev environment
+5. Run dev-gate tests (smoke tests)
+
+**On release tag (vX.Y.Z):**
+1. Retag the existing `{sha:7}` image as `vX.Y.Z` — **do NOT rebuild**
+2. Deploy to staging
+3. Run staging-gate tests
+4. On success: deploy to prod
+5. Run prod-gate tests (post-deploy smoke)
+
+Key principle: the release workflow **never rebuilds**. It promotes the exact
+image that was tested on main.
+
+### 3.4 — Deployment Manifests
+
+Based on the chosen platforms per environment, read the appropriate section
+from `references/platform-deploy-guides.md` and generate:
+
+- **Kubernetes**: Helm chart or kustomize overlays with per-environment values
+- **Azure Container Apps**: Bicep/ARM template or `az containerapp` commands in workflow
+- **Azure App Service**: App Service deployment slots config
+- **AWS Fargate**: ECS task definition + service config
+- **Google Cloud Run**: Cloud Run service YAML or `gcloud run deploy` commands
+- **Dokku**: Procfile + dokku git push deployment step
+- **Coolify**: API-based deployment step or docker-compose based
+- **CapRover**: captain-definition file + deploy step
+
+### 3.5 — Environment Matrix
+
+Generate an environment matrix config file (`deploy/environments.json` or
+`deploy/environments.yml`) defining per-environment settings:
+
+```yaml
+environments:
+  dev:
+    target: <platform>
+    registry_tag_pattern: "{sha:7}"
+    auto_deploy: true
+    tests: [smoke]
+  staging:
+    target: <platform>
+    registry_tag_pattern: "v{version}"
+    auto_deploy: false  # requires manual approval or tag
+    tests: [integration, e2e]
+  prod:
+    target: <platform>
+    registry_tag_pattern: "v{version}"
+    auto_deploy: false
+    tests: [smoke-post-deploy]
+```
+
+### 3.6 — Health Check Endpoint Guidance
+
+If the detected framework doesn't already have a health endpoint, add a comment
+in the generated workflow noting that a `/healthz` or `/health` endpoint is
+recommended for deployment readiness probes.
+
+---
+
+## Phase 4: Verify
+
+If Docker is available, run a verification step:
+
+```bash
+docker build --target production -t dock-verify:test .
+```
+
+If the build succeeds, report success. If it fails, diagnose and fix the
+Dockerfile. Skip this phase if Docker is not installed (noted in pre-flight).
+
+Also validate generated workflow files:
+- GitHub Actions: check YAML syntax
+- Azure Pipelines: check YAML syntax
+- GitLab CI: check YAML syntax
+
+Present the user with a summary of all generated files before writing.
+
+**If `--dry-run` flag**: Show the file list and content previews without writing.
+
+---
+
+## Final Report
+
+After all files are generated and verified, present:
+
+```
+Dock complete
+
+  Stack:     {language} / {framework}
+  Registry:  {registry}
+  Stages:    {env1} → {env2} → {env3}
+
+  Generated files:
+    {file list with brief descriptions}
+
+  Pipeline flow:
+    PR → build + test → [push to registry]
+    Merge → build + test → push → deploy dev → smoke tests
+    Tag  → retag (no rebuild) → deploy staging → e2e → deploy prod → smoke
+
+  Next steps:
+    1. Review generated files
+    2. Configure secrets: {list of required secrets}
+    3. Push to trigger first pipeline run
+```
+
+---
+
+## Idempotency
+
+If /dock detects it has been run before (existing `deploy/` directory, existing
+deployment workflow), it should:
+- **Dockerfile**: Update if stack detection shows changes; preserve custom stages
+- **Workflow**: Merge new steps; never overwrite user customizations without confirmation
+- **Manifests**: Update image references; preserve environment-specific overrides
+- **Always ask** before overwriting existing files
+
+---
+
+## Integration with /rig and /ship
+
+- **/rig integration**: When /rig runs after /dock, it should detect `deploy/`
+  artifacts and wire the CI workflow to trigger deployment on merge to main.
+- **/ship integration**: /ship's merge step naturally triggers the deployment
+  workflow created by /dock. No special coupling needed — the CI/CD workflow
+  handles the handoff via branch/tag triggers.

package/skills/dock/references/dockerfile-templates.md

@@ -0,0 +1,358 @@
+# Dockerfile Templates
+
+Multi-stage Dockerfile templates by detected stack. Each template follows the
+four-stage pattern: deps → build → test → production.
+
+Customize based on DETECTION_REPORT values. These are starting points, not
+rigid templates — adapt to the specific project.
+
+---
+
+## Node.js
+
+### With npm/yarn/pnpm
+
+```dockerfile
+# Stage 1: Dependencies
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+# Stage 2: Build
+FROM deps AS build
+COPY . .
+RUN npm run build
+
+# Stage 3: Test (used in CI, not in final image)
+FROM build AS test
+RUN npm test
+
+# Stage 4: Production
+FROM node:22-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001 -G appgroup
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/package.json ./
+USER appuser
+EXPOSE {PORT}
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:{PORT}/healthz || exit 1
+CMD ["node", "dist/index.js"]
+```
+
+### With bun
+
+```dockerfile
+FROM oven/bun:1-alpine AS deps
+WORKDIR /app
+COPY package.json bun.lockb ./
+RUN bun install --frozen-lockfile
+
+FROM deps AS build
+COPY . .
+RUN bun run build
+
+FROM build AS test
+RUN bun test
+
+FROM oven/bun:1-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001 -G appgroup
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/package.json ./
+USER appuser
+EXPOSE {PORT}
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+  CMD bun --eval "fetch('http://localhost:{PORT}/healthz').then(r => process.exit(r.ok ? 0 : 1))" || exit 1
+CMD ["bun", "run", "dist/index.js"]
+```
+
+### Next.js (standalone output)
+
+```dockerfile
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+FROM deps AS build
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+FROM build AS test
+RUN npm test
+
+FROM node:22-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001 -G appgroup
+COPY --from=build /app/.next/standalone ./
+COPY --from=build /app/.next/static ./.next/static
+COPY --from=build /app/public ./public
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=15s \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1
+CMD ["node", "server.js"]
+```
+
+Note: Requires `output: 'standalone'` in next.config.js.
+
+---
+
+## Python
+
+### With pip/uv
+
+```dockerfile
+FROM python:3.12-slim AS deps
+WORKDIR /app
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+FROM deps AS build
+COPY . .
+
+FROM build AS test
+RUN python -m pytest
+
+FROM python:3.12-slim AS production
+WORKDIR /app
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+COPY --from=deps /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=deps /usr/local/bin /usr/local/bin
+COPY --from=build /app .
+USER appuser
+EXPOSE {PORT}
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:{PORT}/healthz')" || exit 1
+CMD ["gunicorn", "--bind", "0.0.0.0:{PORT}", "--workers", "4", "app:app"]
+```
+
+### With uv (faster installs)
+
+```dockerfile
+FROM python:3.12-slim AS deps
+WORKDIR /app
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+FROM deps AS build
+COPY . .
+RUN uv sync --frozen --no-install-project
+
+FROM build AS test
+RUN uv run pytest
+
+FROM python:3.12-slim AS production
+WORKDIR /app
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+COPY --from=deps /app/.venv /app/.venv
+COPY --from=build /app .
+ENV PATH="/app/.venv/bin:$PATH"
+USER appuser
+EXPOSE {PORT}
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:{PORT}/healthz')" || exit 1
+CMD ["gunicorn", "--bind", "0.0.0.0:{PORT}", "--workers", "4", "app:app"]
+```
+
+### Django
+
+Replace CMD with:
+```dockerfile
+CMD ["gunicorn", "--bind", "0.0.0.0:{PORT}", "--workers", "4", "{PROJECT_NAME}.wsgi:application"]
+```
+
+Add collectstatic to build stage:
+```dockerfile
+RUN python manage.py collectstatic --noinput
+```
+
+### FastAPI
+
+Replace CMD with:
+```dockerfile
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "{PORT}", "--workers", "4"]
+```
+
+---
+
+## Go
+
+```dockerfile
+FROM golang:1.23-alpine AS deps
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+
+FROM deps AS build
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server ./cmd/server
+
+FROM build AS test
+RUN go test ./...
+
+FROM gcr.io/distroless/static-debian12 AS production
+COPY --from=build /app/server /server
+EXPOSE {PORT}
+USER nonroot:nonroot
+CMD ["/server"]
+```
+
+---
+
+## Rust
+
+```dockerfile
+FROM rust:1.83-slim AS deps
+WORKDIR /app
+COPY Cargo.toml Cargo.lock ./
+RUN mkdir src && echo "fn main() {}" > src/main.rs
+RUN cargo build --release && rm -rf src
+
+FROM deps AS build
+COPY . .
+RUN cargo build --release
+
+FROM build AS test
+RUN cargo test --release
+
+FROM debian:bookworm-slim AS production
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+COPY --from=build /app/target/release/{BINARY_NAME} /usr/local/bin/app
+USER appuser
+EXPOSE {PORT}
+CMD ["app"]
+```
+
+---
+
+## Ruby / Rails
+
+```dockerfile
+FROM ruby:3.3-slim AS deps
+WORKDIR /app
+RUN apt-get update && apt-get install -y build-essential libpq-dev && rm -rf /var/lib/apt/lists/*
+COPY Gemfile Gemfile.lock ./
+RUN bundle config set --local deployment true && bundle install
+
+FROM deps AS build
+COPY . .
+RUN SECRET_KEY_BASE=placeholder bundle exec rails assets:precompile
+
+FROM build AS test
+RUN bundle exec rspec
+
+FROM ruby:3.3-slim AS production
+WORKDIR /app
+RUN apt-get update && apt-get install -y libpq5 && rm -rf /var/lib/apt/lists/*
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+COPY --from=deps /app/vendor/bundle ./vendor/bundle
+COPY --from=build /app .
+ENV RAILS_ENV=production RAILS_SERVE_STATIC_FILES=true
+USER appuser
+EXPOSE {PORT}
+HEALTHCHECK --interval=30s --timeout=3s --start-period=15s \
+  CMD ruby -e "require 'net/http'; Net::HTTP.get(URI('http://localhost:{PORT}/up'))" || exit 1
+CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "{PORT}"]
+```
+
+---
+
+## .NET
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:9.0 AS deps
+WORKDIR /app
+COPY *.csproj ./
+RUN dotnet restore
+
+FROM deps AS build
+COPY . .
+RUN dotnet publish -c Release -o /app/publish --no-restore
+
+FROM build AS test
+RUN dotnet test --no-restore
+
+FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS production
+WORKDIR /app
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+COPY --from=build /app/publish .
+USER appuser
+EXPOSE {PORT}
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+  CMD curl -f http://localhost:{PORT}/healthz || exit 1
+CMD ["dotnet", "{ASSEMBLY_NAME}.dll"]
+```
+
+---
+
+## Java / Spring Boot
+
+```dockerfile
+FROM eclipse-temurin:21-jdk AS deps
+WORKDIR /app
+COPY pom.xml mvnw .mvn ./
+RUN ./mvnw dependency:resolve
+
+FROM deps AS build
+COPY . .
+RUN ./mvnw package -DskipTests
+
+FROM build AS test
+RUN ./mvnw test
+
+FROM eclipse-temurin:21-jre AS production
+WORKDIR /app
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+COPY --from=build /app/target/*.jar app.jar
+USER appuser
+EXPOSE {PORT}
+HEALTHCHECK --interval=30s --timeout=3s --start-period=30s \
+  CMD curl -f http://localhost:{PORT}/actuator/health || exit 1
+CMD ["java", "-jar", "app.jar"]
+```
+
+---
+
+## Generic .dockerignore
+
+Adapt based on detected stack. Always include:
+
+```
+.git
+.github
+.gitlab
+.env
+.env.*
+*.md
+LICENSE
+docs/
+tests/
+test/
+__tests__/
+*.test.*
+*.spec.*
+.vscode
+.idea
+.editorconfig
+.eslintrc*
+.prettierrc*
+Makefile
+docker-compose*.yml
+```
+
+Stack-specific additions:
+- Node: `node_modules/`
+- Python: `__pycache__/`, `*.pyc`, `.venv/`, `.mypy_cache/`
+- Go: no additions needed (Go copies only what's needed)
+- Rust: `target/`
+- Ruby: `.bundle/`, `tmp/`, `log/`