Activate Worktree Environment

Overview

PER-WORKTREE SKILL - Runs the project's pre-generated setup-env.sh to provision an isolated environment for a new git worktree, then verifies readiness with smoke-test.sh. Core principle: Always verify before developing.

PREREQUISITE: Project must already have setup scripts generated by setup-isolated-env:generate-env-scripts. If scripts don't exist, run that skill first.

Announce at start: "i'm using activate-worktree-env skill to set up and verify this worktree environment"

When to Use

Use when:

• A new git worktree has been created for a feature branch
• Starting work in an existing worktree that has no .env.local yet
• Re-provisioning a worktree whose environment was lost or corrupted

Don't use for:

• Creating the setup scripts themselves (use setup-isolated-env:generate-env-scripts)
• Projects without isolation scripts (run generate-env-scripts first)

Quick Reference

Step	Command	Run From
1. Run setup-env.sh	<worktree_scripts>/setup-env.sh	Project root
2. Navigate to worktree	cd .worktrees/<env-name>	Project root
3. Run smoke test	../../<worktree_scripts>/smoke-test.sh	Inside worktree
4. Start dev	bun run dev (or project command)	Inside worktree

Implementation

Step 1: Find Script Location

Check CLAUDE.md for the worktree scripts location:

• Look for ## Isolated Development Environments section
• The location is listed under ### Creating a New Environment

Common locations:

• .worktrees_scripts/ (default)
• scripts/

# Verify scripts exist
ls <worktree_scripts>/setup-env.sh

If scripts don't exist: Stop. Run setup-isolated-env:generate-env-scripts first.

Step 2: Run setup-env.sh

Run from project root (NOT from inside the worktree):

# From project root
<worktree_scripts>/setup-env.sh

The script will:

1. Prompt for environment name (or detect from git branch)
2. Allocate unique ports and database identifiers
3. Create git worktree at .worktrees/<env-name>
4. Copy .env.example → .env.local with unique values
5. Create isolated database
6. Run migrations
7. Display environment summary

If script fails: Read the error output. Common causes:

• Infrastructure not running (start Docker/Supabase first)
• Environment name conflict (choose a different name)
• Database creation permission issue (see Troubleshooting)

Step 3: Navigate to Worktree

cd .worktrees/<env-name>

Step 4: Run Smoke Test

CRITICAL: Smoke test MUST run from WITHIN the worktree (not project root).

# Already inside .worktrees/<env-name>
../../<worktree_scripts>/smoke-test.sh

Smoke test checks:

• Environment variables are set (PORT, DATABASE_URL, etc.)
• Port is available (not in use by another process)
• Database connectivity
• Infrastructure services are running

If smoke test passes: Environment is ready. Start development.

If smoke test fails: Do NOT start development. See Troubleshooting.

Step 5: Start Development

Only after smoke test passes:

# Inside .worktrees/<env-name>
bun run dev
# or: npm run dev / yarn dev / pnpm dev

Troubleshooting

setup-env.sh fails - infrastructure not running:

• Start Docker: docker compose up -d
• Start Supabase: supabase start
• Re-run setup-env.sh

setup-env.sh fails - environment name conflict:

• Choose a different environment name
• Or clean up old environment: <worktree_scripts>/cleanup-env.sh <old-name>

Database creation fails (Supabase MCP projects):

• Check if CLAUDE.md has SQL execution restrictions
• May need to create database manually via Claude Code MCP
• See WORKTREE.md for project-specific database strategy

Smoke test fails - wrong directory:

• Must run from INSIDE the worktree: cd .worktrees/<env-name> first
• Path to smoke test is relative: ../../<worktree_scripts>/smoke-test.sh
• Do NOT run from project root

Smoke test fails - PORT not set:

• Check .env.local exists in worktree
• Verify setup-env.sh completed successfully (no errors)
• Re-run setup-env.sh if .env.local is missing or empty

Smoke test fails - database connectivity:

• Verify infrastructure is running: supabase status or docker compose ps
• Check DATABASE_URL in .env.local points to correct host/port
• Test connection manually: psql "$DATABASE_URL" -c "SELECT 1"

Smoke test fails - port in use:

• Another process is using the allocated port
• Check: lsof -i :<PORT>
• Either stop conflicting process or adjust port in .env.local and re-run smoke test

Cleanup When Done

When finished with the worktree:

# From project root
<worktree_scripts>/cleanup-env.sh <env-name>

This removes the worktree, drops the database, and frees allocated ports.