worktrees

name	worktrees
version	1.0
last_updated	2026-08-06T00:00:00.000Z
id	worktrees
one_line_purpose	Do all feature work in isolated git worktrees.
entry_point	docs/skills/worktrees/SKILL.md
category	meta
mcp_compliance_level	partial
optimization_status	draft
status	active
dependencies	[]
tags	["git","worktrees","workflow","agents"]
description	Covers the worktree helper script, branch naming, and cleanup so the main checkout stays clean. Use before starting any change, or when the main checkout is dirty or on a stale branch.
metadata	{"type":"procedure","source-of-truth":[".github/scripts/worktree.sh",".github/scripts/install-hooks.sh",".gitignore"]}

Worktrees

Use when

• Starting any change that is not a one-line fix on testing.
• The main checkout is dirty, on a stale feature branch, or holds another task's work in progress.
• Running an agent: every agent session gets its own worktree so concurrent sessions cannot collide in the same working tree.

Do not use when

• You are already inside a linked worktree. Check first:

[[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]] && echo "already isolated"

The contract

The main checkout at the repository root stays on testing or main with a clean tree. All feature work happens in .worktrees/<slug>, branched from projectbluefin/testing.

Two mechanisms enforce this:

• .worktrees/ is gitignored. A nested .git directory stages as a gitlink and silently corrupts history, so it must never be tracked.
• The pre-push hook refuses to push a feature branch from the main checkout, and refuses any remote outside the projectbluefin org. Install it once after cloning with bash .github/scripts/install-hooks.sh.

Procedure

Create a worktree. The branch is always cut from a freshly fetched projectbluefin/testing, never from whatever the main checkout happens to be sitting on:

bash .github/scripts/worktree.sh new fix/my-thing
cd .worktrees/fix-my-thing

Work, validate, and push from inside the worktree:

just check && pre-commit run --all-files
git push projectbluefin fix/my-thing

Clean up after the PR merges:

bash .github/scripts/worktree.sh done fix/my-thing

Housekeeping

List every worktree with its PR state:

bash .github/scripts/worktree.sh list

Remove all worktrees whose PRs are merged or closed. Dirty worktrees are skipped, never discarded: