Skip to content

Dependencies & Epics

Dependencies

Specs can declare dependencies on other specs. Dependencies are declared in the FR front matter:

deps: [002, 003]

Managing Dependencies

nspec dep add --to S001 --dep S002    # S001 depends on S002
nspec dep remove --to S001 --dep S002

Via MCP:

add_dep(spec_id="S001", dep_id="S002")
remove_dep(spec_id="S001", dep_id="S002")

Validation

The dependency layer validates:

  • No circular references — Cycles are detected and reported
  • No dangling dependencies — References to non-existent specs are flagged
  • Ordering — Specs are ordered so dependencies come before dependents
  • Cross-epic resolution — Dependencies across epic boundaries are resolved correctly

Blocked Specs

A spec is blocked when any of its dependencies are not yet completed. The MCP tool blocked_specs lists all currently blocked specs with their blocking dependencies.

Visualizing dependencies in the TUI

The detail view (press Enter on a spec in nspec tui) renders the dependency graph around the selected spec. See the TUI guide for the full keybindings; the concepts it surfaces are:

  • Upstream vs. downstream. Two always-visible sections frame every spec: Upstream Dependencies (what this spec depends on) and Downstream Dependents (what depends on this spec). Navigate between them with ←/h (upstream) and →/l (downstream).
  • Direct vs. transitive (indirect). Directly declared dependencies are listed first. Dependencies reached through the chain — A → B → C makes C an indirect dependency of A — follow them, tagged (indirect). The walk is breadth-first and cycle-safe, so even tangled graphs render without looping.
  • Health highlighting. Each line carries inline markers:
  • (blocked) — the dependency is itself blocked (one of its deps is incomplete).
  • (cycle) — this spec and the dependency are mutually reachable, i.e. a dependency cycle.

Long sections show the first 5 entries with a ... +N more (press 'd' to expand) hint; press d to expand. Dependencies can be added (a) or removed (r) inline from this view.

The (blocked) marker is per-dependency: it flags a listed dependency that is itself blocked — one that blocked_specs would report because one of its own upstream deps is incomplete. It describes the health of that link in the chain, not the selected spec's own status. (The selected spec is, by the same rule, blocked whenever any of its direct upstream dependencies is incomplete — but that is the spec's state, not what this inline marker shows.)

Epics

Epics group related specs. Epic membership is determined by ID ranges configured per epic.

Viewing Epics

# Via CLI
nspec dashboard

Via MCP:

epics()         # List all epics with progress
get_epic()      # Currently active epic

Epic Priorities

Epic priorities must be unique. Use swap_priority to reorder epics without conflicts:

swap_priority(epic_a="E001", epic_b="E002")

Moving Specs Between Epics

nspec dep move --to E002 --dep S042

Parking an Epic

Park all non-completed specs in an epic at once:

park_epic(epic_id="E005")

Dependency Graph

The dep_graph MCP tool returns the full dependency graph for an epic, showing which specs block which and the current completion status.

dep_graph(epic_id="E001")