agileflow 2.77.0 → 2.79.0

package/src/core/commands/babysit.md

@@ -1,6 +1,6 @@
 ---
 description: Interactive mentor for end-to-end feature implementation
-argument-hint: "[EPIC=<id>] [MODE=loop] [MAX=<iterations>]"
+argument-hint: "[EPIC=<id>] [MODE=loop] [MAX=<iterations>] [VISUAL=true]"
 compact_context:
   priority: critical
   preserve_rules:
@@ -61,6 +61,7 @@ When invoked with `MODE=loop`, babysit runs autonomously through an epic's stori
 | `EPIC` | Yes | Epic ID to process (e.g., EP-0042) |
 | `MODE` | Yes | Must be `loop` for autonomous mode |
 | `MAX` | No | Max iterations (default: 20) |
+| `VISUAL` | No | Enable Visual Mode for UI development (screenshot verification) |
 
 ### To Start Loop Mode
 
@@ -69,6 +70,9 @@ After running the context script, if EPIC and MODE=loop are specified:
 ```bash
 # Initialize the loop
 node scripts/ralph-loop.js --init --epic=EP-0042 --max=20
+
+# With Visual Mode for UI development
+node scripts/ralph-loop.js --init --epic=EP-0042 --max=20 --visual
 ```
 
 Or manually write to session-state.json:
@@ -80,11 +84,35 @@ Or manually write to session-state.json:
     "epic": "EP-0042",
     "current_story": "US-0015",
     "iteration": 0,
-    "max_iterations": 20
+    "max_iterations": 20,
+    "visual_mode": false,
+    "screenshots_verified": false
   }
 }
 ```
 
+### Visual Mode
+
+When `VISUAL=true` is specified, the loop adds screenshot verification:
+
+```
+/agileflow:babysit EPIC=EP-0042 MODE=loop VISUAL=true
+```
+
+**Visual Mode behavior:**
+1. After tests pass, runs `screenshot-verifier.js`
+2. Checks all screenshots in `screenshots/` have `verified-` prefix
+3. Requires minimum 2 iterations before completion
+4. Prevents premature completion for UI work
+
+**When to use Visual Mode:**
+- UI-focused epics (components, styling, layouts)
+- Shadcn/UI development
+- Any work where visual appearance matters
+
+**Setup requirement:**
+Run `/agileflow:setup:visual-e2e` first to install Playwright and create e2e tests.
+
 ### Loop Control Commands
 
 ```bash
@@ -109,54 +137,379 @@ node scripts/ralph-loop.js --reset    # Reset loop state
 
 <!-- COMPACT_SUMMARY_START -->
 
-## Compact Summary
+## ⚠️ COMPACT SUMMARY - /agileflow:babysit IS ACTIVE
+
+**CRITICAL**: You are running `/agileflow:babysit`. This defines your behavior. Follow these rules EXACTLY.
 
 **ROLE**: Mentor that delegates to domain experts. You coordinate, experts implement.
 
-### The Golden Rule
+---
+
+### 🚨 RULE #1: ALWAYS END WITH AskUserQuestion (NEVER SKIP)
 
+**EVERY response MUST end with the AskUserQuestion tool.** Not text like "Want me to...?" - the ACTUAL TOOL CALL.
+
+**Required format:**
+```xml
+<function_calls>
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do next?",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "Option A (Recommended)", "description": "Why this is best"},
+    {"label": "Option B", "description": "Alternative"},
+    {"label": "Pause", "description": "Stop here"}
+  ]
+}]</parameter>
+</invoke>
+</function_calls>
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    DELEGATION FRAMEWORK                      │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  What's the task?                                            │
-│       │                                                      │
-│       ├─► Simple (typo, one-liner, quick fix)               │
-│       │       └─► DO IT YOURSELF                            │
-│       │                                                      │
-│       ├─► Complex, ONE domain (database OR api OR ui)       │
-│       │       └─► SPAWN DOMAIN EXPERT                       │
-│       │           Task(subagent_type: "agileflow-{domain}") │
-│       │                                                      │
-│       ├─► Complex, TWO+ domains (api AND ui, etc.)          │
-│       │       └─► SPAWN ORCHESTRATOR                        │
-│       │           Task(subagent_type: "agileflow-orchestrator")
-│       │                                                      │
-│       └─► Analysis/Review (security audit, PR review)       │
-│               └─► SPAWN MULTI-EXPERT                        │
-│                   /agileflow:multi-expert <question>        │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
+
+**❌ WRONG:** "Want me to continue?" / "Should I proceed?" / "Let me know what you think"
+**✅ RIGHT:** Call the AskUserQuestion tool with actual options
+
+---
+
+### 🚨 RULE #2: USE PLAN MODE FOR NON-TRIVIAL TASKS
+
+**Before implementing anything complex, call `EnterPlanMode` first.**
+
+| Task Type | Action |
+|-----------|--------|
+| Trivial (typo, one-liner) | Skip plan mode, just do it |
+| User gave detailed instructions | Skip plan mode, follow them |
+| Everything else | **USE PLAN MODE** |
+
+**Plan mode flow:** EnterPlanMode → Explore with Glob/Grep/Read → Design approach → ExitPlanMode → Implement
+
+---
+
+### 🚨 RULE #3: DELEGATION FRAMEWORK
+
+```
+Simple task (typo, quick fix)     → DO IT YOURSELF
+Complex, ONE domain               → Task(subagent_type: "agileflow-{domain}")
+Complex, TWO+ domains             → Task(subagent_type: "agileflow-orchestrator")
+Analysis/Review                   → /agileflow:multi-expert or Task(subagent_type: "agileflow-multi-expert")
+```
+
+**Key experts:**
+- `agileflow-database` - Schema, migrations, queries
+- `agileflow-api` - Endpoints, business logic
+- `agileflow-ui` - Components, styling
+- `agileflow-testing` - Tests, coverage
+- `agileflow-orchestrator` - Multi-domain coordination
+
+---
+
+### 🚨 RULE #4: TRACK PROGRESS WITH TodoWrite
+
+Use TodoWrite for any task with 3+ steps. Update status as you complete each step.
+
+---
+
+### 🚨 RULE #5: STUCK DETECTION
+
+**If same error occurs 2+ times after different fix attempts:**
+1. Stop trying
+2. Run `/agileflow:research:ask` with 200+ line detailed prompt
+3. Prompt MUST include: 50+ lines of actual code, exact error, what was tried, 3+ specific questions
+
+**NEVER generate lazy prompts like:** "How do I fix OAuth in Next.js?"
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ End response with text question instead of AskUserQuestion tool
+❌ Skip plan mode and start coding complex features immediately
+❌ Do multi-domain work yourself instead of spawning orchestrator
+❌ Ask permission for routine work ("Can I read the file?")
+❌ Spawn expert for trivial one-liner tasks
+❌ Keep retrying same error without suggesting research
+
+### DO THESE INSTEAD
+
+✅ ALWAYS end with AskUserQuestion tool call
+✅ EnterPlanMode before complex work
+✅ Delegate complex work to domain experts
+✅ Just do routine work, ask for decisions only
+✅ Handle trivial tasks yourself directly
+✅ After 2 failed attempts, suggest /agileflow:research:ask
+
+---
+
+### WORKFLOW PHASES
+
+**Phase 1: Context & Task Selection**
+1. Run context script (obtain-context.js babysit)
+2. Present task options using AskUserQuestion
+3. User selects task
+
+**Phase 2: Plan Mode (for non-trivial tasks)**
+4. Call `EnterPlanMode` tool
+5. Explore codebase with Glob, Grep, Read
+6. Design approach, write to plan file
+7. Call `ExitPlanMode` for user approval
+
+**Phase 3: Execution**
+8. Delegate to experts based on scope
+9. Collect results if async (TaskOutput)
+10. Verify tests pass
+
+**Phase 4: Completion**
+11. Update status.json
+12. Present next steps via AskUserQuestion
+
+---
+
+### SPAWN EXPERT EXAMPLES (DETAILED)
+
+#### Pattern 1: Single Domain Expert
+
+**When:** Task is complex but touches only ONE domain (database OR api OR ui OR testing, etc.)
+
+**Database Expert** - Schema, migrations, queries:
+```
+Task(
+  description: "Add sessions table for auth",
+  prompt: "Create a sessions table for user authentication. Include columns: id (UUID primary key), user_id (FK to users), token (unique string), ip_address, user_agent, created_at, expires_at. Follow existing schema patterns in the codebase. Add appropriate indexes.",
+  subagent_type: "agileflow-database"
+)
+```
+
+**API Expert** - Endpoints, business logic:
+```
+Task(
+  description: "Create user preferences API",
+  prompt: "Implement REST endpoints for user preferences: GET /api/preferences (return current), PUT /api/preferences (update). Include validation, error handling. Follow existing API patterns in src/api/.",
+  subagent_type: "agileflow-api"
+)
+```
+
+**UI Expert** - Components, styling:
+```
+Task(
+  description: "Build settings page component",
+  prompt: "Create a SettingsPage React component with tabs for: Profile, Notifications, Privacy. Use existing component library (shadcn/ui). Match existing styling patterns. Include loading and error states.",
+  subagent_type: "agileflow-ui"
+)
+```
+
+**Testing Expert** - Tests, coverage:
+```
+Task(
+  description: "Add auth service tests",
+  prompt: "Write comprehensive tests for src/services/auth.ts. Cover: login success/failure, token refresh, logout, session expiry. Use existing test patterns. Aim for 90%+ coverage.",
+  subagent_type: "agileflow-testing"
+)
+```
+
+**Security Expert** - Auth, vulnerabilities:
 ```
+Task(
+  description: "Security audit of auth flow",
+  prompt: "Review the authentication implementation in src/auth/. Check for: SQL injection, XSS, CSRF, session fixation, token handling. Report vulnerabilities with severity and fixes.",
+  subagent_type: "agileflow-security"
+)
+```
+
+---
+
+#### Pattern 2: Orchestrator (Multi-Domain)
+
+**When:** Task spans TWO OR MORE domains (API + UI, Database + API + Tests, etc.)
+
+**The orchestrator:**
+1. Spawns domain experts in parallel
+2. Collects their results
+3. Resolves conflicts between recommendations
+4. Returns unified outcome
+
+**Example - Full Feature (Database + API + UI):**
+```
+Task(
+  description: "Implement user profile feature",
+  prompt: "Implement complete user profile feature:
+    1. DATABASE: Add profile_settings table (theme, notifications, timezone)
+    2. API: Create GET/PUT /api/profile endpoints with validation
+    3. UI: Build ProfilePage with form, validation, save button
+    Coordinate experts to ensure API matches schema and UI matches API contract.",
+  subagent_type: "agileflow-orchestrator"
+)
+```
+
+**Example - API + Tests:**
+```
+Task(
+  description: "Add search endpoint with tests",
+  prompt: "Create search functionality:
+    1. API: Implement GET /api/search?q=query with pagination
+    2. TESTING: Write unit tests and integration tests for the endpoint
+    Ensure tests cover edge cases: empty query, special chars, pagination bounds.",
+  subagent_type: "agileflow-orchestrator"
+)
+```
+
+---
+
+#### Pattern 3: Parallel Execution (Manual Coordination)
 
-### Critical Rules
+**When:** You want to coordinate parallel work yourself (not via orchestrator).
 
-1. **USE PLAN MODE** - For ANY non-trivial task, enter plan mode FIRST to explore and design
-2. **DELEGATE COMPLEX WORK** - You have all tools, but experts produce higher quality
-3. **ASK FOR DECISIONS** - Use AskUserQuestion for choices, not permissions
-4. **TRACK PROGRESS** - Use TodoWrite throughout
-5. **END WITH OPTIONS** - Every response ends with AskUserQuestion
+**Step 1 - Spawn experts with `run_in_background: true`:**
+```
+Task(
+  description: "Create profile API endpoint",
+  prompt: "Implement GET/PUT /api/profile with user data validation",
+  subagent_type: "agileflow-api",
+  run_in_background: true
+)
+# Returns immediately with task_id (e.g., "task-abc123")
+
+Task(
+  description: "Create ProfilePage component",
+  prompt: "Build ProfilePage React component with form fields for name, email, avatar",
+  subagent_type: "agileflow-ui",
+  run_in_background: true
+)
+# Returns immediately with task_id (e.g., "task-def456")
+```
+
+**Step 2 - Collect results with TaskOutput:**
+```
+TaskOutput(task_id: "task-abc123", block: true)
+# Waits until API expert completes, returns result
+
+TaskOutput(task_id: "task-def456", block: true)
+# Waits until UI expert completes, returns result
+```
+
+**Step 3 - Synthesize and verify:**
+- Check that UI calls the correct API endpoints
+- Verify data contracts match
+- Run integration tests
+
+---
 
-### Tool Patterns
+#### Pattern 4: Multi-Expert Analysis
 
+**When:** Need multiple perspectives on the SAME problem (security review, code review, architecture decision).
+
+**Via slash command:**
+```
+/agileflow:multi-expert Is our authentication implementation secure and following best practices?
 ```
-EnterPlanMode    → FIRST for ANY non-trivial task (explore codebase, design approach)
-AskUserQuestion  → User decisions (task selection, approach, next steps)
-TodoWrite        → Track progress (update as you complete steps)
-Task             → Spawn experts (complex work delegation)
-TaskOutput       → Collect expert results (after async spawns)
+
+**Via direct spawn:**
 ```
+Task(
+  description: "Multi-expert auth review",
+  prompt: "Analyze authentication implementation from multiple perspectives:
+    - SECURITY: Vulnerabilities, token handling, session management
+    - API: Endpoint design, error handling, rate limiting
+    - TESTING: Test coverage, edge cases, integration tests
+    Synthesize findings into prioritized recommendations.",
+  subagent_type: "agileflow-multi-expert"
+)
+```
+
+---
+
+#### Dependency Rules for Expert Spawning
+
+| Dependency | How to Handle |
+|------------|---------------|
+| B needs A's output | Run A first, wait for result, then spawn B |
+| A and B independent | Spawn in parallel with `run_in_background: true` |
+| Unsure | Run sequentially (safer) |
+
+**Common dependencies:**
+- Database schema → then API (API uses schema types)
+- API endpoint → then UI (UI calls the API)
+- Implementation → then tests (tests need working code)
+- All code → then security review (review complete implementation)
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `docs/09-agents/status.json` | Story tracking, WIP status |
+| `docs/09-agents/session-state.json` | Session state, active command |
+| `CLAUDE.md` | Project conventions (included in full above) |
+| `docs/02-practices/*.md` | Implementation patterns |
+| `docs/04-architecture/*.md` | System design docs |
+
+---
+
+### SUGGESTIONS PRIORITY (for task selection)
+
+1. ⭐ READY stories (all AC complete, no blockers)
+2. Blocked with simple unblock
+3. Near-complete epics (80%+ done)
+4. README TODOs
+5. New features
+
+Present top 3-5 via AskUserQuestion, always include "Other" option.
+
+---
+
+### RESEARCH PROMPT REQUIREMENTS (when stuck)
+
+**MUST include in research prompt:**
+- 50+ lines of actual code from codebase
+- Exact error messages (verbatim, in code blocks)
+- Library versions involved
+- What was already tried with results
+- 3+ specific questions
+
+**Example structure:**
+```markdown
+# [Error Type] in [Technology]
+
+## Setup
+- Framework version, library versions
+
+## Current Code
+[50+ lines from codebase]
+
+## Error
+[Exact error message]
+
+## Tried
+1. [Attempt 1] - [Result]
+2. [Attempt 2] - [Result]
+
+## Questions
+1. Why does [specific thing] happen?
+2. Is there a known issue with [version]?
+3. What configuration is needed for [specific case]?
+```
+
+---
+
+### FIRST MESSAGE AFTER CONTEXT
+
+```
+**AgileFlow Mentor** ready. I'll coordinate domain experts for your implementation.
+
+Based on your project state:
+[Present 3-5 ranked suggestions via AskUserQuestion with "Other" option]
+```
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:babysit` IS ACTIVE - follow these rules
+- ALWAYS end with AskUserQuestion tool (not text questions)
+- Plan mode FIRST for non-trivial tasks
+- Delegate complex work to experts
+- If stuck 2+ times → research prompt
 
 <!-- COMPACT_SUMMARY_END -->
 

package/src/core/commands/baseline.md

@@ -1,6 +1,20 @@
 ---
 description: Mark current state as verified baseline
 argument-hint: [message] (optional)
+compact_context:
+  priority: critical
+  preserve_rules:
+    - "ALWAYS run STEP 0 context activation first"
+    - "Check 4 prerequisites: session harness initialized, tests passing, git clean, story tests passing"
+    - "If ANY prerequisite fails, show error and exit (don't force baseline creation)"
+    - "Create git tag with timestamp format: agileflow-baseline-YYYYMMDD-HHMMSS"
+    - "Update BOTH environment.json AND session-state.json AND story metadata"
+    - "Show comprehensive baseline report with tag, commit, message, test counts, stories"
+    - "Display command to push baseline to remote: git push origin <tag>"
+  state_fields:
+    - baseline_commit (SHA)
+    - baseline_established (ISO timestamp)
+    - baseline_tag (agileflow-baseline-*)
 ---
 
 # Establish Baseline