Skip to main content

Dependencies

Manage relationships between specs with LeanSpec's dependency tracking.

Overview​

LeanSpec has two types of relationships:

related - Bidirectional Soft Reference​

  • Meaning: Informational relationship (specs are connected/related)
  • Behavior: Automatically shown from both sides
  • Symbol: ⟷ (bidirectional arrow)

depends_on - Directional Blocking Dependency​

  • Meaning: Hard dependency - spec cannot start until dependencies complete
  • Behavior: Directional only (shows differently from each side)
  • Symbol: → (depends on) and ← (blocks)

Use related for informational connections:

# In spec 042
related: [043, 044]

Both sides see the relationship:

$ lean-spec deps 042
Related Specs:
  ⟷ 043-feature-launch [in-progress]
  ⟷ 044-api-update [planned]

$ lean-spec deps 043
Related Specs:
  ⟷ 042-error-handling [complete]  # Automatically shown!

Use when:

  • Specs cover related topics or features
  • Work is coordinated but not blocking
  • Context is helpful but not required

Blocking Dependencies​

Use depends_on for hard dependencies:

# Spec A depends on Spec B
# In spec A
depends_on: [spec-b]

Shows differently from each side:

$ lean-spec deps spec-a
Depends On:
  → spec-b [in-progress]  # A depends on B

$ lean-spec deps spec-b
Required By:
  ← spec-a [planned]  # B is required by A

Use when:

  • Spec truly cannot start until another completes
  • There's a clear dependency chain
  • Work must be done in specific order

Deps Command​

View all relationships for a spec:

lean-spec deps <spec>

Shows:

  • Specs this depends on (→)
  • Specs that depend on this (←)
  • Related specs (⟷)

Example Output​

🔗 Dependencies for 043-feature-launch

Depends On:
  → 042-error-handling [complete] ✅
  → 041-api-design [complete] ✅

Required By:
  ← 044-integration-test [planned]
  ← 045-documentation [planned]

Related Specs:
  ⟷ 040-performance [in-progress]
  ⟷ 039-security-audit [complete]

Status: Ready to start (all dependencies complete)

Best Practices​

Most relationships are informational, not blocking:

# ✅ Good - Related specs for context
related: [feature-a, feature-b]

# ❌ Overuse - Not a true blocking dependency
depends_on: [documentation-spec]

2. Reserve depends_on for True Blockers​

Only use when work truly cannot start:

# ✅ Good - API must exist before integration
depends_on: [api-implementation]

# ❌ Bad - These can be done in parallel
depends_on: [docs-update]

3. Avoid Circular Dependencies​

# ❌ Bad - Circular dependency
# Spec A
depends_on: [spec-b]

# Spec B
depends_on: [spec-a]

LeanSpec will warn about circular dependencies.

4. Update Once, Show Everywhere​

related only needs to be in one spec:

# ✅ Good - Only in spec A
# Spec A
related: [spec-b]

# Spec B - no need to list A
# (relationship automatically shown)

Workflows​

Before Starting Work​

Check dependencies:

lean-spec deps <spec>

Ensure all depends_on specs are complete before starting.

During Planning​

Map relationships:

# View related work
lean-spec deps feature-spec

# Check what's blocked
lean-spec board --status planned

Identifying Bottlenecks​

Find specs blocking others:

# Check what depends on this
lean-spec deps <in-progress-spec>

# Look for "Required By" items

Dependency Patterns​

Sequential Work​

# Phase 1
status: complete

# Phase 2
depends_on: [phase-1]
status: in-progress

# Phase 3
depends_on: [phase-2]
status: planned

Parallel Work with Coordination​

# Feature A
related: [feature-b, feature-c]

# Feature B
related: [feature-a, feature-c]

# Feature C
related: [feature-a, feature-b]

Integration Point​

# Core Feature
status: in-progress

# Tests (blocked until feature done)
depends_on: [core-feature]

# Docs (can start early, related)
related: [core-feature]

Managing Changes​

Adding Dependencies​

# Before
status: planned

# After
depends_on: [prerequisite-spec]
status: planned  # Can't start until dependency complete

Removing Dependencies​

When a dependency is no longer needed:

# Before
depends_on: [old-requirement]

# After
# (remove depends_on or replace with related)
related: [old-requirement]

Tips​

  • Check dependencies before starting work
  • Use related for most connections
  • Only use depends_on for true blockers
  • Update relationships as you learn
  • Review dependency chains during planning
  • Avoid long dependency chains (breaks parallel work)

Learning More​