170 lines
4.8 KiB
Markdown
170 lines
4.8 KiB
Markdown
---
|
|
name: beadboard-driver
|
|
description: Use when an agent is executing work in a non-BeadBoard repo while a human coordinates from BeadBoard, and you need reliable state, mail, assignment, and evidence flow from start to close.
|
|
---
|
|
|
|
# BeadBoard Driver
|
|
|
|
## Overview
|
|
|
|
This skill is the operator runbook for agent execution in external repos with BeadBoard as control plane.
|
|
|
|
Core principle: explicit state + explicit assignment + explicit evidence.
|
|
|
|
## The Iron Law
|
|
|
|
```
|
|
No bead claims, handoffs, or completion statements without:
|
|
1) assignee set,
|
|
2) coordination checked,
|
|
3) evidence recorded.
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- `bd` must be installed and available on `PATH`.
|
|
- `bb` or `beadboard` must be installed globally and available on `PATH`.
|
|
- Work from the target repository root.
|
|
|
|
## Session Runbook (Do Not Skip Steps)
|
|
|
|
### Step 1: Preflight and Communication Validation
|
|
|
|
```bash
|
|
node skills/beadboard-driver/scripts/session-preflight.mjs
|
|
node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs
|
|
```
|
|
|
|
Expected outcome:
|
|
- `bd` detected
|
|
- `bb` detected (global install)
|
|
- `mail.delegate` points to `bb-mail-shim.mjs`
|
|
- `BB_AGENT` or `BD_ACTOR` identity is available
|
|
|
|
If either script fails, stop and fix environment first.
|
|
|
|
### Step 2: Create Agent Bead Identity
|
|
|
|
```bash
|
|
bd create --title="Agent: <role-name>" --description="<scope>" --type=task --priority=0 --label="gt:agent,role:<orchestrator|ui|graph|backend|infra>"
|
|
```
|
|
|
|
Then set lifecycle state:
|
|
|
|
```bash
|
|
bd agent state <agent-bead-id> spawning
|
|
bd agent state <agent-bead-id> running
|
|
```
|
|
|
|
### Step 3: Initialize/Update `project.md`
|
|
|
|
`project.md` lives in the target repo root (not in the skill folder):
|
|
- first agent in repo creates it from `skills/beadboard-driver/project.template.md`
|
|
- later agents read and update it before work
|
|
|
|
Required updates each session:
|
|
- confirm whether `bd` and `bb/beadboard` are globally installed
|
|
- record shell/platform facts affecting execution
|
|
- record mail delegate/identity policy if changed
|
|
|
|
### Step 4: Read Hard Memory and Task Context
|
|
|
|
```bash
|
|
bd show beadboard-116 beadboard-60a beadboard-zas
|
|
bd ready
|
|
bd show <target-bead-id>
|
|
```
|
|
|
|
Minimum: read task contract, dependencies, success criteria, and blockers.
|
|
|
|
### Step 5: Claim Work with Assignee + Hook Slot
|
|
|
|
```bash
|
|
bd update <target-bead-id> --status in_progress --assignee <agent-bead-id>
|
|
bd slot set <agent-bead-id> hook <target-bead-id>
|
|
```
|
|
|
|
Never use `--claim`. Use explicit `--assignee`.
|
|
|
|
### Step 6: Execute + Heartbeat + Coordinate via Mail
|
|
|
|
During execution:
|
|
|
|
```bash
|
|
bd agent heartbeat <agent-bead-id>
|
|
```
|
|
|
|
Coordinate through delegated mail:
|
|
|
|
```bash
|
|
bd mail inbox
|
|
bd mail send --to <agent-or-role> --bead <bead-id> --category <HANDOFF|BLOCKED|DECISION|INFO> --subject "<short>" --body "<details>"
|
|
bd mail read <message-id>
|
|
bd mail ack <message-id>
|
|
```
|
|
|
|
When blocked:
|
|
- send `BLOCKED`
|
|
- set `bd agent state <agent-bead-id> stuck`
|
|
- resume only after intervention/response
|
|
|
|
### Step 7: Verification Gates (Code Changes)
|
|
|
|
```bash
|
|
npm run typecheck
|
|
npm run lint
|
|
npm run test
|
|
```
|
|
|
|
Do not claim fixed/done without fresh command output from this session.
|
|
|
|
### Step 8: Publish Evidence and Close
|
|
|
|
```bash
|
|
bd update <target-bead-id> --notes "<commands run + key outputs + files changed>"
|
|
bd close <target-bead-id> --reason "<what was completed>"
|
|
bd slot clear <agent-bead-id> hook
|
|
bd agent state <agent-bead-id> done
|
|
```
|
|
|
|
### Step 9: Memory Review
|
|
|
|
If reusable lesson exists:
|
|
- create/supersede canonical memory decision bead
|
|
|
|
If no reusable lesson:
|
|
- record: `Memory review: no new reusable memory.`
|
|
|
|
## Red Flags
|
|
|
|
Stop and correct if you are about to:
|
|
- close without `--assignee` history
|
|
- skip `bd mail` checks at session start/claim/close
|
|
- claim completion without gate output
|
|
- write project context inside skill folder instead of repo `project.md`
|
|
- use deprecated direct command patterns from old docs
|
|
|
|
## Use-The-Right-Doc Map
|
|
|
|
- `references/session-lifecycle.md`:
|
|
Full end-to-end session choreography.
|
|
- `references/agent-state-liveness.md`:
|
|
Agent states, heartbeat cadence, liveness interpretation.
|
|
- `references/coordination-system.md`:
|
|
Canonical bb-mail command surface and category semantics.
|
|
- `references/coord-events-sessions-ack.md`:
|
|
Trigger map, inbox polling protocol, blocked-to-resume walkthrough.
|
|
- `references/command-matrix.md`:
|
|
Exact command inventory for day-to-day operation.
|
|
- `references/failure-modes.md`:
|
|
Deterministic diagnosis and recovery paths.
|
|
- `references/memory-system.md`:
|
|
Memory anchors, injection protocol, promotion/supersede rules.
|
|
- `references/archetypes-templates-swarms.md`:
|
|
Swarm composition, molecule operations, worker dispatch patterns.
|
|
- `references/missions-realtime.md`:
|
|
Real-time/watcher/event troubleshooting.
|
|
|
|
## Bottom Line
|
|
|
|
If you follow this runbook exactly, any agent can enter cold, coordinate safely, and deliver auditable completion without drift.
|