worktree-bootstrap

name	worktree-bootstrap
description	Create and fully bootstrap a WWV git worktree for isolated feature/debug work. Copies env vars, installs deps, generates Prisma client, and verifies the dev server boots before reporting ready.

Worktree Bootstrap

Use this skill when creating a new worktree for isolated debugging or feature work. Eliminates the repeated "missing .env.local" / "Prisma client not generated" failures.

Steps

1. Create the worktree

From C:\dev\wwv\worldwideview\:

git-wt switch --create <branch-name> --yes

This places the worktree at C:\dev\wwv\worldwideview.<branch-name>\.

2. Copy environment file

.env contains shared secrets (AUTH_SECRET, DATABASE_URL, etc.) that are gitignored and not present in new worktrees. Copy it:

Copy-Item C:\dev\wwv\worldwideview\.env C:\dev\wwv\worldwideview.<branch-name>\.env

Verify required vars are present:

Select-String -Path C:\dev\wwv\worldwideview.<branch-name>\.env -Pattern "^AUTH_SECRET=|^DATABASE_URL="

If you need worktree-specific overrides (different port, DB name, feature flags), create a .env.local alongside it - Next.js loads .env.local on top of .env.

Both must match. If either is missing, copy from a teammate or the main .env.local.

3. Install dependencies

Set-Location C:\dev\wwv\worldwideview.<branch-name>
pnpm install

4. Generate Prisma client

npx prisma generate

5. Initialize isolated .planning

Each worktree gets its OWN real .planning directory, never a junction to the shared root. This keeps phases and STATE private per worktree so simultaneous sessions never bleed into each other.

$wt = "C:\dev\wwv\worldwideview.<branch-name>"
New-Item -ItemType Directory -Force -Path "$wt\.planning\phases", "$wt\.planning\debug", "$wt\.planning\surveys" | Out-Null
Copy-Item C:\dev\wwv\.planning\config.json "$wt\.planning\config.json" -Force

Then add three files in $wt\.planning\:

• WORKSPACE.md (manifest: branch, repo, "real isolated dir" note)
• STATE.md (fresh GSD state: milestone: none, status: idle)
• SHARED-DOCS.md (pointer to the shared cross-feature docs)

Quickest way is to copy these three from an existing isolated worktree and edit the branch/feature name:

Copy-Item C:\dev\wwv\worldwideview.test-sandbox\.planning\WORKSPACE.md, C:\dev\wwv\worldwideview.test-sandbox\.planning\STATE.md, C:\dev\wwv\worldwideview.test-sandbox\.planning\SHARED-DOCS.md "$wt\.planning\"

NEVER create .planning as a junction. The shared root C:\dev\wwv\.planning holds ONLY cross-feature docs (ROADMAP, MILESTONES, research, PROJECT, REQUIREMENTS).

6. Wire the shared-docs env var

So GSD skills can find cross-feature docs without duplicating them, add to the worktree's .env.local:

WWV_SHARED_PLANNING=C:/dev/wwv/.planning

7. (Optional) Sync with main

If the branch is behind main:

git merge main
# or
git rebase main

8. Verify the dev server boots

pnpm dev

Watch for the "Ready" line. If it fails, check:

• Docker is running (needed for PostgreSQL): docker compose up -d
• No port conflict on 3000: netstat -ano | Select-String ":3000"

9. Report ready

Once the dev server returns HTTP 200 on http://localhost:3000, the worktree is ready for use.

.planning Isolation (per-worktree)

Each worktree owns a real, isolated .planning directory (created in Step 5). It is NOT a junction and NOT shared. Phases and STATE.md are private to the worktree, so two simultaneous sessions on different features never see each other's phases.

This replaces the older "one .planning branch per worktree" model (which relied on .planning being a git repo with a SessionStart/post-checkout hook switching its branch). That model could not isolate simultaneous sessions: all worktrees shared one physical .planning HEAD, so whichever session ran its hook last won and the others silently read the wrong feature's phases. The per-worktree real-directory model fixes that.

Cross-feature docs

ROADMAP, MILESTONES, research/, PROJECT, REQUIREMENTS stay authoritative at the shared root C:\dev\wwv\.planning. Each worktree references them via the WWV_SHARED_PLANNING env var (Step 6) instead of duplicating them. See SHARED-DOCS.md in any worktree's .planning.

Self-healing

If you find a worktree whose .planning is still a junction (created before the migration), the planning-sync.sh SessionStart hook converts it into a real isolated directory automatically on the next session open.

Teardown

When done, use /branch-cleanup. It archives this worktree's real .planning to the shared archive first, then removes the worktree via the worktree-manager agent. Never rm -rf a worktree (it orphans the Docker volume). For a manual teardown:

Set-Location C:\dev\wwv\worldwideview
git-wt remove