agileflow 2.30.0

package/src/core/commands/deps.md

@@ -0,0 +1,560 @@
+---
+description: Visualize dependency graph with critical path detection
+allowed-tools: 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
+```yaml
+---
+id: US-0042
+depends_on:
+  - US-0040
+  - US-0041
+blocks:
+  - US-0045
+---
+```
+
+### 2. Bus Log (implicit dependencies)
+```jsonl
+{"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
+```bash
+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
+```bash
+# 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
+```bash
+# 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
+```mermaid
+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
+```dot
+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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+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
+```bash
+/AgileFlow:dependencies
+```
+
+### Specific epic dependencies
+```bash
+/AgileFlow:dependencies EPIC=EP-0010
+```
+
+### Specific story dependencies
+```bash
+/AgileFlow:dependencies STORY=US-0032
+```
+
+### Only critical path analysis
+```bash
+/AgileFlow:dependencies ANALYSIS=critical-path
+```
+
+### Export as Mermaid diagram
+```bash
+/AgileFlow:dependencies FORMAT=mermaid > dependencies.mmd
+```
+
+### Check for circular dependencies
+```bash
+/AgileFlow:dependencies ANALYSIS=circular
+```
+
+INTEGRATION WITH OTHER COMMANDS
+
+- Before `/AgileFlow:board`: Run `/AgileFlow:dependencies` to understand blockers
+- After `/AgileFlow:story-new`: Run `/AgileFlow:dependencies` to visualize impact
+- In `/AgileFlow:babysit`: Check `/AgileFlow:dependencies` before 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