agileflow 2.90.6 → 2.91.0

package/src/core/commands/epic.md

@@ -1,6 +1,6 @@
 ---
 description: Create a new epic with stories
-argument-hint: EPIC=<EP-ID> TITLE=<text> OWNER=<id> GOAL=<text> [STORIES=<list>]
+argument-hint: EPIC=<EP-ID> TITLE=<text> OWNER=<id> GOAL=<text> [STORIES=<list>] [RESEARCH=<file>]
 compact_context:
   priority: high
   preserve_rules:
@@ -11,11 +11,13 @@ compact_context:
     - "MUST validate JSON after every modification"
     - "MUST use AskUserQuestion for user confirmation (YES/NO/CANCEL format)"
     - "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"
   state_fields:
     - epic_id
     - owner
     - story_count
     - creation_timestamp
+    - research_validated
 ---
 
 # epic-new
@@ -105,6 +107,8 @@ OWNER=<id>             # Agent or person name (required)
 GOAL=<outcome>         # Epic goal/metric (required)
 STORIES=<list>         # Comma-separated triplets (optional)
   Format: "US-0001|Story One|owner,US-0002|Story Two|owner2"
+RESEARCH=<file>        # Research note filename (optional)
+  Format: "20260119-feature-research.md" (in docs/10-research/)
 ```
 
 **Output Files Created**:
@@ -182,6 +186,7 @@ STORIES=<list>         # Comma-separated triplets (optional)
 - ALWAYS validate JSON after merge (prevents corruption)
 - Use TodoWrite for step tracking (6 steps)
 - Files: epic file, N story files, status.json, bus/log.jsonl
+- **RESEARCH-FIRST**: For complex epics (3+ stories), validate research exists; suggest /agileflow:research:ask if missing
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -263,6 +268,92 @@ After successfully creating the epic, offer next steps:
 
 ---
 
+## Research-First Validation (GSD Integration)
+
+Before creating an epic or starting work, validate that research exists for complex features.
+
+### Research Validation Flow
+
+**Step 1: Check for Research Field**
+
+When epic has a `research` field in status.json:
+```javascript
+const epic = status.epics["EP-0022"];
+if (epic.research) {
+  // Verify research file exists
+  const researchPath = `docs/10-research/${epic.research}`;
+  if (!fs.existsSync(researchPath)) {
+    console.warn(`⚠️  Research file not found: ${researchPath}`);
+  }
+}
+```
+
+**Step 2: Warn if No Research for Complex Epic**
+
+If epic has 3+ stories and no research field, suggest research first:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "This epic has no linked research. Complex features benefit from research-first planning. What would you like to do?",
+  "header": "Research Check",
+  "multiSelect": false,
+  "options": [
+    {"label": "Create research first (Recommended)", "description": "Run /agileflow:research:ask to gather context"},
+    {"label": "Continue without research", "description": "Proceed with epic creation"},
+    {"label": "Link existing research", "description": "Specify research file to link"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "Create research first"**:
+- Suggest: `/agileflow:research:ask <topic>`
+- After research created, re-run epic creation with RESEARCH parameter
+
+**If "Link existing research"**:
+- Show list of recent research files in docs/10-research/
+- Let user select one
+- Add to epic: `research: "selected-file.md"`
+
+### Epic Schema with Research
+
+```json
+{
+  "EP-0022": {
+    "title": "GSD Integration",
+    "status": "in_progress",
+    "owner": "AG-DEVOPS",
+    "goal": "Adopt GSD workflow patterns",
+    "research": "20260119-gsd-agileflow-integration-analysis.md",
+    "research_required": false,
+    "stories": ["US-0129", "US-0130", "US-0131", "US-0132"]
+  }
+}
+```
+
+**Fields**:
+- `research` (optional): Filename of research note in docs/10-research/
+- `research_required` (optional): If true, blocks implementation until research exists
+
+### When Starting Work Without Research
+
+If user tries to start a story in an epic that has `research_required: true` but no valid research file:
+
+```
+⚠️  Research Required
+
+Epic EP-0022 requires research before implementation.
+Research file not found: 20260119-missing-research.md
+
+Suggested actions:
+1. Run /agileflow:research:ask "GSD workflow integration"
+2. Link existing research with /agileflow:epic RESEARCH=<file>
+3. Remove research_required flag if research is optional
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:epic:list` - View all epics with progress

package/src/core/commands/help.md

@@ -1,6 +1,7 @@
 ---
 description: Display AgileFlow system overview and commands
 argument-hint: (no arguments)
+type: output-only  # Display command - generates output, not an ongoing task
 compact_context:
   priority: medium
   preserve_rules:

package/src/core/commands/metrics.md

@@ -2,6 +2,7 @@
 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]"
 model: haiku
+type: output-only  # Analytics display - read-only, not an ongoing task
 compact_context:
   priority: medium
   preserve_rules:

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

@@ -563,6 +563,7 @@ The implementation plan is now tracked and ready to execute.
 ## Related Commands
 
 - `/agileflow:research:import` - Import new research (includes analysis option)
+- `/agileflow:research:synthesize` - Synthesize insights across multiple research files
 - `/agileflow:research:view` - Read-only view of research
 - `/agileflow:research:list` - Show all research notes
 - `/agileflow:research:ask` - Generate research prompt for web AI

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

@@ -1,6 +1,7 @@
 ---
 description: Generate detailed research prompt for web AI tools (ChatGPT, Perplexity, etc.)
 argument-hint: TOPIC=<text> [DETAILS=<constraints>] [ERROR=<error message>]
+type: output-only  # This command generates output for user to copy - not an ongoing task
 compact_context:
   priority: critical
   preserve_rules:
@@ -775,4 +776,5 @@ After clicking "Sign in with Google", immediately get unauthorized_client error.
 - `/agileflow:research:analyze` - Analyze existing research for implementation
 - `/agileflow:research:import` - Import research results back
 - `/agileflow:research:list` - Show research notes index
+- `/agileflow:research:synthesize` - Synthesize insights across multiple research files
 - `/agileflow:research:view` - Read specific research note

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

@@ -827,4 +827,5 @@ The implementation plan is now tracked and ready to execute.
 - `/agileflow:research:analyze` - Revisit existing research for implementation analysis
 - `/agileflow:research:ask` - Generate research prompt for web AI
 - `/agileflow:research:list` - Show research notes index
+- `/agileflow:research:synthesize` - Synthesize insights across multiple research files
 - `/agileflow:research:view` - Read specific research note

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

@@ -1,6 +1,7 @@
 ---
 description: Show research notes index
 argument-hint: (no arguments)
+type: output-only  # This command displays output - not an ongoing task
 compact_context:
   priority: medium
   preserve_rules:
@@ -258,4 +259,5 @@ Quick actions:
 - `/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:synthesize` - Synthesize insights across multiple research files
 - `/agileflow:research:view` - Read specific research note