agileflow 2.76.0 → 2.78.0

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

@@ -1,6 +1,18 @@
 ---
 description: Show research notes index
 argument-hint: (no arguments)
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:research:list - List all research notes (read-only)"
+    - "NO FILE WRITES - This is read-only browsing"
+    - "Read docs/10-research/README.md for index table"
+    - "If README doesn't exist, list files from directory"
+    - "After showing list, offer quick action links"
+    - "Suggest: view a note OR ask new research OR import new research"
+  state_fields:
+    - research_count
+    - most_recent_topic
 ---
 
 # /agileflow:research:list
@@ -22,11 +34,165 @@ Shows all research notes stored in `docs/10-research/` with:
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Command**: `/agileflow:research:list`
-**Purpose**: Display research notes index from docs/10-research/README.md
-**Key Rule**: Read-only, no file writes
+## ⚠️ COMPACT SUMMARY - /agileflow:research:list IS ACTIVE
+
+**CRITICAL**: You are running `/agileflow:research:list`. This is a read-only research index viewer.
+
+**ROLE**: Display research index and offer navigation options.
+
+---
+
+### 🚨 RULE #1: NO FILE WRITES (READ-ONLY)
+
+**This command ONLY reads and displays. NEVER write, edit, or modify.**
+
+```
+❌ WRONG: Update timestamps / Add entries / Reorganize
+✅ RIGHT: Read index and display to user
+```
+
+---
+
+### 🚨 RULE #2: READ INDEX FROM docs/10-research/README.md
+
+**Primary source: `docs/10-research/README.md` should contain a table:**
+
+```markdown
+## Research Notes
+
+| Date | Topic | File | Summary |
+|------|-------|------|---------|
+| 2026-01-07 | OAuth Integration | 20260107-oauth.md | Setup Google OAuth |
+| 2026-01-06 | Performance Tips | 20260106-perf.md | Caching strategies |
+```
+
+**If README doesn't exist:** List files from the directory directly.
+
+---
+
+### 🚨 RULE #3: HANDLE MISSING RESEARCH GRACEFULLY
+
+**If no research exists, show helpful message:**
+
+```
+No research notes found.
+
+Quick start:
+- /agileflow:research:ask TOPIC="your topic" - Generate research prompt for ChatGPT/Claude
+- /agileflow:research:import TOPIC="..." - Import external content
+```
+
+---
+
+### 🚨 RULE #4: SIMPLE, CLEAN OUTPUT
+
+**Just show the list. No complex formatting, no long explanations.**
+
+```
+Research Notes
+==============
+
+| Date       | Topic                  | File                        |
+|------------|------------------------|-----------------------------|
+| 2026-01-07 | OAuth Integration       | 20260107-oauth.md           |
+| 2026-01-06 | Performance Tips        | 20260106-perf.md            |
+| 2026-01-05 | Database Migrations     | 20260105-migrations.md      |
+
+Total: 3 research notes
+```
+
+---
+
+### 🚨 RULE #5: OFFER QUICK ACTION LINKS
+
+**After showing list, provide suggested actions:**
+
+```
+Quick actions:
+- /agileflow:research:view FILE=<filename> - Read a specific note
+- /agileflow:research:analyze FILE=<filename> - Analyze for implementation
+- /agileflow:research:ask TOPIC="new topic" - Create new research prompt
+- /agileflow:research:import TOPIC="..." - Import external content
+```
+
+Or use AskUserQuestion:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "View a research note", "description": "Read specific research"},
+    {"label": "Analyze research for implementation", "description": "Enter plan mode"},
+    {"label": "Create new research prompt", "description": "/agileflow:research:ask"},
+    {"label": "Import external content", "description": "/agileflow:research:import"},
+    {"label": "Done", "description": "Exit"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Modify the index
+❌ Add or remove entries
+❌ Show only recent research, hide older entries
+❌ Truncate topic names or summaries
+❌ Fail silently if research directory doesn't exist
+❌ End without offering next actions
+
+### DO THESE INSTEAD
+
+✅ Read-only: no modifications
+✅ Show ALL research notes in index
+✅ Display complete file paths
+✅ Graceful handling if no research exists
+✅ Always offer suggested actions
+✅ Link to related commands (view, analyze, ask, import)
+
+---
+
+### WORKFLOW
+
+**Step 1: Read Index**
+1. Try to read `docs/10-research/README.md`
+2. If missing, list files from `docs/10-research/` directory
+3. If directory doesn't exist, show helpful message
+
+**Step 2: Display Index**
+4. Show table with: Date, Topic, File, Summary
+5. Count total research notes
+6. Show list to user
+
+**Step 3: Offer Actions**
+7. Suggest next steps via quick links or AskUserQuestion
+8. Allow user to view, analyze, or create new research
+
+---
+
+### KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `docs/10-research/` | Directory containing all research notes |
+| `docs/10-research/README.md` | Index of research with metadata |
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:research:list` IS ACTIVE - you're listing research notes
+- Read-only: no file modifications
+- Read index from README.md or list directory
+- Display ALL research notes, don't truncate
+- Show helpful message if no research exists
+- Always offer next action options
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---
@@ -71,7 +237,8 @@ Use /agileflow:research:view FILE=<filename> to read a specific note.
 If notes exist:
 ```
 Quick actions:
-- /agileflow:research:view FILE=20241231-oauth-setup.md - Read a note
+- /agileflow:research:view FILE=<filename> - Read a note
+- /agileflow:research:analyze FILE=<filename> - Analyze for implementation
 - /agileflow:research:ask TOPIC="new topic" - Create new research prompt
 - /agileflow:research:import - Import external content
 ```
@@ -88,6 +255,7 @@ Quick actions:
 
 ## Related Commands
 
+- `/agileflow:research:analyze` - Analyze research for implementation in your project
 - `/agileflow:research:ask` - Generate research prompt for web AI
 - `/agileflow:research:import` - Import research results
 - `/agileflow:research:view` - Read specific research note

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

@@ -1,6 +1,18 @@
 ---
 description: Read a specific research note
 argument-hint: FILE=<filename>
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:research:view - Display research note contents (read-only)"
+    - "NO FILE WRITES - This is read-only, no modifications"
+    - "If FILE not provided, list available research and ask user to select"
+    - "Display FULL content, never truncate"
+    - "After viewing, offer actions: Analyze for implementation OR View another OR Done"
+    - "If user selects 'Analyze', invoke /agileflow:research:analyze with the FILE"
+  state_fields:
+    - selected_research_file
+    - file_displayed
 ---
 
 # /agileflow:research:view
@@ -21,11 +33,158 @@ Displays the content of a research note from `docs/10-research/`. Useful for:
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Command**: `/agileflow:research:view FILE=<filename>`
-**Purpose**: Display contents of a specific research note
-**Key Rule**: Read-only, no file writes
+## ⚠️ COMPACT SUMMARY - /agileflow:research:view IS ACTIVE
+
+**CRITICAL**: You are running `/agileflow:research:view`. This is a read-only research viewer.
+
+**ROLE**: Display research note contents and offer next actions.
+
+---
+
+### 🚨 RULE #1: NO FILE WRITES (READ-ONLY)
+
+**This command ONLY reads files. NEVER write, edit, or modify anything.**
+
+```
+❌ WRONG: Modify the research file / Update timestamps / Add sections
+✅ RIGHT: Read and display the file contents, nothing else
+```
+
+---
+
+### 🚨 RULE #2: HANDLE FILE SELECTION
+
+**If FILE argument not provided, prompt user to select:**
+
+1. List available research files from `docs/10-research/`
+2. Show most recent files first
+3. Use AskUserQuestion to let user select
+4. Include "Show full list" option if many files
+5. Then proceed to display
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which research would you like to view?",
+  "header": "Select",
+  "multiSelect": false,
+  "options": [
+    {"label": "20260106-oauth-setup.md", "description": "OAuth 2.0 Setup"},
+    {"label": "20260105-next-patterns.md", "description": "Next.js Best Practices"},
+    {"label": "Show full list", "description": "See all research notes"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+### 🚨 RULE #3: DISPLAY FULL CONTENT
+
+**Always display the ENTIRE research note. Never truncate or summarize.**
+
+```
+❌ WRONG: "The research discusses OAuth implementation..."
+✅ RIGHT: [Display full file contents exactly as written]
+```
+
+---
+
+### 🚨 RULE #4: HANDLE MISSING FILES GRACEFULLY
+
+**If FILE doesn't exist, show helpful error:**
+
+```
+Research note not found: [FILENAME]
+
+Use /agileflow:research:list to see all available research notes.
+```
+
+---
+
+### 🚨 RULE #5: OFFER ACTIONS AFTER VIEWING
+
+**After displaying, ALWAYS ask what user wants to do next:**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do with this research?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Analyze for implementation (Recommended)", "description": "Enter plan mode to understand how to implement this"},
+    {"label": "View another research note", "description": "Select a different note"},
+    {"label": "Done", "description": "Exit"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "Analyze selected"**: Invoke `/agileflow:research:analyze FILE=[current file]`
+**If "View another"**: List files again and repeat
+**If "Done"**: Exit
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Modify or edit the research file
+❌ Truncate or summarize content instead of showing full file
+❌ Add timestamps or metadata to the file
+❌ Fail silently if file doesn't exist
+❌ End without offering next actions
+❌ Assume user knows what to do after viewing
+
+### DO THESE INSTEAD
+
+✅ Read only, never modify
+✅ Display complete file contents
+✅ Show helpful error for missing files
+✅ Always offer action options after viewing
+✅ Link to /agileflow:research:analyze for implementation
+✅ Link to /agileflow:research:list for browsing all notes
+
+---
+
+### WORKFLOW
+
+**Phase 1: Get File Selection**
+1. Check if FILE argument provided
+2. If not, list files and ask user to select
+3. Validate file exists
+
+**Phase 2: Read & Display**
+4. Read the entire file from docs/10-research/
+5. Display full content to user
+
+**Phase 3: Offer Actions**
+6. Ask what user wants to do next
+7. Route to appropriate command:
+   - Analyze → /agileflow:research:analyze
+   - View another → Step 1 (select again)
+   - Done → Exit
+
+---
+
+### KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `docs/10-research/` | Directory containing all research notes |
+| `docs/10-research/README.md` | Index of research notes (if available) |
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:research:view` IS ACTIVE - you're viewing a research note
+- Read-only: no file modifications whatsoever
+- If FILE not provided, list files and ask user to select
+- Display FULL content, never truncate
+- Always offer next actions (Analyze, View another, Done)
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---
@@ -79,12 +238,25 @@ Output the full content of the research note.
 ### Step 4: Suggest Actions
 
 After displaying:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do with this research?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Analyze for implementation", "description": "Enter plan mode and see how to implement this in your project"},
+    {"label": "View another research note", "description": "Switch to a different note"},
+    {"label": "Done", "description": "Exit"}
+  ]
+}]</parameter>
+</invoke>
 ```
----
 
-Actions:
-- /agileflow:research:list - See all research notes
-- /agileflow:research:ask TOPIC="new topic" - Create new research
+If "Analyze for implementation" selected, invoke:
+```
+/agileflow:research:analyze FILE=[current file]
 ```
 
 ---
@@ -108,6 +280,7 @@ Actions:
 
 ## Related Commands
 
+- `/agileflow:research:analyze` - Analyze research for implementation in your project
 - `/agileflow:research:ask` - Generate research prompt for web AI
 - `/agileflow:research:import` - Import research results
 - `/agileflow:research:list` - Show research notes index

package/src/core/commands/retro.md

@@ -1,7 +1,23 @@
 ---
 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=<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)"
+    - "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)"
+    - "MUST prioritize action items by impact (HIGH/MEDIUM/LOW)"
+    - "MUST celebrate wins (even small ones)"
+    - "MUST save automatically to docs/08-project/retrospectives/ unless SAVE=false"
+  state_fields:
+    - timeframe
+    - story_count
+    - action_count
+    - celebration_count
 ---
 
 # retro
@@ -22,64 +38,135 @@ Automated retrospective generator that analyzes patterns and surfaces insights f
 
 <!-- COMPACT_SUMMARY_START -->
 
-## Compact Summary
+## ⚠️ COMPACT SUMMARY - /agileflow:retro IS ACTIVE
 
-**Command Purpose**: Automated retrospective generator analyzing AgileFlow data to surface insights, patterns, and actionable improvements using Start/Stop/Continue format.
+**CRITICAL**: You are the Retrospective Facilitator. This analyzes patterns and surfaces improvements (read-only).
 
-**Role**: Retrospective Facilitator
+---
 
-**Critical Behavioral Rules**:
-- ALWAYS create TodoWrite task list at start (9 steps)
-- Focus on TEAM-LEVEL patterns, never individual blame
-- Balance positive (Continue) with improvements (Start/Stop)
-- Use DATA to drive insights (no subjective opinions without evidence)
-- Prioritize action items by impact (HIGH/MEDIUM/LOW)
-- ALWAYS celebrate wins, even small ones
-- Save automatically to docs/08-project/retrospectives/ unless SAVE=false
+### 🚨 RULE #1: ALWAYS Create TodoWrite Task List FIRST
+
+Create 9-step task list immediately:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Load data sources (bus/log.jsonl, status.json, stories, velocity)
+2. Analyze what went well (velocity, cycles, completions, estimation)
+3. Analyze improvements (velocity drops, cycles, WIP, blockers)
+4. Detect patterns (recurring blockers, handoffs, story sizes)
+5. Generate action items (prioritized HIGH/MEDIUM/LOW)
+6. Create celebration section (wins, even small ones)
+7. Generate comprehensive report
+8. Save to docs/08-project/retrospectives/
+9. Update retrospectives index</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+Mark each step complete as you finish.
 
-**Key Data Sources**:
-1. docs/09-agents/bus/log.jsonl - Event patterns, status transitions, blocking events
-2. docs/09-agents/status.json - Current state, WIP levels, owner distribution
-3. docs/06-stories/**/US-*.md - Story completion, estimates vs actuals, AC rates
-4. Velocity data - Points completed, throughput trends
+### 🚨 RULE #2: ALWAYS Focus on TEAM-LEVEL Patterns
 
-**TodoWrite Task List** (create at start):
-```
-TodoWrite tool usage:
-- content: "1. Load data sources\n2. Analyze what went well\n3. Analyze improvements\n4. Detect patterns\n5. Generate action items\n6. Create celebration section\n7. Generate report\n8. Save file\n9. Update index"
-- status: "in-progress"
-- activeForm: true
-```
+- Analyze team behaviors, not individuals
+- Never blame people (blame processes)
+- Look for system issues and process improvements
+- Celebrate team wins collectively
 
-**Workflow Steps**:
-1. Create TodoWrite task list → Load and analyze data sources
-2. Identify "What Went Well" patterns (velocity, cycles, completions, estimation, workload)
-3. Identify "What Needs Improvement" patterns (velocity drops, cycles, WIP, blocking, bottlenecks)
-4. Detect advanced patterns (recurring blockers, handoffs, story size correlations)
-5. Generate prioritized action items (HIGH/MEDIUM/LOW) → Create celebration section
-6. Generate ASCII report → Save to retrospectives/ → Update index
+### 🚨 RULE #3: ALWAYS Balance Continue/Start/Stop
 
-**Inputs** (optional):
-- `TIMEFRAME`: sprint|2weeks|30d|90d (default: 2weeks)
-- `EPIC`: <EP_ID> (epic-specific retrospective)
-- `FORMAT`: ascii|markdown|html (default: ascii)
-- `SAVE`: true|false (default: true)
+- CONTINUE: What went well (keep doing)
+- START: New improvements needed (action items)
+- STOP: What's not working (anti-patterns)
 
-**Output Format**:
-- ASCII box with Unicode (╔═╗║╚╝)
-- Sections: Summary → What Went Well → What Needs Improvement → Actions → Team Contributions → Predictions
-- Icons: ✅ ⚠️ 🛑 ▶️ 🎯 📊 🔮 🎉
+Balance should be ~40% Continue, 40% Start/Stop, 20% Actions
 
-**Example Usage**:
-```bash
-/agileflow:retro
-/agileflow:retro TIMEFRAME=30d
-/agileflow:retro EPIC=EP-0010 FORMAT=markdown
-```
+### 🚨 RULE #4: ALWAYS Use DATA to Drive Insights
+
+- NO opinion without evidence
+- Back every statement with data
+- Show calculations (e.g., "Velocity +12%")
+- Link to specific stories or events
+- Never assume (calculate from bus log)
+
+---
+
+## Key Data Sources & Analysis
+
+**Data Sources** (read-only):
+1. docs/09-agents/bus/log.jsonl - Status transitions, blocking events, timelines
+2. docs/09-agents/status.json - Current state, WIP, owner distribution
+3. docs/06-stories/**/US-*.md - Completed stories, estimates vs actuals
+4. Velocity data - Points completed, trends (from /agileflow:velocity)
+
+**Analysis Patterns to Look For**:
+- Velocity changes (↗ ↘ →)
+- Cycle time trends (avg days to complete)
+- WIP violations (over 2/agent)
+- Blocking patterns (recurring blockers, durations)
+- Estimation accuracy (variance %)
+- Agent utilization (balanced distribution)
+- Stale stories (in-progress >10 days)
+- Story size correlation (do small stories complete faster?)
+- Day-of-week patterns (Friday dips?)
+- Handoff patterns (frequent reassignments)
+
+---
+
+## Output Structure
+
+**Retrospective Report Includes**:
+1. **Summary** - Sprint dates, stories completed, velocity, key metrics
+2. **What Went Well** (CONTINUE) - 5-7 positive patterns with data
+3. **What Needs Improvement** (START/STOP) - 5-7 improvement areas with actions
+4. **Action Items** - Prioritized by impact (HIGH/MEDIUM/LOW)
+5. **Team Contributions** - Workload distribution (who did what %)
+6. **Predictions** - Forward-looking next sprint capacity
+
+**Format Options**:
+- ASCII: Box drawing with Unicode (╔═╗║╚╝)
+- Markdown: For docs/wiki
+- HTML: For web export
+
+---
+
+## Anti-Patterns & Correct Usage
 
-**Success Criteria**: Comprehensive data analysis, balanced Continue/Start/Stop, specific actionable items, celebration section, predictions, file saved with date stamp
+❌ **DON'T**:
+- Include individual blame (focus on systems/processes)
+- Make subjective claims without data
+- Skip celebration section (morale matters)
+- Forget to prioritize actions (HIGH/MEDIUM/LOW)
+- Ignore team contributions (acknowledge work)
+
+✅ **DO**:
+- Focus on team-level patterns
+- Back every insight with data
+- Celebrate wins (small and large)
+- Prioritize action items by impact
+- Acknowledge individual contributions
+- Provide specific, actionable next steps
+
+---
+
+## Integration & Follow-up
+
+After displaying retrospective:
+- `/agileflow:sprint-plan` - Use learnings for next sprint
+- `/agileflow:metrics` - See detailed metrics supporting insights
+- `/agileflow:velocity` - See velocity trends over longer horizon
+- Update retrospectives/ index for historical tracking
+
+---
 
-**Integration**: After `/metrics`, before sprint planning, with `/velocity`, in `/babysit`
+## REMEMBER AFTER COMPACTION
+
+- Command is read-only (analyzes data, no updates)
+- Creates 9-step TodoWrite task list (tracks progress)
+- Focuses on TEAM-LEVEL patterns (never individual blame)
+- Balances Continue/Start/Stop with data evidence
+- Generates retrospective report with Start/Stop/Continue format
+- Prioritizes action items by impact (HIGH/MEDIUM/LOW)
+- Celebrates team wins (morale building)
+- Saves to docs/08-project/retrospectives/ (historical tracking)
+- Uses data to drive all insights (no subjective opinions)
 
 <!-- COMPACT_SUMMARY_END -->