Best Practices for Merging Worktree Branches After Parallel Builds

Isolate each builder in a dedicated Git worktree, validate TypeScript with npx tsc --noEmit before merging, and use git merge --no-ff to preserve history while running final verification via npm run build and npm run check.

The AI Website Cloner template by JCodesMore orchestrates parallel component builds using isolated Git worktrees to prevent file collisions. When multiple builder agents finish simultaneously, merging these worktree branches back into the main repository requires a deterministic workflow that preserves code integrity and build safety. Following the repository's architectural patterns documented in README.md and AGENTS.md ensures that parallel builds integrate cleanly without history corruption or broken TypeScript.

Isolate Builders in Dedicated Worktrees

The foundation of safe parallel builds starts with complete isolation. According to the repository's parallel build documentation in README.md at line 93, the pipeline creates a fresh worktree for each component using git worktree add:

git worktree add -b feature/header ./worktrees/header-builder

This command establishes an isolated branch where a builder agent can modify files without interfering with other concurrent builders. Each worktree operates as a separate working directory linked to the same repository, ensuring that simultaneous writes never target the same files.

Enforce Type Checking Before Merging

Before any worktree branch is considered ready for integration, the repository mandates strict validation. As specified in README.md at line 94, each builder must run:

npx tsc --noEmit

This type-checking gate prevents broken TypeScript from entering the merge queue. The --noEmit flag ensures the compiler validates types without generating output files, providing fast feedback while maintaining repository cleanliness. Only after this command exits successfully should the worktree branch proceed to the merge phase.

Execute Sequential Merges with Non-Fast-Forward

The actual merging of worktree branches follows a sequential pattern documented in AGENTS.md at line 60. Unlike fast-forward merges that flatten history, the template specifies using --no-ff to preserve the narrative of each builder's contribution:

git checkout main
git pull
git merge --no-ff feature/header
git merge --no-ff feature/footer

Repeat this process for each worktree branch created during the parallel build phase. The --no-ff flag forces Git to create a merge commit even when a fast-forward is possible, maintaining clear boundaries between component contributions and simplifying debugging when issues arise.

Resolve Conflicts Proactively

While worktree isolation prevents most file collisions, shared utility files or component specifications can still generate merge conflicts. When conflicts appear, resolve them by opening the conflicted files and applying the component-spec changes manually. After resolution, re-validate the merged code:

npx tsc --noEmit

This secondary type-check ensures that conflict resolutions did not introduce type errors or broken imports. The repository's "most important notes" emphasize that fast conflict resolution avoids accumulation of "merge hell" scenarios common in parallel development workflows.

Verify Final Output and Clean Up

After all worktree branches merge successfully, the combined output must pass rigorous validation. The pipeline defined in README.md requires running:

npm run build
npm run check

The npm run check command (defined in package.json and enforced in .github/workflows/ci.yml) runs linting, type-checking, and build verification to catch regressions. Once validation passes, remove temporary worktrees to prevent stale references:

git worktree remove ./worktrees/header-builder
git worktree prune

For continued synchronization, run scripts/sync-agent-rules.sh after merging to regenerate platform-specific agent files and keep documentation in sync with the merged codebase.

Summary

• Use git worktree add to create isolated directories for each parallel builder, preventing file collisions during simultaneous component generation.
• Validate with npx tsc --noEmit before merging any worktree branch to ensure TypeScript integrity at the source.
• Merge sequentially using --no-ff to preserve history clarity and create explicit merge commits for each builder's contribution.
• Re-run type checks immediately after resolving merge conflicts to catch integration errors before they reach the main branch.
• Execute npm run build and npm run check after all merges complete to verify the combined output compiles and matches design specifications.
• Clean up with git worktree remove and git worktree prune to eliminate temporary directories and stale references.

Frequently Asked Questions

What is the purpose of using git worktree instead of standard branches for parallel builds?

Git worktrees provide separate working directories for each branch, allowing builders to modify files simultaneously without switching contexts or risking dirty working tree states. According to the AI Website Cloner template's architecture, this isolation ensures that parallel builder agents never overwrite each other's changes during component generation.

Why does the template require --no-ff when merging worktree branches?

The --no-ff (no fast-forward) flag forces Git to create a merge commit even when the branch could be fast-forwarded. As documented in AGENTS.md, this preserves the complete history of each builder's contribution, making it easier to identify which component introduced specific changes or regressions when debugging the parallel build output.

How should I handle TypeScript errors discovered during the merge process?

If npx tsc --noEmit fails during pre-merge validation or after conflict resolution, fix the type errors in the worktree branch before attempting to merge again. The repository's workflow treats type-checking as a mandatory gate; broken TypeScript must never reach the main branch, as this would compromise the npm run build step in the CI pipeline defined in .github/workflows/ci.yml.

Can I automate the cleanup of worktree branches after merging?

Yes, automation is recommended. Create a helper script similar to scripts/sync-agent-rules.sh that executes git worktree remove <path> for each completed builder directory, followed by git worktree prune. This prevents accumulation of stale worktrees and ensures temporary build directories do not clutter the repository or consume unnecessary disk space.

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