docs: update next session prompt for maf v5 rewrite
- Correct skill folder prominently called out: skills/beadboard-driver/
- Warns against .agents/skills/ (wrong folder used in dc7f201)
- Documents all beadboard-izs work committed by parallel agents
- Lists ground truth help/ files to read before writing v5 docs
- maf execution order with parallelism map
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ZenchantLive
parent
85898a433a
commit
c6f8149ba2
1 changed files with 170 additions and 52 deletions
|
|
@ -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=<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**:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
git add skills/beadboard-driver/<specific-files>
|
||||
git commit -m "feat(driver-v5): <description> (maf.<n>)"
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue