Two files, one repository
JuliusBrussee/caveman ships 2 formats across 39 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareCLAUDE.md ↔ AGENTS.md
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 23 | 0% |
| Commands | 0 | 0 | 16 | 0% |
| Section tags | 1 | 0 | 4 | 20% |
What each file covers
Sections
0 shared · 1 only in A · 23 only in B- − agents — the agent-profile registry (`caveman wrap` data)
- + CLAUDE.md — caveman
- + README is a product artifact
- + Project overview
- + What lives where
- + File structure and what owns what
- + Single source of truth files — edit only these
- + Auto-generated / auto-synced — do not edit directly
- + CI sync workflow
- + Hook system (Claude Code)
- + `src/hooks/caveman-config.js` — shared module
- + `src/hooks/caveman-activate.js` — SessionStart hook
- + `src/hooks/caveman-mode-tracker.js` — UserPromptSubmit hook
- + `src/hooks/caveman-statusline.sh` — Statusline badge
- + Hook installation
- + Skill system
- + Intensity levels
- + Auto-clarity rule
- + caveman-compress
- + caveman-commit / caveman-review
- + Agent distribution
- + Evals
- + Benchmarks
- + Key rules for agents working here
Commands
0 shared · 0 only in A · 16 only in B- + npx skills
- + npx caveman --with-init
- + npx caveman --only <agent>
- + npx skills add ... -a <profile>
- + npx skills add
- + node
- + npx -y github:JuliusBrussee/caveman
- + npx -y github:JuliusBrussee/caveman -- --uninstall
- + node bin/install.js --uninstall
- + npx skills add ... -a cursor
- + npx skills add ... -a windsurf
- + npx skills add ... -a cline
- + npx skills add ... -a github-copilot
- + npx skills add JuliusBrussee/caveman -a <profile>
- + node bin/install.js --list
- + uv run python benchmarks/run.py
Section tags
1 shared · 0 only in A · 4 only in B- + architecture
- + git-pr
- + do-not
- + docs
- agent-behaviour
Line diff
JuliusBrussee/caveman · agents/AGENTS.md
@@ −1 @@
1# agents — the agent-profile registry (`caveman wrap` data)
2
3**This file is a pointer. The orientation lives in [`CLAUDE.md`](CLAUDE.md)** (same directory) —
4one source, kept current, so the two cannot diverge again.
5
6Read `CLAUDE.md` for: how a profile points an agent at the gateway (`injection.method`), the
7three-tier `injection_completeness` honesty scale (declarative / builder-assisted / code-only) and
8why "adding an agent is a pure data change" is only true for the declarative tier, command/skill
9surfaces, and the fail-closed compile invariants (catalog-priced models, derived CI pins,
10verification staleness).
11
JuliusBrussee/caveman · CLAUDE.md
@@ +1 @@
1# CLAUDE.md — caveman
2
3## README is a product artifact
4
5README = product front door. Non-technical people read it to decide if caveman worth install. Treat like UI copy.
6
7**Rules for any README change:**
8
9- Readable by non-AI-agent users. If you write "SessionStart hook injects system context," invisible to most — translate it.
10- Keep Before/After examples first. That the pitch.
11- Install table always complete + accurate. One broken install command costs real user.
12- What You Get table must sync with actual code. Feature ships or removed → update table.
13- Preserve voice. Caveman speak in README on purpose. "Brain still big." "Cost go down forever." "One rock. That it." — intentional brand. Don't normalize.
14- Benchmark numbers from real runs in `benchmarks/` and `evals/`. Never invent or round. Re-run if doubt.
15- Adding new agent to install table → add detail block in `<details>` section below.
16- Readability check before any README commit: would non-programmer understand + install within 60 seconds?
17
18---
19
20## Project overview
21
22Caveman makes AI coding agents respond in compressed caveman-style prose while preserving technical substance, code, commands, and exact errors. Publish no reduction or quality-equivalence percentage without a committed reviewed benchmark. Ships as Claude Code plugin, Codex plugin, Gemini CLI extension, and agent rule files for Cursor, Windsurf, Cline, Copilot, and other profiles via `npx skills`.
23
24---
25
26## What lives where
27
28Post-cleanup layout. Sources of truth at the top, distribution mirrors below, build outputs in `dist/`, human docs alongside each skill.
29
30```
31caveman/
32├── README.md # Front door (product pitch)
33├── INSTALL.md # Per-agent install commands
34├── CONTRIBUTING.md # Dev guide
35├── CLAUDE.md # This file (maintainer instructions)
36├── AGENTS.md / GEMINI.md # Autodiscovery files (must stay at root)
37│
38├── install.sh / install.ps1 # 30-line shims → bin/install.js
39│
40├── bin/ # Unified installer
41│ ├── install.js # Single source for all 30+ agents (PROVIDERS array)
42│ └── lib/settings.js # JSONC-tolerant settings.json reader/writer
43│
44├── skills/ # ALL skills, single source of truth
45│ ├── caveman/{SKILL.md, README.md}
46│ ├── caveman-commit/{SKILL.md, README.md}
47│ ├── caveman-review/{SKILL.md, README.md}
48│ ├── caveman-help/{SKILL.md, README.md}
49│ ├── caveman-stats/{SKILL.md, README.md}
50│ ├── caveman-compress/{SKILL.md, README.md, scripts/}
51│ └── cavecrew/{SKILL.md, README.md}
52│
53├── agents/ # cavecrew subagents (single source — kept at root for plugin auto-discovery)
54├── commands/ # Codex/Gemini TOML command stubs (root for plugin auto-discovery)
55│
56├── src/ # Internal source — not auto-discovered by plugin
57│ ├── hooks/ # Claude Code hooks (installer reads here)
58│ ├── rules/ # Auto-activation rule body (single source)
59│ ├── tools/ # caveman-init.js (per-repo rule writer)
60│ └── mcp-servers/ # caveman-shrink npm-published MCP middleware
61│
62├── packages/ # Current public packages
63│ ├── agent/ # @caveman-ai/agent runtime + Cave Build compiler
64│ ├── create-caveman-agent/ # Agent SDK project initializer
65│ ├── cli/ # @caveman-ai/cli
66│ ├── sdk/ # TypeScript + Python gateway clients
67│ ├── kit/ · graders/ # Honesty UI surfaces + fail-closed eval graders
68│ ├── mastra/ · subagent-tax/ # Mastra adapter + local harness-prefix benchmark
69│ └── shared/ # Contracts + binary installer
70├── engine/ · proxy/ # BSL local compression runtime + provider proxy
71├── cacheengine/ · rewriter/ # Standalone cache planner + prompt rewriter
72├── mcp/ · mem/ · shrink/ # Recovery tools, memory, output compression
73├── browse/ · extension/ # Local browser driver + MV3 extension
74├── shared/ # Provider catalog + BSL platform libraries
75│
76├── .claude-plugin/ # Claude Code plugin manifest (REQUIRED at root)
77├── plugins/caveman/ # Claude Code plugin distribution (CI-mirrored)
78│ ├── skills/ # ← from skills/
79│ └── agents/ # ← from agents/
80│
81├── dist/ # Build artifacts (gitignored)
82│ └── caveman.skill # ZIP of skills/caveman/, rebuilt by CI
83│
84├── tests/ # All tests (Node + Python)
85├── benchmarks/ # Real token measurements through Claude API
86├── evals/ # Three-arm eval harness
87├── docs/ # User-facing docs site
88└── .github/workflows/ # CI sync
89```
90
91---
92
93## File structure and what owns what
94
95### Single source of truth files — edit only these
96
97| File | What it controls |
98|------|-----------------|
99| `skills/caveman/SKILL.md` | Caveman behavior: intensity levels, rules, wenyan mode, auto-clarity, persistence. Only file to edit for behavior changes. |
100| `src/rules/caveman-activate.md` | Always-on auto-activation rule body. Consumed by `src/tools/caveman-init.js` when a user runs `npx caveman --with-init` (per-repo IDE rule files). Edit here, not in any per-agent rule copy. |
101| `src/rules/caveman-openclaw-bootstrap.md` | Marker-fenced bootstrap snippet appended to `~/.openclaw/workspace/SOUL.md` by `bin/lib/openclaw.js`. Drives always-on caveman through the OpenClaw gateway. Must include the SENTINEL `Respond terse like smart caveman` and stay well under OpenClaw's 12K-per-bootstrap-file cap. |
102| `bin/lib/openclaw.js` | OpenClaw install/uninstall helper. Frontmatter merge (`version`, `always: true`), SOUL.md marker append/strip, idempotent. Shared by `bin/install.js` and `src/tools/caveman-init.js`. |
103| `skills/caveman-commit/SKILL.md` | Caveman commit message behavior. Fully independent skill. |
104| `skills/caveman-review/SKILL.md` | Caveman code review behavior. Fully independent skill. |
105| `skills/caveman-help/SKILL.md` | Quick-reference card. One-shot display, not a persistent mode. |
106| `skills/caveman-compress/SKILL.md` | Compress sub-skill behavior. |
107| `skills/cavecrew/SKILL.md` | Cavecrew decision guide — when to delegate to caveman subagents vs vanilla. Edit only here. |
108| `agents/cavecrew-investigator.md` | Read-only locator subagent (haiku). Output contract: `path:line — symbol — note`. |
109| `agents/cavecrew-builder.md` | Surgical 1-2 file editor subagent. Refuses 3+ file scope. |
110| `agents/cavecrew-reviewer.md` | Diff/file reviewer subagent (haiku). One-line findings with severity emoji. |
111| `src/plugins/opencode/plugin.js` | opencode native plugin. ESM Bun module — `session.created` writes flag, `tui.prompt.append` parses slash/natural-language activation and appends per-prompt reinforcement. Reuses `caveman-config.js` via `createRequire`. |
112| `src/plugins/opencode/commands/*.md` | Six opencode slash-command prompt templates (`/caveman`, `/caveman-{commit,review,compress,stats,help}`). |
113
114### Auto-generated / auto-synced — do not edit directly
115
116We removed the agent-specific dotdir mirrors at the repo root (`.cursor/`, `.windsurf/`, `.clinerules/`, `.github/copilot-instructions.md`, root `caveman/SKILL.md`). They were never read by the installer — only used to self-apply caveman to this repo when a maintainer opened it in Cursor/Windsurf/Cline. Devs who want caveman in their editor while editing this repo should run `npx caveman --with-init` once (writes per-repo rule files from `src/rules/caveman-activate.md` via `src/tools/caveman-init.js`). For per-user installs through the upstream skills CLI, `npx caveman --only <agent>` runs `npx skills add ... -a <profile>`.
117
118A handful of dotdir leftovers (`.junie/`, `.kiro/`, `.roo/`, `.agents/`) still hold a stale `cavecrew/SKILL.md` mirror from before the cleanup. They aren't read by anything in the current install path; remove on sight, no migration needed.
119
120What's left is the Claude Code plugin distribution (required by the plugin loader) and the release ZIP.
121
122| File | Synced from |
123|------|-------------|
124| `plugins/caveman/skills/caveman/SKILL.md` | `skills/caveman/SKILL.md` |
125| `plugins/caveman/skills/caveman-compress/SKILL.md` (+ `scripts/`) | `skills/caveman-compress/SKILL.md` (+ `scripts/`) |
126| `plugins/caveman/skills/cavecrew/SKILL.md` | `skills/cavecrew/SKILL.md` |
127| `plugins/caveman/agents/cavecrew-*.md` | `agents/cavecrew-*.md` |
128| `dist/caveman.skill` | ZIP of `skills/caveman/` directory (gitignored; rebuilt by CI on release) |
129
130Skills not in this table (`caveman-commit`, `caveman-review`, `caveman-help`, `caveman-stats`) are not mirrored into the Claude Code plugin distribution by CI. They reach Claude Code through the standalone hook + skill install path, and reach other agents via `npx skills add`. A `plugins/caveman/skills/caveman-stats/` directory is currently checked in as a hand-committed copy; the sync workflow does not touch it, so don't rely on edits there to propagate.
131
132---
133
134## CI sync workflow
135
136`.github/workflows/sync-skill.yml` triggers on main push when `skills/**/SKILL.md` or `agents/cavecrew-*.md` changes.
137
138What it does:
1391. Copies `skills/caveman/SKILL.md` and `skills/cavecrew/SKILL.md` into their `plugins/caveman/skills/<name>/` mirrors so the Claude Code plugin loader sees the latest behavior.
1402. Copies `skills/caveman-compress/SKILL.md` and its `scripts/` into `plugins/caveman/skills/caveman-compress/`.
1413. Copies `agents/cavecrew-*.md` into `plugins/caveman/agents/`.
1424. Rebuilds `dist/caveman.skill` (ZIP of `skills/caveman/`) for the release artifact.
1435. Commits and pushes with `[skip ci]` to avoid loops.
144
145CI bot commits as `github-actions[bot]`. After PR merge, wait for workflow before declaring release complete.
146
147The old steps that mirrored SKILL.md and rules into root dotdirs (`.cursor/`, `.windsurf/`, `.clinerules/`, `.github/copilot-instructions.md`) are gone — those mirrors no longer exist. The old `caveman-compress/` → `skills/compress/` rename-on-sync is also gone now that compress lives at `skills/caveman-compress/`.
148
149---
150
151## Hook system (Claude Code)
152
153Three hooks in `src/hooks/` plus a `caveman-config.js` shared module and a `package.json` CommonJS marker. Communicate via flag file at `$CLAUDE_CONFIG_DIR/.caveman-active` (falls back to `~/.claude/.caveman-active`).
154
155```
156SessionStart hook ──writes "full"──▶ $CLAUDE_CONFIG_DIR/.caveman-active ◀──writes mode── UserPromptSubmit hook
157 │
158 reads
159 ▼
160 caveman-statusline.sh
161 [CAVEMAN] / [CAVEMAN:ULTRA] / ...
162```
163
164`src/hooks/package.json` pins the directory to `{"type": "commonjs"}` so the `.js` hooks resolve as CJS even when an ancestor `package.json` (e.g. `~/.claude/package.json` from another plugin) declares `"type": "module"`. Without this, `require()` blows up with `ReferenceError: require is not defined in ES module scope`.
165
166All hooks honor `CLAUDE_CONFIG_DIR` for non-default Claude Code config locations.
167
168### `src/hooks/caveman-config.js` — shared module
169
170Exports:
171- `getDefaultMode()` — resolves default mode in order: `CAVEMAN_DEFAULT_MODE` env var → repo-local config (`<cwd>/.caveman/config.json` or `<cwd>/.caveman.json`, walking up to the filesystem root) → user config (`$XDG_CONFIG_HOME/caveman/config.json` / `~/.config/caveman/config.json` / `%APPDATA%\caveman\config.json`) → `'full'`. The env var short-circuits before any cwd walk. Repo-local config lets a team check in a per-project default without polluting every contributor's env or user config.
172- `findRepoConfigPath(start)` — walks up from `start` (default `process.cwd()`) looking for the first `.caveman/config.json` or `.caveman.json`. Bounded to 64 ancestors. Refuses symlinked files (symmetric with `safeWriteFlag` / `readFlag`).
173- `safeWriteFlag(flagPath, content)` — symlink-safe flag write. Refuses if flag target or its immediate parent is a symlink. Opens with `O_NOFOLLOW` where supported. Atomic temp + rename. Creates with `0600`. Protects against local attackers replacing the predictable flag path with a symlink to clobber files writable by the user. Used by both write hooks. Silent-fails on all filesystem errors.
174
175### `src/hooks/caveman-activate.js` — SessionStart hook
176
177Runs once per Claude Code session start. Three things:
1781. Writes the active mode to `$CLAUDE_CONFIG_DIR/.caveman-active` via `safeWriteFlag` (creates if missing)
1792. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user
1803. Checks `settings.json` for statusline config; if missing, appends nudge to offer setup on first interaction
181
182Silent-fails on all filesystem errors — never blocks session start.
183
184### `src/hooks/caveman-mode-tracker.js` — UserPromptSubmit hook
185
186Reads JSON from stdin. Three responsibilities:
187
188**1. Slash-command activation.** If prompt starts with `/caveman`, writes mode to flag file via `safeWriteFlag`:
189- `/caveman` → configured default (see `caveman-config.js`, defaults to `full`)
190- `/caveman lite` → `lite`
191- `/caveman ultra` → `ultra`
192- `/caveman wenyan` or `/caveman wenyan-full` → `wenyan` (alias) / `wenyan-full`
193- `/caveman wenyan-lite` → `wenyan-lite`
194- `/caveman wenyan-ultra` → `wenyan-ultra`
195- `/caveman-commit` → `commit`
196- `/caveman-review` → `review`
197- `/caveman-compress` → `compress`
198
199**2. Natural-language activation/deactivation.** Matches phrases like "activate caveman", "turn on caveman mode", "talk like caveman" and writes the configured default mode. Matches "stop caveman", "disable caveman", "normal mode", "deactivate caveman" etc. and deletes the flag file. README promises these triggers, the hook enforces them.
200
201**3. Per-turn reinforcement.** When flag is set to a non-independent mode (i.e. not `commit`/`review`/`compress`), emits a small `hookSpecificOutput` JSON reminder so the model keeps caveman style after other plugins inject competing instructions mid-conversation. The full ruleset still comes from SessionStart — this is just an attention anchor.
202
203### `src/hooks/caveman-statusline.sh` — Statusline badge
204
205Reads flag file at `$CLAUDE_CONFIG_DIR/.caveman-active`. Outputs colored badge string for Claude Code statusline:
206- `full` or empty → `[CAVEMAN]` (orange)
207- anything else → `[CAVEMAN:<MODE_UPPERCASED>]` (orange)
208
209Then appends the lifetime-savings suffix (`⛏ 12.4k`) read from `$CLAUDE_CONFIG_DIR/.caveman-statusline-suffix` — written by `caveman-stats.js` on every `/caveman-stats` run. **Default on**; users opt out with `CAVEMAN_STATUSLINE_SAVINGS=0`. The suffix file is absent until `/caveman-stats` runs at least once, so fresh installs render no fake number.
210
211Configured in `settings.json` under `statusLine.command`. PowerShell counterpart at `src/hooks/caveman-statusline.ps1` for Windows. Both scripts symlink-refuse and whitelist-validate the flag/suffix file contents — never echo arbitrary bytes.
212
213### Hook installation
214
215**Plugin install** — hooks wired automatically by plugin system.
216
217**Standalone install** — `bin/install.js` (the unified Node installer) copies hook files into `$CLAUDE_CONFIG_DIR/hooks/` and merges SessionStart + UserPromptSubmit + statusline into `settings.json`. Uses the JSONC-tolerant helpers in `bin/lib/settings.js` so a commented `settings.json` no longer crashes the merge. Defensive `validateHookFields` runs before every write to prevent a single malformed hook from poisoning the entire file (Claude Code Zod silently discards the whole `settings.json` on schema mismatch).
218
219The `install.sh` / `install.ps1` shims at the repo root delegate to `bin/install.js` via `node` (local clone) or `npx -y github:JuliusBrussee/caveman` (curl|bash). No legacy fallback path remains — earlier `install.sh.legacy` / `install.ps1.legacy` files were removed.
220
221**Uninstall** — `npx -y github:JuliusBrussee/caveman -- --uninstall` (or `node bin/install.js --uninstall` from a clone). Strips caveman hook entries from `settings.json` via substring marker `caveman`, deletes hook files, and removes the Claude plugin / Gemini extension. Skill installs done via `npx skills add` must be removed via the IDE's skill manager (we don't track them).
222
223---
224
225## Skill system
226
227Skills = Markdown files with YAML frontmatter consumed by Claude Code's skill/plugin system and by `npx skills` for other agents.
228
229Each skill has a human-facing `README.md` alongside the LLM-facing `SKILL.md`. The README explains what the skill does for users browsing GitHub; the SKILL.md is the prompt body the agent loads. Don't merge them — different audiences, different formats.
230
231### Intensity levels
232
233Defined in `skills/caveman/SKILL.md`. Six levels: `lite`, `full` (default), `ultra`, `wenyan-lite`, `wenyan-full`, `wenyan-ultra`. Persists until changed or session ends.
234
235### Auto-clarity rule
236
237Caveman drops to normal prose for: security warnings, irreversible action confirmations, multi-step sequences where fragment ambiguity risks misread, user confused or repeating question. Resumes after. Defined in skill — preserve in any SKILL.md edit.
238
239### caveman-compress
240
241Sub-skill in `skills/caveman-compress/SKILL.md`. Takes file path, compresses prose to caveman style, writes to original path, saves backup at `<filename>.original.md`. Validates headings, code blocks, URLs, file paths, commands preserved. Retries up to 2 times on failure with targeted patches only. Requires Python 3.10+.
242
243The slash command is `/caveman-compress` everywhere — same name in plugin and standalone install. CI no longer renames the directory on sync (the old `caveman-compress/` → `skills/compress/` sed rename is gone now that the source lives at `skills/caveman-compress/`).
244
245### caveman-commit / caveman-review
246
247Independent skills in `skills/caveman-commit/SKILL.md` and `skills/caveman-review/SKILL.md`. Both have own `description` and `name` frontmatter so they load independently. caveman-commit: Conventional Commits, ≤50 char subject. caveman-review: one-line comments in `L<line>: <severity> <problem>. <fix>.` format.
248
249---
250
251## Agent distribution
252
253How caveman reaches each agent type:
254
255| Agent | Mechanism | Auto-activates? |
256|-------|-----------|----------------|
257| Claude Code | Plugin (hooks + skills) or standalone hooks | Yes — SessionStart hook injects rules |
258| Codex | Plugin in `plugins/caveman/` plus repo `.codex/hooks.json` and `.codex/config.toml` | Yes on macOS/Linux — SessionStart hook |
259| Gemini CLI | Extension with `GEMINI.md` context file | Yes — context file loads every session |
260| opencode | Native plugin (`src/plugins/opencode/`) copied into `~/.config/opencode/plugins/caveman/` + `AGENTS.md` ruleset + skills/agents/commands directories. Plugin uses `session.created` and `tui.prompt.append` lifecycle hooks. No statusline (opencode TUI exposes no plugin-writable badge). | Yes — `session.created` writes flag, `AGENTS.md` carries always-on ruleset |
261| OpenClaw | Workspace skill at `~/.openclaw/workspace/skills/caveman/SKILL.md` (frontmatter merged with `version` + `always: true`) plus a marker-fenced bootstrap block in `~/.openclaw/workspace/SOUL.md`. Both writes go through `bin/lib/openclaw.js`; workspace path is overridable via `OPENCLAW_WORKSPACE`. | Yes — SOUL.md is auto-injected each turn under "Project Context" (subject to OpenClaw's 12K-per-file / 60K-total bootstrap caps) |
262| Cursor | `npx skills add ... -a cursor` (default via `--only cursor`) writes the upstream skill profile; per-repo `.cursor/rules/caveman.mdc` via `--with-init` (calls `src/tools/caveman-init.js`) | Yes — always-on rule |
263| Windsurf | `npx skills add ... -a windsurf` (default via `--only windsurf`); per-repo `.windsurf/rules/caveman.md` via `--with-init` | Yes — always-on rule |
264| Cline | `npx skills add ... -a cline` (default via `--only cline`); per-repo `.clinerules/caveman.md` via `--with-init` | Yes — Cline auto-discovers `.clinerules/` |
265| Copilot | `npx skills add ... -a github-copilot` (soft probe — pass `--only copilot`); per-repo `.github/copilot-instructions.md` + `AGENTS.md` via `--with-init` | Yes — repo-wide instructions |
266| Others (Junie, Trae, Warp, Tabnine, Mistral, Qwen, Devin, Droid, ForgeCode, Bob, Crush, iFlow, OpenHands, Qoder, Rovo Dev, Replit, Antigravity, …) | `npx skills add JuliusBrussee/caveman -a <profile>` | No — user must say `/caveman` each session |
267
268opencode reaches Tier 1 minus the statusline (opencode's TUI has no plugin-writable badge). Mode flag lives at `~/.config/opencode/.caveman-active` for any external tooling that wants to surface it.
269
270For agents without hook systems, the always-on snippet lives in `INSTALL.md`'s "Want it always on?" section — keep current with `src/rules/caveman-activate.md`.
271
272**Adding a new agent.** Edit the `PROVIDERS` array in `bin/install.js` — single source of truth, no more bash/PS1 dual-source drift. Each entry has `id`, `label`, `mech`, `detect` (clause spec like `command:foo||dir:$HOME/x`), optional `profile` (vercel-labs/skills slug), optional `soft: true` (config-dir-only detection).
273
2741. The profile slug must exist in upstream [vercel-labs/skills](https://github.com/vercel-labs/skills). Verify against the README before merging — wrong slugs cause `npx skills add` to fail at runtime, not at install-script load.
2752. Run `node bin/install.js --list` to confirm the new row renders correctly.
2763. Soft probes (config-dir-only) are fine but tag them with `soft: true`. They render with `(soft)` in `--list` so users know detection is best-effort.
277
278---
279
280## Evals
281
282`evals/` has three-arm harness:
283- `__baseline__` — no system prompt
284- `__terse__` — `Answer concisely.`
285- `<skill>` — `Answer concisely.\n\n{SKILL.md}`
286
287Honest delta = **skill vs terse**, not skill vs baseline. Baseline comparison conflates skill with generic terseness — that cheating. Harness designed to prevent this.
288
289`llm_run.py` calls `claude -p --system-prompt ...` per (prompt, arm), saves to `evals/snapshots/results.json`. `measure.py` reads snapshot offline with tiktoken (OpenAI BPE — approximates Claude tokenizer, ratios meaningful, absolute numbers approximate).
290
291Add skill: drop `skills/<name>/SKILL.md`. Harness auto-discovers. Add prompt: append line to `evals/prompts/en.txt`.
292
293Snapshots committed to git. CI reads without API calls. Only regenerate when SKILL.md or prompts change.
294
295---
296
297## Benchmarks
298
299`benchmarks/` runs real prompts through Claude API (not Claude Code CLI), records raw token counts. Results committed as JSON in `benchmarks/results/`. Benchmark table in README generated from results — update when regenerating.
300
301To reproduce: `uv run python benchmarks/run.py` (needs `ANTHROPIC_API_KEY` in `.env.local`).
302
303---
304
305## Key rules for agents working here
306
307- Edit `skills/<name>/SKILL.md` for behavior changes. Never edit synced copies under `plugins/caveman/skills/`.
308- Edit `src/rules/caveman-activate.md` for auto-activation rule changes. Never edit any per-agent rule copy a user has on their machine.
309- Edit `src/rules/caveman-openclaw-bootstrap.md` for the OpenClaw SOUL.md bootstrap snippet. Keep the `<!-- caveman-begin -->` / `<!-- caveman-end -->` markers and the `Respond terse like smart caveman` sentinel — `bin/lib/openclaw.js` keys idempotency off both. If you change the embedded fallback in `bin/lib/openclaw.js`, keep it byte-equivalent to the file.
310- Per-skill human docs live in `skills/<name>/README.md`. The LLM-facing body is in `SKILL.md`. Don't merge them — different audiences.
311- Build artifacts go in `dist/`. Never check files into `dist/` manually — CI rebuilds them on push, and `dist/` is gitignored.
312- README most important file for user-facing impact. Optimize for non-technical readers. Preserve caveman voice.
313- `INSTALL.md` is the per-agent install reference. Keep the install table in `README.md` short and link out to `INSTALL.md` for the full matrix.
314- Benchmark and eval numbers must be real. Never fabricate or estimate.
315- CI workflow commits back to main after merge. Account for when checking branch state.
316- Hook files must silent-fail on all filesystem errors. Never let hook crash block session start.
317- Any new flag file write must go through `safeWriteFlag()` in `caveman-config.js`. Direct `fs.writeFileSync` on predictable user-owned paths reopens the symlink-clobber attack surface.
318- Hooks must respect `CLAUDE_CONFIG_DIR` env var, not hardcode `~/.claude`. Same for `bin/install.js` / statusline scripts.
319- `bin/install.js` is the only installer source. `install.sh` / `install.ps1` at repo root are 30-line shims that delegate to it. Never re-add per-OS install logic to the shims — that's how we got the Windows quoting bug (#249).
320- Any settings.json read in installer or hooks must go through `bin/lib/settings.js` `readSettings()` so JSONC comments don't crash the merge. Any settings.json write must run through `validateHookFields()` first.
321
@@ −1 +1 @@
1−# agents — the agent-profile registry (`caveman wrap` data)
1+# CLAUDE.md — caveman
22
3−**This file is a pointer. The orientation lives in [`CLAUDE.md`](CLAUDE.md)** (same directory) —
4−one source, kept current, so the two cannot diverge again.
3+## README is a product artifact
54
6−Read `CLAUDE.md` for: how a profile points an agent at the gateway (`injection.method`), the
7−three-tier `injection_completeness` honesty scale (declarative / builder-assisted / code-only) and
8−why "adding an agent is a pure data change" is only true for the declarative tier, command/skill
9−surfaces, and the fail-closed compile invariants (catalog-priced models, derived CI pins,
10−verification staleness).
5+README = product front door. Non-technical people read it to decide if caveman worth install. Treat like UI copy.
6+
7+**Rules for any README change:**
8+
9+- Readable by non-AI-agent users. If you write "SessionStart hook injects system context," invisible to most — translate it.
10+- Keep Before/After examples first. That the pitch.
11+- Install table always complete + accurate. One broken install command costs real user.
12+- What You Get table must sync with actual code. Feature ships or removed → update table.
13+- Preserve voice. Caveman speak in README on purpose. "Brain still big." "Cost go down forever." "One rock. That it." — intentional brand. Don't normalize.
14+- Benchmark numbers from real runs in `benchmarks/` and `evals/`. Never invent or round. Re-run if doubt.
15+- Adding new agent to install table → add detail block in `<details>` section below.
16+- Readability check before any README commit: would non-programmer understand + install within 60 seconds?
17+
18+---
19+
20+## Project overview
21+
22+Caveman makes AI coding agents respond in compressed caveman-style prose while preserving technical substance, code, commands, and exact errors. Publish no reduction or quality-equivalence percentage without a committed reviewed benchmark. Ships as Claude Code plugin, Codex plugin, Gemini CLI extension, and agent rule files for Cursor, Windsurf, Cline, Copilot, and other profiles via `npx skills`.
23+
24+---
25+
26+## What lives where
27+
28+Post-cleanup layout. Sources of truth at the top, distribution mirrors below, build outputs in `dist/`, human docs alongside each skill.
29+
30+```
31+caveman/
32+├── README.md # Front door (product pitch)
33+├── INSTALL.md # Per-agent install commands
34+├── CONTRIBUTING.md # Dev guide
35+├── CLAUDE.md # This file (maintainer instructions)
36+├── AGENTS.md / GEMINI.md # Autodiscovery files (must stay at root)
37+│
38+├── install.sh / install.ps1 # 30-line shims → bin/install.js
39+│
40+├── bin/ # Unified installer
41+│ ├── install.js # Single source for all 30+ agents (PROVIDERS array)
42+│ └── lib/settings.js # JSONC-tolerant settings.json reader/writer
43+│
44+├── skills/ # ALL skills, single source of truth
45+│ ├── caveman/{SKILL.md, README.md}
46+│ ├── caveman-commit/{SKILL.md, README.md}
47+│ ├── caveman-review/{SKILL.md, README.md}
48+│ ├── caveman-help/{SKILL.md, README.md}
49+│ ├── caveman-stats/{SKILL.md, README.md}
50+│ ├── caveman-compress/{SKILL.md, README.md, scripts/}
51+│ └── cavecrew/{SKILL.md, README.md}
52+│
53+├── agents/ # cavecrew subagents (single source — kept at root for plugin auto-discovery)
54+├── commands/ # Codex/Gemini TOML command stubs (root for plugin auto-discovery)
55+│
56+├── src/ # Internal source — not auto-discovered by plugin
57+│ ├── hooks/ # Claude Code hooks (installer reads here)
58+│ ├── rules/ # Auto-activation rule body (single source)
59+│ ├── tools/ # caveman-init.js (per-repo rule writer)
60+│ └── mcp-servers/ # caveman-shrink npm-published MCP middleware
61+│
62+├── packages/ # Current public packages
63+│ ├── agent/ # @caveman-ai/agent runtime + Cave Build compiler
64+│ ├── create-caveman-agent/ # Agent SDK project initializer
65+│ ├── cli/ # @caveman-ai/cli
66+│ ├── sdk/ # TypeScript + Python gateway clients
67+│ ├── kit/ · graders/ # Honesty UI surfaces + fail-closed eval graders
68+│ ├── mastra/ · subagent-tax/ # Mastra adapter + local harness-prefix benchmark
69+│ └── shared/ # Contracts + binary installer
70+├── engine/ · proxy/ # BSL local compression runtime + provider proxy
71+├── cacheengine/ · rewriter/ # Standalone cache planner + prompt rewriter
72+├── mcp/ · mem/ · shrink/ # Recovery tools, memory, output compression
73+├── browse/ · extension/ # Local browser driver + MV3 extension
74+├── shared/ # Provider catalog + BSL platform libraries
75+│
76+├── .claude-plugin/ # Claude Code plugin manifest (REQUIRED at root)
77+├── plugins/caveman/ # Claude Code plugin distribution (CI-mirrored)
78+│ ├── skills/ # ← from skills/
79+│ └── agents/ # ← from agents/
80+│
81+├── dist/ # Build artifacts (gitignored)
82+│ └── caveman.skill # ZIP of skills/caveman/, rebuilt by CI
83+│
84+├── tests/ # All tests (Node + Python)
85+├── benchmarks/ # Real token measurements through Claude API
86+├── evals/ # Three-arm eval harness
87+├── docs/ # User-facing docs site
88+└── .github/workflows/ # CI sync
89+```
90+
91+---
92+
93+## File structure and what owns what
94+
95+### Single source of truth files — edit only these
96+
97+| File | What it controls |
98+|------|-----------------|
99+| `skills/caveman/SKILL.md` | Caveman behavior: intensity levels, rules, wenyan mode, auto-clarity, persistence. Only file to edit for behavior changes. |
100+| `src/rules/caveman-activate.md` | Always-on auto-activation rule body. Consumed by `src/tools/caveman-init.js` when a user runs `npx caveman --with-init` (per-repo IDE rule files). Edit here, not in any per-agent rule copy. |
101+| `src/rules/caveman-openclaw-bootstrap.md` | Marker-fenced bootstrap snippet appended to `~/.openclaw/workspace/SOUL.md` by `bin/lib/openclaw.js`. Drives always-on caveman through the OpenClaw gateway. Must include the SENTINEL `Respond terse like smart caveman` and stay well under OpenClaw's 12K-per-bootstrap-file cap. |
102+| `bin/lib/openclaw.js` | OpenClaw install/uninstall helper. Frontmatter merge (`version`, `always: true`), SOUL.md marker append/strip, idempotent. Shared by `bin/install.js` and `src/tools/caveman-init.js`. |
103+| `skills/caveman-commit/SKILL.md` | Caveman commit message behavior. Fully independent skill. |
104+| `skills/caveman-review/SKILL.md` | Caveman code review behavior. Fully independent skill. |
105+| `skills/caveman-help/SKILL.md` | Quick-reference card. One-shot display, not a persistent mode. |
106+| `skills/caveman-compress/SKILL.md` | Compress sub-skill behavior. |
107+| `skills/cavecrew/SKILL.md` | Cavecrew decision guide — when to delegate to caveman subagents vs vanilla. Edit only here. |
108+| `agents/cavecrew-investigator.md` | Read-only locator subagent (haiku). Output contract: `path:line — symbol — note`. |
109+| `agents/cavecrew-builder.md` | Surgical 1-2 file editor subagent. Refuses 3+ file scope. |
110+| `agents/cavecrew-reviewer.md` | Diff/file reviewer subagent (haiku). One-line findings with severity emoji. |
111+| `src/plugins/opencode/plugin.js` | opencode native plugin. ESM Bun module — `session.created` writes flag, `tui.prompt.append` parses slash/natural-language activation and appends per-prompt reinforcement. Reuses `caveman-config.js` via `createRequire`. |
112+| `src/plugins/opencode/commands/*.md` | Six opencode slash-command prompt templates (`/caveman`, `/caveman-{commit,review,compress,stats,help}`). |
113+
114+### Auto-generated / auto-synced — do not edit directly
115+
116+We removed the agent-specific dotdir mirrors at the repo root (`.cursor/`, `.windsurf/`, `.clinerules/`, `.github/copilot-instructions.md`, root `caveman/SKILL.md`). They were never read by the installer — only used to self-apply caveman to this repo when a maintainer opened it in Cursor/Windsurf/Cline. Devs who want caveman in their editor while editing this repo should run `npx caveman --with-init` once (writes per-repo rule files from `src/rules/caveman-activate.md` via `src/tools/caveman-init.js`). For per-user installs through the upstream skills CLI, `npx caveman --only <agent>` runs `npx skills add ... -a <profile>`.
117+
118+A handful of dotdir leftovers (`.junie/`, `.kiro/`, `.roo/`, `.agents/`) still hold a stale `cavecrew/SKILL.md` mirror from before the cleanup. They aren't read by anything in the current install path; remove on sight, no migration needed.
119+
120+What's left is the Claude Code plugin distribution (required by the plugin loader) and the release ZIP.
121+
122+| File | Synced from |
123+|------|-------------|
124+| `plugins/caveman/skills/caveman/SKILL.md` | `skills/caveman/SKILL.md` |
125+| `plugins/caveman/skills/caveman-compress/SKILL.md` (+ `scripts/`) | `skills/caveman-compress/SKILL.md` (+ `scripts/`) |
126+| `plugins/caveman/skills/cavecrew/SKILL.md` | `skills/cavecrew/SKILL.md` |
127+| `plugins/caveman/agents/cavecrew-*.md` | `agents/cavecrew-*.md` |
128+| `dist/caveman.skill` | ZIP of `skills/caveman/` directory (gitignored; rebuilt by CI on release) |
129+
130+Skills not in this table (`caveman-commit`, `caveman-review`, `caveman-help`, `caveman-stats`) are not mirrored into the Claude Code plugin distribution by CI. They reach Claude Code through the standalone hook + skill install path, and reach other agents via `npx skills add`. A `plugins/caveman/skills/caveman-stats/` directory is currently checked in as a hand-committed copy; the sync workflow does not touch it, so don't rely on edits there to propagate.
131+
132+---
133+
134+## CI sync workflow
135+
136+`.github/workflows/sync-skill.yml` triggers on main push when `skills/**/SKILL.md` or `agents/cavecrew-*.md` changes.
137+
138+What it does:
139+1. Copies `skills/caveman/SKILL.md` and `skills/cavecrew/SKILL.md` into their `plugins/caveman/skills/<name>/` mirrors so the Claude Code plugin loader sees the latest behavior.
140+2. Copies `skills/caveman-compress/SKILL.md` and its `scripts/` into `plugins/caveman/skills/caveman-compress/`.
141+3. Copies `agents/cavecrew-*.md` into `plugins/caveman/agents/`.
142+4. Rebuilds `dist/caveman.skill` (ZIP of `skills/caveman/`) for the release artifact.
143+5. Commits and pushes with `[skip ci]` to avoid loops.
144+
145+CI bot commits as `github-actions[bot]`. After PR merge, wait for workflow before declaring release complete.
146+
147+The old steps that mirrored SKILL.md and rules into root dotdirs (`.cursor/`, `.windsurf/`, `.clinerules/`, `.github/copilot-instructions.md`) are gone — those mirrors no longer exist. The old `caveman-compress/` → `skills/compress/` rename-on-sync is also gone now that compress lives at `skills/caveman-compress/`.
148+
149+---
150+
151+## Hook system (Claude Code)
152+
153+Three hooks in `src/hooks/` plus a `caveman-config.js` shared module and a `package.json` CommonJS marker. Communicate via flag file at `$CLAUDE_CONFIG_DIR/.caveman-active` (falls back to `~/.claude/.caveman-active`).
154+
155+```
156+SessionStart hook ──writes "full"──▶ $CLAUDE_CONFIG_DIR/.caveman-active ◀──writes mode── UserPromptSubmit hook
157+ │
158+ reads
159+ ▼
160+ caveman-statusline.sh
161+ [CAVEMAN] / [CAVEMAN:ULTRA] / ...
162+```
163+
164+`src/hooks/package.json` pins the directory to `{"type": "commonjs"}` so the `.js` hooks resolve as CJS even when an ancestor `package.json` (e.g. `~/.claude/package.json` from another plugin) declares `"type": "module"`. Without this, `require()` blows up with `ReferenceError: require is not defined in ES module scope`.
165+
166+All hooks honor `CLAUDE_CONFIG_DIR` for non-default Claude Code config locations.
167+
168+### `src/hooks/caveman-config.js` — shared module
169+
170+Exports:
171+- `getDefaultMode()` — resolves default mode in order: `CAVEMAN_DEFAULT_MODE` env var → repo-local config (`<cwd>/.caveman/config.json` or `<cwd>/.caveman.json`, walking up to the filesystem root) → user config (`$XDG_CONFIG_HOME/caveman/config.json` / `~/.config/caveman/config.json` / `%APPDATA%\caveman\config.json`) → `'full'`. The env var short-circuits before any cwd walk. Repo-local config lets a team check in a per-project default without polluting every contributor's env or user config.
172+- `findRepoConfigPath(start)` — walks up from `start` (default `process.cwd()`) looking for the first `.caveman/config.json` or `.caveman.json`. Bounded to 64 ancestors. Refuses symlinked files (symmetric with `safeWriteFlag` / `readFlag`).
173+- `safeWriteFlag(flagPath, content)` — symlink-safe flag write. Refuses if flag target or its immediate parent is a symlink. Opens with `O_NOFOLLOW` where supported. Atomic temp + rename. Creates with `0600`. Protects against local attackers replacing the predictable flag path with a symlink to clobber files writable by the user. Used by both write hooks. Silent-fails on all filesystem errors.
174+
175+### `src/hooks/caveman-activate.js` — SessionStart hook
176+
177+Runs once per Claude Code session start. Three things:
178+1. Writes the active mode to `$CLAUDE_CONFIG_DIR/.caveman-active` via `safeWriteFlag` (creates if missing)
179+2. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user
180+3. Checks `settings.json` for statusline config; if missing, appends nudge to offer setup on first interaction
181+
182+Silent-fails on all filesystem errors — never blocks session start.
183+
184+### `src/hooks/caveman-mode-tracker.js` — UserPromptSubmit hook
185+
186+Reads JSON from stdin. Three responsibilities:
187+
188+**1. Slash-command activation.** If prompt starts with `/caveman`, writes mode to flag file via `safeWriteFlag`:
189+- `/caveman` → configured default (see `caveman-config.js`, defaults to `full`)
190+- `/caveman lite` → `lite`
191+- `/caveman ultra` → `ultra`
192+- `/caveman wenyan` or `/caveman wenyan-full` → `wenyan` (alias) / `wenyan-full`
193+- `/caveman wenyan-lite` → `wenyan-lite`
194+- `/caveman wenyan-ultra` → `wenyan-ultra`
195+- `/caveman-commit` → `commit`
196+- `/caveman-review` → `review`
197+- `/caveman-compress` → `compress`
198+
199+**2. Natural-language activation/deactivation.** Matches phrases like "activate caveman", "turn on caveman mode", "talk like caveman" and writes the configured default mode. Matches "stop caveman", "disable caveman", "normal mode", "deactivate caveman" etc. and deletes the flag file. README promises these triggers, the hook enforces them.
200+
201+**3. Per-turn reinforcement.** When flag is set to a non-independent mode (i.e. not `commit`/`review`/`compress`), emits a small `hookSpecificOutput` JSON reminder so the model keeps caveman style after other plugins inject competing instructions mid-conversation. The full ruleset still comes from SessionStart — this is just an attention anchor.
202+
203+### `src/hooks/caveman-statusline.sh` — Statusline badge
204+
205+Reads flag file at `$CLAUDE_CONFIG_DIR/.caveman-active`. Outputs colored badge string for Claude Code statusline:
206+- `full` or empty → `[CAVEMAN]` (orange)
207+- anything else → `[CAVEMAN:<MODE_UPPERCASED>]` (orange)
208+
209+Then appends the lifetime-savings suffix (`⛏ 12.4k`) read from `$CLAUDE_CONFIG_DIR/.caveman-statusline-suffix` — written by `caveman-stats.js` on every `/caveman-stats` run. **Default on**; users opt out with `CAVEMAN_STATUSLINE_SAVINGS=0`. The suffix file is absent until `/caveman-stats` runs at least once, so fresh installs render no fake number.
210+
211+Configured in `settings.json` under `statusLine.command`. PowerShell counterpart at `src/hooks/caveman-statusline.ps1` for Windows. Both scripts symlink-refuse and whitelist-validate the flag/suffix file contents — never echo arbitrary bytes.
212+
213+### Hook installation
214+
215+**Plugin install** — hooks wired automatically by plugin system.
216+
217+**Standalone install** — `bin/install.js` (the unified Node installer) copies hook files into `$CLAUDE_CONFIG_DIR/hooks/` and merges SessionStart + UserPromptSubmit + statusline into `settings.json`. Uses the JSONC-tolerant helpers in `bin/lib/settings.js` so a commented `settings.json` no longer crashes the merge. Defensive `validateHookFields` runs before every write to prevent a single malformed hook from poisoning the entire file (Claude Code Zod silently discards the whole `settings.json` on schema mismatch).
218+
219+The `install.sh` / `install.ps1` shims at the repo root delegate to `bin/install.js` via `node` (local clone) or `npx -y github:JuliusBrussee/caveman` (curl|bash). No legacy fallback path remains — earlier `install.sh.legacy` / `install.ps1.legacy` files were removed.
220+
221+**Uninstall** — `npx -y github:JuliusBrussee/caveman -- --uninstall` (or `node bin/install.js --uninstall` from a clone). Strips caveman hook entries from `settings.json` via substring marker `caveman`, deletes hook files, and removes the Claude plugin / Gemini extension. Skill installs done via `npx skills add` must be removed via the IDE's skill manager (we don't track them).
222+
223+---
224+
225+## Skill system
226+
227+Skills = Markdown files with YAML frontmatter consumed by Claude Code's skill/plugin system and by `npx skills` for other agents.
228+
229+Each skill has a human-facing `README.md` alongside the LLM-facing `SKILL.md`. The README explains what the skill does for users browsing GitHub; the SKILL.md is the prompt body the agent loads. Don't merge them — different audiences, different formats.
230+
231+### Intensity levels
232+
233+Defined in `skills/caveman/SKILL.md`. Six levels: `lite`, `full` (default), `ultra`, `wenyan-lite`, `wenyan-full`, `wenyan-ultra`. Persists until changed or session ends.
234+
235+### Auto-clarity rule
236+
237+Caveman drops to normal prose for: security warnings, irreversible action confirmations, multi-step sequences where fragment ambiguity risks misread, user confused or repeating question. Resumes after. Defined in skill — preserve in any SKILL.md edit.
238+
239+### caveman-compress
240+
241+Sub-skill in `skills/caveman-compress/SKILL.md`. Takes file path, compresses prose to caveman style, writes to original path, saves backup at `<filename>.original.md`. Validates headings, code blocks, URLs, file paths, commands preserved. Retries up to 2 times on failure with targeted patches only. Requires Python 3.10+.
242+
243+The slash command is `/caveman-compress` everywhere — same name in plugin and standalone install. CI no longer renames the directory on sync (the old `caveman-compress/` → `skills/compress/` sed rename is gone now that the source lives at `skills/caveman-compress/`).
244+
245+### caveman-commit / caveman-review
246+
247+Independent skills in `skills/caveman-commit/SKILL.md` and `skills/caveman-review/SKILL.md`. Both have own `description` and `name` frontmatter so they load independently. caveman-commit: Conventional Commits, ≤50 char subject. caveman-review: one-line comments in `L<line>: <severity> <problem>. <fix>.` format.
248+
249+---
250+
251+## Agent distribution
252+
253+How caveman reaches each agent type:
254+
255+| Agent | Mechanism | Auto-activates? |
256+|-------|-----------|----------------|
257+| Claude Code | Plugin (hooks + skills) or standalone hooks | Yes — SessionStart hook injects rules |
258+| Codex | Plugin in `plugins/caveman/` plus repo `.codex/hooks.json` and `.codex/config.toml` | Yes on macOS/Linux — SessionStart hook |
259+| Gemini CLI | Extension with `GEMINI.md` context file | Yes — context file loads every session |
260+| opencode | Native plugin (`src/plugins/opencode/`) copied into `~/.config/opencode/plugins/caveman/` + `AGENTS.md` ruleset + skills/agents/commands directories. Plugin uses `session.created` and `tui.prompt.append` lifecycle hooks. No statusline (opencode TUI exposes no plugin-writable badge). | Yes — `session.created` writes flag, `AGENTS.md` carries always-on ruleset |
261+| OpenClaw | Workspace skill at `~/.openclaw/workspace/skills/caveman/SKILL.md` (frontmatter merged with `version` + `always: true`) plus a marker-fenced bootstrap block in `~/.openclaw/workspace/SOUL.md`. Both writes go through `bin/lib/openclaw.js`; workspace path is overridable via `OPENCLAW_WORKSPACE`. | Yes — SOUL.md is auto-injected each turn under "Project Context" (subject to OpenClaw's 12K-per-file / 60K-total bootstrap caps) |
262+| Cursor | `npx skills add ... -a cursor` (default via `--only cursor`) writes the upstream skill profile; per-repo `.cursor/rules/caveman.mdc` via `--with-init` (calls `src/tools/caveman-init.js`) | Yes — always-on rule |
263+| Windsurf | `npx skills add ... -a windsurf` (default via `--only windsurf`); per-repo `.windsurf/rules/caveman.md` via `--with-init` | Yes — always-on rule |
264+| Cline | `npx skills add ... -a cline` (default via `--only cline`); per-repo `.clinerules/caveman.md` via `--with-init` | Yes — Cline auto-discovers `.clinerules/` |
265+| Copilot | `npx skills add ... -a github-copilot` (soft probe — pass `--only copilot`); per-repo `.github/copilot-instructions.md` + `AGENTS.md` via `--with-init` | Yes — repo-wide instructions |
266+| Others (Junie, Trae, Warp, Tabnine, Mistral, Qwen, Devin, Droid, ForgeCode, Bob, Crush, iFlow, OpenHands, Qoder, Rovo Dev, Replit, Antigravity, …) | `npx skills add JuliusBrussee/caveman -a <profile>` | No — user must say `/caveman` each session |
267+
268+opencode reaches Tier 1 minus the statusline (opencode's TUI has no plugin-writable badge). Mode flag lives at `~/.config/opencode/.caveman-active` for any external tooling that wants to surface it.
269+
270+For agents without hook systems, the always-on snippet lives in `INSTALL.md`'s "Want it always on?" section — keep current with `src/rules/caveman-activate.md`.
271+
272+**Adding a new agent.** Edit the `PROVIDERS` array in `bin/install.js` — single source of truth, no more bash/PS1 dual-source drift. Each entry has `id`, `label`, `mech`, `detect` (clause spec like `command:foo||dir:$HOME/x`), optional `profile` (vercel-labs/skills slug), optional `soft: true` (config-dir-only detection).
273+
274+1. The profile slug must exist in upstream [vercel-labs/skills](https://github.com/vercel-labs/skills). Verify against the README before merging — wrong slugs cause `npx skills add` to fail at runtime, not at install-script load.
275+2. Run `node bin/install.js --list` to confirm the new row renders correctly.
276+3. Soft probes (config-dir-only) are fine but tag them with `soft: true`. They render with `(soft)` in `--list` so users know detection is best-effort.
277+
278+---
279+
280+## Evals
281+
282+`evals/` has three-arm harness:
283+- `__baseline__` — no system prompt
284+- `__terse__` — `Answer concisely.`
285+- `<skill>` — `Answer concisely.\n\n{SKILL.md}`
286+
287+Honest delta = **skill vs terse**, not skill vs baseline. Baseline comparison conflates skill with generic terseness — that cheating. Harness designed to prevent this.
288+
289+`llm_run.py` calls `claude -p --system-prompt ...` per (prompt, arm), saves to `evals/snapshots/results.json`. `measure.py` reads snapshot offline with tiktoken (OpenAI BPE — approximates Claude tokenizer, ratios meaningful, absolute numbers approximate).
290+
291+Add skill: drop `skills/<name>/SKILL.md`. Harness auto-discovers. Add prompt: append line to `evals/prompts/en.txt`.
292+
293+Snapshots committed to git. CI reads without API calls. Only regenerate when SKILL.md or prompts change.
294+
295+---
296+
297+## Benchmarks
298+
299+`benchmarks/` runs real prompts through Claude API (not Claude Code CLI), records raw token counts. Results committed as JSON in `benchmarks/results/`. Benchmark table in README generated from results — update when regenerating.
300+
301+To reproduce: `uv run python benchmarks/run.py` (needs `ANTHROPIC_API_KEY` in `.env.local`).
302+
303+---
304+
305+## Key rules for agents working here
306+
307+- Edit `skills/<name>/SKILL.md` for behavior changes. Never edit synced copies under `plugins/caveman/skills/`.
308+- Edit `src/rules/caveman-activate.md` for auto-activation rule changes. Never edit any per-agent rule copy a user has on their machine.
309+- Edit `src/rules/caveman-openclaw-bootstrap.md` for the OpenClaw SOUL.md bootstrap snippet. Keep the `<!-- caveman-begin -->` / `<!-- caveman-end -->` markers and the `Respond terse like smart caveman` sentinel — `bin/lib/openclaw.js` keys idempotency off both. If you change the embedded fallback in `bin/lib/openclaw.js`, keep it byte-equivalent to the file.
310+- Per-skill human docs live in `skills/<name>/README.md`. The LLM-facing body is in `SKILL.md`. Don't merge them — different audiences.
311+- Build artifacts go in `dist/`. Never check files into `dist/` manually — CI rebuilds them on push, and `dist/` is gitignored.
312+- README most important file for user-facing impact. Optimize for non-technical readers. Preserve caveman voice.
313+- `INSTALL.md` is the per-agent install reference. Keep the install table in `README.md` short and link out to `INSTALL.md` for the full matrix.
314+- Benchmark and eval numbers must be real. Never fabricate or estimate.
315+- CI workflow commits back to main after merge. Account for when checking branch state.
316+- Hook files must silent-fail on all filesystem errors. Never let hook crash block session start.
317+- Any new flag file write must go through `safeWriteFlag()` in `caveman-config.js`. Direct `fs.writeFileSync` on predictable user-owned paths reopens the symlink-clobber attack surface.
318+- Hooks must respect `CLAUDE_CONFIG_DIR` env var, not hardcode `~/.claude`. Same for `bin/install.js` / statusline scripts.
319+- `bin/install.js` is the only installer source. `install.sh` / `install.ps1` at repo root are 30-line shims that delegate to it. Never re-add per-OS install logic to the shims — that's how we got the Windows quoting bug (#249).
320+- Any settings.json read in installer or hooks must go through `bin/lib/settings.js` `readSettings()` so JSONC comments don't crash the merge. Any settings.json write must run through `validateHookFields()` first.
11321
