Integrate caveman-style token compression as companion skill

[jbaruch]

Summary

Integrate caveman-style output token compression into IIKit as an optional companion mode. IIKit skills are verbose — they produce long explanations, status updates, and artifact summaries that consume significant tokens without adding proportional value.

Motivation

• IIKit sessions are token-heavy. A full specify → plan → tasks → implement cycle can consume substantial output tokens on status updates, explanations, and artifact summaries alone.
• Caveman demonstrates ~65% output token reduction with no loss of technical accuracy.
• A referenced March 2026 study found brevity constraints improved accuracy by 26 percentage points on certain benchmarks.
• Input compression of IIKit's own skill prompts and CLAUDE.md could reduce session-start token cost by ~46%.

Scope

Output Compression

• Add a caveman mode toggle (e.g., /iikit-caveman on|off or a context.json flag)
• When active, all skill output (status messages, artifact summaries, validation reports) uses terse caveman-style language
• Code blocks, file paths, requirement IDs (FR-XXX, SC-XXX, T001), and artifact content pass through untouched
• Three levels: lite (grammar intact, filler removed), full (fragments, no articles), ultra (telegraphic)

Input Compression

• Apply caveman-compress to IIKit's own skill prompt files to reduce session-start token load
• Keep human-readable originals alongside compressed versions (like caveman's CLAUDE.md / CLAUDE.original.md pattern)
• Measure before/after token counts for the full skill set

Integration Points

• SessionStart hook or context.json flag to activate
• Per-skill opt-in (some skills like /iikit-01-specify produce user-facing artifacts that should stay verbose; status messages can compress)
• Compatible with existing caveman installation if user already has it

Non-Goals

• Does NOT change the IIKit workflow or phase structure
• Does NOT compress artifact content (spec.md, plan.md, tasks.md remain full prose)
• Does NOT affect thinking/reasoning tokens (only output)

Success Criteria

• Measurable token reduction (target: 40%+ on output, 30%+ on input)
• No loss of technical information in compressed output
• Artifact quality unchanged (same spec.md, plan.md, tasks.md content)
• User can toggle on/off without restarting session

Prior Art

• caveman — 65% output compression, 46% input compression
• caveman-compress — input token optimization

[jbaruch]

Benchmark results and scope update

Ran a 4-demo × 2-arm benchmark (todo CLI, URL-shortener REST API, Rust semver lib, CSV data pipeline) comparing full IIKit workflows with and without juliusbrussee/caveman active. All 8 runs headless via claude -p --output-format json on sonnet-4-6, no budget cap, same driver prompt and canned clarify answers per demo.

All 8 runs completed successfully with green test suites. Caveman won on every demo:

Demo	Control cost	Caveman cost	Δ cost	Δ duration	Δ output tok
todo	$5.51	$4.40	−20%	−11%	−34%
api	$4.65	$2.45	−47%	−57%	−44%
lib	$4.21	$3.93	−7%	−10%	−28%
pipeline	$4.83	$2.65	−45%	−46%	−22%
aggregate	$19.20	$13.43	−30%	−31%	−32%

Integrity preserved. Initial concern about reduced test coverage under caveman was wrong on closer inspection — analyze reports showed 94–100% FR coverage under both arms. Caveman writes closer to the spec-mandated minimum; control writes that minimum plus supplementary tests. Scenario-per-FR density is lower under caveman (e.g. lib: 3.8 → 2.1) but both satisfied the integrity chain (spec → testify → implement) and passed the analyze gate.

What caveman actually compresses

Chat between tool calls — per-turn assistant text drops 33–56% in 3 of 4 demos. Artifact contents (spec.md, plan.md, tasks.md) stay normal prose and in 3 of 4 demos were actually larger than control's. Caveman also has built-in Auto-Clarity that drops compression for warnings, multi-step sequences, and user clarification requests.

What landed now

• README — new "Recommended Companion: Caveman" section after Installation with benchmark summary and the /caveman full activation instruction
• /iikit-core init Step 5 (Report) — one-line recommendation nudging users to install the companion

No hooks, no custom /iikit-caveman skill, no AGENTS.md changes. A custom skill would duplicate caveman's toggle semantics (/caveman, trigger phrases, Auto-Clarity) and add maintenance drag without adding capability.

What remains open

Issue stays open to track input-compression of IIKit's own SKILL.md files via caveman-compress at publish time. That's a one-time publish-pipeline addition:

• Run caveman-compress over each SKILL.md at publish
• Ship compressed variants as the default, keep originals as .original.md for reference
• Expected impact: reduced SessionStart input cost for every user, complementing the runtime output savings caveman already provides

Full write-up and raw data: /tmp/iikit-bench-v2/results-v2.md (local — can share if helpful). Total benchmark spend: ~$33.