Understanding the Limitations of the cavecrew-builder Agent in JuliusBrussee/caveman

The cavecrew-builder agent is intentionally constrained to surgical edits on maximum two files, prohibiting new file creation (unless explicitly requested), destructive operations, new abstractions, and narrative output to maintain a token budget of approximately 700 tokens per edit.

The cavecrew-builder is a specialized sub-agent in the JuliusBrussee/caveman repository designed for compact, verifiable code modifications. Understanding the limitations of the cavecrew-builder agent ensures developers delegate appropriate tasks and avoid workflow interruptions caused by its strict refusal protocols defined in agents/cavecrew-builder.md.

Operational Constraints Defined in agents/cavecrew-builder.md

The agent's behavior is governed by strict rules encoded in its front-matter configuration. These constraints prioritize safety and predictability over flexibility.

File-Scope Limitations

The agent operates under a strict file-count cap. According to agents/cavecrew-builder.md, the ideal workload is one file, with two files being the absolute maximum. When instructed to modify three or more files, the agent refuses immediately with the error code too-big.

This limitation ensures that each edit remains within the approximate 700-token budget per operation, preventing context window overflow and maintaining computational efficiency.

Restricted File Operations

New-file creation is disabled by default. The agent can only create files if the user explicitly asks for them; otherwise, it rejects new-file requests. Additionally, the agent cannot delete files, push changes to repositories, or execute arbitrary shell commands, as the Bash tool is unavailable in its environment.

Prohibited Abstractions and Refactors

The agent must not introduce new functions, classes, or modules. Its scope is limited to surgical tweaks such as typo corrections, identifier renames, comment removal, and formatting adjustments. The documentation explicitly forbids "drive-by refactors" and comment additions, ensuring the agent performs only minimal, targeted changes.

Workflow and Output Restrictions

The cavecrew-builder follows a rigid procedural pattern that differs from general-purpose agents.

Mandatory Read-Edit-Verify Cycle

As implemented in agents/cavecrew-builder.md, the agent must execute a three-step workflow:

1. Read the target file(s)
2. Edit using the smallest viable diff
3. Re-read to verify changes

Skipping any step triggers an automatic refusal. This verification loop guarantees that modifications compile and match the requested transformation before the agent returns control.

Receipt-Only Output Format

Unlike conversational agents, the cavecrew-builder never returns prose explanations. It outputs only a terse receipt containing the file path, line range, and change description. The format follows the pattern defined in lines 30-34 of agents/cavecrew-builder.md:

src/util.ts:12‑14 — rename oldName → newName.
verified: re-read OK

Technical Boundaries and Model Configuration

Beyond workflow constraints, the agent faces hard technical limits regarding system access and runtime configuration.

No Destructive Shell Operations

The absence of Bash tool access prevents the agent from shelling out, pushing commits, or deleting files. Attempts to delete files result in a needs-confirm refusal rather than execution, as documented in lines 41-42 of agents/cavecrew-builder.md.

Model Override Behavior

By default, the agent inherits the session's default model without pinning a specific version in its front-matter. To force a different model, developers must set the CAVECREW_BUILDER_MODEL environment variable, which patches the configuration via src/hooks/cavecrew-model-overrides.js. The skills/cavecrew/README.md file provides the complete decision guide for these overrides.

Practical Examples of Agent Behavior

These scenarios demonstrate how the constraints manifest in actual usage.

Example 1: Successful Single-File Edit

When renaming a function within the file limit, the agent completes the workflow:

{
  "agent": "cavecrew-builder",
  "goal": "Rename `oldName` → `newName` in `src/util.ts`",
  "steps": [
    "Read src/util.ts",
    "Edit src/util.ts (replace `oldName` with `newName`)",
    "Read src/util.ts to verify"
  ]
}

Receipt Output:

src/util.ts:12‑14 — rename oldName → newName.
verified: re-read OK

Example 2: Refusal Due to Excessive Scope

Requesting edits across three files triggers the too-big. refusal:

{
  "agent": "cavecrew-builder",
  "goal": "Apply the same refactor across three files",
  "files": ["a.ts", "b.ts", "c.ts"]
}

Result:

too-big. split: 3 one-line tasks.

Example 3: Refusal of Destructive Operation

Attempting deletion surfaces the needs-confirm error:

{
  "agent": "cavecrew-builder",
  "goal": "Delete `src/old_module.ts`"
}

Result:

needs-confirm. op: delete src/old_module.ts

Summary

• The cavecrew-builder agent accepts maximum two files per task, refusing larger batches with too-big.
• New files are created only when explicitly requested; deletions and shell commands are prohibited.
• The agent performs surgical tweaks only, banning new abstractions, classes, or drive-by refactors.
• A mandatory Read-Edit-Verify workflow ensures changes are correct before returning a terse receipt.
• Output is limited to receipt format only, with no explanatory narrative.
• Model selection defaults to the session setting unless overridden via the CAVECREW_BUILDER_MODEL environment variable.

Frequently Asked Questions

How many files can the cavecrew-builder agent edit at once?

The agent can edit maximum two files simultaneously. One file is ideal; attempting to process three or more files results in an immediate too-big. refusal with instructions to split the task into separate one-line requests.

Can the cavecrew-builder agent create new files?

Yes, but only if the user explicitly asks for file creation. By default, the agent operates in edit-existing-only mode and rejects requests to generate new files unless the user specifically requests them in the goal description.

Why does the cavecrew-builder agent refuse to delete files?

The agent lacks Bash tool access and destructive operation permissions as defined in agents/cavecrew-builder.md. Deletion attempts return a needs-confirm refusal because the agent cannot execute shell commands or permanent removals, ensuring the main Claude Code session retains control over dangerous operations.

How can I change the model used by the cavecrew-builder agent?

Set the CAVECREW_BUILDER_MODEL environment variable in your environment. Unlike other agents that pin specific models in their front-matter, the cavecrew-builder inherits the session default unless this variable is present, which patches the configuration through src/hooks/cavecrew-model-overrides.js as documented in skills/cavecrew/README.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}