# Creating and Managing Beads Complete guide for agents on bead creation, naming, dependencies, and workflow. --- ## Bead Naming Format (CRITICAL) | Level | Format | Example | |-------|--------|---------| | **Epic** | `beadboard-` | `beadboard-abc` | | **Task** | `beadboard-.x` | `beadboard-abc.1` | | **Subtask** | `beadboard-.x.x` | `beadboard-abc.1.2` | **Rules:** - `` 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 ` | Set blocker dependency | | `bd dep relate ` | Set semantic relationship | | `bd ready` | List unblocked beads | | `bd update --notes "..."` | Add evidence | | `bd close --reason "..."` | Complete bead | --- ## Common Mistakes 1. **Wrong naming**: `task-1` instead of `beadboard-abc.1` 2. **Missing parent**: Tasks must have `--parent=beadboard-` 3. **Closing before updating**: Always `update` first, then `close` 4. **Wrong dep direction**: `bd dep add ` (blocked first!) 5. **Skipping evidence**: Always include command output in `--notes`