How to Verify TypeScript and Build Integrity After Merging Component Worktrees in AI Website Cloner

Run npx tsc --noEmit to catch type errors and npm run build to validate the production bundle after merging all Git worktrees back into the main branch.

The AI Website Cloner Template orchestrates parallel development through isolated Git worktrees, allowing multiple builder agents to modify different sections simultaneously. When these component branches converge into the main repository, you must verify TypeScript and build integrity after merging component worktrees to prevent deployment failures. This verification process ensures that the Next.js application compiles under strict type checking and bundles successfully through the Tailwind CSS pipeline.

The Two-Step Verification Workflow

The repository enforces a strict two-phase validation strategy documented in .windsurf/workflows/clone-website.md and .opencode/commands/clone-website.md. Each phase targets distinct failure modes that emerge when independent worktrees integrate.

Phase 1: TypeScript Type Checking

Before any worktree merges, each builder agent must validate its contributions using npx tsc --noEmit. This command scans all TypeScript files against the strict configuration defined in tsconfig.json without emitting JavaScript artifacts. It detects missing imports, interface mismatches, and implicit any violations that could propagate into the main branch.

Phase 2: Production Build Validation

After merging worktrees into the main branch, running npm run build executes the Next.js compiler alongside the Tailwind CSS pipeline. This step validates that the combined codebase produces a runnable production bundle, catching route conflicts, duplicate Tailwind class definitions, and asset bundling errors that type checking alone cannot detect.

Pre-Merge TypeScript Validation

Every builder agent must pass type verification before finishing its worktree session. According to AGENTS.md, the source of truth for agent behavior, agents execute npx tsc --noEmit to ensure their code is free of type errors. This check validates dependencies on shared utilities like src/lib/utils.ts and ensures strict mode compliance across the monorepo.

Run this command in each worktree before committing:

npx tsc --noEmit

A zero exit status confirms type safety. Non-zero exits indicate the agent must resolve missing imports or interface mismatches before the worktree can be safely merged.

Post-Merge Build Verification

Once all component worktrees merge into the main branch, immediate build verification prevents broken deployments. The package.json defines the build script that triggers the Next.js production compiler and Tailwind processing.

Execute the full verification sequence after merging:

git checkout main
git merge worktree-component-foo

# Repeat for each component worktree

npx tsc --noEmit
npm run build

This sequence catches merge-induced type conflicts and bundling errors. If npm run build fails, the error typically stems from duplicate route definitions or conflicting Tailwind configurations introduced by parallel agents.

Automated Workflow Integration

The template maintains synchronization across AI agent platforms through scripts/sync-agent-rules.sh and scripts/sync-skills.mjs. These scripts propagate the verification commands from AGENTS.md into platform-specific instruction files, ensuring that every agent—whether using Windsurf or OpenCode—follows identical type checking and build protocols.

The workflow documentation explicitly mandates that agents verify npx tsc --noEmit before finishing and that maintainers verify npm run build after integration. This consistency prevents version drift in verification logic across the distributed development environment.

Handling Verification Failures

When either check fails, revert the problematic merge and isolate the conflict:

1. Identify the offending file from the TypeScript compiler or Next.js build output.
2. Checkout the source worktree branch and apply fixes.
3. Re-run npx tsc --noEmit in the worktree.
4. Re-merge the corrected branch.
5. Execute the full post-merge verification sequence.

This iterative process ensures that only type-safe, build-verified code reaches the main branch.

Summary

• Type checking with npx tsc --noEmit validates TypeScript integrity in individual worktrees before merging, catching missing imports and strict mode violations.
• Production builds with npm run build verify that merged worktrees bundle correctly through the Next.js and Tailwind pipeline, detecting route conflicts and CSS issues.
• AGENTS.md and synchronization scripts (scripts/sync-agent-rules.sh, scripts/sync-skills.mjs) enforce consistent verification across all AI agent platforms.
• Failures require reverting the merge, fixing the source worktree, and repeating the verification sequence before final integration.

Frequently Asked Questions

What command checks for type errors without generating JavaScript files?

Use npx tsc --noEmit to validate TypeScript against tsconfig.json settings without emitting compiled output. This command is configured in package.json under the typecheck script and runs during both pre-merge agent validation and post-merge integrity checks.

Why does the build fail after merging worktrees even when type checking passes?

TypeScript validation confirms syntax and type correctness, but npm run build catches runtime bundling issues like duplicate Next.js route definitions, conflicting Tailwind CSS classes, or asset resolution errors that only surface during the production compilation phase.

Where are the verification rules defined for AI agents?

The primary source of truth is AGENTS.md, which mandates that builder agents must pass npx tsc --noEmit before finishing worktrees. The scripts scripts/sync-agent-rules.sh and scripts/sync-skills.mjs propagate these rules into platform-specific files like .windsurf/workflows/clone-website.md and .opencode/commands/clone-website.md.

How do I resolve type conflicts between parallel worktrees?

Revert the failing merge, switch to the source worktree branch, and run npx tsc --noEmit to identify the specific conflict. Fix the imports or interface definitions, verify the build passes in isolation, then re-merge and run the full post-merge verification sequence (npx tsc --noEmit && npm run build) on the main branch.

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