# cavecrew 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". - **Kind:** skill - **Source:** https://github.com/JuliusBrussee/caveman - **Page:** https://forefy.com/skills/108b28ec-1a9b-489a-9a84-4788cdb5c0e6 - **API (JSON + files):** https://forefy.com/api/skills/108b28ec-1a9b-489a-9a84-4788cdb5c0e6 --- ## README.md # cavecrew Decision guide. When to delegate to caveman subagents instead of doing the work inline. ## What it does Tells the main thread when to spawn a caveman-style subagent versus the vanilla equivalent. The win: subagent tool-results inject back into main context verbatim, and caveman output is roughly 1/3 the size of vanilla prose. Across 20 delegations in one session, that is the difference between context exhaustion and finishing the task. Three subagents: | Subagent | Job | Use when | |----------|-----|----------| | `cavecrew-investigator` | Locate code (read-only) | "Where is X defined / what calls Y / list uses of Z" | | `cavecrew-builder` | Surgical edit, 1-2 files | Scope is obvious, ≤2 files. Refuses 3+ file scope. | | `cavecrew-reviewer` | Diff/file review | One-line findings with severity emoji | Use vanilla `Explore` or `Code Reviewer` when you want prose, architecture commentary, or rationale. Use main thread directly for one-line answers and 3+ file refactors. This skill is a decision guide, not a slash command. It activates when the conversation mentions delegation. ## How to invoke Triggers on phrases like "delegate to subagent", "use cavecrew", "spawn investigator", "save context", "compressed agent output". ## Example chaining Locate → fix → verify (most common): 1. `cavecrew-investigator` returns site list (`path:line — symbol — note`) 2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder` 3. `cavecrew-reviewer` audits the resulting diff Parallel scout: spawn 2-3 `cavecrew-investigator` calls in one message with different angles (defs, callers, tests). Aggregate in main. ## See also - [`SKILL.md`](./SKILL.md) — full decision matrix and output contracts - [`agents/cavecrew-investigator.md`](../../agents/cavecrew-investigator.md) - [`agents/cavecrew-builder.md`](../../agents/cavecrew-builder.md) - [`agents/cavecrew-reviewer.md`](../../agents/cavecrew-reviewer.md) - [Caveman README](../../README.md) — repo overview ## SKILL.md --- name: cavecrew description: > 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 = 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 alternatives | 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 | 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.** ## Why this exists (the real win) 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. ## Output contracts What main thread can rely on per agent: **`cavecrew-investigator`** ```
: - path:line — `symbol` — short note totals: . ``` Or `No match.` Always file-path-first, line-number-attached, backticked symbols. Safe to grep with `path:\d+`. **`cavecrew-builder`** ``` — . verified: . ``` Or one of: `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` (terminal first token). **`cavecrew-reviewer`** ``` path:line: : . . 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.