@complexthings/superpowers-agent 9.0.0 → 9.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +2 -2
  2. package/skills/collaboration/leveraging-cli-tools/SKILL.md +48 -101
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@complexthings/superpowers-agent",
3
- "version": "9.0.0",
3
+ "version": "9.0.1",
4
4
  "description": "Superpowers agent CLI — skills system for AI coding agents",
5
5
  "type": "module",
6
6
  "bin": {
@@ -33,7 +33,7 @@
33
33
  },
34
34
  "repository": {
35
35
  "type": "git",
36
- "url": "https://github.com/complexthings/superpowers.git"
36
+ "url": "git+https://github.com/complexthings/superpowers.git"
37
37
  },
38
38
  "bugs": {
39
39
  "url": "https://github.com/complexthings/superpowers/issues"
package/skills/collaboration/leveraging-cli-tools/SKILL.md CHANGED
@@ -1,132 +1,79 @@
1
1
  ---
2
2
  name: leveraging-cli-tools
3
- 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
3
+ 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.
4
4
  ---
5
5
 
6
6
  # Leveraging CLI Tools
7
7
 
8
- ## Core Principle
8
+ ## Purpose
9
9
 
10
- **High-performance CLI tools reduce costs, latency, and cognitive load by 5-50x.**
10
+ 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.
11
11
 
12
- Modern tools have massive RL optimization in frontier models - use them.
12
+ ## When a relevant task arises
13
13
 
14
- ## Tool Availability Protocol
14
+ 1. Pick the right tool from the table below.
15
+ 2. Confirm it's installed before relying on it — e.g. `command -v rg`.
16
+ 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.
15
17
 
16
- **Session start (silent check, cache result):**
18
+ Check only the tools the current task needs — no upfront session-wide scan.
17
19
 
18
- ```bash
19
- command -v rg jq fd bat gh >/dev/null 2>&1 && echo "ready" || echo "missing"
20
- ```
21
-
22
- **If tools missing:** Offer installation when relevant task appears.
23
- **If tools ready:** Use optimal workflows throughout session.
24
-
25
- ## Tool Selection
26
-
27
- | Task | Use | Instead of | Speedup |
28
- |------|-----|-----------|---------|
29
- | Search code | **rg** | grep | 10-50x |
30
- | Parse JSON | **jq** | awk/sed | 5-20x |
31
- | Find files | **fd** | find | 5-10x |
32
- | View code | **bat** | cat | Better UX |
33
- | Transform code | **ast-grep** | sed | 3-10x |
34
- | GitHub ops | **gh** | curl+API | 2-5x |
35
- | Interactive select | **fzf** | manual | 10-100x |
36
-
37
- ## Quick Reference
38
-
39
- ### Code Search: rg
40
- ```bash
41
- rg "AuthError" --type typescript # 10-50x faster than grep, respects .gitignore
42
- ```
20
+ ## Tools
43
21
 
44
- ### JSON Parse: jq
45
- ```bash
46
- jq '.results[] | select(.status=="error") | .error.code' api.json | sort -u
47
- ```
48
-
49
- ### Find Files: fd
50
- ```bash
51
- fd "\.test\.ts$" # 5-10x faster than find, parallel traversal
52
- ```
22
+ | Rating | Tool | Replaces | Why | Install |
23
+ |:------:|------|----------|-----|---------|
24
+ | 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` |
25
+ | 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` |
26
+ | 9 | `fd` | `find` | File finding. Faster, saner syntax, parallel traversal, `.gitignore`-aware. | `brew install fd` |
27
+ | 8 | `yq` | `grep`/`sed`/`awk` on YAML | `jq` for YAML/TOML/XML. Reads CI files, `docker-compose`, k8s manifests, frontmatter. | `brew install yq` |
28
+ | 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` |
29
+ | 8 | `gh` | `curl` + GitHub API + tokens | GitHub from the shell — PRs, issues, CI, API. No hand-rolled `curl` + token juggling. | `brew install gh` |
30
+ | 7 | `sd` | `sed -i`, `perl -pe` | Find/replace. Literal-string-safe, no regex-escaping footguns. | `brew install sd` |
31
+ | 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` |
32
+ | 6 | `htmlq` | `grep`/`sed` on HTML | `jq` for HTML — CSS-selector extraction from fetched pages. | `brew install htmlq` |
33
+ | 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` |
34
+ | 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` |
35
+ | 5 | `hyperfine` | `time`, `for`-loop timing | Statistical benchmarking with warmups. Real before/after numbers, not `time` guesses. | `brew install hyperfine` |
36
+ | 5 | `tokei` | `wc -l`, `find … \| wc`, `cloc` | Instant LOC/language breakdown. Orient in an unfamiliar repo before exploring. | `brew install tokei` |
37
+ | 5 | `fzf` (`-f`) | manual fuzzy filtering | Non-interactive `-f`/`--filter` mode: fuzzy-rank a candidate list piped from `fd`/`rg`. | `brew install fzf` |
38
+ | 4 | `watchexec` | `while`+`sleep`, `entr` | Run a command on file change. Useful in build/test loops; non-interactive unlike most watchers. | `brew install watchexec` |
53
39
 
54
- ### View Code: bat
55
- ```bash
56
- bat src/auth.ts # Syntax highlighting, Git integration, line numbers
57
- ```
40
+ ## Core workflows
58
41
 
59
- ### Code Transform: ast-grep
42
+ **Filter before reading** — find the matches, then read only those.
60
43
  ```bash
61
- sg --pattern 'console.log($$$ARGS)' --rewrite 'logger.debug($$$ARGS)'
44
+ rg -l "password.*hash" src/auth/ --type ts | xargs rg "TODO"
62
45
  ```
63
46
 
64
- ## Installation Protocol
65
-
66
- **If tool missing when needed:**
67
-
68
- 1. Explain impact: "Using rg is 10-50x faster, reducing token costs"
69
- 2. Install automatically for core tools (rg, jq, fd, bat, gh): `brew install ripgrep jq fd bat gh` (macOS) or equivalent
70
- 3. Ask before installing: ast-grep, httpie, fzf
71
-
72
- **No exceptions:** If tool unavailable and user declines install, explain performance cost but use fallback.
73
-
74
- ## Key Workflows
75
-
76
- ### Filter Before Reading
47
+ **Compose tools** — search, parse, dedup in one pass.
77
48
  ```bash
78
- # DON'T: Read all files blindly
79
- # DO: Filter first, read matches only
80
- rg "password.*hash" src/auth/ --type ts -l | xargs bat
49
+ rg -l '"error"' logs/ --type json | xargs jq -r 'select(.level=="error") | .code' | sort -u
81
50
  ```
82
51
 
83
- Under fatigue: filtering first reduces cognitive load.
84
-
85
- ### Compose Tools
52
+ **Structural rewrite, not regex** — refactor by AST so syntax can't trip you.
86
53
  ```bash
87
- rg "error.code" logs/ -o | jq -r . | sort -u # Search + parse + dedup
54
+ sg --pattern 'console.log($$$A)' --rewrite 'logger.debug($$$A)' --lang ts
88
55
  ```
89
56
 
90
- ## Performance Impact
91
-
92
- | Task | grep/find/cat | rg/fd/bat | Savings |
93
- |------|---------------|-----------|---------|
94
- | Search 50k files | 45s | 0.8s | 56x, ~40k tokens |
95
- | Parse 10MB JSON | 12s (awk) | 2s (jq) | 6x, ~15k tokens |
96
- | Find in monorepo | 8s | 1s | 8x, ~10k tokens |
57
+ 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.
97
58
 
98
- ## Red Flags
59
+ ## Red flags
99
60
 
100
- - Manually parsing JSON with awk/sed/grep (use jq)
101
- - Reading files without filtering first (use rg to filter)
102
- - Not checking tool availability at session start
103
- - Using bash grep when Grep tool exists (use Grep tool)
61
+ - Parsing JSON/YAML with `awk`/`sed`/`grep` instead of `jq`/`yq`.
62
+ - Reading files before filtering them with `rg`.
63
+ - Hand-rolling `curl` against the GitHub API instead of `gh`.
64
+ - Regex codemods with `sed` where `ast-grep` is structurally safe.
104
65
 
105
- ## Common Rationalizations
66
+ ## Common rationalizations
106
67
 
107
68
  | Excuse | Reality |
108
69
  |--------|---------|
109
- | "grep works fine" | 50x slower, burns 40k tokens on 50k files |
110
- | "I don't know if they have jq" | Check once, install takes 30s, saves hours |
111
- | "Not worth setup overhead" | One install = 10-100x speedup on ALL future tasks |
112
- | "User didn't ask for optimization" | Faster task completion IS better completion |
113
-
114
- ## When NOT to Use
115
-
116
- **Skip when:**
117
- - Small dataset (< 100 files, < 1MB) AND one-off task
118
- - User explicitly declines install
119
- - Teaching context where standard tools are the goal
120
-
121
- **Use when:**
122
- - Codebase search (always)
123
- - JSON operations (always)
124
- - Time pressure, large datasets, repeated operations
125
-
126
- ## Summary
127
-
128
- **Protocol: Check → Use → Combine**
70
+ | "grep works fine" | On a big tree it's 10-50x slower and floods context with noise `rg` would have filtered out. |
71
+ | "I don't know if they have jq" | One `command -v jq` answers it; install is seconds and pays back across the whole session. |
72
+ | "Not worth the setup" | One install = a speedup on every future task, not just this one. |
73
+ | "User didn't ask for optimization" | Faster, lower-noise completion *is* better completion. |
129
74
 
130
- Session start: Silent availability check. Task appears: Use optimal tool or install. Complex tasks: Compose tools.
75
+ ## When NOT to use
131
76
 
132
- **Not using available tools burns resources.**
77
+ - A tiny one-off (a handful of files, well under a megabyte) where the standard tool is already at hand.
78
+ - The user declined the install — note the cost once, then use the fallback.
79
+ - A teaching context where the standard tool is the point.