start-vibing-stacks 2.15.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/skills/docker-patterns/SKILL.md

@@ -1,52 +1,205 @@
 ---
 name: docker-patterns
-version: 1.0.0
+version: 2.0.0
+description: "Docker patterns for 2026: BuildKit + Buildx Bake (default builder for Docker Compose since June 2025), multi-stage builds, distroless / chiseled bases (90% size reduction, no shell), non-root users, .dockerignore, healthchecks, additional_contexts for service deps, secrets via build mounts (not COPY), reproducible builds. Stack examples: Node 22, Python 3.13 (uv), PHP 8.4 (FPM + Nginx)."
 ---
 
-# Docker Patterns
+# Docker Patterns (2026)
 
-## PHP (PHP-FPM + Nginx)
+**Invoke when writing or modifying any `Dockerfile`, `docker-compose.yml`, `docker-bake.hcl`, or container build config.**
 
-```dockerfile
-FROM php:8.3-fpm-alpine
+> 2026 reality: BuildKit is the only builder; Bake is the default for Compose multi-image projects (since June 2025); distroless / chiseled bases are the default for production runtime; non-root + readonly rootfs is the default. **Anything else needs justification.**
 
-RUN apk add --no-cache \
-    libzip-dev \
-    && docker-php-ext-install pdo_mysql zip opcache
+## 1. The four non-negotiables
 
-COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
-COPY . /var/www/html
-WORKDIR /var/www/html
+1. **Multi-stage build** — separate build deps from runtime deps. No exceptions.
+2. **Distroless or chiseled runtime** — no shell, no package manager, no curl. ~2 MB instead of ~120 MB.
+3. **Non-root user** — `USER 10001:10001` in the runtime stage. Never `root`.
+4. **`.dockerignore`** — at minimum: `node_modules`, `vendor`, `.git`, `.env*`, `*.log`, `dist`, `build`, `coverage`, `__pycache__`, `.venv`.
 
-RUN composer install --no-dev --optimize-autoloader
-RUN chown -R www-data:www-data /var/www/html
+## 2. Node.js 22 — production-grade Dockerfile
 
-EXPOSE 9000
-CMD ["php-fpm"]
+```dockerfile
+# syntax=docker/dockerfile:1.7
+ARG NODE_VERSION=22.11.0
+
+# ---------- builder ----------
+FROM node:${NODE_VERSION}-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci --ignore-scripts
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+# ---------- runtime: distroless, no shell ----------
+FROM gcr.io/distroless/nodejs22-debian12:nonroot AS runtime
+WORKDIR /app
+COPY --from=builder --chown=nonroot:nonroot /app/node_modules ./node_modules
+COPY --from=builder --chown=nonroot:nonroot /app/dist         ./dist
+COPY --from=builder --chown=nonroot:nonroot /app/package.json ./
+USER nonroot
+EXPOSE 3000
+ENV NODE_ENV=production
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD ["/nodejs/bin/node", "-e", "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+CMD ["dist/server.js"]
 ```
 
-## Node.js (Multi-stage)
+Key 2026 patterns: `--mount=type=cache` for npm, `--ignore-scripts` (supply-chain hardening — see `secrets-management` §2025-A03), distroless `nonroot` tag, `--chown` on COPY, healthcheck against `/healthz`.
+
+## 3. Python 3.13 + `uv` — production-grade Dockerfile
 
 ```dockerfile
-FROM node:20-alpine AS builder
+# syntax=docker/dockerfile:1.7
+FROM python:3.13-slim-bookworm AS builder
+COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv
 WORKDIR /app
-COPY package*.json ./
-RUN npm ci
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-install-project
 COPY . .
-RUN npm run build
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
 
-FROM node:20-alpine
+FROM gcr.io/distroless/python3-debian12:nonroot AS runtime
 WORKDIR /app
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-EXPOSE 3000
-CMD ["node", "dist/index.js"]
+COPY --from=builder --chown=nonroot:nonroot /app /app
+USER nonroot
+EXPOSE 8000
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+CMD ["/app/.venv/bin/uvicorn", "myapp.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## 4. PHP 8.4 (FPM + Nginx) with Composer install in builder
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+FROM composer:2 AS vendor
+WORKDIR /app
+COPY composer.json composer.lock ./
+RUN composer install --no-dev --no-interaction --no-scripts --prefer-dist --optimize-autoloader
+
+FROM php:8.4-fpm-alpine AS runtime
+RUN apk add --no-cache libzip-dev oniguruma-dev icu-dev \
+ && docker-php-ext-install pdo_mysql zip opcache intl bcmath \
+ && rm -rf /var/cache/apk/*
+WORKDIR /var/www/html
+COPY --from=vendor /app/vendor ./vendor
+COPY --chown=www-data:www-data . .
+USER www-data
+EXPOSE 9000
+HEALTHCHECK --interval=30s --timeout=3s CMD php-fpm-healthcheck || exit 1
+CMD ["php-fpm"]
+```
+
+## 5. Compose with `additional_contexts` — service deps without sequential builds
+
+For a project where service B depends on service A's image, **don't** rely on `depends_on` for build order — declare a build-time dependency:
+
+```yaml
+# docker-compose.yml
+services:
+  api:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+
+  worker:
+    build:
+      context: ./worker
+      dockerfile: Dockerfile
+      additional_contexts:
+        api: "service:api"          # build worker AFTER api, with api's image as a context
+```
+
+## 6. Bake — the default Compose builder (since Jun 2025)
+
+Compose v2 now invokes Buildx Bake by default for multi-service projects. Opt out with `COMPOSE_BAKE=false` only if you need a feature Bake doesn't support (rare).
+
+```hcl
+# docker-bake.hcl — explicit form for CI / multi-arch
+variable "TAG" { default = "latest" }
+
+group "default" {
+  targets = ["api", "worker"]
+}
+
+target "api" {
+  context    = "./api"
+  dockerfile = "Dockerfile"
+  platforms  = ["linux/amd64", "linux/arm64"]
+  tags       = ["myorg/api:${TAG}"]
+  cache-from = ["type=gha"]
+  cache-to   = ["type=gha,mode=max"]
+}
+
+target "worker" {
+  inherits  = ["api"]
+  context   = "./worker"
+  tags      = ["myorg/worker:${TAG}"]
+}
+```
+
+```bash
+# Build everything in parallel, push to registry, with cache shared via GitHub Actions
+TAG=v1.2.3 docker buildx bake --push
 ```
 
-## Rules
+## 7. Build-time secrets — `--mount=type=secret`, never `COPY .env`
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
+    npm ci
+```
+
+```bash
+docker buildx build --secret id=npmrc,src=$HOME/.npmrc .
+```
+
+The secret never lands in any image layer. **Never** `COPY .env` or `ENV API_KEY=...`. See `secrets-management`.
+
+## 8. Healthchecks — match the orchestrator's expectation
+
+```dockerfile
+# Application-level check; fast; idempotent.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD wget -qO- http://127.0.0.1:3000/healthz || exit 1
+```
+
+For Kubernetes the Dockerfile HEALTHCHECK is informational only — the cluster uses `livenessProbe` / `readinessProbe`. See `observability` §7.
+
+## 9. Image hardening checklist
+
+- [ ] Multi-stage build present
+- [ ] Runtime stage is distroless / chiseled / scratch (no shell, no package manager)
+- [ ] `USER` directive set to non-root before `CMD`
+- [ ] `.dockerignore` excludes `.env*`, `node_modules`, `.git`, build outputs
+- [ ] No secrets baked into layers (`docker history --no-trunc IMAGE` clean)
+- [ ] `HEALTHCHECK` directive present
+- [ ] Image pinned by digest in production manifests (`image@sha256:...`)
+- [ ] `docker scout cves IMAGE` (or `trivy image IMAGE`) clean of HIGH/CRITICAL
+- [ ] Build is reproducible — same input → same digest
+
+## FORBIDDEN
+
+| Pattern | Why |
+|---|---|
+| `FROM ubuntu:latest` (or any `latest`) | Unpinned, unreproducible |
+| `RUN apt-get install ...` without `--no-install-recommends` and `rm -rf /var/lib/apt/lists/*` | Bloated layers, stale package cache |
+| `COPY .env .` | Secrets in image layer forever |
+| `ENV API_KEY=...` in Dockerfile | Same |
+| `USER root` in runtime stage | Container escape blast radius |
+| `chmod 777` on app dirs | Privilege escalation in shared envs |
+| `--privileged` containers without explicit security review | Almost always wrong |
+| `curl ... | sh` in RUN | Unverifiable supply chain |
+| Single-stage build with dev deps in final image | Bloated, exposes build tools |
+| `HEALTHCHECK NONE` | Orchestrator can't tell if app is wedged |
+
+## See Also
 
-1. **Multi-stage builds** — smaller images
-2. **Alpine base** — minimal attack surface
-3. **.dockerignore** — exclude node_modules, .git
-4. **Non-root user** — security
-5. **Health checks** — always include
+- `secrets-management` — build-time secret mounts, OIDC for registry push
+- `security-baseline` (2025-A03) — supply chain: pin actions by SHA, sign images (Sigstore/cosign)
+- `observability` — `/healthz` + `/readyz` semantics
+- `ci-pipelines` — building & pushing in CI

package/stacks/_shared/skills/git-workflow/SKILL.md

@@ -1,40 +1,163 @@
 ---
 name: git-workflow
-version: 1.0.0
+version: 2.0.0
+description: "Git workflow conventions used by commit-manager v2.0.0+: Conventional Commits (no AI-attribution footers), branch naming, direct-to-main vs feature-branch flow, end-on-main rule, push policy, never force-push main, signed commits encouraged. Invoke when starting a feature, creating commits, pushing, or wiring git-related hooks."
 ---
 
 # Git Workflow
 
-## Branch Naming
+**ALWAYS invoke when starting work, creating commits, pushing, or wiring `pre-commit` / `Stop` hooks that touch git.**
+
+> The git history is documentation. A reader six months from now should understand *why*, not just *what*. The commit-manager agent enforces the message format below; this skill defines what counts as compliant.
+
+## 1. Branch naming
 
 ```
-feature/short-description
-fix/bug-description
-refactor/what-changed
-chore/maintenance-task
+feature/<short-kebab-description>
+fix/<bug-id-or-description>
+refactor/<area-changed>
+chore/<maintenance-task>
+docs/<scope>
+ci/<workflow-area>
 ```
 
-## Commit Format (Conventional)
+Rules:
+- Always kebab-case, never spaces or underscores.
+- ≤ 50 chars; longer goes in the PR description.
+- One feature per branch.
+
+## 2. Conventional Commits — required format
+
+```
+<type>(<scope>): <subject>
+
+<body — wrapped at ~72 cols; bullets when ≥ 3 files affected>
+```
+
+| Type | When |
+|---|---|
+| `feat` | New user-visible capability |
+| `fix` | Bug fix |
+| `refactor` | Internal change, no behavior change |
+| `perf` | Performance improvement |
+| `test` | Tests added/changed only |
+| `docs` | Documentation only |
+| `chore` | Build, deps, tooling — nothing user-visible |
+| `ci` | CI/CD config |
+| `style` | Formatting only |
+| `revert` | Reverts a prior commit |
+| `build` | Build system / bundler config |
+
+Subject:
+- ≤ 50 chars
+- imperative ("add login retry", not "added", not "adds")
+- no trailing period
+- lowercase first word (after the type/scope prefix)
+
+Body (only when ≥ 3 files or non-obvious *why*):
+- explain motivation, trade-offs, links to issues
+- bullet list when summarizing multiple changes
+
+### Example
 
 ```
-type(scope): description
+feat(auth): add session refresh with rotating cookies
 
-Body explaining what and why.
+- Issue rotated session id on each login + every 7 days
+- Persist previous id for 30s grace window to avoid races
+- Drop legacy cookie name `sid` from response set; honor on read
+```
 
+### **No AI-attribution footers** *(commit-manager v2.0.0+ rule)*
+
+Do **not** append:
+```
 Generated with Claude Code
 Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
-## Flow
+The commit message describes the change. Tooling provenance lives in CI artifacts, signed commits, or release metadata — not in every commit body.
+
+## 3. Two valid flows
+
+The repo's CLAUDE.md (or `git-workflow` overlay) declares which is in effect.
+
+### Flow A — direct-to-main (small repos, single contributor, fast iteration)
+
+```
+1. Pull main, ensure clean tree
+2. Make changes
+3. Quality gate green
+4. Commit → push to main
+```
+
+### Flow B — feature branch + merge (multi-contributor, CI gates required)
 
-1. Create branch from main: `git checkout -b feature/name`
+```
+1. From clean main, create branch:    git checkout -b feature/<name>
 2. Work, commit incrementally
-3. When done: merge to main, delete branch
-4. Push main to remote
+3. Quality gate green
+4. Push branch:                       git push -u origin HEAD
+5. Open PR; CI must pass
+6. Merge (squash or rebase — never merge commit on main)
+7. Delete branch local + remote
+8. Checkout main, pull
+```
+
+End state in **both flows**: clean tree, on `main`, in sync with `origin/main`. The Stop validator enforces this.
+
+## 4. Push policy
+
+| Operation | Allowed | Notes |
+|---|---|---|
+| `git push` to feature branch | ✅ Always | Force-push only if branch is yours and not yet reviewed |
+| `git push` to main | ✅ When tree clean and CI green locally | Branch protection should reject otherwise |
+| `git push --force-with-lease` to feature branch | ✅ Preferred over `--force` | Refuses if remote moved since your last fetch |
+| `git push --force` to main | ❌ Never | Re-writes shared history |
+| `git push --no-verify` | ❌ Never | Bypasses hooks intentionally configured to gate |
+
+## 5. Pre-flight checklist (commit-manager runs this internally)
+
+- [ ] Working tree status reviewed (`git status -sb`)
+- [ ] Diff reviewed (`git diff --stat HEAD` then `git diff` if needed)
+- [ ] Quality gate passed (typecheck / lint / tests / build)
+- [ ] Security gate passed (`security-auditor` clean)
+- [ ] No secrets in diff (gitleaks)
+- [ ] CLAUDE.md `Last Change` updated when scope warrants it
+- [ ] Conventional commit message drafted
+- [ ] Push target confirmed (`origin main` vs `origin feature/*`)
+
+## 6. Tags & releases
+
+```bash
+# Annotated tags only — lightweight tags are stripped by some hosts
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+```
+
+Semver: bump `MAJOR.MINOR.PATCH` per breaking/feature/fix.
+
+## 7. Recovering from mistakes
+
+| Situation | Fix |
+|---|---|
+| Bad commit not pushed | `git reset --soft HEAD~1`, fix, re-commit |
+| Bad commit pushed to feature branch | `git commit --amend` then `git push --force-with-lease` |
+| Bad commit pushed to main | `git revert <sha>` and push the revert (NEVER force-push main) |
+| Pushed a secret | Revoke at provider FIRST, then `git filter-repo` + force-push (one-time, document it) |
+| Wrong branch | `git stash`, `git checkout <correct>`, `git stash pop` |
 
 ## Rules
 
-- NEVER force push main
-- ALWAYS conventional commits
-- ALWAYS end on main branch
-- ONE feature per branch
+- **NEVER** force-push `main` / `master`
+- **NEVER** `--no-verify` to bypass hooks
+- **ALWAYS** Conventional Commits, no AI-attribution footers
+- **ALWAYS** end on `main` with a clean tree (Stop validator enforces)
+- **ONE** feature per branch (or per direct-to-main commit batch)
+
+## See Also
+
+- `commit-manager` agent — drives the message + push pipeline
+- `quality-gate` — the gate the commit-manager waits for
+- `secrets-management` — gitleaks 3-layer (pre-commit, CI, push protection)
+- `ci-pipelines` — branch-protection rules that mirror this skill