diff --git a/skills/beadboard-driver/references/session-lifecycle.md b/skills/beadboard-driver/references/session-lifecycle.md index 3593166..8a349b5 100644 --- a/skills/beadboard-driver/references/session-lifecycle.md +++ b/skills/beadboard-driver/references/session-lifecycle.md @@ -1,36 +1,173 @@ # Session Lifecycle -## 1) Start Session +This runbook is the minimum lifecycle contract for agents using BeadBoard Driver. -1. Run environment diagnosis. -2. Run preflight. -3. Resolve bb path and confirm `bd` availability. -4. Generate unique session agent name. -5. Register agent identity. -6. Confirm you are operating in the assigned target repository. -7. Do not change project scope (scope is user-controlled in BeadBoard UI). +## 1) Session Start -## 2) Pick and Claim Work +1. Run preflight and discovery checks: -1. `bd ready` -2. `bd show ` -3. `bd update --status in_progress --claim` +```bash +node skills/beadboard-driver/scripts/session-preflight.mjs +node skills/beadboard-driver/scripts/resolve-bb.mjs +``` -## 3) Coordinate During Work +2. Create or identify your agent bead first (required before claiming work): -1. Reserve sensitive scopes before edits. -2. Send structured mail for blockers and handoffs. -3. Read and acknowledge required messages. +```bash +bd create --title "Agent: " --type task --priority 0 --label "gt:agent,role:" +``` -## 4) Verify and Close +3. Set state transitions and attach hook when work begins: -1. Run required gates (typecheck/test/lint). -2. Build readiness report with checks + artifacts. -3. Post notes to bead. -4. Close bead with explicit reason. +```bash +bd agent state spawning +bd agent state running +``` -## 5) Session End Hygiene +4. Query hard memory for your domain before claim: -1. Release reservations. -2. Ensure no unresolved blocker mail is pending for your bead. -3. Hand off context if stopping before close. +```bash +bd query "label=memory AND label=mem-canonical AND label=mem-hard AND status=closed" +``` + +## 2) Discover Work and Read Epic Context + +1. Find ready work: + +```bash +bd ready +``` + +2. For child tasks, read parent epic first: + +```bash +bd show +bd children +``` + +3. Read full assigned bead: + +```bash +bd show +``` + +## 3) Claim Correctly (`--assignee`, not `--claim`) + +Claim order is strict: +1. Agent bead exists +2. Set bead to in_progress with assignee +3. Hook agent slot to current bead + +```bash +bd update --status in_progress --assignee +bd slot set hook +bd agent state working +``` + +## 4) Dependency Workflow During Execution + +Use dependencies to model execution order, not visual grouping. + +Add blocker dependency (`` depends on ``): + +```bash +bd dep add +``` + +Add non-blocking related context link: + +```bash +bd dep relate +``` + +Inspect dependency state: + +```bash +bd dep list +bd dep tree +``` + +## 5) BLOCKED Path (Mandatory Pattern) + +When blocked, do all four actions: + +1. State signal: + +```bash +bd agent state stuck +``` + +2. Coordination signal: + +```bash +bb agent send --from --to --bead --category BLOCKED --subject "" --body "" +``` + +3. Keep heartbeat while waiting: + +```bash +bd agent heartbeat +``` + +4. Resume cleanly once unblocked: + +```bash +bd agent state running +bd agent state working +``` + +## 6) Verification and Closure + +Run gates before close claims: + +```bash +npm run typecheck +npm run lint +npm run test +``` + +Record evidence and close bead: + +```bash +bd update --notes "Commands run: ... Outputs: ..." +bd close --reason "" +``` + +Detach hook when bead is complete: + +```bash +bd slot clear hook +bd agent state done +``` + +## 7) Memory Review Rule (Create vs Skip) + +Create/supersede canonical memory only when BOTH are true: +- Rule is reusable across future tasks +- Evidence exists from at least one concrete failure/recovery pattern + +Otherwise, record: + +```bash +bd update --notes "Memory review: no new reusable memory." +``` + +If reusable and novel: +- Create new memory decision bead +- Link anchor + evidence via `bd dep relate` +- Supersede old memory if replacing policy (`bd supersede --with `) + +## 8) Session End Hygiene + +1. Ensure no lingering hook slot: + +```bash +bd slot show +``` + +2. Ensure no unresolved required-ack backlog for your active work. +3. Set end state: + +```bash +bd agent state stopped +```