How the Worktree Merging Process Resolves Conflicts in the AI Website Cloner Template

The AI Website Cloner Template resolves merge conflicts by prioritizing the most recent worktree branch, using automated Git commands for simple conflicts, and falling back to manual resolution with explanatory comments for complex UI code overlaps.

The worktree merging process in the JCodesMore/ai-website-cloner-template orchestrates parallel development across isolated Git worktrees, ensuring that multiple AI builder agents can simultaneously modify code without corrupting the main branch. According to the repository's source code, this system creates temporary branches for each component, validates changes before integration, and applies a structured conflict resolution strategy when overlapping edits occur.

Isolated Worktree Architecture

The foundation of conflict prevention lies in strict isolation. Each builder agent operates within its own Git worktree and associated branch, eliminating cross-contamination during the build phase.

Worktree Creation via Opencode SDK

When the orchestrator (the “foreman” that coordinates the agents) dispatches a builder agent, it invokes the worktreeCreate endpoint of the Opencode SDK to generate a dedicated worktree. For example, a button component might receive its own branch named feature/button-spec:

git worktree add ../worktree-button feature/button-spec
cd ../worktree-button

As documented in [AGENTS.md](https://github.com/JCodesMore/ai-website-cloner-template/blob/master/AGENTS.md#L61), this enforces the policy that "each teammate works in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly."

Independent Development Phase

Inside its isolated worktree, the builder writes code, assets, and specification files without interfering with other agents. Because every worktree maintains its own branch with unique commit history, normal Git isolation guarantees that changes do not clash during the development phase. The scripts/sync-agent-rules.sh file regenerates agent-specific instructions to ensure consistent adherence to these isolation protocols across all parallel workflows.

Pre-Merge Validation Pipeline

Before any worktree branch enters the merge queue, the orchestrator enforces strict validation gates. This early detection prevents broken code from reaching the main branch.

The orchestrator executes a type-check using the command defined in package.json and tsconfig.json:

npx tsc --noEmit

If validation fails, the worktree is not merged; instead, the orchestrator returns the worktree to the responsible agent for error correction. This validation step ensures that only syntactically correct code attempts to merge, reducing the complexity of downstream conflict resolution.

The Merge Execution Strategy

Once all worktrees pass validation, the orchestrator coordinates the integration back into the main branch.

Standard Git Merge Workflow

The orchestrator checks out the main branch and merges each worktree branch sequentially using non-fast-forward merges to preserve branch history:

git checkout main
git merge --no-ff feature/button-spec

Because worktrees are built atop a common base commit, most merges complete as fast-forward or clean merges without intervention. The [README.md](https://github.com/JCodesMore/ai-website-cloner-template/blob/master/README.md#L94-L95) describes this as part of the Assembly & QA stage in the five-stage pipeline.

Conflict Resolution Workflow

When two worktrees modify the same file, the worktree merging process activates its conflict resolution protocol. This workflow prioritizes recency and automation while maintaining code integrity.

Detecting Conflicts

When git merge --no-ff reports a conflict, the orchestrator identifies affected files using standard Git commands:

git status

# or

git diff --name-only --diff-filter=U

These commands list conflicted files with unmerged status, triggering the resolution engine.

Prioritization Strategy

The orchestrator applies a last-writer-wins policy. It prioritizes the most recent worktree—the branch that finished last—because it reflects the latest specification and requirements. This deterministic approach eliminates ambiguity in resolution decisions.

Automated Resolution

For simple conflicts, such as identical line changes or additive import statements, the orchestrator resolves conflicts automatically by accepting the newer version:

git checkout --theirs src/components/ui/button.tsx
git add src/components/ui/button.tsx
git commit -m "Resolve merge conflict for button component"

The --theirs flag implements the recency prioritization directly in Git, keeping the changes from the most recent worktree.

Manual Resolution for Complex Conflicts

When conflicts involve complex UI code overlaps that automated tools cannot reconcile safely, the orchestrator pauses for manual intervention. The system opens the conflicted file, inserts explanatory comments describing the competing changes, and requires human review. After manual editing, the orchestrator re-runs the type-check (npx tsc --noEmit) and build process to verify repository health before completing the commit.

Post-Merge Quality Assurance

After all worktree branches merge successfully, the orchestrator executes a final validation suite. This includes running npm run build and performing visual-diff checks against the original reference site. Any remaining issues are classified as merge-resolution bugs and must be fixed before the final commit is accepted. This guarantees that the merged result maintains functional and visual consistency with the target website.

Summary

• The AI Website Cloner Template uses isolated Git worktrees with unique branches for each builder agent to prevent initial contamination.
• The orchestrator validates each worktree using npx tsc --noEmit before attempting any merge.
• Worktrees merge via git merge --no-ff, with conflicts detected through git status or git diff --name-only --diff-filter=U.
• The resolution process prioritizes the most recent worktree branch, using git checkout --theirs for automated resolution of simple conflicts.
• Complex UI conflicts require manual resolution with explanatory comments, followed by re-validation using npm run build.
• Final QA includes visual-diff checks to ensure the merged output matches the original site specification.

Frequently Asked Questions

What triggers the conflict resolution process in the worktree merging strategy?

The conflict resolution process activates when the orchestrator executes git merge --no-ff <branch> and Git detects overlapping modifications to the same file across different worktree branches. This typically occurs when two AI builder agents independently edit shared components or configuration files, causing the merge operation to stop and report unmerged paths.

How does the orchestrator decide which worktree changes to keep during a merge?

The orchestrator implements a recency-based prioritization strategy that favors the worktree branch that finished last. According to the AGENTS.md policy, this reflects the latest specification. For automated resolution, the system uses git checkout --theirs <file> to accept the newer version, while complex conflicts require manual review with explanatory comments added to the code.

What validation checks run before and after merging worktree branches?

Before merging, each worktree must pass npx tsc --noEmit (type-checking) as defined in tsconfig.json and package.json. After all merges complete, the orchestrator runs npm run build and visual-diff checks against the original site. Any failures during these stages prevent the merge from finalizing or require immediate bug fixes.

Where is the worktree merge policy documented in the repository?

The merge policy appears in [AGENTS.md](https://github.com/JCodesMore/ai-website-cloner-template/blob/master/AGENTS.md#L61) at line 61, which mandates that agents "work in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly." The [README.md](https://github.com/JCodesMore/ai-website-cloner-template/blob/master/README.md#L94-L95) at lines 94-95 further describes this as the Assembly & QA stage of the five-stage pipeline, while scripts/sync-agent-rules.sh enforces these rules across agent configurations.

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