hatch3r 1.8.0 → 1.9.0

package/dist/content/skills/hatch3r-cli-toolbox/SKILL.md

@@ -0,0 +1,269 @@
+---
+id: hatch3r-cli-toolbox
+description: "Category-indexed reference for 25 specialist CLI tools beyond the always-on five (ripgrep, jq, gh, fd, fzf). Use to pick the right tool for ai-chat, structural-search, sed-style edits, data ops, browser automation, container ops, and more."
+tags: [cli-tools, reference, orchestration, maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# CLI Toolbox
+
+Compact decision reference for 25 specialist CLI tools agents may reach for in addition to the five always-on skills (`hatch3r-cli-ripgrep`, `hatch3r-cli-jq`, `hatch3r-cli-gh`, `hatch3r-cli-fd`, `hatch3r-cli-fzf`).
+
+Each entry below states a single discriminator ("When to use"), one representative recipe, and the better alternative ("Wrong choice when"). Tools are installed via `npx hatch3r cli-tools`; this skill governs *selection*, not installation.
+
+## Category index
+
+| Category | Tools |
+|----------|-------|
+| AI / LLM | `aichat`, `llm`, `mods`, `rtk` |
+| Structural search & rewrite | `ast-grep`, `comby` |
+| Sed-style literal edits | `sd` |
+| Format converters / queriers | `yq`, `taplo` |
+| Data ops (CSV / Parquet / JSON-Lines) | `csvkit`, `duckdb`, `miller`, `qsv` |
+| Containers | `docker`, `podman` |
+| Git TUI / diff viewers | `lazygit`, `delta`, `difftastic`, `bat` |
+| Visualisation / view | `bat`, `overview` |
+| Forges (non-GitHub) | `glab` (GitLab), `az-devops` (Azure DevOps) |
+| Browser automation | `playwright`, `stagehand` |
+| Compression | `zstd` |
+| React state | `rtk` (caveat — see below) |
+
+(Some tools appear in two cells when their best use spans categories.)
+
+## Token-cost discipline
+
+CLI tools return structured stdout that fits in <1 KB for typical queries; equivalent MCP calls regularly exceed 10 KB. Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction. Apply this same discipline across every tool below: prefer `--json`/`--output json`, scope with flags, cap with `--max-count` / `LIMIT`, project with `jq -r`.
+
+---
+
+## AI / LLM
+
+### aichat
+- **When to use:** RAG-enabled multi-provider conversational shell with saved session history; preferred for multi-turn refinement.
+- **Recipe:** `aichat --rag mydocs 'how do we configure auth?'` — query a pre-built local RAG index.
+- **Wrong choice when:** scripted Unix-pipeline transforms — use `mods`; plugin-rich CI workflows — use `llm`.
+
+### llm
+- **When to use:** model-agnostic shell prompting with prompt templates, embeddings, and a plugin ecosystem; preferred for CI batch jobs.
+- **Recipe:** `llm -t code-review -m claude-3-5-sonnet < patch.diff`
+- **Wrong choice when:** deterministic text rewrites — use `sd`/`comby`/`ast-grep`; multi-turn TTY chat — use `aichat`.
+
+### mods
+- **When to use:** Unix-pipeline LLM inference reading Markdown stdin and writing Markdown stdout; preferred for one-shot transforms.
+- **Recipe:** `git diff | mods 'write a conventional-commits message for this diff'`
+- **Wrong choice when:** plugin/template needs — use `llm`; multi-turn session — use `aichat`.
+
+### rtk
+- **When to use:** compressing oversize tool output payloads before they enter an LLM prompt (test-runner output, traces).
+- **Caveat (issue #1282):** rtk's compressed output corrupts downstream consumers when stdout is piped/redirected. Wrap any piped invocation as `rtk proxy <cmd>` — `proxy` is a documented raw-passthrough subcommand. Track: https://github.com/rtk-ai/rtk/issues/1282
+- **Recipe:** `rtk run pytest -x`
+- **Wrong choice when:** piping to `jq`/`grep`/`awk` without `rtk proxy` — use plain shell + `tee`; safety-critical CI — run the test directly.
+
+---
+
+## Structural search & rewrite
+
+### ast-grep
+- **When to use:** Tree-sitter AST pattern matches and rewrites scoped to a single grammar (TS, Python, Rust, Go).
+- **Recipe:** `sg run -p 'await $FN()' -r 'await ($FN()).catch(e => log(e))' --update-all src/`
+- **Wrong choice when:** plain literal text — use `hatch3r-cli-ripgrep`; multi-language SAST rule packs — use `semgrep`.
+
+### comby
+- **When to use:** declarative `:[hole]` pattern match-and-rewrite spanning mixed-language repositories — single template, 30+ grammars.
+- **Recipe:** `comby 'console.log(:[arg])' 'logger.info(:[arg])' -i src/`
+- **Wrong choice when:** language-precise type-aware refactor — use `ast-grep`; plain text — use `sd`.
+
+---
+
+## Sed-style literal edits
+
+### sd
+- **When to use:** literal-string stream substitution with no regex foot-guns — defaults to regex but `-s` switches to literal mode.
+- **Recipe:** `rg --files-with-matches 'oldName' -tts | xargs sd 'oldName' 'newName'`
+- **Wrong choice when:** identifier-aware rename — use `ast-grep`; multi-step transforms — use `sed -e`.
+
+---
+
+## Format converters & queriers
+
+### yq
+- **When to use:** editing Kubernetes manifests, Helm values, or GitHub-Actions workflows in place — preserves comments/anchors with `-P`.
+- **Recipe:** `yq -i '.version = "1.7.5"' .hatch3r/hatch.json`
+- **Wrong choice when:** JSON input — use `hatch3r-cli-jq`; TOML — use `taplo`.
+
+### taplo
+- **When to use:** formatting, linting, and querying TOML (`pyproject.toml`, `Cargo.toml`); bundled schemas for both.
+- **Recipe:** `taplo get -f Cargo.toml package.version`
+- **Wrong choice when:** YAML/JSON — use `yq`/`jq`; cross-format conversion — use `dasel`.
+
+---
+
+## Data ops (CSV / Parquet / JSON-Lines)
+
+### csvkit
+- **When to use:** Python-powered CSV toolkit covering `csvlook`, `csvsql`, `csvjoin`, `csvstat` — best for ad-hoc EDA and SQL-over-CSV.
+- **Recipe:** `csvsql --query 'SELECT name FROM data WHERE active = 1' data.csv`
+- **Wrong choice when:** files >1M rows — use `duckdb`; single-column slice — use `qsv`.
+
+### duckdb
+- **When to use:** ad-hoc analytical SQL over local Parquet, CSV, JSON; streams reads so memory stays bounded.
+- **Recipe:** `duckdb -c "SELECT count(*) FROM 'data/*.parquet'"`
+- **Wrong choice when:** <10k rows and column slice only — use `qsv`; transactional writes — use SQLite/Postgres.
+
+### miller
+- **When to use:** `awk`-like record processing across CSV/TSV/JSON-Lines streams with the `put`/`filter` DSL.
+- **Recipe:** `mlr --icsv --ojson put '$tax = $amount * 0.07' transactions.csv`
+- **Wrong choice when:** multi-GB analytical joins — use `duckdb`; trivial slicing — use `qsv`.
+
+### qsv
+- **When to use:** fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained `xsv` successor (`BurntSushi/xsv` archived 2025-04-24, `jqnatividad/qsv` is the active fork).
+- **Recipe:** `qsv search -s email '@example\.com$' users.csv`
+- **Wrong choice when:** Parquet/JSON or window functions — use `duckdb`; per-record DSL transforms — use `miller`.
+
+---
+
+## Containers
+
+### docker
+- **When to use:** image build, container run, exec inspection, registry push against a running Docker Engine daemon.
+- **Recipe:** `docker run --rm -v "$PWD":/app -w /app node:22 npm test`
+- **Wrong choice when:** rootless / daemonless required — use `podman`; Kubernetes deploy — use `kubectl`/`helm`.
+
+### podman
+- **When to use:** rootless OCI-image execution without a privileged daemon — ideal for hardened CI workers.
+- **Recipe:** `podman run --rm -v "$PWD:/app:Z" -w /app node:22 npm test` (`:Z` triggers SELinux relabel on Fedora/RHEL).
+- **Wrong choice when:** Swarm / Docker-Desktop integration — use `docker`; tools that hard-code `/var/run/docker.sock` (unless `podman system service` is running).
+
+---
+
+## Git TUI / diff viewers
+
+### lazygit
+- **When to use:** keyboard-driven terminal UI for staging, rebasing, branch switching — humans only; agents should call plain `git`.
+- **Recipe:** `lazygit -p path/to/repo` (TTY required; hangs in non-TTY).
+- **Wrong choice when:** autonomous agent or CI — use plain `git status`/`add`/`commit` for parseable stdout.
+
+### delta
+- **When to use:** viewing unified git diffs with side-by-side syntax-coloured hunks (ANSI pager).
+- **Recipe:** `git config --global core.pager delta` then `git config --global interactive.diffFilter 'delta --color-only'`.
+- **Wrong choice when:** scripted consumers — ANSI breaks parsers; semantic refactor review — use `difftastic`.
+
+### difftastic
+- **When to use:** syntax-aware diffing that reports semantic edits (rename of block does not show as wholesale rewrite).
+- **Recipe:** `git -c diff.external=difft diff HEAD~1 HEAD`
+- **Wrong choice when:** stable POSIX diff output for scripts — use `diff -u`; quick unified-diff pager — use `delta`.
+
+### bat
+- **When to use:** scrolling one source file with syntax colours, line numbers, git modification markers.
+- **Recipe:** `bat --plain --line-range 50:100 src/adapters/cursor.ts`
+- **Wrong choice when:** binary files (use `xxd | bat --language=hex`); strict POSIX pipelines (use `cat`); two-file compare (use `delta`).
+
+---
+
+## Visualisation
+
+### overview
+- **When to use:** legacy umbrella catalog of all CLI tools — this `hatch3r-cli-toolbox` skill replaces it. Retained as a category cell for back-references in user content; if you see hatch3r-cli-overview mentioned anywhere (un-backticked here to keep the cross-reference scanner clean), treat it as a synonym for this toolbox.
+
+---
+
+## Forges (non-GitHub)
+
+### glab
+- **When to use:** GitLab merge-request review, pipeline retries, issue triage with native PAT/OAuth auth.
+- **Recipe:** `glab mr list --assignee=@me --output json | jq '.[] | {iid, title, web_url}'`
+- **Wrong choice when:** GitHub-hosted — use `hatch3r-cli-gh`; Azure Repos — use `az-devops`.
+
+### az-devops
+- **When to use:** Azure DevOps work-item edits, repo pushes, pipeline runs via the `az` CLI extension.
+- **Recipe:** `az repos pr list --status active --query '[].pullRequestId' --output tsv`
+- **Wrong choice when:** GitHub — use `hatch3r-cli-gh`; GitLab — use `glab`.
+
+---
+
+## Browser automation
+
+### playwright
+- **When to use:** end-to-end browser test execution capturing screenshots and traces; deterministic locators, multi-browser.
+- **Recipe:** `npx playwright test --grep '@smoke' --workers=1 --reporter=line`
+- **Wrong choice when:** API-only system — use `curl` + `jq`; agent-driven natural-language browsing — use `stagehand`.
+
+### stagehand
+- **When to use:** natural-language browser steering with on-the-fly DOM reasoning; v3 (2025-10-29) talks Chrome DevTools Protocol directly. Drivers (`playwright-core`, `puppeteer-core`, `patchright-core`) are peer deps — install only the one you need.
+- **Recipe:** `npx create-browser-app` scaffolds a v3 project; runtime: `stagehand.act("click the login button")`.
+- **Wrong choice when:** high-volume scraping — use Browserbase managed browsers or v3 action cache; air-gapped CI — pre-record then replay; existing stable Playwright suite — keep it.
+
+---
+
+## Compression
+
+### zstd
+- **When to use:** high-ratio compression with single-digit-millisecond decompress speeds — cold-storage payloads, CI artifact upload.
+- **Recipe:** `tar --zstd -cf bundle.tar.zst dist/ governance/`
+- **Wrong choice when:** distribution where every byte counts and decompress speed is irrelevant — use `xz -9e`; legacy Windows recipients — use `zip`; already-compressed payloads — skip compression.
+
+---
+
+## Detection & install
+
+Verify each tool with `command -v <bin>`. Install commands:
+
+| Tool | mac (`brew`) | linux (`apt` / `pip` / other) |
+|------|--------------|--------------------------------|
+| `aichat` | `brew install aichat` | `cargo install aichat` |
+| `ast-grep` | `brew install ast-grep` | `cargo install ast-grep --locked` |
+| `az-devops` | `brew install azure-cli && az extension add --name azure-devops` | `apt install azure-cli && az extension add --name azure-devops` |
+| `bat` | `brew install bat` | `apt install bat` (binary may be `batcat`) |
+| `comby` | `brew install comby` | `bash <(curl -sL get.comby.dev)` |
+| `csvkit` | `pipx install csvkit` | `pipx install csvkit` |
+| `delta` | `brew install git-delta` | `apt install git-delta` (or download release) |
+| `difftastic` | `brew install difftastic` | `cargo install difftastic` |
+| `docker` | `brew install --cask docker` | `apt install docker.io` |
+| `duckdb` | `brew install duckdb` | download from https://duckdb.org/ |
+| `glab` | `brew install glab` | `apt install glab` (or GitLab release) |
+| `lazygit` | `brew install lazygit` | `apt install lazygit` |
+| `llm` | `brew install llm` | `pipx install llm` |
+| `miller` | `brew install miller` | `apt install miller` |
+| `mods` | `brew install charmbracelet/tap/mods` | `apt install mods` (Charm repo) |
+| `playwright` | `npm install -D @playwright/test && npx playwright install` | same |
+| `podman` | `brew install podman` | `apt install podman` |
+| `qsv` | `brew install qsv` | `cargo install qsv` |
+| `rtk` | `brew install rtk-ai/tap/rtk` | check upstream release |
+| `sd` | `brew install sd` | `cargo install sd` |
+| `stagehand` | `npm install -g @browserbasehq/stagehand` | same |
+| `taplo` | `brew install taplo` | `cargo install taplo-cli --locked` |
+| `yq` | `brew install yq` | `apt install yq` (verify mikefarah Go build, not python wrapper) |
+| `zstd` | `brew install zstd` | `apt install zstd` |
+
+## References
+
+This skill synthesizes 25 pre-existing in-repo per-tool skills (collapsed in v1.9.0 per the Decision #14 toolbox criterion in `.claude/rules/content-authoring.md`). The original source files (now removed) lived at the following paths (IDs intentionally un-backticked here so the cross-reference scanner does not treat removed standalone skills as broken canonical IDs):
+
+- skills/hatch3r-cli-aichat/SKILL.md
+- skills/hatch3r-cli-ast-grep/SKILL.md
+- skills/hatch3r-cli-az-devops/SKILL.md
+- skills/hatch3r-cli-bat/SKILL.md
+- skills/hatch3r-cli-comby/SKILL.md
+- skills/hatch3r-cli-csvkit/SKILL.md
+- skills/hatch3r-cli-delta/SKILL.md
+- skills/hatch3r-cli-difftastic/SKILL.md
+- skills/hatch3r-cli-docker/SKILL.md
+- skills/hatch3r-cli-duckdb/SKILL.md
+- skills/hatch3r-cli-glab/SKILL.md
+- skills/hatch3r-cli-lazygit/SKILL.md
+- skills/hatch3r-cli-llm/SKILL.md
+- skills/hatch3r-cli-miller/SKILL.md
+- skills/hatch3r-cli-mods/SKILL.md
+- skills/hatch3r-cli-overview/SKILL.md
+- skills/hatch3r-cli-playwright/SKILL.md
+- skills/hatch3r-cli-podman/SKILL.md
+- skills/hatch3r-cli-qsv/SKILL.md
+- skills/hatch3r-cli-rtk/SKILL.md
+- skills/hatch3r-cli-sd/SKILL.md
+- skills/hatch3r-cli-stagehand/SKILL.md
+- skills/hatch3r-cli-taplo/SKILL.md
+- skills/hatch3r-cli-yq/SKILL.md
+- skills/hatch3r-cli-zstd/SKILL.md
+
+Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the rejected merge alternative (keep every tool as a standalone skill) was rejected because the 25 collapsed entries averaged 75 lines each (1.9k lines total) with >70% structural duplication of the same "When to Use / Token Cost / Recipes / Wrong Choice / Alternatives / Install" frame — collapse into a single category-indexed reference cuts the surface to ~250 lines while preserving the discriminator that picks one tool over another.

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

@@ -42,6 +42,19 @@ Run through the self-assessment checklist:
 4. **File currency**: List files you've modified — when did you last read each one?
 5. **Scope check**: Compare your current work to the original issue description.
 
+### Model-Aware Threshold Profiles
+
+Default thresholds assume a large-context model. When the active model is known, apply the matching profile to adjust thresholds:
+
+| Model Tier | Context Window | Token Warning | Turn Limit | File Staleness |
+|-----------|---------------|---------------|------------|----------------|
+| Small (< 32K) | ~32K tokens | > 60% of window | > 15 turns | > 10 turns |
+| Medium (32K--128K) | ~128K tokens | > 70% of window | > 25 turns | > 15 turns |
+| Large (128K--200K) | ~200K tokens | > 80% of window | > 30 turns | > 20 turns |
+| Extended (> 200K) | 200K+ tokens | > 85% of window | > 40 turns | > 25 turns |
+
+Profile resolution: read `models` in `.hatch3r/hatch.json`; default to **Large** if unset. A `contextHealth` section in `hatch.json` with explicit thresholds overrides the profile. Log the active profile at the start of each check: `"Context health using <tier> profile (<window_size> tokens)"`.
+
 ## Step 2: Identify Degradation
 
 | Check | Healthy | Degraded |
@@ -71,7 +84,7 @@ Run through the self-assessment checklist:
 ### If 5 checks degraded (Red): Checkpoint and Stop
 1. Save all progress (files changed, tests written)
 2. Document remaining work and blockers
-3. Post progress on the issue/work item (GitHub Issue, ADO Work Item, or GitLab Issue — check `platform` in `.agents/hatch.json`)
+3. Post progress on the issue/work item (GitHub Issue, ADO Work Item, or GitLab Issue — check `platform` in `.hatch3r/hatch.json`)
 4. Recommend fresh conversation
 
 ## Step 4: Verify Improvement
@@ -108,7 +121,10 @@ Context poisoning is more dangerous than missing context because it leads to con
 - [ ] Appropriate corrective action taken
 - [ ] Health verified at Green or Yellow after correction
 
+## Board Pickup Integration
+
+When `board-pickup` operates in auto-advance mode, context health is checked between issues. Orange completes the current issue then a fresh agent handles the next; Red mid-issue marks the issue PARTIAL and moves it back to Ready.
+
 ## Related Skills & Agents
 
-- **Command**: `hatch3r-context-health` -- full monitoring protocol with integration points
 - **Command**: `hatch3r-board-pickup` -- auto-advance mode uses context health for session management

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

@@ -53,7 +53,34 @@ 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 the model tier rates from the `hatch3r-cost-tracking` command reference.
+Calculate estimated cost using these model tier rates (reference rates — update based on actual provider pricing):
+
+| 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 |
+
+### Default Budgets
+
+When `hatch.json` has no `costTracking` section, apply these defaults (report-only — no hard stop unless `hardStop: true`):
+
+| Budget Type | Default |
+|------------|---------|
+| `sessionBudget` | $10.00 |
+| `issueBudget` | $5.00 |
+| `epicBudget` | $25.00 |
+| `warningThresholds` | [0.5, 0.75, 0.9] |
+| `hardStop` | false |
+
+### Enforcement
+
+| Threshold | Action |
+|-----------|--------|
+| 50% | Log warning, continue |
+| 75% | Alert user, suggest optimization |
+| 90% | Strong warning, recommend delegation or checkpoint |
+| 100% | Stop (if `hardStop: true`) or alert and continue |
 
 ## Step 3: Identify Optimizations
 
@@ -67,11 +94,37 @@ Review usage patterns for savings:
 
 ## Step 4: Generate Report
 
-Produce a cost report using the output format from the `hatch3r-cost-tracking` command. Include:
-- Total estimated tokens (input + output)
-- Estimated cost at the current model tier
-- Budget status (if configured)
-- Top optimization opportunities
+Produce a cost report in this format:
+
+```
+## Cost Report: {scope}
+
+**Period:** {session/issue/sprint}
+
+**Token Usage:**
+- Input tokens: ~{n}
+- Output tokens: ~{n}
+- Total tokens: ~{n}
+
+**Estimated Cost:** ${amount}
+
+**Budget Status:** {amount} / {budget} ({percentage}%)
+
+**Breakdown:**
+
+| Phase | Tokens | Cost | % of Total |
+|-------|--------|------|-----------|
+| Planning | ~{n} | ${x} | {%} |
+| Implementation | ~{n} | ${x} | {%} |
+| Testing | ~{n} | ${x} | {%} |
+| Review | ~{n} | ${x} | {%} |
+| Sub-agents | ~{n} | ${x} | {%} |
+
+**Optimization Opportunities:**
+- {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.
 
 ## Error Handling
 
@@ -88,5 +141,4 @@ Produce a cost report using the output format from the `hatch3r-cost-tracking` c
 
 ## Related Skills & Agents
 
-- **Command**: `hatch3r-cost-tracking` — full cost tracking protocol with guardrails and budget enforcement
 - **Skill**: `hatch3r-context-health` — context health monitoring complements cost tracking for session management

package/{skills → dist/content/skills}/hatch3r-customize/SKILL.md

@@ -5,11 +5,10 @@ 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.
+> **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.
 
 ## Quick Start
 
@@ -43,10 +42,10 @@ This skill handles customization for all artifact types. The `type` parameter de
 
 | Type | Source Directory | Customization Directory | YAML Fields |
 |------|-----------------|------------------------|-------------|
-| `agent` | `.agents/agents/` | `.hatch3r/agents/` | `model`, `description`, `enabled` |
-| `command` | `.agents/commands/` | `.hatch3r/commands/` | `description`, `enabled` |
-| `rule` | `.agents/rules/` | `.hatch3r/rules/` | `scope`, `description`, `enabled` |
-| `skill` | `.agents/skills/` | `.hatch3r/skills/` | `description`, `enabled` |
+| `agent` | `agents/` | `.hatch3r/agents/` | `model`, `description`, `enabled` |
+| `command` | `commands/` | `.hatch3r/commands/` | `description`, `enabled` |
+| `rule` | `rules/` | `.hatch3r/rules/` | `scope`, `description`, `enabled` |
+| `skill` | `skills/` | `.hatch3r/skills/` | `description`, `enabled` |
 
 **Protected agents:** Some agents have `protected: true` in their canonical frontmatter. For these agents, `description` and `enabled` overrides are ignored — only `model` and markdown instructions can be customized.
 

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

@@ -1,7 +1,7 @@
 ---
 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.
-tags: [maintenance, security]
+tags: [maintenance, floor:security]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -48,7 +48,7 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 For critical and high vulnerabilities:
 
 - Use **web search** to look up each CVE: exploitability, affected versions, fix version, workarounds.
-- Check npm advisories and platform-specific security tools for official guidance (check `platform` in `.agents/hatch.json`):
+- Check npm advisories and platform-specific security tools for official guidance (check `platform` in `.hatch3r/hatch.json`):
   - **GitHub:** GitHub Security Advisories (`gh api /repos/{owner}/{repo}/security-advisories`)
   - **Azure DevOps:** Azure Artifacts security scanning and Azure Boards advisory tracking
   - **GitLab:** GitLab Dependency Scanning (Security & Compliance → Vulnerability Report)
@@ -99,6 +99,10 @@ Use the project's PR template. Include:
 - **Major version upgrade breaks tests**: Roll back the upgrade, document the breaking changes encountered, and create a dedicated migration issue with the specific test failures and required code changes.
 - **Lockfile conflicts after upgrade**: Regenerate the lockfile from scratch (`rm package-lock.json && npm install`), verify all tests pass, and commit the clean lockfile.
 
+## Tracking Issues for Deferred Items
+
+For CVEs or outdated packages not addressed in this session, create a tracking issue on the project's platform (GitHub Issues, ADO Work Item, or GitLab Issue per `platform` in `.hatch3r/hatch.json`). Use severity-based priority labels: Critical/High → `priority:p0`/`priority:p1`; Medium/Low → `priority:p2`; Major outdated → `priority:p2`; Minor/patch → `priority:p3`. Include package name, current version, target version, severity, CVE ID (if applicable), and migration notes. Never close out a critical/high CVE without either a fix or a tracking issue.
+
 ## Definition of Done
 
 - [ ] No critical or high CVEs remaining

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

@@ -2,7 +2,7 @@
 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]
+tags: [implementation, floor:ui-ux, ui, design-system, frontend]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-feature/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-feature
 description: End-to-end feature implementation workflow. Covers data model, domain logic, API, and UI as a vertical slice. Use when implementing new features or working on feature request issues.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-gh-agentic-workflows/SKILL.md

@@ -1,14 +1,14 @@
 ---
 id: hatch3r-gh-agentic-workflows
 description: Set up CI/CD agentic workflows for continuous AI-powered repository automation (GitHub Actions, Azure Pipelines, GitLab CI)
-tags: [devops, team]
+tags: [devops, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 ---
 # CI/CD Agentic Workflows Integration
 
-> **Platform detection:** Check `platform` in `.agents/hatch.json` to determine which CI/CD system to use. Defaults to `"github"`.
+> **Platform detection:** Check `platform` in `.hatch3r/hatch.json` to determine which CI/CD system to use. Defaults to `"github"`.
 
 This skill guides setup for AI-powered CI/CD automation in hatch3r-managed projects. The core SKILL covers GitHub Actions (the default); non-GitHub platforms load on demand from `references/`.
 
@@ -33,7 +33,7 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 | Azure DevOps Pipelines | `references/azure-devops.md` |
 | GitLab CI/CD | `references/gitlab-ci.md` |
 
-Load only the references file that matches `platform` in `.agents/hatch.json`. Do not eagerly load all three.
+Load only the references file that matches `platform` in `.hatch3r/hatch.json`. Do not eagerly load all three.
 
 ## Overview (GitHub Actions)
 
@@ -100,7 +100,7 @@ permissions:
 ---
 ```
 
-Replace `{defaultBranch}` with `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+Replace `{defaultBranch}` with `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 After a PR is merged, check if documentation needs updating and open a follow-up PR.
 

package/{skills → dist/content/skills}/hatch3r-gh-agentic-workflows/references/azure-devops.md

@@ -1,6 +1,6 @@
 # Azure DevOps Pipelines — Agentic Workflow Patterns
 
-Loaded on demand when `platform: azure-devops` in `.agents/hatch.json` or when user is setting up Azure DevOps CI.
+Loaded on demand when `platform: azure-devops` in `.hatch3r/hatch.json` or when user is setting up Azure DevOps CI.
 
 Azure Pipelines use YAML files in the repo (typically `azure-pipelines.yml` or files under `.azuredevops/`) to define CI/CD jobs. Use the `az pipelines` CLI for management and monitoring.
 
@@ -24,7 +24,7 @@ steps:
     displayName: 'AI-assisted test improvement'
 ```
 
-Replace `{defaultBranch}` with `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+Replace `{defaultBranch}` with `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 ## 2. Continuous Triage (ADO)
 

package/{skills → dist/content/skills}/hatch3r-gh-agentic-workflows/references/gitlab-ci.md

@@ -1,6 +1,6 @@
 # GitLab CI/CD — Agentic Workflow Patterns
 
-Loaded on demand when `platform: gitlab` in `.agents/hatch.json` or when user is setting up GitLab CI.
+Loaded on demand when `platform: gitlab` in `.hatch3r/hatch.json` or when user is setting up GitLab CI.
 
 GitLab CI uses `.gitlab-ci.yml` at the repo root to define pipelines. Use the `glab ci` CLI for management and monitoring.
 

package/{skills → dist/content/skills}/hatch3r-handoff-prepare/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-handoff-prepare
-description: Capture mid-work session state into a canonical handoff document at .agents/handoffs/active/. Use when ending a session mid-work, switching tools, or after context-health Orange/Red.
-tags: [core, maintenance]
+description: Capture mid-work session state into a canonical handoff document at .hatch3r/handoffs/active/. Use when ending a session mid-work, switching tools, or after context-health Orange/Red.
+tags: [orchestration, maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -17,7 +17,7 @@ Task Progress:
 - [ ] Step 1: Gather session state (git_ref, files, tests, work_item)
 - [ ] Step 2: Compose body (8 required sections + user-tier markers)
 - [ ] Step 3: Validate against readiness rule
-- [ ] Step 4: Write atomically to .agents/handoffs/active/<id>.md
+- [ ] Step 4: Write atomically to .hatch3r/handoffs/active/<id>.md
 - [ ] Step 5: Confirm with path, summary, and Iteration Summary
 ```
 
@@ -36,13 +36,13 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 
 ## Step 1: Gather State
 
-Collect the inputs required by the handoff schema (see `.agents/handoffs/README.md` for the canonical schema):
+Collect the inputs required by the handoff schema (see `.hatch3r/handoffs/README.md` for the canonical schema):
 
 1. **git_ref** — run `git branch --show-current` and `git rev-parse --short HEAD`. Compose as `branch@sha7` (e.g., `feat/cache-refactor@a3f2c1d`).
 2. **branch** — same value as the branch component above.
 3. **Modified files** — run `git status --porcelain`; pair each path with its change type for the `File Manifest` table.
 4. **Build & Test Status** — from session memory, recover the most recent results of `npm test`, `npm run lint`, and `npx tsc --noEmit`. If none ran this session, re-run them.
-5. **work_item (optional)** — read `platform` from `.agents/hatch.json` (`github | azure-devops | gitlab`) plus active issue from the current branch name or recent board state. Compose as `gh:owner/repo#42`, `ado:org/project:work-item/123`, or `gl:owner/repo!42`.
+5. **work_item (optional)** — read `platform` from `.hatch3r/hatch.json` (`github | azure-devops | gitlab`) plus active issue from the current branch name or recent board state. Compose as `gh:owner/repo#42`, `ado:org/project:work-item/123`, or `gl:owner/repo!42`.
 6. **compaction_count (optional)** — increment from a parent handoff's value if resuming; else omit.
 7. **target_agent** — explicit named agent (`hatch3r-implementer`, `hatch3r-reviewer`, etc.) or `any` only when the user opts in.
 
@@ -108,7 +108,7 @@ A failed Required criterion is `errors[]` — refuse the write. A failed Recomme
 
 1. Generate the id: `<YYYY-MM-DD>_T<HHmm>_<5hex>_<kebab-slug>` (e.g., `2026-05-17_T1430_a3f2c_issue-42-cache-refactor`). The 5-char hex segment is a random suffix that prevents accidental same-id overwrites within the same minute.
 2. Call `writeHandoff(agentsDir, handoff)` from `src/content/handoffs/index.ts`. The function performs an atomic temp+rename per the `safeWrite.ts` pattern under `HATCH3R_LOCK=1`.
-3. The handoff lands at `.agents/handoffs/active/<id>.md`.
+3. The handoff lands at `.hatch3r/handoffs/active/<id>.md`.
 
 **Status default:** `in-progress`. Use `open` if the work has not been started, or `handed-off` if explicitly transferring to another developer or agent.
 
@@ -119,7 +119,7 @@ A failed Required criterion is `errors[]` — refuse the write. A failed Recomme
 Report:
 
 ```
-Handoff written: .agents/handoffs/active/<id>.md
+Handoff written: .hatch3r/handoffs/active/<id>.md
 Summary: {summary}
 Warnings: {list or "none"}
 ```
@@ -130,7 +130,7 @@ Then emit the canonical Iteration Summary block per `rules/hatch3r-iteration-sum
 
 - **Always:** validate before write (readiness rule criteria 1-7), compute integrity hash, wrap body in user-tier markers, default `target_agent` to an explicit value, preserve `git_ref` accuracy at write time.
 - **Ask first:** before overwriting an existing active handoff for the same `work_item` (only allowed when existing is older than 24 hours), before setting `target_agent: any`.
-- **Never:** include full conversation transcripts, include secrets/credentials/tokens, write directly to `.agents/handoffs/archived/`, paraphrase content from the Iteration Summary block.
+- **Never:** include full conversation transcripts, include secrets/credentials/tokens, write directly to `.hatch3r/handoffs/archived/`, paraphrase content from the Iteration Summary block.
 
 ## Error Handling
 
@@ -148,7 +148,7 @@ Then emit the canonical Iteration Summary block per `rules/hatch3r-iteration-sum
 - [ ] Step 1 state gathered (git_ref, files, tests, optional work_item)
 - [ ] Step 2 body composed with 8 sections and user-tier markers
 - [ ] Step 3 readiness rule passed (criteria 1-7) with warnings surfaced
-- [ ] Step 4 file written to `.agents/handoffs/active/<id>.md`
+- [ ] Step 4 file written to `.hatch3r/handoffs/active/<id>.md`
 - [ ] Step 5 confirmation reported + Iteration Summary block emitted
 
 ## Related Skills & Agents

package/{skills → dist/content/skills}/hatch3r-handoff-resume/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-handoff-resume
-description: Load and resume a handoff document from .agents/handoffs/active/. Validates schema, integrity, expiry, and git_ref drift before surfacing content as user-tier context.
-tags: [core, maintenance]
+description: Load and resume a handoff document from .hatch3r/handoffs/active/. Validates schema, integrity, expiry, and git_ref drift before surfacing content as user-tier context.
+tags: [orchestration, maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-incident-response/SKILL.md

@@ -43,7 +43,7 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 | P2       | Partial degradation, limited impact         | Single flow broken, slow performance       |
 | P3       | Minor issue, workaround available            | Cosmetic bug, edge case                     |
 
-- Check for related issues or prior incidents using the platform tools (check `platform` in `.agents/hatch.json`):
+- Check for related issues or prior incidents using the platform tools (check `platform` in `.hatch3r/hatch.json`):
   - **GitHub:** Use **GitHub MCP** (`issue_read`, `search_issues`) or `gh issue list --search "..."`
   - **Azure DevOps:** `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Title] CONTAINS '...'"` or `az boards work-item show --id N`
   - **GitLab:** `glab issue list --search "..."` or `glab issue view N`
@@ -86,7 +86,7 @@ Store in project incident docs or as an issue/wiki page on the platform. Follow
 
 ## Step 6: Follow-Up Issues
 
-- Create follow-up issues/work items for each action item from the post-mortem (check `platform` in `.agents/hatch.json`):
+- Create follow-up issues/work items for each action item from the post-mortem (check `platform` in `.hatch3r/hatch.json`):
   - **GitHub:** `gh issue create --title "..." --body "..." --label "incident-follow-up"` (or use **GitHub MCP** `issue_create`)
   - **Azure DevOps:** `az boards work-item create --type "Bug" --title "..." --description "..." --fields "System.Tags=incident-follow-up"`
   - **GitLab:** `glab issue create --title "..." --description "..." --label "incident-follow-up"`