---
name: using-git-worktrees
description: Set up an isolated workspace before feature work, preferring native platform worktree tools with a manual git worktree fallback. Use before executing implementation plans or any work that should not touch the current checkout. Not for writing the plan itself: use writing-plans. Not for task execution mechanics: use subagent-driven-development after the workspace exists.
license: MIT
metadata:
  author: TechTide AI (Alex Cinovoj)
  provenance: rewritten from patterns in obra/superpowers (MIT)
  category: Methodology & Process
---

# Using Git Worktrees

Feature work happens in an isolated workspace so the user's checkout stays untouched. Order of preference: detect isolation you already have, use a native worktree tool, fall back to manual `git worktree` last. Never fight the harness.

## Step 0: Detect existing isolation

Before creating anything:

```bash
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)
git rev-parse --show-superproject-working-tree 2>/dev/null
```

- `GIT_DIR != GIT_COMMON` and the third command prints nothing: you are already in a linked worktree. Skip to Step 2. Do not nest another worktree.
- Third command prints a path: you are in a submodule, not a worktree. Treat as a normal checkout.
- `GIT_DIR == GIT_COMMON`: normal checkout. If the user has not already stated a worktree preference, ask: "Want me to set up an isolated worktree? It protects your current branch." Honor a declared preference without re-asking. If they decline, work in place and skip to Step 2.

## Step 1: Create the workspace

**1a. Native tool first.** If the platform provides a worktree mechanism (a tool named like `EnterWorktree`, a `/worktree` command, a `--worktree` flag), use it and go to Step 2. Native tools handle placement, branch creation, and cleanup; running `git worktree add` alongside one creates phantom state the harness cannot see.

**1b. Git fallback, only when no native tool exists.**

Directory priority: explicit user preference, then an existing `.worktrees/` (wins over `worktrees/` if both exist), then default to `.worktrees/` at the project root.

Verify the directory is ignored before creating anything in it:

```bash
git check-ignore -q .worktrees || { echo ".worktrees/" >> .gitignore && git add .gitignore && git commit -m "chore: ignore worktrees dir"; }
```

Then create and enter:

```bash
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
cd ".worktrees/$BRANCH_NAME"
```

If creation fails on a sandbox permission error, say so and work in the current directory instead; still run Steps 2 and 3 in place.

## Step 2: Project setup

Detect and install: `package.json` gets `npm install` (or the repo's manager), `Cargo.toml` gets `cargo build`, `requirements.txt` gets `pip install -r`, `pyproject.toml` gets the project's tool, `go.mod` gets `go mod download`. No manifest, no install.

## Step 3: Verify a clean baseline

Run the project's test command. All green: report "Worktree ready at <path>, N tests passing, ready to implement <feature>." Failures: report them and ask whether to proceed or investigate first. Without a clean baseline you cannot tell your bugs from pre-existing ones.

## Good vs bad

**Bad:** Platform exposes `EnterWorktree`, agent runs `git worktree add ../feature-x` anyway. The harness does not know the directory exists; cleanup never happens; the next session finds a stale phantom worktree on a stale branch.

**Good:** Agent detects a normal checkout, sees `EnterWorktree` is available, uses it, runs `npm install`, runs the suite, reports "142 tests passing, ready to implement".

## Verification

After setup, run `git rev-parse --git-dir` and `git rev-parse --git-common-dir`. Expect different paths (linked worktree) or an explicit user decision to work in place. Then run `git status --short` from the main checkout. Expect no worktree files appearing as untracked. If they appear, the worktree directory is not ignored: fix `.gitignore` before any commits happen.

## Completion checklist

- [ ] Step 0 detection ran before any creation
- [ ] Native tool used when available; git fallback only otherwise
- [ ] User consent or declared preference honored
- [ ] Worktree directory verified ignored (fallback path)
- [ ] Dependencies installed per the repo's manifest
- [ ] Baseline tests run; failures reported before proceeding

Any box unchecked: not done. Fix or say so.

## Footguns

- **Nested worktrees.** Creating a worktree while already inside one. Step 0 exists to prevent exactly this; run it every time, including after session resumes.
- **Submodule false positive.** Submodules also have `GIT_DIR != GIT_COMMON`. Without the superproject check you will misreport isolation and skip creating a workspace you actually need.
- **Untracked worktree pollution.** A project-local worktree directory that is not git-ignored dumps hundreds of files into `git status` and, worst case, into a commit. Check-ignore first, always.
- **Building on a red baseline.** If tests fail before you start, every later failure is ambiguous. Get an explicit go-ahead before working on top of failures.