power-worktree

Work in an Isolated Workspace

Step 0 — You may already be isolated

Check before creating anything:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)
git rev-parse --show-superproject-working-tree

If GIT_DIR differs from GIT_COMMON and the third command prints nothing (you are not in a submodule, where the same difference appears for an unrelated reason), you are already in a worktree. Skip to Step 2.

Step 1a — Native tooling first

If your harness has its own worktree mechanism — an EnterWorktree tool, a /worktree command, a --worktree flag — use it.

Running git worktree add when a native tool exists is the most common mistake here: it creates a worktree the harness does not know about, so its own bookkeeping points at the old one, and everything after that is confusing in a way that is hard to trace back.

Step 1b — Fallback

Only if there is no native tool. Get consent first: this changes where the human's work happens.

Choose the location by priority: what the human specified, then an existing .worktrees/, then an existing worktrees/, then .worktrees/ as the default.

Check it is ignored before creating it:

git check-ignore -q .worktrees/ || echo "not ignored — add it to .gitignore first"
git worktree add .worktrees/<slug> -b <branch>

An un-ignored worktree directory turns the entire checkout into untracked noise inside the parent repository.

If git worktree add fails on permissions, you are probably in a sandbox that cannot write where you asked. Say so; do not retry with sudo or a path outside the repository.

Step 2 — Set it up

Install dependencies with the project's real command, read from its manifest. Copy the local environment files the project needs — except anything holding a secret, which the human provides.

Step 3 — Green baseline

Run the test suite before changing anything.

A baseline you did not take is a baseline you will invent later, and the first failure will look like yours whether it is or not. If the suite is already red, say so now and agree what "green" means for this work.