beads-operations

Use when running, maintaining, or troubleshooting beads (`bd`) day-to-day — deciding bd vs TodoWrite, Joe's shared-server conventions (`bd init --shared-server --skip-agents`, the shared Dolt server o

SKILL.md

GitHub

Beads operations

Opinionated guidance for running beads the way Joe does, plus a troubleshooting/maintenance runbook. For the exhaustive command reference, use the working-with-beads skill.

Precedence: This skill supersedes the conventions in the bundled third-party beads plugin skill. Where they differ (especially server setup), follow this skill. The plugin is kept for its lifecycle hooks, commands, and task-agent — not its convention guidance.

Decision: bd vs TodoWrite

Ask "will I need this context in 2 weeks / across sessions?" — yes → bd (durable, dependency-aware, survives compaction); no → TodoWrite (this-hour working copy). They layer: read a bead → spin up TodoWrite items for the current hour → update the bead's notes → TodoWrite is discarded, the bead persists.

Reference map

BeadBoard (the dashboard on top of bd)

When bd work is coordinated through BeadBoard (Joe's multi-agent dashboard): the agent-side operating contract — the Iron Law, the session lifecycle, mail, evidence — is the beadboard-driver skill. Running its macOS launchd services (the :3000 dashboard, the daemon), the dashboard HTTP API, the Dolt↔JSONL sync, and the verify-sync.sh diagnostic is the beadboard-operations skill. Neither replaces this skill's bd conventions; they layer on top.

When beads is broken

Go straight to references/troubleshooting.md. Do not improvise schema/server fixes — beads' shared-server states have specific recoveries, and guessing makes them worse.

Taming bd prime

The session-start "Beads Workflow Context / SESSION CLOSE PROTOCOL" preamble is emitted by bd prime, wired as a SessionStart (and PreCompact) hook by bd setup claude — not bd hooks install. It ships a conservative "don't push without explicit authority" git policy and is easily duplicated across project + global settings.json. To change the wording, neutralize the policy, dedupe the hooks, or understand the flags / PRIME.md override and its resolution order, see references/prime-customization.md.

Niche features

Chemistry/molecules, async gates, worktrees, swarm, federation — not duplicated here. See working-with-beads/references/cli/ (mol.md, gate.md, worktree.md, swarm.md, federation.md).