diff --git a/CLAUDE.md b/CLAUDE.md index 8733da7..db60bac 100644 --- a/CLAUDE.md +++ b/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 diff --git a/README.md b/README.md index c5b0c62..07fd22c 100644 --- a/README.md +++ b/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. | diff --git a/STRUCTURE.md b/STRUCTURE.md index a039442..5488c10 100644 --- a/STRUCTURE.md +++ b/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 diff --git a/agents/explorer.md b/agents/explorer.md new file mode 100644 index 0000000..af37340 --- /dev/null +++ b/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 + +``` +## + +**Answer:** + +**Where:** +- `path:line` — +- `path:line` — <...> + +**Coverage:** +``` + +# 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. diff --git a/docs/agents.md b/docs/agents.md index b900417..f634865 100644 --- a/docs/agents.md +++ b/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.