# How Builder Agents Are Dispatched for Complex Sections in the AI Website Cloner Template

> Discover how builder agents dispatch for complex sections in the AI website cloner template. Learn about single vs. parallel agent allocation based on sub-component count.

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

---

**Builder agents are dispatched based on section complexity: simple sections with 1-2 sub-components receive a single agent, while complex sections with 3+ sub-components trigger multiple parallel agents—one per sub-component plus a wrapper agent—all operating in isolated Git worktrees.**

The JCodesMore/ai-website-cloner-template repository orchestrates website cloning through a sophisticated multi-agent system where builder agents dispatched for complex sections follow a strict complexity-based protocol. Before any agent runs, the system generates detailed component specifications that determine whether a section requires parallel decomposition or single-agent construction. This ensures that intricate page sections are broken down into manageable, concurrently built units while maintaining build integrity through Git worktree isolation.

## The Component Specification Phase

Before dispatching any builders, the extraction phase writes a **component specification file** for every section at `docs/research/components/<name>.spec.md`. This spec serves as the single source of truth for agent dispatch decisions.

According to the inspection guide in [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md) (lines 228-236), the system strictly requires this specification to exist before initiating the dispatch loop. The spec file contains the structural breakdown of sub-components, which the system parses to determine complexity thresholds and routing logic.

## Complexity-Based Dispatch Rules

The dispatch logic hinges on two complexity indicators defined in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) (lines 81-84): specification line count exceeding approximately 150 lines, or the presence of three or more distinct sub-components.

### Simple Sections (1-2 Sub-Components)

When a section contains fewer than three sub-components and falls under the line threshold, it is classified as simple. In this case, **one builder agent** receives the entire specification file and constructs the complete component in a single Git worktree. This minimizes overhead for straightforward layouts that do not benefit from parallelization.

### Complex Sections (3+ Sub-Components)

Complex sections trigger a decomposition strategy. The system dispatches:
- **One dedicated builder agent per sub-component**, each operating in its own parallel worktree
- **One additional "wrapper" builder agent** that imports all sub-components and assembles the final section structure

This approach prevents context overflow and allows specialized agents to focus on discrete functional units concurrently.

## Parallel Execution in Git Worktrees

All builder agents execute within **isolated Git worktrees**—temporary branches created specifically for each agent session. The workflow follows this cycle:

1. Create a worktree branch for each required builder (e.g., `builder-header`, `builder-card`, `builder-wrapper`)
2. Run agents simultaneously in their respective worktrees
3. Merge completed worktrees back into `main` using `git merge --no-ff builder-*`
4. Verify build integrity with `npm run build`

As documented in the README (lines 93-99), this parallel build strategy ensures that complex sections are constructed concurrently without merge conflicts, while the final merge step validates that integrated components compile successfully.

## Implementation Example: Dispatch Logic

The following examples illustrate how the dispatch system programmatically determines agent allocation and manages worktree lifecycle.

### TypeScript Dispatch Implementation

This illustrative implementation from [`src/lib/dispatch.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/dispatch.ts) demonstrates the complexity check and worktree creation:

```typescript
import { execSync } from "child_process";

/**
 * Dispatch builder agents for a section.
 * @param specPath Path to the component spec file.
 * @param subComponents List of sub‑component names extracted from the spec.
 */
export function dispatchBuilders(specPath: string, subComponents: string[]) {
  // Complexity determination: 3+ sub-components triggers complex mode
  const isComplex = subComponents.length > 2;

  // Create worktree for each builder agent
  const worktrees = isComplex
    ? subComponents.map((name) =>
        `git worktree add ../worktree-${name} -b builder-${name}`
      )
    : [`git worktree add ../worktree-${Date.now()} -b builder-section`];

  worktrees.forEach(cmd => execSync(cmd, { stdio: "inherit" }));

  // Dispatch agents based on complexity
  if (isComplex) {
    subComponents.forEach(name => {
      execSync(
        `opencode run builder --spec ${specPath} --component ${name}`,
        { stdio: "inherit" }
      );
    });
    // Wrapper builder for assembly
    execSync(
      `opencode run builder --spec ${specPath} --wrapper true`,
      { stdio: "inherit" }
    );
  } else {
    execSync(`opencode run builder --spec ${specPath}`, {
      stdio: "inherit",
    });
  }

  // Merge and verify
  execSync(`git checkout main && git merge --no-ff builder-*`, {
    stdio: "inherit",
  });
  execSync(`npm run build`, { stdio: "inherit" });
}

```

### Shell-Based Workflow

Workflow scripts like `scripts/sync-skills.mjs` utilize shell commands to implement the same logic:

```bash

# Check complexity thresholds

LINE_COUNT=$(wc -l < docs/research/components/hero.spec.md)
SUB_COUNT=$(grep -c '^## Sub‑Component' docs/research/components/hero.spec.md)

if [ "$LINE_COUNT" -gt 150 ] || [ "$SUB_COUNT" -gt 2 ]; then
  # Complex: parallel sub-component builders

  for sub in Header Card Footer; do
    git worktree add ../wt-$sub -b builder-$sub
    opencode run builder --spec docs/research/components/hero.spec.md --component $sub
  done
  # Wrapper assembly

  git worktree add ../wt-wrapper -b builder-wrapper
  opencode run builder --spec docs/research/components/hero.spec.md --wrapper
else
  # Simple: single agent

  git worktree add ../wt-simple -b builder-simple
  opencode run builder --spec docs/research/components/hero.spec.md
fi

# Integration and validation

git checkout main && git merge --no-ff builder-* && npm run build

```

## Key Source Files

- **[`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md)** – Defines the complexity thresholds and dispatch rules (lines 81-84)
- **[`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** – Documents the parallel build strategy using Git worktrees (lines 93-99)
- **[`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md)** – Details the extract-spec-dispatch workflow loop (lines 228-236)
- **`scripts/sync-skills.mjs`** – Synchronizes skill definitions to ensure dispatch logic consistency across the repository

## Summary

- Builder agents are dispatched only after component specification files are written to `docs/research/components/`.
- Complexity is determined by spec length (~150+ lines) or sub-component count (3+ distinct units).
- Simple sections use a single agent; complex sections use parallel agents—one per sub-component plus a wrapper.
- All agents operate in isolated Git worktrees to prevent conflicts and enable concurrent execution.
- Post-build merge validation ensures integrated components pass `npm run build` before completion.

## Frequently Asked Questions

### What defines a "complex" section in the AI Website Cloner?

A section is classified as complex if its specification file exceeds approximately 150 lines or contains three or more distinct sub-components. This threshold triggers the parallel dispatch strategy defined in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) to prevent context overload and enable concurrent construction.

### How does the system handle simple sections differently from complex ones?

Simple sections with 1-2 sub-components receive a single builder agent that constructs the entire component in one worktree. Complex sections are decomposed into individual sub-components, each assigned to a dedicated agent, plus an additional wrapper agent that assembles the final structure.

### What happens after builder agents complete their work in the worktrees?

Upon completion, each worktree branch is merged back into the `main` branch using `git merge --no-ff builder-*`. Immediately after merging, the system runs `npm run build` to verify that the integrated components compile successfully and the section functions as intended.

### Where is the dispatch logic configured in the repository?

The primary dispatch rules reside in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) (lines 81-84), with supplementary workflow documentation in [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md) (lines 228-236) and high-level architecture notes in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) (lines 93-99). The `scripts/sync-skills.mjs` file ensures these definitions remain synchronized across the codebase.