agileflow 2.99.8 → 3.0.0

package/src/core/commands/ideate/new.md

@@ -226,7 +226,7 @@ Be SPECIFIC - reference actual file paths, function names, and code patterns.
 **Write** (save report):
 ```xml
 <invoke name="Write">
-<parameter name="file_path">/path/to/docs/08-project/ideation-YYYYMMDD.md</parameter>
+<parameter name="file_path">/path/to/docs/08-project/ideation/ideation-YYYYMMDD.md</parameter>
 <parameter name="content"># Ideation Report...</parameter>
 </invoke>
 ```
@@ -240,7 +240,7 @@ Be SPECIFIC - reference actual file paths, function names, and code patterns.
 
 **Categories**: Security, Performance, Code Quality, UX/Design, Testing, API/Architecture
 **Confidence**: High (2+ experts agree; 3+ for ultradeep), Medium (1 expert with evidence)
-**Output**: `docs/08-project/ideation-<YYYYMMDD>.md` | Optional stories
+**Output**: `docs/08-project/ideation/ideation-<YYYYMMDD>.md` | Optional stories
 <!-- COMPACT_SUMMARY_END -->
 
 ---
@@ -664,7 +664,7 @@ For each idea:
 5. Run `/agileflow:ideate:history` to see full idea backlog
 ```
 
-**Save report to**: `docs/08-project/ideation-{YYYYMMDD}.md`
+**Save report to**: `docs/08-project/ideation/ideation-{YYYYMMDD}.md`
 
 **Update ideation index**: Save the updated index to `docs/00-meta/ideation-index.json`
 
@@ -735,7 +735,7 @@ After generating output, present options:
 - 8 ideas with specific evidence → MEDIUM confidence
 - 6 ideas too vague → excluded
 
-**Step 5**: Generate report with 12 ideas, saved to `docs/08-project/ideation-20260106.md`
+**Step 5**: Generate report with 12 ideas, saved to `docs/08-project/ideation/ideation-20260106.md`
 
 **Step 6**: Skipped (OUTPUT=report only)
 
@@ -758,7 +758,7 @@ After generating output, present options:
 - 25 ideas with 1-2 experts + evidence → MEDIUM confidence
 - 32 ideas too vague or single expert without evidence → excluded
 
-**Step 5**: Generate report with 33 ideas, saved to `docs/08-project/ideation-20260106.md`
+**Step 5**: Generate report with 33 ideas, saved to `docs/08-project/ideation/ideation-20260106.md`
 
 **Step 6**: Generate 8 stories for HIGH-confidence items
 

package/src/core/commands/logic/audit.md

@@ -299,7 +299,7 @@ Total: 7 findings (2 false positives excluded)
 2. Empty cart not handled in checkout [CONFIRMED by Edge, Flow]
 3. Type coercion in price calculation [LIKELY - Type]
 
-[Full report saved to docs/08-project/logic-audit-20260203.md]
+[Full report saved to docs/08-project/logic-audits/logic-audit-20260203.md]
 ```
 
 ---
@@ -330,7 +330,7 @@ Total: 7 findings (2 false positives excluded)
 - LIKELY: 1 analyzer with evidence → Medium priority
 - INVESTIGATE: 1 analyzer, weak evidence → Low priority
 
-**Output**: `docs/08-project/logic-audit-{YYYYMMDD}.md`
+**Output**: `docs/08-project/logic-audits/logic-audit-{YYYYMMDD}.md`
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/pr.md

@@ -168,17 +168,18 @@ Suggest a commit message following conventional format:
 </invoke>
 ```
 
-**AskUserQuestion** (for confirmation):
+**AskUserQuestion** (for confirmation - include context from story):
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Use this PR description?",
-  "header": "Confirm",
+  "question": "PR description ready for [STORY]: [N] files changed, [AC_count] AC items. What next?",
+  "header": "PR Action",
   "multiSelect": false,
   "options": [
-    {"label": "Copy to clipboard", "description": "Ready to paste into GitHub"},
-    {"label": "Edit it", "description": "Let me modify sections"},
-    {"label": "Cancel", "description": "Don't create PR now"}
+    {"label": "Create PR with gh CLI (Recommended)", "description": "Push branch and create PR linking [STORY] with [N] files changed"},
+    {"label": "Edit description first", "description": "Modify summary, add test evidence, or adjust sections"},
+    {"label": "Add test plan section", "description": "Include testing instructions before creating PR"},
+    {"label": "Cancel", "description": "PR description saved, create later"}
   ]
 }]</parameter>
 </invoke>

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

@@ -367,19 +367,21 @@ ls docs/10-research/*.md
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Which research would you like to analyze for implementation?",
+  "question": "Found [N] research notes. Which would you like to analyze for implementation?",
   "header": "Select",
   "multiSelect": false,
   "options": [
-    {"label": "[Most recent research file]", "description": "[Topic from filename]"},
-    {"label": "[Second most recent]", "description": "[Topic]"},
-    {"label": "[Third most recent]", "description": "[Topic]"},
-    {"label": "Show full list", "description": "See all research notes"}
+    {"label": "[actual-filename.md] (Recommended)", "description": "[Actual topic] - imported [date], [N] action items"},
+    {"label": "[second-filename.md]", "description": "[Actual topic] - imported [date]"},
+    {"label": "[third-filename.md]", "description": "[Actual topic] - imported [date]"},
+    {"label": "Show full list", "description": "Browse all [N] research notes"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: Always populate with ACTUAL filenames and topics from `docs/10-research/`, sorted most-recent first. Include import date and action item count if visible from the index. Mark the most recent as "(Recommended)". If an active story/epic relates to a research topic, prioritize that file instead.
+
 ### Step 3: Assess and Read Research
 
 First, assess the research file size and complexity:
@@ -434,18 +436,20 @@ Display a brief summary:
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Would you like me to analyze how this research could be implemented in your project?",
+  "question": "'[TOPIC]' has [N] findings and [M] action items. Analyze for implementation?",
   "header": "Analyze",
   "multiSelect": false,
   "options": [
-    {"label": "Yes - Implementation ideation with multi-expert analysis (Recommended)", "description": "Deploy 3-5 domain experts to analyze from security, performance, testing, and architecture perspectives"},
-    {"label": "Just view the full research", "description": "Display without analysis"},
-    {"label": "Cancel", "description": "Exit"}
+    {"label": "Implementation ideation with [detected-type] experts (Recommended)", "description": "Deploy [3-5] [expert list] to map [N] findings to your codebase"},
+    {"label": "View full research ([SIZE])", "description": "Display the complete note ([LINE_COUNT] lines) for reading"},
+    {"label": "Skip for now", "description": "Research saved at docs/10-research/[FILENAME]"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: Populate `[TOPIC]` with research topic, `[N]`/`[M]` with actual finding and action item counts from the file. Auto-detect research type from content keywords to determine expert list. `[SIZE]` shows file size context (e.g., "12KB" or "small"). `[FILENAME]` is the actual filename. For RLM-needed files (50k+), add "(using RLM for targeted extraction)" to the view description.
+
 **If "Just view"**: Display full research content, exit.
 **If "Cancel"**: Exit.
 **If "Yes"**: Continue to Step 5.
@@ -671,19 +675,21 @@ Based on expert consensus: **{ADR/Epic/Story/Practice}**
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Based on this multi-expert analysis, would you like to proceed with implementation?",
+  "question": "[N] experts analyzed '[TOPIC]' ([CONSENSUS_LEVEL] consensus, [STEPS] implementation steps). Proceed?",
   "header": "Proceed?",
   "multiSelect": false,
   "options": [
-    {"label": "Yes - Create implementation artifacts", "description": "I'll create the recommended artifact based on expert consensus"},
-    {"label": "Modify approach first", "description": "Let's adjust the plan before creating artifacts"},
-    {"label": "Save analysis to research file", "description": "Append Implementation Ideation Report to the research note for later"},
-    {"label": "Cancel", "description": "Exit plan mode, no changes"}
+    {"label": "Yes - Create [RECOMMENDED_ARTIFACT] (Recommended)", "description": "[STEPS] high-confidence steps across [M] files, ~[EFFORT] effort"},
+    {"label": "Modify approach first", "description": "Adjust [specific disagreement or concern area]"},
+    {"label": "Save analysis to research file", "description": "Append ideation report to docs/10-research/[FILENAME]"},
+    {"label": "Cancel", "description": "Exit plan mode, research unchanged"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: Populate `[N]` with expert count, `[CONSENSUS_LEVEL]` with High/Medium/Low, `[STEPS]` with count of high-confidence steps, `[M]` with files affected, `[EFFORT]` with consensus effort estimate. For "Modify", reference the specific area where experts had lowest agreement.
+
 **If "Modify approach"**: Discuss changes, update analysis, re-ask.
 **If "Save analysis"**: Append the Implementation Ideation Report to the research file, exit plan mode.
 **If "Cancel"**: Exit plan mode, done.
@@ -698,20 +704,22 @@ Based on expert consensus, present the recommendation:
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Based on expert consensus, I recommend creating: [ARTIFACT TYPE]. What would you like to do?",
+  "question": "Expert consensus recommends [ARTIFACT_TYPE] for '[TOPIC]'. What would you like to create?",
   "header": "Create",
   "multiSelect": false,
   "options": [
-    {"label": "[Recommended artifact] (Recommended)", "description": "[Why experts agreed on this choice]"},
-    {"label": "Create ADR instead", "description": "Document this as an architecture decision"},
-    {"label": "Create Epic + Stories instead", "description": "Break down into trackable work items"},
-    {"label": "Create single Story instead", "description": "Track as a single work item"},
-    {"label": "Skip artifact creation", "description": "Analysis is enough for now"}
+    {"label": "[Recommended artifact]: [suggested title] (Recommended)", "description": "[N] experts agreed - [brief reason from consensus]"},
+    {"label": "Create Epic + Stories instead", "description": "Break into [estimated N] stories across [domains detected]"},
+    {"label": "Create single Story instead", "description": "Track as one work item (~[effort estimate])"},
+    {"label": "Create Practice doc instead", "description": "Document as guidelines in docs/02-practices/"},
+    {"label": "Skip artifact creation", "description": "Research + ideation report saved, implement later"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: First option MUST be the actual expert-recommended artifact with a suggested title (e.g., "Epic: OAuth Integration" or "Story: Fix cache invalidation"). Include expert count and brief consensus reason. For alternatives, populate with specifics from expert analysis: estimated story count, detected domains, effort estimate. Remove the recommended artifact from the alternatives list (don't show "Create Epic instead" if Epic is the recommendation).
+
 ---
 
 ### Step 11: Create Selected Artifact

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

@@ -779,6 +779,49 @@ After clicking "Sign in with Google", immediately get unauthorized_client error.
 
 ---
 
+## Smart Next Steps (AskUserQuestion)
+
+After generating the research prompt, suggest contextual next steps:
+
+**After prompt generation:**
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Research prompt for '[TOPIC]' generated ([LINE_COUNT] lines, [CODE_LINES] lines of code). What would you like to do?",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "Copy & paste to ChatGPT/Perplexity (Recommended)", "description": "Prompt covers [N] files and [M] specific questions - ready to paste"},
+    {"label": "Regenerate with more detail", "description": "Add [missing element: more code from X / error details / attempted solutions]"},
+    {"label": "Save prompt to docs/10-research/", "description": "Save as [YYYYMMDD]-prompt-[topic-slug].md for later use"},
+    {"label": "Done", "description": "Prompt generated, no further action needed"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Key**: Always populate `[TOPIC]` with the actual research topic, `[LINE_COUNT]` with the real line count, `[CODE_LINES]` with code snippet line count, `[N]` with number of source files referenced, and `[M]` with number of specific questions. For "Regenerate", identify what's weakest (fewest code lines? no error details? only 1 attempt listed?) and mention it specifically.
+
+**After user returns with results:**
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Got results for '[TOPIC]'. What would you like to do?",
+  "header": "Import",
+  "multiSelect": false,
+  "options": [
+    {"label": "Import with /research:import (Recommended)", "description": "Save to docs/10-research/ and optionally run multi-expert ideation"},
+    {"label": "Analyze for implementation in [current epic/project]", "description": "Deploy domain experts to map findings to your codebase"},
+    {"label": "Ask follow-up about [specific gap]", "description": "Generate deeper prompt on [area needing more detail]"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Key**: Populate `[TOPIC]` with the research topic. For "Analyze", reference the active epic/story from status.json if one exists, otherwise use "your project". For "Ask follow-up", identify the weakest area of the response (incomplete code example? missing edge case? unclear on versioning?) and reference it specifically.
+
+---
+
 ## Related Commands
 
 - `/agileflow:research:analyze` - Analyze existing research for implementation

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

@@ -625,17 +625,19 @@ Display the formatted research file for review.
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Save this research file?",
+  "question": "Save '[TOPIC]' to docs/10-research/[FILENAME]? ([N] key findings, [M] code snippets, [K] action items)",
   "header": "Confirm",
   "multiSelect": false,
   "options": [
-    {"label": "Yes, save to docs/10-research/", "description": "Write file and update index"},
-    {"label": "No, cancel", "description": "Cancel without saving"}
+    {"label": "Yes, save to docs/10-research/ (Recommended)", "description": "Write [FILENAME] and update research index ([TOTAL] notes total)"},
+    {"label": "No, make changes first", "description": "Cancel, I'll revise before saving"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: Populate `[TOPIC]` with research topic, `[FILENAME]` with the generated filename (YYYYMMDD-slug.md), `[N]`/`[M]`/`[K]` with actual counts of key findings, code snippets, and action items extracted. `[TOTAL]` is the count of existing notes + 1.
+
 ### Step 7: Save Research File
 
 If YES:
@@ -662,26 +664,28 @@ After saving, ask if the user wants to understand how this research applies to t
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Would you like me to analyze how this research could be implemented in your project?",
+  "question": "Saved '[TOPIC]' ([N] findings, [M] action items). Analyze for implementation?",
   "header": "Analyze",
   "multiSelect": false,
   "options": [
-    {"label": "Yes - Implementation ideation with multi-expert analysis (Recommended)", "description": "Deploy 3-5 domain experts to analyze from security, performance, testing, and architecture perspectives"},
-    {"label": "No - Just save the research", "description": "Keep as reference, I can analyze later"},
-    {"label": "Link to existing Epic/Story", "description": "Reference from current work without full analysis"}
+    {"label": "Implementation ideation with multi-expert analysis (Recommended)", "description": "Deploy [3-5] [detected-type] experts to analyze from [relevant perspectives]"},
+    {"label": "Save as reference for later", "description": "Saved to docs/10-research/[FILENAME] - analyze anytime with /research:analyze"},
+    {"label": "Link to [ACTIVE-STORY-OR-EPIC]", "description": "Add research reference to [story/epic title] without full analysis"}
   ]
 }]</parameter>
 </invoke>
 ```
 
-**If "Link to existing"**: Add to the target document and finish:
+**Key**: Populate `[TOPIC]` with research topic, `[N]`/`[M]` with actual counts. For the expert option, auto-detect research type (security→"security, api, testing", performance→"performance, database, api", etc.) and list the specific expert perspectives. For "Link to", use the active story/epic ID and title from status.json. If no active work, show "Link to existing Epic/Story" instead. For "Save as reference", include the actual filename that was saved.
+
+**If "Link"**: Add to the target document and finish:
 ```markdown
 **Research**: See [Topic Research](../10-research/YYYYMMDD-topic-slug.md)
 ```
 
-**If "No"**: Research is saved, exit gracefully.
+**If "Save as reference"**: Research is saved, exit gracefully.
 
-**If "Yes"**: Continue to Step 10.
+**If "Analyze"**: Continue to Step 10.
 
 ---
 
@@ -906,19 +910,21 @@ Based on expert consensus: **{ADR/Epic/Story/Practice}**
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Based on this multi-expert analysis, would you like to proceed with implementation?",
+  "question": "[N] experts analyzed '[TOPIC]' ([CONSENSUS_LEVEL] consensus). Proceed with implementation?",
   "header": "Proceed?",
   "multiSelect": false,
   "options": [
-    {"label": "Yes - Create implementation artifacts", "description": "I'll create the recommended artifact based on expert consensus"},
-    {"label": "Modify approach first", "description": "Let's adjust the plan before creating artifacts"},
-    {"label": "Save analysis only", "description": "Exit plan mode, keep research + analysis for later"},
-    {"label": "Cancel", "description": "Exit plan mode, research already saved"}
+    {"label": "Yes - Create [RECOMMENDED_ARTIFACT] (Recommended)", "description": "[N] high-confidence steps identified across [M] files"},
+    {"label": "Modify approach first", "description": "Adjust [specific area of disagreement or concern]"},
+    {"label": "Save analysis to research file", "description": "Append ideation report to [FILENAME] for later"},
+    {"label": "Cancel", "description": "Exit plan mode, research saved at docs/10-research/[FILENAME]"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: Populate `[N]` with number of experts consulted, `[TOPIC]` with research topic, `[CONSENSUS_LEVEL]` with High/Medium/Low. For "Create", use the actual recommended artifact type (Epic + Stories / Story / Practice doc). For "Modify", reference the specific area where experts disagreed or had concerns. `[FILENAME]` is the actual saved research file.
+
 **If "Modify approach"**: Discuss changes, update analysis, re-ask.
 **If "Save analysis only"**: Append Implementation Ideation Report to the research file, exit plan mode.
 **If "Cancel"**: Exit plan mode, done.
@@ -933,20 +939,22 @@ Based on expert consensus, present the recommendation:
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Based on expert consensus, I recommend creating: [ARTIFACT TYPE]. What would you like to do?",
+  "question": "Expert consensus recommends [ARTIFACT_TYPE] for '[TOPIC]'. What would you like to create?",
   "header": "Create",
   "multiSelect": false,
   "options": [
-    {"label": "[Recommended artifact] (Recommended)", "description": "[Why experts agreed on this choice]"},
-    {"label": "Create ADR instead", "description": "Document this as an architecture decision"},
-    {"label": "Create Epic + Stories instead", "description": "Break down into trackable work items"},
-    {"label": "Create single Story instead", "description": "Track as a single work item"},
-    {"label": "Skip artifact creation", "description": "Research and analysis are enough for now"}
+    {"label": "[Recommended artifact]: [suggested title] (Recommended)", "description": "[N] experts agreed - [brief reason from consensus]"},
+    {"label": "Create Epic + Stories instead", "description": "Break into [estimated N] stories across [domains detected]"},
+    {"label": "Create single Story instead", "description": "Track as one work item (~[effort estimate])"},
+    {"label": "Create Practice doc instead", "description": "Document as guidelines in docs/02-practices/"},
+    {"label": "Skip artifact creation", "description": "Research + ideation report saved, implement later"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: First option MUST be the actual expert-recommended artifact with a suggested title (e.g., "Epic: OAuth Integration" or "Story: Fix cache invalidation"). Include expert count and brief consensus reason. For alternatives, populate with specifics: estimated story count, detected domains (API+UI, Database+API, etc.), and effort estimate from experts. Remove the recommended artifact from the alternatives list (don't show "Create Epic instead" if Epic is the recommendation).
+
 ---
 
 ### Step 16: Create Selected Artifact

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

@@ -125,25 +125,26 @@ Quick actions:
 - /agileflow:research:import TOPIC="..." - Import external content
 ```
 
-Or use AskUserQuestion:
+Use AskUserQuestion with contextual options based on what was found:
 
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "What would you like to do?",
+  "question": "Found N research notes. 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"}
+    {"label": "View '[most-recent-filename]' (Recommended)", "description": "Most recent note from [date] on [topic]"},
+    {"label": "Analyze research for implementation", "description": "Deploy multi-expert analysis on a specific note"},
+    {"label": "Generate new research prompt", "description": "Create a detailed prompt for ChatGPT/Perplexity"},
+    {"label": "Done", "description": "N notes listed, no further action"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+**Key**: Always populate the first option with the ACTUAL most recent filename and topic, not a generic "View a note".
+
 ---
 
 ### ANTI-PATTERNS (DON'T DO THESE)