How the AI Website Cloner Orchestrates Its Multi-Phase Reverse-Engineering Pipeline

The AI website cloner implements a foreman-patterned orchestration system that sequences five distinct phases—from reconnaissance to visual QA—using isolated Git worktrees and spec-first contracts to parallelize component generation while enforcing type safety.

The JCodesMore/ai-website-cloner-template repository transforms live websites into pixel-perfect Next.js projects through a meticulously staged multi-phase reverse-engineering pipeline. Unlike traditional two-phase scrapers, this system employs a foreman pattern that walks the job site, extracts exhaustive specifications, and dispatches specialized builder agents to reconstruct components in parallel isolation.

The Five-Phase Reverse-Engineering Pipeline

The pipeline defined in .github/skills/clone-website/SKILL.md decomposes website cloning into five discrete phases, each with strict verification gates.

Phase 1: Reconnaissance

The foreman agent captures the target site’s complete design language and behavior profile. Key actions include:

• Capturing full-page screenshots for desktop and mobile viewports
• Extracting global design tokens (fonts, colors, spacing scales)
• Downloading favicons, meta tags, and global assets
• Running a systematic interaction sweep that tests scroll, click, hover, and responsive breakpoints

All reconnaissance data is stored under docs/research/, including generated files like docs/research/BEHAVIORS.md and docs/research/PAGE_TOPOLOGY.md. This phase establishes the foundational design contract before any code is written.

Phase 2: Foundation Build

With design tokens extracted, the pipeline updates the Next.js scaffold:

• Global CSS variables are injected into src/app/globals.css (colors, spacing, keyframe animations, and scroll libraries like Lenis)
• Fonts are configured in src/app/layout.tsx via next/font/google or next/font/local
• TypeScript interfaces for content structures are generated
• Inline SVGs are extracted into reusable React components in src/components/icons.tsx
• All discovered assets are downloaded to public/ via scripts/download-assets.mjs

The phase completes only after npm run build executes successfully, ensuring the foundation is type-safe before component construction begins.

Phase 3: Component Specification & Dispatch

For each section identified in the page topology, the foreman executes a strict extract-spec-build sequence:

1. Extract – The foreman screenshots the section, runs a getComputedStyle() extraction script, and captures multi-state CSS, content, and assets
2. Write Spec – Creates a markdown specification in docs/research/components/ containing DOM hierarchy, exact CSS values, interaction models, responsive breakpoints, and verbatim text
3. Dispatch Builder – Spawns a specialized builder agent in its own Git worktree that receives the spec inline and generates the component code

Builder agents are limited to approximately 150 lines of specification per task; larger sections are split into sub-components. Each builder must run npx tsc --noEmit before completing to ensure type safety.

Phase 4: Page Assembly

The foreman merges all worktree branches back into main and wires components together:

• Generated components are imported and composed in src/app/page.tsx according to the topology map
• Page-level behaviors (scroll-snap, IntersectionObserver, smooth-scroll libraries) are injected
• npm run build must remain green after each merge

This incremental assembly prevents integration errors from accumulating across the codebase.

Phase 5: Visual QA Diff

The final validation phase ensures pixel-perfect accuracy:

• Side-by-side screenshots compare the original site against the clone (desktop and mobile)
• Discrepancies trigger a revisit of the component spec, re-extraction, and fixing
• Interactive testing (scroll, click, hover) verifies identical behavior
• Results are recorded in docs/research/QA_RESULTS.md

Only after passing this visual diff is the clone considered complete.

Orchestration Mechanics: How the Pipeline Executes

The repository implements four critical architectural patterns to manage parallel execution without corruption.

Foreman Pattern

The main agent acts as a foreman walking the job site, not a simple two-phase inspector. As stated in the skill definition: "This is not a two-phase process (inspect then build). You are a foreman walking the job site." Extraction and construction occur in parallel, but the foreman strictly sequences the foundation (fonts, colors, assets) before allowing component builders to start.

Worktree Isolation

Each builder agent operates in its own Git worktree, preventing cross-contamination between parallel component generators. The sync scripts scripts/sync-agent-rules.sh and scripts/sync-skills.mjs regenerate platform-specific copies of the skill, ensuring every agent references the same source of truth.

Spec-First Contract

The markdown specification serves as the single source of truth between extraction and building. Builder agents never read external documentation; they receive the full spec inline in their prompt. This guarantees exhaustive extraction and creates auditable artifacts in docs/research/components/.

Incremental Verification

After each worktree merge, the pipeline runs npm run build (and optionally npx tsc --noEmit) to catch type or compilation errors immediately. This incremental verification prevents the accumulation of build-breaking changes across the multi-phase reverse-engineering pipeline.

Implementation Examples

Invoke the clone-website skill through your AI agent interface:

# Start the AI agent (Claude Code recommended)

claude --chrome

# Invoke the clone-website skill on one or many targets

/clone-website https://example.com https://another-site.org

Regenerate platform-specific skill files after editing source definitions:

# Regenerate AGENTS.md copies for each platform

bash scripts/sync-agent-rules.sh

# Regenerate the /clone-website skill files

node scripts/sync-skills.mjs

A generated component spec follows this structure:

// Example from docs/research/components/hero-section.md

# HeroSection Specification

## Overview

- **Target file:** src/components/HeroSection.tsx
- **Screenshot:** docs/design-references/hero-section.png
- **Interaction model:** scroll-driven

## Computed Styles

### Container

- display: flex
- padding: 48px 24px
- background-color: #f5f7fa

## States & Behaviors

### Scroll-triggered shrink

- **Trigger:** scroll-position > 120px
- **State A:** height: 400px, box-shadow: none
- **State B:** height: 120px, box-shadow: 0 4px 12px rgba(0,0,0,0.1)
- **Transition:** all 0.3s ease

Summary

• The AI website cloner uses a five-phase pipeline (Reconnaissance → Foundation → Component Spec → Assembly → QA) defined in .github/skills/clone-website/SKILL.md
• ForemanPattern orchestration allows parallel component building while enforcing foundation-first sequencing
• Git worktree isolation prevents cross-contamination between builder agents working simultaneously
• Spec-first contracts (150-line limits) ensure exhaustive extraction and type-safe generation via npx tsc --noEmit
• Incremental verification through npm run build gates keeps the integration surface green throughout the process

Frequently Asked Questions

What is the role of the foreman agent in the AI website cloner?

The foreman agent acts as the central orchestrator that walks the target site, extracts design specifications, and dispatches specialized builder agents. Unlike simple scrapers, the foreman manages parallel execution while ensuring global assets (fonts, colors, CSS variables) are established in src/app/globals.css and src/app/layout.tsx before component construction begins.

How does the pipeline prevent conflicts between parallel builder agents?

The system uses Git worktree isolation, where each builder agent operates in its own independent worktree. The sync scripts scripts/sync-agent-rules.sh and scripts/sync-skills.mjs ensure all agents share the same rule definitions without direct filesystem overlap, allowing safe parallel merges back into the main branch.

What triggers a rebuild or fix during the Visual QA phase?

The Visual QA Diff (Phase 5) captures side-by-side screenshots of the original site and the clone. If pixel discrepancies are detected, the foreman automatically revisits the component specification in docs/research/components/, re-extracts the styles, and dispatches a fix to the builder agent. The process iterates until the visual diff passes and docs/research/QA_RESULTS.md confirms parity.

Why is the component specification limited to 150 lines?

The 150-line specification limit ensures builder agents can process the complete context within their context windows while maintaining precision. Larger sections are recursively split into sub-components, preventing specification overflow and ensuring each builder can run npx tsc --noEmit validation efficiently against its discrete scope.

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