agileflow 2.94.1 → 2.95.1

package/src/core/commands/audit.md

@@ -393,6 +393,99 @@ Then run audit again.
 
 ---
 
+## Expected Output
+
+### Success - Story Passes Audit
+
+```
+========================================
+      STORY AUDIT: US-0129
+========================================
+
+TESTS
+Command: npm test
+Result: PASSED (2,201 passed, 0 failed)
+Duration: 45.2s
+
+ACCEPTANCE CRITERIA
+[x] Create packages/cli/src/core/commands/audit.md
+[x] Accept story ID as argument
+[x] Run tests and report pass/fail
+[x] Check acceptance criteria met
+[x] Prompt for learnings to capture
+[x] Output: PASS/FAIL with recommended next action
+[x] On PASS, suggest marking story complete
+
+AC Verification: 7/7 (100%)
+
+========================================
+      AUDIT RESULT: PASS
+========================================
+Tests: PASSING
+AC: ALL VERIFIED (7/7)
+
+Learnings captured:
+- GSD audit pattern successfully integrated
+
+NEXT STEPS:
+1. Mark story complete: /agileflow:status US-0129 STATUS=done
+2. Review epic progress: /agileflow:epic EP-0022
+```
+
+### Error - Story Fails Audit
+
+```
+========================================
+      STORY AUDIT: US-0129
+========================================
+
+TESTS
+Command: npm test
+Result: FAILED (40 passed, 3 failed)
+Duration: 12.8s
+
+ACCEPTANCE CRITERIA
+[x] Create packages/cli/src/core/commands/audit.md
+[x] Accept story ID as argument
+[x] Run tests and report pass/fail
+[ ] Check acceptance criteria met
+[ ] Prompt for learnings to capture
+[x] Output: PASS/FAIL with recommended next action
+[x] On PASS, suggest marking story complete
+
+AC Verification: 5/7 (71%)
+
+========================================
+      AUDIT RESULT: FAIL
+========================================
+Tests: FAILING (3 failed)
+AC: PARTIAL (5/7)
+
+BLOCKING ISSUES:
+- Test: audit.test.ts:42 - Expected PASS verdict
+- AC: "Check acceptance criteria met" - Not implemented
+- AC: "Prompt for learnings" - Missing
+
+NEXT STEPS:
+1. Fix failing tests
+2. Complete missing AC items
+3. Re-run: /agileflow:audit US-0129
+```
+
+### Error - Story Not Found
+
+```
+❌ Story US-9999 not found in status.json
+
+Available in_progress stories:
+- US-0129: Create /agileflow:audit command
+- US-0130: Add phase handoff summaries
+
+Run: /agileflow:audit US-0129
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:verify` - Run tests only (no AC check)

package/src/core/commands/auto.md

@@ -474,6 +474,79 @@ OUTPUT
 
 ---
 
+## Expected Output
+
+### Success - Stories Generated
+
+```
+🔍 Analyzing source: docs/requirements/auth-prd.md
+✓ Source type: Product Requirements Document (PRD)
+✓ Found 7 feature areas
+
+📋 Story Generation Preview
+══════════════════════════════════════════════════════════════
+Source: docs/requirements/auth-prd.md
+Epic: EP-0010 (User Authentication)
+Stories to Create: 7
+
+1. US-0050: User registration form with validation (1.5d, AG-API)
+2. US-0051: User login with credentials (1d, AG-API)
+3. US-0052: Password reset flow (1d, AG-API)
+4. US-0053: OAuth Google integration (1.5d, AG-API)
+5. US-0054: OAuth GitHub integration (1.5d, AG-API)
+6. US-0055: Rate limiting middleware (0.5d, AG-CI)
+7. US-0056: Session management service (1d, AG-API)
+
+Total Estimate: 8.5 days
+Owners: AG-API (6), AG-CI (1)
+══════════════════════════════════════════════════════════════
+
+Create these stories? (YES/NO)
+```
+
+After confirmation:
+```
+✓ Created docs/06-stories/EP-0010/US-0050-user-registration.md
+✓ Created docs/06-stories/EP-0010/US-0051-user-login.md
+✓ Created docs/06-stories/EP-0010/US-0052-password-reset.md
+✓ Created docs/06-stories/EP-0010/US-0053-oauth-google.md
+✓ Created docs/06-stories/EP-0010/US-0054-oauth-github.md
+✓ Created docs/06-stories/EP-0010/US-0055-rate-limiting.md
+✓ Created docs/06-stories/EP-0010/US-0056-session-management.md
+✓ Created 7 test stubs in docs/07-testing/test-cases/
+✓ Updated status.json with 7 stories
+✓ Logged 7 assignments to bus
+
+🎉 Successfully generated 7 stories for EP-0010
+```
+
+### Error - Invalid Source
+
+```
+❌ Error: Source file not found
+Path: docs/requirements/nonexistent.md
+
+Please provide a valid source path:
+- PRD document (.md, .pdf)
+- API spec (openapi.yaml, swagger.json)
+- Mockup (Figma URL, .png, .jpg)
+```
+
+### Error - Source Not Parseable
+
+```
+❌ Error: Could not extract requirements from source
+File: docs/assets/logo.png
+
+Supported source types:
+- Product Requirements Documents (PRD)
+- API specifications (OpenAPI/Swagger)
+- Design mockups with annotations
+- Mermaid flow diagrams
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:story` - Create user stories manually

package/src/core/commands/babysit.md

@@ -11,6 +11,7 @@ compact_context:
     - "{{RULES:delegation}}"
     - "STUCK DETECTION: If same error 2+ times, suggest /agileflow:research:ask with 200+ line detailed prompt"
     - "Research prompts MUST include: 50+ lines actual code, exact error, what was tried, 3+ specific questions"
+    - "PLAN FILE CONTEXT: BEFORE ExitPlanMode, EDIT plan file to add babysit rules header at TOP - rules survive context clear"
     - "STORY CLAIMING: Run 'node .agileflow/scripts/lib/story-claiming.js claim <id>' IMMEDIATELY after user selects story"
     - "STORY CLAIMING: Run 'node .agileflow/scripts/lib/story-claiming.js others' BEFORE suggesting stories, exclude 🔒 claimed"
     - "STORY CLAIMING: Run 'node .agileflow/scripts/lib/story-claiming.js release <id>' when story marked done"
@@ -328,6 +329,52 @@ Use TodoWrite for any task with 3+ steps. Update status as you complete each ste
 
 ---
 
+### 🚨 RULE #6: PLAN FILE CONTEXT PRESERVATION
+
+**BEFORE calling ExitPlanMode**, you MUST add a babysit rules header to your plan file.
+
+**WHY**: When user selects "Clear context and bypass permissions", the plan file is the ONLY context that survives. Embedding rules in the plan file ensures babysit workflow continues after context clear.
+
+**STEPS**:
+1. Before calling ExitPlanMode, use the Edit tool to add this header to the TOP of your plan file:
+
+```markdown
+## ⚠️ MANDATORY IMPLEMENTATION RULES (from /babysit)
+
+These rules MUST be followed during implementation:
+1. **ALWAYS end your final response with AskUserQuestion tool** offering next steps
+2. **Use EnterPlanMode** if any NEW non-trivial tasks arise during implementation
+3. **Delegate complex work** to domain experts via Task tool
+4. **Track progress** with TodoWrite for multi-step work
+
+After implementation completes, you MUST call AskUserQuestion with options like:
+- "Run tests to verify"
+- "Continue to next task"
+- "Review changes"
+- "Pause here"
+
+---
+```
+
+2. Then call ExitPlanMode
+
+**EXAMPLE PLAN FILE STRUCTURE**:
+```markdown
+# Plan: Add User Profile Feature
+
+## ⚠️ MANDATORY IMPLEMENTATION RULES (from /babysit)
+[rules as above]
+
+---
+
+## Implementation Plan
+1. Create database schema...
+2. Add API endpoint...
+3. Build UI component...
+```
+
+---
+
 ### ANTI-PATTERNS (DON'T DO THESE)
 
 ❌ End response with text question instead of AskUserQuestion tool
@@ -361,23 +408,28 @@ Use TodoWrite for any task with 3+ steps. Update status as you complete each ste
    ```
 
 **Phase 2: Plan Mode (for non-trivial tasks)**
-6. Call `EnterPlanMode` tool
-7. Explore codebase with Glob, Grep, Read
-8. Design approach, write to plan file
-9. Call `ExitPlanMode` for user approval
+6. **Set restoration flag** (backup for context clear):
+   ```bash
+   node -e "const fs=require('fs');const p='docs/09-agents/session-state.json';if(fs.existsSync(p)){const s=JSON.parse(fs.readFileSync(p,'utf8'));s.babysit_pending_restore=true;fs.writeFileSync(p,JSON.stringify(s,null,2)+'\n');}"
+   ```
+7. Call `EnterPlanMode` tool
+8. Explore codebase with Glob, Grep, Read
+9. Design approach, write to plan file
+10. **CRITICAL: Add babysit rules header** to TOP of plan file (Rule #6)
+11. Call `ExitPlanMode` for user approval
 
 **Phase 3: Execution**
-10. Delegate to experts based on scope
-11. Collect results if async (TaskOutput)
-12. Verify tests pass
+12. Delegate to experts based on scope
+13. Collect results if async (TaskOutput)
+14. Verify tests pass
 
 **Phase 4: Completion**
-13. Update status.json (mark story done)
-14. **RELEASE THE STORY claim:**
+15. Update status.json (mark story done)
+16. **RELEASE THE STORY claim:**
     ```bash
     node .agileflow/scripts/lib/story-claiming.js release <story-id>
     ```
-15. Present next steps via AskUserQuestion
+17. Present next steps via AskUserQuestion
 
 ---
 
@@ -445,6 +497,9 @@ Present top 3-5 via AskUserQuestion, always include "Other" option.
 - Delegate complex work to experts
 - If stuck 2+ times → research prompt
 - Use state narration markers (📍🔀🔄⚠️✅) for visibility
+- **PLAN FILE CONTEXT - CRITICAL:**
+  BEFORE ExitPlanMode, EDIT the plan file to add babysit rules header at TOP
+  This ensures rules survive "Clear context and bypass permissions"
 - **STORY CLAIMING - CRITICAL:**
   1. BEFORE suggesting: `node .agileflow/scripts/lib/story-claiming.js others` → exclude 🔒
   2. AFTER user selects: `node .agileflow/scripts/lib/story-claiming.js claim <id>`
@@ -773,7 +828,7 @@ When stuck detection triggers:
 | Redo work when wrong | Get alignment before coding |
 | User surprises | User approves approach |
 
-### Plan Mode Flow
+### Plan Mode Flow (with Context Preservation)
 
 1. **Enter** - Call `EnterPlanMode` tool
 2. **Explore** - Use Glob, Grep, Read to understand:
@@ -786,8 +841,22 @@ When stuck detection triggers:
    - Files to modify/create
    - Key decisions and trade-offs
    - Testing approach
-4. **Approve** - Call `ExitPlanMode` for user review
-5. **Execute** - Implement the approved plan
+4. **CRITICAL: Add Babysit Header** - Edit the plan file to include this at the TOP:
+   ```markdown
+   ## ⚠️ MANDATORY IMPLEMENTATION RULES (from /babysit)
+
+   These rules MUST be followed during implementation:
+   1. ALWAYS end your final response with AskUserQuestion tool
+   2. Use EnterPlanMode if new non-trivial tasks arise
+   3. Delegate complex work to domain experts
+   4. Track progress with TodoWrite
+
+   After implementation, call AskUserQuestion with next step options.
+
+   ---
+   ```
+5. **Approve** - Call `ExitPlanMode` for user review
+6. **Execute** - Implement (rules survive context clear because they're in plan file)
 
 ### Plan Mode Examples
 
@@ -1061,6 +1130,93 @@ Based on your project state:
 
 ---
 
+## Expected Output
+
+### Success - Mentor Ready
+
+```
+**AgileFlow Mentor** ready. I'll coordinate domain experts for your implementation.
+
+Based on your project state:
+
+📍 Current: EP-0026 (Q1 2026 Codebase Improvements)
+   - 18/24 stories completed (75%)
+   - 1 in-progress: US-0203
+
+Suggested next steps:
+1. ⭐ US-0205: Add integration tests for color system (Ready)
+2. ⭐ US-0206: Create error handling patterns (Ready)
+3. ✓ US-0203: Interactive Command Documentation (Continue)
+
+**My approach:**
+1. You select a task
+2. I enter plan mode to explore and design the approach
+3. You approve the plan
+4. I execute (directly or via domain experts)
+```
+
+### Success - Loop Mode Started
+
+```
+🔄 Loop Mode Initialized
+══════════════════════════════════════════════════════════════
+
+Epic: EP-0042 (User Authentication)
+Stories: 8 total, 3 completed, 5 remaining
+Mode: loop (autonomous)
+Max iterations: 20
+
+Starting with: US-0050 (User Registration)
+Status: ready → in_progress
+
+📍 Working on: US-0050
+   Estimate: 1.5d
+   Owner: AG-API
+
+Proceeding with implementation...
+```
+
+### Success - Expert Delegation
+
+```
+🔀 Spawning domain expert...
+
+Task: Add sessions table for user login tracking
+Expert: agileflow-database
+Status: Running in background
+
+[Agent output will appear when complete]
+
+📍 Waiting for database expert...
+   Task ID: task-abc123
+```
+
+### Error - Stuck Detection
+
+```
+⚠️ Stuck Detection Triggered
+
+I've tried 2 approaches but we're still hitting the same error:
+
+Error: [auth] unauthorized_client
+  at AuthHandler (node_modules/next-auth/src/lib/...)
+
+This seems like a case where external research would help -
+the issue involves next-auth OAuth that needs more context.
+
+Generating research prompt with /agileflow:research:ask...
+
+The prompt includes:
+- 50+ lines of your auth implementation
+- Exact error message and stack trace
+- What I've already tried
+- 3 specific questions
+
+Copy and paste into ChatGPT/Claude web, then share results here.
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:sprint` - Sprint planning with velocity forecasting

package/src/core/commands/baseline.md

@@ -660,6 +660,79 @@ Claude: 🧪 Verifying all requirements...
 
 ---
 
+## Expected Output
+
+### Success - Baseline Created
+
+```
+🧪 Verifying all requirements...
+
+✅ Tests: 42/42 passing (12.3s)
+✅ Git: Clean working tree
+✅ Stories: 3 in-progress (all verified)
+
+Creating baseline...
+✅ Git tag: agileflow-baseline-20251206-143000
+✅ environment.json updated
+✅ session-state.json updated
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Baseline Established
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tag: agileflow-baseline-20251206-143000
+Commit: abc123def456
+Message: Major milestone - v1.0 ready
+Tests: 42/42 passing
+Stories: US-0043, US-0044, US-0045
+
+To push to team:
+  git push origin agileflow-baseline-20251206-143000
+```
+
+### Error - Tests Failing
+
+```
+🧪 Verifying all requirements...
+
+❌ Tests FAILED: 40/42 passing (2 failed)
+
+Cannot create baseline with failing tests.
+
+Run /agileflow:verify to see details.
+Fix failing tests before creating baseline.
+```
+
+### Error - Uncommitted Changes
+
+```
+🧪 Verifying all requirements...
+
+❌ Git: Uncommitted changes detected
+
+   M  src/api/auth.js
+   ?? src/api/new-feature.js
+
+Commit or stash changes before creating baseline:
+  git add . && git commit -m "message"
+  # or
+  git stash
+```
+
+### Error - No Stories in Progress
+
+```
+🧪 Verifying all requirements...
+
+⚠️ No in-progress stories with passing tests
+
+Baselines should mark meaningful progress.
+Assign stories to work on first:
+  /agileflow:assign STORY=US-XXXX
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:verify` - Run tests and update status

package/src/core/commands/batch.md

@@ -478,6 +478,70 @@ Future versions may add: coverage, lint, types gates.
 
 ---
 
+## Expected Output
+
+### Success - Batch Map Operation
+
+```
+🔄 Batch Processing: map
+Items: 5 files
+Processor: test-gate
+
+Processing...
+[1/5] ✅ src/api/auth.js - tests passed (2.1s)
+[2/5] ✅ src/api/users.js - tests passed (1.8s)
+[3/5] ❌ src/api/orders.js - 2 tests failed
+[4/5] ✅ src/api/products.js - tests passed (1.5s)
+[5/5] ✅ src/api/payments.js - tests passed (2.3s)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Batch Complete: 4/5 passed (80%)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Failed items:
+- src/api/orders.js: AssertionError: expected 200
+
+Run with FAIL_FAST=true to stop on first failure.
+```
+
+### Success - Parallel Batch
+
+```
+🔄 Batch Processing: pmap (parallel)
+Items: 8 stories
+Concurrency: 4
+
+[============================] 100% (8/8)
+
+Results:
+✅ US-0050: completed
+✅ US-0051: completed
+✅ US-0052: completed
+⏳ US-0053: in_progress (blocked by external API)
+✅ US-0054: completed
+✅ US-0055: completed
+✅ US-0056: completed
+✅ US-0057: completed
+
+Total time: 45.2s (parallel) vs ~180s (sequential)
+```
+
+### Error - Invalid Operation
+
+```
+❌ Error: Unknown batch operation: aggregate
+
+Supported operations:
+- map: Transform each item
+- pmap: Parallel map
+- filter: Select matching items
+- reduce: Aggregate results
+
+Usage: /agileflow:batch OP=map ITEMS=<list> FN=<processor>
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:babysit` - Mentor workflow

package/src/core/commands/blockers.md

@@ -532,6 +532,66 @@ If yes, suggest:
 
 ---
 
+## Expected Output
+
+### Success - Blockers Found
+
+```
+🚧 Blocker Analysis
+══════════════════════════════════════════════════════════════
+
+📍 DEPENDENCY BLOCKERS (2)
+┌──────────────────────────────────────────────────────────────┐
+│ US-0053: OAuth Google integration                            │
+│ ⏳ Blocked by: US-0051 (User login) - in_progress            │
+│ ETA: ~2 days (based on story estimate)                       │
+├──────────────────────────────────────────────────────────────┤
+│ US-0056: Session management                                  │
+│ ⏳ Blocked by: US-0050 (User registration) - in_review       │
+│ ETA: <1 day (awaiting review)                                │
+└──────────────────────────────────────────────────────────────┘
+
+🔧 TECHNICAL BLOCKERS (1)
+┌──────────────────────────────────────────────────────────────┐
+│ US-0055: Rate limiting middleware                            │
+│ 🔧 Blocker: Missing Redis configuration                      │
+│ Suggested: See ADR-0015 for caching decisions                │
+└──────────────────────────────────────────────────────────────┘
+
+📊 Summary: 3 blockers across 3 stories
+Suggested Actions:
+- /agileflow:status US-0050 STATUS=done (if review passed)
+- /agileflow:adr for Redis decision
+```
+
+### Success - No Blockers
+
+```
+🚧 Blocker Analysis
+══════════════════════════════════════════════════════════════
+
+✅ No blockers found!
+
+All in-progress stories are unblocked.
+Ready: 5 stories awaiting assignment.
+
+Run /agileflow:board to see full status.
+```
+
+### Error - No Stories in Epic
+
+```
+❌ Error: No stories found in EP-0099
+
+Create stories first:
+  /agileflow:story EPIC=EP-0099 TITLE="..."
+
+Or check epic exists:
+  /agileflow:epic:view EP-0099
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:status` - Update story status

package/src/core/commands/board.md

@@ -433,6 +433,72 @@ OUTPUT
 
 ---
 
+## Expected Output
+
+### Success - Kanban Board
+
+```
+📋 AgileFlow Kanban Board
+Updated: 2026-01-29 09:45:00
+Epic: EP-0026 (Q1 2026 Improvements)
+══════════════════════════════════════════════════════════════════════════════
+
+│ READY (3)        │ IN PROGRESS (2)  │ IN REVIEW (1)    │ DONE (15)       │
+├──────────────────┼──────────────────┼──────────────────┼─────────────────┤
+│ US-0200 [P2]     │ US-0198 [P2]     │ US-0195 [P1]     │ US-0186 ✓       │
+│ DI for Gen..     │ Color consol..   │ Path valid..     │ US-0187 ✓       │
+│ AG-API           │ AG-DEVOPS ●      │ AG-API           │ US-0188 ✓       │
+│                  │                  │                  │ US-0189 ✓       │
+│ US-0203 [P2]     │ US-0199 [P2]     │                  │ US-0190 ✓       │
+│ Command docs     │ Path resolve..   │                  │ ...             │
+│ AG-DEVOPS        │ AG-API ●         │                  │ +10 more        │
+│                  │                  │                  │                 │
+│ US-0205 [P3]     │                  │                  │                 │
+│ Agent matrix     │                  │                  │                 │
+│ AG-DOCS          │                  │                  │                 │
+══════════════════════════════════════════════════════════════════════════════
+
+WIP Limit: 3/3 ⚠️ (at capacity)
+● = Currently active
+
+📊 Statistics:
+- Total: 21 stories
+- Velocity: 4.2 stories/week
+- Blocked: 0
+
+Suggested: Complete in-progress work before pulling new stories.
+```
+
+### Success - Filtered View
+
+```
+📋 AgileFlow Kanban Board (Filtered: AG-API)
+══════════════════════════════════════════════════════════════
+
+Stories owned by AG-API: 8 total
+- Ready: 2
+- In Progress: 1
+- In Review: 1
+- Done: 4
+
+[Board shows only AG-API stories...]
+```
+
+### Error - Epic Not Found
+
+```
+❌ Error: Epic not found: EP-9999
+
+Available epics:
+- EP-0026: Q1 2026 Improvements (21 stories)
+- EP-0025: Session System (8 stories)
+- EP-0024: Visual E2E Testing (6 stories)
+
+Usage: /agileflow:board [EPIC=EP-XXXX]
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:sprint` - Sprint planning