viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
beadboard/skills/beadboard-driver/SKILL.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

2.6 KiB
Raw Blame History

name description
beadboard-driver Drive BeadBoard agent workflows with strict preflight, per-session unique agent identity, and evidence-backed closeout. Use when handling bead lifecycle work that combines bd status commands with bb agent coordination (register/list/show, send/inbox/read/ack, reserve/release/status), especially in multi-agent sessions where path resolution, collision avoidance, and verification discipline are required.

Beadboard Driver

Overview

Use this skill to run repeatable bd + bb workflows without drift. Resolve bb safely, generate a unique session identity, coordinate with reservations/mail, and produce closeout evidence before claiming completion.

Core Workflow

  1. Run preflight:
node skills/beadboard-driver/scripts/session-preflight.mjs
  1. Generate a unique per-session agent name:
node skills/beadboard-driver/scripts/generate-agent-name.mjs
  1. Register identity, then claim bead:
& "$env:BB_REPO\bb.ps1" agent register --name <agent-name> --role <role>
bd update <bead-id> --status in_progress --claim
  1. Coordinate during implementation:
& "$env:BB_REPO\bb.ps1" agent reserve --agent <agent-name> --scope "<path-glob>" --bead <bead-id>
& "$env:BB_REPO\bb.ps1" agent send --from <agent-name> --to <peer-agent> --bead <bead-id> --category HANDOFF --subject "<subject>" --body "<body>"
  1. Build readiness summary before close:
node skills/beadboard-driver/scripts/readiness-report.mjs --checks '[{"name":"typecheck","ok":true}]' --artifacts '[{"path":"artifacts/final.png","required":true}]'

Path Resolution Policy

  • Treat BB_REPO as authoritative when set.
  • On invalid BB_REPO, stop and return remediation text. Do not silently bypass.
  • If BB_REPO is unset, resolve from global bb, then cached path, then bounded discovery.
  • Update the skill cache only after a verified path is found.
  • Never mutate shell profile/env vars automatically.

Identity Policy

  • Create one unique agent identity per session.
  • Use adjective-noun names and retry on collisions.
  • Register identity before any mail/reservation command.
  • Keep bead claim authority in bd; identity alone is not a claim.

Verification Policy

  • Do not claim completion without fresh command evidence.
  • Require typecheck, test, and lint evidence for closeout tasks.
  • Use readiness report output in bead notes.

References

  • Command and argument contracts: references/command-matrix.md
  • Failure and recovery handling: references/failure-modes.md
  • End-to-end session choreography: references/session-lifecycle.md