How to Merge Completed Worktree Branches into the Main Branch in the AI Website Cloner Template

The AI Website Cloner Template uses a six-step workflow to merge isolated worktree branches into main that involves type-check validation, pull request creation, post-merge verification, and repository cleanup.

The AI Website Cloner Template (JCodesMore/ai-website-cloner-template) manages parallel development through isolated git worktrees, where each builder-agent works in a separate branch. When development completes, the repository follows a strict orchestrated workflow defined in .windsurf/workflows/clone-website.md and AGENTS.md to safely integrate changes back into the canonical main branch.

Prerequisites and Validation

Before any merge operation, the worktree must pass a type-check validation gate. According to the README's "Parallel Build" section, every worktree must successfully run npx tsc --noEmit to ensure TypeScript integrity before it is considered ready for integration into main.

This validation prevents type errors from entering the main branch and aligns with the agent instructions in AGENTS.md that require builders to "merge everyone's work at the end, resolving any merge conflicts smartly."

Step-by-Step Merge Workflow

The complete workflow for merging completed worktree branches into the main branch consists of five distinct phases:

1. Validate the Worktree

Navigate to the specific worktree directory and run the TypeScript compiler to verify type safety:

cd worktrees/component-header
npx tsc --noEmit

The command must exit with code 0 before proceeding. This step corresponds to the Parallel Build phase documented in the repository README.

2. Push the Worktree Branch

Once validation passes, push the temporary worktree branch to the remote repository:

git push origin worktree/component-header

This makes the branch available for pull request creation and code review.

3. Create or Fast-Forward Merge

The orchestrating script creates a pull request against main. Using the GitHub CLI, this appears as:

gh pr create \
   --title "Add header component (worktree)" \
   --base main \
   --head worktree/component-header

Alternatively, if repository policy allows direct integration, the workflow may perform a fast-forward merge without PR overhead.

4. Run Final Verification

After the PR is merged, the orchestrator executes the Assembly & QA stage. This involves running the full production build and verification checks from the repository root:

cd /path/to/repo
npm run build
npm run lint && npm run typecheck

The workflow also triggers visual-diff checks to guarantee that the integration does not break the site. This final verification step ensures that parallel worktree development results in a coherent, production-ready codebase.

5. Clean Up the Worktree

Remove the worktree directory and delete the temporary branch to maintain repository hygiene:

git worktree remove worktrees/component-header
git branch -D worktree/component-header

This cleanup phase prepares the repository for the next set of component worktrees.

Orchestration and Configuration Files

The merge workflow is encoded across several key files in the repository:

• .windsurf/workflows/clone-website.md – Contains the detailed step-by-step instructions for the merge phase, including dispatch, wait, and merge operations.
• AGENTS.md – Specifies the policy that "each teammate works in their own worktree branch and merge everyone's work at the end," governing how agents resolve conflicts during integration.
• README.md – Documents the five-phase pipeline, particularly the Parallel Build (validation) and Assembly & QA (post-merge verification) stages.
• scripts/sync-agent-rules.sh and scripts/sync-skills.mjs – Maintain synchronization of merge policies across different platforms and update the /clone-website skill that orchestrates worktree creation and merging.

Summary

• Type-check first – Every worktree must pass npx tsc --noEmit before merging.
• PR-based integration – Worktree branches are pushed and merged via pull requests (or fast-forward when policy permits).
• Post-merge verification – The Assembly & QA stage runs full builds, linting, and visual-diff checks to ensure integration quality.
• Automated cleanup – Worktrees are removed and temporary branches deleted after successful merge.
• Policy-driven – The workflow is enforced through AGENTS.md and executed via .windsurf/workflows/clone-website.md.

Frequently Asked Questions

What is a git worktree and why does this template use them?

A git worktree allows you to check out multiple branches simultaneously in separate directories. The AI Website Cloner Template uses isolated worktrees so that multiple builder-agents can develop different components (headers, footers, sections) in parallel without interfering with each other's working directories or the main branch state.

What happens if the type-check validation fails during the merge workflow?

If npx tsc --noEmit exits with a non-zero code, the merge workflow halts immediately. The worktree branch cannot be pushed or merged into main until all TypeScript errors are resolved, preventing broken code from entering the production branch.

Can I merge worktree branches without creating a pull request?

Yes, depending on repository policy. The workflow supports both pull request-based merges (using gh pr create and gh pr merge) and direct fast-forward merges for trusted or automated integrations. However, the README and AGENTS.md recommend PR-based workflows for proper code review and conflict resolution.

Where is the merge workflow logic actually defined in the source code?

The merge workflow logic is primarily defined in .windsurf/workflows/clone-website.md, which contains the orchestration steps. Supporting policy appears in AGENTS.md, while scripts/sync-skills.mjs maintains the /clone-website skill that automates the worktree creation, merge, and final build verification process.

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