using-git-worktrees · diff
git:20260501.de63568 to git:20260501.92c6b1d
205 added, 28 removed. Audit A to A.
---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
---
- <skill>
+ # Using Git Worktrees
- <purpose>
- Create isolated git workspaces for feature work. Systematic directory selection + safety verification = reliable isolation.
- </purpose>
+ ## Overview
- <triggers>
- <rule>Use before executing implementation plans (required by subagent-driven-development and executing-plans).</rule>
- <rule>Use when starting feature work that needs isolation from current workspace.</rule>
- </triggers>
+ Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
- <warning level="soft">
- Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
- </warning>
+ **Core principle:** Systematic directory selection + safety verification = reliable isolation.
- <process>
- <step>**Directory selection** — Priority: (1) existing `.worktrees/` or `worktrees/` dir, (2) CLAUDE.md preference, (3) ask user: `.worktrees/` (project-local, hidden) or `~/.config/bearpaws/worktrees/{project}/` (global).</step>
- <step>**Safety verification** — For project-local dirs: `git check-ignore -q .worktrees`. If NOT ignored: add to .gitignore + commit immediately, then proceed. Global dirs need no verification.</step>
- <step>**Create worktree** — `git worktree add "{path}/{branch}" -b "{branch}"` → `cd` into it.</step>
- <step>**Run project setup** — Auto-detect: `package.json` → `npm install`, `Cargo.toml` → `cargo build`, `requirements.txt` → `pip install -r`, `go.mod` → `go mod download`.</step>
- <step>**Verify clean baseline** — Run test suite. If pass: report ready. If fail: report failures, ask whether to proceed.</step>
- </process>
+ **Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
- <rules>
- <rule>Never create project-local worktree without verifying it's git-ignored.</rule>
- <rule>Never skip baseline test verification.</rule>
- <rule>Never proceed with failing tests without asking.</rule>
- <rule>Follow directory priority — don't assume location when ambiguous.</rule>
- </rules>
+ ## Directory Selection Process
- ## Integration
+ Follow this priority order:
- **Called by:** bp:brainstorming (after design approved), bp:subagent-driven-development, bp:executing-plans.
- **Pairs with:** bp:finishing-a-development-branch (cleanup after work complete).
+ ### 1. Check Existing Directories
- </skill>
+ ```bash
+ # Check in priority order
+ ls -d .worktrees 2>/dev/null # Preferred (hidden)
+ ls -d worktrees 2>/dev/null # Alternative
+ ```
+
+ **If found:** Use that directory. If both exist, `.worktrees` wins.
+
+ ### 2. Check CLAUDE.md
+
+ ```bash
+ grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+ ```
+
+ **If preference specified:** Use it without asking.
+
+ ### 3. Ask User
+
+ If no directory exists and no CLAUDE.md preference:
+
+ ```
+ No worktree directory found. Where should I create worktrees?
+
+ 1. .worktrees/ (project-local, hidden)
+ 2. ~/.config/bearpaws/worktrees/<project-name>/ (global location)
+
+ Which would you prefer?
+ ```
+
+ ## Safety Verification
+
+ ### For Project-Local Directories (.worktrees or worktrees)
+
+ **MUST verify directory is ignored before creating worktree:**
+
+ ```bash
+ # Check if directory is ignored (respects local, global, and system gitignore)
+ git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+ ```
+
+ **If NOT ignored:**
+
+ Per Jesse's rule "Fix broken things immediately":
+ 1. Add appropriate line to .gitignore
+ 2. Commit the change
+ 3. Proceed with worktree creation
+
+ **Why critical:** Prevents accidentally committing worktree contents to repository.
+
+ ### For Global Directory (~/.config/bearpaws/worktrees)
+
+ No .gitignore verification needed - outside project entirely.
+
+ ## Creation Steps
+
+ ### 1. Detect Project Name
+
+ ```bash
+ project=$(basename "$(git rev-parse --show-toplevel)")
+ ```
+
+ ### 2. Create Worktree
+
+ ```bash
+ # Determine full path
+ case $LOCATION in
+ .worktrees|worktrees)
+ path="$LOCATION/$BRANCH_NAME"
+ ;;
+ ~/.config/bearpaws/worktrees/*)
+ path="~/.config/bearpaws/worktrees/$project/$BRANCH_NAME"
+ ;;
+ esac
+
+ # Create worktree with new branch
+ git worktree add "$path" -b "$BRANCH_NAME"
+ cd "$path"
+ ```
+
+ ### 3. Run Project Setup
+
+ Auto-detect and run appropriate setup:
+
+ ```bash
+ # 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
+ ```
+
+ ### 4. Verify Clean Baseline
+
+ Run tests to ensure worktree starts clean:
+
+ ```bash
+ # Examples - use project-appropriate command
+ npm test
+ cargo test
+ pytest
+ go test ./...
+ ```
+
+ **If tests fail:** Report failures, ask whether to proceed or investigate.
+
+ **If tests pass:** Report ready.
+
+ ### 5. Report Location
+
+ ```
+ Worktree ready at <full-path>
+ Tests passing (<N> tests, 0 failures)
+ Ready to implement <feature-name>
+ ```
+
+ ## Quick Reference
+
+ | Situation | Action |
+ |-----------|--------|
+ | `.worktrees/` exists | Use it (verify ignored) |
+ | `worktrees/` exists | Use it (verify ignored) |
+ | Both exist | Use `.worktrees/` |
+ | Neither exists | Check CLAUDE.md → Ask user |
+ | Directory not ignored | Add to .gitignore + commit |
+ | Tests fail during baseline | Report failures + ask |
+ | No package.json/Cargo.toml | Skip dependency install |
+
+ ## Common Mistakes
+
+ ### Skipping ignore verification
+
+ - **Problem:** Worktree contents get tracked, pollute git status
+ - **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+ ### Assuming directory location
+
+ - **Problem:** Creates inconsistency, violates project conventions
+ - **Fix:** Follow priority: existing > CLAUDE.md > ask
+
+ ### 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 ignored - git check-ignore confirms .worktrees/ is ignored]
+ [Create worktree: git worktree add .worktrees/auth -b feature/auth]
+ [Run npm install]
+ [Run npm test - 47 passing]
+
+ Worktree ready at /Users/jesse/myproject/.worktrees/auth
+ Tests passing (47 tests, 0 failures)
+ Ready to implement auth feature
+ ```
+
+ ## Red Flags
+
+ **Never:**
+ - Create worktree without verifying it's ignored (project-local)
+ - Skip baseline test verification
+ - Proceed with failing tests without asking
+ - Assume directory location when ambiguous
+ - Skip CLAUDE.md check
+
+ **Always:**
+ - Follow directory priority: existing > CLAUDE.md > ask
+ - Verify directory is ignored for project-local
+ - Auto-detect and run project setup
+ - Verify clean test baseline
+
+ ## Integration
+
+ **Called by:**
+ - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+ - **subagent-driven-development** - REQUIRED before executing any tasks
+ - **executing-plans** - REQUIRED before executing any tasks
+ - Any skill needing isolated workspace
+
+ **Pairs with:**
+ - **finishing-a-development-branch** - REQUIRED for cleanup after work complete