worktree-hygiene - SKILL.md Agent Skill

name: worktree-hygiene description: Reap merged git worktrees and branches safely across the warp, codex, opencode, and conductor harnesses. Use when worktrees pile up, after a branch merges, when cleaning up `git worktree list`, removing an orphaned or detached worktree, or deciding whether a worktree is safe to delete. Not for creating branches or authoring commits (use the git skill). metadata: author: epicenter version: '1.0'

Worktree Hygiene

Related Skills: git for branch creation, staging, and commit messages. standalone-commits for reviewable units. pull-request for merge strategy.

Four harnesses (warp, codex, opencode, conductor) mint worktrees here and nothing reaps them, so they accumulate. The cure is to reap on close: when a branch lands, remove its worktree and delete the branch in the same motion. This skill is the safe procedure for doing that, one-off or as a periodic sweep.

The reap signal (and the trap)

"Branch merged" is not sufficient to reap. A merged branch routinely carries live uncommitted edits in its working tree; removing it with --force destroys that work. The real signal is:

reap = (branch fully contained in origin/main)  AND  (working tree clean OR only throwaway dirt)

Use git merge-base --is-ancestor <branch> origin/main for containment: if true, every commit on the branch is in origin/main, which is airtight even when the branch sits on a stacked base. git cherry origin/main <branch> shows unmerged commits (+ lines).

Audit procedure

Fetch first if origin/main is stale, then classify every worktree:

cd <main-checkout>; base=origin/main
git worktree list --porcelain | awk '/^branch /{print $2}' | sed 's#refs/heads/##' | while read b; do
  [ -z "$b" ] && continue
  ahead=$(git cherry "$base" "$b" 2>/dev/null | grep -c '^+')
  if git merge-base --is-ancestor "$b" "$base" 2>/dev/null; then st="MERGED"; else st="$ahead unmerged"; fi
  printf "%-50s %s\n" "$b" "$st"
done

For each MERGED worktree, check its working tree with git -C <path> status --porcelain (no output = clean). Inspect dirty file lists before deciding: lockfile-only churn is throwaway; modified source or unique untracked files are real work. Detached-HEAD worktrees have no branch line; test their tip with git merge-base --is-ancestor <sha> origin/main.

Decide per worktree

merged + clean                 -> reap: git worktree remove <path>; git branch -d/-D <branch>
merged + throwaway dirt only   -> reap: git worktree remove --force <path>; git branch -d/-D <branch>
detached + merged + clean      -> reap: git worktree remove <path>   (no branch to delete)
merged + REAL uncommitted work -> preserve. Branch or commit the work first; do not reap.
detached + REAL uncommitted    -> anchor before anything: git -C <path> switch -c holding/<name>
unmerged commits               -> leave alone (active work)

Reaping is destructive: gate it

git worktree remove and git branch -d are destructive (AGENTS.md: destructive actions need approval). For a sweep, present an approve-list of exact commands grouped by tier before running any of them. Never reap on a self-reported "it's merged"; run the audit yourself.

git branch -d refuses unless the branch is merged into the current HEAD. If local main lags origin/main, it will refuse a branch that is merged only on the remote; -D is then justified by the merge-base --is-ancestor origin/main proof.
git worktree remove can fail with Directory not empty when ignored files (node_modules, .DS_Store) remain. It still de-registers the worktree. Finish with git worktree prune then rm -rf <path>.
The harnesses spawn and mutate worktrees continuously, even mid-sweep. Re-run the audit at the end; treat reaping as ongoing discipline, not a one-time event.

Repo-specific worktree gotchas

git stash is shared across all worktrees here. A bare git stash/stash pop can grab another worktree's entry. Prefer explicit branches; avoid stash.
Animal-named warp branches are stacked on unmerged bases, cut from whatever was checked out rather than clean origin/main. Before opening a PR from one, run git diff --stat origin/main...HEAD and confirm scope; unrelated work rides along otherwise.
Verify HEAD before committing in a worktree (git rev-parse --abbrev-ref HEAD). A handoff may claim a "fresh worktree on branch X" that does not exist; these stay checked out on the base branch itself.

Invariant: one owner per worktree

Each worktree and branch has a single owner (the harness/agent that created it). Do not reap or commit into a worktree you do not own without confirming it is abandoned; a clean-looking tree may belong to a live session.

Final checks

Re-run the audit; confirm reaped paths are gone with git worktree list.
git worktree prune to clear stale registrations.
Confirm any anchored holding/* branches still hold their edits.