68 added, 25 removed. Audit A to A.
---
name: cavecrew
description: >
- Caveman-flavored subagent presets. When you need a subagent for research,
- small edits, or code review, prefer the cavecrew variants
- (cavecrew-investigator / cavecrew-builder / cavecrew-reviewer). They are
- caveman-mode-by-default at ultra intensity and use machine-to-machine
- caveman grammar in handoffs to other subagents.
- Trigger phrases: "use cavecrew", "spawn investigator", "spawn builder",
- "spawn reviewer", "give this to a subagent", "delegate this".
+ Decision guide for delegating to caveman-style subagents. Tells the main
+ thread WHEN to spawn `cavecrew-investigator` (locate code), `cavecrew-builder`
+ (1-2 file edit), or `cavecrew-reviewer` (diff review) instead of doing the
+ work inline or using vanilla `Explore`. Subagent output is caveman-compressed
+ so the tool-result injected back into main context is ~60% smaller — main
+ context lasts longer across long sessions.
+ Trigger: "delegate to subagent", "use cavecrew", "spawn investigator/builder/reviewer",
+ "save context", "compressed agent output".
---
- Cavecrew = caveman ruleset applied to subagents (not chat-with-user).
+ Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation.
- ## When to use cavecrew vs vanilla subagents
+ ## When to use cavecrew vs alternatives
- Use vanilla subagents when the user asked for prose-y human-readable output. Use cavecrew when:
+ | Task | Use |
+ |---|---|
+ | "Where is X defined / what calls Y / list uses of Z" | `cavecrew-investigator` |
+ | Same but you also want suggestions/architecture commentary | `Explore` (vanilla) |
+ | Surgical edit, ≤2 files, scope obvious | `cavecrew-builder` |
+ | New feature / 3+ files / cross-cutting refactor | Main thread or `feature-dev:code-architect` |
+ | Review diff, branch, or file for bugs | `cavecrew-reviewer` |
+ | Deep code review with rationale + alternatives | `Code Reviewer` (vanilla) |
+ | One-line answer you already know | Main thread, no subagent |
- - The output is for another agent / pipeline step (machine-to-machine).
- - You're spawning multiple subagents and the cumulative prose blowup matters.
- - The user has caveman mode active — keep the style consistent across the session.
+ Rule of thumb: **if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla.**
- ## Three presets (in `plugins/caveman/agents/`)
+ ## Why this exists (the real win)
- | Subagent | When | Output shape |
- |---|---|---|
- | `cavecrew-investigator` | Read-only research, locate files, map structure. Defer to it for "where is X defined" / "what calls Y" / "summarize this dir." | Caveman-ultra prose, file paths backticked, line numbers in `file.ts:42` form. No suggestions. |
- | `cavecrew-builder` | Small targeted edits in one or two files. Defer for typo fixes, single-function changes, mechanical refactors. | Caveman-ultra commit-message-style summary of what changed. |
- | `cavecrew-reviewer` | Review a diff or branch. Defer for PR-style review. | One-line-per-finding comments per `caveman-review` skill: `L<line>: <severity> <problem>. <fix>.` |
+ Subagent tool results get injected into main context verbatim. A vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from `cavecrew-investigator` returns ~700 tokens. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task.
- ## Composition rules
+ ## Output contracts
- - All three import the canonical caveman ruleset from `skills/caveman/SKILL.md` at intensity `ultra`.
- - Code blocks, file paths, function names, error strings: never abbreviated. Same boundary rules as the base caveman skill.
- - Subagent → subagent handoffs use caveman-internal grammar (terse machine-to-machine, no whimsy). User-facing summaries can soften slightly if asked.
+ What main thread can rely on per agent:
- ## Auto-clarity
+ **`cavecrew-investigator`**
+ ```
+ <Header>:
+ - path:line — `symbol` — short note
+ totals: <counts>.
+ ```
+ Or `No match.` Always file-path-first, line-number-attached, backticked symbols. Safe to grep with `path:\d+`.
- Inherit from caveman: drop to normal prose for security warnings, irreversible action confirmations, multi-step sequences where fragment ambiguity risks misread. Otherwise stay caveman.
+ **`cavecrew-builder`**
+ ```
+ <path:line-range> — <change ≤10 words>.
+ verified: <re-read OK | mismatch @ path:line>.
+ ```
+ Or one of: `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` (terminal first token).
+
+ **`cavecrew-reviewer`**
+ ```
+ path:line: <emoji> <severity>: <problem>. <fix>.
+ totals: N🔴 N🟡 N🔵 N❓
+ ```
+ Or `No issues.` Findings sorted file → line ascending.
+
+ ## Chaining patterns
+
+ **Locate → fix → verify** (most common):
+ 1. `cavecrew-investigator` returns site list.
+ 2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`.
+ 3. `cavecrew-reviewer` audits the diff.
+
+ **Parallel scout** (when investigation is broad):
+ Spawn 2-3 `cavecrew-investigator` calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread.
+
+ **Single-shot edit** (when site is already known):
+ Skip investigator. Hand exact path:line to `cavecrew-builder` directly.
+
+ ## What NOT to do
+
+ - Don't use `cavecrew-builder` when you don't already know the file. Spawn investigator first or main thread will eat tokens passing context.
+ - Don't chain `cavecrew-investigator → cavecrew-builder` for a 5-file refactor. Builder will return `too-big.` and you'll have wasted a turn.
+ - Don't ask `cavecrew-reviewer` for "general feedback" — it returns findings only, no architecture opinions. Use `Code Reviewer` for that.
+ - Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase.
+
+ ## Auto-clarity (inherited)
+
+ Subagents drop caveman → normal English for security warnings, irreversible-action confirmations, and any output where fragment ambiguity could be misread. Resume caveman after.