agileflow 2.50.0 → 2.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/README.md +82 -460
  2. package/package.json +18 -3
  3. package/scripts/agileflow-configure.js +134 -63
  4. package/scripts/agileflow-welcome.js +161 -31
  5. package/scripts/generators/agent-registry.js +2 -2
  6. package/scripts/generators/command-registry.js +6 -6
  7. package/scripts/generators/index.js +2 -6
  8. package/scripts/generators/inject-babysit.js +9 -2
  9. package/scripts/generators/inject-help.js +3 -1
  10. package/scripts/generators/inject-readme.js +7 -3
  11. package/scripts/generators/skill-registry.js +5 -5
  12. package/scripts/get-env.js +13 -12
  13. package/scripts/obtain-context.js +396 -185
  14. package/scripts/session-coordinator.sh +232 -0
  15. package/scripts/session-manager.js +512 -0
  16. package/src/core/agents/orchestrator.md +275 -0
  17. package/src/core/commands/adr.md +38 -16
  18. package/src/core/commands/agent.md +39 -22
  19. package/src/core/commands/assign.md +17 -0
  20. package/src/core/commands/auto.md +60 -46
  21. package/src/core/commands/babysit.md +302 -637
  22. package/src/core/commands/baseline.md +20 -0
  23. package/src/core/commands/blockers.md +33 -48
  24. package/src/core/commands/board.md +19 -0
  25. package/src/core/commands/changelog.md +20 -0
  26. package/src/core/commands/ci.md +17 -0
  27. package/src/core/commands/context.md +43 -40
  28. package/src/core/commands/debt.md +76 -45
  29. package/src/core/commands/deploy.md +20 -0
  30. package/src/core/commands/deps.md +40 -46
  31. package/src/core/commands/diagnose.md +24 -18
  32. package/src/core/commands/docs.md +18 -0
  33. package/src/core/commands/epic.md +31 -0
  34. package/src/core/commands/feedback.md +33 -21
  35. package/src/core/commands/handoff.md +29 -0
  36. package/src/core/commands/help.md +16 -7
  37. package/src/core/commands/impact.md +31 -61
  38. package/src/core/commands/metrics.md +17 -35
  39. package/src/core/commands/packages.md +21 -0
  40. package/src/core/commands/pr.md +15 -0
  41. package/src/core/commands/readme-sync.md +42 -9
  42. package/src/core/commands/research.md +58 -11
  43. package/src/core/commands/retro.md +42 -50
  44. package/src/core/commands/review.md +22 -27
  45. package/src/core/commands/session/end.md +53 -297
  46. package/src/core/commands/session/history.md +38 -257
  47. package/src/core/commands/session/init.md +44 -446
  48. package/src/core/commands/session/new.md +152 -0
  49. package/src/core/commands/session/resume.md +51 -447
  50. package/src/core/commands/session/status.md +32 -244
  51. package/src/core/commands/sprint.md +33 -0
  52. package/src/core/commands/status.md +18 -0
  53. package/src/core/commands/story-validate.md +32 -0
  54. package/src/core/commands/story.md +21 -6
  55. package/src/core/commands/template.md +18 -0
  56. package/src/core/commands/tests.md +22 -0
  57. package/src/core/commands/update.md +72 -58
  58. package/src/core/commands/validate-expertise.md +25 -37
  59. package/src/core/commands/velocity.md +33 -74
  60. package/src/core/commands/verify.md +16 -0
  61. package/src/core/experts/documentation/expertise.yaml +16 -2
  62. package/src/core/skills/agileflow-retro-facilitator/SKILL.md +57 -219
  63. package/src/core/skills/agileflow-retro-facilitator/cookbook/4ls.md +86 -0
  64. package/src/core/skills/agileflow-retro-facilitator/cookbook/glad-sad-mad.md +79 -0
  65. package/src/core/skills/agileflow-retro-facilitator/cookbook/start-stop-continue.md +142 -0
  66. package/src/core/skills/agileflow-retro-facilitator/prompts/action-items.md +83 -0
  67. package/src/core/skills/writing-skills/SKILL.md +352 -0
  68. package/src/core/skills/writing-skills/testing-skills-with-subagents.md +232 -0
  69. package/tools/cli/agileflow-cli.js +4 -2
  70. package/tools/cli/commands/config.js +20 -13
  71. package/tools/cli/commands/doctor.js +25 -9
  72. package/tools/cli/commands/list.js +10 -6
  73. package/tools/cli/commands/setup.js +54 -3
  74. package/tools/cli/commands/status.js +6 -8
  75. package/tools/cli/commands/uninstall.js +5 -5
  76. package/tools/cli/commands/update.js +51 -7
  77. package/tools/cli/installers/core/installer.js +8 -4
  78. package/tools/cli/installers/ide/_base-ide.js +3 -1
  79. package/tools/cli/installers/ide/claude-code.js +3 -7
  80. package/tools/cli/installers/ide/codex.js +440 -0
  81. package/tools/cli/installers/ide/manager.js +2 -6
  82. package/tools/cli/lib/content-injector.js +3 -3
  83. package/tools/cli/lib/docs-setup.js +3 -2
  84. package/tools/cli/lib/npm-utils.js +3 -3
  85. package/tools/cli/lib/ui.js +7 -7
  86. package/tools/cli/lib/version-checker.js +3 -3
  87. package/tools/postinstall.js +2 -3
@@ -85,6 +85,26 @@ git checkout agileflow-baseline-20251222-143000
85
85
  - Use descriptive messages for future reference
86
86
  - Compare current state to baseline with `/agileflow:verify`
87
87
 
88
+ **Tools Used**:
89
+ - TodoWrite: Track 8-step baseline creation workflow
90
+
91
+ **TodoWrite Example**:
92
+ ```xml
93
+ <invoke name="TodoWrite">
94
+ <parameter name="content">
95
+ 1. Run pre-flight checks (session harness, tests, git status, story tests)
96
+ 2. Show baseline summary (what will be included)
97
+ 3. Get baseline message (from user or use default)
98
+ 4. Create git tag with timestamp
99
+ 5. Update docs/00-meta/environment.json (baseline_commit)
100
+ 6. Update docs/09-agents/session-state.json (baseline history)
101
+ 7. Update story frontmatter (verified_at_baseline)
102
+ 8. Display final report
103
+ </parameter>
104
+ <parameter name="status">in-progress</parameter>
105
+ </invoke>
106
+ ```
107
+
88
108
  <!-- COMPACT_SUMMARY_END -->
89
109
 
90
110
  ## Prompt
@@ -30,63 +30,48 @@ This gathers git status, stories/epics, session state, and registers for PreComp
30
30
  - Display recently resolved blockers (optional)
31
31
 
32
32
  **Arguments** (all optional):
33
- - `AGENT=<id>` - Filter by specific agent (e.g., AG-UI, AG-API)
34
- - `SHOW_RESOLVED=true` - Include recently resolved blockers (last 7 days)
35
- - `DETAILED=true` - Show extended details (dependencies, research links, ADRs)
36
-
37
- **Data Sources**:
38
- 1. `status.json` - Current story statuses and blockers
39
- 2. `bus/log.jsonl` - Recent unblock/blocked messages
40
- 3. Story files (`US-*.md`) - Detailed story information
41
- 4. ADRs (`adr-*.md`) - Architecture decisions for context
42
- 5. Research notes (`10-research/*.md`) - Background research
43
- 6. Epic files - Epic context for blocked stories
33
+ - `AGENT`: <id> (filter by specific agent: AG-UI, AG-API, etc.)
34
+ - `SHOW_RESOLVED`: true (include recently resolved blockers, last 7 days)
35
+ - `DETAILED`: true (show extended details: dependencies, research links, ADRs)
44
36
 
45
- **Blocker Types Detected**:
46
- 1. **Direct Blockers** - Stories with status="blocked"
47
- 2. **Dependency Blockers** - Stories waiting on incomplete dependencies
48
- 3. **WIP Capacity Blockers** - Agents at WIP limit (2 in-progress stories)
49
- 4. **Stale Blockers** - Blocked >14 days (critical priority)
37
+ **Data Sources** (parsing required):
38
+ 1. `status.json` - Current story statuses and blockers (JSON parsing)
39
+ 2. `bus/log.jsonl` - Recent unblock/blocked messages (JSON parsing + timestamp filtering)
40
+ 3. Story files (`US-*.md`) - Detailed story information (YAML frontmatter parsing)
41
+ 4. ADRs (`adr-*.md`) - Architecture decisions (keyword matching)
42
+ 5. Research notes (`10-research/*.md`) - Background research (keyword matching)
50
43
 
51
- **Output Sections**:
52
- - **Summary Stats** - Count by type, critical count, cross-agent coordination
53
- - **Critical Blockers** - Stale blockers (>14 days) needing immediate attention
54
- - **Active Blockers** - Grouped by category with resolution suggestions
55
- - **AG-API Unblocking Status** - v2.7.0 coordination tracking
56
- - **Capacity Analysis** - Agents at WIP limit with waiting stories
57
- - **Recently Resolved** - Last 7 days of unblock activity (if requested)
58
- - **Prioritized Actions** - Ranked next steps with suggested commands
59
-
60
- **Resolution Suggestions Include**:
61
- - Estimated completion time for blocking dependencies
62
- - Interim workarounds (mock data, feature flags)
63
- - Linked ADRs and research for context
64
- - Specific questions for clarification blockers
65
- - Escalation paths for external blockers
66
- - Redistribution options for capacity blockers
44
+ **Blocker Types Detected**:
45
+ 1. **Direct** - Stories with status="blocked" (extract from status.json)
46
+ 2. **Dependency** - Stories waiting on incomplete dependencies (parse frontmatter deps_on)
47
+ 3. **WIP Capacity** - Agents at WIP limit (count in-progress stories per agent)
48
+ 4. **Stale** - Blocked >14 days (timestamp comparison)
49
+
50
+ **Workflow**:
51
+ 1. Extract all blockers from status.json Parse bus/log.jsonl for recent activity
52
+ 2. Categorize by type (Technical/Coordination/Clarification/External/Capacity/Research)
53
+ 3. For each blocker: Match to ADRs/research via keyword search
54
+ 4. Generate resolution suggestions (estimated unblock time, workarounds, escalation)
55
+ 5. If SHOW_RESOLVED=true: Extract unblock messages from last 7 days
56
+ 6. Prioritize actions and display dashboard
67
57
 
68
58
  **Example Usage**:
69
59
  ```bash
70
- # All blockers
71
60
  /agileflow:blockers
72
-
73
- # AG-UI blockers only
74
61
  /agileflow:blockers AGENT=AG-UI
75
-
76
- # Include resolved blockers
77
- /agileflow:blockers SHOW_RESOLVED=true
78
-
79
- # Full detailed output
80
- /agileflow:blockers DETAILED=true
62
+ /agileflow:blockers SHOW_RESOLVED=true DETAILED=true
81
63
  ```
82
64
 
83
- **Related Commands**:
84
- - `/agileflow:status` - Update blocker status
85
- - `/story-new` - Create unblocking stories
86
- - `/handoff` - Reassign capacity-blocked stories
87
- - `/adr-new` - Document architectural decisions
88
- - `/agileflow:board` - Visualize current state
89
- - `/agileflow:validate-system` - Check for inconsistencies
65
+ **Output Sections**:
66
+ - Summary Stats (count by type, critical count)
67
+ - Critical Blockers (stale >14 days)
68
+ - Active Blockers (grouped by category with solutions)
69
+ - AG-API Unblocking Status (v2.7.0 coordination)
70
+ - Capacity Analysis (agents at WIP limit)
71
+ - Recently Resolved (last 7 days if requested)
72
+ - Prioritized Actions (ranked next steps)
73
+
74
+ **Integration**: With `/status`, `/story-new`, `/handoff`, `/adr-new`, `/board`, `/validate-system`
90
75
  <!-- COMPACT_SUMMARY_END -->
91
76
 
92
77
  Comprehensive blocker tracking, resolution suggestions, and cross-agent coordination (leverages v2.7.0 AG-API unblocking capabilities).
@@ -89,6 +89,25 @@ This gathers git status, stories/epics, session state, and registers for PreComp
89
89
  - Export board snapshots to track velocity over time
90
90
  - Use GROUP_BY=owner to balance workload
91
91
 
92
+ **Tool Usage Examples**:
93
+
94
+ AskUserQuestion (for actions after displaying board):
95
+ ```xml
96
+ <invoke name="AskUserQuestion">
97
+ <parameter name="questions">[{
98
+ "question": "What would you like to do?",
99
+ "header": "Board Actions",
100
+ "multiSelect": false,
101
+ "options": [
102
+ {"label": "Update a story status", "description": "Change story status on board"},
103
+ {"label": "Export board", "description": "Save board snapshot to file"},
104
+ {"label": "View story details", "description": "See full story information"},
105
+ {"label": "Filter board", "description": "Filter by epic/owner"}
106
+ ]
107
+ }]</parameter>
108
+ </invoke>
109
+ ```
110
+
92
111
  <!-- COMPACT_SUMMARY_END -->
93
112
 
94
113
  ## Prompt
@@ -78,6 +78,26 @@ Automatically generate changelog from PR titles, commits, and tags.
78
78
  - Crash when user is null (#124)
79
79
  - Memory leak in WebSocket handler (#139)
80
80
  ```
81
+
82
+ **Tool Usage Example**:
83
+ When commits need manual categorization:
84
+ ```xml
85
+ <invoke name="AskUserQuestion">
86
+ <parameter name="questions">[{
87
+ "question": "How should this commit be categorized?",
88
+ "header": "Categorize Commit",
89
+ "multiSelect": false,
90
+ "options": [
91
+ {"label": "Added", "description": "New feature or capability (feat:)"},
92
+ {"label": "Changed", "description": "Modification or enhancement (refactor:, perf:)"},
93
+ {"label": "Fixed", "description": "Bug fix (fix:)"},
94
+ {"label": "Security", "description": "Security fix (security:)"},
95
+ {"label": "Skip", "description": "Don't include in changelog"}
96
+ ]
97
+ }]</parameter>
98
+ </invoke>
99
+ ```
100
+
81
101
  <!-- COMPACT_SUMMARY_END -->
82
102
 
83
103
  ## Prompt
@@ -52,6 +52,23 @@ Bootstrap minimal CI workflow and CODEOWNERS.
52
52
  /docs/03-decisions/ @owners
53
53
  ```
54
54
 
55
+ **Tools Used**:
56
+ - TodoWrite: Track 5-step setup workflow
57
+
58
+ **TodoWrite Example**:
59
+ ```xml
60
+ <invoke name="TodoWrite">
61
+ <parameter name="content">
62
+ 1. Parse input (OWNERS)
63
+ 2. Create .github/workflows/ci.yml with lint/typecheck/test jobs
64
+ 3. Create CODEOWNERS file with owner mappings
65
+ 4. Show preview and wait for YES/NO confirmation
66
+ 5. Print notes for enabling required checks
67
+ </parameter>
68
+ <parameter name="status">in-progress</parameter>
69
+ </invoke>
70
+ ```
71
+
55
72
  **Workflow**:
56
73
  1. Parse OWNERS input
57
74
  2. Generate CI workflow with generic job placeholders
@@ -20,50 +20,53 @@ Web AI Context Manager - Generates/exports/manages project context briefs for we
20
20
  - **Import is one-step**: Process CONTENT immediately and create research file
21
21
  - **Link research files**: Always reference research from ADRs/Epics/Stories that use it
22
22
 
23
+ ### Tool Usage Examples
24
+
25
+ **TodoWrite** (for all modes requiring multi-step tracking):
26
+ ```xml
27
+ <invoke name="TodoWrite">
28
+ <parameter name="content">1. Read existing docs/context.md
29
+ 2. Gather sources (status.json, bus/log.jsonl, epics)
30
+ 3. Extract key information
31
+ 4. Generate managed sections
32
+ 5. Show diff for review
33
+ 6. Apply changes after YES</parameter>
34
+ <parameter name="status">in-progress</parameter>
35
+ <parameter name="activeForm">1</parameter>
36
+ </invoke>
37
+ ```
38
+
39
+ **Edit** (when writing context or research files):
40
+ ```xml
41
+ <invoke name="Edit">
42
+ <parameter name="file_path">/full/path/to/docs/context.md</parameter>
43
+ <parameter name="old_string"><!-- MANAGED_SECTION -->\n[old content]\n<!-- END_MANAGED --></parameter>
44
+ <parameter name="new_string"><!-- MANAGED_SECTION -->\n[new content]\n<!-- END_MANAGED --></parameter>
45
+ </invoke>
46
+ ```
47
+
48
+ **AskUserQuestion** (when needing confirmation):
49
+ ```xml
50
+ <invoke name="AskUserQuestion">
51
+ <parameter name="questions">[{"question": "Apply these changes?", "header": "Diff Preview", "multiSelect": false, "options": [{"label": "Yes, update", "description": "Write changes"}, {"label": "No, abort", "description": "Cancel"}]}]</parameter>
52
+ </invoke>
53
+ ```
54
+
23
55
  ### Core Workflow
24
56
 
25
- **MODE=full (default)**
26
- 1. Create todo list tracking: read existing, gather sources, extract info, generate sections, preserve user content, show diff, apply after YES
27
- 2. Read docs/context.md (if exists)
28
- 3. Gather sources: status.json, bus/log.jsonl, epics, stories, ADRs, practices, architecture, roadmap, research, manifests, CI, CHANGELOG
29
- 4. Generate comprehensive context with: what we're building, current focus, feature map, tech/tooling, decisions, architecture, testing, recent progress, risks, next steps
30
- 5. Show diff, wait for YES confirmation
31
- 6. Update only managed sections
32
-
33
- **MODE=export**
34
- 1. Read docs/context.md
35
- 2. Output concise excerpt (≤300 lines): last updated, what we're building, current focus, tech/tooling, key decisions, feature map, next steps
36
- 3. End with "Paste this excerpt into your web AI tool..."
37
- 4. NO file writes
38
-
39
- **MODE=note**
40
- 1. Append timestamped note under "Notes" section
41
- 2. Create section if missing
42
- 3. Show diff, wait for YES confirmation
43
-
44
- **MODE=research**
45
- 1. Create todo list tracking: generate prompt, wait for results, format research, save to docs/10-research/, update index, ask about ADR/Epic/Story, link research
46
- 2. STEP 1: Generate single code block prompt for web AI requesting TL;DR, step-by-step plan, code snippets, config, tests, security checklist, ADR draft, story breakdown, rollback plan, risks, PR template, sourcing rules
47
- 3. Tell user to paste prompt into ChatGPT/Perplexity and return with results
48
- 4. STEP 2: When user returns with results, format into structured markdown with sections: Summary, Key Findings, Implementation, Code Snippets, Security, Testing, Risks, ADR Recommendation, Story Breakdown, References
49
- 5. Save to docs/10-research/YYYYMMDD-topic-slug.md
50
- 6. Update docs/10-research/README.md index
51
- 7. Ask if user wants ADR/Epic/Story created from research
52
- 8. Add research reference to created ADR/Epic/Story
53
-
54
- **MODE=import**
55
- 1. Create todo list tracking: validate inputs, process content, extract key points, extract code, generate actions, suggest stories, format research file, save, update index
56
- 2. Validate TOPIC and CONTENT are provided
57
- 3. Process raw content (transcript, article, etc.) by: summarizing key points, extracting code snippets, generating action items, suggesting user stories
58
- 4. Format into structured research file with all extracted sections
59
- 5. Save to docs/10-research/YYYYMMDD-topic-slug.md
60
- 6. Update docs/10-research/README.md index
61
- 7. Ask if user wants ADR/Epic/Story created from imported content
62
- 8. Add research reference to created ADR/Epic/Story
57
+ **MODE=full**: Create todo list → Read docs/context.md → Gather sources → Generate sections → Show diff → Apply after YES
58
+
59
+ **MODE=export**: Read docs/context.md Output ≤300 line excerpt → No file writes
60
+
61
+ **MODE=note**: Create todo list Append timestamped note Show diff Apply after YES
62
+
63
+ **MODE=research**: Create todo list → STEP 1: Generate prompt → STEP 2: Format & save to docs/10-research/
64
+
65
+ **MODE=import**: Create todo list → Validate inputs → Process content → Save to docs/10-research/
63
66
 
64
67
  ### Key Files
65
- - docs/context.md - Main context brief (managed sections + user content)
66
- - docs/10-research/YYYYMMDD-topic-slug.md - Research results storage
68
+ - docs/context.md - Main context brief
69
+ - docs/10-research/YYYYMMDD-topic-slug.md - Research storage
67
70
  - docs/10-research/README.md - Research index
68
71
  - status.json - Current work tracking
69
72
  - bus/log.jsonl - Recent progress messages
@@ -16,63 +16,54 @@ Track and visualize technical debt across the codebase.
16
16
  <!-- COMPACT_SUMMARY_START -->
17
17
  ## Compact Summary
18
18
 
19
- **Purpose**: Identify, categorize, and prioritize technical debt for refactoring
19
+ **Command**: `tech-debt` - Identify, categorize, and prioritize technical debt for refactoring
20
20
 
21
21
  **Quick Usage**:
22
22
  ```
23
23
  /agileflow:tech-debt SCAN=quick OUTPUT=report THRESHOLD=medium
24
24
  ```
25
25
 
26
- **What It Does**:
27
- 1. Scans codebase for debt indicators (TODO, complexity, duplication)
28
- 2. Searches stories tagged with `tech-debt: true`
29
- 3. Analyzes ADRs for deprecated decisions
30
- 4. Reviews git history for high-churn files
31
- 5. Categorizes debt by type (Architecture, Code Quality, Testing, etc.)
32
- 6. Scores each item by Severity × Scope × Pain
33
- 7. Generates prioritized debt report
34
- 8. Optionally creates stories for critical debt
35
-
36
- **Required Inputs**:
37
- - None (all optional with smart defaults)
26
+ **What It Does**: Scan codebase → Categorize debt → Score by Severity/Scope/Pain → Generate report → Optional stories
38
27
 
39
28
  **Optional Inputs**:
40
- - `SCAN=full|quick` - Scan depth (default: quick)
41
- - `OUTPUT=report|stories|both` - Output type (default: report)
42
- - `THRESHOLD=high|medium|low` - Minimum severity (default: medium)
43
-
44
- **Output Files**:
45
- - Debt report: `docs/08-project/tech-debt-<YYYYMMDD>.md`
46
- - Optional: Stories for top debt items
47
- - Optional: Dashboard at `docs/08-project/debt-dashboard.md`
48
-
49
- **Debt Categories**:
50
- - Architecture: Wrong abstractions, tight coupling
51
- - Code Quality: Duplication, complexity, style issues
52
- - Documentation: Missing, outdated, incomplete
53
- - Testing: Low coverage, flaky tests, missing E2E
54
- - Security: Outdated deps, exposed secrets, weak auth
55
- - Performance: N+1 queries, memory leaks, slow ops
56
- - Dependencies: Outdated packages, unmaintained libs
29
+ - `SCAN=full|quick` (default: quick)
30
+ - `OUTPUT=report|stories|both` (default: report)
31
+ - `THRESHOLD=high|medium|low` (default: medium)
32
+
33
+ ### Tool Usage Examples
34
+
35
+ **Bash** (to scan codebase for TODOs, complexity, etc.):
36
+ ```xml
37
+ <invoke name="Bash">
38
+ <parameter name="command">grep -r "TODO\|FIXME\|HACK" src/ --include="*.ts" --include="*.js" | head -20</parameter>
39
+ <parameter name="description">Find TODO comments in codebase</parameter>
40
+ </invoke>
41
+ ```
57
42
 
58
- **Scoring Formula**:
43
+ **Glob** (to find high-churn files):
44
+ ```xml
45
+ <invoke name="Glob">
46
+ <parameter name="pattern">src/**/*.{ts,js}</parameter>
47
+ </invoke>
59
48
  ```
60
- Score = (Severity × Scope × Pain) / 10
61
- - Severity: 1-10 (impact level)
62
- - Scope: 1-10 (files affected)
63
- - Pain: 1-10 (developer frustration)
49
+
50
+ **Read** (to analyze git history and ADRs):
51
+ ```xml
52
+ <invoke name="Read">
53
+ <parameter name="file_path">/full/path/to/docs/03-decisions/adr-0015-deprecated.md</parameter>
54
+ </invoke>
64
55
  ```
65
56
 
66
- **Workflow**:
67
- 1. Scan for debt indicators across codebase
68
- 2. Categorize and score each item
69
- 3. Generate prioritized report
70
- 4. Ask: "Generate stories for critical debt? (YES/NO)"
71
- 5. Ask: "Save report to docs/08-project/? (YES/NO)"
72
- 6. Suggest adding debt review to roadmap
57
+ **Write** (to save debt report):
58
+ ```xml
59
+ <invoke name="Write">
60
+ <parameter name="file_path">/full/path/to/docs/08-project/tech-debt-20251222.md</parameter>
61
+ <parameter name="content"># Technical Debt Report
62
+
63
+ **Generated**: 2025-12-22
64
+ **Total Debt Items**: 42
65
+ **Critical**: 3 | **High**: 12 | **Medium**: 18 | **Low**: 9
73
66
 
74
- **Example Report Section**:
75
- ```markdown
76
67
  ## Critical Debt (Score >80)
77
68
 
78
69
  ### 1. Auth service tightly coupled to database
@@ -85,8 +76,48 @@ Score = (Severity × Scope × Pain) / 10
85
76
  **Type**: Testing | **Score**: 85
86
77
  **Impact**: High regression risk, blocking production
87
78
  **Files**: src/api/payments/*.ts (12 files, 0% coverage)
88
- **Estimate**: 2-3 days
79
+ **Estimate**: 2-3 days</parameter>
80
+ </invoke>
89
81
  ```
82
+
83
+ **Write** (to create debt stories):
84
+ ```xml
85
+ <invoke name="Write">
86
+ <parameter name="file_path">/full/path/to/docs/06-stories/EP-XXXX/US-XXXX-refactor-auth.md</parameter>
87
+ <parameter name="content">---
88
+ story_id: US-XXXX
89
+ type: tech-debt
90
+ debt_score: 87
91
+ estimate: 3d
92
+ ---
93
+
94
+ # US-XXXX: Refactor auth service to separate concerns
95
+
96
+ ## Current State (Before)
97
+ Auth service tightly coupled to database layer...
98
+
99
+ ## Desired State (After)
100
+ Clear separation: AuthService, AuthRepository, AuthController...</parameter>
101
+ </invoke>
102
+ ```
103
+
104
+ **AskUserQuestion** (for approval):
105
+ ```xml
106
+ <invoke name="AskUserQuestion">
107
+ <parameter name="questions">[{"question": "Generate stories for critical debt?", "header": "Action", "multiSelect": false, "options": [{"label": "Yes, create stories", "description": "Generate stories for top 5 critical items"}, {"label": "No, report only", "description": "Save report without creating stories"}]}]</parameter>
108
+ </invoke>
109
+ ```
110
+
111
+ **Debt Categories**:
112
+ - Architecture: Wrong abstractions, tight coupling
113
+ - Code Quality: Duplication, complexity, style issues
114
+ - Documentation: Missing, outdated, incomplete
115
+ - Testing: Low coverage, flaky tests, missing E2E
116
+ - Security: Outdated deps, exposed secrets, weak auth
117
+ - Performance: N+1 queries, memory leaks, slow ops
118
+ - Dependencies: Outdated packages, unmaintained libs
119
+
120
+ **Output Files**: `docs/08-project/tech-debt-<YYYYMMDD>.md` | Optional stories | Optional dashboard
90
121
  <!-- COMPACT_SUMMARY_END -->
91
122
 
92
123
  ## Prompt
@@ -56,6 +56,26 @@ Automatically set up deployment pipeline for the project.
56
56
  - Mobile (Expo) → EAS
57
57
  - Serverless → AWS Lambda, Vercel Functions
58
58
 
59
+ **Tools Used**:
60
+ - TodoWrite: Track 8-step deployment setup workflow
61
+
62
+ **TodoWrite Example**:
63
+ ```xml
64
+ <invoke name="TodoWrite">
65
+ <parameter name="content">
66
+ 1. Detect project type (static, full-stack, mobile, containers, serverless)
67
+ 2. Recommend platform based on project type
68
+ 3. Generate deployment configuration files
69
+ 4. Create CI/CD workflow file
70
+ 5. Create .env.example and secrets management docs
71
+ 6. Show configuration preview
72
+ 7. Create files after YES/NO confirmation
73
+ 8. Display next steps (add secrets, connect repo, test deploy)
74
+ </parameter>
75
+ <parameter name="status">in-progress</parameter>
76
+ </invoke>
77
+ ```
78
+
59
79
  **Workflow**:
60
80
  1. Detect project type from package.json, Dockerfile, etc.
61
81
  2. Recommend deployment platform
@@ -26,63 +26,57 @@ This gathers git status, stories/epics, session state, and registers for PreComp
26
26
  **Purpose**: Visualize and analyze story/epic dependency graphs with critical path detection, circular dependency checking, and blocking story impact analysis.
27
27
 
28
28
  **Input Parameters** (all optional):
29
- - SCOPE=story|epic|all (default: all)
30
- - EPIC=<EP_ID> (show dependencies within specific epic)
31
- - STORY=<US_ID> (show dependencies for specific story)
32
- - FORMAT=ascii|mermaid|graphviz|json (default: ascii)
33
- - ANALYSIS=critical-path|circular|blocking|all (default: all)
29
+ - `SCOPE`: story|epic|all (default: all)
30
+ - `EPIC`: <EP_ID> (dependencies within specific epic)
31
+ - `STORY`: <US_ID> (dependencies for specific story)
32
+ - `FORMAT`: ascii|mermaid|graphviz|json (default: ascii)
33
+ - `ANALYSIS`: critical-path|circular|blocking|all (default: all)
34
34
 
35
35
  **Dependency Sources**:
36
- 1. Story frontmatter (depends_on, blocks fields)
37
- 2. Bus log (implicit dependencies from blocked events)
38
- 3. Epic hierarchy (parent-child relationships)
36
+ 1. Story frontmatter - depends_on, blocks fields (YAML parsing):
37
+ ```yaml
38
+ depends_on:
39
+ - US-0030
40
+ - US-0031
41
+ blocks:
42
+ - US-0033
43
+ ```
44
+ 2. Bus log - implicit dependencies from blocked events (JSON parsing)
45
+ 3. Epic hierarchy - parent-child relationships
39
46
 
40
47
  **Core Analysis Types**:
41
- 1. **Critical Path Detection**: Longest path from root to leaf story (delays here affect entire project)
42
- 2. **Circular Dependency Detection**: Identify impossible-to-complete dependency cycles
43
- 3. **Blocking Story Impact**: Find stories that block multiple others (high-priority bottlenecks)
44
- 4. **Parallel Work Opportunities**: Identify stories that can be started now (no blockers)
45
-
46
- **Output Format** (ASCII default):
48
+ 1. **Critical Path**: Longest path from root to leaf (delays affect entire project)
49
+ 2. **Circular Dependency Detection**: Impossible-to-complete cycles (flag as errors)
50
+ 3. **Blocking Story Impact**: Stories that block multiple others (bottlenecks)
51
+ 4. **Parallel Work Opportunities**: Stories ready to start (no blockers)
52
+
53
+ **Parsing Algorithm**:
54
+ 1. Read all story frontmatter files → Extract depends_on, blocks
55
+ 2. Query bus/log.jsonl for implicit dependencies
56
+ 3. Build adjacency list graph structure
57
+ 4. Run DFS for critical path (longest path from roots to leaves)
58
+ 5. Run cycle detection algorithm (DFS with visited tracking)
59
+ 6. Calculate impact scores for each blocking story
60
+ 7. Render in requested format
61
+
62
+ **Example Usage**:
63
+ ```bash
64
+ /agileflow:dependencies
65
+ /agileflow:dependencies EPIC=EP-0010
66
+ /agileflow:dependencies STORY=US-0032 ANALYSIS=critical-path
67
+ /agileflow:dependencies FORMAT=mermaid
47
68
  ```
48
- Story Dependency Graph
49
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
50
-
51
- Legend:
52
- ✅ Done 🟢 Ready 🟡 In Progress 🔵 In Review ⚪ Blocked
53
-
54
- [Visual tree showing dependencies]
55
-
56
- Critical Path:
57
- US-0030 → US-0031 → US-0032 → US-0033 (11 days total)
58
69
 
59
- Blocking Stories:
60
- US-0040 blocks: US-0041, US-0042 (⚠️ High impact)
61
-
62
- Circular Dependencies: None detected ✅
63
- ```
70
+ **Output**: ASCII tree with legend, critical path, blocking stories, circular dependency check, actionable recommendations
64
71
 
65
72
  **Critical Rules**:
66
73
  - Parse frontmatter first (authoritative source)
67
- - Flag circular dependencies as errors (cannot be completed)
68
- - Highlight critical path stories (delays affect entire project)
74
+ - Flag circular dependencies as errors (cannot complete)
75
+ - Highlight critical path stories (delays affect project)
69
76
  - Show actionable recommendations
70
- - Use consistent color coding across all formats
77
+ - Use consistent color coding across formats
71
78
 
72
- **Common Usage**:
73
- ```bash
74
- /agileflow:dependencies # Show all dependencies
75
- /agileflow:dependencies EPIC=EP-0010 # Specific epic
76
- /agileflow:dependencies STORY=US-0032 # Specific story
77
- /agileflow:dependencies ANALYSIS=critical-path # Only critical path
78
- /agileflow:dependencies FORMAT=mermaid # Export as Mermaid
79
- ```
80
-
81
- **Integration Points**:
82
- - Before `/board`: Understand blockers before planning
83
- - After `/story-new`: Visualize impact of new story
84
- - In `/babysit`: Check dependencies before starting work
85
- - With `/metrics`: Correlate cycle time with dependency depth
79
+ **Integration**: Before `/board`, after `/story-new`, in `/babysit`, with `/metrics`
86
80
 
87
81
  <!-- COMPACT_SUMMARY_END -->
88
82