write-manual

Using Git Worktrees

Put the work in an isolated workspace and write down where it is. A worktree nobody recorded is a worktree the next turn loses — and lost workspaces are how commits end up on main.

One mechanism: the native EnterWorktree tool. It creates the worktree, switches this session into it, and lets the harness manage cleanup. Reaching for git worktree add while that tool exists creates a workspace the harness cannot see — that is the mistake this skill exists to prevent. Invoking this skill is the project instruction EnterWorktree asks for.

Step 0 — already isolated?

git rev-parse --git-dir --git-common-dir --show-toplevel
git branch --show-current
git rev-parse --show-superproject-working-tree   # non-empty ⇒ submodule, not a worktree

Different git-dir and git-common-dir (and not a submodule) means you are already in a linked worktree. Do not create another — record it (Step 2) and go to Step 3.

Otherwise you are in a normal checkout. CLAUDE.md workflow rule 5 — a run is implemented in a worktree — is the consent; do not stop to ask for it again. Ask only if the user has said otherwise in this session, and if they decline isolation, work in place: create a feature branch first if HEAD is on main/master, then record it with Step 2's block anyway — worktree pointing at this checkout. Skipping the record leaves the run without a workspace, which breaks resuming and blocks stage=finish later.

Step 1 — create it

Before creating it, make sure the spec and plan are committed. The worktree branches from your current local HEAD (worktree.baseRef: "head" in settings.json — with the harness default "fresh" it would branch from origin/<default> and contain neither). Uncommitted, they are absent from the branch the run builds on and from its history, and the spec is not there for anyone reading the branch later.

Also before creating it, confirm the worktree directory is ignored — in the main checkout, which is where an unignored worktree directory shows up in git status and where git add -A would stage it as an embedded repository. Run this in the main checkout, as is:

mkdir -p .claude/worktrees && git check-ignore -q .claude/worktrees || { echo '.claude/worktrees/' >> .gitignore && git add .gitignore && git commit -m "chore: ignore worktrees"; }

The mkdir makes the directory exist, so check-ignore answers correctly; the commit lands on HEAD before the branch is cut, so the worktree contains it.

Call EnterWorktree with a name derived from the work (feat/json-export). It creates the worktree under .claude/worktrees/, switches this session into it, and lets the harness handle cleanup.

Fallback, only if EnterWorktree is unavailable: git worktree add .worktrees/<branch> -b <branch> (same ignore check), and then EnterWorktree with path pointing at it — that is what moves this session's cwd into the worktree. Skip that and every subagent inherits the main checkout's directory while the run believes it is isolated. If creation fails on a sandbox permission error, say so and work in place.

Step 2 — record the workspace

~/.claude/hooks/flow-state set stage=isolate worktree=. branch=. base=HEAD

flow-state resolves the three literals itself, from the current directory: worktree=. is the toplevel, branch=. the current branch, base=HEAD the SHA. Run it from inside the worktree.

If that prints "no run state", nobody opened the run: flow-state init <task-slug> and re-run the block. An unrecorded workspace is one a resumed session cannot find.

Recording is what turns the workspace from something remembered into something the tooling can act on: from here on every subagent is told which tree to read (a SubagentStart hook injects it), a second workspace is refused, and "kontynuuj" in a fresh session finds the tree again. base is the branch's starting commit, which the whole-branch review reads instead of guessing a merge base.

On a detached HEAD, record the worktree and note that a branch has to be created at finish time.

Step 3 — setup and clean baseline

Install what the project needs with its own package manager, then run the test suite and the build. Tests alone can pass on a tree that does not build: a config that resolves from the main checkout (a tsconfig.json extends) needs the main checkout's dependencies installed too.

Tests must be green before your changes exist — otherwise you cannot tell your bugs from the ones you inherited. If they fail, report the failures and ask whether to proceed or investigate.

Record that it happened, so a resumed run does not pay for the install and the full suite twice — and so nothing infers "baseline done" from the workspace being recorded, which happens one step earlier:

~/.claude/hooks/flow-state task 0 done "baseline green: <result>"

Report: worktree path, branch, test result, and what you are about to implement.

Never

• Create a worktree when Step 0 already found one — including any subagent creating its own. Subagents read the tree they are given.
• Use git worktree add when EnterWorktree is available.
• Start implementation on main/master without explicit consent.
• Skip the baseline run, or proceed past failing baseline tests silently.