How Assembly & QA Work in the AI Website Cloner Pipeline

The Assembly & QA process in the AI Website Cloner pipeline merges parallel builder worktrees into a unified Next.js app in src/app/page.tsx, then validates pixel-perfect fidelity through side-by-side visual diffs at desktop and mobile breakpoints.

The JCodesMore/ai-website-cloner-template repository implements a five-phase cloning pipeline where the final two stages—Assembly and Visual QA—transform extracted component specifications into a production-ready Next.js application. These phases ensure that independently built page sections integrate seamlessly and match the original website pixel-for-pixel before delivery.

Phase 4 – Page Assembly

After individual builder agents complete their assigned sections in isolated worktrees, the foreman initiates Phase 4 to consolidate these contributions into a cohesive application.

Merging Parallel Worktrees

Each builder works on a dedicated branch (e.g., builder-hero-section). Upon completion, the foreman merges these branches into the main branch incrementally. According to the workflow documentation in .windsurf/workflows/clone-website.md at line 402, every merge is immediately followed by a build check to catch integration errors early.

# Merge a builder's worktree

git checkout main
git merge builder-hero-section
npm run build  # Exits non-zero if TypeScript compilation fails

Wiring the Page in src/app/page.tsx

The foreman composes the final page in src/app/page.tsx, which serves as the single source of truth for page-level architecture. This file:

• Imports all section components from @/components/
• Recreates layout structures including scroll containers, column grids, and sticky layers
• Passes real content to component props
• Implements global behaviors: scroll-snap, smooth-scroll libraries, intersection observers, and dark-mode toggles

import HeroSection from '@/components/HeroSection';
import Footer from '@/components/Footer';

export default function Page() {
  return (
    <>
      <HeroSection />
      {/* additional sections */}
      <Footer />
    </>
  );
}

Build Verification

The pipeline enforces strict TypeScript checking through npm run build (defined in package.json). This command runs after every merge to ensure the project compiles without type or syntax errors before proceeding to QA.

Phase 5 – Visual QA Diff

Once assembly completes, Phase 5 initiates a rigorous visual diff workflow documented at line 412 of .windsurf/workflows/clone-website.md. This manual verification ensures the clone matches the original site at both desktop and mobile breakpoints.

Screenshot Comparison Workflow

The QA process requires side-by-side comparison at specific viewports:

1. Capture screenshots of the original site at 1440 px (desktop) and 390 px (mobile)
2. Start the clone locally with npm run dev and capture matching screenshots
3. Walk through the page top-to-bottom, comparing layouts, typography, spacing, and colors
4. Test all interactive behaviors including clicks, hovers, and scroll-driven animations

Discrepancy Resolution Loop

When visual mismatches are detected, the agent consults the component specification files in docs/research/components/*.spec.md:

• If the spec is wrong: Re-extract the correct value from the original site
• If the spec is correct: Fix the component implementation in the source code

After each fix, the agent runs npm run build again to verify compilation and repeats the visual comparison until no differences remain. The clone is considered complete only after this QA pass succeeds.

Key Implementation Details

Incremental Merge Strategy

The Assembly phase relies on incremental merges rather than bulk integration. Each builder's worktree merges separately, allowing the foreman to isolate and resolve conflicts immediately. This approach prevents "integration hell" when multiple agents modify shared dependencies.

TypeScript Build Enforcement

The pipeline treats npm run build as a gate. As noted in the README at line 94, the build must pass after every merge and before final delivery. This ensures production readiness and catches type errors that unit tests might miss.

Summary

• Assembly consolidates parallel builder worktrees into src/app/page.tsx, handling imports, layouts, and global behaviors
• Visual QA performs manual side-by-side comparisons at 1440 px and 390 px viewports to verify pixel-perfect fidelity
• The foreman resolves discrepancies by checking docs/research/components/*.spec.md and either re-extracting specs or fixing implementations
• Strict build verification via npm run build runs after every merge and before final acceptance
• The process completes only when the visual diff shows no mismatches and the TypeScript project compiles cleanly

Frequently Asked Questions

What triggers the Assembly phase in the AI Website Cloner pipeline?

The Assembly phase begins after all builder agents finish their assigned sections in separate worktrees. The foreman then merges these branches into the main branch and starts wiring the components together in src/app/page.tsx.

How does the pipeline ensure the cloned website matches the original visually?

The Visual QA phase requires manual side-by-side screenshot comparisons at desktop (1440 px) and mobile (390 px) breakpoints. The agent walks through both versions simultaneously, noting any discrepancies in layout, styling, or interactions, then fixes them by updating either the component code or the specification files.

Why does the pipeline run npm run build multiple times?

The build command serves as a compilation gate. It runs immediately after each worktree merge to catch integration errors early, and again after any fixes during Visual QA to ensure the TypeScript project remains valid before final delivery.

Where are the component specifications stored that drive the Assembly & QA process?

Component specifications reside in docs/research/components/*.spec.md. These files contain the extracted design values, layout parameters, and content that builders use during Assembly and that QA references when resolving visual mismatches.

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