18fbafdce4
- Extract src/lib/agent/ bounded context with types, registry, messaging - Add comments_count to BeadIssue for SSE comment detection - Create batch endpoints for mail/reservations APIs - Add memory validation to session-preflight - Remove unused empty dirs (mockup, sessions, timeline) - Move stashes to docs/references, gitignore them
173 lines
3.4 KiB
Markdown
173 lines
3.4 KiB
Markdown
# Session Lifecycle
|
|
|
|
This runbook is the minimum lifecycle contract for agents using BeadBoard Driver.
|
|
|
|
## 1) Session Start
|
|
|
|
1. Run preflight and discovery checks:
|
|
|
|
```bash
|
|
node {baseDir}/scripts/session-preflight.mjs
|
|
```
|
|
|
|
2. Create or identify your agent bead first (required before claiming work):
|
|
|
|
```bash
|
|
bd create --title "Agent: <name>" --type task --priority 0 --label "gt:agent,role:<role>"
|
|
```
|
|
|
|
3. Set state transitions and attach hook when work begins:
|
|
|
|
```bash
|
|
bd agent state <agent-bead-id> spawning
|
|
bd agent state <agent-bead-id> running
|
|
```
|
|
|
|
4. Query hard memory for your domain before claim:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
bd ready
|
|
```
|
|
|
|
2. For child tasks, read parent epic first:
|
|
|
|
```bash
|
|
bd show <epic-id>
|
|
bd children <epic-id>
|
|
```
|
|
|
|
3. Read full assigned bead:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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>`):
|
|
|
|
```bash
|
|
bd dep add <blocked-id> <blocker-id>
|
|
```
|
|
|
|
Add non-blocking related context link:
|
|
|
|
```bash
|
|
bd dep relate <id-a> <id-b>
|
|
```
|
|
|
|
Inspect dependency state:
|
|
|
|
```bash
|
|
bd dep list <bead-id>
|
|
bd dep tree <bead-id>
|
|
```
|
|
|
|
## 5) BLOCKED Path (Mandatory Pattern)
|
|
|
|
When blocked, do all four actions:
|
|
|
|
1. State signal:
|
|
|
|
```bash
|
|
bd agent state <agent-bead-id> stuck
|
|
```
|
|
|
|
2. Coordination signal:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bd agent heartbeat <agent-bead-id>
|
|
```
|
|
|
|
4. Resume cleanly once unblocked:
|
|
|
|
```bash
|
|
bd agent state <agent-bead-id> running
|
|
bd agent state <agent-bead-id> 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 <bead-id> --notes "Commands run: ... Outputs: ..."
|
|
bd close <bead-id> --reason "<completed outcome>"
|
|
```
|
|
|
|
Detach hook when bead is complete:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bd slot show <agent-bead-id>
|
|
```
|
|
|
|
2. Ensure no unresolved required-ack backlog for your active work.
|
|
3. Set end state:
|
|
|
|
```bash
|
|
bd agent state <agent-bead-id> stopped
|
|
```
|