feat(low-token): bundle caveman skill and wire into --low-token preset

[SamPlvs]

Summary

First Tier 1 deliverable per the Q3/H2 roadmap (#66). Bundles the caveman terse-output skill and wires it into the --low-token preset so it activates automatically when users opt into low-token mode.

How it works

zo build --low-token
   ↓
_LOW_TOKEN_PRESET["caveman"] = True
   ↓
_resolve_caveman() (CLI > plan > preset precedence)
   ↓
Orchestrator(caveman=True)
   ↓
_prompt_low_token_overrides() appends "Token Efficiency Skill: Caveman Mode"
   ↓
Lead prompt directs lead + sub-agents to use the auto-loaded skill

Opt-out paths (precedence order): --no-caveman CLI flag > plan caveman: false > preset default. Banner shows [low-token + caveman] for visual confirmation.

Why caveman is safe to auto-activate

The caveman skill explicitly preserves:

• Code blocks (verbatim)
• Quoted error strings (verbatim)
• Tool inputs (Write/Edit args — caveman only touches chat output, not tool calls)
• Structured artifacts (metrics.jsonl, result.md, training_status.json, agent contracts) — written via Write/Edit, not chat
• Security warnings + irreversible-action confirmations — caveman auto-disables for these per its own rules

So the gates that depend on structured outputs (Phase 4 ZOTrainingCallback artifacts, oracle's result.md, etc.) are not at risk.

Files

• .claude/skills/caveman/{SKILL.md, LICENSE, README.md} — vendored from upstream (MIT, Copyright (c) 2026 Julius Brussee), fetched 2026-05-05
• src/zo/cli.py — _LOW_TOKEN_PRESET["caveman"] = True; new _resolve_caveman() helper; --no-caveman flag on build and continue; banner badge update
• src/zo/orchestrator.py — Orchestrator.__init__ accepts caveman: bool; new caveman property; _prompt_low_token_overrides() extended with caveman directive
• src/zo/plan.py — PlanFrontmatter.caveman: bool | None (None = preset default; explicit False = opt-out)
• scripts/benchmark_low_token.sh — third run variant low-token-no-caveman for ablation

Test plan

• ruff clean on src/zo/{cli,orchestrator,plan}.py
• bash -n clean on scripts/benchmark_low_token.sh
• _resolve_caveman precedence verified for all 4 cases (default-on, --no-caveman wins, plan opt-out wins, no-low-token forces off)
• validate-docs.sh 10/10 + 1 pre-existing warning
• Unit tests for new preset flag, _resolve_caveman, prompt directive — follow-up commit
• Docs cascade: low-token-mode.mdx, low-token-preset.mdx, cost-benchmark.mdx — follow-up commit
• Bench run on MNIST plan (~25min, ~$5–7) to measure the actual savings delta — follow-up commit

Why draft

Wiring is in and unit-smoke-tested, but not yet validated end-to-end against a real zo build session. The bench run is the proof-of-savings step. Tests + docs land after the bench so they reflect what actually happens, not what the prompt says should happen.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying zero-operators with    Cloudflare Pages

Latest commit:	6a87b41
Status:	✅  Deploy successful!
Preview URL:	https://1c4cbb36.zero-operators.pages.dev
Branch Preview URL:	https://claude-caveman-ablation.zero-operators.pages.dev

View logs

[SamPlvs]

Correction in commit 6a87b41 — please read before reviewing the first commit's prompt directive.

While reviewing caveman's upstream CLAUDE.md after a sharp question from the user, found that caveman's always-on activation in Claude Code is delivered by SessionStart and UserPromptSubmit hooks, not by being a skill. The standalone install (hooks/install.sh in their repo) copies hook scripts into ~/.claude/hooks/ and patches ~/.claude/settings.json.

The first commit (f190bc7) wrote a prompt directive that said "ACTIVATE caveman skill. The vendored SKILL.md is auto-loaded by Claude Code". This was incorrect — skills in .claude/skills/<name>/SKILL.md are invocations, not always-on enforcement. Without the hooks, the file alone doesn't make agents adopt caveman speech.

We deliberately don't run upstream's install.sh (would modify the user's ~/.claude/ globally — too invasive for an opt-in cost-saving feature).

Fix in 6a87b41: the caveman rules are now inlined directly into the orchestrator prompt. Lead and every spawned sub-agent see the rules verbatim in their prompts. No skill or hook system dependency. The vendored SKILL.md stays as a reference + forward-compat artifact (and as documentation for users who choose to install caveman properly with hooks).

Net effect: same intent (caveman auto-on with --low-token), more honest mechanism (inline directive instead of "skill auto-load"), no architectural surprises hidden behind the abstraction.

The bench remains the only honest measurement of actual savings.