caveman-internal

Caveman Internal Protocol

Scope

IN-scope (compress)

• Artifact summaries written to .cavekit/artifacts/
• Context bundles between tasks (.cavekit/context-bundles/)
• Review notes and gap lists (non-user-facing)
• state.md notes: field and loop-log.md entries
• Status-block body (dashboard injected by the stop hook)
• Inter-agent handoff memos

OUT-of-scope (never compress)

• Source code (any language, any file)
• Git commit messages and PR descriptions
• Kits (specs), build sites, DESIGN.md
• Error messages that a human will act on
• Security warnings and deprecation notices
• Structured findings tables (P0/P1/P2/P3, coverage matrices)
• Regression test names and assertion messages

Compressing out-of-scope content is a bug. If a reader cannot act on a compressed artifact, regenerate it verbose and log a caveman fallback — see "Fallback protocol" below.

Intensity levels

Lite — trim the fat (~20% savings)

Professional tone. Grammar intact. Drop filler, pleasantries, hedging. Keep articles and full sentences.

Rate-limit middleware passes unit tests. Integration failed on 429 header case sensitivity. Fix in progress.

Full — default (~40% savings)

Classic caveman. Drop articles, filler, pleasantries. Fragments fine. Technical terms stay exact. Pattern: [thing] [action] [reason]. [next].

Rate-limit mw pass unit. Integration fail on 429 header case. Fixing.

Ultra — maximum grunt (~65% savings)

Telegraphic. Abbreviate common terms (DB, auth, config, req, res, fn, impl, mw, mcp). Arrow notation for causality. One-word answers when enough.

mw ok, int fail header case → fix

Automatic intensity selection

Consult the session budget ledger before writing an internal artifact:

Budget remaining	Intensity
> 50 %	lite
20 – 50 %	full
< 20 %	ultra

Override rules:

• depth = thorough tasks clamp to lite regardless of pressure (accuracy matters more than tokens when the stakes are high).
• phase = inspecting clamps to lite for the gap-analysis output.
• Security-sensitive artifacts clamp to lite.
• If the caller sets caveman_intensity explicitly in the artifact envelope, use that and skip auto-selection.

See references/budget-thresholds.md for the detailed decision table.

Fallback protocol

If a downstream reader cannot reconstruct intent from a compressed artifact:

1. Regenerate the artifact in full prose (no compression).
2. Append a one-line entry to state.md's "Caveman fallbacks" section:

   - 2026-04-17T12:34Z T-017 verifier fallback: artifact summary re-expanded
   

3. If the same artifact category fails 3+ times in one session, clamp that category to lite for the rest of the session and log to state.md.

Envelope

Every compressed artifact carries a tiny header:

<!-- caveman: intensity=full version=1 -->

Readers that see this header know the body is compressed and apply the reverse-expansion grammar (re-add articles, re-expand abbreviations) when rendering for a human.

Examples

Verbose	Full	Ultra
"The build completed successfully after three waves."	"Build complete. 3 waves."	"Build ok 3w"
"All tests pass, but one test was skipped due to a missing fixture."	"Tests pass. One skipped, missing fixture."	"Tests ok 1 skip fx"
"The reviewer flagged two critical issues in the auth middleware."	"Reviewer: 2 P0 in auth mw."	"Rev 2 P0 auth mw"

Integration with the existing caveman skill

The user-facing caveman skill governs how the assistant speaks to the user during a session (answers, explanations, replies). This caveman-internal skill governs how agents write artifacts for each other. Both must be on or both off for a coherent experience, so caveman_mode = off in config also disables this skill.