viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(skill): refresh command matrix and failure modes

Browse source
This commit is contained in:
ZenchantLive 2026-03-03 19:08:58 -08:00
parent 53648852a3
commit 1880301e8b
2 changed files with 132 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

114
skills/beadboard-driver/references/command-matrix.md
View file

@ -1,41 +1,81 @@
# Command Matrix
## Bootstrapping and Handshake
- `node scripts/bb-init.mjs --register <name> --role <role> --json`
- Output: `{ ok, agent_id, mode, lease, timestamp }`
- `node scripts/bb-init.mjs --adopt <id> [--non-interactive] --json`
- Output: `{ ok, agent_id, mode, lease, timestamp }` or `{ ok:false, error }`
## Coordination Commands (`bb`)
- `bb agent register --name <agent> --role <role>`
- `bb agent activity-lease --agent <agent> [--json]`
- Output: `{ ok, command, data: AgentRecord }`
- `bb agent list [--role <role>] [--status <status>]`
- `bb agent show --agent <agent>`
- `bb agent send --from <agent> --to <agent> --bead <id> --category <HANDOFF|BLOCKED|DECISION|INFO> --subject <text> --body <text>`
- `bb agent inbox --agent <agent> [--state unread|read|acked] [--bead <id>]`
- `bb agent read --agent <agent> --message <message-id>`
- `bb agent ack --agent <agent> --message <message-id>`
- `bb agent reserve --agent <agent> --scope <path> --bead <id> [--ttl <minutes>] [--takeover-stale]`
- `bb agent release --agent <agent> --scope <path>`
- `bb agent status [--bead <id>] [--agent <agent>]`
## Lifecycle Commands (`bd`)
- `bd ready`
- `bd show <bead-id>`
- `bd update <bead-id> --status in_progress --claim`
- `bd update <bead-id> --notes "<evidence>"`
- `bd close <bead-id> --reason "<summary>"`
## Legacy/Internal Scripts
- `node skills/beadboard-driver/scripts/resolve-bb.mjs`
# Command Matrix
This matrix lists the operational command surface for the BeadBoard driver skill.
Day-to-day runbooks use `bd mail` delegation rather than direct low-level agent CLI invocations.
## Session and Identity
- `node skills/beadboard-driver/scripts/session-preflight.mjs`
- `node skills/beadboard-driver/scripts/generate-agent-name.mjs`
- `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`
- `bd create --title="Agent: <role-name>" --description="<agent scope>" --type=task --priority=0 --label="gt:agent,role:<orchestrator|ui|graph|backend|infra>"`
- `bd agent state <agent-bead-id> spawning`
- `bd agent state <agent-bead-id> running`
- `bd agent heartbeat <agent-bead-id>`
- `bd agent show <agent-bead-id>`
## Work Claim and Lifecycle
- `bd ready`
- `bd show <bead-id>`
- `bd update <bead-id> --status in_progress --assignee <agent-bead-id>`
- `bd slot set <agent-bead-id> hook <bead-id>`
- `bd update <bead-id> --notes "<evidence>"`
- `bd close <bead-id> --reason "<completion summary>"`
- `bd slot clear <agent-bead-id> hook`
## Mail and Coordination (`bd mail` delegated)
- `bd mail inbox`
- `bd mail send --to <agent-id> --bead <bead-id> --category <HANDOFF|BLOCKED|DECISION|INFO> --subject "<short>" --body "<details>"`
- `bd mail read <message-id>`
- `bd mail ack <message-id>`
Delegate setup and validation:
- `bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"`
- `export BB_AGENT=<agent-id>`
- `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`
## Dependency and Graph Control
- `bd dep <blocker-id> --blocks <blocked-id>`
- `bd dep add <blocked-id> <blocker-id>`
- `bd dep list <bead-id>`
- `bd dep tree <bead-id>`
- `bd dep cycles`
- `bd dep relate <issue-a> <issue-b>`
- `bd dep unrelate <issue-a> <issue-b>`
## Swarm and Molecule Operations
- `bd swarm validate <epic-id>`
- `bd swarm create <epic-id> [--coordinator <rig/address>] [--force]`
- `bd swarm status <swarm-id>`
- `bd swarm list`
- `bd mol show <formula-or-mol-id>`
- `bd mol pour <formula-id> --var key=value`
- `bd mol ready`
- `bd mol progress <mol-id>`
- `bd mol stale`
## Gates and Blocked Work
- `bd gate list`
- `bd gate list --all`
- `bd gate check`
- `bd gate check --type=bead`
- `bd gate show <gate-id>`
- `bd gate resolve <gate-id>`
## Comments and Audit Trail
- `bd comments <bead-id>`
- `bd comments add <bead-id> "<coordination note>"`
- `bd comments add <bead-id> -f <path-to-note-file>`
## Environment and Repair Helpers
- `node skills/beadboard-driver/scripts/resolve-bb.mjs`
- `node skills/beadboard-driver/scripts/readiness-report.mjs --checks <json> --artifacts <json>`
- `node skills/beadboard-driver/scripts/diagnose-env.mjs`
- `node skills/beadboard-driver/scripts/heal-common-issues.mjs [--project-root <path>] [--apply] [--fix-git-index-lock]`
- `node skills/beadboard-driver/scripts/ensure-project-context.mjs [--project-root <path>]`

82
skills/beadboard-driver/references/failure-modes.md
View file

@ -1,47 +1,75 @@
# Failure Modes
This document tracks high-impact coordination and environment failures for the BeadBoard driver skill.
## `BD_NOT_FOUND`
- Cause: `bd` missing from PATH.
- Recovery: install beads CLI or add `bd` executable directory to PATH.
- Signal: preflight or scripts fail with `BD_NOT_FOUND`.
- Cause: `bd` is not installed or not on `PATH`.
- Recovery:
- Install beads CLI.
- Re-open shell so `PATH` updates apply.
- Re-run `node skills/beadboard-driver/scripts/session-preflight.mjs`.
## `BB_NOT_FOUND`
- Cause: `BB_REPO` invalid or no `bb` command / cache / discovery hit.
- Signal: `resolve-bb.mjs` or `bb-mail-shim.mjs` reports bb command missing.
- Cause: global BeadBoard CLI not installed, or not discoverable.
- Recovery:
- Set `BB_REPO` to BeadBoard repo root.
- Verify `bb.ps1` exists under `BB_REPO`.
- Retry preflight.
- Install BeadBoard globally (`bb`/`beadboard` on `PATH`).
- Re-run `node skills/beadboard-driver/scripts/resolve-bb.mjs`.
- Re-run preflight.
## `NAME_GENERATION_EXHAUSTED`
## `MAIL_DELEGATE_MISSING` / `BD_MAIL_DELEGATE_NOT_SET`
- Cause: all generated names collided with existing registry entries.
- Signal: `bd mail ...` returns delegate-not-configured or shim not invoked.
- Cause: neither env delegate (`BEADS_MAIL_DELEGATE`/`BD_MAIL_DELEGATE`) nor `mail.delegate` config is set.
- Recovery:
- increase retry count (`BB_NAME_MAX_RETRIES`),
- expand adjective/noun pools,
- retry generation.
- `bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"`
- `export BB_AGENT=<agent-id>`
- `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`
## Reservation Conflicts
## `BB_MAIL_NOT_CONFIGURED`
- `RESERVATION_CONFLICT`: active owner exists.
- `RESERVATION_STALE_FOUND`: stale reservation exists; use takeover only when safe.
- `RELEASE_FORBIDDEN`: non-owner attempted release.
- Signal: `ensure-bb-mail-configured.mjs` fails contract checks.
- Cause: delegate points to wrong command, missing shim path, or invalid `BB_AGENT` context.
- Recovery:
- Run session preflight to re-apply expected delegate command.
- Set `BB_AGENT` explicitly.
- Validate with `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`.
## `DOLT_NOT_RUNNING`
- Signal: `bd` reads stale/fallback data, API routes return Dolt connection failures, or status checks report backend unavailable.
- Cause: Dolt SQL server not started for this workspace.
- Recovery:
- From repo root: `bd dolt start`
- Verify backend health before proceeding (`beadboard status --json` or project-specific health checks).
## `AGENT_HEARTBEAT_MISSED` (Witness liveness degradation)
- Signal: agent appears stale/dead in liveness surfaces after inactivity window.
- Cause: agent is not sending `bd agent heartbeat <agent-bead-id>` during active work.
- Recovery:
- Resume periodic heartbeat (typically every 30-120 seconds while active).
- Set explicit state transitions: `running` -> `working` -> `stuck|done|stopped`.
- If work was interrupted, post a coordination note/message before resuming.
## Mail Lifecycle Errors
- `UNKNOWN_SENDER` / `UNKNOWN_RECIPIENT`: register agents before send.
- `ACK_FORBIDDEN`: only recipient may ack.
- `MESSAGE_NOT_FOUND`: stale id or wrong message reference.
- `UNKNOWN_SENDER` / `UNKNOWN_RECIPIENT`: register agent identities before sending.
- `MESSAGE_NOT_FOUND`: incorrect message id or wrong inbox context.
- `ACK_FORBIDDEN`: only the message recipient can acknowledge.
## Local Workspace Repair Signals
- `GIT_INDEX_LOCK_PRESENT`: stale git lock blocks writes.
- Recovery:
- Confirm no active git process is still using the repo.
- Run `node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo> --apply --fix-git-index-lock`.
## Policy Guardrails
- Do not write `.beads/issues.jsonl` directly.
- Do not close beads without verification evidence.
- Do not bypass `BB_REPO` when it is set but invalid; fix it explicitly.
## Local Environment Repair Signals
- `GIT_INDEX_LOCK_PRESENT`: stale git lock can block local operations.
- Recovery:
- confirm no active git process is using the repository,
- run `node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo> --apply --fix-git-index-lock`.
- Do not close beads without fresh evidence.
- Do not bypass invalid `BB_REPO` values; fix configuration first.