bd dep

Manage dependencies between issues

Usage

bd dep [issue-id] [flags]
bd dep add <issue-id> <depends-on-id>
bd dep remove <issue-id> <depends-on-id>
bd dep list <issue-id>
bd dep tree <issue-id>
bd dep cycles

Description

Manage dependencies between issues. Dependencies define blocking relationships, parent-child hierarchies, and other issue connections.

Subcommands

add

Add a dependency between two issues.

bd dep add <issue-id> <depends-on-id> [flags]

issue-id · string · required

The dependent issue (the one that is blocked)

depends-on-id · string · required

The dependency (the blocker). Can be:

• Local issue ID (e.g., bd-xyz)
• External reference: external:<project>:<capability> Can also be specified via --blocked-by or --depends-on flag.

--type · string · default: "blocks"

Dependency type: blocks, tracks, related, parent-child, discovered-from, until, caused-by, validates, relates-to, supersedes

--blocked-by · string

Alternative to positional arg (same as depends-on-id)

--depends-on · string

Alias for --blocked-by

remove (rm)

Remove a dependency.

bd dep remove <issue-id> <depends-on-id>

list

List dependencies or dependents of an issue.

bd dep list <issue-id> [flags]

--direction · string · default: "down"

Direction: down (dependencies), up (dependents)

--type · string

Filter by dependency type

tree

Show dependency tree.

bd dep tree <issue-id> [flags]

--direction · string · default: "down"

Direction: down (dependencies), up (dependents), both (full graph)

--max-depth · integer · default: "50"

Maximum tree depth to display

--status · string

Filter to only show issues with this status

--format · string

Output format: mermaid for Mermaid.js flowchart

--show-all-paths · boolean

Show all paths to nodes (no deduplication for diamond dependencies)

cycles

Detect dependency cycles.

bd dep cycles

Examples

Add Dependencies

Blocks Dependency

bd dep add bd-123 bd-124 --json
# bd-123 depends on (is blocked by) bd-124

External Dependencies

Cross-Project

bd dep add gt-xyz external:beads:mol-run-assignee --json
# gt-xyz depends on beads project shipping mol-run-assignee capability

List Dependencies

What Blocks This Issue

bd dep list bd-123 --json
# Default: down direction (dependencies)

Dependency Tree

Show Blockers

bd dep tree bd-123 --json

Cycle Detection

Check for Cycles

bd dep cycles --json

JSON Output

dep add

{
  "status": "added",
  "issue_id": "bd-123",
  "depends_on_id": "bd-124",
  "type": "blocks"
}

dep list

[
  {
    "id": "bd-124",
    "title": "Implement API endpoint",
    "status": "in_progress",
    "priority": 1,
    "dependency_type": "blocks"
  }
]

dep tree

[
  {
    "id": "bd-123",
    "title": "Deploy feature",
    "status": "open",
    "priority": 1,
    "depth": 0,
    "parent_id": "",
    "truncated": false
  },
  {
    "id": "bd-124",
    "title": "Run tests",
    "status": "in_progress",
    "priority": 1,
    "depth": 1,
    "parent_id": "bd-123",
    "truncated": false
  }
]

dep cycles

[
  [
    {
      "id": "bd-123",
      "title": "Issue A"
    },
    {
      "id": "bd-124",
      "title": "Issue B"
    }
  ]
]

Dependency Types

blocks

Blocking relationship: Issue A depends on (is blocked by) Issue B. Issue A cannot be closed until B is closed.

Default type when not specified.

parent-child

Hierarchical relationship: Used for epics and subtasks. Child issues inherit the parent’s completion dependency.

Created automatically with --parent flag in bd create.

discovered-from

Discovery tracking: Links newly discovered issues to their source investigation.

Example: Bug found during feature development.

tracks

Tracking relationship: Issue A tracks progress of Issue B (used in convoy patterns).

related

Informational link: Issues are related but don’t block each other. Bidirectional.

relates-to

Alias for related

until

Temporal dependency: Issue A depends on B until a condition is met.

caused-by

Causation tracking: Issue A was caused by Issue B (e.g., bug caused by feature).

validates

Validation relationship: Issue A validates Issue B (e.g., test validates feature).

supersedes

Replacement relationship: Issue A replaces Issue B.

External References

External references allow cross-project dependencies:

Format

external:<project>:<capability>

Examples

# gastown depends on beads shipping a capability
bd dep add gt-xyz external:beads:mol-run-assignee

# beads depends on gastown feature
bd dep add bd-abc external:gastown:agent-dispatch

Resolution

External refs are resolved at query time using routes.jsonl configuration:

1. Check if capability is “shipped” in target project
2. Block if not shipped
3. Unblock when shipped

External refs are stored as-is in the database. The external_projects config maps project names to their database locations.

Tree Visualization

Terminal Output

🌲 Dependency tree for bd-123:

bd-123: Deploy feature [P1] (open) [BLOCKED]
├── bd-124: Run tests [P1] (in_progress)
│   └── bd-125: Fix test data [P2] (open)
└── bd-126: Update docs [P3] (closed) ✓

Mermaid Diagram

Cycle Detection

Cycles hide issues from ready work and cause confusion:

bd dep cycles

Output:

⚠ Found 1 dependency cycles:

1. Cycle involving:
   - bd-123: Issue A
   - bd-124: Issue B
   - bd-125: Issue C

Run 'bd dep tree bd-123' to visualize.

Cycles prevent issues from appearing in bd ready even if they should be unblocked. Fix by removing one dependency in the cycle.

Anti-Patterns

Child→Parent Dependency

bd dep add bd-abc.1 bd-abc
# Error: bd-abc.1 is already a child of bd-abc
# Adding explicit dependency creates deadlock

Children inherit parent completion dependency via hierarchy. Explicit dependency creates:

• Child can’t start (parent open)
• Parent can’t close (children not done)
• Deadlock!

Best Practices

For Agents

1. Use discovered-from to link bugs found during work
2. Check cycles after adding dependencies
3. Use external refs for cross-project dependencies
4. Verify dependencies exist before adding

For Humans

1. Keep dependency types semantic (blocks for blocking, tracks for tracking)
2. Use parent-child for true hierarchies
3. Avoid deep trees (>5 levels) - flatten if possible
4. Document external refs in issue description

Dependency Hygiene

# Before closing an issue, check what it blocks
bd dep list bd-123 --direction up --json

# After closing, verify nothing is wrongly blocked
bd blocked --json

Related Commands

• bd ready - Find unblocked work
• bd blocked - Show blocked issues
• bd create --deps - Create with dependencies
• bd update --parent - Reparent issues