Git worktrees

Worktrees isolate branch changes without stashing or switching another checkout. Use one for concurrent writers or a task that needs its own checkout.

Choose the location

1. Follow the user's or project's worktree-location rule.
2. Otherwise use the repository's .worktrees/ directory.
3. For a directory inside the repository, verify the chosen directory is ignored before creating it. An ignored sibling directory is not evidence that this path is ignored.

directory="<selected-dir>"
git check-ignore -q "$directory/"

If the path is not ignored, add the required ignore entry before creating the worktree.

Create the checkout

Confirm the repository root, base revision, branch name, and destination. Do not replace an existing directory or change another checkout's state.

branch="<branch-name>"
base_ref="<base-ref>"
git worktree add "$directory/$branch" -b "$branch" "$base_ref"

After creation, confirm the new checkout's root, branch, and revision before editing.

Keep environments local

• Each worktree owns its mutable virtual environment, installed dependencies, and build outputs.
• Do not symlink or copy .venv, node_modules, vendor/bundle, target, or equivalent mutable directories from another checkout.
• Share download caches only when the package manager supports safe concurrent cache access.
• Use the project's declared manager and lockfile to create a fresh local environment when the required environment is missing.
• If a worktree already points to shared mutable state, stop before installing or testing. Propose replacing that link with a local environment without modifying its target.
• Before trusting tests or diagnostics, confirm project imports and source resolution point into this worktree. Editable installs and ancestor dependency lookup can resolve the original checkout even when manifests match.

Establish a baseline

Run the relevant existing checks within the approved task scope and runtime limits.

If a check fails before implementation, record its command, revision, and failure. Ask before continuing when the failure prevents meaningful verification. If a check cannot run, report it as unrun rather than treating an absent environment as a passing baseline.

Report the worktree path, branch, revision, environment state, and the checks actually performed.

Clean up after approval

After the user chooses cleanup, check the worktree is clean and its work is merged or otherwise preserved. Then remove it and use safe branch deletion:

git worktree remove <path>
git branch -d <branch-name>

If deletion is refused because work is unmerged, stop and report it. Never force deletion without explicit approval. Never delete or repair another worktree's environment during cleanup.

Completion

The requested worktree exists with verified identity and isolated mutable state, or the setup blocker is reported. Record unrun checks and the next authorized action.