specsmd 0.0.0-dev.55 → 0.0.0-dev.56

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.55",
+  "version": "0.0.0-dev.56",
   "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": {