| 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:
