Features
Dependency Management

Dependency Management

Track relationships, detect bottlenecks, and visualize work unit dependencies.

Dependency management creates an explicit graph of how work units relate to each other. It tracks which work blocks other work, identifies bottlenecks, detects circular dependencies, and helps AI suggest logical dependency relationships based on work unit content.

The Problem: Hidden Dependencies

Without explicit dependency tracking, work units have invisible relationships:

AUTH-001 (User login) needs AUTH-002 (Session management) to be done first
But nowhere is this relationship documented.

Result:
- Work starts in wrong order
- Blocked work sits idle
- Circular dependencies discovered too late
- No visibility into critical path

The result: Inefficient sequencing, wasted effort, missed dependencies, project delays.

How Dependencies Work

Dependencies create a directed graph between work units with four relationship types:

Four Relationship Types:

  1. blocks / blockedBy: Bidirectional hard blocker (A blocks B ↔ B blockedBy A)
  2. dependsOn: Unidirectional soft dependency (A depends on B)
  3. relatesTo: Bidirectional informational link (A relates to B ↔ B relates to A)
  4. Auto-inverse: System maintains both directions automatically

Relationship Types Explained

blocks / blockedBy (Bidirectional)

Meaning: Hard blocker. Blocked work CANNOT start until blocking work is done.

How it works: When you add A blocks B, the system automatically adds B blockedBy A.

Use cases:

  • Sequential implementation (database schema before API endpoints)
  • Infrastructure before features (auth system before user management)
  • Critical path dependencies

Example:

fspec add-dependency AUTH-001 --blocks AUTH-002

Result:

AUTH-001 blocks AUTH-002
AUTH-002 blockedBy AUTH-001

AUTH-002 cannot start until AUTH-001 is done.

Natural language:

"AUTH-001 must be completed before AUTH-002 can begin."
"AUTH-002 is blocked by AUTH-001."

dependsOn (Unidirectional)

Meaning: Soft dependency. Dependent work SHOULD wait but CAN start if needed.

How it works: Only creates one-way relationship. Does NOT auto-create inverse.

Use cases:

  • Suggested ordering (feature should wait for tests)
  • Best practices (UI should wait for API design)
  • Preference, not requirement

Example:

fspec add-dependency AUTH-003 --depends-on AUTH-001

Result:

AUTH-003 dependsOn AUTH-001

AUTH-003 should ideally wait for AUTH-001, but can proceed if necessary.

Natural language:

"AUTH-003 depends on AUTH-001 being done first (preferred)."

relatesTo (Bidirectional)

Meaning: Informational link. No ordering, just related work.

How it works: When you add A relatesTo B, system automatically adds B relatesTo A.

Use cases:

  • Similar work units (same component)
  • Cross-references (bug fix relates to feature)
  • Knowledge sharing (developers should be aware)

Example:

fspec add-dependency AUTH-004 --relates-to DASH-001

Result:

AUTH-004 relatesTo DASH-001
DASH-001 relatesTo AUTH-004

These work units are related but no dependency ordering.

Natural language:

"AUTH-004 and DASH-001 are related (same system component)."

Circular Dependency Detection

The system automatically detects circular dependencies using depth-first search (DFS):

How Cycle Detection Works

Algorithm: Depth-First Search (DFS) with visited node tracking

Process:

  1. Start at work unit A
  2. Traverse all dependencies recursively
  3. Track visited nodes
  4. If we return to A during traversal → CYCLE DETECTED

Example cycle:

AUTH-001 blocks AUTH-002
AUTH-002 blocks AUTH-003
AUTH-003 blocks AUTH-001  ← Would create cycle!

Detection output:

❌ Cannot add dependency: Circular dependency detected

Cycle path:
  AUTH-001 → AUTH-002 → AUTH-003 → AUTH-001

This would create an impossible dependency chain.

To fix:
1. Remove one of the blocking relationships
2. Reorder work units
3. Use dependsOn (soft) instead of blocks (hard)

When Cycles Are Detected

blocks / blockedBy: ALWAYS rejected (hard blockers cannot have cycles)

dependsOn: WARNED but allowed (soft dependencies can have cycles)

relatesTo: ALLOWED (informational, no ordering)

Example:

# This will be REJECTED
fspec add-dependency AUTH-001 --blocks AUTH-002
fspec add-dependency AUTH-002 --blocks AUTH-003
fspec add-dependency AUTH-003 --blocks AUTH-001
 
❌ Error: Circular dependency detected
 
# This will be WARNED
fspec add-dependency AUTH-001 --depends-on AUTH-002
fspec add-dependency AUTH-002 --depends-on AUTH-001
 
⚠️  Warning: Circular soft dependency detected
   This is allowed but may indicate design issue

Bottleneck Identification

Bottlenecks are work units that block many other units:

What Is a Bottleneck?

Definition: A work unit that blocks multiple other work units.

Impact: If bottleneck is delayed, ALL dependent work is delayed.

Calculation:

Bottleneck Score = Count of 'blocks' relationships

Querying Bottlenecks

fspec query bottlenecks

Output:

🚨 Bottleneck Analysis

High Priority Bottlenecks (blocks 3+ units):

1. AUTH-001: Authentication Core (blocks 5 units)
   Blocks:
   - AUTH-002: User Login
   - AUTH-003: Password Reset
   - AUTH-004: OAuth Integration
   - AUTH-005: Two-Factor Auth
   - AUTH-006: Session Management

   Impact: 5 work units cannot start until AUTH-001 is complete
   Recommendation: Prioritize AUTH-001 immediately

2. DB-001: Database Schema (blocks 4 units)
   Blocks:
   - API-001, API-002, API-003, API-004

   Impact: 4 API endpoints waiting
   Recommendation: Fast-track DB-001

Medium Priority Bottlenecks (blocks 2 units):

3. INFRA-001: CI/CD Setup (blocks 2 units)
   Blocks:
   - DEPLOY-001, DEPLOY-002

Summary:
- Total bottlenecks: 3
- Total blocked work: 11 units
- Critical path: AUTH-001 → 5 units

AI Bottleneck Suggestions

AI can suggest prioritization based on bottlenecks:

YOU: "What should I work on next?"

AI: Analyzing dependency graph...

    🚨 Critical bottleneck detected: AUTH-001

    AUTH-001 blocks 5 other work units:
    - AUTH-002 (User Login)
    - AUTH-003 (Password Reset)
    - AUTH-004 (OAuth)
    - AUTH-005 (2FA)
    - AUTH-006 (Sessions)

    Recommendation: Prioritize AUTH-001 immediately to unblock 5 units.

    If you complete AUTH-001 now, you unlock 40% of authentication work.

Natural Language Workflows

Scenario 1: Adding Dependencies During Planning

YOU: "Create stories for authentication. The login feature needs session management first."

AI: Creating authentication stories...
    fspec create-story "Session management" --prefix AUTH
    ✓ Created AUTH-001

    fspec create-story "User login" --prefix AUTH
    ✓ Created AUTH-002

    Adding dependency (AUTH-002 depends on AUTH-001)...
    fspec add-dependency AUTH-002 --depends-on AUTH-001

    ✓ Added dependency: AUTH-002 dependsOn AUTH-001

    Now the system knows AUTH-002 should wait for AUTH-001.

YOU: "Actually, login cannot start until sessions are done. Make it a hard blocker."

AI: Converting soft dependency to hard blocker...
    fspec remove-dependency AUTH-002 --depends-on AUTH-001
    fspec add-dependency AUTH-001 --blocks AUTH-002

    ✓ Updated: AUTH-001 blocks AUTH-002 (bidirectional)

    AUTH-002 is now blocked and cannot start until AUTH-001 is complete.

Scenario 2: Detecting Circular Dependencies

YOU: "Create these dependencies:
     AUTH-001 blocks AUTH-002
     AUTH-002 blocks AUTH-003
     AUTH-003 blocks AUTH-001"

AI: Adding dependencies...
    fspec add-dependency AUTH-001 --blocks AUTH-002
    ✓ Added: AUTH-001 blocks AUTH-002

    fspec add-dependency AUTH-002 --blocks AUTH-003
    ✓ Added: AUTH-002 blocks AUTH-003

    fspec add-dependency AUTH-003 --blocks AUTH-001

    ❌ Error: Circular dependency detected

    Cycle path:
      AUTH-001 → AUTH-002 → AUTH-003 → AUTH-001

    This would create an impossible dependency chain.

AI: I detected a circular dependency. This isn't physically possible.

    Let me suggest a fix:
    - AUTH-001: Database schema (foundational)
    - AUTH-002: Login logic (depends on schema)
    - AUTH-003: Login UI (depends on logic)

    Correct dependency chain:
    AUTH-001 → AUTH-002 → AUTH-003 (linear, no cycle)

    Should I set it up this way instead?

YOU: "Yes, do that."

AI: Removing circular dependency and creating linear chain...
    fspec remove-dependency AUTH-003 --blocks AUTH-001

    ✓ Correct dependency structure established
    ✓ No circular dependencies

Scenario 3: Identifying Bottlenecks

YOU: "Show me what's blocking our progress."

AI: Analyzing dependency graph for bottlenecks...
    fspec query bottlenecks

🚨 Bottleneck Analysis

Critical Bottleneck Detected:

AUTH-001: Authentication Core (blocks 5 units)
  Status: implementing
  Blocks:
  - AUTH-002: User Login
  - AUTH-003: Password Reset
  - AUTH-004: OAuth
  - AUTH-005: 2FA
  - AUTH-006: Sessions

Impact: 5 work units (40% of authentication work) blocked

Recommendation: AUTH-001 is the critical path. Prioritize completion.

YOU: "How can we unblock this?"

AI: Options to unblock AUTH-001 bottleneck:

    1. Fast-track AUTH-001 (BEST)
       Complete AUTH-001 ASAP to unblock all 5 units

    2. Reorder dependencies
       Identify which units truly need AUTH-001 done
       Convert hard blocks to soft dependsOn where possible

    3. Parallelize work
       If AUTH-001 has sub-tasks, complete core first
       Allows some blocked work to start earlier

    Which approach should we take?

YOU: "Fast-track it."

AI: Moving AUTH-001 to high priority...
    fspec update-work-unit AUTH-001 --tags @high-priority @critical-path

    ✓ AUTH-001 marked as critical path
    ✓ Team can focus on unblocking 5 units

Scenario 4: AI Dependency Suggestions

YOU: "I created AUTH-007 for logout functionality. What dependencies should it have?"

AI: Analyzing AUTH-007 content for dependency suggestions...
    fspec suggest-dependencies AUTH-007

🤖 AI Dependency Suggestions for AUTH-007: User Logout

Based on code analysis and work unit descriptions:

Recommended Dependencies:

1. AUTH-007 depends on AUTH-001 (Session Management) [HIGH CONFIDENCE]
   Reason: Logout requires destroying sessions
   Type: dependsOn (soft dependency)

2. AUTH-007 relates to AUTH-002 (User Login) [MEDIUM CONFIDENCE]
   Reason: Logout is the inverse of login
   Type: relatesTo (informational)

Should I add these dependencies?

YOU: "Yes, add both."

AI: fspec add-dependency AUTH-007 --depends-on AUTH-001
    fspec add-dependency AUTH-007 --relates-to AUTH-002

    ✓ Added 2 dependencies
    ✓ Dependency graph updated

    AUTH-007 now has proper dependency context.

Scenario 5: Visualizing Dependency Graph

YOU: "Show me the full authentication dependency graph."

AI: Generating dependency graph for AUTH prefix...
    fspec dependencies --prefix AUTH --visualize

<Mermaid chart={`
graph TB
    A[AUTH-001 Session Mgmt Done] --> B[AUTH-002 Login Implementing]
    A --> C[AUTH-003 Password Reset Testing]
    A --> D[AUTH-007 Logout Backlog]

    B -.depends on.-> A
    C -.depends on.-> A
    D -.depends on.-> A

    B <-.relates to.-> D

    E[AUTH-004 OAuth Backlog] --> F[AUTH-002]

    style A fill:#51cf66
    style B fill:#2a5f8f
    style C fill:#17a2b8
    style D fill:#6c757d
    style E fill:#6c757d
`} />

Graph Analysis:
- 5 total work units
- AUTH-001: Complete (unblocked 3 units)
- AUTH-002: In progress (depends on AUTH-001 ✓)
- AUTH-004: Blocked by AUTH-002
- Critical path: AUTH-001 → AUTH-002 → AUTH-004

Dependency Operations

Adding Dependencies

Hard blocker (bidirectional):

fspec add-dependency AUTH-001 --blocks AUTH-002

Soft dependency (unidirectional):

fspec add-dependency AUTH-003 --depends-on AUTH-001

Informational relationship (bidirectional):

fspec add-dependency AUTH-004 --relates-to DASH-001

Multiple dependencies at once:

fspec add-dependency AUTH-005 \
  --blocks AUTH-006 \
  --depends-on AUTH-001 \
  --relates-to AUTH-002

Removing Dependencies

Remove specific dependency:

fspec remove-dependency AUTH-002 --blocks AUTH-003

Remove all dependencies for a work unit:

fspec remove-dependency AUTH-001 --all

Output:

✓ Removed 5 dependencies from AUTH-001:
  - blocks AUTH-002
  - blocks AUTH-003
  - dependsOn AUTH-000
  - relatesTo DASH-001
  - relatesTo DASH-002

Viewing Dependencies

Single work unit:

fspec dependencies AUTH-001

Output:

Dependencies for AUTH-001: Session Management

Blocks (2):
  → AUTH-002: User Login
  → AUTH-003: Password Reset

Blocked By (0):
  (none)

Depends On (1):
  → AUTH-000: Authentication Core

Related To (1):
  ↔ DASH-001: User Dashboard

Impact:
- Blocks 2 work units
- Blocked by 0 work units
- Unblocks 2 units when complete

Project-wide:

fspec dependencies

Output:

Project Dependency Summary

Total Work Units: 50
Units with Dependencies: 25
Total Dependencies: 60
  - blocks: 20
  - dependsOn: 25
  - relatesTo: 15

Top 5 Bottlenecks:
1. AUTH-001 (blocks 5)
2. DB-001 (blocks 4)
3. INFRA-001 (blocks 3)
4. API-001 (blocks 3)
5. UI-001 (blocks 2)

Circular Dependencies: 0

Querying Dependencies

Find bottlenecks:

fspec query bottlenecks

Find blocked work:

fspec query blocked

Output:

🚫 Blocked Work Units (5)

1. AUTH-002: User Login
   Blocked by: AUTH-001 (Session Management)
   Status: AUTH-001 is in implementing
   Unblock ETA: Unknown

2. AUTH-003: Password Reset
   Blocked by: AUTH-001 (Session Management)
   Status: AUTH-001 is in implementing
   Unblock ETA: Unknown

3. AUTH-004: OAuth Integration
   Blocked by: AUTH-002 (User Login)
   Status: AUTH-002 is in backlog
   Unblock ETA: Unknown (double-blocked)

[... more blocked units ...]

Summary:
- 5 work units blocked
- 3 by AUTH-001
- 2 by AUTH-002

Find circular dependencies:

fspec query circular

Output (none found):

✅ No circular dependencies detected

Dependency graph is valid.

Output (found):

❌ Circular Dependencies Detected (2)

Cycle 1:
  AUTH-001 → AUTH-002 → AUTH-003 → AUTH-001

Cycle 2:
  DB-001 → DB-002 → DB-001

Action Required:
Remove at least one dependency from each cycle to resolve.

AI Dependency Suggestions

Suggest dependencies for new work unit:

fspec suggest-dependencies AUTH-007

Output:

🤖 AI Dependency Suggestions for AUTH-007: User Logout

Based on analysis of:
- Work unit description
- Related work units
- Code context
- ACDD scenarios

Suggested Dependencies:

HIGH CONFIDENCE (90%+):
1. AUTH-007 depends on AUTH-001 (Session Management)
   Reason: Logout must destroy user sessions
   Type: dependsOn

MEDIUM CONFIDENCE (60-90%):
2. AUTH-007 relates to AUTH-002 (User Login)
   Reason: Login/logout are complementary operations
   Type: relatesTo

3. AUTH-007 blocks DASH-001 (User Dashboard)
   Reason: Dashboard needs logout functionality
   Type: blocks

LOW CONFIDENCE (<60%):
4. AUTH-007 relates to AUDIT-001 (Audit Logging)
   Reason: Logout events may need logging
   Type: relatesTo

Add suggestions? (high-confidence only / all / none)

Dependency Graph Visualization

Visual representation helps understand complex dependencies:

Graph Legend

Node Colors:

  • 🟢 Green: Done (completed work)
  • 🔵 Blue: In Progress (implementing, testing, validating)
  • ⚫ Gray: Not Started (backlog, specifying)

Edge Styles:

  • Solid arrow →: blocks/blockedBy (hard blocker)
  • Dashed arrow -.→: dependsOn (soft dependency)
  • Double arrow ↔: relatesTo (bidirectional, informational)

Edge Colors:

  • 🔴 Red: Critical path (blocks)
  • 🟡 Yellow: Soft dependencies
  • 🟢 Green: Related work

Integration with ACDD Workflow

Dependencies enhance planning and execution throughout ACDD:

Discovery Phase: Map Dependencies

Identify logical ordering early:

YOU: "We're planning authentication. What order should we build things?"

AI: Let me suggest dependency order...

    Foundational (no dependencies):
    - AUTH-001: Session Management (database schema)

    Core Features (depend on foundation):
    - AUTH-002: User Login (depends on AUTH-001)
    - AUTH-003: Password Reset (depends on AUTH-001)

    Advanced Features (depend on core):
    - AUTH-004: OAuth (depends on AUTH-002)
    - AUTH-005: 2FA (depends on AUTH-002)

    Recommended dependency structure:
    AUTH-001 → AUTH-002 → AUTH-004
               ↓
             AUTH-003

    Should I create these dependencies?

Specifying Phase: Validate Structure

Ensure no circular dependencies before implementing:

fspec query circular
✅ No circular dependencies

Implementing Phase: Follow Critical Path

Work on bottlenecks first:

fspec query bottlenecks
 
🚨 AUTH-001 blocks 5 units (critical path)
 
Start with AUTH-001 to unblock maximum work.

Done Phase: Auto-Unblock

When work reaches done, dependent work is unblocked:

AUTH-001 moved to done
→ Unblocked: AUTH-002, AUTH-003, AUTH-004, AUTH-005, AUTH-006

Best Practices

✅ DO

  • Map dependencies during planning - Identify order early
  • Use blocks sparingly - Only for true hard blockers
  • Use dependsOn for preference - Soft dependencies allow flexibility
  • Check for cycles regularly - Run fspec query circular
  • Prioritize bottlenecks - Work on high-block-count units first
  • Use AI suggestions - Let AI identify dependencies from context
  • Visualize complex graphs - Use Mermaid diagrams for clarity
  • Update as work progresses - Dependencies may change

❌ DON'T

  • Over-specify dependencies - Too many dependencies create rigidity
  • Create circular blocks - Physically impossible to resolve
  • Ignore bottleneck warnings - Bottlenecks delay everything
  • Use blocks for all dependencies - Reserve for hard requirements
  • Forget to remove - Clean up dependencies when work changes
  • Manually track - Use fspec's graph instead of spreadsheets

Common Patterns

Pattern 1: Linear Dependency Chain

Sequential work where each unit depends on the previous:

A → B → C → D

fspec add-dependency A --blocks B
fspec add-dependency B --blocks C
fspec add-dependency C --blocks D

Pattern 2: Fan-Out (Bottleneck)

One unit blocks many:

     A
    /|\\\
   B C D E

fspec add-dependency A --blocks B
fspec add-dependency A --blocks C
fspec add-dependency A --blocks D
fspec add-dependency A --blocks E

Pattern 3: Fan-In (Convergence)

Many units block one:

   A B C
    \|/
     D

fspec add-dependency A --blocks D
fspec add-dependency B --blocks D
fspec add-dependency C --blocks D

Pattern 4: Diamond Dependency

Complex multi-path:

     A
    / \\
   B   C
    \\ /
     D

fspec add-dependency A --blocks B
fspec add-dependency A --blocks C
fspec add-dependency B --blocks D
fspec add-dependency C --blocks D

Troubleshooting

Issue: Circular dependency detected

Error: Circular dependency: A → B → C → A

Solution: Remove one dependency to break the cycle

fspec remove-dependency C --blocks A

Or change to soft dependency:

fspec remove-dependency C --blocks A
fspec add-dependency C --depends-on A

Issue: Work unit unexpectedly blocked

Problem: Cannot start AUTH-005 but don't know why

Solution: Check dependencies

fspec dependencies AUTH-005
 
Blocked By (1):
  → AUTH-002: User Login (status: implementing)
 
AUTH-005 is blocked by AUTH-002 which is still in progress.

Issue: Too many dependencies, can't track

Problem: 50 dependencies on one work unit

Solution: Simplify dependency structure

# Remove unnecessary dependencies
fspec remove-dependency AUTH-001 --all
 
# Add only critical blockers
fspec add-dependency AUTH-001 --blocks AUTH-002

Issue: AI suggests wrong dependencies

Problem: Suggestions don't make sense

Solution: Improve work unit descriptions

Add more context to work unit descriptions so AI understands relationships better.

Summary

Dependency management provides explicit relationship tracking:

Before Dependencies:

  • Hidden relationships
  • Wrong work order
  • Blocked work invisible
  • Circular dependencies discovered late
  • No bottleneck visibility

With Dependencies:

  • ✅ Explicit relationship graph
  • ✅ Automatic cycle detection
  • ✅ Bottleneck identification
  • ✅ Critical path visibility
  • ✅ AI dependency suggestions
  • ✅ Work order optimization
  • ✅ Visual graph representation

Four Relationship Types:

  1. blocks/blockedBy: Hard blocker (bidirectional)
  2. dependsOn: Soft dependency (unidirectional)
  3. relatesTo: Informational link (bidirectional)
  4. Auto-inverse: System maintains both directions

Key Features:

  • Circular dependency detection via DFS
  • Bottleneck identification by block count
  • AI-suggested dependencies from context
  • Mermaid graph visualization
  • Critical path analysis

Core Commands:

fspec add-dependency <id> --blocks <id2>       # Hard blocker
fspec add-dependency <id> --depends-on <id2>   # Soft dependency
fspec add-dependency <id> --relates-to <id2>   # Informational
fspec remove-dependency <id> --all             # Remove all
fspec dependencies <id>                        # View deps
fspec query bottlenecks                        # Find bottlenecks
fspec query blocked                            # Find blocked work
fspec query circular                           # Detect cycles
fspec suggest-dependencies <id>                # AI suggestions

Integration Points:

  • Discovery: Map logical ordering
  • Specifying: Validate no cycles
  • Implementing: Follow critical path
  • Done: Auto-unblock dependent work

Dependencies transform implicit relationships into explicit, trackable, optimizable work graphs.

Tagging SystemPrivacy