worktree-bootstrap

Make a git worktree run its dev server exactly like the active trunk — in one command. Project-agnostic: works for any JavaScript/TypeScript repo on macOS, Linux, or WSL.

Two modes (auto-detected)

Run the same script anywhere — it detects where you are and does the right thing:

• Inside a linked worktree → bootstrap it: catch up to the trunk, copy env, install deps, check the Next.js pins. (The common case — the rest of this doc.)
• In the primary checkout (not a worktree) → prep the current branch for worktrees: audit the branch-level things every future worktree inherits — a .worktreeinclude file (so new worktrees get gitignored secrets at creation) and the turbopack.root / allowedDevOrigins pins — and report what's missing. When the script runs in prep mode, apply its recommendations: create or extend .worktreeinclude (safe + additive — show the user what you're adding), and propose the next.config pins for confirmation (they're source code). It's a one-time "make this branch worktree-ready" pass.

Why this exists

A linked worktree is pinned to its own dedicated branch (git won't let two worktrees share one), and that branch is frozen at creation — it never advances, so every commit on the trunk leaves the worktree silently behind ("missing commits"). On top of that, git worktree add (and claude --worktree) only check out tracked files, so a new worktree is also missing the gitignored things a dev server needs:

• Behind the trunk → the worktree's branch predates recent commits (config pins, lockfile changes, fixes). This skill fast-forwards it to the trunk first, so every later step runs on the final tree.
• .env.local / .env → the app crashes at runtime because a required env var is undefined (a database URL, an API key, etc.).
• node_modules → pnpm run dev fails with next: command not found (pnpm won't climb to the parent's node_modules).