Worktree Merge Process After Builder Agents Complete Their Tasks

The worktree merge process stitches together isolated Git worktrees from parallel builder agents into a coherent main branch through pre-merge TypeScript validation, fast-forward merges, and post-merge build verification.

After parallel builder agents finish generating code sections in the JCodesMore/ai-website-cloner-template repository, the pipeline enters the merge phase to consolidate isolated worktrees. This process ensures that each component built in isolation—such as hero sections or footers—integrates into a type-safe, build-ready Next.js codebase without conflicts.

How Builder Agents Use Git Worktrees

Each builder agent operates within its own Git worktree to prevent file system collisions during parallel development. The orchestration script creates isolated branches (e.g., builder-hero, builder-footer) where agents write component files independently.

According to the repository's AGENTS.md policy, all agents must work in isolated worktrees and merge at the end of their tasks. This isolation allows multiple builders to modify src/components/ simultaneously without stepping on each other's changes.

The worktree creation follows this pattern:

# Orchestrator creates isolated worktree for a builder agent

git worktree add -b builder-hero ./worktrees/builder-hero main

The Merge Phase Workflow

The worktree merge process operates as an iterative cycle managed by the orchestrator (foreman). Each builder's contributions move through validation, merging, and verification stages before final page assembly.

Pre-Merge TypeScript Validation

Before merging back to main, each builder must guarantee its code compiles cleanly. The agent runs TypeScript checks inside its worktree directory:

cd worktrees/builder-hero
npx tsc --noEmit

This validation step ensures that type errors never reach the main branch. As documented in .windsurf/workflows/clone-website.md under the "Step 4: Merge" section, this checkpoint prevents broken code from entering the integration pipeline.

Merging Builder Branches to Main

Once validation passes, the orchestrator checks out the main branch and pulls the builder's worktree branch for merging. The merge typically executes as a fast-forward or straight-line merge because each builder only touches its own component files:

git checkout main
git merge --no-ff builder-hero

The --no-ff flag ensures a merge commit is created even when fast-forwarding is possible, preserving the history of which builder contributed which components. This logic is detailed in the workflow documentation at .windsurf/workflows/clone-website.md#L92-L99.

Post-Merge Build Verification

After each merge, the pipeline runs a full project build to confirm integration success:

npm run build

If type errors or build failures appear, they are fixed immediately before the next builder's worktree is merged. This iterative verification ensures that the cumulative codebase remains build-ready throughout the merge process.

Handling Merge Conflicts and Rollbacks

When the post-merge verification fails, the orchestrator can revert the problematic merge:

git revert <merge-commit>

Alternatively, conflicts can be resolved manually by re-applying the builder's changes after fixing the spec file. This rollback capability prevents a single builder's errors from blocking the entire pipeline.

Key Files in the Merge Architecture

The worktree merge process relies on specific configuration files that define the pipeline behavior:

• README.md – Contains the high-level pipeline overview, specifically the "Parallel Build" and "Assembly & QA" items at lines 93-95 that describe the merge sequence.

• .windsurf/workflows/clone-website.md – Provides step-by-step merge instructions and orchestration logic for the foreman agent.

• AGENTS.md – Defines the policy requiring all agents to work in isolated worktrees and merge at completion.

• src/app/page.tsx – Serves as the final page assembly point where merged components are imported after all worktrees integrate into the main branch.

Summary

• Builder agents create isolated Git worktrees (e.g., builder-hero) to work independently on specific page sections.
• Each builder runs npx tsc --noEmit to validate TypeScript correctness before merging.
• The orchestrator merges worktree branches using git merge --no-ff for clear contribution history.
• Post-merge verification runs npm run build to ensure the integrated codebase compiles successfully.
• Failed merges can be reverted immediately to maintain main branch stability.

Frequently Asked Questions

Why do builder agents use Git worktrees instead of separate clones?

Git worktrees allow agents to share the same repository object database while maintaining separate working directories. This approach saves disk space and ensures all builders reference the same base commit, making the worktree merge process faster and more reliable than managing multiple full clones.

What happens if the post-merge build fails?

If npm run build fails after merging a builder's worktree, the orchestrator immediately reverts the merge commit using git revert or resolves conflicts manually. The builder must then fix the underlying issues in its spec file before the merge is attempted again, preventing broken code from persisting in the main branch.

How does the orchestrator handle merge conflicts between builders?

The orchestrator minimizes conflicts by ensuring each builder only modifies its assigned component files. When conflicts do occur, the foreman agent resolves them manually or reverts the problematic merge. The workflow documented in .windsurf/workflows/clone-website.md specifies that builders should touch disjoint file sets to enable fast-forward merges.

Where does the final page assembly occur after all worktrees merge?

The final page assembly happens in src/app/page.tsx, which imports the components from all merged builder worktrees. This file serves as the integration point where the isolated sections (hero, footer, navigation) compose into the complete Next.js page after the worktree merge process completes.

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