hatch3r 1.7.1 → 1.8.0

package/skills/hatch3r-cli-stagehand/SKILL.md

@@ -0,0 +1,111 @@
+---
+id: hatch3r-cli-stagehand
+description: "Browserbase Stagehand — AI-driven browser automation. Use when natural-language browser steering with on-the-fly DOM reasoning; invoke `stagehand`. Wraps Browserbase Stagehand so prompts decide which DOM nodes to inspect or click."
+tags: ["cli-tools", "browser", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: stagehand
+  bin: stagehand
+  tier: 3
+  category: browser
+  homepage: https://github.com/browserbase/stagehand
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# stagehand
+
+Browserbase Stagehand — AI-driven browser automation
+
+## When to Use
+
+Reach for `stagehand` when the task is in the **browser** category and the agent would otherwise call an MCP tool or read large outputs into context. v3 (released 2025-10-29) operates directly on the Chrome DevTools Protocol — choose Stagehand when the target page changes shape often enough that hand-written selectors break, or when a prompt is the most compact spec of intent.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## v3 Driver Model
+
+v3 dropped the hard Playwright dependency and exposes a modular driver layer. Pick the driver that matches the host environment:
+
+- **CDP-native (default):** Stagehand talks Chrome DevTools Protocol directly — no test-runner dependency, smallest install, Bun-compatible.
+- **Playwright peer:** install `playwright-core` alongside Stagehand to reuse existing Playwright fixtures, traces, or `@playwright/test` reporters.
+- **Puppeteer peer:** install `puppeteer-core` to share a launcher with existing Puppeteer scripts.
+- **Patchright peer:** install `patchright-core` for stealth-patched CDP profiles.
+
+`playwright-core`, `puppeteer-core`, and `patchright-core` are peer dependencies in v3 — install only the driver you use.
+
+## Recipes
+
+```bash
+npx create-browser-app
+```
+Scaffold a v3 Stagehand project with TypeScript wiring, a `stagehand.config.ts`, and an example `act`/`extract`/`observe` script. Replaces the v2 `npx stagehand init` workflow.
+
+```bash
+node scripts/login.ts
+```
+Execute an AI-driven action script. The script imports `Stagehand` from `@browserbasehq/stagehand`, calls `stagehand.act("click the login button")`, and Stagehand resolves the action at runtime via CDP — no test runner required.
+
+```bash
+npx browse get markdown https://example.com
+```
+One-shot page extraction via `browse-cli` (v0.6+). Returns structured Markdown the agent can consume directly; cheaper than spawning a full Stagehand session for a single read.
+
+```bash
+npx browse cdp wss://browser.example.com
+```
+Attach to an existing CDP endpoint (Browserbase managed session, local Chrome, or a custom launcher). Useful when the script delegates browser lifecycle to another supervisor.
+
+```typescript
+// scripts/observe.ts — observe primitive returns actions without executing
+import { Stagehand } from "@browserbasehq/stagehand";
+const stagehand = new Stagehand({ env: "LOCAL" });
+await stagehand.init();
+const actions = await stagehand.observe("find the login form");
+console.log(JSON.stringify(actions, null, 2));
+await stagehand.close();
+```
+Dry-run agent loop: `observe` returns the candidate action set without performing it, so a caller can route the decision (execute, ask the user, or reject).
+
+## Wrong Choice When
+
+- **High-volume scraping at scale:** Stagehand's per-action LLM round-trip is cost-prohibitive past a few hundred pages — use the Browserbase managed-browser product, raw CDP with cached locators (v3's `deepLocator`), or Stagehand's action cache once a workflow is recorded as a deterministic script.
+- **Headless CI in air-gapped environments:** Stagehand requires outbound LLM API access for selector resolution; offline environments fail the `act`/`extract`/`observe` calls. Pre-record actions with v3's automatic action cache, then replay the cached deterministic script in the air-gapped runner.
+- **Workflows already covered by a stable test suite:** if Playwright tests with hand-tuned locators already pass green, Stagehand adds an LLM round-trip per step with no behavioural gain. Use `hatch3r-cli-playwright` (tier 2) for the test surface; reserve Stagehand for the agent-driven exploratory flows.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-playwright` (tier 2) | Existing test fixtures, deterministic CI, no LLM round-trips needed |
+| Browserbase managed browsers | Production scale, session recording, anti-bot evasion, CAPTCHA solving |
+| Stagehand action cache (built into v3) | Same workflow re-run many times — record once, replay deterministically |
+| Skyvern / Browser-Use | Workflow-style automation with embedded LLM agents and built-in task loops |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v stagehand
+```
+
+Install (mac):
+
+```bash
+# npm — v3 (Oct 29 2025); drivers are peer deps, install only what you use
+npm install -g @browserbasehq/stagehand
+# Add a driver only if you need Playwright/Puppeteer/Patchright interop:
+# npm install -g playwright-core   # OR
+# npm install -g puppeteer-core    # OR
+# npm install -g patchright-core
+```
+
+References:
+- v3 release announcement (2025-10-29): https://www.browserbase.com/blog/stagehand-v3
+- Latest npm releases: https://github.com/browserbase/stagehand/releases
+- v3 docs: https://docs.stagehand.dev/v3/get_started/introduction
+
+Homepage: https://github.com/browserbase/stagehand

package/skills/hatch3r-cli-taplo/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-taplo
+description: "TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml. Use when formatting and linting pyproject.toml or Cargo.toml manifests; invoke `taplo`. Preserves YAML anchors, comments, and ordering when editing in place."
+tags: ["cli-tools", "yaml"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: taplo
+  bin: taplo
+  tier: 2
+  category: yaml
+  homepage: https://taplo.tamasfe.dev/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# taplo
+
+TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml
+
+## When to Use
+
+Reach for `taplo` when the task is in the **yaml** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+taplo fmt
+```
+Format every TOML file under the cwd in-place; idempotent — safe to run in pre-commit.
+
+```bash
+taplo fmt --check
+```
+Exit non-zero if any TOML file would change; CI-friendly drift detector.
+
+```bash
+taplo lint
+```
+Surface syntax and schema-violation diagnostics; works with bundled schemas for `Cargo.toml`, `pyproject.toml`.
+
+```bash
+taplo get -f Cargo.toml package.version
+```
+Extract a single TOML value as plain stdout — replaces a multi-line `grep`/`sed` recipe.
+
+```bash
+taplo get -f pyproject.toml -o json 'project.dependencies'
+```
+Emit the value as JSON for piping into `jq` — keeps quoting unambiguous.
+
+## Wrong Choice When
+
+- The project has no TOML files (pure YAML/JSON config) — skip entirely; use `yq` for YAML, `jq` for JSON.
+- You are converting TOML to YAML/JSON as the goal — `yq` or `dasel` handle multi-format conversion in one binary.
+- The TOML lives inside a templating system (Jinja/Handlebars) — render the template first, then run `taplo` on the output.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `yq` | Mixed YAML/TOML/JSON; want a single multi-format query tool. |
+| `dasel` | Same as `yq` plus XML; cross-format updates. |
+| `grep` + `sed` | A single value lookup in a script with no `taplo` dependency available. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v taplo
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install taplo
+```
+
+Homepage: https://taplo.tamasfe.dev/

package/skills/hatch3r-cli-yq/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-yq
+description: "YAML processor (mikefarah Go implementation). Use when editing Kubernetes manifests, Helm values, or GitHub-Actions workflows in place; invoke `yq`. Preserves YAML anchors, comments, and ordering when editing in place."
+tags: ["cli-tools", "yaml", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: yq
+  bin: yq
+  tier: 1
+  category: yaml
+  homepage: https://github.com/mikefarah/yq
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# yq
+
+YAML processor (mikefarah Go implementation)
+
+## When to Use
+
+Reach for `yq` when the task is in the **yaml** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+yq '.spec.containers[].image' k8s/deployment.yml
+```
+Project every container image across multi-doc Kubernetes manifests — same path syntax as `jq`.
+
+```bash
+yq -i '.version = "1.7.5"' .agents/hatch.json
+```
+In-place edit (`-i`) — single-shot version bumps without shelling out to a templating step.
+
+```bash
+yq -o=json '.' config.yml | jq '.servers | length'
+```
+Convert YAML to JSON on the wire so `jq` can take over for richer querying.
+
+```bash
+yq eval-all '. as $i ireduce ({}; . * $i)' base.yml override.yml
+```
+Deep-merge multiple YAML documents into one — pattern for layered config (base + env override).
+
+```bash
+yq -P -i '.tags |= sort | .' content.yml
+```
+Pretty-print preservation (`-P`) keeps comments/anchors stable while sorting the `tags` array in place.
+
+## Wrong Choice When
+
+- Don't assume `yq` flags work when the binary is actually the Python `kislyuk/yq` wrapper around jq — flags and filter dialect differ. Confirm `yq --version` reports `mikefarah` first; otherwise reach for `python-yq` documentation or install the Go build.
+- Don't expect round-trip comment preservation without the `-P` (pretty) output mode; default JSON-style output drops comments. Reach for `yq -P` or `taplo` for TOML.
+- Don't use `yq` on Kubernetes manifests when you actually need schema-aware validation. Reach for `kubectl explain` / `kubeconform` and use `yq` only for projection.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `jq` (`hatch3r-cli-jq`) | JSON input, or YAML converted via `yq -o=json` — jq's filter language has more rebuild idioms. |
+| `dasel` | Multi-format (JSON/YAML/TOML/XML) single-binary path queries in CI. |
+| `taplo` | TOML-specific formatting and schema validation (`pyproject.toml`, `Cargo.toml`). |
+| `kubectl explain` | Kubernetes-resource schema lookup — `yq` projects, kubectl explains. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v yq
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install yq
+```
+
+Homepage: https://github.com/mikefarah/yq

package/skills/hatch3r-cli-zstd/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-zstd
+description: "Fast lossless compression with high ratio. Use when high-ratio compression with single-digit-millisecond decompress speeds; invoke `zstd`. Designed for cold-storage payloads and CI artifact upload/download steps."
+tags: ["cli-tools", "archive", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: zstd
+  bin: zstd
+  tier: 1
+  category: archive
+  homepage: https://github.com/facebook/zstd
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# zstd
+
+Fast lossless compression with high ratio
+
+## When to Use
+
+Reach for `zstd` when the task is in the **archive** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+tar --zstd -cf bundle.tar.zst dist/ governance/
+```
+Stream `tar` through zstd in one shot — default level (~3) gives high-ratio archives an order of magnitude faster than gzip.
+
+```bash
+tar --zstd -xf bundle.tar.zst -C /tmp/restore/
+```
+Extract a zstd-compressed tarball to a target directory — paired with the previous recipe for round-trip backup.
+
+```bash
+zstd -19 -T0 huge.csv
+```
+Level 19 (near-max ratio) with `-T0` (all CPU threads) — appropriate for archival snapshots where compression time is fine.
+
+```bash
+pzstd --keep -d findings.tar.zst
+```
+Parallel decompression preserving the input (`--keep`) — fastest restore path for large `.zst` archives on multi-core hosts.
+
+```bash
+zstd --train datasets/*.json -o dict.zstd && zstd -D dict.zstd payload.json
+```
+Train a dictionary from a sample corpus then compress with `-D dict.zstd` — wins when payloads share schema (logs, structured events).
+
+## Wrong Choice When
+
+- Don't use `zstd` for distribution where every byte of size matters and decompression speed does not. Reach for `xz` (`xz -9e`) — slower but tighter ratios for immutable releases.
+- Don't ship a zstd archive to legacy Windows recipients without a bundled decoder; native support landed in Windows 11 but earlier hosts need 7-Zip 21.07+. Reach for `zip` for broadest compatibility.
+- Don't reach for `zstd` to compress already-compressed payloads (JPEGs, MP4s, existing zips); ratios approach 1.0 and the CPU spend is wasted. Skip compression or use `tar -cf` with no codec.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `xz` | Immutable release artifacts where size is the dominant cost. |
+| `gzip` | Universal compatibility — every UNIX-like system since 1992. |
+| `zip` | Windows recipients without native `.zst` support; flat distribution archives. |
+| `7z` | Heterogeneous payloads where xz-style LZMA2 plus per-file streaming beats both zstd and gzip. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v zstd
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install zstd
+```
+
+Homepage: https://github.com/facebook/zstd

package/skills/hatch3r-command-customize/SKILL.md

@@ -5,9 +5,19 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+redirect_to: hatch3r-customize
 ---
 # Command Customization
 
 > **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: command`.
 
 For command-specific reference (YAML schema, examples), see the `hatch3r-command-customize` command.
+
+## Rejected Merge Alternative (D16.3 add-vs-remove bias)
+
+Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
+
+1. **Preserves UX entry points.** Users typed `/h4tcher-command-customize` or referenced the id `hatch3r-command-customize` (per `commands/hatch3r-command-customize.md:2` and sibling redirects) before consolidation. Deleting the id breaks those entry points without a redirect target.
+2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
+
+The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

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

@@ -12,12 +12,26 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Assess current context health
 - [ ] Step 2: Identify degradation signals
 - [ ] Step 3: Apply corrective action
 - [ ] Step 4: Verify health improvement
 ```
 
+## 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: original task recall, corrective action authority at Orange/Red (delegate vs checkpoint-and-stop), scope of files to re-read, whether to post progress to platform on Red, and irreversible stop (discard unsaved work) vs preserve.
+
+## 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.
+
 ## Step 1: Assess Context Health
 
 Run through the self-assessment checklist:

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

@@ -12,12 +12,26 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Review cost tracking configuration
 - [ ] Step 2: Estimate current session token usage
 - [ ] Step 3: Identify cost optimization opportunities
 - [ ] Step 4: Generate cost report
 ```
 
+## 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: tracking scope (session vs issue vs epic), budget values when missing from hatch.json, hardStop authority (block vs warn), report format target, and whether to defer non-critical work over budget.
+
+## 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.
+
 ## Step 1: Review Configuration
 
 1. Check `hatch.json` for a `costTracking` section.

package/skills/hatch3r-customize/SKILL.md

@@ -5,13 +5,17 @@ tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+canonical_for: [hatch3r-agent-customize, hatch3r-command-customize, hatch3r-rule-customize, hatch3r-skill-customize]
 ---
 # Artifact Customization Management
 
+> **Canonical entry point.** Four type-specific skills (`hatch3r-agent-customize`, `hatch3r-command-customize`, `hatch3r-rule-customize`, `hatch3r-skill-customize`) redirect here via `redirect_to: hatch3r-customize` frontmatter. Their body documents the rejected-merge alternative per `governance/audit/domains/D16-compound-system.md` SA 16.3.
+
 ## Quick Start
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Identify what to customize (and why)
 - [ ] Step 2: Determine customization needs
 - [ ] Step 3: Multi-stakeholder review
@@ -20,6 +24,19 @@ Task Progress:
 - [ ] Step 6: Verify the customized output
 ```
 
+## 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: artifact type (agent vs command vs rule vs skill), target artifact id, whether disabling breaks a command pipeline dependency, scope narrowing for rules (and excluded glob patterns), and whether this customization should be an upstream contribution instead.
+
+## 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.
+
 ## Artifact Types
 
 This skill handles customization for all artifact types. The `type` parameter determines file locations, available YAML fields, and verification steps.

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

@@ -14,6 +14,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Run npm audit + npm outdated, categorize findings
 - [ ] Step 2: Research CVEs via web search for critical/high
 - [ ] Step 3: Plan upgrades (breaking vs non-breaking, bundle impact)
@@ -22,6 +23,19 @@ Task Progress:
 - [ ] Step 6: Open PR with upgrade rationale
 ```
 
+## 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: scope (critical/high only vs all), major-version-bump authority, bundle-size budget, deferral policy when no fix is available, and whether to also remove unused deps in the same pass.
+
+## 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.
+
 ## Step 1: Gather Findings
 
 - Run `npm audit` and capture output. Categorize by severity: critical, high, moderate, low.

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

@@ -0,0 +1,164 @@
+---
+id: 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
+tags: [ui, design-system, frontend]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# Design System Detection Workflow
+
+## Quick Start
+
+When an agent is about to author or modify UI, run this skill first to produce a Design System Inventory. Skip = the implementer may duplicate primitives or invent tokens that already exist. Embed the inventory in the implementation plan, PR description, or `.audit-workspace/design-system-inventory.md` for the current task before any UI code is written.
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Scan package.json for design-system signals
+- [ ] Step 2: Locate token source
+- [ ] Step 3: Map component library
+- [ ] Step 4: Identify breakpoint and responsive strategy
+- [ ] Step 5: Record findings (Design System Inventory)
+```
+
+## 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: project root path (monorepo subpackage vs root), canonical token source when multiple exist, primitive directory convention, responsive strategy expected (container-first vs media-first), and verdict authority (reuse vs extend vs create).
+
+## 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.
+
+## Step 1: Scan package.json for design-system signals
+
+Look for the following packages and record both presence and version:
+
+- `@radix-ui/*` or `radix-ui` (headless primitives, WAI-ARIA compliant)
+- `shadcn` reference in `components.json` (source-in-repo registry)
+- `tailwindcss` — note major version (v3 has `tailwind.config.js`; v4 uses `@theme` in CSS)
+- `@chakra-ui/*`, `@mui/material`, `@mui/joy`
+- `bootstrap`, `@headlessui/react`, `@base-ui-components/react`
+
+Detection command:
+
+```
+cat package.json | jq '.dependencies, .devDependencies | keys[]' | grep -iE 'radix|tailwind|chakra|mui|shadcn|headless|base-ui'
+```
+
+Output: a list of design-system packages with semver. If zero matches, record "no UI library detected — confirm with maintainer before scaffolding a new one."
+
+## Step 2: Locate token source
+
+Detection order (first match wins):
+
+1. `tokens.json` at repo root or in `src/`, `design/`, `tokens/` — check for `$value`/`$type` keys; DTCG 2025.10 conformance.
+2. CSS `@theme` block in any `*.css` file (Tailwind v4) — `rg -l '@theme\s*\{' --type css`.
+3. `src/styles/tokens.css` or similar — CSS custom properties at `:root`.
+4. `tailwind.config.{js,ts}` `theme.extend` (Tailwind v3 fallback).
+5. Figma export (`figma.tokens.json`, `tokens-studio.json`).
+
+For each source found, record:
+
+- File path
+- Format (DTCG / `@theme` / CSS custom properties / Tailwind v3 config)
+- Color space (OKLCH / Display-P3 / hex/RGB legacy)
+
+If multiple sources exist, flag the duplication — DTCG mandates a single source of truth. The Design System Inventory must call out which source the implementer should treat as canonical.
+
+## Step 3: Map component library
+
+Check `components.json` (shadcn registry config). Record: `style`, `tailwind.config`, `aliases.components`, `aliases.ui`.
+
+Find component directories:
+
+- `src/components/ui/*` (shadcn convention)
+- `src/components/primitives/*`
+- `app/components/*` (Nuxt / Next.js app router)
+- `packages/ui/*` (monorepo)
+
+Detection command:
+
+```
+fd -t d -E node_modules 'ui|primitives|components' src app packages 2>/dev/null | head -10
+```
+
+List the existing primitives by filename (Button, Input, Dialog, Card, Tooltip, ...). The implementer uses this list in Step 5 to decide reuse vs extend vs create.
+
+## Step 4: Identify breakpoint and responsive strategy
+
+Container queries (preferred for component-scoped responsiveness in 2026):
+
+```
+rg -l '@container' --type css
+```
+
+Media queries (viewport-scoped):
+
+```
+rg -o '@media\s*\([^)]+\)' --type css | sort -u | head -10
+```
+
+Breakpoint tokens: check `--breakpoint-*` custom properties or Tailwind `screens` config.
+
+Record one of: container-query-first / media-query-first / mixed. A component-library project that ships `@container`-based primitives must not be extended with `@media`-only additions.
+
+## Step 5: Record findings
+
+Produce a Design System Inventory block. Embed it in the implementation plan, PR description, or `.audit-workspace/design-system-inventory.md`:
+
+```
+Design System Inventory
+-----------------------
+Component library: <shadcn|Radix|MUI|Chakra|custom|none> (version X)
+Token source: <file path> (<DTCG|@theme|CSS vars|Tailwind config>)
+Color space: <OKLCH|Display-P3|hex>
+Responsive strategy: <container-first|media-first|mixed>
+Existing primitives: Button, Input, Dialog, ...
+Verdict: <reuse|extend|create-with-justification>
+```
+
+## Reuse decision tree
+
+| Situation | Action |
+|-----------|--------|
+| Primitive exists, matches use case | Import + use directly |
+| Primitive exists, doesn't quite fit | Extend via composition; do not fork |
+| No primitive | Author new, add to `ui/` directory, document in PR |
+
+## Error Handling
+
+- **No package.json found**: Project may be a non-JS stack. Record stack (Rails, Phoenix, Go templates) and check for stack-native token sources before declaring "no design system."
+- **Multiple token sources detected**: Flag in the inventory verdict. Implementer must reconcile to a single source before adding tokens; new work blocked until reconciliation owner is named.
+- **shadcn `components.json` present but `src/components/ui/` empty**: Project is shadcn-initialized but no primitives copied yet. Run `npx shadcn@latest add <component> --dry-run` to preview before authoring.
+
+## Definition of Done
+
+- [ ] package.json scanned and library list recorded
+- [ ] Token source located and color space confirmed
+- [ ] Component primitive list captured
+- [ ] Breakpoint strategy classified
+- [ ] Inventory block written to plan / PR / `.audit-workspace/`
+- [ ] Reuse / extend / create verdict explicit per surface
+
+## References
+
+- [W3C Design Tokens Format Module 2025.10](https://www.designtokens.org/tr/drafts/format/) — DTCG canonical format
+- [shadcn CLI docs](https://ui.shadcn.com/docs/cli) — `add`, `init`, `--dry-run`, `--diff`, `--view`
+- [Tailwind v4 theme docs](https://tailwindcss.com/docs/theme) — `@theme` block configuration
+- [Radix Primitives](https://www.radix-ui.com/primitives/docs/overview/introduction) — headless WAI-ARIA primitives
+- [Interop 2026](https://wpt.fyi/interop-2026) — container queries, `:has()`, anchor positioning, View Transitions baseline status
+
+## Cross-references
+
+Rules consumed by this skill:
+
+- `rules/hatch3r-design-system-detection.md` — rule version of this guidance (mandate + scope)
+- `rules/hatch3r-component-conventions.md` — primitive composition + state patterns
+- `rules/hatch3r-theming.md` — token layering (primitive → semantic → component)