worktree-enhanced

Enhanced Worktree Workflow

When to Use This Skill

Use this skill when:

• Starting work on a new feature or bug fix
• Need isolation from current workspace
• Want parallel development on multiple issues
• Executing implementation plans that require clean state

This skill handles the full worktree setup workflow with:

• Dev server detection and coordination
• Local env file propagation from the main checkout
• Automatic dev server startup option
• Project-specific worktree conventions

Enhanced Features

1. Dev Server Awareness

Every worktree gets its own dev-server port — never assume port 3000 belongs to the worktree you're in. If the project has adopted the per-worktree port pattern (scripts/worktree-port.cjs, installed by install-worktree-port.sh), resolve the port before checking it:

# Resolve this checkout's port: the per-worktree script if the project has it
# installed, else the port recorded in .claude/launch.json, else 3000 (the
# main-checkout default)
if [ -f scripts/worktree-port.cjs ]; then
  PORT="$(node scripts/worktree-port.cjs)"
else
  PORT="$(node -p "require('./.claude/launch.json').configurations[0].port" 2>/dev/null || echo 3000)"
fi

DEV_SERVER_PID=$(lsof -ti:"$PORT")

if [ -n "$DEV_SERVER_PID" ]; then
  echo "Dev server already running on port $PORT (PID: $DEV_SERVER_PID)"
else
  echo "No dev server running on port $PORT yet"
fi

If the project has no per-worktree port scripts yet, run install-worktree-port.sh <project-dir> (in shared/Development/tools/dev-server/) before creating more worktrees — otherwise every worktree's npm run dev fights over the same port.

2. Worktree Creation

# Standard worktree creation from base skill
git worktree add [path] -b [branch] [base-branch]

# Copy ignored local env files from the main checkout, if present. These files
# stay untracked, but worktrees need the same server-side keys and feature flags.
main_worktree="$(git worktree list --porcelain | awk '
  /^worktree / { path = substr($0, 10) }
  /^branch / && $2 !~ /worktrees/ {
    print path
    exit
  }
')"

for env_file in .env.local .env.development.local .env.test.local; do
  if [ -n "$main_worktree" ] &&
     [ "$main_worktree" != "[worktree-path]" ] &&
     [ -f "$main_worktree/$env_file" ] &&
     [ ! -f "[worktree-path]/$env_file" ]; then
    cp "$main_worktree/$env_file" "[worktree-path]/$env_file"
    echo "Copied $env_file from main checkout"
  fi
done

# Enhanced: Offer dev server startup
cd [worktree-path]

# Check if package.json exists
if [ -f package.json ]; then
  echo "Found package.json"
  echo ""
  echo "Dev server options:"
  echo "(a) Start dev server now (runs in background, on this worktree's own port)"
  echo "(b) Skip (I'll start it manually later)"
  echo "(c) Just point the browser at the main workspace's already-running server"

  # If user chooses (a):
  echo "Starting dev server in background..."
  npm run dev > dev-server.log 2>&1 &
  echo "Dev server started (PID: $!)"
  echo "Logs: tail -f dev-server.log"
fi