/dependency-manager

name: dependency-manager
description: "Visualizes, creates, and diagnoses dependencies between MCP work items. Use when a user says: what blocks this, add a dependency, show dependency graph, why can't this start, link these items, unblock this, remove dependency, or show blockers."
argument-hint: "[optional: item UUID, title, or action like 'show blockers for X']"

dependency-manager — Dependency Visualization, Creation, and Diagnosis

Manage BLOCKS, IS_BLOCKED_BY, and RELATES_TO edges between work items. Handles all four paths: view existing dependencies, create new edges, delete edges, and diagnose why items cannot start.

---

Step 1: Determine Intent

Classify the user request before making any tool calls.

Resolve `$ARGUMENTS` to a UUID via `query_items` search (`operation="search"`, `query=$ARGUMENTS`, `limit=5`); if ambiguous, present matches via `AskUserQuestion`. If `$ARGUMENTS` is already a UUID, default intent to VIEW for that item.

**If `$ARGUMENTS` is empty**, infer intent from the surrounding conversation. If intent is still unclear, ask via `AskUserQuestion`: "What would you like to do with dependencies? Options: view, create, delete, diagnose."

**Compound requests** (e.g., "show what blocks this and remove the dependency"): handle the VIEW path first, then proceed to the second action using the results.

**Intent signal words:**

| Signal words | Path | |---|---| | "show", "view", "graph", "what blocks", "what depends on", "visualize" | VIEW (Step 2) | | "add", "create", "link", "connect", "chain", "depend on" | CREATE (Step 3) | | "remove", "delete", "unlink", "disconnect" | DELETE (Step 4) | | "why can't this start", "why is this blocked", "diagnose", "show blockers", "unblock" | DIAGNOSE (Step 5) |

---

Step 2: View Dependencies

Once you have an item ID and intent is VIEW, query its dependency edges:

query_dependencies(operation="get", itemId="<uuid>", direction="all", includeItemInfo=true)

Format the result as an ASCII tree:

◉ Design API schema (work)
  ↳ BLOCKS → ○ Implement data models (queue)
  ↳ BLOCKS → ○ Build REST endpoints (queue)
  ← BLOCKED BY → ◉ Finalize data contract (work)

Use the visual symbols to indicate role at a glance:

| Symbol | Role | |---|---| | ✓ | terminal | | ◉ | work or review | | ○ | queue | | ⊘ | blocked |

**Direction parameter meanings:**

| Value | Returns | |---|---| | `outgoing` | Edges where this item is the source (things this item blocks) | | `incoming` | Edges where this item is the target (things that block this item) | | `all` | Both directions combined |

For a full chain view (ancestors and descendants beyond immediate neighbors), add `neighborsOnly=false`:

query_dependencies(operation="get", itemId="<uuid>", direction="all", includeItemInfo=true, neighborsOnly=false)

This performs BFS traversal and returns the full dependency graph. Use it when the user asks to "show the full chain" or "trace all blockers."

After displaying the tree, note any items in `⊘ blocked` state and offer to run DIAGNOSE (Step 5) on them.

---

Step 3: Create Dependencies

Identify the structure from what the user described, then select the right creation pattern.

**Decision tree:**

Two specific items to link → single edge (dependencies array)
Three or more items in a sequence (A then B then C) → linear pattern
One item that blocks many others → fan-out pattern
Many items that all block one item → fan-in pattern

**Pattern reference:**

| Pattern | Key parameter | When to use | |---|---|---| | Single edge | `dependencies=[{fromItemId, toItemId}]` | Link exactly two items | | `linear` | `itemIds=[A, B, C, D]` | Sequential chain: A→B→C→D | | `fan-out` | `fromItemId=A`, `toItemIds=[B, C, D]` | One item blocks many | | `fan-in` | `fromItemIds=[A, B, C]`, `toItemId=D` | Many items block one |

Confirm the derived edges with the user before creating. Show them what you're about to create in a readable way, for example:

About to create: A → B → C → D as a linear chain. Proceed?

Adjust the format to fit the actual pattern (single edge, fan-out, fan-in, etc.).

Then call `manage_dependencies(operation="create")` with the selected pattern:

manage_dependencies(
  operation="create",
  pattern="linear",
  itemIds=["<uuid-a>", "<uuid-b>", "<uuid-c>", "<uuid-d>"]
)

For a single edge or custom edges, use the `dependencies` array directly:

manage_dependencies(
  operation="create",
  dependencies=[
    { fromItemId: "<uuid-a>", toItemId: "<uuid-b>", type: "BLOCKS" }
  ]
)

After creation, show the edges created:

✓ Created 3 dependency edges:
  A → BLOCKS → B
  B → BLOCKS → C
  C → BLOCKS → D

To set a partial unblock threshold (so the blocked item unblocks before the blocker is terminal), include `unblockAt` in the dependency spec. See the `unblockAt` reference table below.

---

Step 4: Delete Dependencies

Query existing edges first so the user knows what can be deleted:

query_dependencies(operation="get", itemId="<uuid>", direction="all", includeItemInfo=true)

Present the edges to the user:

Existing edges for "Implement data models":
  [1] ◉ Design API schema → BLOCKS → this item  (dep-uuid-1)
  [2] this item → BLOCKS → ○ Build REST endpoints  (dep-uuid-2)

Which edge(s) would you like to remove?

Confirm before deleting. Then call `manage_dependencies(operation="delete")` using the appropriate mode:

manage_dependencies(operation="delete", dependencyId="<dep-uuid>")

**Delete parameter modes:**

| Mode | Parameters | When to use | |---|---|---| | By dependency ID | `id="<dep-uuid>"` | Delete one specific edge (most precise) | | By relationship | `fromItemId="<uuid>", toItemId="<uuid>"` | Delete the edge between two known items | | By relationship + type | `fromItemId, toItemId, type="BLOCKS"` | When multiple edge types exist between same pair | | All edges for item | `fromItemId="<uuid>", deleteAll=true` | Remove all outgoing edges