specsmd 0.0.0-dev.55 → 0.0.0-dev.57

package/flows/fire/agents/builder/skills/run-execute/SKILL.md

@@ -1,6 +1,7 @@
 # Skill: Run Execute
 
-Execute a work item based on its assigned mode (autopilot, confirm, validate).
+Execute work items based on their assigned mode (autopilot, confirm, validate).
+Supports both single-item and multi-item (batch/wide) runs.
 
 ---
 
@@ -33,6 +34,7 @@ Before executing scripts, ensure required dependencies are installed:
 
 - Pending work item ready for execution
 - Resumed from interrupted run
+- Batch of work items passed from run-plan
 
 ---
 
@@ -45,26 +47,82 @@ Before executing scripts, ensure required dependencies are installed:
 
 ---
 
+## Critical Requirements
+
+### MUST Use Scripts - Never Bypass
+
+**CRITICAL**: You MUST call the scripts. DO NOT use mkdir or manual file creation.
+
+| Action | CORRECT | WRONG |
+|--------|---------|-------|
+| Initialize run | `node scripts/init-run.js ...` | `mkdir .specs-fire/runs/run-001` |
+| Complete item | `node scripts/complete-run.js ... --complete-item` | Manual state editing |
+| Complete run | `node scripts/complete-run.js ... --complete-run` | Manual state editing |
+
+The scripts:
+- Create run folder AND run.md together
+- Update state.yaml atomically
+- Track run history in runs.completed
+- Handle batch run state transitions
+
+### Batch Run Execution Flow
+
+For runs with multiple work items:
+
+```
+1. Call init-run.js ONCE at start (creates run.md with ALL items)
+2. Execute each work item sequentially:
+   - Load item context
+   - Execute based on mode (autopilot/confirm/validate)
+   - Call complete-run.js --complete-item after each
+3. Call complete-run.js --complete-run after final item
+```
+
+---
+
 ## Workflow
 
 ```xml
 <skill name="run-execute">
 
   <mandate>
+    USE SCRIPTS — Never bypass init-run.js or complete-run.js.
     TRACK ALL FILE OPERATIONS — Every create, modify must be recorded.
     NEVER skip tests — Tests are mandatory, not optional.
     FOLLOW BROWNFIELD RULES — Read before write, match existing patterns.
   </mandate>
 
   <step n="1" title="Initialize Run">
-    <action script="scripts/init-run.js">Create run record</action>
-    <action>Generate run ID: run-{NNN}</action>
-    <action>Create folder: .specs-fire/runs/{run-id}/</action>
-    <action>Set active_run in state.yaml</action>
+    <critical>
+      MUST call init-run.js script. DO NOT use mkdir directly.
+      The script creates BOTH the folder AND run.md file.
+    </critical>
+
+    <action>Prepare work items JSON array:</action>
+    <code>
+      # For single item:
+      node scripts/init-run.js {rootPath} {workItemId} {intentId} {mode}
+
+      # For batch/wide (multiple items):
+      node scripts/init-run.js {rootPath} --batch '[
+        {"id": "item-1", "intent": "intent-1", "mode": "autopilot"},
+        {"id": "item-2", "intent": "intent-1", "mode": "confirm"}
+      ]' --scope=batch
+    </code>
+
+    <action>Parse script output for runId and runPath</action>
+    <action>Verify run.md was created in .specs-fire/runs/{run-id}/</action>
+
+    <check if="run.md not found">
+      <error>init-run.js failed to create run.md. Check script output.</error>
+    </check>
   </step>
 
-  <step n="2" title="Load Context">
-    <action>Read work item from .specs-fire/intents/{intent}/work-items/{id}.md</action>
+  <step n="2" title="Execute Work Items Loop">
+    <note>For batch runs, repeat steps 2-6 for each work item</note>
+
+    <action>Get current_item from state.yaml active_run</action>
+    <action>Load work item from .specs-fire/intents/{intent}/work-items/{id}.md</action>
     <action>Read intent brief for broader context</action>
     <action>Load ALL project standards:</action>
     <substep>.specs-fire/standards/tech-stack.md — Technology choices</substep>
@@ -183,15 +241,36 @@ Before executing scripts, ensure required dependencies are installed:
     </check>
 
     <action>Validate acceptance criteria from work item</action>
-    <action>Measure coverage against target from testing-standards.md</action>
-    <action>Generate test report using template: templates/test-report.md.hbs</action>
-    <action>Save to: .specs-fire/runs/{run-id}/test-report.md</action>
   </step>
 
-  <step n="7" title="Complete Run">
-    <action script="scripts/complete-run.js">Finalize run record</action>
-    <action>Update state.yaml (clear active_run, mark work item complete)</action>
-    <action>Generate run log: .specs-fire/runs/{run-id}/run.md</action>
+  <step n="7" title="Complete Current Work Item">
+    <critical>
+      MUST call complete-run.js script. Check if more items remain.
+    </critical>
+
+    <check if="batch run with more items pending">
+      <action>Call complete-run.js with --complete-item flag:</action>
+      <code>
+        node scripts/complete-run.js {rootPath} {runId} --complete-item
+      </code>
+      <action>Parse output for nextItem</action>
+      <output>
+        Work item {current_item} complete.
+        Next: {nextItem}
+      </output>
+      <goto step="2">Continue with next work item</goto>
+    </check>
+
+    <check if="last item or single item run">
+      <action>Call complete-run.js with --complete-run flag:</action>
+      <code>
+        node scripts/complete-run.js {rootPath} {runId} --complete-run \
+          --files-created='[{"path":"...","purpose":"..."}]' \
+          --files-modified='[{"path":"...","changes":"..."}]' \
+          --tests=5 --coverage=85
+      </code>
+      <goto step="8"/>
+    </check>
   </step>
 
   <step n="8" title="Generate Walkthrough">
@@ -200,18 +279,16 @@ Before executing scripts, ensure required dependencies are installed:
 
   <step n="9" title="Report Completion">
     <output>
-      Run {run-id} completed for "{title}".
+      Run {run-id} completed.
 
+      Work items completed: {count}
       Files created: {count}
       Files modified: {count}
       Tests added: {count}
-      Coverage: {percentage}%
 
       Artifacts:
-      - Test Report: .specs-fire/runs/{run-id}/test-report.md
+      - Run Log: .specs-fire/runs/{run-id}/run.md
       - Walkthrough: .specs-fire/runs/{run-id}/walkthrough.md
-
-      Continue to next work item? [Y/n]
     </output>
   </step>
 
@@ -222,10 +299,71 @@ Before executing scripts, ensure required dependencies are installed:
 
 ## Scripts
 
-| Script | Purpose |
-|--------|---------|
-| `scripts/init-run.js` | Initialize run record and folder |
-| `scripts/complete-run.js` | Finalize run and update state |
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/init-run.js` | Initialize run record and folder | Creates run.md with all work items |
+| `scripts/complete-run.js` | Finalize run and update state | `--complete-item` or `--complete-run` |
+
+### init-run.js Usage
+
+```bash
+# Single work item
+node scripts/init-run.js /project work-item-id intent-id autopilot
+
+# Batch/wide (multiple items)
+node scripts/init-run.js /project --batch '[
+  {"id": "wi-1", "intent": "int-1", "mode": "autopilot"},
+  {"id": "wi-2", "intent": "int-1", "mode": "confirm"}
+]' --scope=batch
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "runId": "run-001",
+  "runPath": "/project/.specs-fire/runs/run-001",
+  "scope": "batch",
+  "workItems": [...],
+  "currentItem": "wi-1"
+}
+```
+
+### complete-run.js Usage
+
+```bash
+# Complete current item (batch runs - moves to next item)
+node scripts/complete-run.js /project run-001 --complete-item
+
+# Complete entire run (single runs or final item in batch)
+node scripts/complete-run.js /project run-001 --complete-run \
+  --files-created='[{"path":"src/new.ts","purpose":"New feature"}]' \
+  --files-modified='[{"path":"src/old.ts","changes":"Added import"}]' \
+  --tests=5 --coverage=85
+```
+
+**--complete-item Output:**
+```json
+{
+  "success": true,
+  "runId": "run-001",
+  "completedItem": "wi-1",
+  "nextItem": "wi-2",
+  "remainingItems": 1,
+  "allItemsCompleted": false
+}
+```
+
+**--complete-run Output:**
+```json
+{
+  "success": true,
+  "runId": "run-001",
+  "scope": "batch",
+  "workItemsCompleted": 2,
+  "completedAt": "2026-01-20T..."
+}
+```
 
 ---
 
@@ -244,3 +382,23 @@ decisions:
   - decision: Use JWT for tokens
     rationale: Stateless, works with load balancer
 ```
+
+---
+
+## Run Folder Structure
+
+After init-run.js creates a run:
+
+```
+.specs-fire/runs/run-001/
+├── run.md          # Created by init-run.js, updated by complete-run.js
+├── plan.md         # Created during confirm/validate mode (optional)
+└── walkthrough.md  # Created by walkthrough-generate skill
+```
+
+The run.md contains:
+- All work items with their statuses
+- Current item being executed
+- Files created/modified (after completion)
+- Decisions made (after completion)
+- Summary (after completion)

package/flows/fire/agents/builder/skills/run-execute/scripts/complete-run.js

@@ -3,15 +3,24 @@
 /**
  * FIRE Run Completion Script
  *
- * Finalizes a run by:
- * 1. Recording the completed run in state.yaml runs.completed history
- * 2. Updating work item status to completed
- * 3. Clearing active_run
- * 4. Updating run.md with completion data
+ * Supports both single and batch/wide runs.
  *
- * Usage: node complete-run.js <rootPath> <runId> [--files-created=JSON] [--files-modified=JSON] [--decisions=JSON] [--tests=N] [--coverage=N]
+ * For single runs: Completes the run and clears active_run.
+ * For batch/wide runs:
+ *   - --complete-item: Marks current work item done, moves to next
+ *   - --complete-run: Marks all items done and finalizes entire run
  *
- * Example: node complete-run.js /project run-003 --tests=5 --coverage=85
+ * Usage:
+ *   Complete current item:  node complete-run.js <rootPath> <runId> --complete-item [options]
+ *   Complete entire run:    node complete-run.js <rootPath> <runId> --complete-run [options]
+ *   Complete (single/auto): node complete-run.js <rootPath> <runId> [options]
+ *
+ * Options:
+ *   --files-created=JSON   - JSON array of {path, purpose}
+ *   --files-modified=JSON  - JSON array of {path, changes}
+ *   --decisions=JSON       - JSON array of {decision, choice, rationale}
+ *   --tests=N              - Number of tests added
+ *   --coverage=N           - Coverage percentage
  */
 
 const fs = require('fs');
@@ -131,7 +140,7 @@ function writeState(statePath, state) {
 // Run Log Operations
 // =============================================================================
 
-function updateRunLog(runLogPath, params, completedTime) {
+function updateRunLog(runLogPath, activeRun, params, completedTime, isFullCompletion) {
   let content;
   try {
     content = fs.readFileSync(runLogPath, 'utf8');
@@ -143,40 +152,72 @@ function updateRunLog(runLogPath, params, completedTime) {
     );
   }
 
-  // Update status
-  content = content.replace(/status: in_progress/, 'status: completed');
-  content = content.replace(/completed: null/, `completed: ${completedTime}`);
+  // If full completion, update run status
+  if (isFullCompletion) {
+    content = content.replace(/status: in_progress/, 'status: completed');
+    content = content.replace(/completed: null/, `completed: ${completedTime}`);
+  }
+
+  // Update work items status in frontmatter
+  if (activeRun.work_items && Array.isArray(activeRun.work_items)) {
+    for (const item of activeRun.work_items) {
+      // Update status in YAML frontmatter
+      const statusPattern = new RegExp(`(id: ${item.id}\\n\\s+intent: [^\\n]+\\n\\s+mode: [^\\n]+\\n\\s+status: )(\\w+)`);
+      content = content.replace(statusPattern, `$1${item.status}`);
+
+      // Update status in markdown body
+      const bodyPattern = new RegExp(`(\\*\\*${item.id}\\*\\* \\([^)]+\\) — )(\\w+)`);
+      content = content.replace(bodyPattern, `$1${item.status}`);
+    }
+
+    // Update current_item in frontmatter
+    content = content.replace(/current_item: [^\n]+/, `current_item: ${activeRun.current_item || 'none'}`);
+
+    // Update Current Item section
+    if (activeRun.current_item) {
+      const currentItem = activeRun.work_items.find(i => i.id === activeRun.current_item);
+      if (currentItem) {
+        content = content.replace(/## Current Item\n[^\n]+/, `## Current Item\n${currentItem.id} (${currentItem.mode})`);
+      }
+    } else {
+      content = content.replace(/## Current Item\n[^\n]+/, `## Current Item\n(all completed)`);
+    }
+  }
 
-  // Format file lists
-  const filesCreatedText = params.filesCreated.length > 0
-    ? params.filesCreated.map(f => `- \`${f.path}\`: ${f.purpose || '(no purpose)'}`).join('\n')
-    : '(none)';
+  // Format file lists (only on full completion)
+  if (isFullCompletion) {
+    const filesCreatedText = params.filesCreated.length > 0
+      ? params.filesCreated.map(f => `- \`${f.path}\`: ${f.purpose || '(no purpose)'}`).join('\n')
+      : '(none)';
 
-  const filesModifiedText = params.filesModified.length > 0
-    ? params.filesModified.map(f => `- \`${f.path}\`: ${f.changes || '(no changes)'}`).join('\n')
-    : '(none)';
+    const filesModifiedText = params.filesModified.length > 0
+      ? params.filesModified.map(f => `- \`${f.path}\`: ${f.changes || '(no changes)'}`).join('\n')
+      : '(none)';
 
-  const decisionsText = params.decisions.length > 0
-    ? params.decisions.map(d => `- **${d.decision}**: ${d.choice} (${d.rationale || 'no rationale'})`).join('\n')
-    : '(none)';
+    const decisionsText = params.decisions.length > 0
+      ? params.decisions.map(d => `- **${d.decision}**: ${d.choice} (${d.rationale || 'no rationale'})`).join('\n')
+      : '(none)';
 
-  // Replace placeholder sections
-  content = content.replace('## Files Created\n(none yet)', `## Files Created\n${filesCreatedText}`);
-  content = content.replace('## Files Modified\n(none yet)', `## Files Modified\n${filesModifiedText}`);
-  content = content.replace('## Decisions\n(none yet)', `## Decisions\n${decisionsText}`);
+    // Replace placeholder sections
+    content = content.replace('## Files Created\n(none yet)', `## Files Created\n${filesCreatedText}`);
+    content = content.replace('## Files Modified\n(none yet)', `## Files Modified\n${filesModifiedText}`);
+    content = content.replace('## Decisions\n(none yet)', `## Decisions\n${decisionsText}`);
 
-  // Add summary if not present
-  if (!content.includes('## Summary')) {
-    content += `
+    // Add summary if not present
+    if (!content.includes('## Summary')) {
+      const itemCount = activeRun.work_items ? activeRun.work_items.length : 1;
+      content += `
 
 ## Summary
 
+- Work items completed: ${itemCount}
 - Files created: ${params.filesCreated.length}
 - Files modified: ${params.filesModified.length}
 - Tests added: ${params.testsAdded}
 - Coverage: ${params.coverage}%
 - Completed: ${completedTime}
 `;
+    }
   }
 
   try {
@@ -191,11 +232,10 @@ function updateRunLog(runLogPath, params, completedTime) {
 }
 
 // =============================================================================
-// Main Function
+// Complete Current Item (for batch runs)
 // =============================================================================
 
-function completeRun(rootPath, runId, params = {}) {
-  // Defaults for optional params
+function completeCurrentItem(rootPath, runId, params = {}) {
   const completionParams = {
     filesCreated: params.filesCreated || [],
     filesModified: params.filesModified || [],
@@ -204,16 +244,97 @@ function completeRun(rootPath, runId, params = {}) {
     coverage: params.coverage || 0,
   };
 
-  // Validate inputs
   validateInputs(rootPath, runId);
-
-  // Validate FIRE project structure
   const { statePath, runLogPath } = validateFireProject(rootPath, runId);
+  const state = readState(statePath);
+
+  if (!state.active_run) {
+    throw fireError(
+      'No active run found in state.yaml.',
+      'COMPLETE_040',
+      'The run may have already been completed or was never started.'
+    );
+  }
+
+  if (state.active_run.id !== runId) {
+    throw fireError(
+      `Run ID mismatch. Active run is "${state.active_run.id}" but trying to complete "${runId}".`,
+      'COMPLETE_041',
+      `Complete the active run "${state.active_run.id}" first.`
+    );
+  }
+
+  const completedTime = new Date().toISOString();
+  const workItems = state.active_run.work_items || [];
+  const currentItemId = state.active_run.current_item;
+
+  // Find and mark current item as completed
+  let currentItemIndex = -1;
+  for (let i = 0; i < workItems.length; i++) {
+    if (workItems[i].id === currentItemId) {
+      workItems[i].status = 'completed';
+      workItems[i].completed_at = completedTime;
+      currentItemIndex = i;
+      break;
+    }
+  }
+
+  if (currentItemIndex === -1) {
+    throw fireError(
+      `Current item "${currentItemId}" not found in work items.`,
+      'COMPLETE_050',
+      'The run state may be corrupted.'
+    );
+  }
 
-  // Read state
+  // Find next pending item
+  let nextItem = null;
+  for (let i = currentItemIndex + 1; i < workItems.length; i++) {
+    if (workItems[i].status === 'pending') {
+      workItems[i].status = 'in_progress';
+      nextItem = workItems[i];
+      break;
+    }
+  }
+
+  // Update state
+  state.active_run.work_items = workItems;
+  state.active_run.current_item = nextItem ? nextItem.id : null;
+
+  // Update run log
+  updateRunLog(runLogPath, state.active_run, completionParams, completedTime, false);
+
+  // Save state
+  writeState(statePath, state);
+
+  return {
+    success: true,
+    runId: runId,
+    completedItem: currentItemId,
+    nextItem: nextItem ? nextItem.id : null,
+    remainingItems: workItems.filter(i => i.status === 'pending').length,
+    allItemsCompleted: nextItem === null,
+    completedAt: completedTime,
+  };
+}
+
+// =============================================================================
+// Complete Entire Run
+// =============================================================================
+
+function completeRun(rootPath, runId, params = {}) {
+  const completionParams = {
+    filesCreated: params.filesCreated || [],
+    filesModified: params.filesModified || [],
+    decisions: params.decisions || [],
+    testsAdded: params.testsAdded || 0,
+    coverage: params.coverage || 0,
+  };
+
+  validateInputs(rootPath, runId);
+  const { statePath, runLogPath } = validateFireProject(rootPath, runId);
   const state = readState(statePath);
 
-  // Validate active run matches
   if (!state.active_run) {
     throw fireError(
       'No active run found in state.yaml.',
@@ -230,19 +351,33 @@ function completeRun(rootPath, runId, params = {}) {
     );
   }
 
-  // Extract work item and intent from active run
-  const workItemId = state.active_run.work_item;
-  const intentId = state.active_run.intent;
   const completedTime = new Date().toISOString();
+  const workItems = state.active_run.work_items || [];
+  const scope = state.active_run.scope || 'single';
+
+  // Mark all items as completed
+  for (const item of workItems) {
+    if (item.status !== 'completed') {
+      item.status = 'completed';
+      item.completed_at = completedTime;
+    }
+  }
+
+  state.active_run.work_items = workItems;
+  state.active_run.current_item = null;
 
   // Update run log
-  updateRunLog(runLogPath, completionParams, completedTime);
+  updateRunLog(runLogPath, state.active_run, completionParams, completedTime, true);
 
   // Build completed run record
   const completedRun = {
     id: runId,
-    work_item: workItemId,
-    intent: intentId,
+    scope: scope,
+    work_items: workItems.map(i => ({
+      id: i.id,
+      intent: i.intent,
+      mode: i.mode,
+    })),
     completed: completedTime,
   };
 
@@ -255,16 +390,17 @@ function completeRun(rootPath, runId, params = {}) {
 
   // Update work item status in intents
   if (Array.isArray(state.intents)) {
-    for (const intent of state.intents) {
-      if (intent.id === intentId && Array.isArray(intent.work_items)) {
-        for (const workItem of intent.work_items) {
-          if (workItem.id === workItemId) {
-            workItem.status = 'completed';
-            workItem.run_id = runId;
-            break;
+    for (const workItem of workItems) {
+      for (const intent of state.intents) {
+        if (intent.id === workItem.intent && Array.isArray(intent.work_items)) {
+          for (const wi of intent.work_items) {
+            if (wi.id === workItem.id) {
+              wi.status = 'completed';
+              wi.run_id = runId;
+              break;
+            }
           }
         }
-        break;
       }
     }
   }
@@ -278,12 +414,11 @@ function completeRun(rootPath, runId, params = {}) {
   // Save state
   writeState(statePath, state);
 
-  // Return result
   return {
     success: true,
     runId: runId,
-    workItemId: workItemId,
-    intentId: intentId,
+    scope: scope,
+    workItemsCompleted: workItems.length,
     completedAt: completedTime,
     filesCreated: completionParams.filesCreated.length,
     filesModified: completionParams.filesModified.length,
@@ -300,6 +435,8 @@ function parseArgs(args) {
   const result = {
     rootPath: args[0],
     runId: args[1],
+    completeItem: false,
+    completeRunFlag: false,
     filesCreated: [],
     filesModified: [],
     decisions: [],
@@ -309,7 +446,11 @@ function parseArgs(args) {
 
   for (let i = 2; i < args.length; i++) {
     const arg = args[i];
-    if (arg.startsWith('--files-created=')) {
+    if (arg === '--complete-item') {
+      result.completeItem = true;
+    } else if (arg === '--complete-run') {
+      result.completeRunFlag = true;
+    } else if (arg.startsWith('--files-created=')) {
       try {
         result.filesCreated = JSON.parse(arg.substring('--files-created='.length));
       } catch (e) {
@@ -337,6 +478,32 @@ function parseArgs(args) {
   return result;
 }
 
+function printUsage() {
+  console.error('Usage:');
+  console.error('  Complete current item: node complete-run.js <rootPath> <runId> --complete-item [options]');
+  console.error('  Complete entire run:   node complete-run.js <rootPath> <runId> --complete-run [options]');
+  console.error('  Auto (single runs):    node complete-run.js <rootPath> <runId> [options]');
+  console.error('');
+  console.error('Arguments:');
+  console.error('  rootPath  - Project root directory');
+  console.error('  runId     - Run ID to complete (e.g., run-003)');
+  console.error('');
+  console.error('Flags:');
+  console.error('  --complete-item  - Complete only the current work item (batch/wide runs)');
+  console.error('  --complete-run   - Complete the entire run');
+  console.error('');
+  console.error('Options:');
+  console.error('  --files-created=JSON   - JSON array of {path, purpose}');
+  console.error('  --files-modified=JSON  - JSON array of {path, changes}');
+  console.error('  --decisions=JSON       - JSON array of {decision, choice, rationale}');
+  console.error('  --tests=N              - Number of tests added');
+  console.error('  --coverage=N           - Coverage percentage');
+  console.error('');
+  console.error('Examples:');
+  console.error('  node complete-run.js /project run-003 --complete-item');
+  console.error('  node complete-run.js /project run-003 --complete-run --tests=5 --coverage=85');
+}
+
 // =============================================================================
 // CLI Interface
 // =============================================================================
@@ -345,34 +512,32 @@ if (require.main === module) {
   const args = process.argv.slice(2);
 
   if (args.length < 2) {
-    console.error('Usage: node complete-run.js <rootPath> <runId> [options]');
-    console.error('');
-    console.error('Arguments:');
-    console.error('  rootPath  - Project root directory');
-    console.error('  runId     - Run ID to complete (e.g., run-003)');
-    console.error('');
-    console.error('Options:');
-    console.error('  --files-created=JSON   - JSON array of {path, purpose}');
-    console.error('  --files-modified=JSON  - JSON array of {path, changes}');
-    console.error('  --decisions=JSON       - JSON array of {decision, choice, rationale}');
-    console.error('  --tests=N              - Number of tests added');
-    console.error('  --coverage=N           - Coverage percentage');
-    console.error('');
-    console.error('Example:');
-    console.error('  node complete-run.js /my/project run-003 --tests=5 --coverage=85');
+    printUsage();
     process.exit(1);
   }
 
   const params = parseArgs(args);
 
   try {
-    const result = completeRun(params.rootPath, params.runId, {
-      filesCreated: params.filesCreated,
-      filesModified: params.filesModified,
-      decisions: params.decisions,
-      testsAdded: params.testsAdded,
-      coverage: params.coverage,
-    });
+    let result;
+    if (params.completeItem) {
+      result = completeCurrentItem(params.rootPath, params.runId, {
+        filesCreated: params.filesCreated,
+        filesModified: params.filesModified,
+        decisions: params.decisions,
+        testsAdded: params.testsAdded,
+        coverage: params.coverage,
+      });
+    } else {
+      // Default: complete entire run
+      result = completeRun(params.rootPath, params.runId, {
+        filesCreated: params.filesCreated,
+        filesModified: params.filesModified,
+        decisions: params.decisions,
+        testsAdded: params.testsAdded,
+        coverage: params.coverage,
+      });
+    }
     console.log(JSON.stringify(result, null, 2));
     process.exit(0);
   } catch (err) {
@@ -381,4 +546,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { completeRun };
+module.exports = { completeRun, completeCurrentItem };

package/flows/fire/agents/builder/skills/run-execute/scripts/init-run.js

@@ -4,13 +4,19 @@
  * FIRE Run Initialization Script
  *
  * Creates run record in state.yaml and run folder structure.
+ * Supports both single work item and batch/wide runs with multiple items.
+ *
  * Ensures deterministic run ID generation by checking BOTH:
  * - runs.completed history in state.yaml
  * - existing run folders in .specs-fire/runs/
  *
- * Usage: node init-run.js <rootPath> <workItemId> <intentId> <mode>
+ * Usage:
+ *   Single item: node init-run.js <rootPath> <workItemId> <intentId> <mode>
+ *   Batch/Wide:  node init-run.js <rootPath> --batch '<workItemsJson>'
  *
- * Example: node init-run.js /project login-endpoint user-auth confirm
+ * Examples:
+ *   node init-run.js /project login-endpoint user-auth confirm
+ *   node init-run.js /project --batch '[{"id":"wi-1","intent":"int-1","mode":"autopilot"}]'
  */
 
 const fs = require('fs');
@@ -33,35 +39,58 @@ function fireError(message, code, suggestion) {
 // =============================================================================
 
 const VALID_MODES = ['autopilot', 'confirm', 'validate'];
+const VALID_SCOPES = ['single', 'batch', 'wide'];
 
-function validateInputs(rootPath, workItemId, intentId, mode) {
+function validateRootPath(rootPath) {
   if (!rootPath || typeof rootPath !== 'string' || rootPath.trim() === '') {
     throw fireError('rootPath is required.', 'INIT_001', 'Provide a valid project root path.');
   }
 
-  if (!workItemId || typeof workItemId !== 'string' || workItemId.trim() === '') {
-    throw fireError('workItemId is required.', 'INIT_010', 'Provide a valid work item ID.');
+  if (!fs.existsSync(rootPath)) {
+    throw fireError(
+      `Project root not found: "${rootPath}".`,
+      'INIT_040',
+      'Ensure the path exists and is accessible.'
+    );
+  }
+}
+
+function validateWorkItem(item, index) {
+  if (!item.id || typeof item.id !== 'string' || item.id.trim() === '') {
+    throw fireError(
+      `Work item at index ${index} missing 'id'.`,
+      'INIT_010',
+      'Each work item must have an id.'
+    );
   }
 
-  if (!intentId || typeof intentId !== 'string' || intentId.trim() === '') {
-    throw fireError('intentId is required.', 'INIT_020', 'Provide a valid intent ID.');
+  if (!item.intent || typeof item.intent !== 'string' || item.intent.trim() === '') {
+    throw fireError(
+      `Work item "${item.id}" missing 'intent'.`,
+      'INIT_020',
+      'Each work item must have an intent.'
+    );
   }
 
-  if (!mode || !VALID_MODES.includes(mode)) {
+  if (!item.mode || !VALID_MODES.includes(item.mode)) {
     throw fireError(
-      `Invalid mode: "${mode}".`,
+      `Work item "${item.id}" has invalid mode: "${item.mode}".`,
       'INIT_030',
       `Valid modes are: ${VALID_MODES.join(', ')}`
     );
   }
+}
 
-  if (!fs.existsSync(rootPath)) {
+function validateWorkItems(workItems) {
+  if (!Array.isArray(workItems) || workItems.length === 0) {
     throw fireError(
-      `Project root not found: "${rootPath}".`,
-      'INIT_040',
-      'Ensure the path exists and is accessible.'
+      'Work items array is empty or invalid.',
+      'INIT_011',
+      'Provide at least one work item.'
     );
   }
+
+  workItems.forEach((item, index) => validateWorkItem(item, index));
 }
 
 function validateFireProject(rootPath) {
@@ -171,6 +200,19 @@ function generateRunId(runsPath, state) {
   return `run-${String(nextNum).padStart(3, '0')}`;
 }
 
+// =============================================================================
+// Scope Detection
+// =============================================================================
+
+function detectScope(workItems) {
+  if (workItems.length === 1) {
+    return 'single';
+  }
+  // For multiple items, default to batch
+  // (wide would be explicitly set by the caller if all compatible items are included)
+  return 'batch';
+}
+
 // =============================================================================
 // Run Folder Creation
 // =============================================================================
@@ -187,12 +229,21 @@ function createRunFolder(runPath) {
   }
 }
 
-function createRunLog(runPath, runId, workItemId, intentId, mode, startTime) {
+function createRunLog(runPath, runId, workItems, scope, startTime) {
+  // Format work items for run.md
+  const workItemsList = workItems.map((item, index) => {
+    const status = index === 0 ? 'in_progress' : 'pending';
+    return `  - id: ${item.id}\n    intent: ${item.intent}\n    mode: ${item.mode}\n    status: ${status}`;
+  }).join('\n');
+
+  const currentItem = workItems[0];
+
   const runLog = `---
 id: ${runId}
-work_item: ${workItemId}
-intent: ${intentId}
-mode: ${mode}
+scope: ${scope}
+work_items:
+${workItemsList}
+current_item: ${currentItem.id}
 status: in_progress
 started: ${startTime}
 completed: null
@@ -200,8 +251,14 @@ completed: null
 
 # Run: ${runId}
 
-## Work Item
-${workItemId}
+## Scope
+${scope} (${workItems.length} work item${workItems.length > 1 ? 's' : ''})
+
+## Work Items
+${workItems.map((item, i) => `${i + 1}. **${item.id}** (${item.mode}) — ${i === 0 ? 'in_progress' : 'pending'}`).join('\n')}
+
+## Current Item
+${currentItem.id} (${currentItem.mode})
 
 ## Files Created
 (none yet)
@@ -229,9 +286,30 @@ ${workItemId}
 // Main Function
 // =============================================================================
 
-function initRun(rootPath, workItemId, intentId, mode) {
-  // Validate inputs
-  validateInputs(rootPath, workItemId, intentId, mode);
+/**
+ * Initialize a run with one or more work items.
+ *
+ * @param {string} rootPath - Project root directory
+ * @param {Array<{id: string, intent: string, mode: string}>} workItems - Work items to include in run
+ * @param {string} [scope] - Optional scope override ('single', 'batch', 'wide')
+ * @returns {object} Result with runId, runPath, workItems, scope, started
+ */
+function initRun(rootPath, workItems, scope) {
+  // Validate root path
+  validateRootPath(rootPath);
+
+  // Validate work items
+  validateWorkItems(workItems);
+
+  // Detect or validate scope
+  const detectedScope = scope || detectScope(workItems);
+  if (scope && !VALID_SCOPES.includes(scope)) {
+    throw fireError(
+      `Invalid scope: "${scope}".`,
+      'INIT_035',
+      `Valid scopes are: ${VALID_SCOPES.join(', ')}`
+    );
+  }
 
   // Validate FIRE project structure
   const { statePath, runsPath } = validateFireProject(rootPath);
@@ -257,14 +335,22 @@ function initRun(rootPath, workItemId, intentId, mode) {
 
   // Create run log
   const startTime = new Date().toISOString();
-  createRunLog(runPath, runId, workItemId, intentId, mode, startTime);
+  createRunLog(runPath, runId, workItems, detectedScope, startTime);
+
+  // Prepare work items for state with status tracking
+  const stateWorkItems = workItems.map((item, index) => ({
+    id: item.id,
+    intent: item.intent,
+    mode: item.mode,
+    status: index === 0 ? 'in_progress' : 'pending',
+  }));
 
   // Update state with active run
   state.active_run = {
     id: runId,
-    work_item: workItemId,
-    intent: intentId,
-    mode: mode,
+    scope: detectedScope,
+    work_items: stateWorkItems,
+    current_item: workItems[0].id,
     started: startTime,
   };
 
@@ -276,9 +362,9 @@ function initRun(rootPath, workItemId, intentId, mode) {
     success: true,
     runId: runId,
     runPath: runPath,
-    workItemId: workItemId,
-    intentId: intentId,
-    mode: mode,
+    scope: detectedScope,
+    workItems: stateWorkItems,
+    currentItem: workItems[0].id,
     started: startTime,
   };
 }
@@ -287,27 +373,76 @@ function initRun(rootPath, workItemId, intentId, mode) {
 // CLI Interface
 // =============================================================================
 
+function printUsage() {
+  console.error('Usage:');
+  console.error('  Single item: node init-run.js <rootPath> <workItemId> <intentId> <mode>');
+  console.error('  Batch/Wide:  node init-run.js <rootPath> --batch \'<workItemsJson>\' [--scope=<scope>]');
+  console.error('');
+  console.error('Arguments:');
+  console.error('  rootPath      - Project root directory');
+  console.error('  workItemId    - Work item ID (single mode)');
+  console.error('  intentId      - Intent ID (single mode)');
+  console.error('  mode          - Execution mode: autopilot, confirm, validate');
+  console.error('');
+  console.error('Options:');
+  console.error('  --batch       - JSON array of work items');
+  console.error('  --scope       - Override scope: single, batch, wide');
+  console.error('');
+  console.error('Work item JSON format:');
+  console.error('  [{"id": "wi-1", "intent": "int-1", "mode": "autopilot"}, ...]');
+  console.error('');
+  console.error('Examples:');
+  console.error('  node init-run.js /project login-endpoint user-auth confirm');
+  console.error('  node init-run.js /project --batch \'[{"id":"wi-1","intent":"int-1","mode":"autopilot"}]\'');
+}
+
 if (require.main === module) {
   const args = process.argv.slice(2);
 
-  if (args.length < 4) {
-    console.error('Usage: node init-run.js <rootPath> <workItemId> <intentId> <mode>');
-    console.error('');
-    console.error('Arguments:');
-    console.error('  rootPath    - Project root directory');
-    console.error('  workItemId  - Work item ID to execute');
-    console.error('  intentId    - Intent ID containing the work item');
-    console.error('  mode        - Execution mode (autopilot, confirm, validate)');
-    console.error('');
-    console.error('Example:');
-    console.error('  node init-run.js /my/project login-endpoint user-auth confirm');
+  if (args.length < 2) {
+    printUsage();
     process.exit(1);
   }
 
-  const [rootPath, workItemId, intentId, mode] = args;
+  const rootPath = args[0];
+  let workItems = [];
+  let scope = null;
+
+  // Check if batch mode
+  if (args[1] === '--batch') {
+    if (args.length < 3) {
+      console.error('Error: --batch requires a JSON array of work items');
+      printUsage();
+      process.exit(1);
+    }
+
+    try {
+      workItems = JSON.parse(args[2]);
+    } catch (err) {
+      console.error(`Error: Failed to parse work items JSON: ${err.message}`);
+      process.exit(1);
+    }
+
+    // Check for --scope option
+    for (let i = 3; i < args.length; i++) {
+      if (args[i].startsWith('--scope=')) {
+        scope = args[i].substring('--scope='.length);
+      }
+    }
+  } else {
+    // Single item mode (backwards compatible)
+    if (args.length < 4) {
+      printUsage();
+      process.exit(1);
+    }
+
+    const [, workItemId, intentId, mode] = args;
+    workItems = [{ id: workItemId, intent: intentId, mode: mode }];
+    scope = 'single';
+  }
 
   try {
-    const result = initRun(rootPath, workItemId, intentId, mode);
+    const result = initRun(rootPath, workItems, scope);
     console.log(JSON.stringify(result, null, 2));
     process.exit(0);
   } catch (err) {

package/flows/fire/agents/builder/skills/run-plan/SKILL.md

@@ -18,6 +18,29 @@ Plan the scope of a run by discovering available work items and suggesting group
 
 ---
 
+## Critical Clarifications
+
+### Dependencies Mean Sequential Execution, NOT Separate Runs
+
+**IMPORTANT**: When work items have dependencies:
+- They execute **sequentially within the SAME run**
+- They do **NOT** require separate runs
+- The dependent item waits for its dependency to complete before starting
+
+**Example**: If item 05 depends on item 04:
+- **CORRECT**: ONE run with both items, 04 executes first, then 05
+- **WRONG**: TWO separate runs
+
+### All Options Can Include Multiple Items Per Run
+
+| Option | Items Per Run | Execution |
+|--------|---------------|-----------|
+| Single | 1 item | One at a time, separate runs |
+| Batch | Multiple items (same mode) | Sequential within run |
+| Wide | All compatible items | Sequential within run |
+
+---
+
 ## Workflow
 
 ```xml
@@ -28,6 +51,7 @@ Plan the scope of a run by discovering available work items and suggesting group
     SUGGEST smart groupings based on mode, dependencies, and user history.
     LEARN from user choices to improve future recommendations.
     NEVER force a scope - always let user choose.
+    DEPENDENCIES = SEQUENTIAL EXECUTION, NOT SEPARATE RUNS.
   </mandate>
 
   <step n="1" title="Discover Available Work">
@@ -71,10 +95,10 @@ Plan the scope of a run by discovering available work items and suggesting group
     <action>Read workspace.run_scope_preference from state.yaml (if exists)</action>
 
     <grouping-rules>
-      <rule>Same mode items CAN be batched together</rule>
-      <rule>Items with dependencies CANNOT be in same batch</rule>
-      <rule>Cross-intent batching allowed if items are independent</rule>
-      <rule>Validate mode items should generally run alone</rule>
+      <rule>Dependencies = SEQUENTIAL execution in SAME run (NOT separate runs)</rule>
+      <rule>Different modes CAN be in same run (executed sequentially)</rule>
+      <rule>Cross-intent items allowed in same run if compatible</rule>
+      <rule>Validate mode items may benefit from running alone (more checkpoints)</rule>
     </grouping-rules>
 
     <generate-options>
@@ -84,22 +108,22 @@ Plan the scope of a run by discovering available work items and suggesting group
       </option>
 
       <option name="batch">
-        Group by mode (autopilot together, confirm together)
-        Respect dependencies
-        Total runs: {count of mode groups}
+        All pending items in ONE run
+        Execute sequentially (dependencies respected by order)
+        Checkpoints pause at confirm/validate items
+        Total runs: 1
       </option>
 
       <option name="wide">
-        All compatible items in one run
-        Only separate if dependencies require it
-        Total runs: {minimum possible}
+        Same as batch - all items in one run
+        Total runs: 1
       </option>
     </generate-options>
   </step>
 
   <step n="4" title="Present Options">
     <action>Determine recommended option based on:</action>
-    <substep>autonomy_bias (autonomous→wide, controlled→single)</substep>
+    <substep>autonomy_bias (autonomous→batch, controlled→single)</substep>
     <substep>run_scope_preference (user's historical choice)</substep>
     <substep>Number of pending items (few items→single is fine)</substep>
 
@@ -115,20 +139,24 @@ Plan the scope of a run by discovering available work items and suggesting group
       {/for}
       {/for}
 
+      {if dependencies exist}
+      **Dependencies** (determines execution order):
+      - {dependent_item} depends on {dependency_item}
+      {/if}
+
       ---
 
       **How would you like to execute?**
 
       **[1] One at a time** — {single_count} separate runs
-          Most controlled, review after each
+          Most controlled, review after each run
 
-      **[2] Batch by mode** — {batch_count} runs {if recommended}(Recommended){/if}
-          {for each batch}
-          Run {n}: {item_names} ({mode})
-          {/for}
+      **[2] Sequential chain** — 1 run with {count} items (Recommended)
+          Execute in order: {item1} → {item2} → ...
+          Checkpoints pause at confirm/validate items
 
-      **[3] All together** — {wide_count} run(s)
-          Fastest, minimal interruption
+      **[3] All together** — Same as [2]
+          1 run, sequential execution
 
       Choose [1/2/3]:
     </output>
@@ -139,13 +167,9 @@ Plan the scope of a run by discovering available work items and suggesting group
       <set>run_scope = single</set>
       <set>work_items_for_run = [first_pending_item]</set>
     </check>
-    <check if="response == 2">
+    <check if="response == 2 or response == 3">
       <set>run_scope = batch</set>
-      <set>work_items_for_run = first_batch_items</set>
-    </check>
-    <check if="response == 3">
-      <set>run_scope = wide</set>
-      <set>work_items_for_run = all_compatible_items</set>
+      <set>work_items_for_run = all_pending_items_in_dependency_order</set>
     </check>
   </step>
 
@@ -170,14 +194,12 @@ Plan the scope of a run by discovering available work items and suggesting group
       Starting run with {count} work item(s):
 
       {for each item in work_items_for_run}
-      - {item.title} ({item.mode})
+      {index}. {item.title} ({item.mode})
       {/for}
 
-      {if run_scope == batch or wide}
       Items will execute sequentially within this run.
       {if any item is confirm or validate}
-      Checkpoints will pause for approval as needed.
-      {/if}
+      Checkpoints will pause for approval at confirm/validate items.
       {/if}
 
       ---
@@ -185,7 +207,7 @@ Plan the scope of a run by discovering available work items and suggesting group
       Begin execution? [Y/n]
     </output>
     <check if="response == y">
-      <invoke-skill args="work_items_for_run">run-execute</invoke-skill>
+      <invoke-skill args="work_items_for_run, run_scope">run-execute</invoke-skill>
     </check>
   </step>
 
@@ -255,14 +277,13 @@ active_run:
 ```
 1. Collect all pending items with their modes
 2. Build dependency graph
-3. For "batch" option:
-   - Group by mode
-   - Within each mode group, check dependencies
-   - Split if dependency exists within group
-4. For "wide" option:
-   - Start with all items in one group
-   - Split only where dependencies require
-5. Return groupings with run counts
+3. Sort items in dependency order (dependencies first)
+4. For "single" option:
+   - Each item is its own run
+5. For "batch" or "wide" option:
+   - ALL items in ONE run
+   - Execution order follows dependency graph
+   - Checkpoints pause at confirm/validate items
 ```
 
 ---
@@ -274,7 +295,7 @@ IF run_scope_history has 3+ same choices:
   pre_selected = most_common_choice
 
 ELSE IF autonomy_bias == autonomous:
-  recommended = wide
+  recommended = batch (all in one run)
 
 ELSE IF autonomy_bias == controlled:
   recommended = single

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.55",
+  "version": "0.0.0-dev.57",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {