beadboard/skills/beadboard-driver/references/creating-beads.md

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.

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.

# 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

# 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:

# 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):

# 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

bd dep list beadboard-xyz          # Show all dependencies
bd ready                           # Show unblocked, ready-to-start beads

---

Writing Descriptions

Every bead description MUST include:

**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

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

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

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

$ 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

$ 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

# 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

$ bd ready

beadboard-pmt.1  [task]   pmt.1: Stripe account setup

Only pmt.1 is ready—pmt.2 is blocked.

5. Create Subtask

$ 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

# 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