viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
beadboard/skills/beadboard-driver/SKILL.md

159 lines
4.8 KiB
Markdown
Raw Normal View History

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
---
name: beadboard-driver
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
description: Complete operating manual for agents running work in external repos while humans orchestrate from BeadBoard.
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
---
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
# BeadBoard Driver
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
BeadBoard is for teams that want autonomous agents without losing control of the work.
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
Most agent setups break down the same way: work happens quickly, but visibility collapses, handoffs get fuzzy, and “done” starts meaning “probably done.” This skill fixes that operating problem.
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
With BeadBoard Driver, agents execute inside the target project repo, while humans orchestrate from BeadBoard as the control plane: assign, redirect, intervene, verify, and keep a durable coordination record.
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
BeadBoard project:
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
- GitHub: `https://github.com/zenchantlive/beadboard`
## What This Changes
- Work becomes observable, not performative.
- Ownership stays explicit at bead level.
- Handoffs and blockers become machine-readable events.
- Completion claims require evidence, not confidence.
- Multi-agent execution stays coordinated instead of chaotic.
## Operating Reality
- Agents usually run in a non-BeadBoard target repo.
- The user controls project scope from BeadBoard UI.
- Agents execute the current repo context they were assigned.
- `bd` remains source of truth for task/memory state.
## Start Here
Run this quick confidence check before you start a session:
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
```bash
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
bd --version
node skills/beadboard-driver/scripts/session-preflight.mjs
node skills/beadboard-driver/scripts/resolve-bb.mjs
feat(telemetry): complete bb-buff.1.3 - Backend Liveness Refactor STORY: The session backend needed to aggregate agent health from a live telemetry stream rather than static bead metadata. This refactor makes liveness signals real-time and accurate. COLLABORATION: We extended the ActivityEvent model with a native 'heartbeat' kind, updated extendActivityLease() to emit through the activity bus, and refactored getAgentLivenessMap() to prioritize heartbeat activity history over stale bead metadata. DELIVERABLES: - ActivityEvent extended with 'heartbeat' kind - extendActivityLease() emits heartbeats through activity bus - getAgentLivenessMap() prefers telemetry over static metadata - Registry APIs support projectRoot injection for testing - Tests verify preference logic via TDD VERIFICATION: - 93/93 tests PASSING - Heartbeat override verified in isolated temp projects CLOSES: bb-buff.1.3 BLOCKS: bb-buff.3.2, bb-buff.3.3, bb-buff.2.1
2026-02-15 21:14:05 -08:00
```
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
If discovery fails, install/repair from:
- `https://github.com/zenchantlive/beadboard`
## Session Runbook
1. Diagnose environment.
2. Confirm preflight/discovery.
3. Establish session identity.
4. Read memory + ready work.
5. Claim bead with assignee.
6. Execute and coordinate via events.
7. Run verification gates.
8. Publish evidence and close.
9. Perform memory review.
## Core Commands
feat(telemetry): complete bb-buff.1.3 - Backend Liveness Refactor STORY: The session backend needed to aggregate agent health from a live telemetry stream rather than static bead metadata. This refactor makes liveness signals real-time and accurate. COLLABORATION: We extended the ActivityEvent model with a native 'heartbeat' kind, updated extendActivityLease() to emit through the activity bus, and refactored getAgentLivenessMap() to prioritize heartbeat activity history over stale bead metadata. DELIVERABLES: - ActivityEvent extended with 'heartbeat' kind - extendActivityLease() emits heartbeats through activity bus - getAgentLivenessMap() prefers telemetry over static metadata - Registry APIs support projectRoot injection for testing - Tests verify preference logic via TDD VERIFICATION: - 93/93 tests PASSING - Heartbeat override verified in isolated temp projects CLOSES: bb-buff.1.3 BLOCKS: bb-buff.3.2, bb-buff.3.3, bb-buff.2.1
2026-02-15 21:14:05 -08:00
```bash
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
# Diagnostics and discovery
node skills/beadboard-driver/scripts/diagnose-env.mjs
node skills/beadboard-driver/scripts/session-preflight.mjs
node skills/beadboard-driver/scripts/resolve-bb.mjs
# Ensure project context exists in the target repository
node skills/beadboard-driver/scripts/ensure-project-context.mjs --project-root <repo>
# Identity helper
node skills/beadboard-driver/scripts/generate-agent-name.mjs
# Closeout evidence envelope
node skills/beadboard-driver/scripts/readiness-report.mjs --checks '<json>' --artifacts '<json>'
# Safe self-healing (dry-run default)
node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo>
node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo> --apply --fix-git-index-lock
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
```
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
## Bead Lifecycle (Minimum Contract)
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
```bash
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
# Read context
bd show <memory-or-task-id>
bd ready
# Claim explicitly
bd update <bead-id> --status in_progress --assignee <agent-bead-id>
# Record evidence and close
bd update <bead-id> --notes "<commands + outputs>"
bd close <bead-id> --reason "<completed outcome>"
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
```
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
## Use-The-Right-Doc Map
### `references/memory-system.md`
Use when you need to query/apply/create canonical memory, validate provenance, or decide whether a lesson belongs in memory vs task notes.
### `references/coord-events-sessions-ack.md`
Use when you’re coordinating handoffs/blockers/incursions and need correct inbox/read/ack behavior.
### `references/session-lifecycle.md`
Use for end-to-end session choreography and closeout hygiene.
### `references/archetypes-templates-swarms.md`
Use when choosing team shape, role boundaries, and swarm ownership patterns.
### `references/missions-realtime.md`
Use when assigning work and troubleshooting stale/live-update behavior from mission/event flow.
### `references/command-matrix.md`
Use when you need exact command surfaces and argument shape.
### `references/failure-modes.md`
Use when preflight/discovery/coordination fails and you need deterministic recovery.
## Project Context Template
The skill ships a source template file: `project.template.md`.
Runtime contract:
- Agents should use `<target-repo>/project.md` for project context.
- If `<target-repo>/project.md` is missing, create it from `project.template.md`.
- If `<target-repo>/project.md` already exists, do not overwrite it.
Helper command:
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
```bash
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
node skills/beadboard-driver/scripts/ensure-project-context.mjs --project-root <repo>
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
```
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
## Tests
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
Skill-local contracts:
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
- `skills/beadboard-driver/tests/run-tests.mjs`
- `skills/beadboard-driver/tests/*.contract.test.mjs`
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
Repo-level coverage:
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
- `tests/skills/beadboard-driver/*.test.ts`
## Verification Gates
```bash
npm run typecheck
npm run lint
npm run test
```
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
If failures are outside your scope, cite exact failing files/tests and continue transparently.
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
## Bottom Line
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
checkpoint: pre-split branch cleanup
2026-03-03 16:43:42 -08:00
This skill is the bridge between fast autonomous execution and human operator trust. Use it when speed matters, but coordination quality matters more.
Reference in a new issue Copy permalink