hatch3r 1.7.0 → 1.7.5

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

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-sd
+description: "Intuitive sed replacement with literal string patterns. Use when literal-string stream substitution with no regex foot-guns; invoke `sd`. Operates byte-by-byte; safe for fixed-string edits where regex would over-match."
+tags: ["cli-tools", "edit", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: sd
+  bin: sd
+  tier: 1
+  category: edit
+  homepage: https://github.com/chmln/sd
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# sd
+
+Intuitive sed replacement with literal string patterns
+
+## When to Use
+
+Reach for `sd` when the task is in the **edit** 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
+sd 'foo\(' 'bar(' src/lib/util.ts
+```
+Single-file substitution — sd defaults to regex, no escaping for forward slashes or `&`.
+
+```bash
+sd -p 'oldName' 'newName' src/main.ts
+```
+`-p` (preview) prints the diff without writing — safer than running sed and re-reading.
+
+```bash
+sd '\bAPI_KEY\b' 'GH_TOKEN' .env
+```
+Word-boundary anchors catch the symbol without rewriting `API_KEY_BACKUP` or similar.
+
+```bash
+rg --files-with-matches 'oldName' -tts | xargs sd 'oldName' 'newName'
+```
+Two-phase rewrite: `rg` finds candidate files, `sd` applies the substitution per file in parallel.
+
+```bash
+sd -s 'literal string with $special chars' 'replacement' README.md
+```
+`-s` switches to literal-string mode — no regex interpretation, useful when the pattern contains `.`, `*`, `(`.
+
+## Wrong Choice When
+
+- Don't use `sd` for multi-step stream transforms (insert, delete, swap lines in one pass). Reach for `sed -e ... -e ...`, awk, or a real script.
+- Don't use `sd` to refactor identifiers that need type awareness — it cannot tell `count` (the variable) from `count` (the field name). Reach for `ast-grep` (`hatch3r-cli-ast-grep`).
+- Don't reach for `sd` to rewrite extremely large files (>1 GB); it buffers the file in memory. Reach for streaming tools like `sed`.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `sed` (POSIX) | Multi-step transforms, ed-style addressing, or any place sd's flag surface is too thin. |
+| `ast-grep` (`hatch3r-cli-ast-grep`) | Identifier-aware rewrites that must respect language structure. |
+| `perl -pi -e` | Backreferences and lookaround in mature scripts where Perl is already a dependency. |
+| Editor's "rename symbol" (LSP) | Authoritative rename across modules with type information. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v sd
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install sd
+```
+
+Homepage: https://github.com/chmln/sd

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

@@ -0,0 +1,79 @@
+---
+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.
+
+## 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
+npx stagehand init
+```
+Scaffold a Stagehand project with sample TypeScript actions and a `stagehand.config.ts`.
+
+```bash
+npx stagehand run scripts/login.ts
+```
+Execute an AI-driven action script — Stagehand resolves selectors from natural-language intent at runtime.
+
+```bash
+npx stagehand record --selector-mode=ai
+```
+Record an interactive session, capturing AI-resolved selectors for replay.
+
+```bash
+npx stagehand observe https://example.com 'find the login form'
+```
+One-shot observation — returns the structured action(s) without executing them. Useful for dry-run agent loops.
+
+## Wrong Choice When
+
+- **Deterministic E2E test flow with stable selectors:** the AI resolution adds latency and flakiness for selectors you already control. Use `hatch3r-cli-playwright` (tier 2) instead.
+- **High-volume scraping at scale:** Stagehand's per-action LLM round-trip is cost-prohibitive past a few hundred pages — use the Browserbase remote-browser product or raw Playwright with explicit selectors.
+- **Headless CI in air-gapped environments:** Stagehand requires outbound LLM API access for selector resolution; offline environments fail open-loop.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-playwright` (tier 2) | Stable selectors, deterministic CI, no LLM round-trips needed |
+| Browserbase managed browsers | Production scale, session recording, anti-bot evasion |
+| Skyvern / Browser-Use | Workflow-style automation with embedded LLM agents |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v stagehand
+```
+
+Install (mac):
+
+```bash
+# npm
+npm install -g @browserbasehq/stagehand
+```
+
+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-xsv/SKILL.md

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-xsv
+description: "Fast CSV toolkit (slice, search, join, stats). Use when slicing huge CSV documents by row range or column without materialising the dataset; invoke `xsv`. Streams records lazily; works on datasets that exceed available RAM."
+tags: ["cli-tools", "data"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: xsv
+  bin: xsv
+  tier: 2
+  category: data
+  homepage: https://github.com/BurntSushi/xsv
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# xsv
+
+Fast CSV toolkit (slice, search, join, stats)
+
+## When to Use
+
+Reach for `xsv` when the task is in the **data** 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
+xsv stats huge.csv
+```
+Per-column min/max/mean/stddev/cardinality — single streaming pass over the file.
+
+```bash
+xsv select name,email,active records.csv
+```
+Project a subset of columns without rewriting; output stays CSV for downstream tools.
+
+```bash
+xsv sort -s amount records.csv | xsv slice -e 100
+```
+Sort by `amount` then take the first 100 rows — composable pipe; both stages stream.
+
+```bash
+xsv frequency -s status events.csv
+```
+Tabulate value counts for a column; output is itself CSV, parsable by the next step.
+
+```bash
+xsv search -s email '@example\.com$' users.csv
+```
+Regex-filter a column — much cheaper than loading the whole file into a SQL engine.
+
+```bash
+xsv join id orders.csv id customers.csv > joined.csv
+```
+Hash join two CSVs on a common column without spinning up DuckDB.
+
+## Wrong Choice When
+
+- The query needs aggregation across millions of rows or multiple files — DuckDB (Tier 2 sibling) is built for that scan plan.
+- You need a multi-way join with type coercion or window functions — `xsv join` is hash-only and untyped; use DuckDB.
+- The data is JSON or Parquet, not CSV — pipe through `jq`/DuckDB instead of CSV-converting first.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| DuckDB | Aggregations, joins, or non-CSV inputs (Parquet/JSON). |
+| Miller (`mlr`) | Need TSV/JSON-Lines support or per-record transforms in the same tool. |
+| csvkit | Want CSV-to-SQL or CSV-to-JSON conversions out of the box. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v xsv
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install xsv
+```
+
+Homepage: https://github.com/BurntSushi/xsv

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-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

@@ -12,6 +12,7 @@ cache_friendly: true
 
 ```
 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 +21,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.