beadboard/NEXT_SESSION_PROMPT.md

Next Session: BeadBoard Driver Skill v5 Rewrite (beadboard-maf)

TL;DR

Work on the beadboard-maf epic — rewriting the beadboard-driver skill to teach agents the real live command surface. beadboard-izs (coordination layer) is complete. Start maf.1–5 in parallel immediately, then maf.6 onward.

---

⚠️ FOLDER WARNING — READ BEFORE TOUCHING ANYTHING

✅ CORRECT:   skills/beadboard-driver/          ← THE REAL SKILL
❌ WRONG:     .agents/skills/beadboard-driver/  ← OLD COPY, DO NOT EDIT

Every file you create or edit must be under skills/beadboard-driver/. The .agents/ folder is an outdated mirror that does not get distributed. A prior agent (silver-scribe session) made the mistake of writing to .agents/ — commit dc7f201 is noise in the wrong place. Do not repeat this.

---

Context Recovery Checklist

cd /mnt/c/Users/Zenchant/codex/beadboard
git log --oneline -8            # see what's been committed by other agents
bd ready                        # what's unblocked right now
bd show beadboard-maf           # review v5 epic
bd show beadboard-izs           # confirm izs is closed (should be)

---

What's Already Done (beadboard-izs — closed by parallel agents)

All coordination infrastructure is committed and working on feat/bb-mail:

Commit	What	Who
114c227	bb agent commands wired into global bb CLI (src/cli/beadboard-cli.ts)	other agent
dcca324	API routes: /api/agents/mail + /api/agents/reservations (src/app/api/agents/)	other agent
d1b8125	bb-mail-shim.mjs + session-preflight.mjs mail delegate in skills/ + tests	other agent
dc7f201	⚠️ WRONG FOLDER — shim in .agents/ (noise, superseded by d1b8125)	silver-scribe (us)

izs.1 (audit) may still be open — check bd show beadboard-izs.1 and close it if the audit was done inline (it was, across this session).

---

What Was Discovered This Session (Critical Context for v5 Docs)

These facts must inform every reference doc and command example you write:

1. bb agent IS the real coordination API. Commands: register, list, show, activity-lease, send, inbox, read, ack, reserve, release, status. All work globally via the installed bb CLI.

2. bd mail → bb agent via bb-mail-shim.mjs (already in skills/). Set BB_AGENT=<name>, then bd mail inbox/send/read/ack transparently calls bb agent. Configured automatically by running session-preflight.mjs.

3. Message categories: HANDOFF, BLOCKED, DECISION, INFO. HANDOFF and BLOCKED auto-set requires_ack: true.

4. Mail storage: ~/.beadboard/agent/messages/<agent>.jsonl (inbox) + ~/.beadboard/agent/messages/index/<msg-id>.json (state). Reservations: ~/.beadboard/agent/reservations/active.json.

5. Agent registration flow:

   bd agent state bb-<name> idle           # creates bead, sets ZFC state
   bd update bb-<name> --title "Agent: <name>" --add-label "gt:agent,role:<role>"
   

6. Liveness tiers: active (<15m), stale (15–30m), evicted (30–60m), idle (≥60m).

---

The v5 Skill: What Needs to Change

All work is under skills/beadboard-driver/.

Files to rewrite (read each before touching):

File	Problem	maf task
references/coord-events-sessions-ack.md	Deprecated commands, no WHEN-to-use triggers	maf.6
references/archetypes-templates-swarms.md	Zero real bd swarm commands, no bd mol	maf.3
references/command-matrix.md	Dead commands, missing bd agent/swarm/slot/gate/mol	maf.7
references/failure-modes.md	Deprecated errors, missing Dolt/mail/heartbeat failures	maf.7
references/memory-system.md	Missing domain anchor IDs and injection trigger	maf.2
references/session-lifecycle.md	Wrong --claim flag, missing BLOCKED path, 37 lines	maf.4
scripts/lib/driver-lib.mjs	discoverBbPath() only finds bb.ps1 — breaks Linux/WSL	maf.5
project.template.md	Missing BB_AGENT, heartbeat policy, swarm template, mail config	maf.9
SKILL.md	Full v5 rewrite tying all refs together	maf.10 (last)

Files to create (new):

File	Content	maf task
references/agent-state-liveness.md	ZFC states, bd agent heartbeat, liveness tiers, slot workflow	maf.1
references/coordination-system.md	Full bb agent surface, WHEN-to-use triggers, worked BLOCKED flow	maf.6/izs.7

---

Execution Order

START IMMEDIATELY (all parallel, no blockers):
  maf.1  Create references/agent-state-liveness.md    (new doc)
  maf.2  Update references/memory-system.md           (add anchor IDs + inject trigger)
  maf.3  Rewrite references/archetypes-templates-swarms.md
  maf.4  Expand references/session-lifecycle.md
  maf.5  Fix scripts/lib/driver-lib.mjs               (Linux/WSL bb discovery)

AFTER maf.6 PREREQS (izs.7 ref doc must exist):
  maf.6  Rewrite references/coord-events-sessions-ack.md  ← read izs.7 output FIRST

AFTER maf.6:
  maf.7  Rewrite references/command-matrix.md + failure-modes.md
  maf.8  Update tests/
  maf.9  Update project.template.md

LAST:
  maf.10 Rewrite SKILL.md v5 entry point

---

Ground Truth Files to Read Before Writing Anything

help/cli/bd_help.txt                       # full bd command surface
help/cli/agent-help.txt                    # bd agent state/heartbeat/show
help/cli/true_agents.txt                   # agent bead workflow
help/cli/state-help.txt                    # ZFC state machine
help/memory/query_and_injection.txt        # 7-step memory injection playbook
help/memory/memory_fabric_workflow.txt
help/workflows/agent_bead_workflow.txt
skills/beadboard-driver/SKILL.md           # v4 entry point (what you're replacing)
skills/beadboard-driver/references/        # all current reference docs
src/lib/agent-mail.ts                      # real mail implementation + flag names
src/lib/agent-registry.ts                  # registration, liveness
tools/bb.ts                                # bb agent CLI (source of truth for flags)

---

Skill to Use

hyperpowers:executing-plans — execute maf tasks one at a time with review checkpoints. hyperpowers:verification-before-completion — run before closing each maf task.

---

Agent Bead Protocol

# Session start
bd agent state bb-<adjective-noun> idle
bd update bb-<adjective-noun> --title "Agent: <name>" --add-label "gt:agent,role:implementer"
bd agent state bb-<adjective-noun> working
bd update beadboard-maf.1 --status in_progress --assignee <name>

# Session end
bd agent state bb-<adjective-noun> done
bd update bb-<adjective-noun> --status closed

New unique adjective-noun each session (e.g., amber-linden, cobalt-ridge).

---

Commit Convention

Branch: feat/bb-mail

Stage only your files — other agents are working concurrently:

git add skills/beadboard-driver/<specific-files>
git commit -m "feat(driver-v5): <description> (maf.<n>)"