Repository navigation
Integrate caveman-style token compression as companion skill #46
Description
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
cavemanmode toggle (e.g.,/iikit-caveman on|offor 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.mdpattern) - 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-specifyproduce 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
Activity
jbaruch commentedon Apr 23, 2026
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/cavemanactive. All 8 runs headless viaclaude -p --output-format jsonon 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:
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
/caveman fullactivation instruction/iikit-core initStep 5 (Report) — one-line recommendation nudging users to install the companionNo hooks, no custom
/iikit-cavemanskill, 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.mdfiles viacaveman-compressat publish time. That's a one-time publish-pipeline addition:caveman-compressover eachSKILL.mdat publish.original.mdfor referenceFull write-up and raw data:
/tmp/iikit-bench-v2/results-v2.md(local — can share if helpful). Total benchmark spend: ~$33.asm0dey commentedon Jun 30, 2026
Maybe also makes sense to add https://github.com/DietrichGebert/ponytail