CLAUDE.md

1# CLAUDE.md — caveman
2 
3## ForgeCat packaging note
4 
5This converted ForgeCat profile does not install the upstream top-level
6`bin/`, `src/`, or full `hooks/` helper tree directly. Runtime helper files
7that hooks and commands need are packaged under `skills/caveman/...`, because
8ForgeCat installs skill directories across Claude Code, Codex, and Cursor.
9Top-level `hooks/caveman-activate.js` and
10`hooks/caveman-mode-tracker.js` are launchers that dispatch to the installed
11skill helper path.
12 
13## README is a product artifact
14 
15README = product front door. Non-technical people read it to decide if caveman worth install. Treat like UI copy.
16 
17**Rules for any README change:**
18 
19- Readable by non-AI-agent users. If you write "SessionStart hook injects system context," invisible to most — translate it.
20- Keep Before/After examples first. That the pitch.
21- Install table always complete + accurate. One broken install command costs real user.
22- What You Get table must sync with actual code. Feature ships or removed → update table.
23- Preserve voice. Caveman speak in README on purpose. "Brain still big." "Cost go down forever." "One rock. That it." — intentional brand. Don't normalize.
24- Benchmark numbers from real runs in `benchmarks/` and `evals/`. Never invent or round. Re-run if doubt.
25- Adding new agent to install table → add detail block in `<details>` section below.
26- Readability check before any README commit: would non-programmer understand + install within 60 seconds?
27 
28---
29 
30## Project overview
31 
32Caveman makes AI coding agents respond in compressed caveman-style prose — cuts ~65-75% output tokens, full technical accuracy. Ships as Claude Code plugin, Codex plugin, Gemini CLI extension, agent rule files for Cursor, Windsurf, Cline, Copilot, 40+ others via `npx skills`.
33 
34---
35 
36## What lives where
37 
38Post-cleanup layout. Sources of truth at the top, distribution mirrors below, build outputs in `dist/`, human docs alongside each skill.
39 
40```
41caveman/
42├── README.md                    # Front door (product pitch)
43├── INSTALL.md                   # Per-agent install commands
44├── CONTRIBUTING.md              # Dev guide
45├── CLAUDE.md                    # This file (maintainer instructions)
46├── AGENTS.md / GEMINI.md        # Autodiscovery files (must stay at root)
47│
48├── install.sh / install.ps1     # 30-line shims → bin/install.js
49│
50├── bin/                         # Unified installer
51│   ├── install.js               # Single source for all 30+ agents (PROVIDERS array)
52│   └── lib/settings.js          # JSONC-tolerant settings.json reader/writer
53│
54├── skills/                      # ALL skills, single source of truth
55│   ├── caveman/{SKILL.md, README.md}
56│   ├── caveman-commit/{SKILL.md, README.md}
57│   ├── caveman-review/{SKILL.md, README.md}
58│   ├── caveman-help/{SKILL.md, README.md}
59│   ├── caveman-stats/{SKILL.md, README.md}
60│   ├── caveman-compress/{SKILL.md, README.md, scripts/}
61│   └── cavecrew/{SKILL.md, README.md}
62│
63├── agents/                      # cavecrew subagents (single source — kept at root for plugin auto-discovery)
64├── commands/                    # Codex/Gemini TOML command stubs (root for plugin auto-discovery)
65│
66├── src/                         # Internal source — not auto-discovered by plugin
67│   ├── hooks/                   # Claude Code hooks (installer reads here)
68│   ├── rules/                   # Auto-activation rule body (single source)
69│   ├── tools/                   # caveman-init.js (per-repo rule writer)
70│   └── mcp-servers/             # caveman-shrink npm-published MCP middleware
71│
72├── .claude-plugin/              # Claude Code plugin manifest (REQUIRED at root)
73├── plugins/caveman/             # Claude Code plugin distribution (CI-mirrored)
74│   ├── skills/                  # ← from skills/
75│   └── agents/                  # ← from agents/
76│
77├── dist/                        # Build artifacts (gitignored)
78│   └── caveman.skill            # ZIP of skills/caveman/, rebuilt by CI
79│
80├── tests/                       # All tests (Node + Python)
81├── benchmarks/                  # Real token measurements through Claude API
82├── evals/                       # Three-arm eval harness
83├── docs/                        # User-facing docs site
84└── .github/workflows/           # CI sync
85```
86 
87---
88 
89## File structure and what owns what
90 
91### Single source of truth files — edit only these
92 
93| File | What it controls |
94|------|-----------------|
95| `skills/caveman/SKILL.md` | Caveman behavior: intensity levels, rules, wenyan mode, auto-clarity, persistence. Only file to edit for behavior changes. |
96| `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. |
97| `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. |
98| `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`. |
99| `skills/caveman-commit/SKILL.md` | Caveman commit message behavior. Fully independent skill. |
100| `skills/caveman-review/SKILL.md` | Caveman code review behavior. Fully independent skill. |
101| `skills/caveman-help/SKILL.md` | Quick-reference card. One-shot display, not a persistent mode. |
102| `skills/caveman-compress/SKILL.md` | Compress sub-skill behavior. |
103| `skills/cavecrew/SKILL.md` | Cavecrew decision guide — when to delegate to caveman subagents vs vanilla. Edit only here. |
104| `agents/cavecrew-investigator.md` | Read-only locator subagent (haiku). Output contract: `path:line — symbol — note`. |
105| `agents/cavecrew-builder.md` | Surgical 1-2 file editor subagent. Refuses 3+ file scope. |
106| `agents/cavecrew-reviewer.md` | Diff/file reviewer subagent (haiku). One-line findings with severity emoji. |
107| `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`. |
108| `src/plugins/opencode/commands/*.md` | Six opencode slash-command prompt templates (`/caveman`, `/caveman-{commit,review,compress,stats,help}`). |
109 
110### Auto-generated / auto-synced — do not edit directly
111 
112We 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>`.
113 
114A 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.
115 
116What's left is the Claude Code plugin distribution (required by the plugin loader) and the release ZIP.
117 
118| File | Synced from |
119|------|-------------|
120| `plugins/caveman/skills/caveman/SKILL.md` | `skills/caveman/SKILL.md` |
121| `plugins/caveman/skills/caveman-compress/SKILL.md` (+ `scripts/`) | `skills/caveman-compress/SKILL.md` (+ `scripts/`) |
122| `plugins/caveman/skills/cavecrew/SKILL.md` | `skills/cavecrew/SKILL.md` |
123| `plugins/caveman/agents/cavecrew-*.md` | `agents/cavecrew-*.md` |
124| `dist/caveman.skill` | ZIP of `skills/caveman/` directory (gitignored; rebuilt by CI on release) |
125 
126Skills 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.
127 
128---
129 
130## CI sync workflow
131 
132`.github/workflows/sync-skill.yml` triggers on main push when `skills/**/SKILL.md` or `agents/cavecrew-*.md` changes.
133 
134What it does:
1351. 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.
1362. Copies `skills/caveman-compress/SKILL.md` and its `scripts/` into `plugins/caveman/skills/caveman-compress/`.
1373. Copies `agents/cavecrew-*.md` into `plugins/caveman/agents/`.
1384. Rebuilds `dist/caveman.skill` (ZIP of `skills/caveman/`) for the release artifact.
1395. Commits and pushes with `[skip ci]` to avoid loops.
140 
141CI bot commits as `github-actions[bot]`. After PR merge, wait for workflow before declaring release complete.
142 
143The 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/`.
144 
145---
146 
147## Hook system (Claude Code)
148 
149Three 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`).
150 
151```
152SessionStart hook ──writes "full"──▶ $CLAUDE_CONFIG_DIR/.caveman-active ◀──writes mode── UserPromptSubmit hook
153                                                       │
154                                                    reads
155                                                       ▼
156                                              caveman-statusline.sh
157                                            [CAVEMAN] / [CAVEMAN:ULTRA] / ...
158```
159 
160`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`.
161 
162All hooks honor `CLAUDE_CONFIG_DIR` for non-default Claude Code config locations.
163 
164### `src/hooks/caveman-config.js` — shared module
165 
166Exports:
167- `getDefaultMode()` — resolves default mode from `CAVEMAN_DEFAULT_MODE` env var, then `$XDG_CONFIG_HOME/caveman/config.json` / `~/.config/caveman/config.json` / `%APPDATA%\caveman\config.json`, then `'full'`
168- `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.
169 
170### `src/hooks/caveman-activate.js` — SessionStart hook
171 
172Runs once per Claude Code session start. Three things:
1731. Writes the active mode to `$CLAUDE_CONFIG_DIR/.caveman-active` via `safeWriteFlag` (creates if missing)
1742. Emits caveman ruleset as hidden stdout — Claude Code injects SessionStart hook stdout as system context, invisible to user
1753. Checks `settings.json` for statusline config; if missing, appends nudge to offer setup on first interaction
176 
177Silent-fails on all filesystem errors — never blocks session start.
178 
179### `src/hooks/caveman-mode-tracker.js` — UserPromptSubmit hook
180 
181Reads JSON from stdin. Three responsibilities:
182 
183**1. Slash-command activation.** If prompt starts with `/caveman`, writes mode to flag file via `safeWriteFlag`:
184- `/caveman` → configured default (see `caveman-config.js`, defaults to `full`)
185- `/caveman lite` → `lite`
186- `/caveman ultra` → `ultra`
187- `/caveman wenyan` or `/caveman wenyan-full` → `wenyan` (alias) / `wenyan-full`
188- `/caveman wenyan-lite` → `wenyan-lite`
189- `/caveman wenyan-ultra` → `wenyan-ultra`
190- `/caveman-commit` → `commit`
191- `/caveman-review` → `review`
192- `/caveman-compress` → `compress`
193 
194**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.
195 
196**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.
197 
198### `src/hooks/caveman-statusline.sh` — Statusline badge
199 
200Reads flag file at `$CLAUDE_CONFIG_DIR/.caveman-active`. Outputs colored badge string for Claude Code statusline:
201- `full` or empty → `[CAVEMAN]` (orange)
202- anything else → `[CAVEMAN:<MODE_UPPERCASED>]` (orange)
203 
204Then 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.
205 
206Configured 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.
207 
208### Hook installation
209 
210**Plugin install** — hooks wired automatically by plugin system.
211 
212**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).
213 
214The `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.
215 
216**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).
217 
218---
219 
220## Skill system
221 
222Skills = Markdown files with YAML frontmatter consumed by Claude Code's skill/plugin system and by `npx skills` for other agents.
223 
224Each 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.
225 
226### Intensity levels
227 
228Defined in `skills/caveman/SKILL.md`. Six levels: `lite`, `full` (default), `ultra`, `wenyan-lite`, `wenyan-full`, `wenyan-ultra`. Persists until changed or session ends.
229 
230### Auto-clarity rule
231 
232Caveman 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.
233 
234### caveman-compress
235 
236Sub-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+.
237 
238The 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/`).
239 
240### caveman-commit / caveman-review
241 
242Independent 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.
243 
244---
245 
246## Agent distribution
247 
248How caveman reaches each agent type:
249 
250| Agent | Mechanism | Auto-activates? |
251|-------|-----------|----------------|
252| Claude Code | Plugin (hooks + skills) or standalone hooks | Yes — SessionStart hook injects rules |
253| Codex | Plugin in `plugins/caveman/` plus repo `.codex/hooks.json` and `.codex/config.toml` | Yes on macOS/Linux — SessionStart hook |
254| Gemini CLI | Extension with `GEMINI.md` context file | Yes — context file loads every session |
255| 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 |
256| 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) |
257| 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 |
258| Windsurf | `npx skills add ... -a windsurf` (default via `--only windsurf`); per-repo `.windsurf/rules/caveman.md` via `--with-init` | Yes — always-on rule |
259| Cline | `npx skills add ... -a cline` (default via `--only cline`); per-repo `.clinerules/caveman.md` via `--with-init` | Yes — Cline auto-discovers `.clinerules/` |
260| 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 |
261| 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 |
262 
263opencode 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.
264 
265For 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`.
266 
267**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).
268 
2691. 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.
2702. Run `node bin/install.js --list` to confirm the new row renders correctly.
271 
272---
273 
274## Development workflow
275 
276### Node installer
277 
278`bin/install.js` is the single source of truth for provider detection and install behavior.
279 
280Helpers:
281- `bin/lib/settings.js` — reads/writes JSONC `settings.json` safely
282- `bin/lib/openclaw.js` — OpenClaw workspace skill + SOUL bootstrap installer
283 
284The shell / PowerShell shims should stay tiny wrappers only.
285 
286### Testing
287 
288- Installer tests: `node --test tests/installer/*.test.mjs`
289- Python validation / compression tests: `pytest tests/`
290- Repo sanity: `python tests/verify_repo.py`
291 
292### Key maintainer rules
293 
294- Edit `skills/<name>/SKILL.md` for behavior changes. Never edit synced copies under `plugins/caveman/skills/`.
295- Keep `README.md`, `INSTALL.md`, and the actual installer behavior in sync.
296- Preserve the exact trigger phrases promised in docs when editing hook matching logic.
297- Do not weaken symlink-safety or safe-write protections in hook/state helpers.
298- Per-skill human docs live in `skills/<name>/README.md`. The LLM-facing body is in `SKILL.md`. Don't merge them — different audiences.
299