agileflow 2.75.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/design.md

@@ -70,7 +70,7 @@ FIRST ACTION PROTOCOL:
 4. For complete features: Use workflow.md (Plan → Build → Self-Improve)
 5. After work: Run self-improve.md to update expertise
 
-SLASH COMMANDS: /agileflow:context, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:status
+SLASH COMMANDS: /agileflow:context:full, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:status
 <!-- COMPACT_SUMMARY_END -->
 
 You are AG-DESIGN, the Design Specialist for AgileFlow projects.

package/src/core/agents/documentation.md

@@ -76,7 +76,7 @@ DOCUMENTATION PRINCIPLES:
 - Include troubleshooting (users will have problems)
 - Document breaking changes (critical for users)
 
-SLASH COMMANDS: /agileflow:context, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:status
+SLASH COMMANDS: /agileflow:context:full, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:status
 <!-- COMPACT_SUMMARY_END -->
 
 You are AG-DOCUMENTATION, the Documentation Specialist for AgileFlow projects.

package/src/core/agents/integrations.md

@@ -82,7 +82,7 @@ FIRST ACTION PROTOCOL:
 4. For complete features: Use workflow.md (Plan → Build → Self-Improve)
 5. After work: Run self-improve.md to update expertise
 
-SLASH COMMANDS: /agileflow:context, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:tech-debt, /agileflow:status
+SLASH COMMANDS: /agileflow:context:full, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:tech-debt, /agileflow:status
 <!-- COMPACT_SUMMARY_END -->
 
 You are AG-INTEGRATIONS, the Integration Specialist for AgileFlow projects.

package/src/core/agents/mobile.md

@@ -84,7 +84,7 @@ FIRST ACTION PROTOCOL:
 4. For complete features: Use workflow.md (Plan → Build → Self-Improve)
 5. After work: Run self-improve.md to update expertise
 
-SLASH COMMANDS: /agileflow:context, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:tech-debt, /agileflow:status
+SLASH COMMANDS: /agileflow:context:full, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:tech-debt, /agileflow:status
 <!-- COMPACT_SUMMARY_END -->
 
 You are AG-MOBILE, the Mobile Specialist for AgileFlow projects.

package/src/core/agents/monitoring.md

@@ -84,7 +84,7 @@ FIRST ACTION PROTOCOL:
 4. For complete features: Use workflow.md (Plan → Build → Self-Improve)
 5. After work: Run self-improve.md to update expertise
 
-SLASH COMMANDS: /agileflow:context, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:status
+SLASH COMMANDS: /agileflow:context:full, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:status
 <!-- COMPACT_SUMMARY_END -->
 
 You are AG-MONITORING, the Monitoring & Observability Specialist for AgileFlow projects.

package/src/core/agents/performance.md

@@ -91,7 +91,7 @@ FIRST ACTION PROTOCOL:
 
 PLAN MODE REQUIRED: Performance work requires measurement first. Always use EnterPlanMode to profile before optimizing.
 
-SLASH COMMANDS: /agileflow:context, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:tech-debt, /agileflow:impact-analysis, /agileflow:status
+SLASH COMMANDS: /agileflow:context:full, /agileflow:ai-code-review, /agileflow:adr-new, /agileflow:tech-debt, /agileflow:impact-analysis, /agileflow:status
 <!-- COMPACT_SUMMARY_END -->
 
 You are AG-PERFORMANCE, the Performance Specialist for AgileFlow projects.

package/src/core/commands/babysit.md

@@ -1,5 +1,6 @@
 ---
 description: Interactive mentor for end-to-end feature implementation
+argument-hint: "[EPIC=<id>] [MODE=loop] [MAX=<iterations>]"
 compact_context:
   priority: critical
   preserve_rules:
@@ -34,6 +35,78 @@ This gathers: git status, stories/epics, session state, docs structure, research
 
 ---
 
+## LOOP MODE (Autonomous Execution)
+
+When invoked with `MODE=loop`, babysit runs autonomously through an epic's stories:
+
+```
+/agileflow:babysit EPIC=EP-0042 MODE=loop MAX=20
+```
+
+### How Loop Mode Works
+
+1. **Initialization**: Writes loop config to `session-state.json`
+2. **First Story**: Picks first "ready" story, marks it "in_progress"
+3. **Work**: You implement the story normally
+4. **Stop Hook**: When you stop, `ralph-loop.js` runs:
+   - Runs `npm test` (or configured test command)
+   - If tests pass → marks story complete, loads next story
+   - If tests fail → shows failures, you continue fixing
+5. **Loop**: Continues until epic complete or MAX iterations reached
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `EPIC` | Yes | Epic ID to process (e.g., EP-0042) |
+| `MODE` | Yes | Must be `loop` for autonomous mode |
+| `MAX` | No | Max iterations (default: 20) |
+
+### To Start Loop Mode
+
+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
+```
+
+Or manually write to session-state.json:
+
+```json
+{
+  "ralph_loop": {
+    "enabled": true,
+    "epic": "EP-0042",
+    "current_story": "US-0015",
+    "iteration": 0,
+    "max_iterations": 20
+  }
+}
+```
+
+### Loop Control Commands
+
+```bash
+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
+```
+
+### When to Use Loop Mode
+
+**Good for:**
+- Working through a well-defined epic with clear stories
+- Test-driven development (tests define "done")
+- Batch processing multiple stories overnight
+
+**Not good for:**
+- Exploratory work without clear acceptance criteria
+- Stories requiring human review before proceeding
+- Complex multi-domain work needing coordination
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## Compact Summary