agileflow 2.74.0 → 2.76.0

package/scripts/ralph-loop.js

@@ -0,0 +1,491 @@
+#!/usr/bin/env node
+
+/**
+ * ralph-loop.js - Autonomous Story Processing Loop
+ *
+ * This script is the brain of AgileFlow's autonomous work mode.
+ * 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
+ *
+ * Named after the "Ralph Wiggum" pattern from Anthropic.
+ *
+ * Usage (as Stop hook):
+ *   node scripts/ralph-loop.js
+ *
+ * Manual control:
+ *   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
+ */
+
+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();
+}
+
+// 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 {};
+}
+
+// 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');
+}
+
+// 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: {} };
+}
+
+// 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');
+}
+
+// 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) {}
+
+  // Default to npm test
+  return 'npm test';
+}
+
+// Run tests and return result
+function runTests(rootDir, testCommand) {
+  const result = { passed: false, output: '', duration: 0 };
+  const startTime = Date.now();
+
+  try {
+    const output = execSync(testCommand, {
+      cwd: rootDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 300000, // 5 minute timeout
+    });
+    result.passed = true;
+    result.output = output;
+  } catch (e) {
+    result.passed = false;
+    result.output = e.stdout || '' + '\n' + (e.stderr || '');
+    if (e.message) {
+      result.output += '\n' + e.message;
+    }
+  }
+
+  result.duration = Date.now() - startTime;
+  return result;
+}
+
+// Get next ready story in epic
+function getNextStory(status, epicId, currentStoryId) {
+  const stories = status.stories || {};
+
+  // Get all stories in this epic that are ready
+  const readyStories = Object.entries(stories)
+    .filter(([id, story]) => {
+      return story.epic === epicId &&
+             story.status === 'ready' &&
+             id !== currentStoryId;
+    })
+    .sort((a, b) => {
+      // Sort by story number if possible
+      const numA = parseInt(a[0].replace(/\D/g, '')) || 0;
+      const numB = parseInt(b[0].replace(/\D/g, '')) || 0;
+      return numA - numB;
+    });
+
+  if (readyStories.length > 0) {
+    return { id: readyStories[0][0], ...readyStories[0][1] };
+  }
+  return null;
+}
+
+// Mark story as completed
+function markStoryComplete(rootDir, storyId) {
+  const status = getStatus(rootDir);
+  if (status.stories && status.stories[storyId]) {
+    status.stories[storyId].status = 'completed';
+    status.stories[storyId].completed_at = new Date().toISOString();
+    saveStatus(rootDir, status);
+    return true;
+  }
+  return false;
+}
+
+// Mark story as in_progress
+function markStoryInProgress(rootDir, storyId) {
+  const status = getStatus(rootDir);
+  if (status.stories && status.stories[storyId]) {
+    status.stories[storyId].status = 'in_progress';
+    status.stories[storyId].started_at = new Date().toISOString();
+    saveStatus(rootDir, status);
+    return true;
+  }
+  return false;
+}
+
+// Get story details
+function getStoryDetails(rootDir, storyId) {
+  const status = getStatus(rootDir);
+  if (status.stories && status.stories[storyId]) {
+    return { id: storyId, ...status.stories[storyId] };
+  }
+  return null;
+}
+
+// Count stories in epic by status
+function getEpicProgress(status, epicId) {
+  const stories = status.stories || {};
+  const epicStories = Object.entries(stories).filter(([_, s]) => s.epic === epicId);
+
+  return {
+    total: epicStories.length,
+    completed: epicStories.filter(([_, s]) => s.status === 'completed').length,
+    in_progress: epicStories.filter(([_, s]) => s.status === 'in_progress').length,
+    ready: epicStories.filter(([_, s]) => s.status === 'ready').length,
+    blocked: epicStories.filter(([_, s]) => s.status === 'blocked').length,
+  };
+}
+
+// Main loop logic
+function handleLoop(rootDir) {
+  const state = getSessionState(rootDir);
+  const loop = state.ralph_loop;
+
+  // Check if loop mode is enabled
+  if (!loop || !loop.enabled) {
+    return; // Silent exit - not in loop mode
+  }
+
+  const status = getStatus(rootDir);
+  const iteration = (loop.iteration || 0) + 1;
+  const maxIterations = loop.max_iterations || 20;
+
+  console.log('');
+  console.log(`${c.brand}${c.bold}══════════════════════════════════════════════════════════${c.reset}`);
+  console.log(`${c.brand}${c.bold}  RALPH LOOP - Iteration ${iteration}/${maxIterations}${c.reset}`);
+  console.log(`${c.brand}${c.bold}══════════════════════════════════════════════════════════${c.reset}`);
+  console.log('');
+
+  // Check iteration limit
+  if (iteration > maxIterations) {
+    console.log(`${c.yellow}⚠ Max iterations (${maxIterations}) reached. Stopping loop.${c.reset}`);
+    console.log(`${c.dim}Run /agileflow:babysit MODE=loop to restart${c.reset}`);
+    state.ralph_loop.enabled = false;
+    state.ralph_loop.stopped_reason = 'max_iterations';
+    saveSessionState(rootDir, state);
+    return;
+  }
+
+  // Get current story
+  const currentStoryId = loop.current_story;
+  const currentStory = getStoryDetails(rootDir, currentStoryId);
+  const epicId = loop.epic;
+
+  if (!currentStory) {
+    console.log(`${c.red}✗ Current story ${currentStoryId} not found${c.reset}`);
+    state.ralph_loop.enabled = false;
+    state.ralph_loop.stopped_reason = 'story_not_found';
+    saveSessionState(rootDir, state);
+    return;
+  }
+
+  console.log(`${c.cyan}Current Story:${c.reset} ${currentStoryId} - ${currentStory.title || 'Untitled'}`);
+  console.log('');
+
+  // Run tests
+  const testCommand = getTestCommand(rootDir);
+  console.log(`${c.blue}Running:${c.reset} ${testCommand}`);
+  console.log(`${c.dim}${'─'.repeat(58)}${c.reset}`);
+
+  const testResult = runTests(rootDir, testCommand);
+
+  if (testResult.passed) {
+    console.log(`${c.green}✓ Tests passed${c.reset} (${(testResult.duration / 1000).toFixed(1)}s)`);
+    console.log('');
+
+    // Mark story complete
+    markStoryComplete(rootDir, currentStoryId);
+    console.log(`${c.green}✓ Marked ${currentStoryId} as completed${c.reset}`);
+
+    // Get next story
+    const nextStory = getNextStory(status, epicId, currentStoryId);
+
+    if (nextStory) {
+      // Move to next story
+      markStoryInProgress(rootDir, nextStory.id);
+      state.ralph_loop.current_story = nextStory.id;
+      state.ralph_loop.iteration = iteration;
+      saveSessionState(rootDir, state);
+
+      const progress = getEpicProgress(getStatus(rootDir), epicId);
+      console.log('');
+      console.log(`${c.cyan}━━━ Next Story ━━━${c.reset}`);
+      console.log(`${c.bold}${nextStory.id}:${c.reset} ${nextStory.title || 'Untitled'}`);
+      if (nextStory.acceptance_criteria) {
+        console.log(`${c.dim}Acceptance Criteria:${c.reset}`);
+        const criteria = Array.isArray(nextStory.acceptance_criteria)
+          ? nextStory.acceptance_criteria
+          : [nextStory.acceptance_criteria];
+        criteria.slice(0, 3).forEach(ac => console.log(`  • ${ac}`));
+      }
+      console.log('');
+      console.log(`${c.dim}Epic Progress: ${progress.completed}/${progress.total} stories complete${c.reset}`);
+      console.log('');
+      console.log(`${c.brand}▶ Continue implementing ${nextStory.id}${c.reset}`);
+      console.log(`${c.dim}  Run tests when ready. Loop will validate and continue.${c.reset}`);
+
+    } else {
+      // No more stories - epic complete!
+      const progress = getEpicProgress(getStatus(rootDir), epicId);
+      state.ralph_loop.enabled = false;
+      state.ralph_loop.stopped_reason = 'epic_complete';
+      state.ralph_loop.completed_at = new Date().toISOString();
+      saveSessionState(rootDir, state);
+
+      console.log('');
+      console.log(`${c.green}${c.bold}════════════════════════════════════════════════════════${c.reset}`);
+      console.log(`${c.green}${c.bold}  🎉 EPIC COMPLETE!${c.reset}`);
+      console.log(`${c.green}${c.bold}════════════════════════════════════════════════════════${c.reset}`);
+      console.log('');
+      console.log(`${c.green}Epic ${epicId} finished in ${iteration} iterations${c.reset}`);
+      console.log(`${c.dim}${progress.completed} stories completed${c.reset}`);
+      console.log('');
+    }
+
+  } else {
+    // Tests failed - feed back to Claude
+    console.log(`${c.red}✗ Tests failed${c.reset} (${(testResult.duration / 1000).toFixed(1)}s)`);
+    console.log('');
+
+    state.ralph_loop.iteration = iteration;
+    state.ralph_loop.last_failure = new Date().toISOString();
+    saveSessionState(rootDir, state);
+
+    console.log(`${c.yellow}━━━ Test Failures ━━━${c.reset}`);
+
+    // Show truncated output (last 50 lines most relevant)
+    const outputLines = testResult.output.split('\n');
+    const relevantLines = outputLines.slice(-50);
+    console.log(relevantLines.join('\n'));
+
+    console.log('');
+    console.log(`${c.brand}▶ Fix the failing tests and continue${c.reset}`);
+    console.log(`${c.dim}  Loop will re-run tests when you stop.${c.reset}`);
+    console.log(`${c.dim}  Iteration ${iteration}/${maxIterations}${c.reset}`);
+  }
+
+  console.log('');
+}
+
+// Handle CLI arguments
+function handleCLI() {
+  const args = process.argv.slice(2);
+  const rootDir = getProjectRoot();
+
+  if (args.includes('--status')) {
+    const state = getSessionState(rootDir);
+    const loop = state.ralph_loop;
+
+    if (!loop || !loop.enabled) {
+      console.log(`${c.dim}Ralph Loop: not active${c.reset}`);
+    } else {
+      console.log(`${c.green}Ralph Loop: active${c.reset}`);
+      console.log(`  Epic: ${loop.epic}`);
+      console.log(`  Current Story: ${loop.current_story}`);
+      console.log(`  Iteration: ${loop.iteration || 0}/${loop.max_iterations || 20}`);
+    }
+    return true;
+  }
+
+  if (args.includes('--stop')) {
+    const state = getSessionState(rootDir);
+    if (state.ralph_loop) {
+      state.ralph_loop.enabled = false;
+      state.ralph_loop.stopped_reason = 'manual';
+      saveSessionState(rootDir, state);
+      console.log(`${c.yellow}Ralph Loop stopped${c.reset}`);
+    } else {
+      console.log(`${c.dim}Ralph Loop was not active${c.reset}`);
+    }
+    return true;
+  }
+
+  if (args.includes('--reset')) {
+    const state = getSessionState(rootDir);
+    delete state.ralph_loop;
+    saveSessionState(rootDir, state);
+    console.log(`${c.green}Ralph Loop state reset${c.reset}`);
+    return true;
+  }
+
+  // Handle --init
+  if (args.some(a => a.startsWith('--init'))) {
+    const epicArg = args.find(a => a.startsWith('--epic='));
+    const maxArg = args.find(a => a.startsWith('--max='));
+
+    if (!epicArg) {
+      console.log(`${c.red}Error: --epic=EP-XXXX is required${c.reset}`);
+      return true;
+    }
+
+    const epicId = epicArg.split('=')[1];
+    const maxIterations = maxArg ? parseInt(maxArg.split('=')[1]) : 20;
+
+    // Find first ready story in epic
+    const status = getStatus(rootDir);
+    const stories = status.stories || {};
+    const readyStories = Object.entries(stories)
+      .filter(([_, s]) => s.epic === epicId && s.status === 'ready')
+      .sort((a, b) => {
+        const numA = parseInt(a[0].replace(/\D/g, '')) || 0;
+        const numB = parseInt(b[0].replace(/\D/g, '')) || 0;
+        return numA - numB;
+      });
+
+    if (readyStories.length === 0) {
+      console.log(`${c.yellow}No ready stories found in ${epicId}${c.reset}`);
+      console.log(`${c.dim}Create stories with status "ready" first${c.reset}`);
+      return true;
+    }
+
+    const firstStory = readyStories[0];
+    const storyId = firstStory[0];
+
+    // Mark first story as in_progress
+    markStoryInProgress(rootDir, storyId);
+
+    // Initialize loop state
+    const state = getSessionState(rootDir);
+    state.ralph_loop = {
+      enabled: true,
+      epic: epicId,
+      current_story: storyId,
+      iteration: 0,
+      max_iterations: maxIterations,
+      started_at: new Date().toISOString(),
+    };
+    saveSessionState(rootDir, state);
+
+    const progress = getEpicProgress(status, epicId);
+
+    console.log('');
+    console.log(`${c.green}${c.bold}Ralph Loop Initialized${c.reset}`);
+    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}`);
+    console.log(`${c.dim}${'─'.repeat(40)}${c.reset}`);
+    console.log('');
+    console.log(`${c.brand}▶ Starting Story:${c.reset} ${storyId}`);
+    console.log(`  ${firstStory[1].title || 'Untitled'}`);
+    if (firstStory[1].acceptance_criteria) {
+      const criteria = Array.isArray(firstStory[1].acceptance_criteria)
+        ? firstStory[1].acceptance_criteria
+        : [firstStory[1].acceptance_criteria];
+      console.log(`${c.dim}  Acceptance Criteria:${c.reset}`);
+      criteria.slice(0, 3).forEach(ac => console.log(`    • ${ac}`));
+    }
+    console.log('');
+    console.log(`${c.dim}Work on this story. When you stop, tests will run automatically.${c.reset}`);
+    console.log(`${c.dim}If tests pass, the next story will be loaded.${c.reset}`);
+    console.log('');
+
+    return true;
+  }
+
+  if (args.includes('--help')) {
+    console.log(`
+${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
+
+${c.bold}Options:${c.reset}
+  --epic=EP-XXXX    Epic ID to process (required for --init)
+  --max=N           Max iterations (default: 20)
+
+${c.bold}How it works:${c.reset}
+  1. Start loop with /agileflow:babysit EPIC=EP-XXX MODE=loop
+  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
+  6. Loop repeats until epic done or max iterations
+`);
+    return true;
+  }
+
+  return false;
+}
+
+// Main
+function main() {
+  // Handle CLI commands first
+  if (handleCLI()) {
+    return;
+  }
+
+  // Otherwise run the loop handler
+  const rootDir = getProjectRoot();
+  handleLoop(rootDir);
+}
+
+main();

package/src/core/agents/accessibility.md

@@ -428,7 +428,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research accessibility best practices
+- `/agileflow:research:ask TOPIC=...` → Research accessibility best practices
 - `/agileflow:ai-code-review` → Review code for accessibility issues
 - `/agileflow:adr-new` → Document accessibility decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/adr-writer.md

@@ -43,7 +43,7 @@ node .agileflow/scripts/obtain-context.js adr-writer
 
 **Workflow**:
 1. Load expertise: `packages/cli/src/core/experts/adr-writer/expertise.yaml`
-2. Check docs/10-research/ for existing research (or invoke `/agileflow:context MODE=research`)
+2. Check docs/10-research/ for existing research (or invoke `/agileflow:research:ask`)
 3. Check docs/03-decisions/ for related ADRs
 4. Get next ADR number from docs/03-decisions/README.md (sequential: 0001, 0002, etc.)
 5. Gather decision context and alternatives
@@ -135,13 +135,13 @@ Create an ADR when deciding:
 SLASH COMMANDS (Proactive Use)
 
 **Research**:
-- `/agileflow:context MODE=research TOPIC=...` → Generate research for alternatives before writing ADR
+- `/agileflow:research:ask TOPIC=...` → Generate research for alternatives before writing ADR
 
 RESEARCH INTEGRATION
 
 **Before Writing ADR**:
 1. Check docs/10-research/ for existing research on the decision topic
-2. If research is missing or stale, invoke `/agileflow:context MODE=research TOPIC=...`
+2. If research is missing or stale, invoke `/agileflow:research:ask TOPIC=...`
 3. Research should cover all alternatives with pros/cons, benchmarks, trade-offs
 
 **After User Provides Research**:
@@ -151,7 +151,7 @@ RESEARCH INTEGRATION
 
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before writing:
-   - Check docs/10-research/ for relevant research (or invoke `/agileflow:context MODE=research`)
+   - Check docs/10-research/ for relevant research (or invoke `/agileflow:research:ask`)
    - Check existing ADRs in docs/03-decisions/ for related decisions
    - Check CLAUDE.md for current architecture context
 2. Ask for decision context (what's being decided and why now?)
@@ -268,7 +268,7 @@ This contains your mental model of:
 **Then Output**:
 1. ADR context: "Next ADR: ADR-<NUMBER>, recent decisions: <list of last 3 ADRs>"
 2. If research exists: "Found research: <topic> (docs/10-research/<file>)"
-3. If no research: "No research found. I can invoke `/agileflow:context MODE=research` to gather alternatives."
+3. If no research: "No research found. I can invoke `/agileflow:research:ask` to gather alternatives."
 4. Ask: "What technical decision would you like to document?"
 5. Clarify: "I'll document context, alternatives considered, decision, and consequences."
 
@@ -288,7 +288,7 @@ This updates your expertise with what you learned, so you're faster next time.
 
 **After User Describes Decision**:
 1. Clarify context (why now? what forces?)
-2. Check docs/10-research/ for supporting research (or invoke `/agileflow:context MODE=research`)
+2. Check docs/10-research/ for supporting research (or invoke `/agileflow:research:ask`)
 3. Identify 2-5 alternatives with pros/cons
 4. Propose ADR structure (show preview)
 5. Get approval (YES/NO)

package/src/core/agents/analytics.md

@@ -514,7 +514,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research analytics best practices
+- `/agileflow:research:ask TOPIC=...` → Research analytics best practices
 - `/agileflow:ai-code-review` → Review analytics implementation for data quality
 - `/agileflow:adr-new` → Document analytics decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status