feat(skill): code-search v0.1.0 — rg-first code search (RED: grep -r 15min+ hang → GREEN: rg 0s; routing rg/git-grep/repo_read/grep_audit)

README.md

@@ -118,6 +118,7 @@ an explicit `adapted-from` marker in its frontmatter.
 | `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — workflow-spec design gate |
 | `review-kit-pi-method` | `author: ours` — pi-native spawn for clean-context review subagents |
 | `command-index` | `author: ours` — just/Makefile command-index convention (standard targets, auto-doc; idea 3/18) |
+| `code-search` | `author: ours` — rg-first code search (measured 15 min → 0s; routing: rg / git grep / interns repo_read / grep_audit) |
 | `code-review` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — two-axis + Fowler baseline; output: caveman-review format |
 | `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills core + ideya 8 self-skill-authoring |
 | `web-search` | `author: ours` — search_web tool (pi-extension) + policy: when to search, «без поиска» session-off |

README.ru.md

@@ -88,6 +88,7 @@ bash scripts/build.sh caveman          # один
 | `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — дизайн-гейт workflow-спец |
 | `review-kit-pi-method` | `author: ours` — pi-спавн чистых review-субагентов |
 | `command-index` | `author: ours` — конвенция just/Makefile command-index (стандартные таргеты, авто-док; идея 3/18) |
+| `code-search` | `author: ours` — rg-first код-поиск (замер: 15 мин → 0 сек; роутинг: rg / git grep / interns repo_read / grep_audit) |
 | `code-review` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — двухосевость + Fowler-база; формат вывода: caveman-review |
 | `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills ядро + идея 8 self-skill-authoring |
 | остальные `skills/*` | `author: ours` |

skills/code-search/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: code-search
+author: ours
+version: 0.1.0
+description: >
+  Use when searching code for strings, symbols, or usages — "find where X is
+  used", «найди, где используется», "grep for X", "where is X", "search the
+  repo for", any code search, or when deciding HOW to search a codebase. One
+  hard rule: in any tree that can contain node_modules/dist/build/.nuxt,
+  search with `rg` (gitignore-aware) — NEVER `grep -r` (`--include` filters
+  file names, not directory traversal; grep walks every node_modules entry:
+  measured 15+ min never-finishing vs rg 0s on the same tree). Routes:
+  string/symbol search → rg; tracked-files-only → git grep; whole-repo
+  comprehension ("what does module Y do") → interns repo_read (ask-mode);
+  N×M contains audits → interns grep_audit. Skip for web search
+  (web-search), vault search (coworker-search), already-fast tools.
+---
+
+# Code Search
+
+Search code with the fastest correct tool for the question class. The default
+`grep -r` habit is the single biggest time sink in agent work on npm/JS
+projects — the fix is a different binary, not more patience.
+
+## When to use
+
+- Any "where is X used / where does X appear / search the repo for X" request.
+- Deciding HOW to search: rg vs git grep vs intern delegation.
+- A search that "feels slow" — that is a wrong-tool signal, not a slow disk.
+
+## When NOT to use
+
+- Web search → `web-search` skill.
+- Searching the .cowork vault / memory vault → `coworker-search`.
+- A question ABOUT the code ("what does module Y do", "how does the build work") → `interns.repo_read` (delegation, ask-mode per `using-interns`).
+- The right tool is already running and fast.
+
+## Core rule (one sentence)
+
+**In any tree that can contain `node_modules` / `dist` / `build` / `.nuxt` / `vendor`, search with `rg`, never `grep -r`.**
+
+Why — measured on `stostayer.new`, `packages/web` + `apps/web4`, 2026-08-26:
+
+| Fact | Value |
+|---|---|
+| Total files in the two dirs | 113,169 |
+| Of which in `node_modules` + `.nuxt` + `build` | 109,248 (**96%**) |
+| `grep -rn "3590" … --include=*.vue --include=*.js … -l` | **> 15 min, never finished** (RED run: fresh unprompted agent spawned 2× `/usr/bin/grep`, still running at 200s, killed) |
+| `rg -l "3590" …` (same globs) | **0s**, 3 matches |
+| `rg --no-ignore "3590" …` (forced full scan incl. node_modules) | 16s |
+
+Mechanics: `grep -r --include` filters which **file names** get read — it does
+NOT stop **directory traversal**. grep stats/opens every directory entry
+including node_modules (100k+ files) on every search. `rg` reads `.gitignore`
+(+ `.ignore`, `.rgignore`) and skips ignored trees by default — zero flags
+needed. It is already installed on this machine (ripgrep 15.x).
+
+## Routing table
+
+| Question class | Tool | Notes |
+|---|---|---|
+| Find string/symbol/usages in the working tree | `rg -n "pattern" <paths>` | gitignore-aware out of the box. `-l` → filenames only. `-g '*.ext'` to filter. |
+| Only tracked files (clean, deterministic) | `git grep -n "pattern"` | uses the git index; ignores untracked + ignored. Always present even on bare boxes. |
+| "I really must scan generated/vendored too" | `rg --no-ignore` | 16s on the 113k-file tree — still ~50× faster than grep. Never `grep -r` even here. |
+| Whole-repo comprehension ("what does module Y do", "where is X used across the architecture") | `interns.repo_read` | delegation — ask-mode, `using-interns` skill. Packs via repomix + cheap LLM. |
+| N×M contains/not-contains audit (canonical strings across many files) | `interns.grep_audit` | deterministic, no LLM call. |
+
+## Common mistakes / rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "grep works, just slow" | Wrong tool. rg is a drop-in replacement on the same globs: 15 min → 0s on the same tree. |
+| "--include excludes node_modules" | **False.** `--include` filters file *names* that get read, not directories *walked*. grep still traverses all 100k+ node_modules entries. |
+| "Windows/Defender is just slow" | The disk is not the problem — 96% of walked files are build artifacts. rg skips them via .gitignore before the filesystem ever opens them. |
+| "I need to search EVERYTHING" | Use `rg --no-ignore` (16s), still not grep (15 min). Scope with `-g '!node_modules'` if noise is the issue. |
+| "rg isn't installed here" | It is (ripgrep 15.2.0). On a bare box fall back to `git grep` — git is always present. |
+| "It's a one-off, speed doesn't matter" | One-off searches happen 10+ times per session. Each 15-min grep burns an entire agent turn for nothing. |
+
+## Red flags (STOP)
+
+- A search command starting with `grep -r` in any JS/TS/node project — rewrite to `rg` before running.
+- A grep that "hasn't returned" after 30s — it is walking node_modules; kill it, use rg.
+- Search results containing `node_modules/` / `.nuxt/` / `dist/` paths — you scanned garbage; redo with rg (ignore-aware).
+- Writing `--include` and believing directories are excluded.
+
+## Cross-agent applicability
+
+Tool-level rule, works in any agent that can run shell commands (pi, claude,
+codex exec, hermes). `rg` or `git grep` are the always-available core; the
+intern rows are optional delegation for a local `interns` MCP
+(`using-interns` skill). The core rule stands alone without them.
+
+## Out of scope
+
+- Semantic code search / index servers (zoekt, sourcegraph, codesearch) — YAGNI; rg removes the pain without infrastructure.
+- Searching non-code stores (vaults, wikis, the web).
+- Teaching rg's full flag surface — `rg --help` / man.
+- mappa internals: code search stays client-side (operator decision 2026-08-25 — "rg-мост по чек-аутам", outside mappa).