agileflow 2.78.0 → 2.80.0

package/scripts/damage-control-write.js

@@ -15,13 +15,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-
-// Color codes for output
-const c = {
-  red: '\x1b[38;5;203m',
-  reset: '\x1b[0m',
-  dim: '\x1b[2m'
-};
+const { c } = require('../lib/colors');
 
 /**
  * Find project root by looking for .agileflow directory
@@ -54,7 +48,7 @@ function parseSimpleYAML(content) {
   const config = {
     zeroAccessPaths: [],
     readOnlyPaths: [],
-    noDeletePaths: []
+    noDeletePaths: [],
   };
 
   let currentSection = null;
@@ -92,7 +86,7 @@ function loadPatterns(projectRoot) {
   const configPaths = [
     path.join(projectRoot, '.agileflow/config/damage-control-patterns.yaml'),
     path.join(projectRoot, '.agileflow/config/damage-control-patterns.yml'),
-    path.join(projectRoot, '.agileflow/templates/damage-control-patterns.yaml')
+    path.join(projectRoot, '.agileflow/templates/damage-control-patterns.yaml'),
   ];
 
   for (const configPath of configPaths) {
@@ -168,7 +162,7 @@ function validatePath(filePath, config) {
     return {
       action: 'block',
       reason: `Zero-access path: ${zeroMatch}`,
-      detail: 'This file is protected and cannot be accessed'
+      detail: 'This file is protected and cannot be accessed',
     };
   }
 
@@ -178,7 +172,7 @@ function validatePath(filePath, config) {
     return {
       action: 'block',
       reason: `Read-only path: ${readOnlyMatch}`,
-      detail: 'This file is read-only and cannot be written to'
+      detail: 'This file is read-only and cannot be written to',
     };
   }
 
@@ -215,7 +209,7 @@ function main() {
       const result = validatePath(filePath, config);
 
       if (result.action === 'block') {
-        console.error(`${c.red}[BLOCKED]${c.reset} ${result.reason}`);
+        console.error(`${c.coral}[BLOCKED]${c.reset} ${result.reason}`);
         console.error(`${c.dim}${result.detail}${c.reset}`);
         console.error(`${c.dim}File: ${filePath}${c.reset}`);
         process.exit(2);

package/scripts/get-env.js

@@ -156,12 +156,12 @@ function formatOutput(info, asJson = false, compact = false) {
     brand: '\x1b[38;2;232;104;58m', // #e8683a - AgileFlow brand orange
 
     // Vibrant 256-color palette (modern, sleek look)
-    mintGreen: '\x1b[38;5;158m',    // Healthy/success states
-    peach: '\x1b[38;5;215m',        // Warning states
-    coral: '\x1b[38;5;203m',        // Critical/error states
-    lightGreen: '\x1b[38;5;194m',   // Session healthy
-    skyBlue: '\x1b[38;5;117m',      // Directories/paths
-    lavender: '\x1b[38;5;147m',     // Model info
+    mintGreen: '\x1b[38;5;158m', // Healthy/success states
+    peach: '\x1b[38;5;215m', // Warning states
+    coral: '\x1b[38;5;203m', // Critical/error states
+    lightGreen: '\x1b[38;5;194m', // Session healthy
+    skyBlue: '\x1b[38;5;117m', // Directories/paths
+    lavender: '\x1b[38;5;147m', // Model info
   };
 
   // Beautiful compact colorful format (using vibrant 256-color palette)

package/scripts/obtain-context.js

@@ -18,6 +18,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const { c: C, box } = require('../lib/colors');
 
 const DISPLAY_LIMIT = 30000; // Claude Code's Bash tool display limit
 
@@ -28,11 +29,27 @@ if (commandName) {
   if (fs.existsSync(sessionStatePath)) {
     try {
       const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
-      state.active_command = {
+
+      // Initialize active_commands array if not present
+      if (!Array.isArray(state.active_commands)) {
+        state.active_commands = [];
+      }
+
+      // Remove any existing entry for this command (avoid duplicates)
+      state.active_commands = state.active_commands.filter(c => c.name !== commandName);
+
+      // Add the new command
+      state.active_commands.push({
         name: commandName,
         activated_at: new Date().toISOString(),
         state: {},
-      };
+      });
+
+      // Remove legacy active_command field (only use active_commands array now)
+      if (state.active_command !== undefined) {
+        delete state.active_command;
+      }
+
       fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
     } catch (e) {
       // Silently continue if session state can't be updated
@@ -40,33 +57,6 @@ if (commandName) {
   }
 }
 
-// ANSI colors
-const C = {
-  reset: '\x1b[0m',
-  dim: '\x1b[2m',
-  bold: '\x1b[1m',
-  cyan: '\x1b[36m',
-  yellow: '\x1b[33m',
-  green: '\x1b[32m',
-  red: '\x1b[31m',
-  magenta: '\x1b[35m',
-  blue: '\x1b[34m',
-  brightCyan: '\x1b[96m',
-  brightYellow: '\x1b[93m',
-  brightGreen: '\x1b[92m',
-  brand: '\x1b[38;2;232;104;58m', // AgileFlow brand orange
-
-  // Vibrant 256-color palette (modern, sleek look)
-  mintGreen: '\x1b[38;5;158m',    // Healthy/success states
-  peach: '\x1b[38;5;215m',        // Warning states
-  coral: '\x1b[38;5;203m',        // Critical/error states
-  lightGreen: '\x1b[38;5;194m',   // Session healthy
-  lightYellow: '\x1b[38;5;228m',  // Session warning
-  skyBlue: '\x1b[38;5;117m',      // Directories/paths
-  lavender: '\x1b[38;5;147m',     // Model info
-  softGold: '\x1b[38;5;222m',     // Cost/money
-};
-
 function safeRead(filePath) {
   try {
     return fs.readFileSync(filePath, 'utf8');
@@ -211,7 +201,8 @@ function generateSummary() {
 
   // Header row (full width, no column divider)
   const title = commandName ? `Context [${commandName}]` : 'Context Summary';
-  const branchColor = branch === 'main' ? C.mintGreen : branch.startsWith('fix') ? C.coral : C.skyBlue;
+  const branchColor =
+    branch === 'main' ? C.mintGreen : branch.startsWith('fix') ? C.coral : C.skyBlue;
   const maxBranchLen = 20;
   const branchDisplay =
     branch.length > maxBranchLen ? branch.substring(0, maxBranchLen - 2) + '..' : branch;
@@ -286,7 +277,12 @@ function generateSummary() {
 
   // Research
   const researchText = researchFiles.length > 0 ? `${researchFiles.length} notes` : 'none';
-  summary += row('Research', researchText, C.lavender, researchFiles.length > 0 ? C.skyBlue : C.dim);
+  summary += row(
+    'Research',
+    researchText,
+    C.lavender,
+    researchFiles.length > 0 ? C.skyBlue : C.dim
+  );
 
   // Epics
   const epicText = epicFiles.length > 0 ? `${epicFiles.length} epics` : 'none';
@@ -370,14 +366,48 @@ function generateFullContent() {
     } else {
       content += `${C.dim}No active session${C.reset}\n`;
     }
-    if (sessionState.active_command) {
+    // Show all active commands (array)
+    if (Array.isArray(sessionState.active_commands) && sessionState.active_commands.length > 0) {
+      const cmdNames = sessionState.active_commands.map(c => c.name).join(', ');
+      content += `Active commands: ${C.skyBlue}${cmdNames}${C.reset}\n`;
+    } else if (sessionState.active_command) {
+      // Backwards compatibility for old format
       content += `Active command: ${C.skyBlue}${sessionState.active_command.name}${C.reset}\n`;
     }
   } else {
     content += `${C.dim}No session-state.json found${C.reset}\n`;
   }
 
-  // 4. DOCS STRUCTURE (using vibrant 256-color palette)
+  // 4. INTERACTION MODE (AskUserQuestion guidance)
+  const metadata = safeReadJSON('docs/00-meta/agileflow-metadata.json');
+  const askUserQuestionConfig = metadata?.features?.askUserQuestion;
+
+  if (askUserQuestionConfig?.enabled) {
+    content += `\n${C.brand}${C.bold}═══ ⚡ INTERACTION MODE: AskUserQuestion ENABLED ═══${C.reset}\n`;
+    content += `${C.dim}${'─'.repeat(60)}${C.reset}\n`;
+    content += `${C.bold}CRITICAL RULE:${C.reset} End ${C.skyBlue}EVERY${C.reset} response with the AskUserQuestion tool.\n\n`;
+    content += `${C.mintGreen}✓ CORRECT:${C.reset} Call the actual AskUserQuestion tool\n`;
+    content += `${C.coral}✗ WRONG:${C.reset} Text like "Want me to continue?" or "What's next?"\n\n`;
+    content += `${C.lavender}Required format:${C.reset}\n`;
+    content += `${C.dim}\`\`\`xml
+<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 approach"},
+    {"label": "Pause", "description": "Stop here for now"}
+  ]
+}]</parameter>
+</invoke>
+\`\`\`${C.reset}\n`;
+    content += `${C.dim}${'─'.repeat(60)}${C.reset}\n`;
+    content += `${C.dim}Mode: ${askUserQuestionConfig.mode || 'all'} | Configure: /agileflow:configure${C.reset}\n\n`;
+  }
+
+  // 5. DOCS STRUCTURE (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Documentation ═══${C.reset}\n`;
   const docsDir = 'docs';
   const docFolders = safeLs(docsDir).filter(f => {
@@ -401,7 +431,7 @@ function generateFullContent() {
     });
   }
 
-  // 5. RESEARCH NOTES - List + Full content of most recent (using vibrant 256-color palette)
+  // 6. RESEARCH NOTES - List + Full content of most recent (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Research Notes ═══${C.reset}\n`;
   const researchDir = 'docs/10-research';
   const researchFiles = safeLs(researchDir).filter(f => f.endsWith('.md') && f !== 'README.md');
@@ -424,7 +454,7 @@ function generateFullContent() {
     content += `${C.dim}No research notes${C.reset}\n`;
   }
 
-  // 6. BUS MESSAGES (using vibrant 256-color palette)
+  // 7. BUS MESSAGES (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Recent Agent Messages ═══${C.reset}\n`;
   const busPath = 'docs/09-agents/bus/log.jsonl';
   const busContent = safeRead(busPath);
@@ -448,7 +478,7 @@ function generateFullContent() {
     content += `${C.dim}No bus log found${C.reset}\n`;
   }
 
-  // 7. KEY FILES - Full content
+  // 8. KEY FILES - Full content
   content += `\n${C.cyan}${C.bold}═══ Key Context Files (Full Content) ═══${C.reset}\n`;
 
   const keyFilesToRead = [
@@ -474,7 +504,7 @@ function generateFullContent() {
   const settingsExists = fs.existsSync('.claude/settings.json');
   content += `\n  ${settingsExists ? `${C.green}✓${C.reset}` : `${C.dim}○${C.reset}`} .claude/settings.json\n`;
 
-  // 8. EPICS FOLDER
+  // 9. EPICS FOLDER
   content += `\n${C.cyan}${C.bold}═══ Epic Files ═══${C.reset}\n`;
   const epicFiles = safeLs('docs/05-epics').filter(f => f.endsWith('.md') && f !== 'README.md');
   if (epicFiles.length > 0) {

package/scripts/ralph-loop.js

@@ -7,12 +7,18 @@
  * It runs as a Stop hook and handles:
  *   1. Checking if loop mode is enabled
  *   2. Running test validation
- *   3. Updating story status on success
- *   4. Feeding context back for next iteration
- *   5. Tracking iterations and enforcing limits
+ *   3. Running screenshot verification (Visual Mode)
+ *   4. Updating story status on success
+ *   5. Feeding context back for next iteration
+ *   6. Tracking iterations and enforcing limits
  *
  * Named after the "Ralph Wiggum" pattern from Anthropic.
  *
+ * Visual Mode:
+ *   When visual_mode is enabled, the loop also verifies that all
+ *   screenshots have been reviewed (verified- prefix). This ensures
+ *   Claude actually looks at UI screenshots before declaring completion.
+ *
  * Usage (as Stop hook):
  *   node scripts/ralph-loop.js
  *
@@ -26,78 +32,46 @@ const fs = require('fs');
 const path = require('path');
 const { execSync, spawnSync } = require('child_process');
 
-// ANSI colors
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-  brand: '\x1b[38;2;232;104;58m',
-};
-
-// Find project root
-function getProjectRoot() {
-  let dir = process.cwd();
-  while (!fs.existsSync(path.join(dir, '.agileflow')) && dir !== '/') {
-    dir = path.dirname(dir);
-  }
-  return dir !== '/' ? dir : process.cwd();
-}
+// Shared utilities
+const { c } = require('../lib/colors');
+const { getProjectRoot } = require('../lib/paths');
+const { safeReadJSON, safeWriteJSON } = require('../lib/errors');
 
 // Read session state
 function getSessionState(rootDir) {
   const statePath = path.join(rootDir, 'docs/09-agents/session-state.json');
-  try {
-    if (fs.existsSync(statePath)) {
-      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
-    }
-  } catch (e) {}
-  return {};
+  const result = safeReadJSON(statePath, { defaultValue: {} });
+  return result.ok ? result.data : {};
 }
 
 // Write session state
 function saveSessionState(rootDir, state) {
   const statePath = path.join(rootDir, 'docs/09-agents/session-state.json');
-  const dir = path.dirname(statePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+  safeWriteJSON(statePath, state, { createDir: true });
 }
 
 // Read status.json for stories
 function getStatus(rootDir) {
   const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
-  try {
-    if (fs.existsSync(statusPath)) {
-      return JSON.parse(fs.readFileSync(statusPath, 'utf8'));
-    }
-  } catch (e) {}
-  return { stories: {}, epics: {} };
+  const result = safeReadJSON(statusPath, { defaultValue: { stories: {}, epics: {} } });
+  return result.ok ? result.data : { stories: {}, epics: {} };
 }
 
 // Save status.json
 function saveStatus(rootDir, status) {
   const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
-  fs.writeFileSync(statusPath, JSON.stringify(status, null, 2) + '\n');
+  safeWriteJSON(statusPath, status);
 }
 
 // Get test command from package.json or metadata
 function getTestCommand(rootDir) {
   // Check agileflow metadata first
-  try {
-    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
-    if (fs.existsSync(metadataPath)) {
-      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
-      if (metadata.ralph_loop?.test_command) {
-        return metadata.ralph_loop.test_command;
-      }
-    }
-  } catch (e) {}
+  const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+  const result = safeReadJSON(metadataPath, { defaultValue: {} });
+
+  if (result.ok && result.data?.ralph_loop?.test_command) {
+    return result.data.ralph_loop.test_command;
+  }
 
   // Default to npm test
   return 'npm test';
@@ -129,6 +103,73 @@ function runTests(rootDir, testCommand) {
   return result;
 }
 
+// Get screenshots directory from metadata or default
+function getScreenshotsDir(rootDir) {
+  try {
+    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      if (metadata.ralph_loop?.screenshots_dir) {
+        return metadata.ralph_loop.screenshots_dir;
+      }
+    }
+  } catch (e) {}
+  return './screenshots';
+}
+
+// Run screenshot verification (Visual Mode)
+function verifyScreenshots(rootDir) {
+  const result = { passed: false, output: '', total: 0, verified: 0, unverified: [] };
+  const screenshotsDir = getScreenshotsDir(rootDir);
+  const fullPath = path.resolve(rootDir, screenshotsDir);
+
+  // Check if directory exists
+  if (!fs.existsSync(fullPath)) {
+    result.passed = true; // No screenshots = nothing to verify
+    result.output = 'No screenshots directory found';
+    return result;
+  }
+
+  // Get all image files
+  const imageExtensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
+  let files;
+  try {
+    files = fs.readdirSync(fullPath).filter(file => {
+      const ext = path.extname(file).toLowerCase();
+      return imageExtensions.includes(ext);
+    });
+  } catch (e) {
+    result.output = `Error reading screenshots directory: ${e.message}`;
+    return result;
+  }
+
+  if (files.length === 0) {
+    result.passed = true;
+    result.output = 'No screenshots found in directory';
+    return result;
+  }
+
+  // Check each file for verified- prefix
+  for (const file of files) {
+    if (file.startsWith('verified-')) {
+      result.verified++;
+    } else {
+      result.unverified.push(file);
+    }
+  }
+
+  result.total = files.length;
+  result.passed = result.unverified.length === 0;
+
+  if (result.passed) {
+    result.output = `All ${result.total} screenshots verified`;
+  } else {
+    result.output = `${result.unverified.length} screenshots missing 'verified-' prefix`;
+  }
+
+  return result;
+}
+
 // Get next ready story in epic
 function getNextStory(status, epicId, currentStoryId) {
   const stories = status.stories || {};
@@ -211,13 +252,16 @@ function handleLoop(rootDir) {
   const status = getStatus(rootDir);
   const iteration = (loop.iteration || 0) + 1;
   const maxIterations = loop.max_iterations || 20;
+  const visualMode = loop.visual_mode || false;
+  const minIterations = visualMode ? 2 : 1; // Visual mode requires at least 2 iterations
 
   console.log('');
   console.log(
     `${c.brand}${c.bold}══════════════════════════════════════════════════════════${c.reset}`
   );
+  const modeLabel = visualMode ? ' [VISUAL MODE]' : '';
   console.log(
-    `${c.brand}${c.bold}  RALPH LOOP - Iteration ${iteration}/${maxIterations}${c.reset}`
+    `${c.brand}${c.bold}  RALPH LOOP - Iteration ${iteration}/${maxIterations}${modeLabel}${c.reset}`
   );
   console.log(
     `${c.brand}${c.bold}══════════════════════════════════════════════════════════${c.reset}`
@@ -261,6 +305,67 @@ function handleLoop(rootDir) {
 
   if (testResult.passed) {
     console.log(`${c.green}✓ Tests passed${c.reset} (${(testResult.duration / 1000).toFixed(1)}s)`);
+
+    // Visual Mode: Also verify screenshots
+    let screenshotResult = { passed: true };
+    if (visualMode) {
+      console.log('');
+      console.log(`${c.blue}Verifying screenshots...${c.reset}`);
+      screenshotResult = verifyScreenshots(rootDir);
+
+      if (screenshotResult.passed) {
+        console.log(`${c.green}✓ ${screenshotResult.output}${c.reset}`);
+        state.ralph_loop.screenshots_verified = true;
+      } else {
+        console.log(`${c.yellow}⚠ ${screenshotResult.output}${c.reset}`);
+        if (screenshotResult.unverified.length > 0) {
+          console.log(`${c.dim}Unverified screenshots:${c.reset}`);
+          screenshotResult.unverified.slice(0, 5).forEach(file => {
+            console.log(`  ${c.yellow}- ${file}${c.reset}`);
+          });
+          if (screenshotResult.unverified.length > 5) {
+            console.log(
+              `  ${c.dim}... and ${screenshotResult.unverified.length - 5} more${c.reset}`
+            );
+          }
+        }
+        state.ralph_loop.screenshots_verified = false;
+      }
+    }
+
+    // Visual Mode: Enforce minimum iterations
+    if (visualMode && iteration < minIterations) {
+      console.log('');
+      console.log(
+        `${c.yellow}⚠ Visual Mode requires ${minIterations}+ iterations for confirmation${c.reset}`
+      );
+      console.log(
+        `${c.dim}Current: iteration ${iteration}. Let loop run once more to confirm.${c.reset}`
+      );
+
+      state.ralph_loop.iteration = iteration;
+      saveSessionState(rootDir, state);
+
+      console.log('');
+      console.log(`${c.brand}▶ Continue reviewing. Loop will verify again.${c.reset}`);
+      return;
+    }
+
+    // Check if both tests AND screenshots (in visual mode) passed
+    const canComplete = testResult.passed && (!visualMode || screenshotResult.passed);
+
+    if (!canComplete) {
+      // Screenshots not verified yet
+      state.ralph_loop.iteration = iteration;
+      saveSessionState(rootDir, state);
+
+      console.log('');
+      console.log(`${c.cyan}▶ Review unverified screenshots:${c.reset}`);
+      console.log(`${c.dim}  1. View each screenshot in screenshots/ directory${c.reset}`);
+      console.log(`${c.dim}  2. Rename verified files with 'verified-' prefix${c.reset}`);
+      console.log(`${c.dim}  3. Loop will re-verify when you stop${c.reset}`);
+      return;
+    }
     console.log('');
 
     // Mark story complete
@@ -353,10 +458,17 @@ function handleCLI() {
     if (!loop || !loop.enabled) {
       console.log(`${c.dim}Ralph Loop: not active${c.reset}`);
     } else {
-      console.log(`${c.green}Ralph Loop: active${c.reset}`);
+      const modeLabel = loop.visual_mode ? ` ${c.cyan}[VISUAL]${c.reset}` : '';
+      console.log(`${c.green}Ralph Loop: active${c.reset}${modeLabel}`);
       console.log(`  Epic: ${loop.epic}`);
       console.log(`  Current Story: ${loop.current_story}`);
       console.log(`  Iteration: ${loop.iteration || 0}/${loop.max_iterations || 20}`);
+      if (loop.visual_mode) {
+        const verified = loop.screenshots_verified
+          ? `${c.green}yes${c.reset}`
+          : `${c.yellow}no${c.reset}`;
+        console.log(`  Screenshots Verified: ${verified}`);
+      }
     }
     return true;
   }
@@ -386,6 +498,7 @@ function handleCLI() {
   if (args.some(a => a.startsWith('--init'))) {
     const epicArg = args.find(a => a.startsWith('--epic='));
     const maxArg = args.find(a => a.startsWith('--max='));
+    const visualArg = args.includes('--visual') || args.includes('-v');
 
     if (!epicArg) {
       console.log(`${c.red}Error: --epic=EP-XXXX is required${c.reset}`);
@@ -394,6 +507,7 @@ function handleCLI() {
 
     const epicId = epicArg.split('=')[1];
     const maxIterations = maxArg ? parseInt(maxArg.split('=')[1]) : 20;
+    const visualMode = visualArg;
 
     // Find first ready story in epic
     const status = getStatus(rootDir);
@@ -426,6 +540,8 @@ function handleCLI() {
       current_story: storyId,
       iteration: 0,
       max_iterations: maxIterations,
+      visual_mode: visualMode,
+      screenshots_verified: false,
       started_at: new Date().toISOString(),
     };
     saveSessionState(rootDir, state);
@@ -433,11 +549,16 @@ function handleCLI() {
     const progress = getEpicProgress(status, epicId);
 
     console.log('');
-    console.log(`${c.green}${c.bold}Ralph Loop Initialized${c.reset}`);
+    const modeLabel = visualMode ? ` ${c.cyan}[VISUAL MODE]${c.reset}` : '';
+    console.log(`${c.green}${c.bold}Ralph Loop Initialized${c.reset}${modeLabel}`);
     console.log(`${c.dim}${'─'.repeat(40)}${c.reset}`);
     console.log(`  Epic: ${c.cyan}${epicId}${c.reset}`);
     console.log(`  Stories: ${progress.ready} ready, ${progress.total} total`);
     console.log(`  Max Iterations: ${maxIterations}`);
+    if (visualMode) {
+      console.log(`  Visual Mode: ${c.cyan}enabled${c.reset} (screenshot verification)`);
+      console.log(`  Min Iterations: 2 (for confirmation)`);
+    }
     console.log(`${c.dim}${'─'.repeat(40)}${c.reset}`);
     console.log('');
     console.log(`${c.brand}▶ Starting Story:${c.reset} ${storyId}`);
@@ -464,22 +585,37 @@ function handleCLI() {
 ${c.brand}${c.bold}ralph-loop.js${c.reset} - Autonomous Story Processing
 
 ${c.bold}Usage:${c.reset}
-  node scripts/ralph-loop.js                          Run loop check (Stop hook)
-  node scripts/ralph-loop.js --init --epic=EP-XXX     Initialize loop for epic
-  node scripts/ralph-loop.js --status                 Check loop status
-  node scripts/ralph-loop.js --stop                   Stop the loop
-  node scripts/ralph-loop.js --reset                  Reset loop state
+  node scripts/ralph-loop.js                              Run loop check (Stop hook)
+  node scripts/ralph-loop.js --init --epic=EP-XXX         Initialize loop for epic
+  node scripts/ralph-loop.js --init --epic=EP-XXX --visual Initialize with Visual Mode
+  node scripts/ralph-loop.js --status                     Check loop status
+  node scripts/ralph-loop.js --stop                       Stop the loop
+  node scripts/ralph-loop.js --reset                      Reset loop state
 
 ${c.bold}Options:${c.reset}
   --epic=EP-XXXX    Epic ID to process (required for --init)
   --max=N           Max iterations (default: 20)
+  --visual, -v      Enable Visual Mode (screenshot verification)
+
+${c.bold}Visual Mode:${c.reset}
+  When --visual is enabled, the loop also verifies that all screenshots
+  in the screenshots/ directory have been reviewed (verified- prefix).
+
+  This ensures Claude actually looks at UI screenshots before declaring
+  completion. Requires minimum 2 iterations for confirmation.
+
+  Workflow:
+    1. Tests run → must pass
+    2. Screenshots verified → all must have 'verified-' prefix
+    3. Minimum 2 iterations → prevents premature completion
+    4. Only then → story marked complete
 
 ${c.bold}How it works:${c.reset}
-  1. Start loop with /agileflow:babysit EPIC=EP-XXX MODE=loop
+  1. Start loop with /agileflow:babysit EPIC=EP-XXX MODE=loop VISUAL=true
   2. Work on the current story
-  3. When you stop, this hook runs tests
-  4. If tests pass → story marked complete, next story loaded
-  5. If tests fail → failures shown, you continue fixing
+  3. When you stop, this hook runs tests (and screenshot verification in Visual Mode)
+  4. If all pass → story marked complete, next story loaded
+  5. If any fail → failures shown, you continue fixing
   6. Loop repeats until epic done or max iterations
 `);
     return true;