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
286 lines
6.4 KiB
Markdown
286 lines
6.4 KiB
Markdown
# 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`
|