diff --git a/NEXT_SESSION_PROMPT.md b/NEXT_SESSION_PROMPT.md index 0140e6e..e0b5978 100644 --- a/NEXT_SESSION_PROMPT.md +++ b/NEXT_SESSION_PROMPT.md @@ -1,67 +1,185 @@ -# Next Session: Runtime Manager Rollout Complete (beadboard-vyt) +# Next Session: BeadBoard Driver Skill v5 Rewrite (beadboard-maf) -## What Changed (2026-03-03) +## TL;DR -`beadboard-vyt` is completed and closed. +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. -Delivered across phases 0-8: -1. Runtime manager ADR + contract alignment - - `docs/adr/2026-03-03-runtime-manager-global-install.md` - - `docs/adr/2026-03-03-global-installer-contract-and-manifest.md` -2. Runtime manager library - - `src/lib/runtime-manager.ts` -3. Runtime-aware launcher metadata - - `install/beadboard.mjs` -4. Wrapper migration to runtime metadata + atomic shim rewrite - - `install/install.sh` - - `install/install.ps1` -5. Global CLI entrypoint (`doctor`, `self-update`, `uninstall`) - - `bin/beadboard.js` - - `src/cli/beadboard-cli.ts` -6. Driver remediation copy alignment (npm-global first) - - `skills/beadboard-driver/scripts/lib/driver-lib.mjs` - - `skills/beadboard-driver/scripts/session-preflight.mjs` -7. CI/docs rollout updates - - `.github/workflows/installer-smoke.yml` - - `README.md` - - `docs/ops/global-install-rollout.md` +--- -## Verification Evidence +## ⚠️ FOLDER WARNING — READ BEFORE TOUCHING ANYTHING -Focused TDD/acceptance tests added and passing: -1. `tests/docs/runtime-manager-adr-contract.test.ts` -2. `tests/lib/runtime-manager.test.ts` -3. `tests/scripts/beadboard-launcher-runtime.test.ts` -4. `tests/scripts/install-legacy-migration.test.ts` -5. `tests/cli/beadboard-cli.test.ts` -6. Updated installer/driver/docs/ci contract tests all passing. +``` +✅ CORRECT: skills/beadboard-driver/ ← THE REAL SKILL +❌ WRONG: .agents/skills/beadboard-driver/ ← OLD COPY, DO NOT EDIT +``` -Full gates run in-session: -1. `npm run typecheck` -> pass -2. `npm run lint` -> fail outside rollout scope (known pre-existing `.beads/fix.js` and `.beads/fix2.js` errors) -3. `npm run test` -> pass (full explicitly enumerated suite) +**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. -Targeted acceptance checks run and passing: -1. `node --import tsx --test tests/lib/runtime-manager.test.ts` -2. `node --import tsx --test tests/scripts/beadboard-launcher-runtime.test.ts` -3. `node --import tsx --test tests/scripts/install-legacy-migration.test.ts` -4. `node --import tsx --test tests/skills/beadboard-driver/resolve-bb.test.ts` +--- -## Open Risks +## Context Recovery Checklist -1. Global lint remains non-green due known unrelated `.beads/fix.js` and `.beads/fix2.js` rule violations. -2. Repo remains broadly dirty from unrelated concurrent work; commits in this session were intentionally scoped by file selection. +```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) +``` -## Next Bead +--- -Run `bd ready` and pick top priority from ready queue; likely quality/stabilization follow-up around existing global lint/test drift if requested. +## What's Already Done (beadboard-izs — closed by parallel agents) -## Skills Used This Session +All coordination infrastructure is committed and working on `feat/bb-mail`: -1. `executing-plans` -2. `test-driven-development` -3. `verification-before-completion` +| 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) | -## Memory Review +**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). -Memory review completed: no new reusable memory created. +--- + +## 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=`, 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.)" +```