boocode/data/skills/boocode/using-worktrees/SKILL.md

name: using-worktrees description: This skill should be used when starting work that may need isolation from the current checkout — parallel to something already in progress, risky or experimental, a hotfix interrupting other work, or a task that splits into independent mergeable units. Also when the user explicitly asks for a worktree. Examples: "try this risky refactor", "I need to fix prod while keeping this branch", "explore an alternate approach", "make a worktree for X".

Using Worktrees

Decide whether to isolate work in a git worktree, then create it correctly. The judgment — "does this need its own worktree?" — is the point of this skill; the mechanics are routine.

Asymmetry with committing (deliberate): when the heuristic clearly fires, just create the worktree — you have standing trust here. When it's ambiguous, propose it in one line and wait. This is unlike committing, which is always command-gated. Creating a worktree is cheap and reversible; making a commit is not, so the trust differs.

The WHEN heuristic (the core)

Just create (clear — no need to ask)

• Work that runs parallel to something already in progress (don't disturb the in-flight checkout).
• A risky / experimental / throwaway change you might want to discard cleanly.
• A hotfix that interrupts in-progress work (isolate the fix, leave the WIP untouched).
• Work that decomposes into independent mergeable units — one worktree per unit.
• Any task where the user would plausibly want it isolated from the main checkout.

Propose first (ambiguous — one line, then wait)

• Could-go-either-way on size or risk.
• Unsure whether the user wants isolation at all.
• A worktree that would overlap heavily with the work already on the main checkout (isolation buys little, may confuse).

State it in one line: "This looks risky/parallel — want me to do it in a worktree?" Then wait.

Skip (no worktree — work on the current checkout)

• Quick reads, questions about the repo, investigation.
• Small single-stream fixes with nothing to run in parallel.
• Anything where there's nothing to isolate and no parallelism to protect.

parallel / risky / hotfix-interrupting / decomposable  ->  just create
ambiguous size-or-risk / heavy overlap with current     ->  propose (1 line), wait
quick read / small single-stream / nothing to isolate   ->  skip, work in place

The HOW (mechanics)

• Branch from a stable base — the default branch (main/master), never from another feature branch. A worktree off a half-done branch inherits its instability.
• Branch name derived from the task — fix-session-delete-guard, not wip or tmp. No emojis.
• Collision-safe path — a unique dir outside the main checkout (e.g. a per-task or per-branch path), so two worktrees never share a directory.
• Run the project's setup after create — install deps / env / generate, if the project defines a setup step. A fresh worktree has the code but not the installed/generated state. (Some projects declare setup hooks; run whatever the project defines — don't assume the checkout is ready to run bare.)

Runtime isolation caveat

A worktree isolates code state, not execution state. Ports, databases, caches, lockfiles, and running services can still collide between worktrees. Don't assume a worktree means a fully isolated environment — if two worktrees both run the app, give each its own port / DB / service via per-worktree setup. Code isolation ≠ runtime isolation.

Lifecycle

• Worktrees persist — they are not auto-reaped. Leaving one around is fine; it's not litter.
• Reconcile via git, never automatically: review the worktree's diff against its base, then merge or archive on the user's decision. Do not auto-merge.
• Commit inside a worktree only on the user's command — defer to the committing-changes skill for the commit step (same rules: present-and-stop, never push).

DO-NOT

• Never branch from a non-stable base (another feature branch). Stable base only.
• Never auto-merge or auto-reconcile a worktree back. That's a reviewed decision.
• Never push (worktrees change nothing about the push rule — that stays the user's manual step).
• Never git worktree remove without the user's say. Worktrees persist; removing one can discard uncommitted work.
• No emojis in branch names.

Anti-patterns this skill avoids

• Asking permission for an obviously-isolated task (clear cases: just create).
• Creating a worktree for a quick read or a one-line fix (nothing to isolate).
• Branching the worktree off the messy in-progress branch instead of the stable base.
• Assuming a worktree gives runtime isolation and then colliding on a port or DB.
• Auto-removing or auto-merging a worktree the user hasn't reconciled.