RonanCodes/skills/worktree

worktree — don't clobber another agent's working tree

Multiple agents work the local factory at once. Two agents in the same working tree corrupt each other's edits. The fix: a per-repo lock pool of worktrees. You take a free slot, work there, hand it back when you've pushed.

The protocol

# 1. Before touching a repo that might be busy, take a slot:
path="$(ro worktree acquire)"      # prints the path; stderr says which slot
cd "$path"

# 2. Do your work on your own branch (never main):
git checkout -b feat/whatever
# … edit, commit, run the local gate, push, open PR, squash-merge …

# 3. ALWAYS release when you've pushed and you're done:
ro worktree release

acquire locks the first free slot: main (the primary checkout) if free, else an existing Greek worktree (<repo>-beta, -gamma, …), else it creates the next Greek one off origin/main. release (run from inside the slot, or pass the slot name) frees it and marks pushed: true.

Releasing is load-bearing. If you don't release, the slot stays busy and the pool fills up. The only safety net is TTL reaping (RO_WT_TTL, default 6h) via ro worktree reap — don't rely on it.

State

• Lock file: <main-checkout>/.ro/worktree-locks.json (gitignored; ro adds .ro/ to .gitignore automatically).
• Label yourself with RO_AGENT=<name> so ro worktree status shows who holds what.
• ro worktree status prints the whole pool; ro worktree reap frees stale slots.

When to use

• Told "X is being worked on" → acquire a slot instead of editing the primary tree.
• Any unattended/parallel run (/ro:planner-worker, /ro:night-shift, /ro:swarm) touching a shared repo.
• Pairs with /ro:ship (do the work in the acquired slot, ship from there, then release).

reap — two distinct cleanups

There are two populations of stale worktrees, and they need different handling:

1. Stale lock-pool slots (the Greek <repo>-beta/-gamma worktrees that an agent acquired but never released). Freed by the existing TTL reaper:

   ro worktree reap          # frees pool slots past RO_WT_TTL (default 6h)
   

2. Orphaned worktree directories left by subagent runs: .claude/worktrees/agent-*, .swarm/worktrees/*, ns/* worktrees, etc. These are NOT pool slots, so ro worktree reap never touches them, and they pile up (a 2026-06-14 sweep found ~65 across factory/adhd-helper/dataforce/nutmeg). Reap the COMPLETED ones with the bundled script:

   python3 "$(dirname "$0")/scripts/reap-orphans.py" --dry-run   # current repo, preview
   python3 "$(dirname "$0")/scripts/reap-orphans.py"             # current repo, remove
   python3 "$(dirname "$0")/scripts/reap-orphans.py" --all       # scan ~/Dev for all repos
   

What "completed" means (squash-merge safe)

A worktree is removed ONLY if all three hold: clean working tree, nothing unpushed (@{u}..HEAD is empty), AND its remote branch is gone. The remote-branch-gone test is the load-bearing one: every repo here squash-merges, so a merged branch does NOT look merged by commit ancestry (git branch --merged is useless), but a branch that was deleted on merge (standard squash + --delete-branch) is a true "purpose complete" signal. Anything dirty, unpushed, or whose remote branch still exists is KEPT and reported (it is real or in-flight work, never silently deleted). Agent/tooling state (.swarm/, .nightshift/, .ralph/, .claude/RESUME.md) is excluded from the dirty check so it never blocks a reap.

Automatic cleanup (the real fix)

reap is the safety-net sweep. The primary mechanism is that a worker removes its OWN worktree the moment it merges — one git worktree remove in the worker/merger Definition of Done in /ro:planner-worker and /ro:night-shift. Orphans only exist because a run crashed, was capped, or skipped that step.

Run it periodically (locally)

Worktrees are local to this machine, so a cloud /schedule cron CANNOT reap them. Run reap-orphans.py --all locally instead, via either:

• /ro:day-shift (recommended): the morning routine runs locally and already opens the day, so it reaps completed orphans as its first step.
• a Mac launchd weekly job, or a SessionStart hook for the eager option.