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

> Learn the six-step workflow for merging worktree branches into main in the AI Website Cloner Template. Includes validation, PRs, verification, and cleanup.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md) and [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md)** – Contains the detailed step-by-step instructions for the merge phase, including dispatch, wait, and merge operations.
- **[`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** – Documents the five-phase pipeline, particularly the **Parallel Build** (validation) and **Assembly & QA** (post-merge verification) stages.
- **[`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) and executed via [`.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.windsurf/workflows/clone-website.md), which contains the orchestration steps. Supporting policy appears in [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md), while `scripts/sync-skills.mjs` maintains the `/clone-website` skill that automates the worktree creation, merge, and final build verification process.