From agent-skills
Use when running, operating, or troubleshooting the BeadBoard dashboard and its macOS launchd services — `com.beadboard.dashboard` (Next.js UI on :3000), `com.beadboard.daemon`, install.sh/uninstall.sh, the dashboard HTTP API, the Dolt↔JSONL sync architecture (`export.auto`, the `.beads/issues.jsonl` file-watcher), the `verify-sync.sh` diagnostic, env vars (`BEADS_DOLT_SHARED_SERVER`, `BEADS_DOLT_SERVER_PORT`, `BB_AGENT`), service file paths, and the operating/maintenance runbooks. Invoke on "dashboard won't start", "beadboard service", "launchctl beadboard", "is BeadBoard running", "verify-sync", "JSONL drift", "kickstart the dashboard", "EADDRINUSE on 3000". This is the ops/infra layer. For the agent-side coordination contract (the Iron Law, session lifecycle, mail categories, agent states, evidence flow) use `beadboard-driver`; for day-to-day `bd` conventions/troubleshooting use `beads-operations`; for the shared Dolt server internals use `working-with-dolt`.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-skills:beadboard-operationsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The **ops / infrastructure** layer for [BeadBoard](https://github.com/jordanhindo/beadboard) — how it runs as always-on macOS launchd services on Joe's machine. This skill mirrors the docs from the [beadboard-ops](https://github.com/joeblackwaslike/beadboard-ops) repo (the operational glue: launchd units, install/uninstall scripts, and driver-skill wiring; it does not fork BeadBoard itself).
references/architecture/components/beads-cli.mdreferences/architecture/components/daemon.mdreferences/architecture/components/dashboard.mdreferences/architecture/components/dolt-server.mdreferences/architecture/components/driver-skill.mdreferences/architecture/data-flow.mdreferences/architecture/dolt-integration.mdreferences/architecture/system-overview.mdreferences/installation.mdreferences/integration/agent-integration.mdreferences/integration/dashboard-api.mdreferences/integration/launchd-services.mdreferences/integration/plugin-surface-area.mdreferences/overview.mdreferences/prerequisites.mdreferences/reference/cli-commands.mdreferences/reference/environment-variables.mdreferences/reference/file-paths.mdreferences/reference/verify-sync.mdreferences/runbooks/maintenance.mdThe ops / infrastructure layer for BeadBoard — how it runs as always-on macOS launchd services on Joe's machine. This skill mirrors the docs from the beadboard-ops repo (the operational glue: launchd units, install/uninstall scripts, and driver-skill wiring; it does not fork BeadBoard itself).
Two layers, two skills. BeadBoard splits cleanly:
- Agent coordination contract (the Iron Law, the 9-step session lifecycle, mail categories, agent states, evidence) → the
beadboard-driverskill. This skill does not duplicate it.- Operations / infrastructure (services, dashboard, daemon, Dolt↔JSONL sync, diagnostics, runbooks) → this skill.
| Unit | What | Logs |
|---|---|---|
com.beadboard.dashboard | Next.js 15 dashboard on :3000 (KeepAlive, auto-restart) | /tmp/beadboard-dashboard.{log,err} |
com.beadboard.daemon | Execution daemon (RunAtLoad one-shot, forward-compatible stub) | /tmp/beadboard-daemon.{log,err} |
com.beads.shared-dolt-server | Shared Dolt SQL server on :3308 (managed separately) | ~/.beads/shared-server/dolt-server.log |
launchctl list | grep beadboard # 2 units, exit code 0
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000 # -> 200
launchctl kickstart -k gui/$(id -u)/com.beadboard.dashboard # force-restart dashboard
tail -f /tmp/beadboard-dashboard.err # dashboard boot errors
./bin/verify-sync.sh # audit Dolt <-> JSONL across all projects
All files in references/ are auto-fetched from the beadboard-ops repo (website/docs/) and freshness-stamped (source/fetched_at/sha256). Re-sync with make update-beadboard-operations.
Start here
Architecture
references/architecture/system-overview.md — component map, data flow, the two-CLI (bd/bb) modelreferences/architecture/data-flow.md — the 8-step bead lifecycle; the dual-write (Dolt + JSONL) patternreferences/architecture/dolt-integration.md — export.auto, the JSONL-as-notification-channel design, drift prevention, the sync audit/remediationbeads-cli · dashboard · daemon · dolt-server · driver-skillIntegration
references/integration/launchd-services.md — the three LaunchAgents, KeepAlive/RunAtLoad choices, wrapper scripts, launchctl lifecyclereferences/integration/dashboard-api.md — the dashboard's HTTP API surface (agents, beads, runtime, swarm, missions, SSE)references/integration/agent-integration.md — the agent session protocol (cross-reference; the contract itself lives in beadboard-driver)references/integration/plugin-surface-area.md — where plugins/MCP/hooks could extend BeadBoardReference
references/reference/cli-commands.md — bd/bb/launchctl/ops-script command indexreferences/reference/environment-variables.md — BEADS_DOLT_SHARED_SERVER, BEADS_DOLT_SERVER_PORT, BB_AGENT, launchd env (~/.zshenv, not ~/.zshrc)references/reference/file-paths.md — repos, Dolt data dir, plists, skill symlinks, per-project .beads/references/reference/verify-sync.md — the sync diagnostic: columns, sync statuses, exit codes, remediationRunbooks
references/runbooks/operating.md — day-to-day: health checks, restarts, live logs, tracked projects, agent status, port conflictsreferences/runbooks/maintenance.md — diagnostics: "dashboard won't start" tree, exit codes, EADDRINUSE/MODULE_NOT_FOUND/nvm, Dolt locks, upgrades, dolt_gc()beadboard-driver — the agent-side operating contract (Iron Law, session lifecycle, mail, evidence). Use it when an agent is executing work through BeadBoard; use this skill when you're operating the infrastructure underneath it.beads-operations — Joe's bd conventions (shared-server setup, the ready→claim→note→close loop) and the bd-level troubleshooting runbook.working-with-beads — the exact bd CLI reference at the pinned version.working-with-dolt — the dolt CLI + the shared dolt sql-server runbook (port 3308) that this skill's services depend on.npx claudepluginhub joeblackwaslike/agent-marketplace --plugin agent-skillsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.