agileflow 2.92.1 → 2.93.0

package/src/core/commands/docs.md

@@ -1,6 +1,6 @@
 ---
 description: Synchronize documentation with code changes
-argument-hint: [BRANCH=<name>] [BASE=<branch>] [AUTO_CREATE=yes|no]
+argument-hint: [BRANCH=<name>] [BASE=<branch>] [AUTO_CREATE=true|false]
 compact_context:
   priority: high
   preserve_rules:
@@ -8,7 +8,7 @@ compact_context:
     - "Categorize changes: API, UI, services, config, database"
     - "Generate gap report: missing, outdated, up-to-date docs"
     - "NEVER delete docs without explicit approval"
-    - "ALWAYS use diff-first, YES/NO pattern before writing"
+    - "{{RULES:file_preview}}"
     - "PRESERVE custom content - use managed section markers"
     - "INFER docs from TypeScript types, JSDoc, OpenAPI, tests"
     - "Optional AUTO_CREATE mode auto-generates all missing docs"
@@ -396,3 +396,13 @@ OUTPUT
 - Gap report (markdown)
 - List of actions to take
 - Optional: PR with doc updates (if approved)
+
+---
+
+## Related Commands
+
+- `/agileflow:readme-sync` - Sync folder README with contents
+- `/agileflow:changelog` - Generate changelog from commits
+- `/agileflow:update` - Generate stakeholder progress report
+- `/agileflow:template` - Manage custom templates
+- `/agileflow:pr` - Generate pull request from story

package/src/core/commands/epic/list.md

@@ -1,6 +1,18 @@
 ---
 description: List all epics with status and progress
 argument-hint: [STATUS=<status>]
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:epic:list - Lists all epics with progress tracking"
+    - "MUST read status.json for epic data"
+    - "MUST calculate story progress (completed/total) for each epic"
+    - "MUST display table with status, progress percentage, owner"
+    - "MUST offer actions: view details, add story, create new epic"
+    - "This is READ-ONLY - no file writes"
+  state_fields:
+    - status_filter
+    - epic_count
 ---
 
 # /agileflow:epic:list
@@ -21,6 +33,14 @@ Shows all epics from `docs/09-agents/status.json` with:
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js epic:list
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 

package/src/core/commands/epic/view.md

@@ -1,6 +1,23 @@
 ---
 description: View epic details with stories and contextual actions
 argument-hint: EPIC=<EP-ID>
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:epic:view - Views epic with all stories and context-aware actions"
+    - "MUST read epic from status.json and load all stories"
+    - "MUST display overview: title, owner, goal, progress bar"
+    - "MUST group stories by status: in_progress, ready, done"
+    - "MUST offer CONTEXT-AWARE actions based on progress"
+    - "Progress <50% → Add stories, start work, plan sprint"
+    - "Progress 50-99% → Work on remaining, view details"
+    - "Progress 100% → Close epic, view summary"
+    - "Status on-hold → Resume, view blockers, close"
+    - "ALWAYS offer next steps via AskUserQuestion"
+  state_fields:
+    - selected_epic_id
+    - epic_progress
+    - epic_status
 ---
 
 # /agileflow:epic:view
@@ -19,6 +36,14 @@ Displays complete epic information and offers **context-aware actions** based on
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js epic:view
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 

package/src/core/commands/epic.md

@@ -5,13 +5,12 @@ compact_context:
   priority: high
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow:epic-new - Epic creator for feature planning"
-    - "MUST create TodoWrite task list immediately (6 steps: parse, create epic, create stories, merge status, append bus, confirm)"
-    - "MUST show file previews before confirming writes"
-    - "MUST use Edit tool or jq for JSON operations (never echo/cat > status.json)"
-    - "MUST validate JSON after every modification"
-    - "MUST use AskUserQuestion for user confirmation (YES/NO/CANCEL format)"
+    - "{{RULES:todo_tracking}}"
+    - "{{RULES:file_preview}}"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:user_confirmation}}"
     - "STORIES format: 'US-ID|title|owner,US-ID2|title2|owner2' (comma-separated triplets)"
-    - "RESEARCH-FIRST: Validate research exists before creating epic; warn if missing for complex features"
+    - "{{RULES:research_first}}"
   state_fields:
     - epic_id
     - owner

package/src/core/commands/feedback.md

@@ -1,5 +1,6 @@
 ---
 description: Collect and process agent feedback
+argument-hint: (no arguments)
 compact_context:
   priority: medium
   preserve_rules:
@@ -521,3 +522,13 @@ OUTPUT
 - Saved feedback (markdown)
 - Optional: Retrospective summary
 - Optional: Auto-generated improvement stories
+
+---
+
+## Related Commands
+
+- `/agileflow:retro` - Sprint retrospective
+- `/agileflow:status` - Update story status
+- `/agileflow:sprint` - Sprint planning
+- `/agileflow:story` - Create improvement stories
+- `/agileflow:metrics` - Analytics and metrics dashboard

package/src/core/commands/handoff.md

@@ -6,8 +6,8 @@ compact_context:
   preserve_rules:
     - "STORY, FROM, TO are REQUIRED - always ask if missing"
     - "Create handoff note from template in docs/09-agents/comms/"
-    - "Append bus log entry with type='handoff' to docs/09-agents/bus/log.jsonl"
-    - "Always show diff/preview FIRST, wait for YES/NO confirmation BEFORE writing"
+    - "{{RULES:bus_messaging}}"
+    - "{{RULES:file_preview}}"
     - "Include SUMMARY (what was done) and BLOCKERS (issues for next agent)"
     - "Use template: @packages/cli/src/core/templates/comms-note-template.md"
   state_fields:
@@ -374,3 +374,13 @@ Check the FROM and TO parameters.
 Usage:
 /agileflow:handoff STORY=US-0042 FROM=AG-API TO=AG-UI SUMMARY="..."
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:assign` - Assign stories to owners
+- `/agileflow:status` - Update story status
+- `/agileflow:blockers` - Track blockers
+- `/agileflow:board` - Kanban board view
+- `/agileflow:sprint` - Sprint planning

package/src/core/commands/help.md

@@ -167,3 +167,13 @@ docs/
 - `/agileflow:diagnose` - System health check
 - `/agileflow:configure` - Setup AgileFlow
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:configure` - Manage AgileFlow features and hooks
+- `/agileflow:diagnose` - System health diagnostics
+- `/agileflow:whats-new` - Show what's new in AgileFlow
+- `/agileflow:board` - Visual kanban board
+- `/agileflow:babysit` - Interactive mentor workflow

package/src/core/commands/ideate.md

@@ -444,3 +444,13 @@ After generating output, present options:
 | OUTPUT | report, stories, both | report | What to generate |
 
 {{argument}}
+
+---
+
+## Related Commands
+
+- `/agileflow:multi-expert` - Deploy multiple experts for analysis
+- `/agileflow:story` - Create user stories from ideas
+- `/agileflow:epic` - Create epic for grouped improvements
+- `/agileflow:review` - AI-powered code review
+- `/agileflow:debt` - Track technical debt items

package/src/core/commands/impact.md

@@ -1,6 +1,6 @@
 ---
 description: Analyze change impact across codebase
-argument-hint: [FILES=<paths>] [BASE=<branch>] [RUN_TESTS=yes|no]
+argument-hint: [FILES=<paths>] [BASE=<branch>] [RUN_TESTS=true|false]
 compact_context:
   priority: high
   preserve_rules:
@@ -320,3 +320,13 @@ OUTPUT
 - List of affected files and tests
 - Test recommendations (critical/recommended/optional)
 - Optional: Run tests and report results
+
+---
+
+## Related Commands
+
+- `/agileflow:tests` - Set up testing infrastructure
+- `/agileflow:verify` - Run tests and update story status
+- `/agileflow:pr` - Generate pull request from story
+- `/agileflow:review` - AI-powered code review
+- `/agileflow:batch` - Process multiple files

package/src/core/commands/metrics.md

@@ -1,6 +1,6 @@
 ---
 description: Analytics dashboard with cycle time and throughput
-argument-hint: "[TIMEFRAME=7d|30d|90d|all] [EPIC=<id>] [OWNER=<id>] [FORMAT=ascii|json|csv] [METRIC=cycle-time|lead-time|throughput|all]"
+argument-hint: [TIMEFRAME=7d|30d|90d|all] [EPIC=<EP-ID>] [OWNER=<id>] [FORMAT=ascii|json|csv] [METRIC=cycle-time|lead-time|throughput|all]
 model: haiku
 type: output-only  # Analytics display - read-only, not an ongoing task
 compact_context:
@@ -757,3 +757,13 @@ OUTPUT
 - Or JSON/CSV/Markdown based on FORMAT parameter
 - Always include timeframe and generation timestamp
 - Save to docs/08-project/metrics-reports/metrics-YYYYMMDD.md (optional)
+
+---
+
+## Related Commands
+
+- `/agileflow:velocity` - Track velocity and forecast capacity
+- `/agileflow:sprint` - Sprint planning
+- `/agileflow:retro` - Sprint retrospective
+- `/agileflow:board` - Kanban board view
+- `/agileflow:deps` - Dependency visualization

package/src/core/commands/multi-expert.md

@@ -1,6 +1,6 @@
 ---
 description: Deploy multiple domain experts on the same problem for higher confidence
-argument-hint: <question or task>
+argument-hint: <question>
 compact_context:
   priority: high
   preserve_rules:
@@ -360,3 +360,13 @@ Launching experts now...
 ### ARGUMENTS
 
 {{argument}}
+
+---
+
+## Related Commands
+
+- `/agileflow:review` - AI-powered code review
+- `/agileflow:diagnose` - System health diagnostics
+- `/agileflow:impact` - Analyze change impact
+- `/agileflow:babysit` - Mentor workflow
+- `/agileflow:rpi` - Research-Plan-Implement workflow

package/src/core/commands/packages.md

@@ -1,5 +1,6 @@
 ---
 description: Manage dependencies with updates and security audits
+argument-hint: (no arguments)
 compact_context:
   priority: high
   preserve_rules:
@@ -453,3 +454,13 @@ Depending on ACTION:
 - **dashboard**: Dependency dashboard (markdown/html/json/csv)
 - **update**: Update report + optional PR with updates (if approved)
 - **audit**: Security audit report with severity levels
+
+---
+
+## Related Commands
+
+- `/agileflow:diagnose` - System health diagnostics
+- `/agileflow:debt` - Track technical debt items
+- `/agileflow:ci` - Bootstrap CI/CD workflow
+- `/agileflow:pr` - Generate pull request from story
+- `/agileflow:story` - Create story for security updates

package/src/core/commands/pr.md

@@ -323,3 +323,13 @@ Searched:
 Create the story first:
 /agileflow:story EPIC=EP-0010 STORY=US-0042 TITLE="Login Form" OWNER=AG-UI
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:story` - Create user stories
+- `/agileflow:review` - AI-powered code review
+- `/agileflow:verify` - Run tests and update story status
+- `/agileflow:status` - Update story status and progress
+- `/agileflow:ci` - Bootstrap CI/CD workflow

package/src/core/commands/readme-sync.md

@@ -1,6 +1,6 @@
 ---
 description: Synchronize a folder's README.md with its current contents
-argument-hint: FOLDER=<path> | FOLDER=all
+argument-hint: FOLDER=<path>|all
 compact_context:
   priority: medium
   preserve_rules:
@@ -9,7 +9,7 @@ compact_context:
     - "If FOLDER=all, spawn agent for each docs/* subfolder in parallel"
     - "List all files and subdirectories with descriptions"
     - "Build '## Contents' section with file descriptions"
-    - "Always show diff/preview FIRST, wait for YES/NO BEFORE updating"
+    - "{{RULES:file_preview}}"
     - "Only update '## Contents' section - preserve other sections"
     - "Use Edit tool to update README only after approval"
   state_fields:
@@ -255,6 +255,11 @@ Only the `## Contents` section of README.md:
 - Maintains all other sections unchanged
 - Preserves custom notes and links
 
-RELATED
-- CLAUDE.md - Project conventions and practices
-- Mermaid diagram syntax - For flowcharts and sequence diagrams
+---
+
+## Related Commands
+
+- `/agileflow:docs` - Synchronize documentation with code
+- `/agileflow:changelog` - Generate changelog from commits
+- `/agileflow:template` - Manage custom templates
+- `/agileflow:configure` - Manage AgileFlow features

package/src/core/commands/research/analyze.md

@@ -11,9 +11,13 @@ compact_context:
     - "MUST intelligently recommend artifact type (ADR/Epic/Stories/Practice) based on scope"
     - "DO NOT assume a one-size-fits-all artifact type"
     - "Research type + analysis determines artifact: Architecture decision→ADR, Large feature→Epic+Stories, Focused improvement→Story"
+    - "For large research files (50k+ chars) or HIGH complexity: Use RLM approach with document-repl.js"
+    - "Assess file with --info before reading; use targeted extraction for large docs"
   state_fields:
     - selected_research_file
     - research_topic
+    - research_complexity
+    - research_chars
     - plan_mode_active
     - implementation_analysis
 ---
@@ -36,6 +40,14 @@ After importing research with `/agileflow:research:import`, you may not be ready
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js research:analyze
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:research:analyze IS ACTIVE
@@ -155,6 +167,25 @@ Every implementation analysis must include:
 
 ---
 
+### 🚨 RULE #5: USE RLM FOR LARGE RESEARCH FILES
+
+**For research files > 50k chars or HIGH complexity, use document-repl.js:**
+
+```bash
+# Assess first
+node packages/cli/scripts/document-repl.js --load="docs/10-research/FILE.md" --info
+
+# If large/complex, use targeted extraction:
+node packages/cli/scripts/document-repl.js --load="FILE" --toc
+node packages/cli/scripts/document-repl.js --load="FILE" --search="implementation"
+node packages/cli/scripts/document-repl.js --load="FILE" --section="Key Findings"
+```
+
+**❌ WRONG**: Read full 100k char research file into context
+**✅ RIGHT**: Use document-repl.js to extract only relevant sections
+
+---
+
 ### ANTI-PATTERNS (DON'T DO THESE)
 
 ❌ Skip plan mode and analyze without project context
@@ -163,6 +194,7 @@ Every implementation analysis must include:
 ❌ Assume one artifact type for all research (Epic for everything)
 ❌ Create artifacts without user asking first
 ❌ Finish without asking "Should we implement this?"
+❌ Load full large research files (50k+) - use RLM approach
 
 ### DO THESE INSTEAD
 
@@ -172,6 +204,8 @@ Every implementation analysis must include:
 ✅ Show specific, quantifiable benefits
 ✅ Recommend artifact type based on research scope
 ✅ Confirm user wants to implement before creating anything
+✅ Assess research file size/complexity before reading
+✅ Use document-repl.js for large or complex research files
 
 ---
 
@@ -304,12 +338,34 @@ ls docs/10-research/*.md
 </invoke>
 ```
 
-### Step 3: Read and Summarize Research
+### Step 3: Assess and Read Research
+
+First, assess the research file size and complexity:
+
+```bash
+# Assess document complexity
+node packages/cli/scripts/document-repl.js --load="docs/10-research/[SELECTED_FILE]" --info --json
+```
+
+**Decision point based on assessment:**
+
+| Chars | Complexity | Approach |
+|-------|------------|----------|
+| < 10k | Any | Direct read (standard approach) |
+| 10-50k | LOW/MEDIUM | Direct read (standard approach) |
+| 50k+ | Any | **Use RLM approach** |
+| Any | HIGH | **Use RLM approach** |
 
-Read the selected research file:
+**If RLM approach needed** (large or high-complexity file):
+- Use document-repl.js for targeted extraction
+- Get TOC first: `--toc`
+- Search for key concepts: `--search="implementation"`, `--search="benefits"`
+- Extract relevant sections: `--section="Key Findings"`
+- Avoid loading full document to preserve context
 
+**If standard approach** (small, simple file):
 ```bash
-# Read the research note
+# Read the research note directly
 cat docs/10-research/[SELECTED_FILE]
 ```
 
@@ -567,3 +623,4 @@ The implementation plan is now tracked and ready to execute.
 - `/agileflow:research:view` - Read-only view of research
 - `/agileflow:research:list` - Show all research notes
 - `/agileflow:research:ask` - Generate research prompt for web AI
+- `/agileflow:rlm` - RLM document analysis (used automatically for large research files)

package/src/core/commands/research/ask.md

@@ -1,6 +1,6 @@
 ---
 description: Generate detailed research prompt for web AI tools (ChatGPT, Perplexity, etc.)
-argument-hint: TOPIC=<text> [DETAILS=<constraints>] [ERROR=<error message>]
+argument-hint: TOPIC=<text> [DETAILS=<text>] [ERROR=<text>]
 type: output-only  # This command generates output for user to copy - not an ongoing task
 compact_context:
   priority: critical
@@ -40,6 +40,14 @@ When you need external research (from ChatGPT, Perplexity, Claude web, Gemini),
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js research:ask
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:research:ask IS ACTIVE

package/src/core/commands/research/import.md

@@ -45,6 +45,14 @@ Also works for importing:
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js research:import
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:research:import IS ACTIVE

package/src/core/commands/research/list.md

@@ -34,6 +34,14 @@ Shows all research notes stored in `docs/10-research/` with:
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js research:list
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:research:list IS ACTIVE

package/src/core/commands/research/synthesize.md

@@ -1,6 +1,6 @@
 ---
 description: Synthesize insights across multiple research files
-argument-hint: [TOPIC=<text> | FILES=<comma-separated>]
+argument-hint: [TOPIC=<text>] [FILES=<list>]
 compact_context:
   priority: high
   preserve_rules:
@@ -36,6 +36,14 @@ Query across your research notes to discover:
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js research:synthesize
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:research:synthesize IS ACTIVE

package/src/core/commands/research/view.md

@@ -33,6 +33,14 @@ Displays the content of a research note from `docs/10-research/`. Useful for:
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js research:view
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:research:view IS ACTIVE

package/src/core/commands/retro.md

@@ -1,12 +1,12 @@
 ---
 description: Generate retrospective with Start/Stop/Continue format
-argument-hint: "[TIMEFRAME=sprint|2weeks|30d|90d] [EPIC=<id>] [FORMAT=ascii|markdown|html] [SAVE=true|false]"
+argument-hint: [TIMEFRAME=sprint|2weeks|30d|90d] [EPIC=<EP-ID>] [FORMAT=ascii|markdown|html] [SAVE=true|false]
 model: haiku
 compact_context:
   priority: medium
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow:retro - Retrospective facilitator (read-only analysis)"
-    - "MUST create TodoWrite task list (9 steps: load data, analyze well, analyze improvements, detect patterns, generate actions, celebrate, report, save, update index)"
+    - "{{RULES:todo_tracking}}"
     - "MUST focus on TEAM-LEVEL patterns (never individual blame)"
     - "MUST balance positive (Continue) with improvements (Start/Stop)"
     - "MUST use DATA to drive insights (no opinions without evidence)"
@@ -707,3 +707,13 @@ OUTPUT
 - Saved to docs/08-project/retrospectives/retro-YYYYMMDD.md
 - Updated retrospectives/README.md index
 - Action items formatted as checkboxes for easy tracking
+
+---
+
+## Related Commands
+
+- `/agileflow:sprint` - Sprint planning
+- `/agileflow:metrics` - Analytics dashboard
+- `/agileflow:velocity` - Track velocity
+- `/agileflow:feedback` - Collect agent feedback
+- `/agileflow:board` - Kanban board view

package/src/core/commands/review.md

@@ -5,7 +5,7 @@ compact_context:
   priority: critical
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow:ai-code-review - Code reviewer analyzing git diffs"
-    - "NEVER auto-commit fixes without explicit user approval - ALWAYS ask first"
+    - "{{RULES:commit_approval}}"
     - "Be constructive and helpful, never blame or criticize developers"
     - "Show both BAD and GOOD code examples - use ❌ BAD and ✅ GOOD markers"
     - "Prioritize by severity: CRITICAL must be fixed before merge, HIGH should be addressed"
@@ -585,3 +585,13 @@ OUTPUT
 - Code quality score
 - Recommendations
 - Optional: Auto-fixes (if approved)
+
+---
+
+## Related Commands
+
+- `/agileflow:pr` - Generate pull request description
+- `/agileflow:impact` - Analyze change impact
+- `/agileflow:tests` - Set up testing infrastructure
+- `/agileflow:diagnose` - System health diagnostics
+- `/agileflow:multi-expert` - Deploy multiple experts for analysis