How cavecrew-builder Signals “too-big” or “ambiguous” Tasks in Caveman

The cavecrew-builder agent outputs terminal refusal lines—too-big. split: <n> one-line tasks. for oversized requests and ambiguous. ask: <question>. for unclear instructions—allowing parent agents to split work or request clarification instead of guessing.

The cavecrew-builder is a specialized sub-agent in the JuliusBrussee/caveman repository designed to execute minimal, surgical edits across one or two files. When it encounters a task that exceeds its narrow scope or lacks sufficient detail, it does not attempt partial execution or guesswork; instead, it emits structured refusal tokens that the parent orchestrator can parse and act upon.

Terminal Refusal Tokens Defined in cavecrew-builder.md

The signalling mechanism is contract-based. The parent agent expects specific string prefixes that indicate terminal failure states, allowing the orchestration layer to decide whether to split the task, prompt the user, or abort.

The “too-big” Signal

When a request touches three or more files, the builder immediately halts and returns:

too-big. split: <n one-line tasks>.

This token indicates the task violates the builder’s 1-2 file limit and suggests dividing the work into n separate single-line tasks. The parent agent can parse the integer and automatically generate new sub-tasks for each file.

The “ambiguous” Signal

When instructions are unclear, incomplete, or lacking context, the builder responds with:

ambiguous. ask: <one question>.

This signals that the builder cannot determine the correct operation and requires a specific clarifying question to proceed. The parent agent typically routes this question to the user or to a clarification sub-agent.

Implementation in the Source Code

According to the source code in agents/cavecrew-builder.md (lines 38-44), these tokens are defined under the “Refusals (terminal lines)” section. The complete set of terminal refusal tokens includes:

• too-big.
• ambiguous.
• needs-confirm.
• regressed.

When the builder outputs any of these lines, it terminates immediately without printing a diff or attempting file modifications. This fail-fast behavior prevents partial edits and preserves token efficiency.

Code Examples from the Repository

The refusal logic manifests in the agent’s execution flow as simple conditional checks:

// Example: Builder detects a 4-file request
if (files.length >= 3) {
  // Returns a refusal line the parent can parse
  console.log('too-big. split: 4 one-line tasks.');
}

// Example: Builder cannot infer the operation
if (!isClear(request)) {
  console.log('ambiguous. ask: Which function should I refactor?');
}

In practice, the builder never prints a normal diff when it hits these cases; it immediately outputs the refusal line, which the orchestrating code treats as a terminal response.

How Parent Agents Handle These Signals

The cavecrew-investigator and the main Caveman orchestrator monitor the builder’s stdout for these exact string prefixes. Upon detecting too-big., the parent may invoke a task-splitting strategy. Upon detecting ambiguous., it can surface the embedded question to the user via the UI or CLI.

Key Files in the Caveman Ecosystem

• agents/cavecrew-builder.md: Defines the builder’s scope, workflow, output receipt format, and the exact refusal tokens.
• skills/cavecrew/SKILL.md: High-level description of the cavecrew family, reiterating the refusal tokens for consistency across sub-agents.
• agents/cavecrew-investigator.md: Consumes the builder’s refusal lines and decides whether to split the task or ask the user for clarification.

Summary

• cavecrew-builder outputs too-big. split: <n> one-line tasks. when requests touch ≥3 files, violating its 1-2 file constraint.
• It outputs ambiguous. ask: <question>. when instructions are unclear or lack necessary context.
• These tokens are defined in agents/cavecrew-builder.md under “Refusals (terminal lines)” and act as terminal responses.
• Parent agents detect these exact strings to determine next steps without parsing complex error objects or stack traces.

Frequently Asked Questions

What is the file limit for cavecrew-builder before it triggers “too-big”?

The builder is designed for 1-2 file edits. When a task touches three or more files, it emits the too-big. refusal token and suggests splitting the work into separate one-line tasks.

Where are the refusal tokens defined in the source code?

The exact refusal strings are documented in agents/cavecrew-builder.md under the “Refusals (terminal lines)” section, specifically lines 38-44. The file also defines the builder’s scope constraints and workflow.

Can cavecrew-builder attempt part of a large task anyway?

No. When the builder encounters a scope violation or ambiguity, it immediately outputs the refusal line and terminates without attempting partial execution, generating a diff, or modifying any files.

How does the parent agent know when to ask the user for clarification?

The parent agent watches for the ambiguous. ask: prefix in the builder’s output. When detected, it extracts the question following the prefix and can present it to the user to resolve the ambiguity before retrying the task.

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