# How to Resolve Merge Conflicts When Integrating Builder Agent Worktrees Back to Main

> Learn to resolve merge conflicts when integrating builder agent worktrees back to main. Merge, fix conflicts, validate, and fast-forward to a clean main branch.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-06-23

---

**To resolve merge conflicts, first merge `main` into the worktree branch, resolve conflict markers in shared files like [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx), run TypeScript validation, then fast-forward the clean result to `main` before removing the worktree.**

The **AI Website Cloner Template** (`JCodesMore/ai-website-cloner-template`) orchestrates parallel builder agents using **git worktrees**, where each agent operates in an isolated directory on its own branch (e.g., `builder/header`). As documented in [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md), this architecture requires that every teammate use a separate worktree branch and resolve all conflicts before merging back to `main`. When multiple agents modify shared layout components or utility files, you must follow a specific integration sequence to safely resolve merge conflicts without breaking the TypeScript build.

## Understanding the Builder Agent Worktree Architecture

The template's parallel build pipeline—described in the **"Parallel Build"** section of [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)—creates isolated worktrees for each component or section. Each worktree exists at a path like `worktrees/header-component` and tracks a branch named `builder/<component>`.

Because several agents may simultaneously touch shared files—particularly [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx), [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) (containing the `cn()` utility), and global CSS or Tailwind configuration—merge conflicts are inevitable when integrating completed work back to `main`. The repository mandates that you resolve these conflicts within the worktree environment before finalizing the merge.

## Step-by-Step Conflict Resolution Workflow

Follow this sequence to safely integrate a builder agent's worktree while resolving any merge conflicts.

### Inspect and Update Your Branches

First, identify all active worktrees and ensure your `main` branch is current:

```bash

# List all worktree directories and their associated branches

git worktree list

```

Update the main branch to prevent unnecessary rebase operations later:

```bash
git checkout main
git pull origin main

```

### Merge Main into the Worktree Branch

Navigate to the specific worktree directory and merge the updated `main` branch into the builder's branch. This step—which occurs before merging back to `main`—isolates conflict resolution within the worktree:

```bash
cd worktrees/header-component
git checkout builder/header
git merge main

```

If conflicts exist, Git pauses the merge and marks affected files with conflict markers.

### Resolve Conflicts in Critical Files

Open each conflicted file and locate the `<<<<<<<`, `=======`, and `>>>>>>>` markers. Prioritize preserving the builder's generated component markup while integrating any newer changes from `main`, such as global meta tags or utility updates.

Common conflict sources in this repository include:

- **[`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx)** – Shared layout updates and global providers
- **[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)** – The `cn()` utility function for class-name merging
- **`src/`** global CSS or Tailwind configuration files

After editing, stage the resolutions:

```bash
git add src/app/layout.tsx src/lib/utils.ts
git commit

```

Git uses the original merge message by default, though you may edit it to document specific resolutions.

### Validate with TypeScript and Build Checks

The repository enforces strict QA checks before any branch can be considered integrated. As specified in the [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) pipeline documentation, you must verify that conflict resolutions did not introduce type errors:

```bash
npm run typecheck    # or npx tsc --noEmit

npm run build

```

Fix any TypeScript errors that emerged from merging conflicting code paths before proceeding to the final integration.

### Finalize the Integration

With conflicts resolved and checks passing, merge the worktree branch into `main`. Because you already merged `main` into the worktree branch, this should result in a clean fast-forward:

```bash
git checkout main
git merge builder/header

```

Push the updated `main` branch and clean up the worktree infrastructure:

```bash
git push origin main
git worktree remove worktrees/header-component --force
git branch -D builder/header

```

## Post-Integration Synchronization

While not required for conflict resolution, the repository provides helper scripts to synchronize agent definitions after structural changes. Run these to regenerate platform-specific files:

```bash
bash scripts/sync-agent-rules.sh   # Regenerates platform rule files from AGENTS.md

node scripts/sync-skills.mjs       # Rebuilds /clone-website skill definitions

```

These scripts are referenced in the **"MOST IMPORTANT NOTES"** section of [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) and ensure that any modifications made during conflict resolution are propagated to agent configuration files.

## Handling Multiple Worktrees

When integrating work from multiple builder agents, repeat the merge-and-resolution process for each worktree sequentially. Because each worktree merges the latest `main` before integration, you dramatically reduce the likelihood of cascading conflicts. Process worktrees in order of dependency—typically layout-first, then sections—to minimize rework.

## Summary

- **Always merge `main` into the worktree first** to isolate and resolve conflicts before touching the main branch history.
- **Focus resolution on shared files** like [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) and [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts), where multiple agents commonly overlap.
- **Run TypeScript checks** (`npm run typecheck`) after resolution to validate that merges preserved type safety.
- **Remove worktrees with `--force`** only after confirming successful pushes to `main` and deleting the temporary `builder/` branches.
- **Use synchronization scripts** ([`sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/sync-agent-rules.sh), `sync-skills.mjs`) to update agent configurations after integration.

## Frequently Asked Questions

### What causes merge conflicts in the AI Website Cloner Template worktrees?

Merge conflicts occur when multiple builder agents modify the same shared files—most commonly [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) for page structures, [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) for the `cn()` utility function, or global CSS configurations. Because each agent works in an isolated git worktree on its own branch (as mandated by [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md)), simultaneous changes to these shared resources create divergent histories that Git cannot automatically reconcile during the merge back to `main`.

### Why must I merge main into the worktree before merging the worktree to main?

Merging `main` into the worktree branch (e.g., `builder/header`) first follows the "update-then-integrate" pattern recommended in the repository's workflow. This approach isolates conflict resolution within the temporary worktree environment, allowing you to fix markers and run TypeScript validation without affecting the stability of `main`. Once resolved, the final merge to `main` becomes a fast-forward, preserving clean history and ensuring `main` always contains verified, build-passing code.

### How do I handle TypeScript errors that appear after resolving merge conflicts?

After resolving file conflicts, run `npm run typecheck` (or `npx tsc --noEmit`) and `npm run build` as required by the "Parallel Build" pipeline in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md). If TypeScript errors emerge—typically from incompatible type definitions in merged utility files—return to the affected files (often [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)) and adjust the imports or function signatures to satisfy both the builder's generated code and `main`'s type requirements. Never merge to `main` until both commands execute without errors.

### Can I automate the worktree cleanup process after integration?

While the repository provides [`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` for synchronizing agent configurations, the git worktree removal and branch deletion steps are typically performed manually to ensure safety. After verifying the merge to `main` and successful push, use `git worktree remove <path> --force` followed by `git branch -D builder/<component>` to clean up. Automate these commands only after implementing robust CI checks that confirm the integration succeeded and the worktree content is fully merged.