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

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 (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 (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 demonstrates the complexity check and worktree creation:

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:

# 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 – Defines the complexity thresholds and dispatch rules (lines 81-84)
• README.md – Documents the parallel build strategy using Git worktrees (lines 93-99)
• 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 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 (lines 81-84), with supplementary workflow documentation in docs/research/INSPECTION_GUIDE.md (lines 228-236) and high-level architecture notes in README.md (lines 93-99). The scripts/sync-skills.mjs file ensures these definitions remain synchronized across the codebase.

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