beadboard/skills/beadboard-driver/references/session-lifecycle.md

Session Lifecycle

This runbook is the minimum lifecycle contract for agents using BeadBoard Driver.

1) Session Start

1. Run preflight and discovery checks:

node {baseDir}/scripts/session-preflight.mjs

2. Create or identify your agent bead first (required before claiming work):

bd create --title "Agent: <name>" --type task --priority 0 --label "gt:agent,role:<role>"

3. Set state transitions and attach hook when work begins:

bd agent state <agent-bead-id> spawning
bd agent state <agent-bead-id> running

4. Query hard memory for your domain before claim:

# Select domain: memory-arch | memory-workflow | memory-agent | memory-ux | memory-reliability
bd query "label=memory AND label=mem-canonical AND label=<domain> AND status=closed" --sort updated --reverse

2) Discover Work and Read Epic Context

1. Find ready work:

bd ready

2. For child tasks, read parent epic first:

bd show <epic-id>
bd children <epic-id>

3. Read full assigned bead:

bd show <bead-id>

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

bd update <bead-id> --status in_progress --assignee <agent-bead-id>
bd slot set <agent-bead-id> hook <bead-id>
bd agent state <agent-bead-id> working

4) Dependency Workflow During Execution

Use dependencies to model execution order, not visual grouping.

Add blocker dependency (<blocked> depends on <blocker>):

bd dep add <blocked-id> <blocker-id>

Add non-blocking related context link:

bd dep relate <id-a> <id-b>

Inspect dependency state:

bd dep list <bead-id>
bd dep tree <bead-id>

5) BLOCKED Path (Mandatory Pattern)

When blocked, do all four actions:

1. State signal:

bd agent state <agent-bead-id> stuck

2. Coordination signal:

bd mail send --to <target-agent-or-role> --bead <bead-id> --category BLOCKED --subject "<blocker summary>" --body "<what is needed>"

3. Keep heartbeat while waiting:

bd agent heartbeat <agent-bead-id>

4. Resume cleanly once unblocked:

bd agent state <agent-bead-id> running
bd agent state <agent-bead-id> working

6) Verification and Closure

Run gates before close claims:

npm run typecheck
npm run lint
npm run test

Record evidence and close bead:

bd update <bead-id> --notes "Commands run: ... Outputs: ..."
bd close <bead-id> --reason "<completed outcome>"

Detach hook when bead is complete:

bd slot clear <agent-bead-id> hook
bd agent state <agent-bead-id> 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:

bd update <bead-id> --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 <old> --with <new>)

8) Session End Hygiene

1. Ensure no lingering hook slot:

bd slot show <agent-bead-id>

2. Ensure no unresolved required-ack backlog for your active work.
3. Set end state:

bd agent state <agent-bead-id> stopped