Create Beads

Create Beads

Convert implementation plan into beads with dependencies so workers can claim and execute them.

Prerequisites

• Implementation plan exists at docs/plans/*-implementation.md
• bd CLI is available (check with which bd)
• If bd not initialized: bd init --prefix <project-name> --quiet

Process

1. Read the Implementation Plan

Find and read the most recent implementation plan:

ls -t docs/plans/*-implementation.md | head -1

Identify each ### Task N: section as a distinct unit of work.

2. Assess Scaffold Opportunities

Before creating task beads, analyze whether a foundational structure would unlock parallelism.

Scaffolds are:

• Module files with type definitions and function signatures (empty implementations)
• Directory structure and basic interfaces
• Test file skeletons with pending/skip markers
• Data schemas/structs that multiple tasks will use

Benefits:

• Workers can implement different functions independently once scaffold exists
• Easier merges (workers fill in pre-defined slots)
• Guidance (skeleton shows exactly where code goes)

Create scaffold bead if: Multiple tasks modify the same module, or tasks create interdependent types.

3. Assess Dependencies

Analyze the plan to determine task dependencies:

• File references: If Task 3 modifies a file Task 2 creates, Task 3 depends on Task 2
• Logical ordering: Tests for a feature depend on the feature existing
• Parallelization: Independent components can run simultaneously

Default to sequential if uncertain.

4. Create Beads

For scaffold (if identified):

bd create "Create module skeletons for <feature>" -d "Set up file structure and interfaces" -t task -p 1
# Note the returned bead ID (e.g., proj-abc1)

For each task:

bd create "Task N: <title from plan>" -d "<brief description>" -t task -p 2
# Note each returned bead ID

5. Wire Dependencies

# If scaffold exists, it blocks all first-level tasks
bd dep add <task1-id> <scaffold-id>
bd dep add <task2-id> <scaffold-id>

# Tasks block their dependents
bd dep add <task3-id> <task2-id>

6. Report the Dependency Graph

Output the created structure:

Created N beads from implementation plan:

Scaffold: proj-a1b2 - Create module skeletons
  |-- Task 1: proj-c3d4 - Implement user module
  |-- Task 2: proj-e5f6 - Implement auth module (parallel with Task 1)
      |-- Task 3: proj-g7h8 - Wire integration
          |-- Task 4: proj-i9j0 - Final verification

Ready to start: proj-a1b2 (Scaffold)

Verify with: bd ready

Error Handling

bd not initialized: Run bd init --prefix <project-name> --quiet first. Detect project name from directory.

bd routes to different database: If bd --verbose shows "Routing to target repo: ", the CLI has multi-repo routing configured. Either:

• Use --db .beads/beads.db to force local database
• Check that the target database has issue_prefix configured
• Or work with the routing as intended (beads go to planning repo)

Beads already exist for this plan: Check bd list for matching titles. Warn and ask whether to skip, update, or abort.

Plan has no clear task structure: Fall back to single bead for entire plan. Flag: "Could not identify distinct tasks."

Dependency analysis uncertain: Default to sequential. Add note: "Dependencies assumed sequential - review for parallelization."

Output

• Beads appear in bd ready for workers to claim
• BeadsWatcher detects .beads/issues.jsonl changes
• BeadsCoordinator spawns workers for ready beads