hatch3r 1.9.0 → 2.0.0

package/dist/content/skills/hatch3r-containerize/SKILL.md

@@ -0,0 +1,157 @@
+---
+id: hatch3r-containerize
+name: hatch3r-containerize
+type: skill
+description: Containerizes an application through a repeatable workflow — multi-stage Dockerfile, non-root hardening, minimal base image, .dockerignore, healthcheck, local docker-compose, Kubernetes manifest basics, and an image-scan gate. Use when adding or hardening container artifacts.
+tags: [devops]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+
+# Containerization Workflow
+
+Companion workflow to the `hatch3r-devops` agent: that agent reviews and authors infrastructure across CI/CD, IaC, and orchestration with apply-step gating; this skill is the focused step-by-step procedure for producing a hardened container image and its local + orchestration manifests. Use this skill when the task is "containerize this service" or "harden this Dockerfile"; escalate to the agent when the work spans pipelines, cloud IaC, or a deployment strategy.
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Pick a minimal base image + plan build/runtime split
+- [ ] Step 2: Write the multi-stage Dockerfile
+- [ ] Step 3: Harden — non-root USER, dropped privileges, HEALTHCHECK
+- [ ] Step 4: Add .dockerignore + verify build context size
+- [ ] Step 5: Author docker-compose for local dev
+- [ ] Step 6: Author Kubernetes manifest with securityContext
+- [ ] Step 7: Scan the image and gate on findings
+```
+
+Two invariants bound every image this workflow produces: it runs as a non-root user, and it ships only runtime artifacts (no build toolchain, no secrets). Steps 2–3 establish both; Step 7 verifies them.
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: language/runtime + version (drives base-image choice), whether the target is local-dev-only or production orchestration, the orchestrator (plain Docker vs docker-compose vs Kubernetes), whether secrets are needed at build time vs runtime (build-time secrets are an irreversible leak risk), and the registry the final image pushes to.
+
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (one service, Dockerfile only): inline.
+- Tier 2 (Dockerfile + compose + one K8s manifest for one service): spawn one sub-agent per artifact via the Task tool.
+- Tier 3 (multi-service repo, one image set per service): one fresh sub-agent per service; orchestrator integrates the compose/manifest set only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Step 1: Pick a Minimal Base Image and Plan the Build/Runtime Split
+
+- Choose the smallest base that runs the app: a `-slim` variant, a distroless image, or Alpine where the libc difference is acceptable. A smaller base shrinks attack surface and pull time (Docker best-practices — see References).
+- Plan two stages: a build stage that carries the full toolchain (compilers, dev dependencies, test runners) and a runtime stage that carries only the built artifact plus its runtime dependencies (Docker multi-stage — see References).
+- Pin the base image to a specific tag or digest (`node:22.5.1-slim`, not `node:latest`). A mutable tag makes the build non-reproducible.
+
+## Step 2: Write the Multi-Stage Dockerfile
+
+Structure the Dockerfile so each `FROM` begins a stage and the final stage copies only the runtime output:
+
+```dockerfile
+# --- build stage ---
+FROM node:22.5.1-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+# --- runtime stage ---
+FROM node:22.5.1-slim AS runtime
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+```
+
+- Order instructions stalest-to-freshest: copy the lockfile and install dependencies before copying source, so a code edit does not bust the dependency-install layer cache.
+- `COPY --from=build` only the artifacts the app needs at runtime — never the source tree, build cache, or dev dependencies.
+- Never write a secret into a layer. Use BuildKit build secrets (`RUN --mount=type=secret,...`) for build-time credentials and runtime environment injection for runtime credentials; a secret in any layer is recoverable from the image (OWASP Docker Security — see References).
+
+## Step 3: Harden — Non-Root, Dropped Privileges, Healthcheck
+
+- Create a dedicated unprivileged user with an explicit UID/GID and switch to it before the run command. An explicit UID survives rebuilds and maps to a Kubernetes `runAsUser` (Docker best-practices — see References):
+
+```dockerfile
+RUN groupadd -r app --gid=10001 && useradd -r -g app --uid=10001 app
+USER app
+```
+
+- Running as root is the most common dangerous container misconfiguration: a container escape inherits host root (OWASP Docker Security — see References). The non-root `USER` line is mandatory output of this step.
+- Add a `HEALTHCHECK` so the orchestrator can detect and restart an unhealthy container — this is CIS Docker Benchmark control 4.6 (CIS — see References):
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
+  CMD node ./dist/healthcheck.js || exit 1
+```
+
+- Do not install `sudo`; its TTY and signal-forwarding behavior is unpredictable. If privilege elevation is unavoidable, use `gosu` (Docker best-practices — see References).
+- Use `COPY` not `ADD` (ADD's URL-fetch and auto-extract behavior is a footgun); set `ENV NODE_ENV=production` (or the runtime equivalent) so the app does not load dev tooling.
+
+## Step 4: Add .dockerignore and Verify Build Context Size
+
+- Author a `.dockerignore` excluding `.git`, `node_modules` (rebuilt in-image), `.env*`, test artifacts, CI config, and local build output. This keeps secrets out of the build context and shrinks the upload sent to the daemon.
+- A `.env` file reaching the build context is a credential-leak path even if a layer does not copy it — exclude it explicitly.
+- Verify: run the build and confirm the "transferring context" size is small (kilobytes, not the whole repo). A large context means the `.dockerignore` missed something.
+
+## Step 5: Author docker-compose for Local Dev
+
+- Write a `docker-compose.yml` (or `compose.yaml`) that builds the image and wires backing services (database, cache, queue) for local development.
+- Inject configuration via `environment:` / `env_file:` referencing a gitignored `.env`; never inline secrets in the compose file.
+- Add a `healthcheck:` per service and use `depends_on:` with `condition: service_healthy` so the app waits for its database to be ready.
+- Pin backing-service images to specific tags, mirroring the Dockerfile base-pin policy.
+- Mount source as a volume only in the local-dev compose, never in the production image build.
+
+## Step 6: Author the Kubernetes Manifest with securityContext
+
+- Author a Deployment + Service. Set a `securityContext` that enforces the Dockerfile hardening at the orchestrator layer (Kubernetes hardening — see References):
+
+```yaml
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 10001
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop: ["ALL"]
+```
+
+- Set resource `requests` and `limits` (CPU + memory) so a runaway container cannot starve the node.
+- Map the Dockerfile `HEALTHCHECK` to a `readinessProbe` and `livenessProbe` so Kubernetes gates traffic and restarts on the same signal.
+- Reference secrets via a `Secret` object or external secret store; never inline credentials in the manifest.
+- Drop all Linux capabilities and add back only what the workload requires (OWASP Docker Top 10 — see References).
+
+## Step 7: Scan the Image and Gate on Findings
+
+- Build the image, then scan it with a vulnerability scanner (Trivy, Grype, or `docker scout`) before pushing. Trivy also runs CIS Docker/Kubernetes benchmark checks (Trivy / CIS — see References).
+- Gate: block the push on any fixable HIGH or CRITICAL CVE. For an unfixable CVE with no upstream patch, record an explicit accepted-risk note with the CVE id and a re-check date rather than silently shipping.
+- Re-scan after a base-image bump — a new base introduces a new CVE set.
+- Optionally run a config linter (`hadolint` for the Dockerfile, Docker Bench for Security against the host) and surface findings alongside the CVE report.
+
+## Error Handling
+
+- **Final image is unexpectedly large:** confirm the runtime stage copies only artifacts (Step 2), the base is a `-slim`/distroless variant (Step 1), and `.dockerignore` excludes `node_modules`/build output (Step 4). A multi-hundred-MB image usually means the build toolchain leaked into the runtime stage.
+- **App fails to start as non-root:** the process is binding a privileged port (<1024) or writing to a path it no longer owns. Bind a high port and map it at the orchestrator, or `chown` the writable path to the app UID in the build stage. Do not revert to root.
+- **`readOnlyRootFilesystem: true` breaks the app:** mount an `emptyDir` volume at the specific writable path (cache, tmp) the app needs rather than disabling the read-only root.
+- **Scanner reports a CVE with no fix:** do not silently ship. Record the CVE id, affected package, and a re-evaluation date as an accepted-risk note; escalate if it is on the request path and exploitable.
+- **Build needs a secret:** never `COPY` or `ARG` it into a layer. Use a BuildKit secret mount (`RUN --mount=type=secret`); if that is unavailable, build the artifact outside the image and `COPY` only the result.
+
+## Definition of Done
+
+- [ ] Multi-stage Dockerfile: build stage and a runtime stage carrying only runtime artifacts
+- [ ] Runs as a non-root user with an explicit UID; no `sudo`; `HEALTHCHECK` present
+- [ ] Minimal pinned base image (no `latest`); `.dockerignore` verified to shrink the build context
+- [ ] docker-compose for local dev with per-service healthchecks and gitignored secret injection
+- [ ] Kubernetes manifest with `securityContext` (runAsNonRoot, dropped capabilities, read-only root), resource limits, and probes
+- [ ] Image scanned; build/push gated on fixable HIGH/CRITICAL CVEs; accepted-risk notes recorded for unfixable findings
+- [ ] No secret in any image layer, compose file, or manifest
+
+## References
+
+- Docker, Inc. "Building best practices — Dockerfile." `https://docs.docker.com/build/building/best-practices/` (accessed 2026-06-02, Docker Docs, official-docs). Source for the minimal-base-image guidance (Step 1), the non-root `USER` with explicit UID and the no-`sudo`/`gosu` rule (Step 3), and `COPY`-over-`ADD`. Multi-stage build mechanics (Step 2): `https://docs.docker.com/build/building/multi-stage/`.
+- OWASP Foundation. "Docker Security Cheat Sheet." `https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html` (accessed 2026-06-02, OWASP, official-docs). Source for the drop-all-capabilities-then-add-back posture (Steps 6), the no-secrets-in-layers rule (Steps 2–4), and the root-escape blast-radius rationale behind the mandatory non-root user (Step 3). Container-environment controls: OWASP Docker Top 10 `https://owasp.org/www-project-docker-top-10/`.
+- Center for Internet Security / Aqua Security (Trivy). "CIS Docker Benchmark — HEALTHCHECK (control 4.6) and Trivy CIS benchmark scanning." `https://www.cisecurity.org/benchmark/docker` and `https://www.aquasec.com/blog/trivy-kubernetes-cis-benchmark-scanning/` (accessed 2026-06-02, CIS official-docs + Aqua Security established-library). Source for the `HEALTHCHECK` requirement (Step 3), the Kubernetes `securityContext` hardening fields (Step 6), and the Trivy CIS-benchmark image-scan gate (Step 7).

package/dist/content/skills/hatch3r-context-health/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-context-health
-description: Monitor and maintain conversation context health during long sessions. Use when context may be degrading, after many turns, or when experiencing repeated errors.
+name: hatch3r-context-health
+type: skill
+description: Monitors and maintains conversation context health during long sessions. Use when context may be degrading, after many turns, or when experiencing repeated errors.
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -25,12 +27,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Step 1: Assess Context Health
 
@@ -128,3 +125,8 @@ When `board-pickup` operates in auto-advance mode, context health is checked bet
 ## Related Skills & Agents
 
 - **Command**: `hatch3r-board-pickup` -- auto-advance mode uses context health for session management
+
+## References
+
+- [Token counting — Anthropic API docs](https://docs.anthropic.com/en/docs/build-with-claude/token-counting) — accessed 2026-05-31, official-docs (Anthropic). Source for treating the 1-token-per-4-characters figure as an approximation when the platform does not expose exact token counts (Error Handling, Step 1).
+- [Effective context engineering for AI agents — Anthropic engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — accessed 2026-05-31, official-docs (Anthropic). Source for the context-degradation and context-window-pressure signals behind the model-aware threshold profiles and the context-poisoning detection table.

package/dist/content/skills/hatch3r-cost-tracking/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-cost-tracking
-description: Track token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
+name: hatch3r-cost-tracking
+type: skill
+description: Tracks token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -10,11 +12,14 @@ cache_friendly: true
 
 ## Quick Start
 
+**Applies when:** the project tracks cloud/LLM spend against a budget. On a project with no cost-accounting need, skip (per `rules/hatch3r-right-sizing.md`).
+
 ```
 Task Progress:
 - [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Review cost tracking configuration
 - [ ] Step 2: Estimate current session token usage
+- [ ] Step 2a: Re-fetch pricing before reporting (currency gate)
 - [ ] Step 3: Identify cost optimization opportunities
 - [ ] Step 4: Generate cost report
 ```
@@ -25,12 +30,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Step 1: Review Configuration
 
@@ -53,13 +53,25 @@ Estimate tokens for the current session using these rules:
 
 **Subagent cost multiplier.** Each subagent spawn carries a base cost for the agent protocol, included rules, and context. A pipeline with 8 subagents (researcher + implementer + reviewer + fixer + 4 Phase 4 specialists) has significant overhead from context re-transmission. Factor this into budget estimates.
 
-Calculate estimated cost using these model tier rates (reference rates — update based on actual provider pricing):
+Calculate estimated cost using named-model rates tied to model IDs. Published-vendor rates drift between model releases — re-fetch before every report per Step 2a; the `accessed:` date marks when each row was last verified.
+
+| Model | Model ID | Input (per 1M) | Output (per 1M) | accessed |
+|-------|----------|---------------:|----------------:|----------|
+| Claude Haiku 4.5 | `claude-haiku-4-5` | $1.00 | $5.00 | 2026-06-05 |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` | $3.00 | $15.00 | 2026-06-05 |
+| Claude Opus 4.8 | `claude-opus-4-8` | $5.00 | $25.00 | 2026-06-05 |
+
+**Cache-read multiplier.** Cached input tokens (`cache_read_input_tokens` in the API `usage` block) bill at ~0.1× the model's base input rate; cache writes bill at 1.25× (5-minute TTL) or 2× (1-hour TTL). When a session reuses a large cached prefix, price `cache_read_input_tokens` separately at 0.1× base input — counting them at full input rate overstates spend by up to 10× on cache-heavy agent loops. Total prompt size = `input_tokens` (uncached) + `cache_creation_input_tokens` + `cache_read_input_tokens`.
+
+### Step 2a: Re-fetch Pricing Before Reporting (currency gate)
 
-| Model Tier | Input (per 1M tokens) | Output (per 1M tokens) |
-|-----------|----------------------|----------------------|
-| Fast | $0.25 | $1.00 |
-| Standard | $3.00 | $15.00 |
-| Premium | $15.00 | $75.00 |
+Published per-token rates change between model releases. Before emitting a cost figure, verify the rate table is current:
+
+1. If any row's `accessed:` date is older than 30 days, re-fetch the vendor's current pricing (Anthropic: https://www.anthropic.com/pricing, or the live `claude-api` skill's models/pricing reference) and update the row's rates + `accessed:` date in place.
+2. Confirm the model the session actually ran on maps to a named row. If the session used a model ID absent from the table (e.g. an older or non-Anthropic model), add a row with its published rates and `accessed:` date rather than defaulting to the nearest tier.
+3. State the `accessed:` date of the rate used directly in the report (see Step 4). A cost figure with no rate-provenance date is unverifiable — never report a dollar amount without it.
+
+If pricing cannot be re-fetched (offline, vendor page unreachable), proceed with the on-file rates but flag the figure as `(rates as of <accessed-date>, not re-verified)` in the report.
 
 ### Default Budgets
 
@@ -102,11 +114,13 @@ Produce a cost report in this format:
 **Period:** {session/issue/sprint}
 
 **Token Usage:**
-- Input tokens: ~{n}
+- Input tokens (uncached): ~{n}
+- Cache-read tokens: ~{n} (billed ~0.1x base input)
+- Cache-write tokens: ~{n} (billed 1.25x / 2x by TTL)
 - Output tokens: ~{n}
 - Total tokens: ~{n}
 
-**Estimated Cost:** ${amount}
+**Estimated Cost:** ${amount} ({model-id}, rates accessed {YYYY-MM-DD})
 
 **Budget Status:** {amount} / {budget} ({percentage}%)
 
@@ -124,7 +138,7 @@ Produce a cost report in this format:
 - {suggestions based on usage patterns}
 ```
 
-Include total estimated tokens (input + output), estimated cost at current model tier, budget status (if configured), and top optimization opportunities. Always present estimated values with the `~` prefix. Never suppress threshold alerts.
+Include total estimated tokens (uncached input + cache-read + cache-write + output), estimated cost at the named-model rate with its `accessed:` date, budget status (if configured), and top optimization opportunities. Always present estimated values with the `~` prefix. Never report a dollar figure without the model ID and rate-access date. Never suppress threshold alerts.
 
 ## Error Handling
 
@@ -135,10 +149,16 @@ Include total estimated tokens (input + output), estimated cost at current model
 ## Definition of Done
 
 - [ ] Cost configuration reviewed (or report-only mode noted)
-- [ ] Token usage estimated for current session
+- [ ] Token usage estimated for current session (uncached input / cache-read / cache-write / output split)
+- [ ] Pricing rates verified current per Step 2a; report cites model ID + rate `accessed:` date
 - [ ] Optimization opportunities identified
 - [ ] Cost report generated with budget status
 
 ## Related Skills & Agents
 
 - **Skill**: `hatch3r-context-health` — context health monitoring complements cost tracking for session management
+
+## References
+
+- [Anthropic API pricing](https://www.anthropic.com/pricing) — accessed 2026-06-05, official-docs (Anthropic). Source for the per-million-token input/output rates per named model (Haiku 4.5 $1/$5, Sonnet 4.6 $3/$15, Opus 4.8 $5/$25) and the cache-read 0.1x / cache-write 1.25x-2x multipliers in Step 2; these drift between model releases — re-verify per Step 2a when running a cost report.
+- [Token counting — Anthropic API docs](https://docs.anthropic.com/en/docs/build-with-claude/token-counting) — accessed 2026-06-05, official-docs (Anthropic). Source for treating the ~4-characters-per-token figure as an approximation; the documented count-tokens endpoint is authoritative when exact counts are required.

package/dist/content/skills/hatch3r-customize/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-customize
-description: Create and manage customization files for any hatch3r artifact type (agents, commands, rules, skills). Supports model overrides, description changes, scope overrides, enable/disable control, and project-specific markdown instructions.
+name: hatch3r-customize
+type: skill
+description: Creates and manages customization files for any hatch3r artifact type (agents, commands, rules, skills). Supports model overrides, description changes, scope overrides, enable/disable control, and project-specific markdown instructions.
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -8,7 +10,7 @@ cache_friendly: true
 ---
 # Artifact Customization Management
 
-> **Canonical entry point.** This is the single skill for all per-artifact customization (agents, commands, rules, skills). The four prior type-specific skill stubs were removed in v1.9.0 per the Decision #13 Command-vs-Skill criterion; `governance/audit/domains/D16-compound-system.md` SA 16.3 documents the rejected-merge alternative.
+> **Canonical entry point.** This is the single skill for all per-artifact customization (agents, commands, rules, skills). The four prior type-specific skill stubs were removed in v1.9.0 per the Decision #13 Command-vs-Skill criterion; hatch3r's artifact-inventory and redundancy analysis documents the rejected-merge alternative.
 
 ## Quick Start
 
@@ -29,12 +31,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Artifact Types
 

package/dist/content/skills/hatch3r-dep-audit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-dep-audit
-description: Audit and update npm dependencies for security, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or upgrading packages.
+name: hatch3r-dep-audit
+type: skill
+description: Audits and updates npm dependencies for security, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or upgrading packages.
 tags: [maintenance, floor:security]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -29,12 +31,19 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+## Required Agent Delegation
+
+> **Note:** When this skill is invoked via an orchestration pipeline (a `commands/hatch3r-*.md` flow), skip this section — the orchestrator handles agent delegation.
+
+This skill realizes the two-agent dependency pattern (governance PRD Decision 13, F13.1-F04): the agent that *assesses* upgrade risk is distinct from the agent that *applies* it. Spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the points below:
+
+- **`hatch3r-dependency-drafter`** (analysis phase, Steps 1–3) — MUST spawn to inventory the dependency surface, classify each candidate by SemVer band, cross-check advisories, and draft the per-dependency proposal (current pin → proposed pin, band, driver, risk, consumer call sites, verification gate). The drafter is read-only (its `tools.deny` forbids manifest edits and installs), so its proposal is a reviewable decision artifact, not a mutation. Skip only for a trivial single-package patch already scoped by the invocation.
+- **`hatch3r-fixer`** (apply phase, Step 4) — MUST spawn under reviewer authority to perform the manifest edit + `npm install` + per-upgrade verification the drafter's proposal names. The fixer flips each proposal from `drafted` to `applied` after its row's verification gate passes.
+- **`hatch3r-devops`** (apply phase, Step 4 — CI-wiring variant) — spawn instead of `hatch3r-fixer` when the upgrade requires CI manifest wiring (lockfile-cache keys, build-matrix version pins, Renovate/Dependabot config) rather than only a source-tree dependency bump.
+
+The drafter never applies and the fixer/devops never re-assess risk — the split keeps risk assessment separate from risk acceptance.
 
 ## Step 1: Gather Findings
 
@@ -75,10 +84,12 @@ Before changing anything:
 ## Step 5: Verify
 
 ```bash
-npm run lint && npm run typecheck && npm run test
+${HATCH3R:VERIFY_GATE_ALL}
 npm run build
 ```
 
+The gate line is resolved to the project's language-aware command set at sync time (fallback when detection is unknown: `npm run lint && npm run typecheck && npm run test`); the build line is illustrative — substitute the project's build command.
+
 - Confirm bundle size within budget (if defined).
 - Run `npm audit` — no critical or high vulnerabilities remaining.
 - Verify `package-lock.json` is committed by checking `git status` for untracked or modified lockfile.
@@ -111,3 +122,8 @@ For CVEs or outdated packages not addressed in this session, create a tracking i
 - [ ] `package-lock.json` committed
 - [ ] PR includes upgrade rationale and bundle impact
 - [ ] No duplicate packages; unused deps removed
+
+## References
+
+- [npm audit — npm CLI docs](https://docs.npmjs.com/cli/v10/commands/npm-audit) — accessed 2026-05-31, official-docs (npm, Inc.). Source for the `npm audit` severity buckets (critical/high/moderate/low) and `npm outdated` semantics used in Step 1.
+- [GitHub security advisories REST API](https://docs.github.com/en/rest/security-advisories/repository-advisories) — accessed 2026-05-31, official-docs (GitHub). Source for the `gh api /repos/{owner}/{repo}/security-advisories` CVE-research path in Step 2.

package/dist/content/skills/hatch3r-design-system-detect/SKILL.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-design-system-detect
+name: hatch3r-design-system-detect
 type: skill
-description: Detect existing design tokens, component library, and theming convention in a project before authoring new UI primitives — output a concise inventory for downstream implementers
+description: Detects existing design tokens, component library, and theming convention in a project before authoring new UI primitives — output a concise inventory for downstream implementers
 tags: [implementation, floor:ui-ux, ui, design-system, frontend]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -29,12 +30,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Step 1: Scan package.json for design-system signals
 

package/dist/content/skills/hatch3r-docs-writing/SKILL.md

@@ -0,0 +1,159 @@
+---
+id: hatch3r-docs-writing
+name: hatch3r-docs-writing
+type: skill
+description: Authors technical documentation through a repeatable workflow — audience analysis, Diátaxis-mode selection, structure, draft, review, publish. Covers READMEs, ADRs, API docs, and runbooks. Use when writing or restructuring any project documentation.
+tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+
+# Technical Documentation Workflow
+
+Companion workflow to the `hatch3r-docs-writer` agent: that agent is the Phase-4 specialist invoked to update specs after a code change; this skill is the step-by-step procedure a human or agent follows to author a documentation artifact from scratch. Use the agent when documentation must track a `src/` diff; use this skill when authoring a new doc and you need the audience-analysis-through-publish sequence.
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Classify the doc by Diátaxis mode + name the audience
+- [ ] Step 2: Pick the structure template for the chosen mode
+- [ ] Step 3: Draft to the template, one mode per document
+- [ ] Step 4: Run the review checklist (audience, accuracy, style, structure)
+- [ ] Step 5: Publish — link from an index, set owner + last-updated, verify cross-references
+```
+
+The load-bearing decision is Step 1: a document serves exactly one of four user needs. Mixing learning content into a reference table, or burying a how-to procedure inside an explanation, is the most common defect this workflow prevents (Diátaxis — see References).
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target audience, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: which doc type is wanted (README vs ADR vs API reference vs runbook), the reader's existing competence (new user vs maintainer vs on-call), whether an existing doc is being restructured (irreversible section moves), and where the published doc is linked from.
+
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single doc, single mode): inline.
+- Tier 2 (multi-doc set, e.g. README + API reference + runbook for one feature): spawn one sub-agent per document via the Task tool; each authors to its own Diátaxis mode.
+- Tier 3 (full docs-site restructure across many modes): one fresh sub-agent per top-level section; orchestrator integrates the index only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Step 1: Classify by Diátaxis Mode and Name the Audience
+
+Every document answers exactly one of four user needs. Pick one mode before writing a single sentence; if a request spans two, split it into two documents.
+
+| Mode | User need | Reader state | Writing stance |
+|------|-----------|--------------|----------------|
+| Tutorial | Learning by doing | Newcomer, no prior context | Lesson — guarantee a working result, hide edge cases |
+| How-to guide | Achieving a stated goal | Already competent, has a task | Recipe — numbered steps to one outcome, no theory |
+| Reference | Looking up a fact | Working, needs accuracy | Description — complete, dry, structured, no narrative |
+| Explanation | Understanding why | Studying, off-task | Discussion — context, trade-offs, alternatives, rationale |
+
+Map common artifacts to modes:
+
+| Artifact | Primary mode | Note |
+|----------|--------------|------|
+| README | How-to (quickstart) + Reference (config) | Lead with the 60-second "get it running" path; link out to deep docs |
+| API docs | Reference | Endpoint, params, request/response shapes, error codes, auth — one entry per endpoint |
+| Runbook | How-to | Operational procedure: prerequisites, numbered steps, verification, rollback |
+| ADR | Explanation | A decision and its rationale — context, decision, consequences |
+
+Name the audience explicitly in one sentence (e.g., "on-call engineer mid-incident, has shell access, has not seen this service before"). Write to a US-English global-audience reader: short unambiguous sentences, active voice, direct address with "you" (Google dev-docs style — see References). The audience sentence drives every later choice — vocabulary, assumed prerequisites, depth.
+
+## Step 2: Pick the Structure Template
+
+Use the template for the mode chosen in Step 1.
+
+**README (how-to + reference):**
+1. One-line description of what the project is.
+2. Quickstart — the shortest verified path from clone to a running result.
+3. Prerequisites (versions, accounts, tools).
+4. Configuration reference (table: option, type, default, description).
+5. Links to deeper docs (tutorial, full reference, contributing).
+
+**ADR (Nygard format — see References):**
+1. Title (`NNNN-short-decision-name`).
+2. Status (proposed | accepted | rejected | deprecated | superseded by NNNN).
+3. Context (the forces and problem that motivate the decision).
+4. Decision (the change, stated as "we will…").
+5. Consequences (positive and negative effects, including new obligations).
+
+**API reference (one block per endpoint):**
+- Method + path; one-line purpose.
+- Authentication required (scheme + scope).
+- Request: path/query/body params (table: name, type, required, description).
+- Response: success shape + status, paginated where applicable.
+- Errors: status code + meaning + when it fires.
+
+**Runbook (how-to):**
+1. Trigger — what condition this runbook handles.
+2. Prerequisites — access, tools, on-call context.
+3. Numbered steps — each step one action with the exact command.
+4. Verification — the observable signal that confirms success.
+5. Rollback — how to undo if a step fails.
+6. Escalation — who to page if the runbook does not resolve it.
+
+## Step 3: Draft to the Template
+
+- Write to the one chosen mode. If you reach for "but first, some background" inside a how-to, that background belongs in a separate explanation doc — link to it instead.
+- Use a descriptive heading that matches the content type: a bare infinitive for a task heading ("Configure the database"), a noun phrase for a concept heading ("Database configuration") — Google dev-docs style.
+- Put structured facts in tables (config options, params, error codes, invariants), not prose.
+- Put acceptance criteria and operational steps in checklists or numbered lists.
+- Use stable IDs from the project glossary (event IDs, invariant IDs) so the doc survives renames.
+- Every code example uses a current, non-deprecated API — verify against the library's docs at draft time.
+- State confidence on any claim you could not verify against source: mark it `[unverified]` and recommend a maintainer check before publish (quality charter — confidence levels).
+
+## Step 4: Review Checklist
+
+Run all four lenses before publishing. A failure on any line is a blocker.
+
+**Audience:**
+- [ ] The named reader can act on this doc with only the prerequisites it lists — no unstated assumed knowledge.
+- [ ] Depth matches the audience: a tutorial hides edge cases; a reference omits none.
+
+**Accuracy:**
+- [ ] Every command, code block, and config value was run or read against the current source — no copy-from-memory.
+- [ ] Cross-references resolve (no dead links, no renamed-away anchors).
+- [ ] Stable IDs match the glossary.
+
+**Style:**
+- [ ] Active voice, second person, short sentences (Google dev-docs style).
+- [ ] No filler ("it is important to note", "simply", "just"); state the fact directly.
+- [ ] Headings match content type (infinitive for task, noun phrase for concept).
+
+**Structure:**
+- [ ] One Diátaxis mode per document — no learning content in a reference, no theory in a how-to.
+- [ ] Findable from an index or parent doc.
+- [ ] README leads with a runnable quickstart; runbook ends with verification + rollback; ADR records consequences.
+
+## Step 5: Publish
+
+- Link the new doc from its index or parent (a doc no one can find does not exist).
+- Add an ownership footer: owner, reviewers, last-updated date.
+- Re-verify cross-references after the file lands at its final path (anchors shift when filenames change).
+- For docs that mirror code (API reference, config reference), note the source-of-truth file path so the next editor knows what to re-check against.
+- Lint markdown before declaring done (e.g., `npx markdownlint <path>`); a broken table or heading level is a structure defect.
+
+## Error Handling
+
+- **Source code contradicts the existing doc:** the code is the source of truth for behavior. Update the doc to match observed behavior and flag the stale section in the change summary; do not document the intended-but-absent behavior.
+- **Request spans two Diátaxis modes:** do not blend them. Split into two documents (e.g., a how-to guide plus a linked explanation) and state the split in your output.
+- **Cannot verify a code example against source:** mark the example `[unverified]`, recommend a maintainer run it, and lower the document's stated confidence to medium rather than publishing an unverified example as fact.
+- **No index or parent to link from:** create or identify the index entry as part of this work — an unlinked doc fails Step 5.
+
+## Definition of Done
+
+- [ ] Document classified to exactly one Diátaxis mode with a one-sentence named audience
+- [ ] Authored to the matching structure template
+- [ ] All four review-checklist lenses pass (audience, accuracy, style, structure)
+- [ ] Linked from an index/parent; ownership + last-updated footer present
+- [ ] Cross-references resolve and code examples verified against current source (or marked `[unverified]`)
+- [ ] No secrets, tokens, or internal-only URLs in the published text
+
+## References
+
+- Procida, Daniele. "Diátaxis — Start here." `https://diataxis.fr/start-here/` (accessed 2026-06-02, diataxis.fr, peer-reviewed-methodology). Source for the four-mode classification in Step 1 (tutorial / how-to / reference / explanation) and the one-mode-per-document discipline enforced in Steps 3–4.
+- Google. "Google developer documentation style guide — Highlights." `https://developers.google.com/style/highlights` (accessed 2026-06-02, Google for Developers, official-docs). Source for the global-audience writing stance (active voice, second person, short sentences) and the task-vs-concept heading rule (bare infinitive vs noun phrase) in Steps 1–4. Procedures guidance: `https://developers.google.com/style/procedures`.
+- Nygard, Michael. "Documenting Architecture Decisions." `https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions` (accessed 2026-06-02, Cognitect, established-library; ADR template used in 723+ open-source repositories per `https://adr.github.io/`). Source for the ADR structure template in Step 2 (Title / Status / Context / Decision / Consequences).