/caveman-internal

name: caveman-internal
description: Internal token optimization for Forge agent artifacts (handoff notes, artifact summaries, review notes). NOT exposed as a user-facing /caveman command.

<!-- Adapted from JuliusBrussee/caveman (MIT License) https://github.com/JuliusBrussee/caveman

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the conditions of the MIT License. -->

Caveman Internal Skill

Compress prose in Forge's own agent-to-agent artifacts so the autonomous loop spends fewer tokens on coordination and more on actual implementation. This skill is consumed internally by Forge agents (executor, planner, reviewer, verifier) when writing handoff notes, artifact summaries, and review reports. It is NOT a user-facing command and must never be invoked as `/caveman`.

Scope

In scope (compress these):

• `.forge/artifacts/{task-id}.json` artifact descriptions and key_decisions
• `.forge/context-bundles/` handoff notes between tasks
• Review summaries written by the reviewer agent
• Internal status reports passed between agents
• Token-ledger annotations and state.md "What's Done" entries

Out of scope (ALWAYS use normal verbose mode regardless of intensity):

• All code output (source files, code blocks, diffs, patches)
• Commit messages and PR descriptions
• User-facing spec files in `.forge/specs/`
• Security warnings of any kind
• Irreversible action confirmations (deletes, force-pushes, schema drops)
• Error messages humans need to act on
• Anything the user will read directly

Intensity Modes

Three levels. Higher intensity removes more, but technical terms (function names, file paths, identifiers, version numbers, error codes) stay verbatim at every level.

lite

Strip filler words and pleasantries. Keep articles, conjunctions, and full grammar. This is the safest mode and is the default for `standard` depth tasks.

Remove: just, really, basically, very, quite, simply, actually, essentially, indeed, clearly, obviously, sure, certainly, happy to help, of course, please note, it should be noted, as you can see, in order to (use "to").

Example:

• Before: "I just finished implementing the registration endpoint. Basically, it accepts an email and password, and it really validates them carefully before hashing the password with bcrypt."
• After: "Finished implementing the registration endpoint. It accepts an email and password, and validates them before hashing the password with bcrypt."

Token reduction: ~20%.

full

Drop articles (a, an, the) where meaning survives. Allow sentence fragments. Use shorter synonyms. Keep technical terminology precise. Default for `quick` depth tasks.

Substitutions: implement -> add, modify -> change, utilize -> use, demonstrate -> show, approximately -> about, in addition -> also, due to -> from, prior to -> before, subsequent to -> after, in the event that -> if.

Example:

• Before: "I have implemented the registration endpoint. It accepts an email and a password, validates them against the schema, and then hashes the password using bcrypt with twelve rounds before storing the user record in the database."
• After: "Added registration endpoint. Accepts email + password, validates against schema, hashes password with bcrypt 12 rounds, stores user record in database."

Token reduction: ~40%.

ultra

Emergency budget mode. Used when fewer than 20% of task budget tokens remain. Adds aggressive abbreviation and arrows for causality.

Abbreviations: database -> DB, authentication -> auth, configuration -> config, function -> fn, variable -> var, request -> req, response -> res, parameter -> param, environment -> env, repository -> repo, dependency -> dep, validation -> valid, error -> err, message -> msg, application -> app, server -> srv, client -> cli, production -> prod, development -> dev.

Strip conjunctions where meaning is clear. Use arrows for causality and flow: `X -> Y` means X causes/produces Y. Use `+` for "and" in lists.

Example:

• Before: "I have implemented the registration endpoint. It accepts an email and a password, validates them against the schema, and then hashes the password using bcrypt with twelve rounds before storing the user record in the database."
• After: "Added register endpoint. Accepts email+password -> valid vs schema -> bcrypt 12 rounds -> store user in DB."

Token reduction: ~65%.

Intensity Selection Logic

Agents self-select intensity at the start of each task by querying the task budget and applying the rule below. No external orchestrator is required.

Decision rule

Compute `remaining_percentage = remaining / budget * 100` from the task budget, then:

| Remaining budget | Mode | |------------------|------| | > 50% | lite (lowest compression, keep readability) | | 20% to 50% | full (default compression) | | < 20% | ultra (emergency, maximum compression) |

`depth = thorough` clamps the result to `lite` regardless of budget. Compression is never allowed to obscure thorough-depth artifacts.

How to query the budget

From a shell:

node scripts/forge-tools.cjs check-task-budget <task_id> --forge-dir .forge

From Node:

const { checkTaskBudget } = require('./scripts/forge-tools.cjs');
const { used, budget, remaining, percentage } = checkTaskBudget(taskId, forgeDir);

The returned `percentage` is percent used. Compute remaining as `100 - percentage`.

Fallback

If the budget check fails, throws, or there is no current task context (ad-hoc work, repair flows), default to `full`. Never block on budget lookup. See `references/budget-thresholds.md` for the full threshold table and rationale.

Quality F