agileflow 2.78.0 → 2.80.0

package/scripts/screenshot-verifier.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+
+/**
+ * screenshot-verifier.js - Verify all screenshots have been reviewed
+ *
+ * Part of Visual Mode for UI development. This script checks that all
+ * screenshots in a directory have been prefixed with "verified-" to
+ * confirm Claude has visually reviewed each one.
+ *
+ * Usage:
+ *   node scripts/screenshot-verifier.js                    # Default: ./screenshots
+ *   node scripts/screenshot-verifier.js --path ./e2e/shots # Custom path
+ *   node scripts/screenshot-verifier.js --help             # Show help
+ *
+ * Exit codes:
+ *   0 - All screenshots verified (or no screenshots found)
+ *   1 - Some screenshots missing verified- prefix
+ *   2 - Error (directory not found, etc.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Shared utilities
+const { c } = require('../lib/colors');
+
+// Parse command line arguments
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    path: './screenshots',
+    help: false,
+    quiet: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--quiet' || arg === '-q') {
+      options.quiet = true;
+    } else if (arg === '--path' || arg === '-p') {
+      if (args[i + 1]) {
+        options.path = args[i + 1];
+        i++;
+      }
+    } else if (!arg.startsWith('-')) {
+      // Positional argument - treat as path
+      options.path = arg;
+    }
+  }
+
+  return options;
+}
+
+// Show help message
+function showHelp() {
+  console.log(`
+${c.brand}${c.bold}screenshot-verifier${c.reset} - Verify all screenshots have been reviewed
+
+${c.bold}USAGE${c.reset}
+  node screenshot-verifier.js [OPTIONS] [PATH]
+
+${c.bold}OPTIONS${c.reset}
+  --path, -p <dir>   Directory containing screenshots (default: ./screenshots)
+  --quiet, -q        Only output on failure
+  --help, -h         Show this help message
+
+${c.bold}EXAMPLES${c.reset}
+  node screenshot-verifier.js                       # Check ./screenshots
+  node screenshot-verifier.js ./tests/e2e/shots     # Check custom path
+  node screenshot-verifier.js --path ./shots -q     # Quiet mode
+
+${c.bold}EXIT CODES${c.reset}
+  0 - All screenshots verified (or no screenshots found)
+  1 - Some screenshots missing 'verified-' prefix
+  2 - Error (directory not found, etc.)
+
+${c.bold}VISUAL MODE${c.reset}
+  This script is part of AgileFlow's Visual Mode for UI development.
+
+  Workflow:
+  1. Playwright tests create screenshots in the target directory
+  2. Claude reviews each screenshot visually
+  3. Claude renames verified screenshots with 'verified-' prefix
+  4. This script confirms all screenshots have been reviewed
+
+  The 'verified-' prefix ensures Claude actually looked at each image
+  rather than declaring completion prematurely.
+`);
+}
+
+// Get all image files in directory
+function getImageFiles(dir) {
+  const imageExtensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
+
+  try {
+    const files = fs.readdirSync(dir);
+    return files.filter(file => {
+      const ext = path.extname(file).toLowerCase();
+      return imageExtensions.includes(ext);
+    });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return null; // Directory doesn't exist
+    }
+    throw err;
+  }
+}
+
+// Main verification logic
+function verifyScreenshots(options) {
+  const dir = path.resolve(options.path);
+
+  // Check if directory exists
+  if (!fs.existsSync(dir)) {
+    if (!options.quiet) {
+      console.log(`${c.yellow}No screenshots directory found at: ${dir}${c.reset}`);
+      console.log(`${c.dim}Create the directory or run tests to generate screenshots.${c.reset}`);
+    }
+    return { success: true, total: 0, verified: 0, unverified: [] };
+  }
+
+  // Get all image files
+  const files = getImageFiles(dir);
+
+  if (files === null) {
+    console.error(`${c.red}Error: Could not read directory: ${dir}${c.reset}`);
+    process.exit(2);
+  }
+
+  if (files.length === 0) {
+    if (!options.quiet) {
+      console.log(`${c.yellow}No screenshots found in: ${dir}${c.reset}`);
+    }
+    return { success: true, total: 0, verified: 0, unverified: [] };
+  }
+
+  // Check each file for verified- prefix
+  const verified = [];
+  const unverified = [];
+
+  for (const file of files) {
+    if (file.startsWith('verified-')) {
+      verified.push(file);
+    } else {
+      unverified.push(file);
+    }
+  }
+
+  return {
+    success: unverified.length === 0,
+    total: files.length,
+    verified: verified.length,
+    unverified,
+  };
+}
+
+// Format result output
+function formatResult(result, options) {
+  if (options.quiet && result.success) {
+    return;
+  }
+
+  console.log('');
+
+  if (result.total === 0) {
+    console.log(`${c.yellow}No screenshots to verify${c.reset}`);
+    return;
+  }
+
+  if (result.success) {
+    console.log(`${c.green}${c.bold}All screenshots verified${c.reset}`);
+    console.log(
+      `${c.dim}${result.verified}/${result.total} screenshots have 'verified-' prefix${c.reset}`
+    );
+  } else {
+    console.log(`${c.red}${c.bold}Unverified screenshots found${c.reset}`);
+    console.log(`${c.dim}${result.verified}/${result.total} verified${c.reset}`);
+    console.log('');
+    console.log(`${c.yellow}Missing 'verified-' prefix:${c.reset}`);
+    for (const file of result.unverified) {
+      console.log(`  ${c.red}- ${file}${c.reset}`);
+    }
+    console.log('');
+    console.log(`${c.cyan}To verify: Review each screenshot visually, then rename:${c.reset}`);
+    console.log(`${c.dim}  mv screenshots/example.png screenshots/verified-example.png${c.reset}`);
+  }
+
+  console.log('');
+}
+
+// Main entry point
+function main() {
+  const options = parseArgs();
+
+  if (options.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const result = verifyScreenshots(options);
+  formatResult(result, options);
+
+  process.exit(result.success ? 0 : 1);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+// Export for testing
+module.exports = { verifyScreenshots, getImageFiles };

package/scripts/session-manager.js

@@ -13,30 +13,10 @@ 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 (has .agileflow or .git)
-function getProjectRoot() {
-  let dir = process.cwd();
-  while (dir !== '/') {
-    if (fs.existsSync(path.join(dir, '.agileflow')) || fs.existsSync(path.join(dir, '.git'))) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-  return process.cwd();
-}
+// Shared utilities
+const { c } = require('../lib/colors');
+const { getProjectRoot } = require('../lib/paths');
+const { safeReadJSON } = require('../lib/errors');
 
 const ROOT = getProjectRoot();
 const SESSIONS_DIR = path.join(ROOT, '.agileflow', 'sessions');
@@ -162,17 +142,16 @@ function getCurrentBranch() {
 
 // Get current story from status.json
 function getCurrentStory() {
-  try {
-    const statusPath = path.join(ROOT, 'docs', '09-agents', 'status.json');
-    if (!fs.existsSync(statusPath)) return null;
+  const statusPath = path.join(ROOT, 'docs', '09-agents', 'status.json');
+  const result = safeReadJSON(statusPath, { defaultValue: null });
 
-    const status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
-    for (const [id, story] of Object.entries(status.stories || {})) {
-      if (story.status === 'in_progress') {
-        return { id, title: story.title };
-      }
+  if (!result.ok || !result.data) return null;
+
+  for (const [id, story] of Object.entries(result.data.stories || {})) {
+    if (story.status === 'in_progress') {
+      return { id, title: story.title };
     }
-  } catch (e) {}
+  }
   return null;
 }
 

package/src/core/agents/configuration-damage-control.md

@@ -0,0 +1,248 @@
+---
+name: configuration-damage-control
+description: Configure AgileFlow damage control to protect against destructive commands
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: haiku
+compact_context:
+  priority: high
+  preserve_rules:
+    - "Use AskUserQuestion for all configuration choices"
+    - "Copy hook scripts to .claude/hooks/damage-control/"
+    - "Create patterns.yaml if not exists, PRESERVE if exists"
+    - "Write PreToolUse hooks to .claude/settings.json"
+    - "Never overwrite existing patterns without confirmation"
+  state_fields:
+    - damage_control_enabled
+    - protection_level
+---
+
+# Configuration: Damage Control
+
+Set up damage control protection to block destructive commands and protect sensitive paths.
+
+---
+
+## What This Does
+
+Damage control protects your codebase from destructive agent commands through PreToolUse hooks:
+
+1. **Bash Command Validation** - Blocks dangerous commands like `rm -rf`, `DROP TABLE`, force pushes
+2. **Path Protection** - Prevents access to sensitive files (`.env`, `~/.ssh/`, etc.)
+3. **Ask Confirmation** - Prompts before risky-but-valid operations
+
+---
+
+## Configuration Steps
+
+### Step 1: Ask User to Enable
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Enable damage control to protect against destructive commands?",
+  "header": "Damage Control",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enable (Recommended)", "description": "Block dangerous commands and protect sensitive paths"},
+    {"label": "Skip", "description": "No damage control (not recommended)"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+If user selects "Skip", exit with message: "Damage control not enabled. Run /agileflow:configure to enable later."
+
+### Step 2: Ask Protection Level
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Choose protection level:",
+  "header": "Protection Level",
+  "multiSelect": false,
+  "options": [
+    {"label": "Standard (Recommended)", "description": "Deterministic pattern matching - fast, no AI calls"},
+    {"label": "Enhanced", "description": "Standard + AI prompt hook for unknown threats (slower)"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 3: Create Hooks Directory
+
+```bash
+mkdir -p .claude/hooks/damage-control
+```
+
+### Step 4: Copy Hook Scripts
+
+Copy the following scripts from AgileFlow installation:
+
+```bash
+# Source: .agileflow/scripts/damage-control/
+# Destination: .claude/hooks/damage-control/
+
+cp .agileflow/scripts/damage-control/bash-tool-damage-control.js .claude/hooks/damage-control/
+cp .agileflow/scripts/damage-control/edit-tool-damage-control.js .claude/hooks/damage-control/
+cp .agileflow/scripts/damage-control/write-tool-damage-control.js .claude/hooks/damage-control/
+```
+
+### Step 5: Create or Preserve patterns.yaml
+
+**If patterns.yaml does NOT exist**, copy the default:
+
+```bash
+cp .agileflow/scripts/damage-control/patterns.yaml .claude/hooks/damage-control/
+```
+
+**If patterns.yaml ALREADY exists**, preserve it (do not overwrite):
+
+```
+patterns.yaml already exists - preserving existing rules.
+To update patterns, edit .claude/hooks/damage-control/patterns.yaml
+```
+
+### Step 6: Update settings.json
+
+Add PreToolUse hooks to `.claude/settings.json`:
+
+**For Standard protection:**
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/damage-control/bash-tool-damage-control.js",
+          "timeout": 5000
+        }]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/damage-control/edit-tool-damage-control.js",
+          "timeout": 5000
+        }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{
+          "type": "command",
+          "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/damage-control/write-tool-damage-control.js",
+          "timeout": 5000
+        }]
+      }
+    ]
+  }
+}
+```
+
+**For Enhanced protection (adds prompt hook):**
+
+Add to the Bash matcher:
+
+```json
+{
+  "matcher": "Bash",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/damage-control/bash-tool-damage-control.js",
+      "timeout": 5000
+    },
+    {
+      "type": "prompt",
+      "prompt": "Evaluate if this bash command is destructive or could cause irreversible damage. Consider: Does it delete files recursively? Does it modify system files? Could it expose secrets? Block if dangerous."
+    }
+  ]
+}
+```
+
+### Step 7: Merge with Existing Hooks
+
+**IMPORTANT**: If PreToolUse hooks already exist in settings.json, MERGE the new hooks with existing ones. Do NOT replace existing hooks.
+
+Check for existing hooks:
+```javascript
+// If settings.hooks.PreToolUse exists, append to it
+// If a matcher (Bash, Edit, Write) already exists, merge hooks array
+```
+
+### Step 8: Show Completion Summary
+
+```
+Damage Control Enabled
+
+Protection level: Standard (or Enhanced)
+
+Protected against:
+- Destructive bash commands (rm -rf, DROP TABLE, etc.)
+- Access to sensitive paths (~/.ssh, .env, etc.)
+- Force pushes and hard resets
+
+Configuration:
+- Hook scripts: .claude/hooks/damage-control/
+- Patterns file: .claude/hooks/damage-control/patterns.yaml
+- Settings: .claude/settings.json
+
+To customize blocked patterns, edit:
+  .claude/hooks/damage-control/patterns.yaml
+
+Restart Claude Code for hooks to take effect.
+```
+
+---
+
+## Patterns.yaml Reference
+
+```yaml
+# Block dangerous bash commands
+bashToolPatterns:
+  - pattern: '\brm\s+-[rRf]'
+    reason: "rm with recursive or force flags"
+
+# Commands requiring confirmation
+askPatterns:
+  - pattern: 'git\s+push\s+.*--force'
+    reason: "Force push overwrites history"
+
+# Path protection levels
+zeroAccessPaths:   # Cannot read, write, edit, delete
+  - ~/.ssh/
+  - .env
+
+readOnlyPaths:     # Can read, cannot modify
+  - /etc/
+  - package-lock.json
+
+noDeletePaths:     # Can modify, cannot delete
+  - .agileflow/
+  - .claude/
+```
+
+---
+
+## Troubleshooting
+
+**Hooks not working after enabling:**
+- Restart Claude Code - hooks only load on startup
+
+**Command blocked that should be allowed:**
+- Edit patterns.yaml to remove or adjust the pattern
+- Use `ask: true` instead of blocking
+
+**Need to disable damage control:**
+- Remove PreToolUse hooks from .claude/settings.json
+- Or delete .claude/hooks/damage-control/ directory
+
+---
+
+## Related
+
+- Research: `docs/10-research/20260106-claude-code-damage-control-hooks.md`
+- Patterns file: `.claude/hooks/damage-control/patterns.yaml`
+- Hook scripts: `.claude/hooks/damage-control/*.js`

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

package/src/core/commands/configure.md

@@ -10,7 +10,7 @@ compact_context:
     - "CRITICAL: If 🔄 OUTDATED shown → offer --upgrade to re-deploy latest scripts"
     - "MUST backup created on migrate: .claude/settings.json.backup"
     - "MUST show RED RESTART banner after ANY changes (quit, wait 5s, restart)"
-    - "Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, autoupdate"
+    - "Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, autoupdate, askuserquestion"
     - "Stop hooks (ralphloop, selfimprove) run when Claude completes or pauses"
   state_fields:
     - detection_status
@@ -52,7 +52,7 @@ node .agileflow/scripts/agileflow-configure.js --repair=statusline  # Fix specif
 
 ### Features
 
-`sessionstart`, `precompact`, `ralphloop`, `selfimprove`, `archival`, `statusline`, `autoupdate`
+`sessionstart`, `precompact`, `ralphloop`, `selfimprove`, `archival`, `statusline`, `autoupdate`, `askuserquestion`
 
 **Stop hooks** (ralphloop, selfimprove) run when Claude completes or pauses work.
 
@@ -180,12 +180,12 @@ node .agileflow/scripts/agileflow-configure.js --enable=archival --archival-days
 
 ## Profile Details
 
-| Profile | SessionStart | PreCompact | RalphLoop | SelfImprove | Archival | StatusLine |
-|---------|-------------|------------|-----------|-------------|----------|------------|
-| `full` | ✅ | ✅ | ✅ | ✅ | ✅ 30 days | ✅ |
-| `basic` | ✅ | ✅ | ❌ | ❌ | ✅ 30 days | ❌ |
-| `minimal` | ✅ | ❌ | ❌ | ❌ | ✅ 30 days | ❌ |
-| `none` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Profile | SessionStart | PreCompact | RalphLoop | SelfImprove | Archival | StatusLine | AskUserQuestion |
+|---------|-------------|------------|-----------|-------------|----------|------------|-----------------|
+| `full` | ✅ | ✅ | ✅ | ✅ | ✅ 30 days | ✅ | ✅ |
+| `basic` | ✅ | ✅ | ❌ | ❌ | ✅ 30 days | ❌ | ✅ |
+| `minimal` | ✅ | ❌ | ❌ | ❌ | ✅ 30 days | ❌ | ❌ |
+| `none` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
 
 ## Interactive Mode (via /configure command)
 
@@ -226,7 +226,8 @@ Based on selection, run appropriate command.
     {"label": "SelfImprove (Stop Hook)", "description": "Auto-update agent expertise from work"},
     {"label": "Archival", "description": "Auto-archive old completed stories"},
     {"label": "Status Line", "description": "Custom status bar"},
-    {"label": "Auto-Update", "description": "Automatically update AgileFlow on session start"}
+    {"label": "Auto-Update", "description": "Automatically update AgileFlow on session start"},
+    {"label": "AskUserQuestion Mode", "description": "End all responses with AskUserQuestion tool for guided interaction"}
   ]
 }]</parameter>
 </invoke>
@@ -240,6 +241,7 @@ Map selections:
 - "Archival" → `archival`
 - "Status Line" → `statusline`
 - "Auto-Update" → `autoupdate`
+- "AskUserQuestion Mode" → `askuserquestion`
 
 ## Auto-Update Configuration
 
@@ -263,6 +265,41 @@ node .agileflow/scripts/agileflow-configure.js --enable=autoupdate
 
 **Check frequencies:** `hourly`, `daily`, `weekly`, `never`
 
+## AskUserQuestion Mode
+
+Enable AskUserQuestion to have all commands end with guided options:
+
+```bash
+# Enable AskUserQuestion mode
+node .agileflow/scripts/agileflow-configure.js --enable=askuserquestion
+
+# Disable AskUserQuestion mode
+node .agileflow/scripts/agileflow-configure.js --disable=askuserquestion
+```
+
+**What it does:**
+- When enabled: All commands end with AskUserQuestion tool call (guided options)
+- When disabled: Commands can end with natural text questions
+
+**Storage in metadata:**
+```json
+{
+  "features": {
+    "askUserQuestion": {
+      "enabled": true,
+      "mode": "all"
+    }
+  }
+}
+```
+
+**Modes:**
+- `all`: All commands use AskUserQuestion (default)
+- `interactive`: Only interactive commands (babysit, mentor, configure, epic-planner)
+- `none`: Disabled
+
+The guidance is injected via `obtain-context.js` when commands run.
+
 ## Stop Hook Features
 
 Stop hooks run when Claude completes a task or pauses for user input. These enable autonomous workflows.