beads-orchestration

name	beads-orchestration
description	Use for any Beads (`bd`) issue workflow in a Beads-backed repository — coordinating unattended execution of ready issues across parallel workers, implementing a single dispatched issue in a worktree, handling PR-review follow-up tasks, reconciling stale worker/PR/worktree state, or creating and decomposing backlog issues. Route to exactly one subskill per task.
metadata	{"owner":"tze","authors":["tze","OpenAI Codex"],"status":"active","last_reviewed":"2026-07-18"}
compatibility	Requires bd (beads) CLI v1.0.4+, git, and a Beads-backed repository. Execution subskills additionally require gh (authenticated), jq, python3, and git worktree support.

Beads Orchestration

Superskill router for the Beads issue-execution fleet. Five subskills live under subskills/; each is a complete standard skill package (own SKILL.md, references/, scripts/). Subskills are not installed in the global skill catalog — discover them lazily from this package, and load at most one subskill body per task (the coordinator may additionally point dispatched workers at a second one; the workers load it themselves).

Discover subskills

find "$(dirname "$SKILL_PATH")/subskills" -maxdepth 2 -name SKILL.md
rg -n "^name:|^description:" subskills/*/SKILL.md

Routing table

Task intent	Subskill	Typical trigger
Run the unattended loop: select ready issues, claim, dispatch workers, reconcile outcomes. Owns ALL bd lifecycle mutations.	subskills/beads-coordinator/SKILL.md	"while true, tackle the next issue", "keep N workers processing the backlog"
Implement exactly one Beads issue; requires ISSUE_ID and WORKTREE_PATH from a coordinator or operator.	subskills/beads-worker/SKILL.md	Dispatched with a worker contract for one implementation bead
Process one pr-review-task bead: triage threads, report corrections to the implementation lane, attest exact-head merge readiness.	subskills/beads-pr-reviewer-worker/SKILL.md	Dispatched with a pr-review-task bead for an open GitHub PR
Reconcile stale worker state, PR-review bookkeeping, and orphaned worktrees before dispatching new work.	subskills/beads-cleanup/SKILL.md	Coordinator preflight; recovery after a crashed loop; "clean up stale beads state"
Create or decompose backlog issues: features, bugs, epics, grooming, vague ask → actionable beads.	subskills/beads-writer/SKILL.md	"file beads for X", "break this epic down", backlog grooming

Routing rules

• Coordinator vs. worker: if the request is to process the backlog, route to the coordinator — never start implementing issues yourself. Route to a worker subskill only when a coordinator/operator has already supplied the worker contract (ISSUE_ID, WORKTREE_PATH).
• Cleanup is a preflight, not a loop: the coordinator invokes it before its first cycle; route to it directly only for explicit recovery/audit asks.
• Writer is standalone: backlog creation needs no worktrees and no coordinator; it never dispatches execution.
• Fallback: if the task is Beads-adjacent but none of the rows fit (e.g. one-off bd queries, project prioritization), do not load a subskill — use plain bd commands or a dedicated skill such as th-projects (project-direction subskill).

Shared invariants (all subskills)

• During an execution run, the coordinator is the sole mutation authority for canonical lifecycle state (bd create/update/dep/close); dispatched workers and cleanup report instead of mutating. The standalone beads-writer may create/update/depend backlog items during explicit authoring before dispatch, but hands mutation authority to the coordinator once execution starts.
• Worktrees live at .worktrees/parallel-agents/<id> on branch agent/<id>.
• .beads/ is Dolt-backed and gitignored — never commit it to code branches.
• bd 1.0.4 has no --rig flag: target another project with bd -C <path> ….
• Decide, don't defer. Engineering-judgment choices are resolved autonomously per references/decision-autonomy.md; blocking on a human is reserved for its hard-gate list. Load that file before filing or reconciling any decision-shaped blocker.
• Spend tokens like money. All subskills follow references/token-efficiency.md: project JSON output through jq to needed fields, route verbose gate output to files and read only failures, iterate on targeted tests before the single full gate, and right-size worker models. Load it once per session before the first bd/gh query loop.

When bd itself misbehaves

On any unexpected bd error (connection failures, unknown flags, refused mutations, weird exit states), consult references/known-errors.md before debugging from scratch — it catalogs known errors, deprecations, and workarounds. Search it instead of reading it whole: run rg -i -n '<distinctive error text>' references/known-errors.md, then read only the matching section (fall back to skimming the headers via rg -n '^##' … if the search misses). If you hit a rough edge that is not listed, append an entry after resolving it: that file is this skill's persistent memory, and an unrecorded fix gets re-debugged by the next session.