> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt > Use this file to discover all available pages before exploring further. # bd dep > Manage dependencies between issues ## Usage ```bash theme={null} bd dep [issue-id] [flags] bd dep add

bd dep remove

bd dep list bd dep tree 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. ```bash theme={null} bd dep add

[flags] ``` The dependent issue (the one that is blocked) The dependency (the blocker). Can be: * Local issue ID (e.g., `bd-xyz`) * External reference: `external::` Can also be specified via `--blocked-by` or `--depends-on` flag. Dependency type: `blocks`, `tracks`, `related`, `parent-child`, `discovered-from`, `until`, `caused-by`, `validates`, `relates-to`, `supersedes` Alternative to positional arg (same as `depends-on-id`) Alias for `--blocked-by` ### remove (rm) Remove a dependency. ```bash theme={null} bd dep remove

``` ### list List dependencies or dependents of an issue. ```bash theme={null} bd dep list [flags] ``` Direction: `down` (dependencies), `up` (dependents) Filter by dependency type ### tree Show dependency tree. ```bash theme={null} bd dep tree [flags] ``` Direction: `down` (dependencies), `up` (dependents), `both` (full graph) Maximum tree depth to display Filter to only show issues with this status Output format: `mermaid` for Mermaid.js flowchart Show all paths to nodes (no deduplication for diamond dependencies) ### cycles Detect dependency cycles. ```bash theme={null} bd dep cycles ``` ## Examples ### Add Dependencies ```bash Blocks Dependency theme={null} bd dep add bd-123 bd-124 --json # bd-123 depends on (is blocked by) bd-124 ``` ```bash Using --blocks Flag theme={null} bd dep bd-124 --blocks bd-123 --json # Equivalent: bd-124 blocks bd-123 ``` ```bash Using --blocked-by Flag theme={null} bd dep add bd-123 --blocked-by bd-124 --json ``` ```bash Parent-Child theme={null} bd dep add bd-123 bd-parent --type parent-child --json ``` ```bash Discovered-From theme={null} bd dep add bd-new-bug bd-investigation --type discovered-from --json ``` ### External Dependencies ```bash Cross-Project theme={null} bd dep add gt-xyz external:beads:mol-run-assignee --json # gt-xyz depends on beads project shipping mol-run-assignee capability ``` ```bash Remove External Dependency theme={null} bd dep remove gt-xyz external:beads:mol-run-assignee --json ``` ### List Dependencies ```bash What Blocks This Issue theme={null} bd dep list bd-123 --json # Default: down direction (dependencies) ``` ```bash What This Issue Blocks theme={null} bd dep list bd-123 --direction up --json ``` ```bash Filter by Type theme={null} bd dep list bd-123 --direction up --type tracks --json ``` ### Dependency Tree ```bash Show Blockers theme={null} bd dep tree bd-123 --json ``` ```bash Show Dependents theme={null} bd dep tree bd-123 --direction up --json ``` ```bash Full Graph theme={null} bd dep tree bd-123 --direction both --json ``` ```bash Filter by Status theme={null} bd dep tree bd-123 --status open --json ``` ```bash Mermaid Diagram theme={null} bd dep tree bd-123 --format mermaid ``` ### Cycle Detection ```bash Check for Cycles theme={null} bd dep cycles --json ``` ## JSON Output ### dep add ```json theme={null} { "status": "added", "issue_id": "bd-123", "depends_on_id": "bd-124", "type": "blocks" } ``` ### dep list ```json theme={null} [ { "id": "bd-124", "title": "Implement API endpoint", "status": "in_progress", "priority": 1, "dependency_type": "blocks" } ] ``` ### dep tree ```json theme={null} [ { "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 ```json theme={null} [ [ { "id": "bd-123", "title": "Issue A" }, { "id": "bd-124", "title": "Issue B" } ] ] ``` ## Dependency Types **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. **Hierarchical relationship**: Used for epics and subtasks. Child issues inherit the parent's completion dependency. Created automatically with `--parent` flag in `bd create`. **Discovery tracking**: Links newly discovered issues to their source investigation. Example: Bug found during feature development. **Tracking relationship**: Issue A tracks progress of Issue B (used in convoy patterns). **Informational link**: Issues are related but don't block each other. Bidirectional. Alias for `related` **Temporal dependency**: Issue A depends on B until a condition is met. **Causation tracking**: Issue A was caused by Issue B (e.g., bug caused by feature). **Validation relationship**: Issue A validates Issue B (e.g., test validates feature). **Replacement relationship**: Issue A replaces Issue B. ## External References External references allow cross-project dependencies: ### Format ``` external:: ``` ### Examples ```bash theme={null} # 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 ```mermaid theme={null} flowchart TD bd-123["☐ bd-123: Deploy feature"] bd-124["◧ bd-124: Run tests"] bd-125["☐ bd-125: Fix test data"] bd-126["☑ bd-126: Update docs"] bd-123 --> bd-124 bd-124 --> bd-125 bd-123 --> bd-126 ``` ## Cycle Detection Cycles hide issues from ready work and cause confusion: ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} # 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`](/cli/ready) - Find unblocked work * [`bd blocked`](/cli/ready#blocked) - Show blocked issues * [`bd create --deps`](/cli/create) - Create with dependencies * [`bd update --parent`](/cli/update) - Reparent issues