beads-dependency-management

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

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

Be specific: Use blocks only when truly necessary
Avoid over-linking: Don't create dependencies "just in case"
Update dependencies: Remove obsolete blockers
Document reasoning: Use issue descriptions to explain dependencies
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

beads-dependency-management

Beads Dependency Management

Overview

Dependency Types

1. blocks - Hard Blocker

2. related - Soft Association

3. parent-child - Hierarchy

4. discovered-from - Discovery Trail

Dependency Commands

Add Dependency

Remove Dependency

View Dependency Tree

Check for Cycles

Practical Patterns

Pattern 1: Epic with Ordered Subtasks

Pattern 2: Discovery-Driven Development

Pattern 3: Parallel Features with Shared Dependency

Pattern 4: Related Work Clusters

Dependency Queries

Find Blocked Issues

Find Ready Work

Trace Discovery Chain

View Epic Progress

Best Practices

Choosing Dependency Types

Avoiding Cycles

Dependency Hygiene

Common Pitfalls

Overusing blocks

Missing Discovery Links

Orphaned Subtasks

Related Skills

References

1. `blocks` - Hard Blocker

2. `related` - Soft Association

3. `parent-child` - Hierarchy

4. `discovered-from` - Discovery Trail

Overusing `blocks`