# How Merge Conflicts Are Resolved During Parallel Component Building in AI-Website-Cloner

> Learn how the AI-Website-Cloner template resolves merge conflicts during parallel component building. Discover the orchestrator agent, sequential merges, and intelligent conflict editing.

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

---

**The AI-Website-Cloner template resolves merge conflicts during parallel component building by delegating to an orchestrator agent with complete specification context, applying sequential merges validated by TypeScript compilation, and intelligently editing conflicts using design tokens and screenshots from the original site.**

The JCodesMore/ai-website-cloner-template accelerates website generation by dispatching multiple builder agents to work simultaneously in isolated **git worktrees**, each handling a distinct section like `HeroSection` or `FeaturesGrid`. Because these parallel builders modify the same codebase concurrently, overlapping changes to shared utilities or component boundaries inevitably trigger merge conflicts. The template handles these conflicts automatically through an orchestrator that possesses full visibility into every component specification and validates structural integrity after each merge.

## The Parallel Build Architecture

Each website section is built in its own **git worktree** branch to prevent file-system collisions. When the foreman agent extracts a section, it writes a detailed specification to `docs/research/components/` (containing exact CSS, layout parameters, and asset references) and immediately dispatches a builder agent. That agent works in an isolated worktree, commits its component (e.g., [`src/components/HeroSection.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/HeroSection.tsx)), and pushes the branch back to the repository.

When a builder finishes, the orchestrator checks out `main` and executes `git merge --no-ff builder/section-name`. Because many builders run concurrently, this process often produces merge conflicts requiring intelligent resolution.

## Conflict Resolution Strategy

### Full Context Awareness

The orchestrator resolves conflicts by leveraging **complete specification context** rather than naive textual merging. As documented in [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) (lines 94-97), the orchestrator explicitly receives the instruction: "You have full context on what each agent built, so resolve any conflicts intelligently." This context includes:

- Component specification files containing exact design tokens and layout requirements
- Screenshots and asset references from the original cloned site
- The complete code output from each builder agent

### Sequential Merging with Build Validation

Despite builders running in parallel, the orchestrator processes merges **sequentially** to maintain repository integrity. After each merge, the orchestrator immediately runs:

```bash
npm run build
npx tsc --noEmit

```

If the merge introduces TypeScript errors or build failures, the orchestrator fixes them before proceeding to the next worktree branch. This validation step prevents cascading errors that would otherwise destabilize the parallel build pipeline.

### Intelligent Conflict Editing

When overlapping changes occur (such as multiple components importing updated utilities), the orchestrator performs **manual conflict resolution** informed by design specifications. Rather than accepting default git merge behavior, the orchestrator consults the component spec files (e.g., [`docs/research/components/HeroSection.spec.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/components/HeroSection.spec.json)) to determine the correct implementation. The policy requiring intelligent resolution is codified in [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) (lines 60-62), which instructs the orchestrator to "resolve any merge conflicts smartly" by preferring the implementation that most accurately matches the intended design.

### Automation and Synchronization

The workflow scripts [`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh) and `scripts/sync-skills.mjs` prevent unnecessary conflicts by keeping utility functions and agent instructions synchronized across all worktrees. These scripts ensure that shared resources like the **`cn()`** utility in [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) remain consistent, reducing the likelihood of divergent implementations that could cause merge failures.

## Step-by-Step Implementation

The following workflow demonstrates how the template handles concurrent component development:

```bash

# 1️⃣ Create an isolated worktree for a component builder

git worktree add -b builder/hero-section ./worktrees/hero-section HEAD

# Builder agent writes its component and commits

cd worktrees/hero-section

# ... generate src/components/HeroSection.tsx ...

git add src/components/HeroSection.tsx
git commit -m "Add HeroSection component"

# 2️⃣ Orchestrator merges the builder branch back into main

git checkout main
git merge --no-ff builder/hero-section   # may produce conflicts

# 3️⃣ If conflicts arise, open the conflicted file and consult the spec:

#    docs/research/components/HeroSection.spec.json

#    (contains exact CSS, layout, and assets)

# Resolve manually based on specifications, then:

git add src/components/HeroSection.tsx
git commit -m "Resolve merge conflict in HeroSection"

# 4️⃣ Verify the project still builds

npm run build   # or npx tsc --noEmit

```

## Critical Files in the Merge Workflow

Several files govern the conflict resolution process:

- **[`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md)** – Defines the merge step and post-merge verification requirements, explicitly granting the orchestrator full context for intelligent conflict resolution.
- **[`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md)** – Establishes the policy that teammates work in isolated worktrees and that the orchestrator must "resolve any merge conflicts smartly" using available specifications.
- **[`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh)** – Synchronizes agent instructions across worktrees to ensure consistent coding patterns and reduce utility-related conflicts.
- **[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)** – Provides the shared **`cn()`** utility function imported by all component builders, preventing divergent implementations.

## Summary

- **Git worktrees** isolate parallel builder agents, but require explicit merge conflict handling when integrating back to `main`.
- The **orchestrator** resolves conflicts using **full context awareness** of component specifications, screenshots, and design tokens rather than blind textual merging.
- **Sequential merging** with immediate `npm run build` and `npx tsc --noEmit` validation ensures type safety and prevents error propagation.
- **Intelligent editing** consults specification files (e.g., [`HeroSection.spec.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/HeroSection.spec.json)) to determine the correct resolution when code overlaps.
- **Synchronization scripts** keep shared utilities consistent across worktrees, minimizing conflict frequency.

## Frequently Asked Questions

### What causes merge conflicts during parallel component building?

Merge conflicts arise when multiple builder agents modify the same files simultaneously, such as when two components import a shared utility that gets updated in both worktrees, or when component boundaries overlap in the source tree. The concurrent nature of the build process makes these overlaps inevitable without strict file isolation.

### How does the orchestrator know which code version is correct?

The orchestrator consults the **component specification files** stored in `docs/research/components/` and the original site screenshots to determine the correct implementation. Because the orchestrator has "full context on what each agent built" according to [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md), it can identify which branch contains the implementation that matches the design requirements and resolve conflicts in favor of accuracy.

### Why use sequential merging instead of simultaneous merges?

Sequential merging allows the orchestrator to **validate the build after each integration** using `npm run build` and `npx tsc --noEmit`. If simultaneous merges were attempted, type errors or structural conflicts could compound across multiple branches, making debugging significantly more complex. The sequential approach ensures that `main` remains in a working state after each component is integrated.

### What happens if the build fails after a merge?

If `npm run build` or TypeScript compilation fails following a merge, the orchestrator immediately fixes the errors before proceeding to the next worktree branch. This might involve updating imports, adjusting type definitions, or reconciling component interfaces using the specification files as the source of truth. The build must pass before the orchestrator continues the merge queue.