docs(session): update next-session handoff after v5 completion
This commit is contained in:
ZenchantLive
parent
3006698002
commit
fe9a1d99a3
1 changed files with 81 additions and 162 deletions
|
|
@ -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 <agent-bead-id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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=<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>)"
|
||||
```
|
||||
- No new canonical memory bead created in this session.
|
||||
- Reused existing hard-memory anchors/rules during execution.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue