20 KiB
20 KiB
description, allowed-tools
| description | allowed-tools |
|---|---|
| dependencies | Bash, Read, Edit, Write, Glob, Grep |
dependencies
Visualize and analyze story/epic dependency graphs with critical path analysis and circular dependency detection.
Prompt
ROLE: Dependency Graph Analyzer
OBJECTIVE Parse story dependencies from frontmatter and bus/log.jsonl, generate visual dependency graphs, identify critical paths, detect circular dependencies, and suggest optimal work ordering.
INPUTS (optional)
- SCOPE=story|epic|all (default: all)
- EPIC=<EP_ID> (show dependencies within specific epic)
- STORY=<US_ID> (show dependencies for specific story)
- FORMAT=ascii|mermaid|graphviz|json (default: ascii)
- ANALYSIS=critical-path|circular|blocking|all (default: all)
DEPENDENCY SOURCES
1. Story Frontmatter
---
id: US-0042
depends_on:
- US-0040
- US-0041
blocks:
- US-0045
---
2. Bus Log (implicit dependencies)
{"type":"blocked","story":"US-0045","reason":"waiting for US-0042","ts":"..."}
{"type":"handoff","from":"AG-UI","to":"AG-API","story":"US-0043","reason":"depends on backend"}
3. Epic Hierarchy
EP-0010 (Authentication)
├─ US-0030 (Database schema) ← Foundation
├─ US-0031 (User model) ← Depends on US-0030
├─ US-0032 (Login endpoint) ← Depends on US-0031
└─ US-0033 (Login UI) ← Depends on US-0032
DEPENDENCY PARSING
Extract from Story Files
for story_file in docs/06-stories/**/*.md; do
story_id=$(grep "^id:" $story_file | awk '{print $2}')
# Parse depends_on field
depends=$(sed -n '/^depends_on:/,/^[a-z]/p' $story_file | grep -oP 'US-\d+')
# Parse blocks field
blocks=$(sed -n '/^blocks:/,/^[a-z]/p' $story_file | grep -oP 'US-\d+')
echo "$story_id depends_on: $depends"
echo "$story_id blocks: $blocks"
done
Extract from Bus Log
# Find blocking events
jq -r 'select(.type=="blocked" and .reason | contains("waiting for")) |
{story: .story, blocks: (.reason | match("US-\\d+").string)}' bus/log.jsonl
Build Dependency Graph
# Create adjacency list
declare -A graph
for story in all_stories; do
dependencies=$(get_story_dependencies $story)
graph[$story]=$dependencies
done
VISUALIZATION
ASCII Graph (Default)
Story Dependency Graph
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Legend:
✅ Done 🟢 Ready 🟡 In Progress 🔵 In Review ⚪ Blocked
EP-0010: Authentication Epic
┌────────────────────────────────────────────────────────────┐
│ │
│ ✅ US-0030 │
│ Database schema │
│ │ │
│ ├─▶ ✅ US-0031 │
│ │ User model │
│ │ │ │
│ │ ├─▶ 🟡 US-0032 │
│ │ │ Login endpoint (in-progress, AG-API) │
│ │ │ │ │
│ │ │ ├─▶ 🟢 US-0033 │
│ │ │ │ Login UI (ready) │
│ │ │ │ │
│ │ │ └─▶ ⚪ US-0045 │
│ │ │ Password reset (blocked, waiting for US-0032)│
│ │ │ │
│ │ └─▶ ✅ US-0034 │
│ │ JWT middleware │
│ │ │
│ └─▶ 🔵 US-0035 │
│ User registration (in-review) │
│ │
└────────────────────────────────────────────────────────────┘
EP-0011: Payment Processing Epic
┌────────────────────────────────────────────────────────────┐
│ │
│ 🟢 US-0040 │
│ Stripe integration │
│ │ │
│ ├─▶ ⚪ US-0041 │
│ │ Payment form (blocked, waiting for US-0040) │
│ │ │
│ └─▶ ⚪ US-0042 │
│ Webhook handler (blocked, waiting for US-0040) │
│ │
└────────────────────────────────────────────────────────────┘
Critical Path:
US-0030 → US-0031 → US-0032 → US-0033 (11 days total)
⚠️ US-0032 is on critical path and in-progress
Blocking Stories:
US-0040 blocks: US-0041, US-0042 (⚠️ High impact: 2 stories)
US-0032 blocks: US-0033, US-0045 (⚠️ High impact: 2 stories)
Circular Dependencies: None detected ✅
Mermaid Format
graph TD
US0030[US-0030: Database schema ✅]
US0031[US-0031: User model ✅]
US0032[US-0032: Login endpoint 🟡]
US0033[US-0033: Login UI 🟢]
US0034[US-0034: JWT middleware ✅]
US0035[US-0035: User registration 🔵]
US0045[US-0045: Password reset ⚪]
US0030 --> US0031
US0030 --> US0035
US0031 --> US0032
US0031 --> US0034
US0032 --> US0033
US0032 --> US0045
US0040[US-0040: Stripe integration 🟢]
US0041[US-0041: Payment form ⚪]
US0042[US-0042: Webhook handler ⚪]
US0040 --> US0041
US0040 --> US0042
classDef done fill:#90EE90
classDef ready fill:#D3D3D3
classDef inProgress fill:#FFD700
classDef inReview fill:#87CEEB
classDef blocked fill:#FFCCCB
class US0030,US0031,US0034 done
class US0033,US0040 ready
class US0032 inProgress
class US0035 inReview
class US0041,US0042,US0045 blocked
GraphViz DOT Format
digraph dependencies {
rankdir=TB;
node [shape=box, style=rounded];
// Nodes
US0030 [label="US-0030\nDatabase schema", fillcolor="#90EE90", style=filled];
US0031 [label="US-0031\nUser model", fillcolor="#90EE90", style=filled];
US0032 [label="US-0032\nLogin endpoint", fillcolor="#FFD700", style=filled];
US0033 [label="US-0033\nLogin UI", fillcolor="#D3D3D3", style=filled];
US0045 [label="US-0045\nPassword reset", fillcolor="#FFCCCB", style=filled];
// Edges
US0030 -> US0031;
US0031 -> US0032;
US0032 -> US0033;
US0032 -> US0045;
// Critical path (bold red)
US0030 -> US0031 [color=red, penwidth=2];
US0031 -> US0032 [color=red, penwidth=2];
US0032 -> US0033 [color=red, penwidth=2];
}
DEPENDENCY ANALYSIS
1. Critical Path Detection
Definition: Longest path from any root story to any leaf story
# Find all root stories (no dependencies)
roots=$(find_stories_with_no_dependencies)
# For each root, calculate longest path
for root in $roots; do
longest_path=$(find_longest_path_from $root)
echo "$root: $longest_path"
done
# Critical path is the longest of all paths
critical_path=$(find_overall_longest_path)
critical_duration=$(sum_story_estimates_in_path $critical_path)
Output:
Critical Path Analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Longest Path: US-0030 → US-0031 → US-0032 → US-0033
Path Details:
┌──────────┬─────────────────────┬──────────┬────────┬──────────┐
│ Story │ Title │ Estimate │ Status │ Duration │
├──────────┼─────────────────────┼──────────┼────────┼──────────┤
│ US-0030 │ Database schema │ 2d │ ✅ Done│ 2d │
│ US-0031 │ User model │ 3d │ ✅ Done│ 2.5d │
│ US-0032 │ Login endpoint │ 2d │ 🟡 WIP │ 1.5d (so far)│
│ US-0033 │ Login UI │ 1d │ 🟢 Ready│ - │
└──────────┴─────────────────────┴──────────┴────────┴──────────┘
Total Estimated Duration: 8 days
Actual Duration So Far: 6 days
Remaining Work: 1-2 days (US-0032 + US-0033)
⚠️ US-0032 is on critical path and currently in-progress
- Any delay here delays entire epic completion
- Owner: AG-API
- Progress: ~75% complete (1.5d of 2d estimate used)
Recommendation:
- Prioritize US-0032 completion (critical bottleneck)
- Consider pairing to accelerate if delayed
- US-0033 is ready and should start immediately after US-0032
2. Circular Dependency Detection
# Use depth-first search to detect cycles
function has_cycle() {
local story=$1
local path=$2
# If story already in path, we found a cycle
if [[ $path == *"$story"* ]]; then
echo "CYCLE DETECTED: $path → $story"
return 0
fi
# Recursively check dependencies
for dep in $(get_dependencies $story); do
has_cycle $dep "$path → $story"
done
}
for story in all_stories; do
has_cycle $story ""
done
Output:
Circular Dependency Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ CIRCULAR DEPENDENCY DETECTED!
Cycle 1:
US-0050 → US-0051 → US-0052 → US-0050
Details:
US-0050 (Auth service) depends on US-0051 (User service)
US-0051 (User service) depends on US-0052 (Session service)
US-0052 (Session service) depends on US-0050 (Auth service)
Impact: ⚠️ CRITICAL - These stories cannot be completed
Resolution:
1. Review architectural design (likely a design flaw)
2. Break circular dependency by introducing abstraction
3. Consider creating interface/contract story
4. Refactor one story to not depend on the cycle
Suggested Fix:
- Create US-0053: "Auth/User interface contract"
- Make US-0050, US-0051, US-0052 all depend on US-0053
- US-0053 becomes new foundation story
3. Blocking Story Impact
# For each story, find what it blocks
for story in all_stories; do
blocked_stories=$(find_stories_depending_on $story)
count=${#blocked_stories[@]}
if [ $count -gt 0 ]; then
status=$(get_story_status $story)
echo "$story ($status) blocks $count stories: ${blocked_stories[@]}"
# Calculate impact score
impact=$(calculate_impact_score $story)
priority=$(calculate_priority $story $impact)
echo " Impact score: $impact/10, Priority: $priority"
fi
done
Output:
Blocking Story Impact
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
High Impact Blockers:
┌──────────┬────────────────────┬────────┬─────────┬────────────┬──────────┐
│ Story │ Title │ Status │ Blocks │ Impact │ Priority │
├──────────┼────────────────────┼────────┼─────────┼────────────┼──────────┤
│ US-0040 │ Stripe integration │ 🟢 Ready│ 2 stories│ 9/10 ⚠️ │ P0 │
│ │ │ │ US-0041 │ (blocks │ │
│ │ │ │ US-0042 │ payment │ │
│ │ │ │ │ epic) │ │
├──────────┼────────────────────┼────────┼─────────┼────────────┼──────────┤
│ US-0032 │ Login endpoint │ 🟡 WIP │ 2 stories│ 8/10 ⚠️ │ P0 │
│ │ │ │ US-0033 │ (critical │ │
│ │ │ │ US-0045 │ path) │ │
├──────────┼────────────────────┼────────┼─────────┼────────────┼──────────┤
│ US-0030 │ Database schema │ ✅ Done│ 2 stories│ 7/10 │ - │
│ │ │ │ US-0031 │ (already │ │
│ │ │ │ US-0035 │ complete) │ │
└──────────┴────────────────────┴────────┴─────────┴────────────┴──────────┘
⚠️ Action Required:
1. US-0040: Start immediately (blocks 2 stories, epic stalled)
2. US-0032: Monitor closely (in-progress, blocks critical path)
Recommendations:
- Assign US-0040 to available agent ASAP
- Consider pairing on US-0032 if progress slows
- Review US-0041 and US-0042 to verify they truly need US-0040
4. Parallel Work Opportunities
# Find stories that can be worked on in parallel (no dependencies)
independent_stories=$(find_stories_with_no_dependencies_or_dependencies_satisfied)
# Group by epic for clarity
for epic in epics; do
parallel_stories=$(filter_by_epic $independent_stories $epic)
echo "$epic: ${#parallel_stories[@]} stories can be started now"
done
Output:
Parallel Work Opportunities
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stories That Can Start Now (No Blockers):
EP-0010: Authentication
✅ US-0033 (Login UI) - AG-UI available
✅ US-0035 (Registration) - In review (almost done)
EP-0011: Payment Processing
✅ US-0040 (Stripe integration) - AG-API available
⚠️ HIGH PRIORITY: Blocks 2 other stories
EP-0012: User Dashboard
✅ US-0050 (Dashboard layout) - AG-UI available
✅ US-0051 (Profile component) - AG-UI available
Total: 5 stories ready to start (3 agents available)
Recommended Assignments:
AG-UI: US-0033 or US-0050 (both ready, pick by priority)
AG-API: US-0040 (HIGH PRIORITY - unblocks payment epic)
AG-CI: (No stories ready in their domain)
⚡ Optimize throughput: Start 2-3 stories in parallel across agents
GANTT CHART GENERATION
# Generate ASCII Gantt chart based on dependencies
for story in stories_in_dependency_order; do
earliest_start=$(calculate_earliest_start $story)
duration=$(get_estimate $story)
earliest_end=$((earliest_start + duration))
echo "$story: Start day $earliest_start, End day $earliest_end"
print_gantt_bar $story $earliest_start $duration
done
Output:
Gantt Chart (Dependency-Based Schedule)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Timeline (days):
0 2 4 6 8 10 12 14 16
│────│────│────│────│────│────│────│────│
US-0030 ████░░ (2d) ✅ Done
US-0031 ██████░░ (3d) ✅ Done
US-0035 ██████░░ (3d) 🔵 In Review
US-0032 ████░░ (2d) 🟡 In Progress
US-0034 ████░░ (2d) ✅ Done
US-0033 ██░░ (1d) 🟢 Ready
US-0045 ████░░ (2d) ⚪ Blocked
US-0040 ████░░ (2d) 🟢 Ready (parallel)
US-0041 ██░░ (1d) ⚪ Blocked
US-0042 ██████░░ (3d) ⚪ Blocked
Legend:
█ Completed/In Progress
░ Planned
⚠️ Critical Path Stories: US-0030, US-0031, US-0032, US-0033
Insights:
- EP-0010 completion: Day 9 (if no delays)
- EP-0011 completion: Day 8 (if US-0040 starts now)
- Parallelism opportunity: US-0040 can run parallel to US-0032
DEPENDENCY HEALTH SCORE
score=100
# Deduct points for issues
circular_deps=$(count_circular_dependencies)
score=$((score - circular_deps * 20)) # -20 per circular dep
high_impact_blockers=$(count_high_impact_blockers)
score=$((score - high_impact_blockers * 10)) # -10 per high-impact blocker
long_chains=$(count_dependency_chains_over_length 5)
score=$((score - long_chains * 5)) # -5 per long chain
echo "Dependency Health Score: $score/100"
Output:
Dependency Health Score
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Score: 75/100 🟡 Fair
Breakdown:
Base score: 100
- Circular dependencies: -0 (0 found) ✅
- High-impact blockers: -20 (2 found: US-0040, US-0032) ⚠️
- Long dependency chains: -5 (1 chain of 4 stories)
Grade: C+ (Fair)
Recommendations:
1. Start US-0040 immediately (high-impact blocker)
2. Monitor US-0032 progress (critical path)
3. Consider breaking up long chains into smaller increments
To improve score to 90+:
- Resolve high-impact blockers
- Break dependency chains <3 stories
- Ensure parallel work opportunities exist
USAGE EXAMPLES
Show all dependencies
/AgileFlow:dependencies
Specific epic dependencies
/AgileFlow:dependencies EPIC=EP-0010
Specific story dependencies
/AgileFlow:dependencies STORY=US-0032
Only critical path analysis
/AgileFlow:dependencies ANALYSIS=critical-path
Export as Mermaid diagram
/AgileFlow:dependencies FORMAT=mermaid > dependencies.mmd
Check for circular dependencies
/AgileFlow:dependencies ANALYSIS=circular
INTEGRATION WITH OTHER COMMANDS
- Before
/AgileFlow:board: Run/AgileFlow:dependenciesto understand blockers - After
/AgileFlow:story-new: Run/AgileFlow:dependenciesto visualize impact - In
/AgileFlow:babysit: Check/AgileFlow:dependenciesbefore starting work - With
/AgileFlow:metrics: Correlate cycle time with dependency depth
RULES
- Parse dependencies from story frontmatter first (authoritative)
- Fall back to bus/log.jsonl for implicit dependencies
- Detect and flag circular dependencies as errors
- Highlight critical path stories for priority
- Use consistent color coding across all formats
- Export formats should be copy-paste ready
- Always show actionable recommendations
OUTPUT
- ASCII dependency graph with status indicators
- Critical path analysis with duration estimates
- Circular dependency warnings (if any)
- Blocking story impact analysis
- Parallel work opportunities
- Optional: Mermaid/GraphViz export for documentation