feat(agents): add read-only explorer search utility (pinned to sonnet)

CLAUDE.md

@@ -14,6 +14,7 @@ Agents live under `.claude/agents/` (project) or `~/.claude/agents/` (user, all
 - **Four-hat chain (§4):** `architect` (plan, read-only) → `senior-swe` (implement, mutating) → `code-reviewer` (adversarial review, read-only) → `qa` (verify, read-only). Plus `release-engineer` (release prep) and `docs-reconciler` (drift detection).
 - **Specialists (as the change warrants):** `security-reviewer`, `performance-engineer`, `db-migration-specialist`, `debugger`, `tech-writer`, `product-designer`, `devops-sre`.
 - **Delivery layer (§4B):** `technical-program-manager` (scope / sequence / risk), `scrum-master` (cadence / flow). Neither writes code.
+- **Utility (not a roster role):** `explorer` — a cheap, read-only search-and-report agent (pinned to a lighter model). Delegate broad searches and file reads to it: it does the grep/read churn in its own context and returns the conclusion, keeping file dumps out of the main model's context.
 - **Read-only vs mutating** is the `tools:` allowlist: read-only agents omit `Edit`/`Write` and are parallel-safe; mutating agents hold them and must run serially per branch. `concurrency:` is NOT a supported frontmatter field — don't add it.
 
 Full per-agent tables, invoke-when triggers, and the concurrency rationale: `~/.claude/docs/agents.md`. Per-stack override packs (`agents-android/` 7, `agents-ios/` 7, `agents-compute/` 13): see `STRUCTURE.md`.
@@ -168,7 +169,7 @@ Four no-code extensions cover almost everything before you'd fork the binary: **
 
 ### 19.1 What is this project?
 
-- **One-paragraph description:** This repository _is_ a distributed Claude Code configuration, not an application: a stack-agnostic engineering spine (this `CLAUDE.md`, §1–18), platform rule packs (`rules/`), a 42-agent roster across four stacks (`agents/`, `agents-android/`, `agents-ios/`, `agents-compute/`), three hooks — a commit guard, a format-on-save hook, and a session-start project-bootstrap hook (`hooks/`) — and a repo-scaffolder skill (`skills/new-repo/`). Users copy it into `~/.claude/` and per-repo. The product is the configuration's correctness and internal consistency; nothing is compiled or deployed. Public, MIT: github.com/roadhero/claude-code-setup.
+- **One-paragraph description:** This repository _is_ a distributed Claude Code configuration, not an application: a stack-agnostic engineering spine (this `CLAUDE.md`, §1–18), platform rule packs (`rules/`), a 42-agent roster across four stacks (`agents/`, `agents-android/`, `agents-ios/`, `agents-compute/`), a read-only `explorer` search utility (`agents/`, not part of the 42), three hooks — a commit guard, a format-on-save hook, and a session-start project-bootstrap hook (`hooks/`) — and a repo-scaffolder skill (`skills/new-repo/`). Users copy it into `~/.claude/` and per-repo. The product is the configuration's correctness and internal consistency; nothing is compiled or deployed. Public, MIT: github.com/roadhero/claude-code-setup.
 
 ### 19.2 Stack
 

README.md

@@ -10,7 +10,7 @@ Most people publish a single `CLAUDE.md` and call it a setup. The thing that act
 | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `CLAUDE.md`                                                      | The universal spine — a lean (~220-line) always-loaded core: workflow, git rules, coding guidelines, secrets, anti-patterns. Stack-agnostic. Longer reference material lives in `docs/` and loads on demand.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `rules/{web,android,ios,compute}.md`                             | Platform rule packs. Each carries a `paths:` frontmatter glob; Claude Code loads a pack when it reads a file matching that glob (`*.kt` → android, `*.swift` → ios, `*.ts`/`*.py` → web, `*.cpp`/`*.cu` → compute). Path-triggered, so packs whose files you never touch stay out of context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `agents/` (15)                                                   | The default subagent roster: the four-hat chain (architect → senior-swe → code-reviewer → qa), plus specialists (security, performance, db-migration, debugger, devops, docs, design), release-engineer + tech-writer, and a delivery layer (TPM, scrum-master).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `agents/` (15 + `explorer`)                                      | The default subagent roster: the four-hat chain (architect → senior-swe → code-reviewer → qa), plus specialists (security, performance, db-migration, debugger, devops, docs, design), release-engineer + tech-writer, and a delivery layer (TPM, scrum-master). Plus a read-only `explorer` search utility (cheap model) that the roster and main model delegate reads to — a tool, not counted in the 42-agent roster.                                                                                                                                                                                                                                                                                                                                                            |
 | `agents-android/` (7), `agents-ios/` (7), `agents-compute/` (13) | Per-stack overrides. Drop them into a repo's `.claude/agents/` and they override the generic ones of the same name with platform-brained versions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `hooks/guard-commit.sh`                                          | A Claude Code Bash hook (PreToolUse) that blocks the _agent_ from force-pushing, skipping git hooks with `--no-verify`, committing as a non-human, writing AI attribution into a commit message, or staging obvious secrets. Every segment of a chained command is checked on its own. Quoted text, heredoc bodies, substitutions, and arithmetic are stripped as data first, so a commit message or a file body that merely mentions a blocked flag never trips it; a shape the check cannot classify (a shell wrapper of any form, a substitution inside `${...}`, an unquoted pattern in a commit or push, git config passed through the environment) is refused rather than guessed. It guards Claude's git commands — not a human typing `git` directly in their own terminal. |
 | `hooks/format.sh`                                                | Auto-formats edited files by extension across every stack. Missing formatter is a silent no-op, never an error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

STRUCTURE.md

@@ -10,7 +10,7 @@
 │   ├── android.md            # Kotlin/Compose/Hilt/Room
 │   ├── ios.md                # Swift/SwiftUI/Swift6/App Store
 │   └── compute.md            # C++/CUDA/parallel-Python
-├── agents/                   # 15 GENERIC (global default)
+├── agents/                   # 15 GENERIC roster + explorer utility (global default)
 ├── hooks/
 │   ├── guard-commit.sh       # PreToolUse(Bash): block AI attribution, secrets, force-push, --no-verify, non-human committer
 │   ├── format.sh             # PostToolUse(Edit|Write): auto-format by extension, all stacks

agents/explorer.md

@@ -0,0 +1,41 @@
+---
+name: explorer
+description: Read-only code explorer for fast, cheap search-and-report across a codebase. Use to locate code, map how something works, or gather file:line references when you need the conclusion, not the raw files. It searches and reads in its own context and hands back a distilled answer, so the file dumps never land in the calling model's context. Runs on a cheaper model. Give it a specific target and a search breadth. It does not review, judge, or edit. Read-only — safe to run in parallel.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are an Explorer. You find things in a codebase and report back the conclusion — file paths, line numbers, and a short synthesis. You are the cheap, read-only searcher the main model and other agents delegate to so that raw file contents stay in your context, not theirs. You locate and summarize; you do not review, design, judge, or change code.
+
+# Operating principle: locate cheaply, read narrowly, report tightly
+
+- Locate first with `grep`/`glob` (or `rg` / `git grep` / `find` via Bash). Then read only the spans that matter — a function body, a config block — not whole files.
+- Give `file:line` for every claim so the caller can jump straight there. A finding with no location is not useful.
+- Return the distilled answer, not a transcript. The caller wants "auth is enforced in `middleware/auth.ts:20-48`, applied to routes in `router.ts:75`", not the contents of both files.
+- Name your edges. If the search was broad, say what you covered and what you did not reach, so the caller knows how much to trust the sweep.
+
+# Output format
+
+```
+## <the question, restated in one line>
+
+**Answer:** <the direct conclusion, 1–3 sentences>
+
+**Where:**
+- `path:line` — <what is here, one line>
+- `path:line` — <...>
+
+**Coverage:** <what you searched; anything you could not find or did not reach>
+```
+
+# What you DON'T do
+
+- You don't review, critique, or rate code quality — that's `code-reviewer`.
+- You don't make design or correctness decisions, or recommend fixes beyond pointing at the relevant code.
+- You don't edit, stage, or run anything with side effects. Inspection only.
+- You don't dump whole files or paste long excerpts. Cite `file:line` and summarize.
+- You don't speculate. If you can't find something, say so and name where you looked.
+
+# Tone
+
+Terse and factual. Locations over prose. The value you add is a small, accurate answer that saved the caller from reading the repo itself.

docs/agents.md

@@ -36,6 +36,14 @@ Agents live under `.claude/agents/` (project) or `~/.claude/agents/` (user, all
 
 **Concurrency classification.** Mutating agents hold `Edit`/`Write` and must run serially against the same branch; read-only agents omit `Edit`/`Write` and are safe to invoke in parallel. (Read-only agents may still hold `Bash` for inspection, so the boundary is a documented convention backed by the `tools:` list, not a hard sandbox — the Concurrency column above is the authoritative index.) Claude Code orchestrates serially today; an orchestrator that parallelized the read-only subset could read each agent's `tools:` allowlist to derive the safe set — typically a 2–5× speedup on multi-step turns. The read-only/mutating class is signalled by the `tools:` allowlist, **not** a frontmatter flag — `concurrency:` is not a supported sub-agent field, so the harness silently ignores it; the Concurrency column here is documentation for humans.
 
-**Model tiers.** Model selection is by role, via the `model:` frontmatter field. Reasoning, review, design, implementation, and delivery agents carry **no `model:` line**, so they inherit your selected main model — thinking and decisions stay on the powerful model you chose, and follow it if you change it. The one cheap exception in the generic / Android / iOS packs is `docs-reconciler`, pinned to `sonnet`: drift detection is a find-and-report scan that doesn't need frontier reasoning, so it runs on a cheaper model and hands back only its report (the same reason you delegate a broad search to a read-only agent — the file dumps land in the cheap agent's context, not your main one). The `agents-compute/` pack keeps explicit pins at a finer grain — deep specialists (CUDA, numerics, parallelism, memory, systems, performance) on `opus`, routine implementation (build, python, inference plumbing) on `sonnet` — because compute work is rule-heavy and a deterministic per-role pin is worth it there. Rule of thumb: omit `model:` for anything that reasons or writes; pin to a cheap model only pure find-and-report work.
+**Model tiers.** Model selection is by role, via the `model:` frontmatter field. Reasoning, review, design, implementation, and delivery agents carry **no `model:` line**, so they inherit your selected main model — thinking and decisions stay on the powerful model you chose, and follow it if you change it. The cheap ones in the generic / Android / iOS packs are `docs-reconciler` and the `explorer` utility, both pinned to `sonnet`: drift detection and code search are find-and-report work that doesn't need frontier reasoning, so they run on a cheaper model and hand back only their report — the file dumps land in the cheap agent's context, not your main one. The `agents-compute/` pack keeps explicit pins at a finer grain — deep specialists (CUDA, numerics, parallelism, memory, systems, performance) on `opus`, routine implementation (build, python, inference plumbing) on `sonnet` — because compute work is rule-heavy and a deterministic per-role pin is worth it there. Rule of thumb: omit `model:` for anything that reasons or writes; pin to a cheap model only pure find-and-report work.
 
-**Per-stack override packs.** The generic roster ships in `agents/` (15). Stack-specific packs — `agents-android/` (7), `agents-ios/` (7), `agents-compute/` (13) — override the global agent of the same `name:` when dropped into a repo's `.claude/agents/`. See `STRUCTURE.md` → "Agent override model" for which names each pack overrides and which globals fall through.
+**Utility agents (not part of the 42-agent roster).** Alongside the roster, `agents/` ships one read-only utility:
+
+| Agent      | Purpose                           | Concurrency | Invoke when                                                                                              |
+| ---------- | --------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| `explorer` | Cheap read-only search-and-report | Read-only   | Locating code, mapping how something works, or gathering `file:line` refs when you need only the answer. |
+
+`explorer` is pinned to `sonnet` and does the grep/read churn in its own context, handing back a distilled answer so the file dumps never enter the calling model's context — the concrete way to "run reads on a cheaper model" (individual tool calls can't be routed per-model; delegation to a cheap subagent is the mechanism). It's a tool the roster and the main model call, not a workflow role, so it's counted separately from the 42.
+
+**Per-stack override packs.** The generic roster ships in `agents/` (15 roster agents + the `explorer` utility = 16 files). Stack-specific packs — `agents-android/` (7), `agents-ios/` (7), `agents-compute/` (13) — override the global agent of the same `name:` when dropped into a repo's `.claude/agents/`. See `STRUCTURE.md` → "Agent override model" for which names each pack overrides and which globals fall through.