beads-orchestration

Beads Orchestration

Superskill router for the Beads issue-execution fleet. Six 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; a looper loads the one execution subskill its mode runs).

Discover subskills

PKG="$(dirname "<absolute-path-to-this-SKILL.md>")"
find "$PKG/subskills" -maxdepth 2 -name SKILL.md
rg -n "^name:|^description:" "$PKG"/subskills/*/SKILL.md

Resolve every bundled scripts/ and references/ path from the absolute location of the SKILL.md the runtime loaded. A dispatched worker's cwd is its worktree in the target repository, not this package, so a bare relative path resolves against the wrong tree.

Routing table

Task intent	Subskill	Typical trigger
Run the unattended loop: rank ready issues finish-first, claim, dispatch workers, reconcile outcomes; one or several coordinators per tracker. Owns lifecycle writes for its dispatched owners.	subskills/beads-coordinator/SKILL.md	"while true, tackle the next issue", "keep N workers processing the backlog", "run a second coordinator on the same backlog"
Run this session as one self-paced lane with no central coordinator: implement mode claims, works, verifies, and retains a bounded outcome through packages and corrections; review mode independently reviews packages and reports to their owners. Several loopers share one tracker.	subskills/beads-looper/SKILL.md	"/loop through the ready queue", "run this pane as a beads lane", "be the review lane for the other panes"
Implement one cohesive delivery package (one or several beads); requires anchor ISSUE_ID and WORKTREE_PATH.	subskills/beads-worker/SKILL.md	Dispatched with a worker contract for one delivery package
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. looper vs. worker: if the request is to process the backlog, route to the coordinator — never start implementing issues yourself — unless it asks for a self-paced lane, a /loop, one of several independent panes, or no central coordinator: route that to the looper, which is its own coordinator for one lane. 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).

Delivery model

Execution defaults to persistent bounded-outcome owners using the existing looper; coordinated runs use the same model with a small allocation/recovery controller. Read references/delivery-model.md for package units, branch choice, claims, review, evidence and recovery. This replaces per-bead branch/PR/review ceremonies; it does not bypass repository integration policy.

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. With several coordinators, each mutates only the beads it holds, under its own --actor id. A looper is a coordinator for exactly the beads it holds. 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.
• Implementation worktrees use .worktrees/parallel-agents/<anchor> on agent/<anchor>; independent review snapshots use review/<review-id>.
• .beads/ is Dolt-backed and gitignored — never commit it to code branches.
• Build artifacts follow the package. Reuse one target across package commits. Retain receipts needed for evidence/recovery, then delete retired build targets after verified completion or published handoff. A PR opening or one member closing is not permission to delete unfinished or unpublished package work.
• bd has no --rig flag: target another project with bd -C <path> ….
• Execute the governing contract. Use the proportional work-allocation contract to establish scope and acceptance; a formal spec is required only where the work or repository requires one. Respect existing doctrine/specs and route unresolved scope, architecture, trust, or authorization through its real gate.
• Finish outcomes before starting new ones. The coordinator ranks ready work so a pool of lanes completes a few epics instead of half-building many (subskills/beads-coordinator/scripts/rank_ready_work.py). Reports count merged outcomes and name partial ones; bead, PR, and commit counts are activity, not delivery.
• 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; cache first. All subskills follow references/token-efficiency.md. Lanes over fan-out: one long-lived session works through a chain of beads that share context, one at a time, rides autocompaction, and keeps its cache warm, instead of spawning a fresh cold worker per bead. Tracking beads retain individual claims/acceptance; a package shares branch, PR and independent review. Also: project JSON through jq, route gate output to files, run targeted tests before the full gate's one run per tree (in the tier the repo's test-scope policy assigns it), and keep one model per lane. Load it once per session before the first bd/gh query loop.
• Quality gates travel with the work. beads-worker and beads-pr-reviewer-worker share references/craft-and-care-gate.md (the repo-defined execution-quality bar) and references/test-growth-gate.md (one gate species per behavior, a Tests: +a ~b -c delta in every PR). Load them at the subskill's first edit or first finding, not at dispatch.
• Finish on a report, not a question. A dispatched subskill ends only in its defined report (a terminal status, or the shaping writer's returned bead text), never mid-task on a plan, a promise, or a "shall I". It decides what references/decision-autonomy.md lets it decide; only an external or hard-gated blocker is reported as blocked. The coordinator ends at its frontier stop, an owner stop, or a tracker fault it cannot recover. Every report is written for a reader who has not seen the session.
• The owner's instructions outrank skill defaults. A direct instruction from the human owner or operator (not a dispatching agent), or the target repo's AGENTS.md / CLAUDE.md, overrides this package's defaults: lane count, routing, cadence, model tier. It does not lift mutation authority, worktree isolation, exact-head review, or the hard gates in references/decision-autonomy.md. When one of those pauses work, name the rule and its file in the report.

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>' <this package>/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.