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

To resolve merge conflicts, first merge main into the worktree branch, resolve conflict markers in shared files like 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, 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—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, 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:

# List all worktree directories and their associated branches

git worktree list

Update the main branch to prevent unnecessary rebase operations later:

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:

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 – Shared layout updates and global providers
• src/lib/utils.ts – The cn() utility function for class-name merging
• src/ global CSS or Tailwind configuration files

After editing, stage the resolutions:

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 pipeline documentation, you must verify that conflict resolutions did not introduce type errors:

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:

git checkout main
git merge builder/header

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

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 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 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 and 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, 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 for page structures, 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), 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. If TypeScript errors emerge—typically from incompatible type definitions in merged utility files—return to the affected files (often 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 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.

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