hatch3r 1.8.0 → 2.0.0

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

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-mods
-description: "Charm mods — Unix-friendly LLM pipeline tool. Use when Unix-pipeline LLM inference reading Markdown stdin and writing Markdown stdout; invoke `mods`. 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: mods
-  bin: mods
-  tier: 3
-  category: ai
-  homepage: https://github.com/charmbracelet/mods
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# mods
-
-Charm mods — Unix-friendly LLM pipeline tool
-
-## When to Use
-
-Reach for `mods` 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
-cat README.md | mods 'summarize in 3 bullets'
-```
-Pipe a file into mods with an inline instruction; output prints to stdout.
-
-```bash
-git diff | mods 'write a conventional-commits message for this diff'
-```
-Generate a commit message from staged changes — pairs well with `git commit -F -`.
-
-```bash
-mods -m gpt-4o 'rewrite for clarity' < draft.md
-```
-Override the default model per invocation.
-
-```bash
-mods --no-cache 'fresh response please' < input.txt
-```
-Bypass the on-disk response cache when you need a non-deterministic re-roll.
-
-```bash
-mods -f json 'extract action items as a JSON array' < meeting-notes.md
-```
-Force a structured-output format — pipes cleanly into `hatch3r-cli-jq`.
-
-## Wrong Choice When
-
-- **Plugin ecosystem needed (templates, embeddings, multi-step chains):** `hatch3r-cli-llm` (tier 2) covers these; mods is intentionally minimal.
-- **Multi-turn conversational sessions:** mods is single-shot; use `hatch3r-cli-aichat` for persisted history.
-- **Interactive prompt iteration with feedback:** mods has no TUI — `aichat` has REPL mode.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-llm` (tier 2) | Plugin ecosystem, templates, embeddings, CI workflows |
-| `hatch3r-cli-aichat` (tier 3) | Multi-turn sessions, RAG mode, role library |
-| Raw `curl` against provider API | Custom request shape, streaming, no client process |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v mods
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install charmbracelet/tap/mods
-```
-
-Homepage: https://github.com/charmbracelet/mods

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

@@ -1,60 +0,0 @@
----
-id: hatch3r-cli-overview
-description: "Catalog of all hatch3r-recommended CLI tools — discovery entry with tier tables and decision tree."
-tags: ["cli-tools", "core", "reference"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# CLI Tool Catalog
-
-hatch3r recommends a small set of terminal-native CLI tools agents can call instead of MCP servers or wrapped APIs. Each tool listed below has its own skill file with recipes, anti-patterns, and per-OS install instructions. Run `npx hatch3r cli-tools` to (de)select tools, or `npx hatch3r cli-tools detect` for a read-only install report.
-
-## Tier 1 — default-on
-
-| Tool | Skill ID | Use for |
-|------|----------|---------|
-| `ast-grep` | `hatch3r-cli-ast-grep` | Structural search and rewrite for code via AST patterns |
-| `bat` | `hatch3r-cli-bat` | cat clone with syntax highlighting and git integration |
-| `delta` | `hatch3r-cli-delta` | Syntax-highlighting git diff pager |
-| `fd` | `hatch3r-cli-fd` | User-friendly find replacement, gitignore-aware |
-| `gh` | `hatch3r-cli-gh` | GitHub CLI — repos, issues, PRs, releases, gists |
-| `jq` | `hatch3r-cli-jq` | JSON processor and query language |
-| `ripgrep` | `hatch3r-cli-ripgrep` | Fast recursive grep with sane defaults and gitignore awareness |
-| `sd` | `hatch3r-cli-sd` | Intuitive sed replacement with literal string patterns |
-| `yq` | `hatch3r-cli-yq` | YAML processor (mikefarah Go implementation) |
-| `zstd` | `hatch3r-cli-zstd` | Fast lossless compression with high ratio |
-
-## Tier 2 — conditional (offered on project signal)
-
-| Tool | Skill ID | Use for |
-|------|----------|---------|
-| `az-devops` | `hatch3r-cli-az-devops` | Azure DevOps work items, repos, pipelines via az CLI extension |
-| `difftastic` | `hatch3r-cli-difftastic` | Structural diff that understands syntax |
-| `docker` | `hatch3r-cli-docker` | Container runtime and CLI |
-| `duckdb` | `hatch3r-cli-duckdb` | Embedded analytical database with first-class CSV/Parquet support |
-| `fzf` | `hatch3r-cli-fzf` | Interactive fuzzy finder for TTY pickers |
-| `glab` | `hatch3r-cli-glab` | GitLab CLI — merge requests, issues, pipelines |
-| `lazygit` | `hatch3r-cli-lazygit` | Terminal UI for git with keyboard-driven workflows |
-| `llm` | `hatch3r-cli-llm` | simonw/llm — invoke LLMs from the command line with prompt templates |
-| `playwright` | `hatch3r-cli-playwright` | Browser automation, web testing, and UI interaction |
-| `taplo` | `hatch3r-cli-taplo` | TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml |
-| `qsv` | `hatch3r-cli-qsv` | Fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained xsv successor |
-
-## Tier 3 — opt-in advanced
-
-| Tool | Skill ID | Use for |
-|------|----------|---------|
-| `aichat` | `hatch3r-cli-aichat` | Multi-provider LLM chat CLI with RAG and session memory |
-| `comby` | `hatch3r-cli-comby` | Structural search and replace across languages with declarative patterns |
-| `csvkit` | `hatch3r-cli-csvkit` | csvkit — Python CSV toolkit (csvlook, csvsql, csvjoin, csvstat) |
-| `miller` | `hatch3r-cli-miller` | awk/sed/cut/join for CSV/TSV/JSON/Parquet streams |
-| `mods` | `hatch3r-cli-mods` | Charm mods — Unix-friendly LLM pipeline tool |
-| `podman` | `hatch3r-cli-podman` | Daemonless container engine, rootless by default (Docker alternative) |
-| `rtk` | `hatch3r-cli-rtk` | CLI output-compression proxy (see ⚠ caveat) |
-| `stagehand` | `hatch3r-cli-stagehand` | Browserbase Stagehand — AI-driven browser automation |
-
-## Decision Tree
-
-Need text search → `rg`. Structural → `ast-grep`. Files → `fd`. JSON → `jq`. YAML → `yq`. Replace → `sd`. Git/forge → `gh` / `glab` / `az-devops`. Browser → `playwright`. View → `bat`. Diff → `delta`. Archive → `zstd`.

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

@@ -1,89 +0,0 @@
----
-id: hatch3r-cli-playwright
-description: "Browser automation, web testing, and UI interaction. Use when end-to-end browser test execution capturing screenshots and traces; invoke `playwright`. Built around test runners (`@playwright/test`) with deterministic locators and waits."
-tags: ["cli-tools", "browser"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: playwright
-  bin: playwright
-  tier: 2
-  category: browser
-  homepage: https://playwright.dev/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# playwright
-
-Browser automation, web testing, and UI interaction
-
-## When to Use
-
-Reach for `playwright` 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 playwright test
-```
-Run the full suite; non-zero exit on first failing spec.
-
-```bash
-npx playwright test --grep '@smoke' --workers=1
-```
-Filter by tag and serialize workers — stable output for agent log scraping.
-
-```bash
-npx playwright test tests/login.spec.ts --reporter=line
-```
-Single-file run with one-line-per-test reporter — fits in <1KB stdout.
-
-```bash
-npx playwright codegen https://example.com
-```
-Record interactions into a generated spec — human-in-the-loop authoring; not for autonomous runs.
-
-```bash
-npx playwright test --update-snapshots
-```
-Refresh visual/text snapshots after intentional UI changes; review the diff before committing.
-
-```bash
-npx playwright show-report
-```
-Open the HTML report locally — human triage step; agents should parse `test-results/results.json` instead.
-
-## Wrong Choice When
-
-- The system under test exposes only an HTTP API and no rendered UI — use `curl` + `jq` (Tier 1) for ~50x faster runs.
-- The task is autonomous natural-language browsing (navigate, read, decide) rather than scripted assertions — Stagehand is built for that loop.
-- You only need a one-off page snapshot or screenshot from a script — a headless `curl` plus a server-side renderer is cheaper than the full Playwright install.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `curl` + `jq` | API-only tests; no DOM involved. |
-| Stagehand | Agent drives the browser with natural language rather than fixed scripts. |
-| Cypress | Existing Cypress suite or component-test workflow; otherwise prefer Playwright for multi-browser support. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v playwright
-```
-
-Install (mac):
-
-```bash
-# npm
-npm install -D @playwright/test && npx playwright install
-```
-
-Homepage: https://playwright.dev/

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

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-podman
-description: "Daemonless container engine, rootless by default (Docker alternative). Use when rootless OCI-image execution without a privileged daemon; invoke `podman`. Forks per-pod processes directly under the invoking user; ideal for hardened CI workers."
-tags: ["cli-tools", "container", "opt-in"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: podman
-  bin: podman
-  tier: 3
-  category: container
-  homepage: https://podman.io/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# podman
-
-Daemonless container engine, rootless by default (Docker alternative)
-
-## When to Use
-
-Reach for `podman` when the task is in the **container** 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
-podman build -t myapp:dev .
-```
-Build an image from the local Dockerfile — same CLI surface as docker build.
-
-```bash
-podman run --rm -v "$PWD:/app:Z" -w /app node:22 npm test
-```
-Run a one-shot container with the working directory bind-mounted; the `:Z` suffix triggers SELinux relabel on Fedora/RHEL hosts.
-
-```bash
-podman compose up
-```
-Run a `compose.yaml` workflow under podman — uses the podman-compose plugin or docker-compose adapter.
-
-```bash
-podman run --userns=keep-id -v "$PWD:/work" myapp
-```
-Preserve the host UID inside the rootless container so written files do not end up owned by a high-mapped UID.
-
-```bash
-podman system service --time=0 &
-```
-Expose a docker-API-compatible socket so docker-only tooling (e.g. testcontainers) can talk to podman unchanged.
-
-## Wrong Choice When
-
-- **Enterprise compose / swarm orchestration:** `hatch3r-cli-docker` (tier 2) is the established path for Swarm and Docker Desktop integration; podman's swarm support is minimal.
-- **macOS developer experience parity:** docker desktop has native macOS VM tuning; podman runs in a QEMU machine with extra overhead and bind-mount caveats.
-- **Tooling that hard-codes `/var/run/docker.sock`:** unless you start `podman system service`, those tools fail.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-docker` (tier 2) | Mainstream CI, Docker Desktop, Swarm, broad ecosystem assumptions |
-| nerdctl + containerd | Kubernetes-aligned runtime, OCI-faithful CLI |
-| buildah | Image builds without a full container runtime (rootless, scriptable) |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v podman
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install podman
-```
-
-Homepage: https://podman.io/

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

@@ -1,91 +0,0 @@
----
-id: hatch3r-cli-qsv
-description: "Fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained xsv successor. Use when slicing huge CSV documents by row range or column without materialising the dataset; invoke `qsv`. 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: qsv
-  bin: qsv
-  tier: 2
-  category: data
-  homepage: https://github.com/jqnatividad/qsv
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# qsv
-
-Fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained xsv successor
-
-## When to Use
-
-Reach for `qsv` when the task is in the **data** category and the agent would otherwise call an MCP tool or read large outputs into context.
-
-`qsv` is a drop-in superset of `xsv` — every `xsv` sub-command name and flag works under `qsv`, plus 50+ additional commands (`apply`, `fetch`, `validate`, `tojsonl`, `sqlp`, etc.). The upstream `BurntSushi/xsv` repository was archived on 2025-04-24; `jqnatividad/qsv` is the active fork with regular releases.
-
-## 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
-qsv stats huge.csv
-```
-Per-column min/max/mean/stddev/cardinality — single streaming pass over the file.
-
-```bash
-qsv select name,email,active records.csv
-```
-Project a subset of columns without rewriting; output stays CSV for downstream tools.
-
-```bash
-qsv sort -s amount records.csv | qsv slice -e 100
-```
-Sort by `amount` then take the first 100 rows — composable pipe; both stages stream.
-
-```bash
-qsv frequency -s status events.csv
-```
-Tabulate value counts for a column; output is itself CSV, parsable by the next step.
-
-```bash
-qsv search -s email '@example\.com$' users.csv
-```
-Regex-filter a column — much cheaper than loading the whole file into a SQL engine.
-
-```bash
-qsv 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 — `qsv 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 qsv
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install qsv
-```
-
-Homepage: https://github.com/jqnatividad/qsv

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

@@ -1,91 +0,0 @@
----
-id: hatch3r-cli-rtk
-description: "CLI output-compression proxy (see ⚠ caveat). Use when compressing oversize tool output payloads before they enter an LLM prompt; invoke `rtk`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
-tags: ["cli-tools", "ai", "opt-in", "caveat"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: rtk
-  bin: rtk
-  tier: 3
-  category: ai
-  homepage: https://github.com/rtk-ai/rtk
-  caveat: pipe-output-corruption
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# rtk
-
-CLI output-compression proxy (see ⚠ caveat)
-
-## ⚠ Critical: pipe-output corruption (issue #1282)
-
-rtk silently rewrites piped stdout which breaks downstream tooling.
-Mitigation: `export RTK_DISABLE_PIPE_REWRITE=1` or invoke with `rtk --raw-output`.
-Track upstream: https://github.com/rtk-ai/rtk/issues/1282
-
-## When to Use
-
-Reach for `rtk` 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
-export RTK_DISABLE_PIPE_REWRITE=1
-```
-Disable pipe-output rewriting before any pipeline use. Required for safe interop with jq/grep/awk.
-
-```bash
-rtk run npm test
-```
-Run the package's test suite under rtk to compress vitest/jest output before it reaches the agent's context.
-
-```bash
-rtk run pytest -x
-```
-Compress pytest output and stop on first failure — fits a multi-thousand-line traceback into a few KB.
-
-```bash
-rtk eval 'function foo() { return 42 }'
-```
-Sandboxed JavaScript eval — returns just the value, no surrounding noise.
-
-```bash
-rtk --raw-output run go test ./...
-```
-Per-invocation override of the pipe rewrite when piping output into a downstream parser (`| jq`, `| grep`).
-
-## Wrong Choice When
-
-- **Piping to `jq` / `grep` / `awk` without `RTK_DISABLE_PIPE_REWRITE=1` set:** the rewrite mangles JSON byte boundaries (issue #1282) — corruption is silent. Reach for plain shell + `tee` or `hatch3r-cli-jq` directly on raw command output.
-- **Safety-critical CI where masked failures matter:** rtk's compression can elide stack frames a downstream check needs. Run the underlying test command directly and capture full output to a file.
-- **One-shot small commands under ~100 lines:** the compression overhead exceeds the saved context — invoke the underlying tool directly.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| Plain shell + `tee output.log` | When you need a verbatim log file for forensics or CI artifacts |
-| `hatch3r-cli-jq` (tier 1) on raw output | When the upstream command already emits JSON and you want a deterministic projection |
-| Direct `npm test` / `pytest -x` with `--reporter` flags | When the test runner has a built-in compact reporter (jest `--silent`, pytest `-q`) |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v rtk
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install rtk-ai/tap/rtk
-```
-
-Homepage: https://github.com/rtk-ai/rtk

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

@@ -1,85 +0,0 @@
----
-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