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. Resolve the port before checking it:

# Resolve this checkout's port: a project script if it has one
# (scripts/worktree-port.cjs), else the port recorded in .claude/launch.json.
# No fallback: guessing 3000 would report the main checkout's server as this one's.
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)"
fi

if [ -z "$PORT" ] || [ "$PORT" = "undefined" ]; then
  echo "No port recorded for this worktree; assign one (below) before checking for a server"
elif DEV_SERVER_PID=$(lsof -ti:"$PORT"); [ -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

configurations[0] assumes the dev server is the first entry. If launch.json lists Storybook or an API first, read the dev server's entry instead.

If the project has no per-worktree port yet, give each new worktree its own before starting a server — otherwise every worktree's npm run dev fights over the same port. A manual way: pick a free port per worktree and pass it to the dev server (PORT=3101 npm run dev, or the framework's port flag), or derive one from the worktree path:

PORT=$((3100 + $(pwd | cksum | cut -d' ' -f1) % 900))

Record the port in .claude/launch.json so later sessions resolve the same one.

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

3. Post-Creation Checklist

After worktree created:

## Worktree Setup Complete

### Created
- Path: [worktree-path]
- Branch: [branch-name]
- Base: [base-branch]

### Next Steps

#### Before Starting Work
- [ ] Verify dev server is running
      Resolve this worktree's own port first: `node scripts/worktree-port.cjs`
      (if the project has it) or the port in `.claude/launch.json`, then `lsof -ti:$PORT`
      or visit `http://localhost:$PORT`

- [ ] Install dependencies if needed
      If package-lock.json changed: `npm install`

- [ ] Confirm ignored local env files are present
      Copy `.env.local` / `.env.*.local` from the main checkout if missing;
      never commit them. Make sure any API keys the project needs server-side
      are available before testing anything that calls a real service.

- [ ] Run tests to establish baseline
      `npm test` to verify clean state

#### During Development
- [ ] NEVER kill or restart another worktree's dev server
- [ ] Run tests in separate terminal
- [ ] Apply 3-attempt limit for failing tests

#### After Completing Work
- [ ] Run full validation - script names are examples; use the project's own
      and skip any it does not define
      `npm run lint && npm run type-check && npm test`

- [ ] Create PR or merge
      Use `pr-review-fix-pipeline` or manual merge

- [ ] Clean up worktree when done
      `git worktree remove [path]` (only after merged!)

### Quick Commands

```bash
# Navigate to worktree
cd [worktree-path]

# Check this worktree's dev server (resolve $PORT first, see above)
lsof -ti:$PORT

# Start dev server (if needed) — resolves this worktree's own port automatically
npm run dev

# Run tests (don't kill the dev server!)
npm test

# Create PR when ready: fill the repo's PR template, don't use --fill
gh pr create --body-file [filled-pr-template.md]

## Dev Server Protection Rules

Critical rules:

**NEVER:**
- Kill another worktree's dev server during test runs
- Run commands that stop a dev server you didn't start
- Restart a dev server unnecessarily
- Force multiple worktrees onto the same port

**ALWAYS:**
- Resolve this worktree's own port before checking or starting anything
- Run tests in a separate process from the dev server
- Verify changes against the server for THIS worktree, not a stale one from the main tree or another worktree
- Ask user if unclear about dev server state

## Worktree Naming Convention

Naming conventions:

**For issue work:**

../[project-name]-issue-[NUMBER] Branch: issue-[NUMBER]-develop

**For feature work:**

../[project-name]-feature-[NAME] Branch: feature/[NAME]

**For bug fixes:**

../[project-name]-fix-[NAME] Branch: fix/[NAME]

## Integration with Other Skills

### Batch processing

When working on multiple issues in parallel, create a worktree per issue:
```bash
git worktree add ../[project]-issue-123 -b issue-123-develop develop
git worktree add ../[project]-issue-145 -b issue-145-develop develop

# Give each worktree its own port (see Dev Server Awareness) — then start a
# dev server in either or both

With test-fix

In worktree context:

1. Verify dev server running (this worktree's own port)
2. Run failing test
3. Apply 3-attempt limit
4. Never kill the dev server during debugging

With pr-review-fix-pipeline

After work complete in worktree:

1. Push worktree branch
2. Create PR
3. Run `pr-review-fix-pipeline` on the PR
4. Auto-fixes applied
5. Merge when ready
6. Clean up worktree

Example Workflow

Starting New Issue

User: set up a worktree for issue 123

Claude: Creating worktree for new work.

What are you working on?
(a) GitHub issue number
(b) Feature name
(c) Bug fix name
(d) Custom branch name

User: a

Claude: Issue number?

User: 123

Claude: [Checks main checkout's dev server]

Main checkout dev server running on port 3000 (PID: 12345)

Creating worktree:
- Path: ../[project]-issue-123
- Branch: issue-123-develop
- Base: develop

[Creates worktree, copies .env.local from the main checkout]

Worktree created. This worktree's own port: 3247 (derived from its path, as above).

Dev server options:
(a) Start a dev server for this worktree on port 3247
(b) Just use the main checkout's server on 3000 for now

User: a

Claude: Dev server started on port 3247 (PID: 12401)

[Presents post-creation checklist]

Ready to start work!

Multiple Worktrees (Batch Processing)

User: Create worktrees for issues 123, 145, 167

Claude: Creating 3 worktrees for parallel work...

Creating worktrees:
1. ../[project]-issue-123 (issue-123-develop) -> port 3247
2. ../[project]-issue-145 (issue-145-develop) -> port 3512
3. ../[project]-issue-167 (issue-167-develop) -> port 3089

Each worktree gets its own port, so there's no collision — start a dev
server in any or all of them.

All 3 worktrees created.

You can now work on all 3 issues in parallel without conflicts.

Cleanup After Work

When work is merged:

# Verify branch is merged
git branch --merged | grep issue-123-develop

# Remove worktree
git worktree remove ../[project]-issue-123

# Delete branch (if safe)
git branch -d issue-123-develop

Safety check before removal:

Before removing worktree:
- [ ] Verify PR is merged or changes are committed
- [ ] Check for uncommitted changes: `git status`
- [ ] Confirm no valuable work will be lost

Proceed with removal? (y/n)

Notes

• Dev server protection is intentional — killing another worktree's server mid-test throws away its state and can mask real failures. Always verify against the port for the worktree you're actually in, not whatever happens to be running on 3000.
• TodoWrite checklist keeps track of worktree state across a session