# Complexity Budget Rule for Dispatching Builder Agents in the AI Website Cloner Template

> Discover the complexity budget rule in the AI Website Cloner Template. Learn how it splits large component specs across builder agents to avoid errors and streamline development.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: internals
- Published: 2026-06-26

---

**The AI Website Cloner Template enforces a strict ~150-line complexity budget that automatically splits oversized component specifications across multiple builder agents to prevent incomplete implementations and merge conflicts.**

The JCodesMore/ai-website-cloner-template repository implements a rigorous complexity budget rule for dispatching builder agents to ensure high-fidelity website cloning. This mechanical check prevents single agents from choking on massive specifications by breaking complex components into manageable sub-tasks. Understanding this threshold is critical for customizing the workflow or debugging dispatch failures.

## What Is the Complexity Budget Rule?

The rule defines a hard limit on specification file size. When a builder prompt—the `docs/research/components/<Component>.spec.md` file dispatched to a builder agent—exceeds **approximately 150 lines of content**, the system flags it as too complex for a single agent.

According to the workflow documentation in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md), the rule states: *"If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with 'but it's all related.'"*

This constraint appears identically across [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md) and [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md), ensuring consistent enforcement across Windsurf, Opencode, and GitHub agent execution contexts.

## Why the Budget Matters

Builder agents operate optimally within focused, constrained contexts. Exceeding the 150-line threshold correlates with:

- Incomplete or inaccurate code generation
- Merge conflicts during integration
- Broken builds requiring manual intervention

The budget forces a **spec-first workflow** where extraction scripts generate specifications, complexity assessment occurs automatically, and dispatch decisions route work appropriately.

## How the Rule Is Implemented

### Detecting Over-Budget Specifications

The orchestrator scans generated spec files before dispatch. A simple line-count check determines if splitting is required:

```javascript
import fs from 'fs';
import path from 'path';

function needsSplitting(specPath) {
  const lines = fs.readFileSync(specPath, 'utf-8').split('\n');
  return lines.length > 150;   // ≈150-line budget
}

// Example usage
const spec = 'docs/research/components/HeroSection.spec.md';
if (needsSplitting(spec)) {
  console.log('Spec exceeds budget – split into smaller pieces.');
}

```

### Splitting and Redispatching

When detection returns true, the system fractures the spec into logical sub-components. The splitting logic uses markdown headers or semantic boundaries to create separate files:

```javascript
// Assume `spec` holds the full Markdown spec string
const sections = spec.split('## Sub-component');   // logical delimiter

sections.forEach((sub, i) => {
  const subPath = `docs/research/components/HeroSection.part${i + 1}.spec.md`;
  fs.writeFileSync(subPath, sub.trim());
  // Dispatch a builder for each sub-spec
  dispatchBuilderAgent(subPath);
});

```

### Parallel Execution Strategy

Each sub-spec receives its own builder agent running in an isolated git worktree. A dispatch script coordinates parallel execution:

```bash

# Simple wrapper script (scripts/dispatch-builders.sh)

for spec in docs/research/components/HeroSection.part*.spec.md; do
  # Each builder runs in its own worktree

  git worktree add ../builder-$spec $CURRENT_BRANCH
  cd ../builder-$spec
  opencode run builder --spec "$spec"
  cd -
done

```

After completion, outputs merge back into `main` and the build verifies via `npm run build`.

## Key Files Defining the Rule

Several locations enforce this standard:

- **[`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md)** – Documents the core rule and extraction workflow
- **[`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md)** – Duplicates the rule for Opencode compatibility
- **[`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md)** – GitHub agent skill definition containing the budget rule verbatim
- **`scripts/sync-skills.mjs`** – Synchronizes the rule across all skill definitions to prevent drift

## Summary

- The **complexity budget rule** imposes a strict ~150-line limit on builder specifications in the AI Website Cloner Template
- Exceeding this threshold triggers automatic splitting of components into sub-specifications
- The rule is mechanically enforced across [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md), [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md), and [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md)
- Implementation involves line-count detection, logical spec fragmentation, and parallel dispatch to isolated worktrees
- Adhering to this budget maximizes agent accuracy and minimizes integration conflicts

## Frequently Asked Questions

### What happens if a spec file is exactly 150 lines?

Specifications at or below 150 lines are considered within budget and dispatched to a single builder agent without splitting. The threshold acts as a maximum boundary, not a target.

### Can I override the complexity budget rule for related components?

The documentation explicitly prohibits overriding this rule. The [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) file states: *"This is a mechanical check — don't override it with 'but it's all related.'"* Ignoring the budget risks incomplete implementations and broken builds.

### How does the system handle splitting specs with interdependent sub-components?

The extraction logic uses logical delimiters like markdown headers (`## Sub-component`) to ensure each resulting piece represents a coherent, implementable unit. Each sub-spec receives sufficient context to build independently while maintaining interface compatibility during the final merge phase.

### Where is the 150-line threshold defined in the codebase?

The threshold appears as a hardcoded value in the workflow documentation rather than a configurable constant. You will find the specific number in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) at line 46, with identical copies maintained in [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md) and [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) via the `scripts/sync-skills.mjs` synchronization script.