How the AI Website Cloner Template Merge Process Resolves Conflicts Between Worktree Branches

The AI Website Cloner Template orchestrates merges by running isolated Git worktrees per component, verifying each branch with type-checks before merging via git merge --no-ff, and resolving conflicts by prioritizing the most recent worktree while using automated strategies for simple clashes and manual intervention for complex UI code.

The JCodesMore/ai-website-cloner-template implements a distributed build system where multiple AI builder agents develop simultaneously in isolated Git worktrees. When these parallel development streams converge, the orchestrator—acting as a "foreman"—manages a structured merge process that resolves conflicts between worktree branches using standard Git semantics enhanced with automated validation and temporal prioritization.

Isolated Worktree Architecture and Branch Strategy

The foundation of the conflict resolution strategy begins with strict isolation. According to AGENTS.md at line 61, the policy mandates that "each teammate works in their own worktree branch and merge everyone's work at the end, resolving any merge conflicts smartly." This design ensures that the merge process only begins after independent development phases complete.

Worktree Creation and Branch Isolation

Each builder agent receives a dedicated worktree created via the worktreeCreate endpoint of the Opencode SDK. These worktrees operate on unique branches (e.g., feature/button-spec), providing natural Git isolation that prevents clashes during the build phase. As documented in README.md lines 94-95, this architecture supports the template's five-stage pipeline, culminating in the "Assembly & QA" step where worktree branches converge.

Pre-Merge Verification Pipeline

Before the merge process resolves conflicts between worktree branches, the orchestrator enforces strict quality gates. The system runs npx tsc --noEmit to perform type-checking on each worktree branch, followed by npm run build after all merges complete.

If a worktree fails these checks, the orchestrator rejects the merge and returns the branch to the responsible agent for fixes. This verification layer, configured in package.json and tsconfig.json, ensures that only valid code enters the merge process, reducing the complexity of potential conflicts.

The Step-by-Step Merge Workflow

The orchestrator executes a sequential merge strategy that combines standard Git operations with intelligent conflict resolution.

Standard Git Merge Execution

The orchestrator checks out the main branch and merges each worktree branch individually using git merge --no-ff <branch>. Because branches are built upon a common base, most merges proceed as fast-forward or clean merges without manual intervention.

# Orchestrator merges the worktree back into main

git checkout main
git merge --no-ff feature/button-spec   # fast-forward if possible

Conflict Detection and File Identification

When Git detects overlapping changes—such as two worktrees editing the same file—the merge halts. The orchestrator identifies conflicted files using git status or git diff --name-only --diff-filter=U to list only unmerged files.

# If a conflict occurs

git status                               # shows conflicted files

git diff --name-only --diff-filter=U     # list unmerged files

Prioritization and Resolution Strategies

The resolution strategy prioritizes the most recent worktree, as it reflects the latest specification. This temporal prioritization guides the automated decision-making process when determining which changes to preserve.

For simple conflicts—such as identical lines or additive imports—the orchestrator auto-resolves by keeping both changes using git checkout --theirs <file>.

# Automated resolution keeps the most recent worktree version

git checkout --theirs src/components/ui/button.tsx   # keep newest version

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

Complex UI code conflicts require manual resolution. The orchestrator opens the affected files, inserts explanatory comments, and re-runs the type-check and build commands to verify repository health before finalizing the commit.

Post-Merge Quality Assurance

After all worktree branches merge into main, the orchestrator executes final validation through npm run build and visual-diff checks against the original site. Any remaining issues are classified as merge-resolution bugs and must be fixed before the final commit. The scripts/sync-agent-rules.sh file regenerates agent-specific instructions to ensure consistent adherence to these merge-conflict guidelines across all operations.

Summary

• Isolated worktrees prevent conflicts during development by giving each AI builder agent its own branch (e.g., feature/button-spec) via the worktreeCreate endpoint.
• Pre-merge verification requires npx tsc --noEmit and npm run build to pass before any merge proceeds, ensuring only healthy code enters the main branch.
• Git-based merging uses git merge --no-ff sequentially, with conflicts detected via git status and git diff --name-only --diff-filter=U.
• Temporal prioritization favors the most recent worktree during conflict resolution, using git checkout --theirs for auto-resolution of simple conflicts.
• Manual intervention handles complex UI conflicts with explanatory comments and mandatory re-validation through package.json build scripts.
• Final QA includes full builds and visual-diff checks, with scripts/sync-agent-rules.sh maintaining consistent merge policies across agents.

Frequently Asked Questions

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

The orchestrator prioritizes the most recent worktree branch, as it reflects the latest specification. For automated resolution of simple conflicts like additive imports, it uses git checkout --theirs <file> to preserve the newer version. Complex conflicts require manual editing with explanatory comments before re-running npx tsc --noEmit and npm run build to verify integrity.

What happens if a worktree branch fails the type-check before merging?

If npx tsc --noEmit returns errors, the orchestrator immediately aborts the merge for that specific worktree branch. The branch is returned to the responsible AI builder agent for fixes, and the merge process continues only after the type-check passes. This policy, enforced through tsconfig.json settings, prevents broken code from entering the main branch.

Can the merge process handle multiple worktree branches simultaneously?

The orchestrator merges worktree branches sequentially rather than simultaneously, checking out the main branch and running git merge --no-ff <branch> for each worktree individually. This sequential approach allows the system to isolate conflicts to specific branches and apply the temporal prioritization strategy consistently without cross-contamination between parallel merges.

What Git commands does the AI Website Cloner Template use for conflict detection?

The system uses git status to identify conflicted files during the merge process, and git diff --name-only --diff-filter=U to list specifically unmerged files requiring resolution. These commands enable the orchestrator to distinguish between successful merges and those requiring automated or manual intervention using git checkout --theirs or hand-edited resolution.

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