agileflow 2.90.7 → 2.92.0

package/src/core/commands/diagnose.md

@@ -277,3 +277,117 @@ fi
 - Display file sizes and story counts
 - Provide actionable recommendations for issues
 - Exit with code 0 if healthy, code 1 if issues found
+
+---
+
+## Expected Output
+
+### Healthy System
+
+```
+🔍 AgileFlow System Diagnostics
+================================
+
+📋 JSON File Validation
+----------------------
+  ✅ docs/00-meta/agileflow-metadata.json (2KB)
+  ✅ docs/09-agents/status.json (45KB)
+  ℹ️  docs/09-agents/status-archive.json - not found (optional)
+  ✅ .claude/settings.json (8KB)
+
+📦 Auto-Archival System
+----------------------
+  ✅ Archive script exists and is executable
+  ✅ Auto-archival hook configured
+  ✅ Archival threshold: 7 days
+
+🪝 Hooks System
+---------------
+  ✅ .claude/settings.json is valid JSON
+  ℹ️  SessionStart hooks: 3
+  ℹ️  UserPromptSubmit hooks: 1
+  ℹ️  Stop hooks: 0
+
+📏 File Size Analysis
+---------------------
+  status.json: 45KB (127 stories)
+  ✅ status.json size is healthy
+
+📊 Diagnostic Summary
+=====================
+✅ All checks passed! System is healthy.
+```
+
+### System with Issues
+
+```
+🔍 AgileFlow System Diagnostics
+================================
+
+📋 JSON File Validation
+----------------------
+  ✅ docs/00-meta/agileflow-metadata.json (2KB)
+  ✅ docs/09-agents/status.json (156KB)
+     ⚠️  WARNING: status.json is large (156KB). Consider running archival.
+  ℹ️  docs/09-agents/status-archive.json - not found (optional)
+  ❌ .claude/settings.json - INVALID JSON
+     Error details:
+     parse error: Invalid numeric literal at line 42, column 15
+
+📦 Auto-Archival System
+----------------------
+  ⚠️  Archive script exists but is NOT executable
+     Fix: chmod +x scripts/archive-completed-stories.sh
+
+🪝 Hooks System
+---------------
+  ❌ .claude/settings.json is INVALID JSON
+
+📏 File Size Analysis
+---------------------
+  status.json: 156KB (423 stories)
+  ⚠️  WARNING: status.json exceeds 100KB
+     Recommendation: Run archival to reduce file size
+     Command: bash .agileflow/scripts/archive-completed-stories.sh 7
+
+📊 Diagnostic Summary
+=====================
+⚠️  Found 4 issue(s) that need attention.
+
+Next steps:
+1. Fix JSON validation errors using: jq empty <file> to check, then repair manually
+2. Make archive script executable: chmod +x scripts/archive-completed-stories.sh
+3. Run archival: bash .agileflow/scripts/archive-completed-stories.sh
+4. Re-run diagnostics: /agileflow:diagnose
+```
+
+### Missing Critical Files
+
+```
+🔍 AgileFlow System Diagnostics
+================================
+
+📋 JSON File Validation
+----------------------
+  ❌ docs/00-meta/agileflow-metadata.json - NOT FOUND (CRITICAL)
+  ❌ docs/09-agents/status.json - NOT FOUND (CRITICAL)
+  ℹ️  docs/09-agents/status-archive.json - not found (optional)
+  ℹ️  .claude/settings.json - not found (optional)
+
+📦 Auto-Archival System
+----------------------
+  ❌ Archive script NOT found (scripts/archive-completed-stories.sh)
+
+🪝 Hooks System
+---------------
+  ⚠️  Hooks system not configured
+
+📊 Diagnostic Summary
+=====================
+⚠️  Found 4 issue(s) that need attention.
+
+Next steps:
+1. Run AgileFlow setup: npx agileflow setup
+2. Verify installation completed successfully
+3. Re-run diagnostics: /agileflow:diagnose
+```

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
@@ -271,3 +362,116 @@ After successfully creating the epic, offer next steps:
 - `/agileflow:story:list` - View all stories
 - `/agileflow:sprint` - Plan sprint with epic stories
 - `/agileflow:board` - Visual kanban board
+
+---
+
+## Expected Output
+
+### Successful Epic Creation
+
+```
+📦 Creating Epic: EP-0010
+
+Title: User Authentication System
+Owner: AG-API
+Goal: Enable secure user login with OAuth support
+
+Files to create:
+───────────────────────────
+1. docs/05-epics/EP-0010.md
+   - Epic definition with goal and stories
+
+2. docs/06-stories/EP-0010/US-0042-login-form.md
+   - Story: Login Form (AG-UI)
+
+3. docs/06-stories/EP-0010/US-0043-oauth-integration.md
+   - Story: OAuth Integration (AG-API)
+
+4. docs/06-stories/EP-0010/US-0044-session-management.md
+   - Story: Session Management (AG-API)
+
+5. docs/09-agents/status.json (merge)
+   + "EP-0010": {
+   +   "id": "EP-0010",
+   +   "owner": "AG-API",
+   +   "status": "active",
+   +   "stories": ["US-0042", "US-0043", "US-0044"]
+   + }
+   + "US-0042": { "epic": "EP-0010", "owner": "AG-UI", "status": "ready" }
+   + "US-0043": { "epic": "EP-0010", "owner": "AG-API", "status": "ready" }
+   + "US-0044": { "epic": "EP-0010", "owner": "AG-API", "status": "ready" }
+
+6. docs/09-agents/bus/log.jsonl (append)
+   + {"type":"assign","to":"AG-API","epic":"EP-0010","text":"Epic created"}
+   + {"type":"assign","to":"AG-UI","story":"US-0042","text":"Story created"}
+   + {"type":"assign","to":"AG-API","story":"US-0043","text":"Story created"}
+   + {"type":"assign","to":"AG-API","story":"US-0044","text":"Story created"}
+
+[AskUserQuestion: "Create epic EP-0010 with 3 stories?"]
+
+✅ Epic EP-0010 created successfully!
+✅ Created 3 stories: US-0042, US-0043, US-0044
+✅ Bus messages sent to assigned owners
+
+[AskUserQuestion: "What would you like to do next?"]
+```
+
+### Research Validation Warning
+
+```
+📦 Creating Epic: EP-0010 (5 stories)
+
+⚠️  Research Check
+
+This epic has no linked research.
+Complex features (3+ stories) benefit from research-first planning.
+
+[AskUserQuestion: "What would you like to do?"]
+  - Create research first (Recommended)
+  - Continue without research
+  - Link existing research
+```
+
+### With Linked Research
+
+```
+📦 Creating Epic: EP-0010
+
+Research linked: 20260121-auth-system-analysis.md
+
+✅ Research file validated
+✅ Key findings extracted:
+   • OAuth 2.0 recommended over custom auth
+   • JWT for session tokens
+   • 3 integration points identified
+
+[Proceeding with epic creation...]
+```
+
+### Validation Error
+
+```
+❌ Invalid STORIES format
+
+Received: US-0042,US-0043
+Expected: US-0042|title|owner,US-0043|title|owner
+
+Format: "US-ID|title|owner,US-ID2|title2|owner2"
+
+Example:
+STORIES="US-0042|Login Form|AG-UI,US-0043|OAuth|AG-API"
+```
+
+### Epic Already Exists
+
+```
+❌ Epic EP-0010 already exists
+
+Existing epic:
+  Title: User Authentication System
+  Status: in_progress
+  Stories: 3 (1 done, 2 in progress)
+
+To add stories, use:
+  /agileflow:story EPIC=EP-0010 STORY=US-00XX TITLE="..." OWNER=...
+```

package/src/core/commands/handoff.md

@@ -246,3 +246,131 @@ ACTIONS
 2) Append bus line type="handoff".
 
 Diff-first; YES/NO.
+
+---
+
+## Expected Output
+
+### Successful Handoff
+
+```
+📋 Creating Handoff: US-0042
+
+From: AG-API
+To: AG-UI
+Summary: Completed auth endpoints, tests passing
+
+Files to create:
+───────────────────────────────────────────────
+1. docs/09-agents/comms/US-0042-20260121-handoff.md
+
+Preview:
+─────────────────────────────────────────────
+# Handoff: US-0042
+
+**From**: AG-API
+**To**: AG-UI
+**Date**: 2026-01-21
+
+## Summary
+Completed all authentication API endpoints including login, logout, and token refresh.
+Unit and integration tests passing (14 tests).
+
+## Work Completed
+- POST /api/auth/login endpoint
+- POST /api/auth/logout endpoint
+- POST /api/auth/refresh endpoint
+- JWT token generation with 1h expiry
+- Integration tests with mocked database
+
+## Blockers
+- None - API is ready for UI integration
+
+## Notes for Next Agent
+- Use the `useAuth` hook for token management
+- Login endpoint returns { token, user } on success
+- Error responses use standard { error, code } format
+- See docs/04-architecture/auth-api.md for full spec
+
+## Files Modified
+- src/api/auth/login.ts
+- src/api/auth/logout.ts
+- src/api/auth/refresh.ts
+- tests/api/auth/*.test.ts
+─────────────────────────────────────────────
+
+2. docs/09-agents/bus/log.jsonl (append)
+   + {"ts":"2026-01-21T14:30:00Z","type":"handoff","story":"US-0042","from":"AG-API","to":"AG-UI","summary":"Completed auth endpoints"}
+
+[AskUserQuestion: "Create this handoff?"]
+
+✅ Handoff created successfully!
+   Note: docs/09-agents/comms/US-0042-20260121-handoff.md
+   Bus log updated: handoff event appended
+```
+
+### Missing Required Inputs
+
+```
+❌ Missing required inputs
+
+Please provide:
+  • STORY - Story ID (e.g., US-0042)
+  • FROM - Source agent (e.g., AG-API)
+  • TO - Target agent (e.g., AG-UI)
+  • SUMMARY - What was done
+
+Usage:
+/agileflow:handoff STORY=US-0042 FROM=AG-API TO=AG-UI SUMMARY="Completed auth endpoints"
+
+Optional:
+  • BLOCKERS - Issues for next agent (e.g., "Need DBA review")
+```
+
+### Handoff with Blockers
+
+```
+📋 Creating Handoff: US-0042
+
+From: AG-API
+To: AG-UI
+Summary: Completed auth endpoints
+Blockers: 2 identified
+
+Files to create:
+───────────────────────────────────────────────
+1. docs/09-agents/comms/US-0042-20260121-handoff.md
+
+## Blockers
+
+⚠️ The following blockers need attention:
+
+1. **Database migration pending**
+   Schema changes need DBA review before deployment.
+   Related: ADR-0015 (database upgrade strategy)
+
+2. **Rate limiting not configured**
+   Need to decide on rate limits for login endpoint.
+   Suggest: /agileflow:adr for rate limiting decision
+
+[AskUserQuestion: "Create handoff with blockers?"]
+```
+
+### Invalid Agent ID
+
+```
+❌ Invalid agent ID: AG-UNKNOWN
+
+Valid agent IDs:
+  • AG-UI - UI/frontend specialist
+  • AG-API - API/backend specialist
+  • AG-DATABASE - Database specialist
+  • AG-CI - CI/CD specialist
+  • AG-TESTING - Testing specialist
+  • AG-DEVOPS - DevOps specialist
+
+Check the FROM and TO parameters.
+
+Usage:
+/agileflow:handoff STORY=US-0042 FROM=AG-API TO=AG-UI SUMMARY="..."
+```

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:
@@ -91,3 +92,78 @@ Print a concise, one-screen overview:
 <!-- {{COMMAND_LIST}} -->
 
 OUTPUT: plain markdown only (no file writes)
+
+---
+
+## Expected Output
+
+```markdown
+# AgileFlow System Overview
+
+## Folder Structure
+
+```
+docs/
+├── 00-meta/           # Metadata and configuration
+├── 01-brainstorming/  # Ideas and proposals
+├── 02-practices/      # Development guidelines
+├── 03-decisions/      # Architecture Decision Records (ADRs)
+├── 04-architecture/   # System design documentation
+├── 05-epics/          # Epic definitions (EP-XXXX.md)
+├── 06-stories/        # User stories by epic (US-XXXX-<slug>.md)
+├── 07-testing/        # Test plans and coverage
+├── 08-project/        # Project overview, roadmaps, reviews
+├── 09-agents/         # Agent communication
+│   ├── status.json    # Story/epic status tracking
+│   └── bus/log.jsonl  # Inter-agent message bus
+└── 10-research/       # Research notes and findings
+```
+
+## Key Concepts
+
+**Epics** (EP-XXXX): Large features broken into stories
+**Stories** (US-XXXX): Work items with acceptance criteria
+**ADRs**: Architecture Decision Records for technical choices
+**status.json**: Central source of truth for story/epic status
+**bus/log.jsonl**: Async message bus for agent coordination
+
+## Daily Workflow
+
+1. Pick a ready story from status.json
+2. Mark as `in-progress`
+3. Implement to acceptance criteria
+4. Write/update tests
+5. Create PR
+6. Mark as `in-review`
+7. After merge: Mark as `done`
+
+## WIP Limits
+
+- **Max 2 stories per agent** in progress or review
+- Complete or unblock before starting new work
+
+## Available Commands
+
+### Project Management
+- `/agileflow:epic` - Create a new epic
+- `/agileflow:story` - Create a user story
+- `/agileflow:status` - Update story status
+- `/agileflow:board` - Visual kanban board
+- `/agileflow:sprint` - Plan sprint stories
+
+### Development
+- `/agileflow:babysit` - Guided implementation mentor
+- `/agileflow:review` - AI code review
+- `/agileflow:pr` - Generate PR description
+- `/agileflow:tests` - Generate test cases
+
+### Documentation
+- `/agileflow:adr` - Create architecture decision
+- `/agileflow:docs` - Generate documentation
+- `/agileflow:changelog` - Generate changelog entry
+
+### Utilities
+- `/agileflow:help` - This overview
+- `/agileflow:diagnose` - System health check
+- `/agileflow:configure` - Setup AgileFlow
+```

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/pr.md

@@ -227,3 +227,99 @@ ACTIONS
 3) Suggest a Conventional Commit subject for squash.
 
 No file writes.
+
+---
+
+## Expected Output
+
+### Successful PR Description
+
+```
+📝 Generating PR description for US-0042...
+
+Reading story file: docs/06-stories/EP-0010/US-0042-login-form.md
+✅ Found epic: EP-0010 (User Authentication)
+✅ Found 3 acceptance criteria
+✅ Found 1 dependency: US-0041
+
+───────────────────────────────────────────────────────────
+PASTE-READY PR BODY (Copy everything below this line)
+───────────────────────────────────────────────────────────
+
+## US-0042: Implement Login Form with Validation
+
+### Summary
+
+Implements the user login form with email/password validation as part of the
+User Authentication epic (EP-0010). This PR adds client-side validation,
+error handling, and integration with the authentication API.
+
+### Linked Issues
+
+- Closes #US-0042
+- Depends on #US-0041 (Authentication API)
+
+### Acceptance Criteria
+
+- [x] User can enter email and password
+- [x] Form validates email format
+- [ ] Form shows error messages for invalid input
+- [x] Submit button disabled while validating
+
+### Test Evidence
+
+- `npm test src/components/LoginForm.test.tsx` - 12 tests passing
+- Manual testing: Verified on Chrome, Firefox, Safari
+- Screenshot: login-form-validation.png
+
+### Screenshots
+
+![Login Form](./screenshots/login-form.png)
+
+### Risk Assessment
+
+- **Low risk**: UI-only changes, no backend modifications
+- **Rollback**: Revert this PR if issues detected
+
+### Code Owners
+
+@frontend-team
+
+───────────────────────────────────────────────────────────
+
+**Suggested commit message:**
+```
+feat(auth): implement login form with validation
+
+Closes US-0042
+```
+
+[AskUserQuestion: "Use this PR description?"]
+```
+
+### Missing Story ID
+
+```
+❌ Missing required input: STORY
+
+Usage:
+/agileflow:pr STORY=US-0042 TITLE="Login Form"
+
+Optional parameters:
+- AC_CHECKED="1,2,4" - Mark AC items 1, 2, 4 as checked
+- TEST_EVIDENCE="npm test passes, manual QA complete"
+- NOTES="Additional context for reviewers"
+```
+
+### Story File Not Found
+
+```
+❌ Story file not found
+
+Searched:
+- docs/06-stories/US-0042.md
+- docs/06-stories/EP-*/US-0042-*.md
+
+Create the story first:
+/agileflow:story EPIC=EP-0010 STORY=US-0042 TITLE="Login Form" OWNER=AG-UI
+```

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