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.mdskills/beads-operations/SKILL.md
GitHubBeads 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
beadsplugin 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
references/conventions.md— the mandatory setup:--shared-server, the shared Dolt server, port 3308,--skip-agents, env vars, thebdshell wrapper.references/workflows.md— the core loop, compaction recovery, discovered-from side-quests.references/troubleshooting.md— symptom → diagnosis → recovery for the nasty states.references/long-term-maintenance.md— version pin/bump, server lifecycle, backup/export, db hygiene, compaction.references/prime-customization.md— whatbd primeinjects, howbd setup claudewires the SessionStart/PreCompact hooks, the flag/config matrix, thePRIME.mdoverride + resolution order, git-state modes, Joe's neutral PRIME.md, and the un-gunkify runbook.
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).