hatch3r 1.7.1 → 1.8.0

package/skills/hatch3r-agent-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
 ---
 # Agent Customization
 
 > **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: agent`.
 
 For agent-specific reference (model resolution, protected agents, YAML schema), see the `hatch3r-agent-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-agent-customize` or referenced the id `hatch3r-agent-customize` (per CHANGELOG.md, `website/docs/reference/configuration.md:325`, `docs/model-selection.md:158`) 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-ai-feature/SKILL.md

@@ -0,0 +1,136 @@
+---
+id: hatch3r-ai-feature
+type: skill
+description: Eval-driven development workflow for shipping AI features — write eval before prompt, measure, iterate, ship with caching + cost telemetry + model fallback + hallucination SLI
+tags: [implementation, ai]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# AI Feature Workflow (Eval-Driven)
+
+## Quick Start
+
+Run this skill before shipping any LLM-driven feature. It defines the canonical eval-driven loop (write eval, write prompt, measure, iterate) and the production-readiness gates. Skipping any of the 9 steps = the feature is not done.
+
+This skill is the implementation counterpart to `rules/hatch3r-ai-evals.md` (backend governance) and `rules/hatch3r-ai-ux-patterns.md` (UI governance). The rules define the bar; this skill defines the route to clearing the bar.
+
+## 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: task class (classification vs open-ended vs RAG vs agentic), model pin (Sonnet vs Opus vs Haiku), eval threshold values, budget per request (cost cap), and fallback policy (graceful degrade vs hard fail).
+
+## 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: Define the task and success criteria
+
+- Write down what "right" looks like in one paragraph — the user input class, the expected output shape, the failure modes you want to catch.
+- Hand-author 20+ golden examples in `evals/<feature>/golden.jsonl` with `input` + `expected_output` (or a graded rubric when the task is open-ended).
+- Save the threshold per metric in `evals/<feature>/thresholds.json`. Without an explicit threshold, "passing the eval" is undefined.
+- Cross-reference `rules/hatch3r-ai-evals.md` Golden Dataset Versioning for filename and refresh policy.
+- Source diversity matters more than count beyond 20 — include adversarial inputs, edge cases from prior incidents, and at least 3 examples per known input class.
+- Label every example with the input class so per-class accuracy is computable in Step 4.
+
+## Step 2: Pick eval tool and metric
+
+Match the task class to the tool:
+
+- Classification → promptfoo with exact-match assertions.
+- Open-ended generation → DeepEval or braintrust with LLM-as-judge + a 50-example human-labeled calibration set.
+- Retrieval/RAG → RAGAS (context_precision, context_recall, faithfulness, answer_relevance).
+- Tool-use / agentic → Inspect or BFCL-style harness.
+- Safety/red-team → Garak or PyRIT scheduled weekly.
+
+Pin the choice in `evals/README.md` so the next agent run picks the same tool.
+
+## Step 3: Write the prompt
+
+- Author the prompt at `prompts/<feature>/v1.md` with frontmatter `{ id, version: 1, model_pinned, eval_set }`.
+- Commit; record SHA-256 hash in `evals/<feature>/thresholds.json`.
+- If the system prompt + tool definitions + RAG context exceed 1024 tokens, apply Anthropic `cache_control` breakpoints (or rely on OpenAI's automatic prefix cache for ≥1024-token deterministic prefixes). Longest-TTL block first.
+
+## Step 4: Run eval; iterate prompt
+
+- Run `npx promptfoo eval` (or the chosen tool's CLI) against the golden set.
+- Read the per-metric report. If below threshold, modify the prompt, bump to `v2.md`, re-hash, re-run.
+- Treat each prompt revision like a code commit — small, named, testable.
+- Stop iterating when every metric clears its threshold in `thresholds.json` and the pairwise win-rate vs the prior version is >=55%.
+- Capture the eval report artifact in CI so the PR reviewer can read per-case pass/fail without re-running the suite locally.
+- If iteration count exceeds 10 versions without convergence, escalate — the task may need decomposition (one sub-prompt per input class) or a retrieval-grounded approach.
+
+## Step 5: Wire production telemetry
+
+- Per-request log line emits `model`, `tokens_in`, `tokens_out`, `cache_hit`, `cached_tokens`, `cost_usd`, `latency_ms`, `prompt_version`, `prompt_hash`, `cost_center`.
+- Per-request OpenTelemetry span follows the OTel GenAI semantic conventions (`gen_ai.*` attributes).
+- Aggregate dashboards: cost-per-request, hallucination_rate, citation_precision, refusal_rate, cache_hit_ratio.
+- Cross-reference `skills/hatch3r-observability-verify` for the per-feature dashboard checklist.
+
+## Step 6: Wire fallback chain
+
+- Primary model (e.g. Sonnet 4.7) → secondary (cheaper/faster, e.g. Haiku 4.5) → static fallback (cached or canned).
+- Wrap in circuit-breaker + retry-with-decorrelated-jitter — cross-reference `rules/hatch3r-resilience-patterns.md` (Slice 8) for the primitives.
+- Run the eval suite against the secondary path too — a silent quality cliff between primary and secondary is a regression.
+- Static fallback text names the failure mode in user-readable language ("AI is briefly unavailable — retry in a minute") rather than dumping a stack trace into the UI.
+
+## Step 7: Add CI gate
+
+- Eval runs on every PR that touches `**/prompts/**`, `**/rag/**`, `**/ai/**`, `**/llm/**`.
+- PR blocks when any metric drops below the threshold in `evals/<feature>/thresholds.json`.
+- Model-version upgrade (Sonnet to Opus, 4.6 to 4.7) triggers a full eval with a 5% accuracy budget; cross over 5% requires a named-reviewer sign-off + 24-hour canary at 5% traffic.
+
+## Step 8: Production verification
+
+First 24 hours after deploy, monitor:
+
+- `ai.hallucination_rate` — SLO <5% on golden set; alert if 7-day rolling rate >5%.
+- `ai.refusal_rate` — track false-positive refusal rate separately.
+- `ai.cost_per_request_usd` — p50/p95/p99 vs feature budget; alert at 50%/75%/90% of monthly budget.
+- `ai.latency_ms` — first-token-latency p95 + total-response-latency p99.
+- `ai.cache_hit_ratio` — should match the dev-environment baseline within 10%; a drop indicates prefix drift.
+- `ai.tokens_per_request` — p95 should be within 20% of the eval-time distribution; a spike signals retrieval growth or prompt drift.
+
+Cross-reference `skills/hatch3r-observability-verify`.
+
+## Step 9: Feedback loop
+
+- Wire user thumbs-down to a feedback queue per response.
+- Monthly triage job promotes thumbs-down examples into regression fixtures in `evals/<feature>/edge.jsonl`.
+- Promotion is a manual review step — raw user feedback contains noise and adversarial labels.
+- Capture an optional free-text comment with each thumbs-down; the comment is the highest-signal feature for triage clustering.
+- Track feedback volume per response surface — a sudden spike in thumbs-down rate signals an upstream prompt or retrieval regression and gates a rollback.
+
+## Verdict
+
+All 9 steps complete = the AI feature is "done". Anything less = not done. The orchestrator running this skill emits a single-line verdict per step (`STEP_N: PASS|FAIL <evidence-path>`) and aggregates them. One FAIL on any step blocks release.
+
+Evidence paths point at concrete artifacts: the golden set (`evals/<feature>/golden.jsonl`), the prompt version (`prompts/<feature>/v<N>.md`), the eval report (`evals/<feature>/report-<run-id>.json`), and the dashboard URL for production SLI verification. Verdicts without evidence paths are not accepted by the gate.
+
+## When this skill runs
+
+- After `hatch3r-implementer` finishes the surrounding non-AI feature code, before `hatch3r-qa-validation`.
+- On every PR that introduces a new LLM call or modifies an existing prompt, model, or retrieval pipeline.
+- Step 8 (production verification) executes against the post-deploy environment, not the PR branch.
+
+## Cross-References
+
+- `rules/hatch3r-ai-evals.md` — backend governance (eval, cost, caching, fallback, SLI).
+- `rules/hatch3r-ai-ux-patterns.md` — frontend UX patterns (streaming, tool-call cards, citations).
+- `skills/hatch3r-ui-ux-verify/SKILL.md` — UI verification gate for AI surfaces.
+- `skills/hatch3r-observability-verify` — observability wiring checklist.
+- `rules/hatch3r-resilience-patterns.md` (Slice 8) — circuit-breaker + retry primitives reused in the fallback chain.
+
+## References
+
+- promptfoo — `promptfoo.dev`
+- DeepEval — `github.com/confident-ai/deepeval`
+- RAGAS — `docs.ragas.io`
+- Inspect (UK AISI) — `github.com/UKGovernmentBEIS/inspect_ai`
+- Anthropic prompt caching guide — `docs.anthropic.com/en/docs/build-with-claude/prompt-caching`
+- OpenTelemetry GenAI semantic conventions — `opentelemetry.io/docs/specs/semconv/gen-ai/`
+- Berkeley Function Calling Leaderboard (BFCL v4) — `gorilla.cs.berkeley.edu/leaderboard.html`

package/skills/hatch3r-api-spec/SKILL.md

@@ -14,13 +14,19 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Inventory existing endpoints
 - [ ] Step 2: Generate OpenAPI spec
 - [ ] Step 3: Validate schemas
 - [ ] Step 4: Generate documentation
 - [ ] Step 5: Verify spec accuracy
+- [ ] Step 6: Wire oasdiff breaking-change CI gate
 ```
 
+## 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: OpenAPI version (3.0 vs 3.1), spec output path, auth scheme (Bearer vs OAuth2 vs API key), breaking-change policy (block vs version vs document), and target consumers (SDK clients vs human docs vs both).
+
 ## Step 1: Inventory Existing Endpoints
 
 - Scan route definitions across the codebase (controllers, handlers, route files).
@@ -61,6 +67,72 @@ Task Progress:
 - Check that path parameters, query parameters, and headers are documented with accurate types, required flags, and example values.
 - Validate against any existing API consumers (SDKs, frontend clients) for breaking changes.
 
+## Step 6: Wire `oasdiff` Breaking-Change CI Gate
+
+Breaking changes on stable endpoints must trip CI before merge. This step enforces the CONSTITUTION §2 P5 lean-thresholds row "API breaking-change events on stable endpoints = 0 per release" (governance/CONSTITUTION.md:80, verified by `oasdiff / buf breaking / graphql-inspector CI gate`).
+
+### 6.1 Install `oasdiff`
+
+Pick one of two install paths:
+
+- npm global (CI runner with Node 22+): `npm i -g @tufin/oasdiff`
+- Docker image (no Node dependency): `docker run --rm -t -v $(pwd):/specs tufin/oasdiff <subcommand>`
+
+Pin the version in CI (e.g., `npm i -g @tufin/oasdiff@1.10.x` or `tufin/oasdiff:1.10`) so a new release of oasdiff does not change gate semantics mid-cycle.
+
+### 6.2 Compare current spec vs previous merged version
+
+The gate compares the spec on the feature branch against the spec at the merge base on the default branch. Fail CI on any breaking change to a stable endpoint; report non-breaking diffs as informational.
+
+- Fetch the base ref's spec into a temp path (e.g., `git show origin/main:openapi.yaml > /tmp/openapi.base.yaml`).
+- Run `oasdiff breaking /tmp/openapi.base.yaml ./openapi.yaml --fail-on ERR` — exit code 1 when one or more `ERR`-level breaking changes are detected.
+- Scope the gate to stable endpoints by excluding paths tagged `x-stability: experimental` via `--match-path` or by maintaining an `oasdiff-ignore.yaml` rules file for documented breaking changes already coordinated with consumers.
+
+### 6.3 Example GitHub Actions step
+
+```yaml
+name: API Breaking-Change Gate
+on:
+  pull_request:
+    paths:
+      - 'openapi.yaml'
+      - 'openapi.json'
+      - 'docs/api/**'
+
+jobs:
+  oasdiff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install oasdiff
+        run: npm i -g @tufin/oasdiff@1.10.x
+      - name: Resolve base spec
+        run: |
+          git show origin/${{ github.base_ref }}:openapi.yaml > /tmp/openapi.base.yaml
+      - name: Run breaking-change diff
+        run: |
+          oasdiff breaking /tmp/openapi.base.yaml ./openapi.yaml \
+            --fail-on ERR \
+            --format githubactions
+```
+
+The `--format githubactions` flag emits `::error::` annotations so each breaking change shows up inline on the PR diff.
+
+### 6.4 Handling an intentional breaking change
+
+When a breaking change is deliberate (versioned endpoint cut, deprecated field removed after the documented sunset window):
+
+1. Add a row to `oasdiff-ignore.yaml` with the change ID, the affected operation, and a link to the consumer-coordination record.
+2. Bump the spec `info.version` in line with the project's API versioning policy (semver-major for breaking changes on stable endpoints).
+3. Document the change in CHANGELOG (or equivalent) with the migration path for downstream consumers.
+
+The gate stays green only because the change is recorded — not because the breaking signal was silenced.
+
 ## Error Handling
 
 - **Route definitions use dynamic or meta-programmed patterns**: If endpoints are generated at runtime or via decorators that resist static analysis, document the gap and manually enumerate the missing endpoints.
@@ -74,3 +146,4 @@ Task Progress:
 - [ ] Spec passes linter validation
 - [ ] Example requests/responses included
 - [ ] No breaking changes to existing API consumers
+- [ ] `oasdiff breaking` CI gate is wired and fails on any `ERR`-level breaking change on stable endpoints (CONSTITUTION §2 P5: 0 per release)

package/skills/hatch3r-architecture-review/SKILL.md

@@ -12,6 +12,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Read existing ADRs and the template
 - [ ] Step 2: Define the decision context — problem, constraints, options
 - [ ] Step 3: Evaluate options — pros/cons, prototype if needed, check ADR constraints
@@ -20,6 +21,19 @@ Task Progress:
 - [ ] Step 6: Update affected specs or docs to reference the new ADR
 ```
 
+## 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: problem framing (what decision needs to be made), constraint set (mandatory vs preferred), evaluation horizon (short-term vs long-term cost), supersedes which prior ADR, and ADR status target (PROPOSED for discussion vs ACCEPTED for binding decision).
+
+## 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: Read Existing ADRs and Template
 
 - Read all ADRs in project docs to understand current architecture and constraints.

package/skills/hatch3r-bug-fix/SKILL.md

@@ -14,6 +14,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Read the issue and relevant specs
 - [ ] Step 2: Produce a diagnosis plan
 - [ ] Step 2b: Browser reproduction (if UI bug)
@@ -25,6 +26,10 @@ Task Progress:
 - [ ] Step 6: Open PR
 ```
 
+## 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: reproduction steps incomplete, expected vs actual behavior unstated, severity unclear (P0/P1 vs P2/P3), affected environment unknown (staging vs prod), or fix may require schema/API change with downstream consumers.
+
 ## Step 1: Read Inputs
 
 - Parse the issue body: problem description, reproduction steps, expected/actual behavior, severity, affected area.

package/skills/hatch3r-ci-pipeline/SKILL.md

@@ -14,6 +14,7 @@ cache_friendly: true
 
 ```
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: Audit existing pipeline
 - [ ] Step 2: Design stage structure
 - [ ] Step 3: Optimize test parallelization
@@ -21,6 +22,19 @@ Task Progress:
 - [ ] Step 5: Implement and validate
 ```
 
+## 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: CI platform (GitHub Actions vs GitLab vs CircleCI vs Azure Pipelines), pipeline duration target, runner sizing budget, deploy gate (auto vs manual approval for prod), and artifact retention policy.
+
+## 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: Audit Existing Pipeline
 
 - Map the current pipeline stages, their dependencies, and execution times.

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

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-aichat
+description: "Multi-provider LLM chat CLI with RAG and session memory. Use when RAG-enabled multi-provider conversational shell with saved session history; invoke `aichat`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
+tags: ["cli-tools", "ai", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: aichat
+  bin: aichat
+  tier: 3
+  category: ai
+  homepage: https://github.com/sigoden/aichat
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# aichat
+
+Multi-provider LLM chat CLI with RAG and session memory
+
+## When to Use
+
+Reach for `aichat` when the task is in the **ai** 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
+aichat 'explain this commit message' < commit.txt
+```
+One-shot prompt with stdin as the input payload.
+
+```bash
+aichat -r 'tech writer' 'rewrite as bullets' < draft.md
+```
+Apply a saved role (`~/.config/aichat/roles/tech-writer.md`) as the system prompt.
+
+```bash
+aichat --model claude-3-5-sonnet -e 'summarize' README.md
+```
+Pin the model and pass a file argument directly — `-e` executes the prompt non-interactively.
+
+```bash
+aichat --rag mydocs 'how do we configure auth?'
+```
+Query a pre-built RAG index over local documentation — runs embeddings locally, no remote indexer needed.
+
+```bash
+aichat --session refactor-plan
+```
+Resume a named session with persisted history — useful for multi-turn refinement loops.
+
+## Wrong Choice When
+
+- **Scripted Unix-style pipelines with a rich plugin ecosystem:** `hatch3r-cli-llm` (tier 2) has plugin support for templates, embeddings, and provider adapters not in aichat.
+- **Offline-only / fully local inference:** aichat supports Ollama backends but adds an unneeded abstraction; talk to Ollama's HTTP API directly via `curl`.
+- **CI batch tasks that benefit from `mods` pipe semantics:** `hatch3r-cli-mods` reads a single piped payload then exits — simpler for one-shot transforms.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-llm` (tier 2) | Plugin ecosystem, templates, embeddings, structured CI use |
+| `hatch3r-cli-mods` (tier 3) | Single-piped-payload transforms, Unix-pipe ergonomics |
+| Raw `curl` against Ollama / provider HTTP API | Maximum control, no client-side caching or session state |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v aichat
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install aichat
+```
+
+Homepage: https://github.com/sigoden/aichat

package/skills/hatch3r-cli-ast-grep/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-ast-grep
+description: "Structural search and rewrite for code via AST patterns. Use when Tree-sitter AST pattern rewrites scoped to a single grammar; invoke `sg`. Grammar-aware: queries are written in the same syntax as the language being edited."
+tags: ["cli-tools", "search", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: ast-grep
+  bin: sg
+  tier: 1
+  category: search
+  homepage: https://ast-grep.github.io/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# ast-grep
+
+Structural search and rewrite for code via AST patterns
+
+## When to Use
+
+Reach for `sg` when the task is in the **search** 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
+sg --pattern 'console.log($MSG)' --lang ts src/
+```
+Pattern with a meta-variable (`$MSG`) — matches any `console.log` call regardless of whitespace or argument shape.
+
+```bash
+sg run -p 'await $FN()' -r 'await ($FN()).catch(e => log(e))' --update-all src/
+```
+Structural rewrite: every bare `await $FN()` gains a `.catch` arm; `--update-all` writes in place.
+
+```bash
+sg scan --config sgconfig.yml
+```
+Runs a rule pack from `sgconfig.yml` — repo-pinned lints that survive regex edits.
+
+```bash
+sg test --update-snapshots
+```
+Snapshot-style tests for rules — keeps rule packs honest as the codebase shifts.
+
+```bash
+sg --pattern 'function $NAME($$$ARGS) { $$$BODY }' --lang ts --json src/
+```
+Triple-`$` captures the rest of an argument list or body — JSON output feeds `jq` for downstream filtering.
+
+## Wrong Choice When
+
+- Don't reach for `sg` when the target is plain literal text (a TODO marker, a string in CHANGELOG). Reach for `ripgrep` (`hatch3r-cli-ripgrep`) — orders of magnitude faster on raw matching.
+- Don't use `sg` for cross-language SAST policy work (e.g., taint analysis). Reach for `semgrep`, which has rule packs, CI integrations, and a security-audit lineage.
+- Don't reach for `sg` on languages it does not parse (Bash, Makefile, INI). The pattern compiler will reject the request — fall back to `ripgrep` + `sd`.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `ripgrep` (`hatch3r-cli-ripgrep`) | Literal regex over text — ast-grep is overkill if you do not need structural matching. |
+| `semgrep` | Security/policy rule packs, multi-language SAST, central rule registry. |
+| `comby` | Multi-language structural rewrites with template syntax and no per-language plugin. |
+| Editor refactor / language server | Authoritative rename or extract-method with full type information. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v sg
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install ast-grep
+```
+
+Homepage: https://ast-grep.github.io/

package/skills/hatch3r-cli-az-devops/SKILL.md

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-az-devops
+description: "Azure DevOps work items, repos, pipelines via az CLI extension. Use when Azure DevOps work-item edits, repo pushes, and pipeline runs; invoke `az`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
+tags: ["cli-tools", "forge"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: az-devops
+  bin: az
+  tier: 2
+  category: forge
+  homepage: https://learn.microsoft.com/en-us/cli/azure/azure-devops
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# az-devops
+
+Azure DevOps work items, repos, pipelines via az CLI extension
+
+## When to Use
+
+Reach for `az` when the task is in the **forge** 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
+az repos pr list --status active --query '[].pullRequestId' --output tsv
+```
+Print active PR IDs as a newline-separated list; `--query` (JMESPath) trims the payload before stdout.
+
+```bash
+az repos pr show --id 42 --output json
+```
+Fetch a single PR's metadata as JSON for downstream `jq` filters.
+
+```bash
+az boards work-item show --id 4242 --output json
+```
+Pull a work item (bug, task, user story) by numeric ID; one round-trip, structured output.
+
+```bash
+az boards work-item create --type Bug --title 'flaky import test' --description 'Repro: ...'
+```
+Open a work item from CI or an agent; the new ID is printed on stdout.
+
+```bash
+az pipelines run --name CI --branch main
+```
+Queue a pipeline run on a named definition; returns the build ID for polling.
+
+```bash
+az artifacts universal download --feed myfeed --name pkg --version 1.0.0 --path .
+```
+Fetch a Universal Package into the cwd — avoids the larger Azure Artifacts MCP equivalents.
+
+## Wrong Choice When
+
+- The repo is on GitHub — use `gh` (Tier 1); `az repos` will return 404s without a configured Azure project.
+- The repo is on GitLab — use `glab` (Tier 2 sibling); same operations, native auth.
+- You only need to download a public release asset — `curl` to the artifact URL is one hop.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `gh` | GitHub-hosted code or issues. |
+| `glab` | GitLab-hosted code or issues. |
+| `curl` + `AZURE_DEVOPS_PAT` | Endpoint not surfaced by `az devops`; need raw header control. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v az
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install azure-cli && az extension add --name azure-devops
+```
+
+Homepage: https://learn.microsoft.com/en-us/cli/azure/azure-devops