Manage Isolated Git Workspaces

This skill sets up isolated Git worktree workspaces that share the same repository, letting work proceed on multiple branches simultaneously without switching. Its core principle is systematic directory selection plus safety verification for reliable isolation, and it announces itself at the start of use.

Directory selection follows a strict priority order: first check for existing .worktrees (preferred, hidden) or worktrees directories - if both exist, .worktrees wins; then check CLAUDE.md for a stated worktree-directory preference via grep and use it without asking if found; only if neither exists does it ask the user to choose between a project-local .worktrees/ or a global ~/.config/superpowers/worktrees/<project-name>/ location.

Safety verification differs by location. For project-local directories, it must verify the directory is git-ignored with git check-ignore before creating a worktree; if it is not ignored, per "Jesse's rule" of fixing broken things immediately, it adds the appropriate line to .gitignore, commits the change, and only then proceeds - this prevents accidentally committing worktree contents to the repository. Global directories need no such check since they sit entirely outside the project.

Creation follows five steps: detect the project name from git rev-parse --show-toplevel; determine the full worktree path based on the chosen location and create it with git worktree add "$path" -b "$BRANCH_NAME", then cd into it; auto-detect and run project setup (npm install for package.json, cargo build for Cargo.toml, pip install -r requirements.txt or poetry install for Python, go mod download for go.mod); verify a clean baseline by running the project's test command (npm test, cargo test, pytest, go test ./...) and reporting failures for the user to decide whether to proceed or investigate; and finally report the worktree's full path, test results, and readiness to implement the target feature.

A quick-reference table maps situations to actions (e.g. both .worktrees/ and worktrees/ existing resolves to .worktrees/; a not-ignored directory means add-to-gitignore-and-commit; failing baseline tests mean report-and-ask; missing package.json/Cargo.toml means skip dependency install). Common mistakes flagged: skipping ignore verification (worktree contents get tracked and pollute git status - always check-ignore first), assuming the directory location instead of following the existing-then-CLAUDE.md-then-ask priority, proceeding with failing tests without permission (can't distinguish new bugs from pre-existing ones), and hardcoding setup commands instead of auto-detecting from project files. Red flags to never do: create a worktree without verifying it's ignored, skip baseline test verification, proceed with failing tests without asking, assume the directory location when ambiguous, or skip the CLAUDE.md check.

Use whenever isolated workspace setup is needed for parallel branch work. It is called by the brainstorming skill's Phase 4 (required once a design is approved and implementation follows) and by any skill needing an isolated workspace; it pairs with finishing-a-development-branch (required for cleanup once work is complete) and with executing-plans or subagent-driven-development, which do their actual work inside the created worktree.

Input is a target branch name and, implicitly, the current repository's existing worktree-directory conventions or CLAUDE.md preference. Output is a ready worktree at a reported full path, with project dependencies installed and a clean test baseline confirmed, or failures reported for a decision on how to proceed.

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Git worktrees themselves; project-specific setup and test tooling it auto-detects (npm, Cargo, pip/poetry, Go modules); and companion skills brainstorming, finishing-a-development-branch, executing-plans, and subagent-driven-development.

Developers or coding agents that need an isolated, verified-clean workspace for a new branch without disrupting their existing working directory - especially before starting implementation work that pairs with a structured planning or execution skill.