activate-worktree-env

What this skill does

# 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/`

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

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

```bash
cd .worktrees/<env-name>
```

### Step 4: Run Smoke Test

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

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

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

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

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