@complexthings/superpowers-agent 9.2.1 → 10.0.1

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

@@ -1,111 +1,110 @@
 ---
 name: leveraging-cli-tools
-description: Use when performing code searches, JSON/YAML parsing, file finding, structural refactors, or data wrangling, or when a command floods context with verbose output like logs, CI, or test runs - ensures agents reach for high-performance CLI tools (rg, jq, fd, yq, ast-grep, gh, sd) over slower standard tools like grep/find/sed and use them with discipline, choosing the right output-reducing flags, composing pipelines so raw output never enters context, and using a bundled reducer for output that flags cannot shape, cutting token cost and latency 5-50x. Check availability and offer to install a tool when a relevant task arises.
-compatibility: The bundled scripts/slim.py needs python3 (standard on macOS/Linux). The CLI tools install via the system package manager.
+description: Use when performing code searches, JSON/YAML parsing, file finding, structural refactors, or data wrangling, or when a command could flood context with verbose output like logs, CI runs, test output, or git/docker status dumps. Routes agents to `rtk` (Rust Token Killer), a token-optimized CLI proxy that wraps ripgrep, jq, git, gh, test runners, and more, and to `ponytail` for lazy-solution discipline — instead of reaching for raw grep/find/sed/awk or a per-tool checklist. Also sets up rtk and ponytail for the current harness if either isn't configured yet.
 ---
 
 # Leveraging CLI Tools
 
-## Purpose
+The leverage is filtering and transforming with the right tool **before reading**, so tokens and time go to the answer, not the search. `rtk` is the single entry point for that: it wraps the high-performance CLI tools (ripgrep, jq, git, gh, test runners, and more) and returns token-optimized output automatically, and `rtk proxy` reaches anything it doesn't wrap. `ponytail` supplies the "laziest solution that works" discipline alongside it.
 
-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.
+**This supersedes the old approach of memorizing a table of ~16 individual tools (`rg`, `jq`, `fd`, `yq`, `ast-grep`, `sd`, …) and reaching for each one raw.** If you find yourself reconstructing that table from memory, stop — reach for `rtk <tool>` instead, and `rtk proxy <tool>` for anything `rtk` doesn't wrap directly.
 
-Picking the faster tool is only half of it. The other half is using it with discipline — two levers that keep raw output out of your context: **ask for less** (the right flags and selectors), and **shrink what you can't shape** (a reducer for inherently verbose output). A fast tool fed a lazy command still floods your context.
+## Setup rtk
 
-## When a relevant task arises
+Before relying on `rtk`, verify it's configured for the current harness:
 
-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.
+```bash
+bash scripts/setup-rtk.sh
+```
+
+(relative to this skill directory — use the absolute path if you're working elsewhere). This script only **checks and reports**; it never changes anything by itself. It:
+
+1. Detects the current harness (Claude Code, OpenCode, pi, codex, GitHub Copilot).
+2. Checks whether `rtk` is installed and wired into that harness's config (e.g. `rtk init --show` for Claude Code; the harness-specific config file for others).
+3. If everything is already `[ok]`, does nothing further — you're set, move on.
+4. If something's missing, prints the exact command(s) it would run to fix it (e.g. `rtk init --auto-patch`, `rtk init -g --auto-patch`, `rtk init -g --opencode`, `rtk init --codex`).
+
+Anything the script reports missing is a **global or repo-config change** — never run the fix command on your own initiative. Surface the report and the exact command(s) to the user and get their confirmation first (see "Ask before you act" below). If the fix touches Claude Code's own config, tell the user to restart Claude Code afterward so the new config is picked up.
 
-Check only the tools the current task needs — no upfront session-wide scan.
+## Setup ponytail
+
+Same check → report → confirm pattern, for the `ponytail` discipline skill:
+
+```bash
+bash scripts/setup-ponytail.sh
+```
 
-## Tools
+It checks that `ponytail` is installed for the current harness (marketplace/plugin/package presence) and that `~/.config/ponytail/config.json` exists. If the config is missing, it offers to create it with `defaultMode: full` — it only ever creates an absent file, it never edits or overwrites one that already exists. Confirm the offered command with the user, same as rtk setup, before it runs.
 
-| 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` |
+On GitHub Copilot, also check whether this repo's `.github/copilot-instructions.md` already carries the rtk + ponytail instructions. If not, `references/copilot-instructions.md` (bundled with this skill) is the source of truth to append — offer that too, and confirm before writing.
 
-## Use them with discipline
+### Ask before you act
 
-Five habits separate a fast, low-noise result from a slow, context-flooding one. The token savings below are measured, not hypothetical.
+Any setup step that touches global or machine state — installing a package, writing outside this task's working files, editing a config in `$HOME` — gets surfaced and confirmed, never run silently. Ask with whichever question tool your harness exposes: `askUserQuestion`, `ask_user_question`, `askQuestions`, or `question`. Same rule elsewhere in this skill: when you're unsure whether a change is welcome, ask instead of guessing.
 
-**1 — Pick the tool that fits the data, not the one in muscle memory.** JSON → `jq`, YAML/TOML → `yq`, structural refactor → `ast-grep`, GitHub → `gh`. The reflex to resist is `grep`/`sed`/`awk` on structured data — they treat structure as flat text, so you pay in escaping bugs and noise the format-aware tool never produces.
+## Use rtk with discipline
+
+Picking `rtk` is only half of it. The other half is using it with discipline — the same habits that used to be spread across a dozen raw tools, now aimed at `rtk`'s subcommands.
+
+**1 — Reach for `rtk <tool>` for the data's shape, not a raw tool from muscle memory.** Code/text search → `rtk rg`, JSON → `rtk jq`, git/gh → `rtk git` / `rtk gh`, verbose command output (tests, CI, builds) → the matching `rtk` wrapper (`rtk cargo test`, `rtk playwright test`, `rtk jest`, …). The reflex to resist is reaching for `grep`/`sed`/`awk` on structured data, or a raw tool `rtk` already wraps — both throw away the reduction `rtk` gives you for free.
+
+**Prefer `rtk rg` over `rtk grep`.** They cover the same ground, but `rtk rg` runs ripgrep underneath and is faster and more efficient — use it as the default for code/text search.
+
+**This includes interpreters and runners you'd otherwise call bare.** Run scripts through `rtk` too — `rtk python script.py`, `rtk python -c '...'` (and likewise `rtk node …`) — so their output stays inside the same token-optimized, usage-tracked invocation instead of dropping to raw `python3`/`node`.
 
 **2 — Ask for less: use the flag or selector that returns the answer's _shape_.** The biggest single win is never pulling raw output into context. Match the request to the question:
 
-| Question | Flag / selector | Returns |
-|----------|-----------------|---------|
-| Which files match? | `rg -l` | paths only, no lines |
-| How many files? | `rg -l \| wc -l` | a file count, not a line count |
-| How many hits? | `rg -c` (lines/file) / `rg --count-matches` (matches/file) | counts only |
-| Just the matched bit? | `rg -o` | the substring, not the whole line |
-| Enough to judge a hit? | `rg -A/-B/-C N`, `rg -m N` (cap per file) | bounded context |
-| Only certain fields? | `jq -r '.a, .b'`, `yq`, `mlr --opprint cut -f` | projected values, not the whole doc |
-| First N of a list? | pipe to `head`, or `fd --max-results N` | the slice you need |
+| Question | Command | Returns |
+|----------|---------|---------|
+| Which files match? | `rtk rg -l` | paths only, no lines |
+| How many files? | `rtk rg -l \| wc -l` | a file count, not a line count |
+| How many hits? | `rtk rg -c` (lines/file) / `rtk rg --count-matches` (matches/file) | counts only |
+| Just the matched bit? | `rtk rg -o` | the substring, not the whole line |
+| Enough to judge a hit? | `rtk rg -A/-B/-C N`, `rtk rg -m N` (cap per file) | bounded context |
+| Only certain fields? | `rtk jq -r '.a, .b'` | projected values, not the whole doc |
+| Which files, by dir? | `rtk find <pattern>` | paths grouped by directory |
+| Only the errors? | `rtk err <cmd>` | filtered stderr/error lines |
 
-For the **projection tools** (`jq`, `yq`, `dasel`, `miller`, `htmlq`) the selector *is* the filter — `jq` turning a 2,000-record array into one summed number is a ~100% reduction on its own. Shape their output at the selector; never post-filter it (that's what habit 4 is *not* for).
+Shape output at the selector; never pull the whole thing into context and filter it by eye.
 
 **3 — Compose so only the answer comes back.** Do the counting, dedup, and projection *in the pipeline*, not by reading raw output and reasoning over it. One pass keeps every intermediate result out of context:
 ```bash
-rg -l '"error"' logs/ --type json | xargs jq -r 'select(.level=="error") | .code' | sort -u
-```
-This is the lesson of programmatic tool calling (Amazon's PTC benchmarks: ~87-92% fewer tokens): when a task needs several tool calls plus processing, write **one** pipeline or script that does it all and returns only the result — the intermediate data never touches your context. So: filter before reading, and refactor by AST, not regex:
-```bash
-rg -l "password.*hash" src/auth/ --type ts | xargs rg "TODO"
-sg --pattern 'console.log($$$A)' --rewrite 'logger.debug($$$A)' --lang ts
+rtk rg -l '"error"' logs/ --type json | xargs rtk jq -r 'select(.level=="error") | .code' | sort -u
 ```
+When a task needs several tool calls plus processing, write **one** pipeline that does it all and returns only the result — the intermediate data never touches your context.
 
-**4 — Shrink what you can't shape: the bundled reducer for verbose emitters.** Some output has no projection flag — logs, CI output (`gh run view --log`), test runs, stack traces, status dumps. Flags get you part way, but the residual stays repetitive, wide, and noisy. Pipe it through `scripts/slim.py` (relative to this skill; use its absolute path if you're working elsewhere) and ask only for the cuts the task needs:
-```bash
-gh run view --log | python3 scripts/slim.py --errors --uniq --max-line 200
-cargo test 2>&1   | python3 scripts/slim.py --errors --dedup
-rg -n TODO --no-ignore | python3 scripts/slim.py --group-dir
-```
-It does dedup (`--dedup`/`--uniq`, repeats collapse to `(xN)`), grouping (`--group-dir` → per-directory counts), truncation (`--head/--tail/--middle/--max-line`), and noise-stripping (`--comments/--errors/--grep`). On a real 1,236-line CI log, `rg` error-filtering alone cut 91% but left ~6,700 tokens; adding `slim` reached 97% — a third the residual. Run `python3 scripts/slim.py -h` for all modes. The cuts are **lossy and opt-in**: ask for what you need, know what you're discarding, and don't reach for it when a projection tool's own selector would do the job.
+**4 — When `rtk` has no wrapper for a tool, use `rtk proxy <cmd>` instead of the raw command.** `rtk proxy` runs anything raw while keeping it inside the same invocation pattern — e.g. `rtk proxy ast-grep --pattern '...' --lang ts`, `rtk proxy yq '.services' docker-compose.yml`, `rtk proxy sd 'old' 'new' file.ts`. Reach for `rtk <tool>` first; fall back to `rtk proxy <tool>` only when `rtk` doesn't wrap it.
 
-**5 — Read the output critically — it's a claim, not a fact.** A zero or suspiciously low result is the one to distrust: `rg` skips `.gitignore`d and hidden files by default, so a real match in `node_modules/`, `dist/`, or a dotfile is silently absent. Before concluding "none," re-run with `--no-ignore`, `-uu`, or `--hidden` — then decide whether those ignored hits (vendored deps, build output, generated mirrors) actually belong in the answer; surfacing them is the check, keeping them is a judgment call. Mind case (`-i`) and word boundaries (`-w`) so you neither miss `Subagent` nor over-match `tasks` — and when an identifier doubles as a common word (a `Task` tool vs. the word "task"), even `-w` isn't enough: glance at the context to confirm the hit is the symbol, not prose. When a count or list drives a decision, confirm a match means what you think before acting on it.
+**5 — Read the output critically — it's a claim, not a fact.** A zero or suspiciously low result is the one to distrust: `rtk rg` respects `.gitignore`/`.ignore` by default, so a real match in `node_modules/`, `dist/`, or a dotfile is silently absent. Before concluding "no matches," re-run with `--no-ignore` (or `-u`/`-uu`/`--hidden`) — then decide whether those ignored hits (vendored deps, build output, generated mirrors) actually belong in the answer; surfacing them is the check, keeping them is a judgment call. Mind case (`-i`) and word boundaries (`-w`) so you neither miss a hit nor over-match a common word.
 
-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, rewrites, or output reduction.
+In Claude Code the `Grep` and `Glob` tools are themselves built on ripgrep — prefer them for in-context searches, and reach for `rtk` on the command line when you need piping, transforms, rewrites, or output reduction.
 
 ## Red flags
 
-- Parsing JSON/YAML with `awk`/`sed`/`grep` instead of `jq`/`yq`.
-- Reading files before filtering them with `rg`.
-- Piping a tool's full output into context to eyeball it, when `-l`/`-c`/`-o` or a `jq` projection would return just the answer.
-- Letting a verbose command (test run, CI log, `git`/`docker` status dump) land raw in context when `slim` would cut it 90%+.
-- Reaching for `slim` on a projection tool's output — shape it at the `jq`/`yq`/`mlr` selector instead.
-- Concluding "no matches" from a default `rg` run without re-checking `--no-ignore`/`--hidden` — the hit may be sitting in an ignored directory.
-- Hand-rolling `curl` against the GitHub API instead of `gh`.
-- Regex codemods with `sed` where `ast-grep` is structurally safe.
+- Parsing JSON/YAML with `awk`/`sed`/`grep` instead of `rtk jq` / `rtk proxy yq`.
+- Reading files before filtering them with `rtk rg`.
+- Reaching for `rtk grep` by habit when `rtk rg` covers the same ground faster.
+- Running a tool raw (`ast-grep`, `yq`, `sd`, …) when `rtk proxy <tool>` would give the same result inside the standard invocation pattern.
+- Running an interpreter raw (`python3`, `node`, …) when `rtk python` / `rtk node` would keep it inside rtk's optimized invocation.
+- Piping a command's full output into context to eyeball it, when `-l`/`-c`/`-o` or a `rtk jq` projection would return just the answer.
+- Concluding "no matches" from a default `rtk rg` run without re-checking `--no-ignore`/`--hidden` — the hit may be sitting in an ignored directory.
+- Hand-rolling `curl` against the GitHub API instead of `rtk gh`.
+- Reconstructing the old 16-tool table from memory instead of reaching for `rtk`.
+- Running a setup fix (`rtk init --auto-patch`, creating `~/.config/ponytail/config.json`, etc.) without confirming with the user first.
 
 ## Common rationalizations
 
 | Excuse | Reality |
 |--------|---------|
-| "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. |
-| "The test/CI output is just long, I'll scroll it" | A 1,200-line log is ~75k tokens of mostly noise; `slim --errors --uniq` makes it ~2k without losing the failures. |
+| "grep works fine" | On a big tree it's 10-50x slower and floods context with noise `rtk rg` would have filtered out. |
+| "I don't know if rtk is set up" | `bash scripts/setup-rtk.sh` answers it in one check; fixing it pays back across the whole session. |
+| "Not worth the setup" | One confirmed fix = a speedup on every future task, not just this one. |
+| "The test/CI output is just long, I'll scroll it" | `rtk`'s wrappers (`rtk cargo test`, `rtk playwright test`, …) cut that noise automatically — scrolling raw output throws that away. |
+| "This tool isn't in rtk's table, I'll just run it raw" | `rtk proxy <tool>` runs it inside the same pattern — no need to drop back to the bare command. |
 | "User didn't ask for optimization" | Faster, lower-noise completion *is* better completion. |
 
 ## When NOT to use
 
-- 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.
+- The user declined an rtk/ponytail setup fix — note it once, then fall back to the raw tool and move on.
 - A teaching context where the standard tool is the point.
-- Output you already shaped with a selector — don't add a `slim` pass for its own sake.
+- Output you already shaped with a selector — don't add another reduction pass for its own sake.

package/skills/collaboration/leveraging-cli-tools/references/copilot-instructions.md

@@ -0,0 +1,30 @@
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

package/skills/collaboration/leveraging-cli-tools/scripts/setup-ponytail.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# setup-ponytail.sh — verify (and optionally install) the ponytail plugin for
+# whichever agent harness is currently running this script.
+#
+# Contract (same as setup-rtk.sh):
+#   - Default (no flags): CHECK + REPORT ONLY. Detects the current harness,
+#     prints what's installed/missing and the exact command(s) that WOULD
+#     run. Changes nothing on disk or in any plugin registry.
+#   - `--apply`: actually runs the planned install commands / writes the
+#     planned files.
+#   - Idempotent, create-if-absent only. Never overwrites an existing file
+#     (in particular ~/.config/ponytail/config.json is left untouched once
+#     it exists).
+#
+# Usage:
+#   scripts/setup-ponytail.sh            # check only, changes nothing
+#   scripts/setup-ponytail.sh --apply    # apply the plan reported above
+
+set -euo pipefail
+
+APPLY=0
+[[ "${1:-}" == "--apply" ]] && APPLY=1
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COPILOT_ASSET="$SCRIPT_DIR/../references/copilot-instructions.md"
+GAPS=0
+
+ok()   { printf '  [ok] %s\n' "$*"; }
+gap()  { printf '  [MISSING] %s\n' "$*"; GAPS=$((GAPS + 1)); }
+plan() { printf '  would run: %s\n' "$*"; }
+
+# --- detect harness ---------------------------------------------------------
+# Lazy heuristic: env vars first (cheapest, most specific), config dir
+# presence as fallback. Claude Code is checked first since it sets an
+# unambiguous env var even when other harnesses' dirs also exist.
+harness=""
+if [[ -n "${CLAUDECODE:-}" || -n "${CLAUDE_CODE_ENTRYPOINT:-}" ]]; then
+  harness="claude"
+elif [[ -n "${CODEX_HOME:-}" || -d "$HOME/.codex" ]]; then
+  harness="codex"
+elif [[ -n "${GITHUB_COPILOT_CLI:-}" || -d "$HOME/.copilot" ]]; then
+  harness="copilot"
+elif [[ -n "${OPENCODE_MODEL:-}" || -d "$HOME/.config/opencode" ]]; then
+  harness="opencode"
+elif [[ -d "$HOME/.pi" ]]; then
+  harness="pi"
+fi
+
+if [[ -z "$harness" ]]; then
+  echo "Could not detect a known agent harness (Claude Code, OpenCode, pi, codex, Copilot). Nothing to check."
+  exit 0
+fi
+
+echo "Detected harness: $harness"
+echo
+
+case "$harness" in
+  claude)
+    dir="$HOME/.claude/plugins/marketplaces/ponytail"
+    if [[ -d "$dir" ]]; then
+      ok "ponytail marketplace present ($dir)"
+    else
+      gap "ponytail marketplace not found ($dir)"
+      plan "claude plugin marketplace add DietrichGebert/ponytail && claude plugin install ponytail@ponytail"
+      if [[ $APPLY -eq 1 ]]; then
+        claude plugin marketplace add DietrichGebert/ponytail
+        claude plugin install ponytail@ponytail
+        echo "  -> installed. Run /reload-plugins in Claude Code to pick it up."
+      fi
+    fi
+    ;;
+
+  opencode)
+    cfg="$HOME/.config/opencode/opencode.json"
+    if [[ -f "$cfg" ]] && grep -q '@dietrichgebert/ponytail' "$cfg"; then
+      ok "ponytail listed in $cfg"
+    else
+      gap "ponytail not listed in $cfg"
+      plan "add \"@dietrichgebert/ponytail\" to the \"plugins\" array in $cfg"
+      if [[ $APPLY -eq 1 ]]; then
+        if command -v jq >/dev/null 2>&1 && [[ -f "$cfg" ]]; then
+          tmp="$(mktemp)"
+          jq '.plugins = ((.plugins // []) + ["@dietrichgebert/ponytail"] | unique)' "$cfg" > "$tmp" && mv "$tmp" "$cfg"
+        elif command -v jq >/dev/null 2>&1; then
+          mkdir -p "$(dirname "$cfg")"
+          printf '{"plugins":["@dietrichgebert/ponytail"]}\n' > "$cfg"
+        else
+          echo "  -> jq not found; edit $cfg manually and add \"@dietrichgebert/ponytail\" to \"plugins\"." >&2
+        fi
+        echo "  -> restart opencode."
+      fi
+    fi
+    ;;
+
+  pi)
+    cfg="$HOME/.pi/agent/settings.json"
+    if [[ -f "$cfg" ]] && grep -q 'git:github.com/DietrichGebert/ponytail' "$cfg"; then
+      ok "ponytail listed in $cfg"
+    else
+      gap "ponytail not listed in $cfg"
+      plan "pi install git:github.com/DietrichGebert/ponytail"
+      if [[ $APPLY -eq 1 ]]; then
+        pi install git:github.com/DietrichGebert/ponytail
+        echo "  -> restart pi."
+      fi
+    fi
+    ;;
+
+  codex)
+    dir="$HOME/.codex/plugins/cache/ponytail"
+    if [[ -d "$dir" ]]; then
+      ok "ponytail plugin cache present ($dir)"
+    else
+      gap "ponytail plugin cache not found ($dir)"
+      plan "codex plugin marketplace add DietrichGebert/ponytail && codex plugin add ponytail@ponytail"
+      if [[ $APPLY -eq 1 ]]; then
+        codex plugin marketplace add DietrichGebert/ponytail
+        codex plugin add ponytail@ponytail
+        echo "  -> restart codex."
+      fi
+    fi
+    ;;
+
+  copilot)
+    dir="$HOME/.copilot/installed-plugins/ponytail"
+    if [[ -d "$dir" ]]; then
+      ok "ponytail plugin present ($dir)"
+    else
+      gap "ponytail plugin not found ($dir)"
+      plan "copilot plugin marketplace add DietrichGebert/ponytail && copilot plugin install ponytail@ponytail"
+      if [[ $APPLY -eq 1 ]]; then
+        copilot plugin marketplace add DietrichGebert/ponytail
+        copilot plugin install ponytail@ponytail
+        echo "  -> restart copilot."
+      fi
+    fi
+
+    repo_asset="./.github/copilot-instructions.md"
+    if [[ -f "$repo_asset" ]] && grep -q 'Ponytail, lazy senior dev mode' "$repo_asset"; then
+      ok "$repo_asset already has ponytail instructions"
+    elif [[ -f "$repo_asset" ]]; then
+      gap "$repo_asset exists but lacks ponytail instructions"
+      plan "append $COPILOT_ASSET to $repo_asset"
+      if [[ $APPLY -eq 1 ]]; then
+        { echo; cat "$COPILOT_ASSET"; } >> "$repo_asset"
+      fi
+    else
+      gap "$repo_asset not found"
+      plan "create $repo_asset from $COPILOT_ASSET"
+      if [[ $APPLY -eq 1 ]]; then
+        mkdir -p "$(dirname "$repo_asset")"
+        cp "$COPILOT_ASSET" "$repo_asset"
+      fi
+    fi
+    ;;
+esac
+
+# --- all harnesses: global ponytail config, create-if-absent only ----------
+if [[ -n "${APPDATA:-}" ]]; then
+  ponytail_cfg="$APPDATA/ponytail/config.json"
+else
+  ponytail_cfg="$HOME/.config/ponytail/config.json"
+fi
+
+echo
+if [[ -f "$ponytail_cfg" ]]; then
+  ok "$ponytail_cfg already exists (left untouched)"
+else
+  gap "$ponytail_cfg not found"
+  plan "create $ponytail_cfg with {\"defaultMode\":\"full\"}"
+  if [[ $APPLY -eq 1 ]]; then
+    mkdir -p "$(dirname "$ponytail_cfg")"
+    printf '{"defaultMode":"full"}\n' > "$ponytail_cfg"
+    echo "  -> created $ponytail_cfg"
+  fi
+fi
+
+echo
+if [[ $GAPS -eq 0 ]]; then
+  echo "All ponytail checks passed for harness: $harness."
+elif [[ $APPLY -eq 1 ]]; then
+  echo "Applied plan for $GAPS gap(s)."
+else
+  echo "$GAPS gap(s) found. Re-run with --apply to fix."
+fi

package/skills/collaboration/leveraging-cli-tools/scripts/setup-rtk.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# setup-rtk.sh — verify rtk is configured for the current agentic harness.
+#
+# Contract:
+#   - Default (no args): CHECK + REPORT only. Detects the harness, prints
+#     config status per-check ([ok]/[missing]), and prints the EXACT rtk
+#     commands that would fix any gap. Changes NOTHING.
+#   - `--apply`: runs the planned fix commands for the DETECTED harness only.
+#     Every fix is a call to `rtk init ...`, which is itself create-if-absent
+#     and never overwrites existing config, so re-running is always safe.
+#   - If the harness can't be determined, every harness is checked read-only
+#     and nothing is ever applied (there's no single harness to act on).
+#
+# Usage:
+#   scripts/setup-rtk.sh            # check + report (safe, default)
+#   scripts/setup-rtk.sh --apply    # run the planned fix commands
+
+set -euo pipefail
+
+APPLY=false
+if [ "${1:-}" = "--apply" ]; then
+  APPLY=true
+fi
+
+if ! command -v rtk >/dev/null 2>&1; then
+  echo "[--] rtk is not installed or not on PATH — nothing to check."
+  echo "     Install rtk first, then re-run this script."
+  exit 1
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+PLANNED=()
+
+plan() {
+  PLANNED+=("$1")
+  echo "  planned: $1"
+}
+
+run_planned() {
+  for cmd in "${PLANNED[@]}"; do
+    echo "  running: $cmd"
+    eval "$cmd"
+  done
+}
+
+# --- Harness detection -------------------------------------------------
+# Sensible, lazy heuristic: harness-specific env vars first, then config
+# dirs. Order matters — check the most specific/reliable signal first.
+detect_harness() {
+  if [ -n "${CLAUDECODE:-}" ] || [ -n "${CLAUDE_CODE_ENTRYPOINT:-}" ]; then
+    echo claude; return
+  fi
+  if [ -n "${CODEX_SANDBOX:-}" ] || [ -n "${CODEX_HOME:-}" ]; then
+    echo codex; return
+  fi
+  if [ -n "${OPENCODE_MODEL:-}" ] || [ -d "$HOME/.config/opencode" ] && [ -n "${OPENCODE_EXPERIMENTAL_MARKDOWN:-}${OPENCODE_BIN_PATH:-}" ]; then
+    echo opencode; return
+  fi
+  if [ -n "${PI_AGENT:-}" ] || [ -n "${PI_HOME:-}" ]; then
+    echo pi; return
+  fi
+  if [ -n "${GITHUB_COPILOT_CLI:-}" ] || [ -n "${COPILOT_AGENT:-}" ]; then
+    echo copilot; return
+  fi
+  echo unknown
+}
+
+# --- Per-harness checks -------------------------------------------------
+# Each check prints [ok]/[missing] status lines and calls `plan` for any
+# gap. None of these mutate anything by themselves.
+
+check_claude() {
+  echo "Claude Code:"
+  local show
+  show="$(rtk init --show 2>&1)"
+  local core global_bad local_bad
+  core="$(printf '%s\n' "$show" | grep -E '(Hook:|RTK\.md:|Global \(|Local \(|settings\.json:)' || true)"
+  global_bad="$(printf '%s\n' "$core" | grep -v 'Local (' | grep -v '^\[ok\]' || true)"
+  local_bad="$(printf '%s\n' "$core" | grep 'Local (' | grep -v '^\[ok\]' || true)"
+
+  if [ -z "$global_bad" ] && [ -z "$local_bad" ]; then
+    echo "$core" | sed 's/^/  /'
+    echo "  [ok] rtk fully configured for Claude Code"
+    return
+  fi
+
+  echo "$core" | sed 's/^/  /'
+  if [ -n "$global_bad" ]; then
+    plan "rtk init -g --auto-patch"
+  fi
+  if [ -n "$local_bad" ]; then
+    plan "rtk init --auto-patch"
+  fi
+  CLAUDE_NEEDS_RESTART=true
+}
+
+check_opencode() {
+  echo "OpenCode:"
+  local plugin="$HOME/.config/opencode/plugins/rtk.ts"
+  if [ -f "$plugin" ]; then
+    echo "  [ok] plugin installed ($plugin)"
+  else
+    echo "  [missing] plugin not found ($plugin)"
+    plan "rtk init -g --opencode"
+  fi
+}
+
+check_pi() {
+  echo "pi:"
+  local ext="$HOME/.pi/agent/extensions/rtk.ts"
+  local repo_rtk="$REPO_ROOT/RTK.md"
+  if [ -f "$ext" ]; then
+    echo "  [ok] extension installed ($ext)"
+  else
+    echo "  [missing] extension not found ($ext)"
+    plan "rtk init -g --agent pi"
+  fi
+  if [ -f "$repo_rtk" ]; then
+    echo "  [ok] repo RTK.md present ($repo_rtk)"
+  else
+    echo "  [missing] repo RTK.md not found ($repo_rtk)"
+    plan "rtk init --codex"
+  fi
+}
+
+check_codex() {
+  echo "codex:"
+  local codex_home="${CODEX_HOME:-$HOME/.codex}"
+  local global_rtk="$codex_home/RTK.md"
+  local repo_rtk="$REPO_ROOT/RTK.md"
+  if [ -f "$global_rtk" ]; then
+    echo "  [ok] global RTK.md present ($global_rtk)"
+  else
+    echo "  [missing] global RTK.md not found ($global_rtk)"
+    plan "rtk init -g --codex"
+  fi
+  if [ -f "$repo_rtk" ]; then
+    echo "  [ok] repo RTK.md present ($repo_rtk)"
+  else
+    echo "  [missing] repo RTK.md not found ($repo_rtk)"
+    plan "rtk init --codex"
+  fi
+}
+
+check_copilot() {
+  echo "GitHub Copilot:"
+  local global_hook="$HOME/.copilot/hooks/rtk-rewrite.json"
+  local repo_hook="$REPO_ROOT/.github/hooks/rtk-rewrite.json"
+  if [ -f "$global_hook" ]; then
+    echo "  [ok] global hook present ($global_hook)"
+  else
+    echo "  [missing] global hook not found ($global_hook)"
+    plan "rtk init -g --copilot"
+  fi
+  if [ -f "$repo_hook" ]; then
+    echo "  [ok] repo hook present ($repo_hook)"
+  else
+    echo "  [missing] repo hook not found ($repo_hook)"
+    plan "rtk init --copilot"
+  fi
+}
+
+# --- Main ----------------------------------------------------------------
+CLAUDE_NEEDS_RESTART=false
+HARNESS="$(detect_harness)"
+
+case "$HARNESS" in
+  claude)
+    echo "Detected harness: Claude Code"
+    check_claude
+    ;;
+  opencode)
+    echo "Detected harness: OpenCode"
+    check_opencode
+    ;;
+  pi)
+    echo "Detected harness: pi"
+    check_pi
+    ;;
+  codex)
+    echo "Detected harness: codex"
+    check_codex
+    ;;
+  copilot)
+    echo "Detected harness: GitHub Copilot"
+    check_copilot
+    ;;
+  unknown)
+    echo "Harness could not be determined — checking all harnesses read-only."
+    check_claude
+    check_opencode
+    check_pi
+    check_codex
+    check_copilot
+    echo
+    echo "No single harness detected, so nothing can be applied automatically."
+    echo "Re-run on the target machine/agent, or configure manually with the commands above."
+    exit 0
+    ;;
+esac
+
+echo
+if [ "${#PLANNED[@]}" -eq 0 ]; then
+  echo "rtk is already configured for $HARNESS. Nothing to do."
+  exit 0
+fi
+
+if [ "$APPLY" = true ]; then
+  echo "Applying fixes for $HARNESS..."
+  run_planned
+  if [ "$HARNESS" = "claude" ] && [ "$CLAUDE_NEEDS_RESTART" = true ]; then
+    echo
+    echo "rtk config changed for Claude Code — please restart Claude Code to pick it up."
+  fi
+else
+  echo "Run again with --apply to execute the planned command(s) above."
+fi

package/skills/collaboration/leveraging-cli-tools/skill.json

@@ -1,6 +1,6 @@
 {
     "version": "1.0.0",
-    "name": "superpowers:collaboration/leveraging-cli-tools",
+    "name": "leveraging-cli-tools",
     "title": "leveraging-cli-tools",
     "aliases": [
         "leveraging-cli-tools",