Worktree Isolation

---
name: worktree-isolation
description: Isolates work in a sibling git worktree, then merges and cleans up. Use to keep a change out of the main checkout or when parallel tracks collide.
---
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# Worktree Isolation

Isolate a unit of work in a sibling Git worktree. Ordinary Git is sufficient;
`basicly worktree` is an optional provisioning and landing convenience.
It covers placement, provisioning, merge and cleanup.
For tracker records see `work-tracker`. For commits see the git reference of `cli-tools` and `conventional-commits`.

## Rules

- **Isolate every non-trivial change.** This includes multi-file work, work that runs the gates, and work parallel to another track.
- **Skip isolation for a trivial edit, such as a typo.** A worktree has a real setup cost.
- **Put the worktree at the sibling path `<repo>.worktrees/<name>`.** The sibling checkout stays outside repository scans. Git hooks share the common Git directory regardless of checkout placement.
- **Avoid accidental hook bypasses.** A relative `core.hooksPath` can silently skip hooks. For explicit user-requested observer repair, use a command-scoped bypass, run affected checks directly and disclose what did not run. Never disable hooks permanently.
- **Resolve conflicts against the whole task intent.** Inspect both changes, preserve unrelated work and rerun affected checks; do not restart the plan merely because branches coupled.
- **Run merge commands from the base checkout.** Git refuses to update a branch that another worktree has checked out.

## Protected destinations

An agent sandbox can allow source edits while protecting `.codex`, `.agents` or the Git hook directory.
Install and landing preflight planned changes before updating the catalog, committing tracker state or rebasing.
An access refusal names the destination and the ordinary command to retry; unchanged protected outputs need no write.

For an already-authorized upgrade or landing, request task-scoped execution review for that exact command in the named checkout.
In Codex, use the execution tool's `require_escalated` permission with the protected destination as the reason.
The CLI cannot escalate itself. Preserve dotenv denials, normal hooks, signing and loop checkpoints; do not broaden a machine profile.
Read the retry result and verify the repository state before continuing the loop.

## Create and finish a worktree

```sh
basicly worktree create <name> [--base <branch>]           # add and provision
basicly worktree list                                       # active sessions; stale ones are marked
basicly worktree merge <name> --bead <id> [--mode M]        # rebase, verify, --no-ff merge
basicly worktree merge-queue <name>:<id> ... [--mode M]     # merge several, in the given topological order
basicly worktree cleanup <name> [--force]                   # remove the worktree and its merged branch
```

Use `create` when the work commits: it provisions `.venv`, `node_modules` and the hooks, and a plain `git worktree add` leaves them missing, so the first commit fails. A plain `git worktree add ../<repo>.worktrees/<name> -b <branch>` suits read-only work.

Inspect existing branches and worktrees first; do not replace or discard another session's work. Integrate from the base checkout and preserve shared tracker history.

For each lifecycle step, cleanup refusals, how hooks resolve in a linked worktree and the Claude Code background isolation setting, read [lifecycle](references/lifecycle.md).