workflow-beads-dependency-management

name	workflow-beads-dependency-management
description	bd dep add bd-15 bd-10 --type blocks

Beads Dependency Management

Use this skill when: Creating relationships between issues, managing blockers, or organizing work hierarchies

Overview

Beads supports four dependency types that create a directed graph of issue relationships. Understanding when to use each type is critical for effective issue tracking.

Dependency Types

1. blocks - Hard Blocker

Purpose: Prevents an issue from being "ready" until the blocker is closed

Use when: Implementation of X literally cannot proceed without Y being done first

# bd-15 cannot start until bd-10 is complete
bd dep add bd-15 bd-10 --type blocks

# bd-15 won't appear in `bd ready` until bd-10 is closed

Example Use Cases:

• Database schema must exist before migration
• Authentication system before protected endpoints
• Core library before dependent features
• Design approval before implementation

Graph Representation:

bd-10 --> bd-15  (bd-10 blocks bd-15)

2. related - Soft Association

Purpose: Creates context link without blocking

Use when: Two issues share context but don't block each other

# bd-20 and bd-18 are contextually related
bd dep add bd-20 bd-18 --type related

# Both can be worked on independently

Example Use Cases:

• Frontend and backend for same feature
• Documentation for related modules
• Related bug fixes in same area
• Alternative implementation approaches

Graph Representation:

bd-18 <--> bd-20  (bidirectional soft link)

3. parent-child - Hierarchy

Purpose: Creates epic/subtask relationships

Use when: Organizing work into epics and subtasks

# bd-25 is a subtask of epic bd-22
bd dep add bd-25 bd-22 --type parent-child

# Parent: bd-22 (epic)
# Child: bd-25 (subtask)

Example Use Cases:

• Feature epic with implementation subtasks
• Large refactoring broken into steps
• Release milestone with constituent tasks
• Research spike with exploration tasks

Graph Representation:

bd-22 (epic)
  ├─ bd-25 (subtask)
  ├─ bd-26 (subtask)
  └─ bd-27 (subtask)

4. discovered-from - Discovery Trail

Purpose: Tracks issues discovered during work on another issue

Use when: You find new work during execution and want to maintain the discovery chain

# bd-30 was discovered while working on bd-28
bd dep add bd-30 bd-28 --type discovered-from

# Preserves discovery context

Example Use Cases:

• Bug found during feature implementation
• Edge case discovered during testing
• Technical debt identified during refactoring
• Missing documentation found during review

Graph Representation:

bd-28 (working on) --> bd-30 (discovered)

Dependency Commands

Add Dependency

# General syntax
bd dep add <target-issue> <source-issue> --type <type>

# Examples
bd dep add bd-5 bd-3 --type blocks
bd dep add bd-10 bd-8 --type related
bd dep add bd-15 bd-12 --type parent-child
bd dep add bd-20 bd-18 --type discovered-from

Remove Dependency

bd dep remove bd-5 bd-3 --type blocks

View Dependency Tree

# Show all dependencies for an issue
bd dep tree bd-42

# Show specific dependency type
bd dep tree bd-42 --type blocks

Check for Cycles

# Detect circular dependencies
bd dep cycles

# Beads prevents invalid cycles when adding dependencies

Practical Patterns

Pattern 1: Epic with Ordered Subtasks

Create a feature epic with dependencies between subtasks:

# Create epic
bd create "Implement user authentication" -t epic -p 0 --json
# Returns: bd-100

# Create subtasks
bd create "Design auth schema" -t task -p 0 --json          # bd-101
bd create "Implement JWT tokens" -t task -p 1 --json        # bd-102
bd create "Add login endpoints" -t task -p 1 --json         # bd-103
bd create "Add auth middleware" -t task -p 2 --json         # bd-104

# Link to epic
bd dep add bd-101 bd-100 --type parent-child
bd dep add bd-102 bd-100 --type parent-child
bd dep add bd-103 bd-100 --type parent-child
bd dep add bd-104 bd-100 --type parent-child

# Chain dependencies
bd dep add bd-102 bd-101 --type blocks  # JWT depends on schema
bd dep add bd-103 bd-102 --type blocks  # Endpoints depend on JWT
bd dep add bd-104 bd-103 --type blocks  # Middleware depends on endpoints

# Result: Linear workflow within epic
# bd ready will show: bd-101 (first unblocked)

Pattern 2: Discovery-Driven Development

Track discovered work during execution:

# Working on refactoring
bd update bd-50 --status in_progress --json

# Discover issues during work
bd create "Fix user validation bug" -t bug -p 0 --json      # bd-51
bd dep add bd-51 bd-50 --type discovered-from

bd create "Add missing user tests" -t task -p 2 --json      # bd-52
bd dep add bd-52 bd-50 --type discovered-from

bd create "Update user documentation" -t task -p 3 --json   # bd-53
bd dep add bd-53 bd-50 --type discovered-from

# Now you have discovery trail: bd-50 -> bd-51, bd-52, bd-53
# Can work on any discovered issue independently

Pattern 3: Parallel Features with Shared Dependency

Multiple features depend on same foundation:

# Foundation
bd create "Build base API client" -t task -p 0 --json       # bd-200

# Dependent features
bd create "User profile feature" -t feature -p 1 --json     # bd-201
bd create "Settings feature" -t feature -p 1 --json         # bd-202
bd create "Dashboard feature" -t feature -p 1 --json        # bd-203

# All features blocked by foundation
bd dep add bd-201 bd-200 --type blocks
bd dep add bd-202 bd-200 --type blocks
bd dep add bd-203 bd-200 --type blocks

# Result: Complete bd-200, then all features become ready

Pattern 4: Related Work Clusters

Group related issues without blocking:

# Create related issues
bd create "Frontend: User profile UI" -t task -p 1 --json   # bd-300
bd create "Backend: User profile API" -t task -p 1 --json   # bd-301
bd create "Docs: User profile guide" -t task -p 3 --json    # bd-302

# Link as related (no blocking)
bd dep add bd-300 bd-301 --type related
bd dep add bd-300 bd-302 --type related
bd dep add bd-301 bd-302 --type related

# Result: All show as ready, can be worked on in any order
# But context is preserved between related issues

Dependency Queries

Find Blocked Issues

# List issues that are blocked
bd list --status blocked --json

# Show what's blocking an issue
bd dep tree bd-50 | grep "blocks"

Find Ready Work

# Ready work = no blocking dependencies
bd ready --json --limit 10

# Ready work for specific priority
bd ready --priority 0 --json

Trace Discovery Chain

# Find all issues discovered from bd-X
bd dep tree bd-50 --type discovered-from

View Epic Progress

# Show all subtasks of epic
bd dep tree bd-100 --type parent-child

# Filter by status
bd list --json | jq '.[] | select(.parent == "bd-100")'

Best Practices

Choosing Dependency Types

SITUATION                                   → DEPENDENCY TYPE
─────────────────────────────────────────────────────────────
X must complete before Y can start          → blocks
X and Y are related but independent         → related
Y is subtask of epic X                      → parent-child
Y was discovered while working on X         → discovered-from

Avoiding Cycles

Beads prevents cycles in blocks dependencies, but be mindful:

# INVALID - creates cycle
bd dep add bd-10 bd-5 --type blocks
bd dep add bd-5 bd-10 --type blocks  # Error: would create cycle

# VALID - use related instead
bd dep add bd-10 bd-5 --type related
bd dep add bd-5 bd-10 --type related

Dependency Hygiene

1. Be specific: Use blocks only when truly necessary
2. Avoid over-linking: Don't create dependencies "just in case"
3. Update dependencies: Remove obsolete blockers
4. Document reasoning: Use issue descriptions to explain dependencies
5. Review regularly: Check bd dep cycles periodically

Common Pitfalls

Overusing blocks

Problem: Everything blocks everything, nothing is ready

Solution: Reserve blocks for hard dependencies. Use related for soft associations.

Missing Discovery Links

Problem: Lose context of why work was created

Solution: Always link discovered work with discovered-from

Orphaned Subtasks

Problem: Subtasks not linked to parent epic

Solution: Always create parent-child link when breaking down epics

Related Skills

• beads-workflow.md - Core bd CLI commands
• beads-multi-session-patterns.md - Using dependencies in long-horizon tasks
• beads-context-strategies.md - Preserving dependency context

References

• See beads-context/references/beads_cli_reference.md for full bd dep command reference