git:20260501.92c6b1d to git:20260929.1297711

29 added, 206 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

+ description: Use when starting feature work that needs isolation from the current workspace, or before executing an implementation plan

---

- # Using Git Worktrees

- ## Overview

- Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

- **Core principle:** Systematic directory selection + safety verification = reliable isolation.

- **Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."

- ## Directory Selection Process

- Follow this priority order:

- ### 1. Check Existing Directories

- ```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.

+ <skill>

- [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]

+ <purpose>

+ Create isolated git workspaces for feature work. Systematic directory selection + safety verification = reliable isolation.

+ </purpose>

- Worktree ready at /Users/jesse/myproject/.worktrees/auth

- Tests passing (47 tests, 0 failures)

- Ready to implement auth feature

- ```

+ <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>

- ## Red Flags

+ <warning level="soft">

+ Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

+ </warning>

- **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

+ <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>

- **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

+ <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>

- ## Integration

+ ## 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

+ **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).

- **Pairs with:**

- - **finishing-a-development-branch** - REQUIRED for cleanup after work complete

+ </skill>