viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
beadboard/skills/beadboard-driver/references/failure-modes.md
zenchantlive 1ae7efb31b feat(skills): formalize agent coordination via beadboard-driver 
We moved from ad-hoc task claims to a strictly defined 'Skill' system.

Triumphs:
- Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff).
- This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine.
- Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future.

Raw Honest Moment:
Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
2026-02-14 00:23:41 -08:00

1.1 KiB
Raw Blame History

Failure Modes

BD_NOT_FOUND

  • Cause: bd missing from PATH.
  • Recovery: install beads CLI or add bd executable directory to PATH.

BB_NOT_FOUND

  • Cause: BB_REPO invalid or no bb command / cache / discovery hit.
  • Recovery:
    • Set BB_REPO to BeadBoard repo root.
    • Verify bb.ps1 exists under BB_REPO.
    • Retry preflight.

NAME_GENERATION_EXHAUSTED

  • Cause: all generated names collided with existing registry entries.
  • Recovery:
    • increase retry count (BB_NAME_MAX_RETRIES),
    • expand adjective/noun pools,
    • retry generation.

Reservation Conflicts

  • RESERVATION_CONFLICT: active owner exists.
  • RESERVATION_STALE_FOUND: stale reservation exists; use takeover only when safe.
  • RELEASE_FORBIDDEN: non-owner attempted release.

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.

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.