workspace-hygiene
Use this plugin whenever an agent needs an isolated Git checkout, hands work to another session,
or audits old linked worktrees. It contributes the worktree skill generated by the public
beyond10x/worktree CLI.
The executable remains a separately installed Rust tool:
cargo install --git https://github.com/beyond10x/worktree --tag 0.4.0 b10x-worktree-cli
worktree activate --profile <profile.toml> --workspace <workspace-root>
worktree doctor --check
The skill teaches agents to create trees outside the primary repository collection, maintain live
session leases, and publish wanted commits before finishing. Cleanup is review-bound: inspect
worktree gc --repo <primary> --dry-run, then pass only ids from that review to
worktree gc --repo <primary> --apply --id <reviewed-id>. Dirty, locked, live, local-only,
offline, unmanaged, and out-of-policy trees are retained.
Worktree 0.4.0 adds worktree inspect --repo <primary> for actual Git state, storage,
ignored files, leases and retention blockers. It defaults to one repository; use --workspace
to inspect the wider profile. Add --refresh for current remote recovery evidence. Inspection
does not infer story completion or authorize removal.
When the host does not run hooks, the agent explicitly acquires and renews its lease, then releases its own lease before finishing. After verification, it preserves useful evidence and removes only its own reproducible build output. Each session ends with verified cleanup or an explicit handoff that names the retained tree, published commit, blockers and next owner.
Use worktree reconcile --repo <primary> --dry-run for interrupted provisioning, adopted legacy
paths, finished external trees, and already-missing records. Apply only exact reviewed ids. An
interrupted removal keeps durable recovery proof, while a missing Active record without matching
intent remains refused. External retirement additionally requires the explicit
--allow-external-retirement acknowledgement.
For a finished external legacy tree stranded by stale pre-0.3 relocation intent, act only when the
reconciliation dry-run itself proposes retire-external. Worktree requires the exact source and
HEAD to agree and the intended destination to be absent; a cross-device or ambiguous-relocation
refusal is not permission to reinterpret or clear the state by hand.
The plugin contains no cleanup script and no independent policy copy. Update the source CLI and run
worktree skill --out plugins/workspace-hygiene/skills/worktree to refresh the shared Codex and
Claude-compatible guidance.