refactor: extract agent bounded context + fix SSE comments + cleanup unused
- 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
This commit is contained in:
zenchantlive
parent
6f41c4af31
commit
18fbafdce4
34 changed files with 62714 additions and 1970 deletions
|
|
@ -44,7 +44,7 @@ Blocked condition:
|
|||
|
||||
```bash
|
||||
bd agent state bb-silver-scribe stuck
|
||||
bb agent send --from silver-scribe --to cobalt-ridge --bead beadboard-123 --category BLOCKED --subject "Waiting on schema" --body "Need migration direction before continuing."
|
||||
bd mail send --to cobalt-ridge --bead beadboard-123 --category BLOCKED --subject "Waiting on schema" --body "Need migration direction before continuing."
|
||||
```
|
||||
|
||||
Work completion:
|
||||
|
|
@ -74,14 +74,16 @@ Use `bd agent heartbeat <agent-bead-id>` to refresh `last_activity` without chan
|
|||
bd agent heartbeat bb-silver-scribe
|
||||
```
|
||||
|
||||
When to heartbeat:
|
||||
- At least once every 5-10 minutes during long-running work
|
||||
**Daemon agents (persistent processes):**
|
||||
- Normal work: every 5 minutes
|
||||
- High-risk long operations: every 2-3 minutes
|
||||
- Immediately before long test/build phases
|
||||
- Immediately after recovering from interruptions
|
||||
|
||||
Recommended cadence:
|
||||
- Normal work: every 5 minutes
|
||||
- High-risk long operations: every 2-3 minutes
|
||||
**LLM agents (Claude Code, turn-based):**
|
||||
- At turn start (when picking up work)
|
||||
- Immediately before long-running commands
|
||||
- Inter-turn silence is expected and not a health signal
|
||||
|
||||
## Witness Death Timeout
|
||||
|
||||
|
|
@ -95,6 +97,8 @@ Operational interpretation:
|
|||
Agent-side rule:
|
||||
- If you are alive and still executing, heartbeat before anyone has to guess.
|
||||
|
||||
> **Current status:** The Witness enforcement layer is not yet running. Heartbeats are recorded in `last_activity` and visible in the BeadBoard dashboard but are not currently auto-enforced. Agents will not be auto-marked `dead`. Daemon implementation is a future epic.
|
||||
|
||||
## Slot Operations (Current Work Attachment)
|
||||
|
||||
The `hook` slot links an agent bead to the active task bead.
|
||||
|
|
@ -125,7 +129,7 @@ Important slot constraints:
|
|||
|
||||
When blocked:
|
||||
1. Set state to stuck (`bd agent state ... stuck`)
|
||||
2. Send explicit BLOCKED coordination event (`bb agent send --category BLOCKED ...`)
|
||||
2. Send explicit BLOCKED coordination event (`bd mail send --category BLOCKED ...`)
|
||||
3. Keep heartbeat active while waiting
|
||||
4. Resume with `running`/`working` once unblocked
|
||||
|
||||
|
|
|
|||
|
|
@ -8,8 +8,12 @@ Day-to-day runbooks use `bd mail` delegation rather than direct low-level agent
|
|||
- `node skills/beadboard-driver/scripts/session-preflight.mjs`
|
||||
- `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`
|
||||
- `bd create --title="Agent: <role-name>" --description="<agent scope>" --type=task --priority=0 --label="gt:agent,role:<orchestrator|ui|graph|backend|infra>"`
|
||||
- `bd agent state <agent-bead-id> spawning`
|
||||
- `bd agent state <agent-bead-id> running`
|
||||
- `bd agent state <agent-bead-id> spawning` — agent bead created, environment not yet verified
|
||||
- `bd agent state <agent-bead-id> running` — environment verified, ready to claim work
|
||||
- `bd agent state <agent-bead-id> working` — work bead claimed, actively executing
|
||||
- `bd agent state <agent-bead-id> stuck` — blocked, waiting on intervention or response
|
||||
- `bd agent state <agent-bead-id> done` — work bead closed, all deliverables complete
|
||||
- `bd agent state <agent-bead-id> stopped` — session ending cleanly
|
||||
- `bd agent heartbeat <agent-bead-id>`
|
||||
- `bd agent show <agent-bead-id>`
|
||||
|
||||
|
|
@ -75,7 +79,7 @@ Delegate setup and validation:
|
|||
|
||||
## Environment and Repair Helpers
|
||||
|
||||
- `node skills/beadboard-driver/scripts/resolve-bb.mjs`
|
||||
- `node skills/beadboard-driver/scripts/readiness-report.mjs --checks <json> --artifacts <json>`
|
||||
- `node skills/beadboard-driver/scripts/diagnose-env.mjs`
|
||||
- `node skills/beadboard-driver/scripts/heal-common-issues.mjs [--project-root <path>] [--apply] [--fix-git-index-lock]`
|
||||
- `node {baseDir}/scripts/setup-mail-delegate.mjs` — configure mail.delegate (self-resolves shim path)
|
||||
- `node {baseDir}/scripts/readiness-report.mjs --checks <json> --artifacts <json>`
|
||||
- `node {baseDir}/scripts/diagnose-env.mjs`
|
||||
- `node {baseDir}/scripts/heal-common-issues.mjs [--project-root <path>] [--apply] [--fix-git-index-lock]`
|
||||
|
|
|
|||
286
skills/beadboard-driver/references/creating-beads.md
Normal file
286
skills/beadboard-driver/references/creating-beads.md
Normal file
|
|
@ -0,0 +1,286 @@
|
|||
# Creating and Managing Beads
|
||||
|
||||
Complete guide for agents on bead creation, naming, dependencies, and workflow.
|
||||
|
||||
---
|
||||
|
||||
## Bead Naming Format (CRITICAL)
|
||||
|
||||
| Level | Format | Example |
|
||||
|-------|--------|---------|
|
||||
| **Epic** | `beadboard-<id>` | `beadboard-abc` |
|
||||
| **Task** | `beadboard-<epic>.x` | `beadboard-abc.1` |
|
||||
| **Subtask** | `beadboard-<epic>.x.x` | `beadboard-abc.1.2` |
|
||||
|
||||
**Rules:**
|
||||
- `<id>` is auto-generated by `bd create` (alphanumeric, 2-4 chars)
|
||||
- Task numbers increment sequentially under epic
|
||||
- Subtask numbers increment under parent task
|
||||
- **Never skip levels**: epic → task → subtask
|
||||
|
||||
---
|
||||
|
||||
## Creating Epics
|
||||
|
||||
Epics represent high-level features or initiatives.
|
||||
|
||||
```bash
|
||||
bd create \
|
||||
--title="[EPIC] User Authentication System" \
|
||||
--description="Implement secure user login/registration with OAuth support" \
|
||||
--type=epic \
|
||||
--priority=2 \
|
||||
--label="feature,auth"
|
||||
```
|
||||
|
||||
**Output:** `Created beadboard-xyz (epic)`
|
||||
|
||||
---
|
||||
|
||||
## Creating Tasks Under Epics
|
||||
|
||||
Tasks are actionable work units under an epic.
|
||||
|
||||
```bash
|
||||
# Task naming convention: epic.1: Description
|
||||
bd create \
|
||||
--title="xyz.1: Implement login form UI" \
|
||||
--description="Build responsive login form with email/password fields" \
|
||||
--type=task \
|
||||
--priority=2 \
|
||||
--parent=beadboard-xyz
|
||||
```
|
||||
|
||||
**Output:** `Created beadboard-xyz.1 (task)`
|
||||
|
||||
### Creating Subtasks
|
||||
|
||||
```bash
|
||||
# Subtask naming: epic.task.subtask: Description
|
||||
bd create \
|
||||
--title="xyz.1.1: Add form validation" \
|
||||
--description="Implement client-side validation for email format" \
|
||||
--type=task \
|
||||
--priority=1 \
|
||||
--parent=beadboard-xyz.1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setting Dependencies
|
||||
|
||||
### Blocker Dependencies (Execution Order)
|
||||
|
||||
Use when one bead must complete before another starts:
|
||||
|
||||
```bash
|
||||
# xyz.1 cannot start until xyz is done
|
||||
bd dep add beadboard-xyz.1 beadboard-xyz
|
||||
|
||||
# xyz.1.2 is blocked by xyz.1.1
|
||||
bd dep add beadboard-xyz.1.2 beadboard-xyz.1.1
|
||||
```
|
||||
|
||||
### Parent-Child Relationships
|
||||
|
||||
Use for semantic grouping (non-blocking):
|
||||
|
||||
```bash
|
||||
# Link child to parent epic
|
||||
bd dep relate beadboard-xyz beadboard-xyz.1
|
||||
|
||||
# Link subtask to task
|
||||
bd dep relate beadboard-xyz.1 beadboard-xyz.1.1
|
||||
```
|
||||
|
||||
### Viewing Dependencies
|
||||
|
||||
```bash
|
||||
bd dep list beadboard-xyz # Show all dependencies
|
||||
bd ready # Show unblocked, ready-to-start beads
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing Descriptions
|
||||
|
||||
Every bead description MUST include:
|
||||
|
||||
```markdown
|
||||
**Scope:**
|
||||
- Specific thing to implement
|
||||
- Another specific requirement
|
||||
|
||||
**Out of Scope:**
|
||||
- Things explicitly not included
|
||||
- Future work to avoid
|
||||
|
||||
**Success Criteria:**
|
||||
1. Specific measurable outcome
|
||||
2. Test passes
|
||||
3. Evidence of completion
|
||||
```
|
||||
|
||||
### Example Description
|
||||
|
||||
```bash
|
||||
bd create --title="xyz.2: API endpoint" --description="Scope:
|
||||
- POST /api/login endpoint
|
||||
- JWT token generation
|
||||
- Rate limiting (5 req/min)
|
||||
|
||||
Out of Scope:
|
||||
- OAuth providers (in xyz.3)
|
||||
- Password reset flow
|
||||
|
||||
Success Criteria:
|
||||
1. Endpoint returns 200 with valid JWT
|
||||
2. Returns 401 for invalid credentials
|
||||
3. Rate limit enforced" --type=task --priority=2 --parent=beadboard-xyz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Closing Beads
|
||||
|
||||
### Step 1: Update with Evidence
|
||||
|
||||
```bash
|
||||
bd update beadboard-xyz.1 \
|
||||
--notes "Tests pass: npm test -- --grep 'login'
|
||||
Files changed:
|
||||
- src/components/LoginForm.tsx
|
||||
- src/lib/validation.ts
|
||||
Coverage: 94%"
|
||||
```
|
||||
|
||||
### Step 2: Close
|
||||
|
||||
```bash
|
||||
bd close beadboard-xyz.1 --reason "Login form implemented, tested, merged to main"
|
||||
```
|
||||
|
||||
**Rule:** Update first, then close. `bd close` does not accept `--notes`.
|
||||
|
||||
---
|
||||
|
||||
## Complete Example: End-to-End Workflow
|
||||
|
||||
### 1. Create Epic
|
||||
|
||||
```bash
|
||||
$ bd create --title="[EPIC] Payment Integration" --description="Add Stripe payment processing" --type=epic --priority=1 --label="feature,payments"
|
||||
|
||||
Created beadboard-pmt (epic)
|
||||
```
|
||||
|
||||
### 2. Create Tasks
|
||||
|
||||
```bash
|
||||
$ bd create --title="pmt.1: Stripe account setup" --description="Scope:
|
||||
- Create Stripe dev account
|
||||
- Configure webhook endpoint
|
||||
- Add API keys to vault
|
||||
|
||||
Out of Scope:
|
||||
- Production account (separate epic)
|
||||
|
||||
Success Criteria:
|
||||
1. Test transactions work in sandbox
|
||||
2. Webhook receives events" --type=task --priority=1 --parent=beadboard-pmt
|
||||
|
||||
Created beadboard-pmt.1 (task)
|
||||
|
||||
$ bd create --title="pmt.2: Checkout UI" --description="Scope:
|
||||
- Payment form component
|
||||
- Card element integration
|
||||
- Error handling display
|
||||
|
||||
Success Criteria:
|
||||
1. Form submits to Stripe
|
||||
2. Shows success/failure states" --type=task --priority=2 --parent=beadboard-pmt
|
||||
|
||||
Created beadboard-pmt.2 (task)
|
||||
```
|
||||
|
||||
### 3. Set Dependencies
|
||||
|
||||
```bash
|
||||
# pmt.2 blocked by pmt.1 (need Stripe setup first)
|
||||
$ bd dep add beadboard-pmt.2 beadboard-pmt.1
|
||||
|
||||
Added dependency: beadboard-pmt.2 -> beadboard-pmt.1
|
||||
```
|
||||
|
||||
### 4. Check Ready Status
|
||||
|
||||
```bash
|
||||
$ bd ready
|
||||
|
||||
beadboard-pmt.1 [task] pmt.1: Stripe account setup
|
||||
```
|
||||
|
||||
Only `pmt.1` is ready—`pmt.2` is blocked.
|
||||
|
||||
### 5. Create Subtask
|
||||
|
||||
```bash
|
||||
$ bd create --title="pmt.1.1: Webhook handler" --description="Scope:
|
||||
- POST /webhooks/stripe endpoint
|
||||
- Verify Stripe signature
|
||||
- Update order status
|
||||
|
||||
Success Criteria:
|
||||
1. Signature verification passes
|
||||
2. Order updated correctly" --type=task --priority=1 --parent=beadboard-pmt.1
|
||||
|
||||
Created beadboard-pmt.1.1 (task)
|
||||
```
|
||||
|
||||
### 6. Work and Close
|
||||
|
||||
```bash
|
||||
# After completing pmt.1.1
|
||||
$ bd update beadboard-pmt.1.1 --notes "Webhook handler implemented
|
||||
- src/app/api/webhooks/stripe/route.ts
|
||||
- Tests: npm test webhook.test.ts (3 passing)"
|
||||
|
||||
$ bd close beadboard-pmt.1.1 --reason "Webhook handler complete"
|
||||
|
||||
# After completing pmt.1
|
||||
$ bd update beadboard-pmt.1 --notes "Stripe integration complete
|
||||
- Sandbox account: acct_xxx
|
||||
- Webhook: /api/webhooks/stripe
|
||||
- All tests passing"
|
||||
|
||||
$ bd close beadboard-pmt.1 --reason "Stripe account setup finished"
|
||||
|
||||
# Now pmt.2 becomes unblocked
|
||||
$ bd ready
|
||||
|
||||
beadboard-pmt.2 [task] pmt.2: Checkout UI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `bd create --title="..." --type=epic` | Create epic |
|
||||
| `bd create --title="epic.N: ..." --parent=beadboard-xxx` | Create task |
|
||||
| `bd dep add <blocked> <blocker>` | Set blocker dependency |
|
||||
| `bd dep relate <parent> <child>` | Set semantic relationship |
|
||||
| `bd ready` | List unblocked beads |
|
||||
| `bd update <id> --notes "..."` | Add evidence |
|
||||
| `bd close <id> --reason "..."` | Complete bead |
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
1. **Wrong naming**: `task-1` instead of `beadboard-abc.1`
|
||||
2. **Missing parent**: Tasks must have `--parent=beadboard-<epic>`
|
||||
3. **Closing before updating**: Always `update` first, then `close`
|
||||
4. **Wrong dep direction**: `bd dep add <blocked> <blocker>` (blocked first!)
|
||||
5. **Skipping evidence**: Always include command output in `--notes`
|
||||
|
|
@ -13,12 +13,12 @@ This document tracks high-impact coordination and environment failures for the B
|
|||
|
||||
## `BB_NOT_FOUND`
|
||||
|
||||
- Signal: `resolve-bb.mjs` or `bb-mail-shim.mjs` reports bb command missing.
|
||||
- Signal: `session-preflight.mjs` or `bb-mail-shim.mjs` reports bb command missing.
|
||||
- Cause: global BeadBoard CLI not installed, or not discoverable.
|
||||
- Recovery:
|
||||
- Install BeadBoard globally (`bb`/`beadboard` on `PATH`).
|
||||
- Re-run `node skills/beadboard-driver/scripts/resolve-bb.mjs`.
|
||||
- Re-run preflight.
|
||||
- Install BeadBoard globally (`bb`/`beadboard` on `PATH`) — see Bootstrap Step C in SKILL.md.
|
||||
- Run `node {baseDir}/scripts/setup-mail-delegate.mjs` to reconfigure the mail delegate after `bb` is installed.
|
||||
- Re-run preflight: `node {baseDir}/scripts/session-preflight.mjs`.
|
||||
|
||||
## `MAIL_DELEGATE_MISSING` / `BD_MAIL_DELEGATE_NOT_SET`
|
||||
|
||||
|
|
@ -33,10 +33,12 @@ This document tracks high-impact coordination and environment failures for the B
|
|||
|
||||
- Signal: `ensure-bb-mail-configured.mjs` fails contract checks.
|
||||
- Cause: delegate points to wrong command, missing shim path, or invalid `BB_AGENT` context.
|
||||
- Recovery:
|
||||
- Run session preflight to re-apply expected delegate command.
|
||||
- Set `BB_AGENT` explicitly.
|
||||
- Validate with `node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs`.
|
||||
- Recovery (in order):
|
||||
1. Check delegate is set: `bd config get mail.delegate`
|
||||
2. Verify shim path: the path shown must be absolute and the `bb-mail-shim.mjs` file must exist on disk
|
||||
3. Reconfigure if wrong/missing: `node {baseDir}/scripts/setup-mail-delegate.mjs`
|
||||
4. Verify `BB_AGENT` is set: `echo $BB_AGENT` (must be non-empty)
|
||||
5. Re-run verification: `node {baseDir}/scripts/ensure-bb-mail-configured.mjs` — expected: `ok: true`
|
||||
|
||||
## `DOLT_NOT_RUNNING`
|
||||
|
||||
|
|
@ -72,4 +74,4 @@ This document tracks high-impact coordination and environment failures for the B
|
|||
|
||||
- Do not write `.beads/issues.jsonl` directly.
|
||||
- Do not close beads without fresh evidence.
|
||||
- Do not bypass invalid `BB_REPO` values; fix configuration first.
|
||||
- Do not bypass a misconfigured mail delegate; fix configuration with `{baseDir}/scripts/setup-mail-delegate.mjs` first.
|
||||
|
|
|
|||
|
|
@ -7,8 +7,7 @@ This runbook is the minimum lifecycle contract for agents using BeadBoard Driver
|
|||
1. Run preflight and discovery checks:
|
||||
|
||||
```bash
|
||||
node skills/beadboard-driver/scripts/session-preflight.mjs
|
||||
node skills/beadboard-driver/scripts/resolve-bb.mjs
|
||||
node {baseDir}/scripts/session-preflight.mjs
|
||||
```
|
||||
|
||||
2. Create or identify your agent bead first (required before claiming work):
|
||||
|
|
@ -27,7 +26,8 @@ bd agent state <agent-bead-id> running
|
|||
4. Query hard memory for your domain before claim:
|
||||
|
||||
```bash
|
||||
bd query "label=memory AND label=mem-canonical AND label=mem-hard AND status=closed"
|
||||
# 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
|
||||
|
|
@ -100,7 +100,7 @@ bd agent state <agent-bead-id> stuck
|
|||
2. Coordination signal:
|
||||
|
||||
```bash
|
||||
bb agent send --from <agent-name> --to <target-agent-or-role> --bead <bead-id> --category BLOCKED --subject "<blocker summary>" --body "<what is needed>"
|
||||
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:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue