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

1. 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.