---
name: "using-git-worktrees"
description: "Ensure feature work happens in an isolated workspace before it starts - detects existing isolation, creates a git worktree or native isolated workspace, sets up the project, and verifies a clean baseline. Use before executing an implementation plan or starting anything that should not disturb the current working tree. Triggers: start a new feature, work on this separately, set up a branch for this, isolate this work, spin up a worktree."
---

Ensure work happens in an isolated workspace. Prefer this environment's native worktree/branch tools if any exist. Fall back to manual git worktrees only when no native tool is available.

**Core principle:** detect existing isolation first, then use native tools, then fall back to git. Never fight the harness.

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

## Step 0: Detect Existing Isolation
Before creating anything, check whether you're already in an isolated workspace:
```
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
```
Submodule guard: `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," check `git rev-parse --show-superproject-working-tree` — if it returns a path, you're in a submodule, treat as a normal repo.

If `GIT_DIR != GIT_COMMON` (and not a submodule): you're already in a linked worktree — skip to Step 2. Report: "Already in isolated workspace at `<path>` on branch `<name>`" (or note detached HEAD, externally managed, if applicable).

If `GIT_DIR == GIT_COMMON` (or in a submodule): normal repo checkout. If the user hasn't already stated a worktree preference, ask for consent:
> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
If declined, work in place and skip to Step 2.

## Step 1: Create Isolated Workspace
**1a. Native tools (preferred):** if this environment already provides a way to create an isolated workspace/worktree (a tool, command, or flag), use it and skip to Step 2. Native tools handle directory placement, branch creation, and cleanup automatically — using raw `git worktree add` when a native tool exists creates phantom state the harness can't see or manage.

**1b. Git worktree fallback (only if no native tool exists):**
Directory selection priority: 1) any directory preference the user has already stated, 2) an existing project-local worktree directory (`.worktrees` preferred over `worktrees` if both exist), 3) default to `.worktrees/` at the project root.
Safety check: `git check-ignore -q .worktrees` (or `worktrees`) — if NOT ignored, add to `.gitignore` and commit that change first.
Create it:
```
path="$LOCATION/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
```
Sandbox fallback: if `git worktree add` fails with a permission error, tell the user the sandbox blocked worktree creation and that you're working in the current directory instead; run setup/baseline tests in place.

## Step 2: Project Setup
Auto-detect and run appropriate install: `npm install` (package.json), `cargo build` (Cargo.toml), `pip install -r requirements.txt` / `poetry install` (Python), `go mod download` (go.mod).

## Step 3: Verify Clean Baseline
Run the project's tests. If they fail, report failures and ask whether to proceed or investigate first. If they pass, report ready:
```
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```

## Common Mistakes
Fighting the harness (using raw git worktree when native isolation exists). Skipping detection (creating a nested worktree inside an existing one). Skipping ignore verification (worktree contents get tracked). Assuming directory location instead of following the priority order. Proceeding with failing tests without asking.

## Red Flags
Never: create a worktree when Step 0 already detects isolation, use raw git worktree commands when a native tool is available, skip straight to 1b without checking 1a, create a project-local worktree without verifying it's gitignored, skip baseline test verification, proceed with failing tests without asking.
Always: run Step 0 detection first, prefer native tools, follow the directory priority order, verify gitignore for project-local worktrees, auto-detect and run project setup, verify a clean test baseline.