| name | beads-cleanup |
| description | Use when a Beads coordinator needs to reconcile stale worker state, PR-review bookkeeping, or orphaned worktrees before dispatching new work. |
| metadata | {"owner":"tze","authors":["tze","OpenAI Codex"],"status":"active","last_reviewed":"2026-04-12"} |
| compatibility | Requires a Beads-backed git repository with `bd`, `git`, `gh`, `jq`, and git worktree support. Authenticated GitHub access is required for PR reconciliation and branch cleanup. |
Beads Cleanup
Run this skill before a beads-coordinator loop when stale worker state may
have been left behind by crashes, compaction, out-of-token exits, or missed
handoffs.
This skill is a read-heavy reconciliation pass. It repairs Beads metadata and
git artifacts; it does not implement code, dispatch workers, or invent new
workflow rules.
Use This Skill When
- starting or resuming a
beads-coordinator loop
- recovering after a crashed coordinator or killed worker
- auditing stuck
in_progress, blocked, pr-review, or review-running
state
- cleaning orphaned coordinator worktrees or branches tied to Beads issues
Do Not Use This Skill When
- implementing the assigned issue itself
- performing normal ready-work selection or worker dispatch
- creating new beads for discovered work
- repairing GitHub review threads inside an active PR review worker
Source Of Truth
This skill is a routing layer over the existing Beads operating model.
- Repository workflow and ownership model:
../../../../../README.md
- Coordinator mutation authority, atomic claim, and stall-heartbeat rules:
../beads-coordinator/references/runtime-and-safety.md
- Coordinator loop and PR-review lane behavior:
../beads-coordinator/references/coordinator-loop.md
- PR-review worker closure boundary and review-lock vocabulary:
../beads-pr-reviewer-worker/SKILL.md
If these sources disagree with this skill, fix this skill. Do not let cleanup
become a competing doctrine.
Non-Negotiable Boundaries
- Never implement code.
- Never mutate a bead held by a live actor. Decide ownership by the bead's
assignee plus a fresh stall heartbeat, per
../beads-coordinator/references/runtime-and-safety.md.
- Never mutate PR-review bead state from PR outcome. Cleanup does not run
bd close / reopen / PR-driven label changes in response to a PR being
MERGED or CLOSED. It inspects PR state and reports the finding plus a
recommended action; the coordinator's Step 0 is the sole PR-state mutator.
- Cleanup retains ownership of worktree / branch / Dolt hygiene and stale
review-running lock release (a liveness repair, not PR-state
reconciliation — see Pass 5b/Pass 6 in local-state-reconciliation.md).
- Never create new beads from cleanup. Missing wiring should be reported for the
coordinator loop to self-heal.
- Never touch
.beads/dolt/ manually.
- Append notes for every bead mutation so later operators can see what cleanup
changed and why.
- Inspect token-efficiently (
../../references/token-efficiency.md): project
every bd/gh listing through jq to the fields the pass needs, batch
related checks into one composite command, and keep the final report to
findings and mutations — not raw command output.
Load Only The Reference You Need
Workflow
- Read
../beads-coordinator/references/runtime-and-safety.md if you need the
exact claim, stall-heartbeat, and mutation-authority rules before touching
Beads state.
- Run the relevant passes from the reference files in order, skipping mutation
when evidence is incomplete or a bead is held by a live actor (fresh
heartbeat). For PR-review beads, run detection only and report findings.
- Keep canonical PR metadata on the original implementation bead only; review
beads must not invent their own
external_ref.
- Clean worktrees and branches conservatively. Preserve anything that may still
contain useful unpublished work.
- Produce the structured report from
references/reporting.md so the
coordinator has a clear mutation ledger before dispatch begins.
