8.9 KiB
name, description
| name | description |
|---|---|
| beads-dependency-management | 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
- Be specific: Use
blocksonly 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 cyclesperiodically
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 commandsbeads-multi-session-patterns.md- Using dependencies in long-horizon tasksbeads-context-strategies.md- Preserving dependency context
References
- See
beads-context/references/beads_cli_reference.mdfor fullbd depcommand reference