How to Merge Worktree Branches After Parallel Building in the AI Website Cloner Template

The AI Website Cloner Template merges parallel-built worktree branches by creating isolated git worktrees for each section builder, verifying TypeScript integrity with npx tsc --noEmit, and sequentially integrating branches back into main with immediate regression testing via npm run build.

The AI Website Cloner Template orchestrates multiple builder agents to clone website sections simultaneously using git worktrees for isolation. Understanding the merge process for handling worktree branches after parallel building is critical to maintaining type safety and preventing integration conflicts in the Next.js codebase.

The Isolated Worktree Architecture

The repository implements a parallel extraction strategy where each website section (header, hero, footer, etc.) receives its own dedicated builder agent. Rather than risking contamination of the main branch during concurrent development, the orchestrator creates lightweight git worktrees—separate checkout directories linked to unique branches—that allow simultaneous construction without interference.

As documented in the workflow specifications, this architecture follows a strict extract → spec → dispatch → merge cycle that repeats until all sections are fully built and integrated.

Step-by-Step Merge Process for Worktree Branches

1. Creating Dedicated Worktrees for Each Section

When a builder agent begins processing a section, the orchestrator generates a fresh worktree attached to a specific branch. This isolates the builder's changes from the main line of development.

# Example: Create worktree for header section

git worktree add -b worktree-header .worktrees/header HEAD

The builder operates within .worktrees/header, making changes independently of other parallel builds.

2. Type-Safe Building and Committing

Before any merge can occur, the builder must verify type integrity. According to .windsurf/workflows/clone-website.md, the builder runs strict TypeScript validation:

cd .worktrees/header
npx tsc --noEmit  # Must exit zero before proceeding

Once the type-check succeeds, the builder commits changes to the worktree branch:

git add .
git commit -m "Add Header component (generated by builder agent)"

3. Merging Branches with Regression Testing

After a builder finishes its section, the orchestrator merges the worktree branch into the primary main branch. The workflow mandates immediate verification to catch integration regressions.

As specified in lines 397-401 of .windsurf/workflows/clone-website.md, the merge process requires:

"After each merge, verify the build still passes: npm run build"

And:

"If a merge introduces type errors, fix them immediately"

The merge command uses a non-fast-forward strategy to preserve history:

git checkout main
git merge --no-ff worktree-header
npm run build  # Re-run to verify no regressions

4. Iterative Integration Until Completion

The orchestrator repeats the extract → spec → dispatch → merge cycle for every section (e.g., worktree-footer, worktree-hero). As noted in the workflow documentation at line 403, "The extract → spec → dispatch → merge cycle continues until all sections are built."

Each iteration requires cleaning up the completed worktree:

git worktree remove .worktrees/header
git branch -d worktree-header

5. Final Assembly and Wiring

Once all worktree branches are merged and verified, the final step involves assembling the components in the Next.js entry point. According to lines 404-407 of .windsurf/workflows/clone-website.md:

"After all sections are built and merged, wire everything together in src/app/page.tsx"

This represents the last checkpoint before the production build, ensuring all parallel contributions coalesce into a single coherent application.

Critical Implementation Files

The merge process is governed by several key files that define the architectural contract:

File	Role in the Merge Process
.windsurf/workflows/clone-website.md	Defines the step-by-step workflow including merge verification (npm run build requirements) and final wiring instructions
README.md	Documents the high-level Assembly & QA stage at line 94 that describes the worktree merging strategy
AGENTS.md	Establishes agent policy at line 61: "merge everyone's work at the end"
src/app/page.tsx	Final assembly point where merged components are imported and wired together
package.json / next.config.ts	Configuration files that must remain consistent after each merge

Complete Workflow Example

The following bash script demonstrates the full lifecycle of a single worktree branch from creation to merge:

# 1. Create worktree for new section

git worktree add -b worktree-header .worktrees/header HEAD

# 2. Builder makes changes and commits

cd .worktrees/header

# ... extraction and specification edits ...

git add .
git commit -m "Add Header component (generated by builder agent)"

# 3. Run type-check inside worktree (required before merge)

npx tsc --noEmit

# 4. Merge back to main and verify

git checkout main
git merge --no-ff worktree-header
npm run build  # Must succeed; fix TS errors immediately if it fails

# 5. Clean up worktree

git worktree remove .worktrees/header
git branch -d worktree-header

The orchestrator executes this sequence for every parallel section, ensuring type safety and build integrity at each integration point.

Summary

• Isolation via worktrees: Each builder receives a dedicated git worktree (git worktree add -b) to prevent cross-contamination during parallel development.
• Type-gated commits: Builders must pass npx tsc --noEmit before their work is eligible for merging.
• Verified merges: Every merge into main requires immediate regression testing with npm run build, with mandatory fixes for any introduced type errors.
• Iterative completion: The extract → spec → dispatch → merge cycle repeats until all sections are built, as documented in .windsurf/workflows/clone-website.md at line 403.
• Final wiring: After all worktree branches are merged, components are assembled in src/app/page.tsx before the final production build.

Frequently Asked Questions

What happens if a merge introduces TypeScript errors?

The workflow mandates immediate remediation. According to .windsurf/workflows/clone-website.md (lines 397-401), if npm run build fails after a merge, the orchestrator must fix the type errors immediately before proceeding to the next section. This prevents error accumulation that could destabilize the main branch.

Why use git worktrees instead of separate clones?

Git worktrees provide lightweight isolation without the storage overhead of full repository clones. They share the same object database while maintaining separate working directories and branches, making them ideal for parallel builder agents that need isolated environments but must eventually merge into a unified history.

How does the orchestrator handle merge conflicts between parallel builders?

The template architecture minimizes conflicts by isolating sections (headers, footers, heroes) into distinct component files. However, if conflicts arise during git merge --no-ff, the orchestrator must resolve them intelligently before the verification step. The AGENTS.md policy at line 61 emphasizes that all work must be merged at the end, implying conflict resolution is part of the orchestrator's final integration duties.

Where does the final assembly occur after all merges are complete?

Final assembly happens in src/app/page.tsx. As documented in .windsurf/workflows/clone-website.md at lines 404-407, only after all worktree branches are merged and verified does the orchestrator wire the assembled components together in the Next.js page entry point, serving as the last step before production deployment.

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