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

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, 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 and .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:

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:

// 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:

# 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 – Documents the core rule and extraction workflow
• .opencode/commands/clone-website.md – Duplicates the rule for Opencode compatibility
• .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, .opencode/commands/clone-website.md, and .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 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 at line 46, with identical copies maintained in .opencode/commands/clone-website.md and .github/skills/clone-website/SKILL.md via the scripts/sync-skills.mjs synchronization script.

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