@complexthings/superpowers-agent 8.4.1 → 9.0.1

package/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+<!-- SUPERPOWERS_-_INSTRUCTIONS_START -->
+${content}
+<!-- SUPERPOWERS_-_INSTRUCTIONS_END -->

package/.github/workflows/main.yaml

@@ -30,4 +30,4 @@ jobs:
       - name: Publish to npm
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish --access public
+        run: npm publish --access public

package/AGENTS.md

@@ -58,3 +58,100 @@ Skills encode proven techniques that prevent mistakes. Not using them means repe
 
 <!-- SUPERPOWERS_SKILLS_END -->
 
+## What This Project Is
+
+**Superpowers Agent** is a CLI (`superpowers-agent`, alias `superpowers`) that manages reusable markdown-based "skills" for AI coding assistants. It delivers skills to Claude, GitHub Copilot, Cursor, Gemini, OpenCode, and Codex. Skills live in `skills/` (this repo) and `.agents/skills/`, and bootstrap symlinks them into each assistant's config directory. Published to npm as `@complexthings/superpowers-agent`.
+
+## Build & Development
+
+The CLI source lives in `.agents/` and is built with **Bun** (`packageManager: bun@1.3.8`). Run scripts from the `.agents/` directory:
+
+```bash
+cd .agents
+bun run build            # Build minified ESM bundle → .agents/superpowers-agent
+bun run watch            # Build in watch mode
+bun run dev              # Run CLI from source (bun src/cli.js)
+bun run dev:link         # Symlink the `superpowers-agent` bin to the dev source
+bun run production:link  # Symlink the bin to the built bundle
+```
+
+The build (`.agents/build.js`) uses the `Bun.build` API, so it must run under **bun**, not node. Output is `.agents/superpowers-agent` — a polyglot shebang script that execs `bun` if present, otherwise `node`.
+
+The CLI has **no runtime dependencies** (pure Node.js/Bun built-ins). The only dev dependency is `husky`. Node engines: `^20 || ^22 || ^24`.
+
+## Testing
+
+There is **no automated test runner** and no `test` script. Verification is manual: run the CLI commands directly, or drive the saved prompt scenarios in `.agents/prompts/`. State this plainly rather than inventing a test command.
+
+## Architecture
+
+### Source (`.agents/src/`)
+
+| Layer | Files | Responsibility |
+|-------|-------|---------------|
+| CLI entry | `cli.js` | Command dispatch table |
+| Commands | `commands/bootstrap.js`, `update.js`, `simple-commands.js` | Command implementations |
+| Core | `core/config.js`, `paths.js`, `platform-detection.js`, `git.js` | Config, path resolution, platform detection, git helpers |
+| Skills | `skills/finder.js`, `locator.js`, `installer.js`, `executor.js`, `parser.js` | Skill discovery, install, execution pipeline |
+| Agents | `agents/installer.js`, `agents/platforms.js` | Install agent definitions (`.github/agents/*.agent.md`, `.opencode/agents/*.md`) into platform dirs |
+| Integrations | `integrations/claude.js`, `codex.js`, `copilot.js`, `cursor.js`, `gemini.js`, `opencode.js` | Per-platform symlink/config setup |
+| Utils | `utils/symlinks.js`, `frontmatter.js`, `output.js`, `file-ops.js` | Shared helpers |
+
+### Skill Discovery Priority (highest → lowest)
+
+1. `.agents/skills/` — project-level
+2. `~/.agents/skills/` — personal cross-project
+3. `~/.agents/superpowers/skills/` — bundled community skills
+
+### CLI Commands
+
+From `.agents/src/cli.js` dispatch table:
+
+- **Core:** `bootstrap [--no-update] [--force]`, `version`, `check-updates`, `update [--no-reinstall]`
+- **Config:** `config-get`, `config-set <key> <value>`
+- **Skills:** `setup-skills`, `find-skills [pattern]`, `use-skill <name>`, `execute <name>`, `dir <name>`, `path <name>`, `get-helpers <skill> <search-term>`
+- **Install/manage skills:** `add <url-or-path|@alias> [path]`, `add-repository <git-url> [--as=@alias]`, `list-repositories`, `pull <url-or-path|@alias>`, `rm <url-or-path|@alias>`
+- **Integrations:** `install-cursor-hooks`, `install-aliases`
+
+### Key Flows
+
+- **`bootstrap`** → detects installed AI platforms → symlinks skills into each platform's skills dir → writes platform config files
+- **`find-skills [pattern]`** → searches all three skill tiers → returns name/path/description
+- **`execute <skill-name>`** → locates skill → outputs SKILL.md content for the agent to follow
+- **`add <url-or-path|@alias>`** → clones a git repo or copies a local path → installs skills into `~/.agents/superpowers/skills/`
+- **`update`** → checks the npm registry for a newer version → reports if an update is available
+
+### Skill Structure
+
+Each skill is a directory with a `SKILL.md` file:
+
+```
+skills/
+└── <category>/
+    └── <skill-name>/
+        ├── SKILL.md         # Frontmatter (name, description) + instructions
+        ├── scripts/         # Optional support scripts
+        └── resources/       # Optional templates/data
+```
+
+`SKILL.md` frontmatter fields: `name`, `description`, and optional `metadata` (e.g. `version`). The set of bundled skills and their lockfile state are tracked in `skill.json` and `skills-lock.json` at the repo root.
+
+## Versioning & Publishing
+
+The `.husky/pre-commit` hook keeps the root `package.json` and `.agents/package.json` versions in sync: on commit it picks the higher of the two, writes both, refreshes lockfiles, rebuilds the bundle (`cd .agents && bun install && bun run build`), and stages the affected files. Don't hand-edit one version without the other.
+
+The package is published to npm as `@complexthings/superpowers-agent` (registry auth via the `COMPLEX_THINGS_NPM_TOKEN` in `.npmrc`). The current version is whatever `package.json` reports — do not hardcode it elsewhere.
+
+## Agent skills
+
+### Issue tracker
+
+Issues and PRDs are tracked as GitHub issues on `complexthings/superpowers`, managed via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical triage roles use their default label strings (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root (created lazily). See `docs/agents/domain.md`.

package/README.md

@@ -2,10 +2,19 @@
 
 A comprehensive skills library of proven techniques, patterns, and workflows for AI coding assistants.
 
-**This is a fork and extension of Jesse Vincent's incredible [Superpowers for Claude Code](https://github.com/obra/superpowers).** Jesse's groundbreaking work and [his amazing blog post](https://blog.fsck.com/2025/10/09/superpowers/) introduced the concept of systematic, reusable skills for AI agents. This fork extends that vision to support agent-agnostic workflows across GitHub Copilot, Cursor, Gemini, and other AI coding assistants.
+**This is a fork and extension of Jesse Vincent's incredible [Superpowers for Claude Code](https://github.com/obra/superpowers).** Jesse's groundbreaking work and [his amazing blog post](https://blog.fsck.com/2025/10/09/superpowers/) introduced the concept of systematic, reusable skills for AI agents. This fork extends that vision to support agent-agnostic workflows across GitHub Copilot, Claude Code, and OpenCode.
 
 ## What's New
 
+**v9.0.0 (May 28, 2026):**
+
+- **Claude persona installation** — `.claude/agents/<name>.md` personas now install into `~/.claude/agents/` via `add`/`pull` (previously silently skipped)
+- ⚠️ **No more `postinstall`** — the npm `postinstall` script was removed for supply-chain hardening. Fresh installs now require a **one-time manual** `superpowers-agent bootstrap`; `superpowers-agent update` self-runs bootstrap thereafter
+- ⚠️ **Removed Cursor, Codex & Gemini support** — supported platforms are now **GitHub Copilot, Claude Code, and OpenCode** only. Integration modules, detection, the `install-cursor-hooks` command, and `GEMINI.md` generation were removed
+- ⚠️ **Skills live only in `~/.agents/skills`** — per-platform skill symlinking has been removed. A one-time `skill.json`-gated cleaner runs during `bootstrap` to scrub deprecated symlink directories (including legacy Cursor/Codex/Gemini) without touching agent personas
+- **Fixed `copilot-instructions.md`** — `setup-skills` now correctly creates and idempotently updates `.github/copilot-instructions.md`
+- **`bun test` harness** — added a Bun test runner, smoke test, and `test` script following the `.agents/tests/<feature>.test.js` convention
+
 **v8.4.0 (April 6, 2026):**
 
 - **`superpowers-agent rm` command** — new CLI command for removing installed skills and agents from your system
@@ -77,7 +86,7 @@ A comprehensive skills library of proven techniques, patterns, and workflows for
 - **Utility Commands** - `find-skills` to discover available skills, `execute` to load them
 
 Plus:
-- **Universal Prompts** - Work across Claude, GitHub Copilot, Cursor, Gemini, and other AI assistants
+- **Universal Skills** - Work across GitHub Copilot, Claude Code, and OpenCode
 - **Automatic Integration** - Skills activate automatically when relevant
 - **Consistent Workflows** - Systematic approaches to common engineering tasks
 
@@ -85,13 +94,15 @@ Plus:
 
 ## Quick Install (Recommended)
 
-Install Superpowers globally with one command:
+Install Superpowers globally and run the required one-time bootstrap step:
 
 ```bash
 npm install -g @complexthings/superpowers-agent
 superpowers-agent bootstrap
 ```
 
+> **Note:** `superpowers-agent bootstrap` is a **required** one-time step after every fresh install. It is no longer run automatically by npm's `postinstall` hook — you must run it manually. Subsequent `superpowers-agent update` calls will run bootstrap for you automatically.
+
 ## Migration to Superpower Agent `^8.0.0`
 
 ```bash
@@ -273,90 +284,28 @@ superpowers-agent add https://github.com/example/agents-repo.git
 superpowers-agent pull @my-agents
 ```
 
-### Skill Symlinks for IDE Integration
-
-Superpowers automatically creates symlinks to make skills available to all major AI coding assistants in their native skill directories.
-
-**How it works:**
-
-When you run `superpowers-agent bootstrap` or `superpowers-agent setup-skills`:
-
-1. **Global symlinks** (via `bootstrap`) sync skills to user-level directories:
-   - `~/.claude/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.copilot/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.config/opencode/skill/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.cursor/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.gemini/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.codex/skills/superpowers` -> `~/.agents/superpowers/skills/`
-
-2. **Project symlinks** (via `setup-skills`) sync project skills to agent directories:
-   - `.claude/skills` -> `.agents/skills`
-   - `.github/skills` -> `.agents/skills`
-   - `.opencode/skill` -> `.agents/skills`
-   - `.cursor/skills` -> `.agents/skills`
-   - `.gemini/skills` -> `.agents/skills`
-   - `.codex/skills` -> `.agents/skills`
+### Skill Storage
 
-3. **Personal skills** (installed via `superpowers-agent add`) are symlinked individually to all platforms.
+As of v9.0.0, Superpowers no longer creates per-platform skill symlinks. Skills live in just two canonical locations and the supported agents discover them there directly:
 
-**Behavior:**
-- Symlinks are only created if the parent directory exists
-- Use `--force` flag to create parent directories: `superpowers-agent bootstrap --force`
-- Use `--force-<agent>` flags to re-install only specific agent integrations (e.g. `--force-copilot`, `--force-cursor`, `--force-claude`)
-- Symlinks are tracked in `~/.agents/config.json` for management
+- **Global skills** — bundled Superpowers skills in `~/.agents/superpowers/skills/` and personal skills in `~/.agents/skills/`
+- **Project skills** — `.agents/skills/` inside a project (created/managed by `setup-skills`)
 
-**Windows Notes:**
+**Stale symlink cleanup:**
 
-On Windows, symlinks require either:
-- Developer Mode enabled (Settings > Update & Security > For developers)
-- Running as administrator
-
-If symlink creation fails on Windows, you'll see a warning with instructions.
-
-**Configuration:**
-```json
-// ~/.agents/config.json
-{
-  "symlinks": {
-    "claude": {
-      "superpowers": "~/.claude/skills/superpowers",
-      "skills": ["~/.claude/skills/my-skill"]
-    },
-    "copilot": {
-      "superpowers": "~/.copilot/skills/superpowers",
-      "skills": []
-    },
-    "opencode": {
-      "superpowers": "~/.config/opencode/skill/superpowers",
-      "skills": []
-    },
-    "cursor": {
-      "superpowers": "~/.cursor/skills/superpowers",
-      "skills": []
-    },
-    "gemini": {
-      "superpowers": "~/.gemini/skills/superpowers",
-      "skills": []
-    },
-    "codex": {
-      "superpowers": "~/.codex/skills/superpowers",
-      "skills": []
-    }
-  }
-}
-```
+A one-time, `skill.json`-gated cleaner runs during `superpowers-agent bootstrap`. It scrubs deprecated per-platform skill symlink directories left behind by older versions — including legacy Cursor, Codex, and Gemini directories — without touching agent personas in `~/.claude/agents/` or the supported platforms.
 
-## Slash Commands & Skill Priority
+## Skill Priority
 
-Superpowers delivers skills as symlinks into each agent's native skill directory. Each agent discovers and loads skills using its native skill tool — no separate prompt/command files are installed.
+Each supported agent discovers and loads skills using its native skill tool. No separate prompt/command files are installed.
 
 **Skill priority pipeline (first match wins):**
-1. `./skills/` or `.agents/skills/` inside the workspace (project-specific overrides)
+1. `.agents/skills/` inside the workspace (project-specific overrides)
 2. `.claude/skills/` inside the repo if present (repo-wide Claude overrides)
 3. Personal skills in `~/.agents/skills/` (user-level customizations)
 4. Bundled Superpowers skills in `~/.agents/superpowers/skills/` (system defaults)
 
-When any agent invokes a skill — no matter which tool it originates from — the CLI enforces the ordering above. Add a `brainstorming` skill under `./skills/` and every tool immediately picks it up without modifying any prompt files.
+When any agent invokes a skill — no matter which supported tool it originates from — the CLI enforces the ordering above. Add a `brainstorming` skill under `.agents/skills/` and every supported tool immediately picks it up.
 
 ### OpenCode
 
@@ -364,22 +313,11 @@ Skills are available via OpenCode's native `skill` tool. The `.opencode/plugins/
 
 ### GitHub Copilot
 
-Skills are available via the native skill tool. 
-
-### Cursor
-
-Skills are available via the native skill tool. 
-### Gemini
-
-Skills are available via the native skill tool. 
+Skills are available via the native skill tool.
 
 ### Claude Code
 
-Skills are available via the native skill tool. 
-
-### Codex
-
-Skills are available via the native skill tool. 
+Skills are available via the native skill tool. Claude agent personas defined in `.claude/agents/<name>.md` are installed into `~/.claude/agents/` via `add`/`pull`.
 
 ## What's Inside
 
@@ -450,7 +388,7 @@ The `tests/` directory contains agent-agnostic test scripts for validating skill
 ./tests/skill-triggering/run-all.sh
 
 # Configure for your agent
-export AGENT_CLI="opencode"  # or "claude", "cursor", etc.
+export AGENT_CLI="opencode"  # or "claude", "copilot", etc.
 ./tests/skill-triggering/run-test.sh prompts/test-name.txt
 ```
 
@@ -609,7 +547,7 @@ superpowers-agent add @baici
 1. **Bootstrap Process** - Installs agent integrations and syncs skill symlinks globally
 2. **Skill Discovery** - Finds skills across system, personal, and project locations
 3. **Priority Resolution** - Project skills override personal skills override system skills
-4. **Universal Integration** - Works with OpenCode, GitHub Copilot, Cursor, Gemini, and other AI assistants
+4. **Universal Integration** - Works with GitHub Copilot, Claude Code, and OpenCode
 
 **For OpenCode:**
 1. **Plugin System** - The `.opencode/plugins/superpowers-agent.js` plugin injects bootstrap context dynamically at session start
@@ -667,11 +605,11 @@ Use `--force-<agent>` flags to target individual agents without running the full
 # Re-install only GitHub Copilot integration
 superpowers-agent bootstrap --force-copilot
 
-# Re-install Copilot and Gemini together
-superpowers-agent bootstrap --force-copilot --force-gemini
+# Re-install Copilot and Claude together
+superpowers-agent bootstrap --force-copilot --force-claude
 ```
 
-Supported flags: `--force-copilot`, `--force-cursor`, `--force-codex`, `--force-gemini`, `--force-claude`, `--force-opencode`
+Supported flags: `--force-copilot`, `--force-claude`, `--force-opencode`
 
 > When `--force-<agent>` flags are used, universal alias installation and `AGENTS.md` platform generation are skipped. Skill symlink sync still runs. If the agent's directory does not exist (e.g. `~/.copilot`), it will be created automatically.
 
@@ -725,7 +663,7 @@ This project builds on [Jesse Vincent's Superpowers for Claude Code](https://git
 - OpenCode plugin architecture pattern
 - Test infrastructure for skill validation
 
-This fork extends that vision to support agent-agnostic workflows across multiple AI coding assistants including GitHub Copilot, Cursor, Gemini, OpenCode, and Codex.
+This fork extends that vision to support agent-agnostic workflows across GitHub Copilot, Claude Code, and OpenCode.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@complexthings/superpowers-agent",
-  "version": "8.4.1",
+  "version": "9.0.1",
   "description": "Superpowers agent CLI — skills system for AI coding agents",
   "type": "module",
   "bin": {
@@ -25,9 +25,7 @@
   "engines": {
     "node": "^20 || ^22 || ^24"
   },
-  "scripts": {
-    "postinstall": "node .agents/superpowers-agent bootstrap --no-update 2>/dev/null || true"
-  },
+  "scripts": {},
   "author": {
     "name": "Greg Harvell",
     "email": "greg.harvell@complexthings.com",
@@ -35,7 +33,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/complexthings/superpowers.git"
+    "url": "git+https://github.com/complexthings/superpowers.git"
   },
   "bugs": {
     "url": "https://github.com/complexthings/superpowers/issues"

package/skills/collaboration/leveraging-cli-tools/SKILL.md

@@ -1,132 +1,79 @@
 ---
 name: leveraging-cli-tools
-description: Use when performing code searches, JSON parsing, file viewing, or file finding tasks - ensures agents verify and use high-performance CLI tools (rg, jq, fd, bat, ast-grep) instead of slower standard tools, reducing token costs and latency by 5-50x
+description: Use when performing code searches, JSON/YAML parsing, file finding, structural refactors, or data wrangling - ensures agents reach for high-performance CLI tools (rg, jq, fd, yq, ast-grep, gh, sd) over slower standard tools like grep/find/sed, cutting token cost and latency 5-50x. Check availability and offer to install a tool when a relevant task arises.
 ---
 
 # Leveraging CLI Tools
 
-## Core Principle
+## Purpose
 
-**High-performance CLI tools reduce costs, latency, and cognitive load by 5-50x.**
+Reach for high-performance CLI tools over slower standard tools. The leverage is filtering and transforming with the right tool **before reading**, so tokens and time go to the answer, not the search. On a large tree `rg` is 10-50x faster than `grep` and returns far less noise; across a session that compounds into hours and tens of thousands of tokens saved.
 
-Modern tools have massive RL optimization in frontier models - use them.
+## When a relevant task arises
 
-## Tool Availability Protocol
+1. Pick the right tool from the table below.
+2. Confirm it's installed before relying on it — e.g. `command -v rg`.
+3. If it's missing, name the tool and its payoff and **offer** to install it — don't install silently. Adapt the command to the user's package manager/OS (the table shows `brew`; substitute `apt install`, `dnf install`, `pacman -S`, `cargo install`, etc.). If they decline, fall back to the standard tool and move on.
 
-**Session start (silent check, cache result):**
+Check only the tools the current task needs — no upfront session-wide scan.
 
-```bash
-command -v rg jq fd bat gh >/dev/null 2>&1 && echo "ready" || echo "missing"
-```
-
-**If tools missing:** Offer installation when relevant task appears.
-**If tools ready:** Use optimal workflows throughout session.
-
-## Tool Selection
-
-| Task | Use | Instead of | Speedup |
-|------|-----|-----------|---------|
-| Search code | **rg** | grep | 10-50x |
-| Parse JSON | **jq** | awk/sed | 5-20x |
-| Find files | **fd** | find | 5-10x |
-| View code | **bat** | cat | Better UX |
-| Transform code | **ast-grep** | sed | 3-10x |
-| GitHub ops | **gh** | curl+API | 2-5x |
-| Interactive select | **fzf** | manual | 10-100x |
-
-## Quick Reference
-
-### Code Search: rg
-```bash
-rg "AuthError" --type typescript  # 10-50x faster than grep, respects .gitignore
-```
+## Tools
 
-### JSON Parse: jq
-```bash
-jq '.results[] | select(.status=="error") | .error.code' api.json | sort -u
-```
-
-### Find Files: fd
-```bash
-fd "\.test\.ts$"  # 5-10x faster than find, parallel traversal
-```
+| Rating | Tool | Replaces | Why | Install |
+|:------:|------|----------|-----|---------|
+| 10 | `rg` (ripgrep) | `grep`, `grep -r`, `ack` | Code/text search. Respects `.gitignore`, 10-50x faster than `grep` — the highest-leverage tool; filter before reading. | `brew install ripgrep` |
+| 10 | `jq` | `grep`/`sed`/`awk` on JSON | JSON query/transform. Turns API responses and config into exactly the fields you need; the pipe target for JSON. | `brew install jq` |
+| 9 | `fd` | `find` | File finding. Faster, saner syntax, parallel traversal, `.gitignore`-aware. | `brew install fd` |
+| 8 | `yq` | `grep`/`sed`/`awk` on YAML | `jq` for YAML/TOML/XML. Reads CI files, `docker-compose`, k8s manifests, frontmatter. | `brew install yq` |
+| 8 | `ast-grep` (`sg`) | `sed`/`grep` for refactors | Structural search/rewrite by AST, not regex. Safe codebase-wide refactors that `sed` would mangle. | `brew install ast-grep` |
+| 8 | `gh` | `curl` + GitHub API + tokens | GitHub from the shell — PRs, issues, CI, API. No hand-rolled `curl` + token juggling. | `brew install gh` |
+| 7 | `sd` | `sed -i`, `perl -pe` | Find/replace. Literal-string-safe, no regex-escaping footguns. | `brew install sd` |
+| 6 | `dasel` | `jq`+`yq`+`xq` (mixed formats) | Query *and modify* JSON/YAML/TOML/XML/CSV through one selector. Use when format is mixed or unknown. | `brew install dasel` |
+| 6 | `htmlq` | `grep`/`sed` on HTML | `jq` for HTML — CSS-selector extraction from fetched pages. | `brew install htmlq` |
+| 6 | `miller` (`mlr`) | `awk`/`cut`/`join`/`sort` on CSV/TSV | `awk`/`cut`/`join`/`sort` for CSV/TSV/JSON with *named* fields — no brittle column counting. | `brew install miller` |
+| 5 | `qsv` | `awk`/`cut`/`sort -u` on CSV, `csvkit` | High-perf CSV toolkit (maintained `xsv` successor). Stats, slice, join, dedup on big CSVs. | `brew install qsv` |
+| 5 | `hyperfine` | `time`, `for`-loop timing | Statistical benchmarking with warmups. Real before/after numbers, not `time` guesses. | `brew install hyperfine` |
+| 5 | `tokei` | `wc -l`, `find … \| wc`, `cloc` | Instant LOC/language breakdown. Orient in an unfamiliar repo before exploring. | `brew install tokei` |
+| 5 | `fzf` (`-f`) | manual fuzzy filtering | Non-interactive `-f`/`--filter` mode: fuzzy-rank a candidate list piped from `fd`/`rg`. | `brew install fzf` |
+| 4 | `watchexec` | `while`+`sleep`, `entr` | Run a command on file change. Useful in build/test loops; non-interactive unlike most watchers. | `brew install watchexec` |
 
-### View Code: bat
-```bash
-bat src/auth.ts  # Syntax highlighting, Git integration, line numbers
-```
+## Core workflows
 
-### Code Transform: ast-grep
+**Filter before reading** — find the matches, then read only those.
 ```bash
-sg --pattern 'console.log($$$ARGS)' --rewrite 'logger.debug($$$ARGS)'
+rg -l "password.*hash" src/auth/ --type ts | xargs rg "TODO"
 ```
 
-## Installation Protocol
-
-**If tool missing when needed:**
-
-1. Explain impact: "Using rg is 10-50x faster, reducing token costs"
-2. Install automatically for core tools (rg, jq, fd, bat, gh): `brew install ripgrep jq fd bat gh` (macOS) or equivalent
-3. Ask before installing: ast-grep, httpie, fzf
-
-**No exceptions:** If tool unavailable and user declines install, explain performance cost but use fallback.
-
-## Key Workflows
-
-### Filter Before Reading
+**Compose tools** — search, parse, dedup in one pass.
 ```bash
-# DON'T: Read all files blindly
-# DO: Filter first, read matches only
-rg "password.*hash" src/auth/ --type ts -l | xargs bat
+rg -l '"error"' logs/ --type json | xargs jq -r 'select(.level=="error") | .code' | sort -u
 ```
 
-Under fatigue: filtering first reduces cognitive load.
-
-### Compose Tools
+**Structural rewrite, not regex** — refactor by AST so syntax can't trip you.
 ```bash
-rg "error.code" logs/ -o | jq -r . | sort -u  # Search + parse + dedup
+sg --pattern 'console.log($$$A)' --rewrite 'logger.debug($$$A)' --lang ts
 ```
 
-## Performance Impact
-
-| Task | grep/find/cat | rg/fd/bat | Savings |
-|------|---------------|-----------|---------|
-| Search 50k files | 45s | 0.8s | 56x, ~40k tokens |
-| Parse 10MB JSON | 12s (awk) | 2s (jq) | 6x, ~15k tokens |
-| Find in monorepo | 8s | 1s | 8x, ~10k tokens |
+In Claude Code the `Grep` and `Glob` tools are themselves built on ripgrep — prefer them for in-context searches, and reach for the CLI tools when you need piping, transforms, or rewrites.
 
-## Red Flags
+## Red flags
 
-- Manually parsing JSON with awk/sed/grep (use jq)
-- Reading files without filtering first (use rg to filter)
-- Not checking tool availability at session start
-- Using bash grep when Grep tool exists (use Grep tool)
+- Parsing JSON/YAML with `awk`/`sed`/`grep` instead of `jq`/`yq`.
+- Reading files before filtering them with `rg`.
+- Hand-rolling `curl` against the GitHub API instead of `gh`.
+- Regex codemods with `sed` where `ast-grep` is structurally safe.
 
-## Common Rationalizations
+## Common rationalizations
 
 | Excuse | Reality |
 |--------|---------|
-| "grep works fine" | 50x slower, burns 40k tokens on 50k files |
-| "I don't know if they have jq" | Check once, install takes 30s, saves hours |
-| "Not worth setup overhead" | One install = 10-100x speedup on ALL future tasks |
-| "User didn't ask for optimization" | Faster task completion IS better completion |
-
-## When NOT to Use
-
-**Skip when:**
-- Small dataset (< 100 files, < 1MB) AND one-off task
-- User explicitly declines install
-- Teaching context where standard tools are the goal
-
-**Use when:**
-- Codebase search (always)
-- JSON operations (always)
-- Time pressure, large datasets, repeated operations
-
-## Summary
-
-**Protocol: Check → Use → Combine**
+| "grep works fine" | On a big tree it's 10-50x slower and floods context with noise `rg` would have filtered out. |
+| "I don't know if they have jq" | One `command -v jq` answers it; install is seconds and pays back across the whole session. |
+| "Not worth the setup" | One install = a speedup on every future task, not just this one. |
+| "User didn't ask for optimization" | Faster, lower-noise completion *is* better completion. |
 
-Session start: Silent availability check. Task appears: Use optimal tool or install. Complex tasks: Compose tools.
+## When NOT to use
 
-**Not using available tools burns resources.**
+- A tiny one-off (a handful of files, well under a megabyte) where the standard tool is already at hand.
+- The user declined the install — note the cost once, then use the fallback.
+- A teaching context where the standard tool is the point.