name	Using Git Worktrees
description	Use this whenever you need to create an isolated workspace.

*CRITICAL* Add the following steps to your Todo list using TodoWrite:

Find the worktrees directory.

Check existing directories using the Bash tool: ls -d .worktrees 2>/dev/null
If not found, ask me for permission to create a .worktrees directory
If given permission, create .worktrees.

Verify .gitignore before creating a worktree using the Bash tool:

# Check if directory pattern in .gitignore
grep -qE '^(\.worktrees|worktrees)/$' .gitignore && echo "pattern found" || echo "pattern not found"

If not found, add the appropriate line to the .gitignore immediately.

Create the worktree

Come up with a good branch name based on the request.
Create the worktree with the Bash tool: `git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
cd into the newly created path with the Bash tool: cd $path

Auto-detect and run project setup.

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

# Clojure (deps.edn with Babashka task runner)
if [ -f deps.edn ] && [ -f bb.edn ]; then echo "Clojure project detected - deps fetched on first run"; fi

If there is no obvious project setup, you MUST ask me.

Run tests to ensure the worktree is clean.

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...
bb test          # Clojure (Kaocha via Babashka)

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Report ready.

Report Location

New working directory: <full-path>
Tests passing (<N> tests, 0 failures)
All commands and tools will now refer to: <full-path>

Understand that you are now in a new working directory. Your Bash tool instructions from here on out should refer to the worktree directory, NOT your original directory. This is ABSOLUTELY CRITICAL.
Remember: extra/ reference material is NOT in the worktree.

The extra/ directory (see @extra-reference-material skill) stays at the original project root. When you need reference material:

Project root: /home/user/project/
Worktree: /home/user/project/.worktrees/feature/
extra/ is at: /home/user/project/extra/ (NOT in the worktree)

Store the project root path mentally and use it for all extra/ lookups.

Maintaining Working Directory in Worktree

CRITICAL: Once you create and enter a worktree, you must stay within it for the entire session.

Rules:

Never use cd .. from within a worktree - It will eventually take you outside the worktree boundary
Always use absolute paths for commands - Use npm run lint from within the worktree, not cd .. && npm run lint
If you need to run root-level commands, use the full worktree path: cd .. && npm run lint npm run lint # (from worktree root)

cd /home/$USER/code/project/.worktrees/branch-name && npm run lint

Verify your location frequently:

pwd  # Should show .worktrees/branch-name in path
git branch  # Should show * on your feature branch, not main

If you accidentally exit the worktree:

Immediately recognize it (check if you're on main branch)
Navigate back: cd /full/path/to/.worktrees/your-branch
Verify: git branch should show your branch, not main

Red Flags:

Running git status and seeing "On branch main" when you should be on a feature branch
Running pwd and NOT seeing .worktrees/ in the path
Any cd .. command while in a worktree
Looking for extra/ inside the worktree path (it's at project root, not in worktree)

Clojure Projects (deps.edn + Babashka)

For Clojure projects using deps.edn and Babashka task runner:

Setup: No explicit dependency install needed - deps are fetched on first run.

Test commands (Kaocha via Babashka):

bb test - Run all tests across all suites
bb test :suite-name - Run a single test suite (check tests.edn for suite names)
bb test --help - Get test help
bb test --print-test-ids - List all tests
bb test --focus namespace-test - Focus on one test

Other tasks:

bb lint - Lint everything
bb lint dir1 dir2 - Lint specific directories
bb fmt - Format code

Quick Reference

Situation	Action
`.worktrees/` exists	Use it (verify .gitignore)
`.worktree/s does not exist	Check CLAUDE.md → Ask user
Directory not in .gitignore	Add it immediately
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install
`deps.edn` + `bb.edn` exist	Run `bb test` for tests

Common Mistakes

Skipping .gitignore verification

Problem: Worktree contents get tracked, pollute git status
Fix: Always grep .gitignore before creating project-local worktree

Assuming directory location

Problem: Creates inconsistency, violates project conventions
Fix: Follow priority: existing > CLAUDE.md > ask

Missing project installation

Problem: Tests and lint will fail, breaking the project
Fix: Always install the project when creating a new worktree

Proceeding with failing tests

Problem: Can't distinguish new bugs from pre-existing issues
Fix: Report failures, get explicit permission to proceed

Hardcoding setup commands

Problem: Breaks on projects using different tools
Fix: Auto-detect from project files (package.json, etc.)

Example Workflow

You: I'm using the Using Git Worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

Red Flags

Never:

Create worktree without .gitignore verification (project-local)
Skip baseline test verification
Proceed with failing tests without asking
Assume directory location when ambiguous
Skip CLAUDE.md check
Look for extra/ in worktree path (use project root)

Always:

Follow directory priority: existing > CLAUDE.md > ask
Verify .gitignore for project-local
Auto-detect and run project setup
Verify clean test baseline

Using Git Worktrees

Install Skill

SKILL.md