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

> Discover the limitations of the cavecrew-builder agent. Learn why it avoids new files, destructive changes, and complex edits to stay within its token budget.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-08-22

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js). The [`skills/cavecrew/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js) as documented in [`skills/cavecrew/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/README.md).