From fe9a1d99a31f1ff3e00c8df7367e9f7dd21c4ddc Mon Sep 17 00:00:00 2001 From: ZenchantLive Date: Tue, 3 Mar 2026 19:26:20 -0800 Subject: [PATCH] docs(session): update next-session handoff after v5 completion --- NEXT_SESSION_PROMPT.md | 243 ++++++++++++++--------------------------- 1 file changed, 81 insertions(+), 162 deletions(-) diff --git a/NEXT_SESSION_PROMPT.md b/NEXT_SESSION_PROMPT.md index e0b5978..4ba1f0e 100644 --- a/NEXT_SESSION_PROMPT.md +++ b/NEXT_SESSION_PROMPT.md @@ -1,185 +1,104 @@ -# Next Session: BeadBoard Driver Skill v5 Rewrite (beadboard-maf) +# Next Session: Post-v5 Follow-On (beadboard-txj) ## 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. +`beadboard-maf` (Driver Skill v5) is complete and closed. Start next on `beadboard-txj` (Enhanced Graph Edge Visualization), beginning with `beadboard-txj.2`. --- -## ⚠️ FOLDER WARNING — READ BEFORE TOUCHING ANYTHING +## What Changed (Completed This Session) -``` -✅ CORRECT: skills/beadboard-driver/ ← THE REAL SKILL -❌ WRONG: .agents/skills/beadboard-driver/ ← OLD COPY, DO NOT EDIT -``` +### v5 epic closed -**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. +- Closed: `beadboard-maf` and all children `maf.1` through `maf.10`. + +### Major outputs landed + +- New/refreshed skill references under `skills/beadboard-driver/references/`: + - `agent-state-liveness.md` (new) + - `memory-system.md` + - `archetypes-templates-swarms.md` + - `session-lifecycle.md` + - `coord-events-sessions-ack.md` + - `command-matrix.md` + - `failure-modes.md` + - `coordination-system.md` (already added in izs; used as canonical source) +- Script/platform updates: + - `skills/beadboard-driver/scripts/lib/driver-lib.mjs` + - Added `skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs` +- Test expansion: + - Added bb-mail lifecycle and config contract coverage + - Updated cross-platform resolve/preflight tests + - Registered all new tests in `skills/beadboard-driver/tests/run-tests.mjs` and `package.json` +- Template + entrypoint rewrite: + - `skills/beadboard-driver/project.template.md` + - `skills/beadboard-driver/SKILL.md` (full v5 rewrite) + +### Commit log (this session chain) + +- `a4de66a` fix(skill): support linux and wsl bb discovery +- `5364885` docs(skill): rewrite coordination events and ack protocol +- `1880301` docs(skill): refresh command matrix and failure modes +- `003aba3` test(skill): add bb mail lifecycle and preflight coverage +- `60415cc` docs(skill): expand project template for v5 coordination +- `3006698` docs(skill): rewrite beadboard-driver entrypoint for v5 --- -## Context Recovery Checklist +## Verification Evidence + +For code-affecting bead `maf.8`, gates were run and passed: + +```bash +npm run typecheck +npm run lint +npm run test +``` + +- `typecheck`: pass +- `lint`: pass (warnings only, no errors) +- `test`: pass (full suite including new skill contract tests) + +--- + +## Important Notes + +- Communication path remains global-install based: + - `bd mail` delegates through `bb-mail-shim.mjs` to global `bb` CLI + - Requirement is still `bb/beadboard` on `PATH` +- `project.md` policy is now explicit in template/skill: + - first agent creates `project.md` in target repo root + - subsequent agents must read/update it before work + +--- + +## Open Risks / Follow-Ups + +1. `dolt` remote auto-push warnings occurred during some bead closes due to non-fast-forward; local work is committed. +2. One large commit (`003aba3`) intentionally includes deletion of tracked `tmp/bbmaf8*` fixture/worktree artifacts. + +--- + +## Exact Next Bead(s) ```bash 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) +bd ready +bd show beadboard-txj beadboard-txj.2 +bd update beadboard-txj.2 --status in_progress --assignee ``` --- -## What's Already Done (beadboard-izs — closed by parallel agents) +## Skills Used -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). +- beadboard-driver +- verification-before-completion +- (execution pattern) implementing beads in dependency order with per-bead commits --- -## What Was Discovered This Session (Critical Context for v5 Docs) +## Memory Review -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=`, 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/.jsonl` (inbox) + - `~/.beadboard/agent/messages/index/.json` (state). - Reservations: `~/.beadboard/agent/reservations/active.json`. - -5. **Agent registration flow**: - ```bash - bd agent state bb- idle # creates bead, sets ZFC state - bd update bb- --title "Agent: " --add-label "gt:agent,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 - -```bash -# Session start -bd agent state bb- idle -bd update bb- --title "Agent: " --add-label "gt:agent,role:implementer" -bd agent state bb- working -bd update beadboard-maf.1 --status in_progress --assignee - -# Session end -bd agent state bb- done -bd update bb- --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: -```bash -git add skills/beadboard-driver/ -git commit -m "feat(driver-v5): (maf.)" -``` +- No new canonical memory bead created in this session. +- Reused existing hard-memory anchors/rules during execution.