agileflow 2.78.0 → 2.79.0

package/scripts/screenshot-verifier.js

@@ -0,0 +1,213 @@
+#!/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