@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/services/orchestration/workflow-orchestrator.js

@@ -50,6 +50,7 @@ import { PrdFixer } from '../parsers/prd-fixer.js';
 import { FileScaffolder } from '../scaffolding/file-scaffolder.js';
 import { BatchProcessor } from './batch-processor.js';
 import { StoryQueue } from './story-queue.js';
+import { ReviewQueue } from '../review/review-queue.js';
 /**
  * WorkflowOrchestrator service for coordinating multi-phase workflows
  *
@@ -60,14 +61,17 @@ import { StoryQueue } from './story-queue.js';
 export class WorkflowOrchestrator {
     agentRunner;
     batchProcessor;
+    callbacks;
     epicParser;
     fileManager;
     fileScaffolder;
     inputDetector;
     logger;
+    mcpContextInjector;
     pathResolver;
     prdFixer;
     prdParser;
+    reviewPhaseExecutor;
     storyTypeDetector;
     workflowLogger;
     /**
@@ -82,10 +86,13 @@ export class WorkflowOrchestrator {
         this.agentRunner = config.agentRunner;
         this.batchProcessor = config.batchProcessor;
         this.fileManager = config.fileManager;
+        this.mcpContextInjector = config.mcpContextInjector;
         this.pathResolver = config.pathResolver;
+        this.reviewPhaseExecutor = config.reviewPhaseExecutor;
         this.storyTypeDetector = config.storyTypeDetector;
         this.logger = config.logger;
         this.workflowLogger = config.workflowLogger;
+        this.callbacks = config.callbacks;
         this.fileScaffolder = new FileScaffolder(config.logger);
         this.prdFixer = new PrdFixer(config.agentRunner, config.fileManager, config.logger);
         this.logger.debug('WorkflowOrchestrator initialized');
@@ -111,9 +118,48 @@ export class WorkflowOrchestrator {
         if (this.shouldAbortAfterEpicFailure(epicPhase)) {
             return this.buildFailureResult(startTime, epicPhase);
         }
-        const { devPhase, storyPhase } = await this.executeStoryAndDevPhases(config, detection, epicPhase, phaseFlags, startTime);
+        const { devPhase, reviewPhase, storyPhase } = await this.executeStoryAndDevPhases(config, detection, epicPhase, phaseFlags, startTime);
         const qaPhase = await this.executeQaPhaseIfNeeded(config, detection, devPhase, phaseFlags.shouldExecuteQaPhase);
-        return this.buildSuccessResult(startTime, epicPhase, storyPhase, devPhase, qaPhase);
+        return this.buildSuccessResult(startTime, epicPhase, storyPhase, devPhase, qaPhase, reviewPhase);
+    }
+    /**
+     * Get MCP prompt prefix for a given phase
+     *
+     * Returns MCP tool discovery instructions to prepend before agent prompts.
+     * Returns empty string when MCP is disabled, injector is unavailable,
+     * phase is filtered out, or injector returns empty/errors.
+     *
+     * @param phase - Workflow phase (epic, story, dev, review, qa)
+     * @param agentType - Agent type being spawned
+     * @param config - Workflow configuration
+     * @returns Instructions string to prepend, or empty string
+     * @private
+     */
+    async getMcpPromptPrefix(phase, agentType, config) {
+        // Skip if MCP is not enabled
+        if (!config.mcp) {
+            return '';
+        }
+        // Skip if injector is not available
+        if (!this.mcpContextInjector) {
+            return '';
+        }
+        // Skip if phase is filtered out by mcpPhases
+        if (config.mcpPhases && config.mcpPhases.length > 0 && !config.mcpPhases.includes(phase)) {
+            return '';
+        }
+        try {
+            const mcpContext = await this.mcpContextInjector.getContextForAgent(agentType, phase);
+            if (!mcpContext.instructions) {
+                this.logger.warn({ phase }, 'MCP enabled but injector returned empty instructions');
+                return '';
+            }
+            return mcpContext.instructions;
+        }
+        catch (error) {
+            this.logger.warn({ error: error.message, phase }, 'MCP context injection failed, continuing without MCP tools');
+            return '';
+        }
     }
     /**
      * Build prompt for epic creation
@@ -197,13 +243,14 @@ Write output to: ${outputPath}`;
      * @returns WorkflowResult
      * @private
      */
-    buildSuccessResult(startTime, epicPhase, storyPhase, devPhase, qaPhase) {
+    buildSuccessResult(startTime, epicPhase, storyPhase, devPhase, qaPhase, reviewPhase) {
         const totalDuration = Date.now() - startTime;
         const totalFilesProcessed = (epicPhase?.success ?? 0) + (storyPhase?.success ?? 0) + (devPhase?.success ?? 0) + (qaPhase?.success ?? 0);
         const totalFailures = (epicPhase?.failures.length ?? 0) +
             (storyPhase?.failures.length ?? 0) +
             (devPhase?.failures.length ?? 0) +
-            (qaPhase?.failures.length ?? 0);
+            (qaPhase?.failures.length ?? 0) +
+            (reviewPhase?.failures.length ?? 0);
         const overallSuccess = totalFailures === 0;
         this.logger.info({
             overallSuccess,
@@ -216,12 +263,90 @@ Write output to: ${outputPath}`;
             epicPhase,
             overallSuccess,
             qaPhase,
+            reviewPhase,
             storyPhase,
             totalDuration,
             totalFailures,
             totalFilesProcessed,
         };
     }
+    /**
+     * Invoke a callback safely, catching and logging any errors
+     *
+     * All callback invocations are wrapped in try-catch to prevent
+     * callback errors from interrupting workflow execution.
+     *
+     * @param callbackName - Name of the callback for logging
+     * @param callback - The callback function to invoke
+     * @param context - The context to pass to the callback
+     * @private
+     */
+    invokeCallback(callbackName, callback, context) {
+        if (!callback)
+            return;
+        try {
+            callback(context);
+        }
+        catch (error) {
+            this.logger.warn({
+                callbackName,
+                error: error.message,
+            }, 'Callback error (ignored to prevent workflow interruption)');
+        }
+    }
+    /**
+     * Invoke the onSpawnOutput callback safely
+     *
+     * @param callback - The callback function to invoke
+     * @param context - The spawn context
+     * @param output - The output text
+     * @private
+     */
+    invokeSpawnOutputCallback(callback, context, output) {
+        if (!callback)
+            return;
+        try {
+            callback(context, output);
+        }
+        catch (error) {
+            this.logger.warn({
+                callbackName: 'onSpawnOutput',
+                error: error.message,
+            }, 'Callback error (ignored to prevent workflow interruption)');
+        }
+    }
+    /**
+     * Invoke the onError callback safely
+     *
+     * @param error - The error that occurred
+     * @param options - Additional context for the error
+     * @private
+     */
+    invokeErrorCallback(error, options = {}) {
+        const callback = this.callbacks?.onError;
+        if (!callback)
+            return;
+        const context = {
+            error,
+            itemId: options.itemId,
+            message: error.message,
+            metadata: options.metadata,
+            phaseName: options.phaseName,
+            recoverable: options.recoverable ?? true,
+            spawnId: options.spawnId,
+            stack: error.stack,
+            timestamp: Date.now(),
+        };
+        try {
+            callback(context);
+        }
+        catch (callbackError) {
+            this.logger.warn({
+                callbackName: 'onError',
+                error: callbackError.message,
+            }, 'Callback error (ignored to prevent workflow interruption)');
+        }
+    }
     /**
      * Check which files already exist in a directory
      *
@@ -297,7 +422,7 @@ Write output to: ${outputPath}`;
                 const content = await this.fileManager.readFile(filePath);
                 const isScaffolded = content.includes('_[AI Agent will populate');
                 if (isScaffolded) {
-                    this.logger.warn({
+                    this.logger.info({
                         fileName,
                         filePath,
                     }, 'Epic file exists but is only scaffolded (will be re-populated)');
@@ -373,11 +498,13 @@ Write output to: ${outputPath}`;
         const shouldExecuteEpicPhase = detection.type === 'prd' && !config.skipEpics;
         const shouldExecuteStoryPhase = !config.skipStories && detection.type !== 'story-pattern';
         const shouldExecuteDevPhase = !config.skipDev;
+        const shouldExecuteReviewPhase = config.review === true && shouldExecuteDevPhase;
         const shouldExecuteQaPhase = config.qa === true && shouldExecuteDevPhase;
         return {
             shouldExecuteDevPhase,
             shouldExecuteEpicPhase,
             shouldExecuteQaPhase,
+            shouldExecuteReviewPhase,
             shouldExecuteStoryPhase,
         };
     }
@@ -414,10 +541,11 @@ Write output to: ${outputPath}`;
      * @returns Promise resolving to object with success count and failure array
      * @private
      */
-    async devWorker(workerId, queue, config) {
+    async devWorker(workerId, queue, config, reviewQueue) {
         const workerLogger = this.logger.child({ workerId });
         let successCount = 0;
         const failures = [];
+        let devPhaseStarted = false;
         workerLogger.info('Worker started');
         try {
             const storyDir = await this.pathResolver.getStoryDir();
@@ -430,6 +558,16 @@ Write output to: ${outputPath}`;
                     workerLogger.info('Queue closed and empty, worker terminating');
                     break;
                 }
+                // Fire onPhaseStart on first dequeue (after story phase is done creating)
+                if (!devPhaseStarted) {
+                    devPhaseStarted = true;
+                    this.invokeCallback('onPhaseStart', this.callbacks?.onPhaseStart, {
+                        itemCount: 0,
+                        metadata: { mode: 'pipeline', workerId },
+                        phaseName: 'dev',
+                        startTime: Date.now(),
+                    });
+                }
                 workerLogger.info({
                     storyNumber: story.fullNumber,
                     storyTitle: story.title,
@@ -484,7 +622,9 @@ Write output to: ${outputPath}`;
                         storyType: detection.type,
                     }, 'Story type detected, auto-including documentation references');
                     // Build prompt with auto-detected references
-                    let prompt = `@.bmad-core/agents/dev.md\n\n`;
+                    const mcpPrefix = await this.getMcpPromptPrefix('dev', 'dev', config);
+                    let prompt = mcpPrefix ? `${mcpPrefix}\n\n` : '';
+                    prompt += `@.bmad-core/agents/dev.md\n\n`;
                     // Add working directory instruction if specified
                     if (config.cwd) {
                         prompt += `Working directory: ${config.cwd}\n\n`;
@@ -500,6 +640,20 @@ Write output to: ${outputPath}`;
                         prompt += '\n';
                     }
                     prompt += '*yolo mode*\n';
+                    // Generate unique spawn ID
+                    const spawnId = `dev-${story.fullNumber}-${storyStartTime}`;
+                    // Invoke onSpawnStart callback
+                    this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
+                        agentType: 'dev',
+                        itemId: story.fullNumber,
+                        itemTitle: story.title,
+                        outputPath: storyFilePath,
+                        phaseName: 'dev',
+                        prompt,
+                        spawnId,
+                        startTime: storyStartTime,
+                        workerId,
+                    });
                     // Execute dev agent with retry on timeout/killed
                     const result = await runAgentWithRetry(this.agentRunner, prompt, {
                         agentType: 'dev',
@@ -510,11 +664,33 @@ Write output to: ${outputPath}`;
                         logger: this.logger,
                         maxRetries: config.maxRetries,
                     });
+                    const spawnEndTime = Date.now();
+                    const spawnDuration = spawnEndTime - storyStartTime;
                     if (result.success) {
+                        // Invoke onSpawnComplete callback for success
+                        this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                            agentType: 'dev',
+                            duration: spawnDuration,
+                            endTime: spawnEndTime,
+                            itemId: story.fullNumber,
+                            itemTitle: story.title,
+                            output: result.output,
+                            outputPath: storyFilePath,
+                            phaseName: 'dev',
+                            spawnId,
+                            startTime: storyStartTime,
+                            success: true,
+                            workerId,
+                        });
                         // Update story status to Done
                         await this.updateStoryStatus(storyFilePath, 'Done');
                         // Move to QA folder
                         await this.fileManager.moveFile(storyFilePath, qaFilePath);
+                        // Enqueue to review queue if review is enabled (pipelined review path)
+                        if (reviewQueue) {
+                            reviewQueue.enqueue(story);
+                            workerLogger.info({ storyNumber: story.fullNumber }, 'Story enqueued for review');
+                        }
                         successCount++;
                         // Log story completed in pipeline mode
                         const storyDuration = Date.now() - storyStartTime;
@@ -530,6 +706,28 @@ Write output to: ${outputPath}`;
                         workerLogger.info({ storyNumber: story.fullNumber }, 'Story development completed successfully');
                     }
                     else {
+                        // Invoke onSpawnComplete callback for failure
+                        this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                            agentType: 'dev',
+                            duration: spawnDuration,
+                            endTime: spawnEndTime,
+                            error: result.errors,
+                            itemId: story.fullNumber,
+                            itemTitle: story.title,
+                            outputPath: storyFilePath,
+                            phaseName: 'dev',
+                            spawnId,
+                            startTime: storyStartTime,
+                            success: false,
+                            workerId,
+                        });
+                        // Invoke onError callback
+                        this.invokeErrorCallback(new Error(result.errors), {
+                            itemId: story.fullNumber,
+                            phaseName: 'dev',
+                            recoverable: true,
+                            spawnId,
+                        });
                         // Log story failed in pipeline mode
                         const storyDuration = Date.now() - storyStartTime;
                         if (this.workflowLogger) {
@@ -552,6 +750,12 @@ Write output to: ${outputPath}`;
                     }
                 }
                 catch (error) {
+                    // Invoke onError callback for unexpected errors
+                    this.invokeErrorCallback(error, {
+                        itemId: story.fullNumber,
+                        phaseName: 'dev',
+                        recoverable: true,
+                    });
                     // Catch errors for individual stories to prevent worker crash
                     workerLogger.error({
                         error: error.message,
@@ -636,10 +840,18 @@ Write output to: ${outputPath}`;
         const startTime = Date.now();
         const failures = [];
         let successCount = 0;
+        const itemCount = stories.length;
         this.logger.info({
             interval: config.storyInterval,
             storyCount: stories.length,
         }, 'Starting development phase');
+        // Invoke onPhaseStart callback
+        this.invokeCallback('onPhaseStart', this.callbacks?.onPhaseStart, {
+            itemCount,
+            metadata: { interval: config.storyInterval },
+            phaseName: 'dev',
+            startTime,
+        });
         try {
             const storyDir = await this.pathResolver.getStoryDir();
             const qaStoryDir = await this.pathResolver.getQaStoryDir();
@@ -685,7 +897,9 @@ Write output to: ${outputPath}`;
                     storyType: detection.type,
                 }, 'Story type detected, auto-including documentation references');
                 // Build prompt with auto-detected references
-                let prompt = `@.bmad-core/agents/dev.md\n\n`;
+                const mcpPrefix = await this.getMcpPromptPrefix('dev', 'dev', config);
+                let prompt = mcpPrefix ? `${mcpPrefix}\n\n` : '';
+                prompt += `@.bmad-core/agents/dev.md\n\n`;
                 // Add working directory instruction if specified
                 if (config.cwd) {
                     prompt += `Working directory: ${config.cwd}\n\n`;
@@ -701,6 +915,20 @@ Write output to: ${outputPath}`;
                     prompt += '\n';
                 }
                 prompt += '*yolo mode*\n';
+                // Generate unique spawn ID and timestamp
+                const spawnStartTime = Date.now();
+                const spawnId = `dev-${story.fullNumber}-${spawnStartTime}`;
+                // Invoke onSpawnStart callback
+                this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
+                    agentType: 'dev',
+                    itemId: story.fullNumber,
+                    itemTitle: story.title,
+                    outputPath: storyFilePath,
+                    phaseName: 'dev',
+                    prompt,
+                    spawnId,
+                    startTime: spawnStartTime,
+                });
                 const result = await runAgentWithRetry(this.agentRunner, prompt, {
                     agentType: 'dev',
                     references: config.references,
@@ -710,7 +938,23 @@ Write output to: ${outputPath}`;
                     logger: this.logger,
                     maxRetries: config.maxRetries,
                 });
+                const spawnEndTime = Date.now();
+                const spawnDuration = spawnEndTime - spawnStartTime;
                 if (result.success) {
+                    // Invoke onSpawnComplete callback for success
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'dev',
+                        duration: spawnDuration,
+                        endTime: spawnEndTime,
+                        itemId: story.fullNumber,
+                        itemTitle: story.title,
+                        output: result.output,
+                        outputPath: storyFilePath,
+                        phaseName: 'dev',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: true,
+                    });
                     // Update story status to Done
                     await this.updateStoryStatus(storyFilePath, 'Done');
                     // Move to QA folder (qaFilePath already defined above with correct filename)
@@ -719,6 +963,27 @@ Write output to: ${outputPath}`;
                     this.logger.info({ storyNumber: story.fullNumber }, 'Story development completed successfully');
                 }
                 else {
+                    // Invoke onSpawnComplete callback for failure
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'dev',
+                        duration: spawnDuration,
+                        endTime: spawnEndTime,
+                        error: result.errors,
+                        itemId: story.fullNumber,
+                        itemTitle: story.title,
+                        outputPath: storyFilePath,
+                        phaseName: 'dev',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: false,
+                    });
+                    // Invoke onError callback for spawn failure
+                    this.invokeErrorCallback(new Error(result.errors), {
+                        itemId: story.fullNumber,
+                        phaseName: 'dev',
+                        recoverable: true,
+                        spawnId,
+                    });
                     this.logger.error({
                         error: result.errors,
                         storyNumber: story.fullNumber,
@@ -735,11 +1000,22 @@ Write output to: ${outputPath}`;
                 }
             }
             const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.info({
                 duration,
                 failures: failures.length,
                 success: successCount,
             }, 'Development phase completed');
+            // Invoke onPhaseComplete callback
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length,
+                itemCount,
+                phaseName: 'dev',
+                startTime,
+                successCount,
+            });
             return {
                 duration,
                 failures,
@@ -749,9 +1025,28 @@ Write output to: ${outputPath}`;
             };
         }
         catch (error) {
+            const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.error({ error: error.message }, 'Development phase failed');
+            // Invoke onError callback
+            this.invokeErrorCallback(error, {
+                itemId: 'dev-phase',
+                phaseName: 'dev',
+                recoverable: false,
+            });
+            // Invoke onPhaseComplete callback even on error
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length + 1,
+                itemCount,
+                metadata: { error: error.message },
+                phaseName: 'dev',
+                startTime,
+                successCount,
+            });
             return {
-                duration: Date.now() - startTime,
+                duration,
                 failures: [
                     ...failures,
                     {
@@ -780,11 +1075,19 @@ Write output to: ${outputPath}`;
         const startTime = Date.now();
         const failures = [];
         let successCount = 0;
+        let itemCount = 0;
         this.logger.info({
             interval: config.prdInterval,
             parallel: config.parallel,
             prdFile: prdFilePath,
         }, 'Starting epic creation phase');
+        // Invoke onPhaseStart callback (itemCount will be updated once epics are parsed)
+        this.invokeCallback('onPhaseStart', this.callbacks?.onPhaseStart, {
+            itemCount: 0,
+            metadata: { parallel: config.parallel, prdFilePath },
+            phaseName: 'epic',
+            startTime,
+        });
         try {
             // Read PRD file
             let prdContent = await this.fileManager.readFile(prdFilePath);
@@ -819,8 +1122,19 @@ Write output to: ${outputPath}`;
                 }
             }
             this.logger.info({ epicCount: epics.length }, 'Epics extracted from PRD');
+            itemCount = epics.length;
             if (epics.length === 0) {
                 this.logger.warn('No epics found in PRD file');
+                // Invoke onPhaseComplete for empty phase
+                this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                    duration: Date.now() - startTime,
+                    endTime: Date.now(),
+                    failureCount: 0,
+                    itemCount: 0,
+                    phaseName: 'epic',
+                    startTime,
+                    successCount: 0,
+                });
                 return {
                     duration: Date.now() - startTime,
                     failures: [],
@@ -837,8 +1151,18 @@ Write output to: ${outputPath}`;
             const epicsToCreate = epics.filter((epic) => !properlyPopulatedEpics.includes(this.generateEpicFileName(prefix, epic.number)));
             if (epicsToCreate.length === 0) {
                 this.logger.info('All epics already exist and are properly populated, skipping creation');
+                const duration = Date.now() - startTime;
+                this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                    duration,
+                    endTime: Date.now(),
+                    failureCount: 0,
+                    itemCount: epics.length,
+                    phaseName: 'epic',
+                    startTime,
+                    successCount: epics.length,
+                });
                 return {
-                    duration: Date.now() - startTime,
+                    duration,
                     failures: [],
                     phaseName: 'epic',
                     skipped: false,
@@ -851,99 +1175,142 @@ Write output to: ${outputPath}`;
             }, 'Creating/re-populating epic files');
             // Create epic files using BatchProcessor and ClaudeAgentRunner
             const results = await this.batchProcessor.processBatch(epicsToCreate, async (epic) => {
-                // Generate epic file path with prefix
-                const epicFileName = this.generateEpicFileName(prefix, epic.number);
-                const epicFilePath = `${epicDir}/${epicFileName}`;
-                // Check if file already exists and is properly populated
-                const fileExists = await this.fileManager.fileExists(epicFilePath);
-                if (fileExists) {
-                    // Check if the file is properly populated (has actual story entries, not placeholder text)
-                    const existingContent = await this.fileManager.readFile(epicFilePath);
-                    const isScaffolded = existingContent.includes('_[AI Agent will populate');
-                    if (!isScaffolded) {
-                        // File is properly populated, skip recreation
+                const spawnStartTime = Date.now();
+                const spawnId = `epic-${epic.number}`;
+                // Fire onSpawnStart so the reporter shows which epic is being generated
+                this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
+                    agentType: 'architect',
+                    itemId: `epic-${epic.number}`,
+                    itemTitle: epic.title,
+                    phaseName: 'epic',
+                    spawnId,
+                    startTime: spawnStartTime,
+                });
+                try {
+                    // Generate epic file path with prefix
+                    const epicFileName = this.generateEpicFileName(prefix, epic.number);
+                    const epicFilePath = `${epicDir}/${epicFileName}`;
+                    // Check if file already exists and is properly populated
+                    const fileExists = await this.fileManager.fileExists(epicFilePath);
+                    if (fileExists) {
+                        // Check if the file is properly populated (has actual story entries, not placeholder text)
+                        const existingContent = await this.fileManager.readFile(epicFilePath);
+                        const isScaffolded = existingContent.includes('_[AI Agent will populate');
+                        if (!isScaffolded) {
+                            // File is properly populated, skip recreation
+                            this.logger.info({
+                                epicNumber: epic.number,
+                                epicTitle: epic.title,
+                                filePath: epicFilePath,
+                            }, 'Epic file already exists and is properly populated, skipping creation');
+                            return epicFilePath;
+                        }
+                        // File exists but is only scaffolded (incomplete) - will re-populate it
                         this.logger.info({
                             epicNumber: epic.number,
                             epicTitle: epic.title,
                             filePath: epicFilePath,
-                        }, 'Epic file already exists and is properly populated, skipping creation');
-                        return epicFilePath;
+                        }, 'Epic file exists but is only scaffolded (incomplete), re-populating with Claude agent');
                     }
-                    // File exists but is only scaffolded (incomplete) - will re-populate it
-                    this.logger.warn({
-                        epicNumber: epic.number,
-                        epicTitle: epic.title,
-                        filePath: epicFilePath,
-                    }, 'Epic file exists but is only scaffolded (incomplete), re-populating with Claude agent');
-                }
-                // Step 1: Create scaffolded file with structured sections and populated metadata (if not exists)
-                const scaffoldedContent = this.fileScaffolder.scaffoldEpic({
-                    epicNumber: epic.number,
-                    epicTitle: epic.title,
-                    prefix,
-                });
-                if (fileExists) {
-                    this.logger.info({
-                        epicNumber: epic.number,
-                        epicTitle: epic.title,
-                        filePath: epicFilePath,
-                    }, 'Using existing scaffolded epic file');
-                }
-                else {
-                    await this.fileManager.writeFile(epicFilePath, scaffoldedContent);
-                    this.logger.info({
-                        epicNumber: epic.number,
-                        epicTitle: epic.title,
-                        filePath: epicFilePath,
-                    }, 'Epic scaffolded file created');
-                }
-                // Step 2: Build Claude prompt to populate the scaffolded file
-                const prompt = this.buildEpicPrompt(epic, {
-                    cwd: config.cwd,
-                    outputPath: epicFilePath,
-                    prdPath: prdFilePath,
-                    prefix,
-                    references: config.references,
-                });
-                // Log prompt if verbose
-                if (config.verbose) {
-                    this.logger.info({
+                    // Step 1: Create scaffolded file with structured sections and populated metadata (if not exists)
+                    const scaffoldedContent = this.fileScaffolder.scaffoldEpic({
                         epicNumber: epic.number,
                         epicTitle: epic.title,
+                        prefix,
+                    });
+                    if (fileExists) {
+                        this.logger.info({
+                            epicNumber: epic.number,
+                            epicTitle: epic.title,
+                            filePath: epicFilePath,
+                        }, 'Using existing scaffolded epic file');
+                    }
+                    else {
+                        await this.fileManager.writeFile(epicFilePath, scaffoldedContent);
+                        this.logger.info({
+                            epicNumber: epic.number,
+                            epicTitle: epic.title,
+                            filePath: epicFilePath,
+                        }, 'Epic scaffolded file created');
+                    }
+                    // Step 2: Build Claude prompt to populate the scaffolded file
+                    const mcpPrefix = await this.getMcpPromptPrefix('epic', 'architect', config);
+                    const basePrompt = this.buildEpicPrompt(epic, {
+                        cwd: config.cwd,
                         outputPath: epicFilePath,
-                        prompt,
-                    }, 'Claude Prompt (Epic)');
-                }
-                // Step 3: Run Claude agent to populate content sections
-                const result = await runAgentWithRetry(this.agentRunner, prompt, {
-                    agentType: 'architect',
-                    references: config.references,
-                    timeout: config.timeout ?? 2_700_000,
-                }, {
-                    backoffMs: config.retryBackoffMs,
-                    logger: this.logger,
-                    maxRetries: config.maxRetries,
-                });
-                // Log output if verbose
-                if (config.verbose) {
-                    this.logger.info({
-                        duration: result.duration,
-                        epicNumber: epic.number,
-                        errors: result.errors,
-                        output: result.output,
-                        outputLength: result.output.length,
-                        success: result.success,
-                    }, 'Claude Response (Epic)');
-                }
-                if (!result.success) {
-                    throw new Error(result.errors);
+                        prdPath: prdFilePath,
+                        prefix,
+                        references: config.references,
+                    });
+                    const prompt = mcpPrefix ? `${mcpPrefix}\n\n${basePrompt}` : basePrompt;
+                    // Log prompt if verbose
+                    if (config.verbose) {
+                        this.logger.info({
+                            epicNumber: epic.number,
+                            epicTitle: epic.title,
+                            outputPath: epicFilePath,
+                            prompt,
+                        }, 'Claude Prompt (Epic)');
+                    }
+                    // Step 3: Run Claude agent to populate content sections
+                    const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                        agentType: 'architect',
+                        references: config.references,
+                        timeout: config.timeout ?? 2_700_000,
+                    }, {
+                        backoffMs: config.retryBackoffMs,
+                        logger: this.logger,
+                        maxRetries: config.maxRetries,
+                    });
+                    // Log output if verbose
+                    if (config.verbose) {
+                        this.logger.info({
+                            duration: result.duration,
+                            epicNumber: epic.number,
+                            errors: result.errors,
+                            output: result.output,
+                            outputLength: result.output.length,
+                            success: result.success,
+                        }, 'Claude Response (Epic)');
+                    }
+                    if (!result.success) {
+                        throw new Error(result.errors);
+                    }
+                    // Step 4: Verify file was updated by Claude
+                    const updatedContent = await this.fileManager.readFile(epicFilePath);
+                    if (updatedContent === scaffoldedContent) {
+                        throw new Error(`Claude did not update the epic file at ${epicFilePath}`);
+                    }
+                    // Fire onSpawnComplete for success
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'architect',
+                        duration: Date.now() - spawnStartTime,
+                        endTime: Date.now(),
+                        itemId: `epic-${epic.number}`,
+                        itemTitle: epic.title,
+                        phaseName: 'epic',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: true,
+                    });
+                    return epicFilePath;
                 }
-                // Step 4: Verify file was updated by Claude
-                const updatedContent = await this.fileManager.readFile(epicFilePath);
-                if (updatedContent === scaffoldedContent) {
-                    throw new Error(`Claude did not update the epic file at ${epicFilePath}`);
+                catch (spawnError) {
+                    // Fire onSpawnComplete for failure
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'architect',
+                        duration: Date.now() - spawnStartTime,
+                        endTime: Date.now(),
+                        error: spawnError.message,
+                        itemId: `epic-${epic.number}`,
+                        itemTitle: epic.title,
+                        phaseName: 'epic',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: false,
+                    });
+                    throw spawnError;
                 }
-                return epicFilePath;
             }, (info) => {
                 this.logger.info({
                     completedItems: info.completedItems,
@@ -967,11 +1334,23 @@ Write output to: ${outputPath}`;
             // Add properly populated epics to success count
             successCount += properlyPopulatedEpics.length;
             const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.info({
                 duration,
                 failures: failures.length,
                 success: successCount,
             }, 'Epic creation phase completed');
+            // Invoke onPhaseComplete callback
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length,
+                itemCount,
+                metadata: { parallel: config.parallel, prdFilePath },
+                phaseName: 'epic',
+                startTime,
+                successCount,
+            });
             return {
                 duration,
                 failures,
@@ -981,9 +1360,28 @@ Write output to: ${outputPath}`;
             };
         }
         catch (error) {
+            const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.error({ error: error.message }, 'Epic phase failed');
+            // Invoke onError callback
+            this.invokeErrorCallback(error, {
+                itemId: 'epic-phase',
+                phaseName: 'epic',
+                recoverable: false,
+            });
+            // Invoke onPhaseComplete callback even on error
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length + 1,
+                itemCount,
+                metadata: { error: error.message },
+                phaseName: 'epic',
+                startTime,
+                successCount,
+            });
             return {
-                duration: Date.now() - startTime,
+                duration,
                 failures: [
                     ...failures,
                     {
@@ -1050,7 +1448,7 @@ Write output to: ${outputPath}`;
      * @returns PhaseResult with aggregate success/failure counts and duration
      * @private
      */
-    async executePipelinedDevPhase(queue, config) {
+    async executePipelinedDevPhase(queue, config, reviewQueue) {
         const startTime = Date.now();
         // PIPELINE MODE: Use single worker for sequential story processing
         // Stories are processed in order, one at a time as they become available
@@ -1058,13 +1456,19 @@ Write output to: ${outputPath}`;
         this.logger.info({
             interval: config.storyInterval,
             mode: 'sequential',
+            reviewEnabled: !!reviewQueue,
             workerCount,
         }, 'Starting pipelined development phase (sequential processing)');
         try {
-            // Create single worker for sequential processing
-            const workers = Array.from({ length: workerCount }, (_, i) => this.devWorker(i, queue, config));
+            // Create single worker for sequential processing, passing reviewQueue if review is enabled
+            const workers = Array.from({ length: workerCount }, (_, i) => this.devWorker(i, queue, config, reviewQueue));
             // Wait for worker to complete
             const workerResults = await Promise.all(workers);
+            // Close ReviewQueue after all dev workers finish (Task 3: close/drain semantics)
+            if (reviewQueue) {
+                reviewQueue.close();
+                this.logger.info('ReviewQueue closed after all dev workers completed');
+            }
             // Aggregate results from all workers
             let totalSuccess = 0;
             const allFailures = [];
@@ -1079,6 +1483,15 @@ Write output to: ${outputPath}`;
                 success: totalSuccess,
                 workerCount,
             }, 'Pipelined development phase completed');
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime: Date.now(),
+                failureCount: allFailures.length,
+                itemCount: totalSuccess + allFailures.length,
+                phaseName: 'dev',
+                startTime,
+                successCount: totalSuccess,
+            });
             return {
                 duration,
                 failures: allFailures,
@@ -1089,6 +1502,20 @@ Write output to: ${outputPath}`;
         }
         catch (error) {
             this.logger.error({ error: error.message }, 'Pipelined development phase failed');
+            // Ensure ReviewQueue is closed on failure so review workers can terminate
+            if (reviewQueue) {
+                reviewQueue.close();
+                this.logger.info('ReviewQueue closed after dev phase failure');
+            }
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration: Date.now() - startTime,
+                endTime: Date.now(),
+                failureCount: 1,
+                itemCount: 1,
+                phaseName: 'dev',
+                startTime,
+                successCount: 0,
+            });
             return {
                 duration: Date.now() - startTime,
                 failures: [
@@ -1104,19 +1531,187 @@ Write output to: ${outputPath}`;
         }
     }
     /**
-     * Execute pipelined workflow (story and dev phases in parallel)
+     * Review worker that consumes stories from the ReviewQueue and processes them.
+     *
+     * Worker loop:
+     * 1. Dequeue next story (blocks/waits if queue empty)
+     * 2. If null returned, queue is closed and empty → terminate worker
+     * 3. For each story, invoke ReviewPhaseExecutor.reviewStory()
+     * 4. Collect pass/fail results
+     *
+     * @param workerId - Worker identifier for logging
+     * @param reviewQueue - ReviewQueue to dequeue stories from
+     * @param config - Workflow configuration
+     * @returns Worker result with passed and failed story arrays
+     * @private
+     */
+    async reviewWorker(workerId, reviewQueue, config) {
+        const workerLogger = this.logger.child({ reviewWorkerId: workerId });
+        const passedStories = [];
+        const failures = [];
+        let successCount = 0;
+        workerLogger.info('Review worker started');
+        try {
+            while (true) {
+                const story = await reviewQueue.dequeue();
+                if (!story) {
+                    workerLogger.info('ReviewQueue closed and empty, review worker terminating');
+                    break;
+                }
+                workerLogger.info({ storyNumber: story.fullNumber, storyTitle: story.title }, 'Review worker processing story');
+                try {
+                    const result = await this.reviewPhaseExecutor.reviewStory(story, config);
+                    if (result.verdict === 'PASS') {
+                        passedStories.push(story);
+                        successCount++;
+                        workerLogger.info({ storyNumber: story.fullNumber, verdict: 'PASS' }, 'Story review passed');
+                    }
+                    else {
+                        const failureReason = result.message || `Review failed with ${result.issues.length} issue(s)`;
+                        failures.push({
+                            error: failureReason,
+                            identifier: story.fullNumber,
+                        });
+                        workerLogger.warn({
+                            issueCount: result.issues.length,
+                            reason: failureReason,
+                            storyNumber: story.fullNumber,
+                            verdict: 'FAIL',
+                        }, 'Story review failed — excluded from QA');
+                    }
+                }
+                catch (error) {
+                    workerLogger.error({ error: error.message, storyNumber: story.fullNumber }, 'Error reviewing story, marking as failed');
+                    failures.push({
+                        error: error.message,
+                        identifier: story.fullNumber,
+                    });
+                }
+            }
+            workerLogger.info({ failureCount: failures.length, passedCount: passedStories.length, successCount }, 'Review worker completed');
+            return { failures, passedStories, success: successCount };
+        }
+        catch (error) {
+            workerLogger.error({ error: error.message }, 'Review worker failed with unhandled error');
+            return { failures, passedStories, success: successCount };
+        }
+    }
+    /**
+     * Execute pipelined review phase with worker pool.
+     *
+     * @param reviewQueue - ReviewQueue to consume stories from
+     * @param config - Workflow configuration
+     * @returns PhaseResult with aggregate success/failure counts and passed stories
+     * @private
+     */
+    async executePipelinedReviewPhase(reviewQueue, config) {
+        const startTime = Date.now();
+        const workerCount = 1;
+        this.logger.info({ mode: 'sequential', workerCount }, 'Starting pipelined review phase');
+        try {
+            const workers = Array.from({ length: workerCount }, (_, i) => this.reviewWorker(i, reviewQueue, config));
+            const workerResults = await Promise.all(workers);
+            let totalSuccess = 0;
+            const allFailures = [];
+            const allPassedStories = [];
+            for (const result of workerResults) {
+                totalSuccess += result.success;
+                allFailures.push(...result.failures);
+                allPassedStories.push(...result.passedStories);
+            }
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                failures: allFailures.length,
+                passedStories: allPassedStories.length,
+                success: totalSuccess,
+                workerCount,
+            }, 'Pipelined review phase completed');
+            return {
+                passedStories: allPassedStories,
+                phaseResult: {
+                    duration,
+                    failures: allFailures,
+                    phaseName: 'review',
+                    skipped: false,
+                    success: totalSuccess,
+                },
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Pipelined review phase failed');
+            return {
+                passedStories: [],
+                phaseResult: {
+                    duration: Date.now() - startTime,
+                    failures: [{ error: error.message, identifier: 'review-phase' }],
+                    phaseName: 'review',
+                    skipped: false,
+                    success: 0,
+                },
+            };
+        }
+    }
+    /**
+     * Execute pipelined workflow (story, dev, and optionally review phases in parallel)
+     *
+     * When config.review === true && reviewPhaseExecutor is available:
+     *   [StoryQueue] → dev workers → [ReviewQueue] → review workers → QA collection
+     * When config.review === false (default):
+     *   [StoryQueue] → dev workers → QA collection (unchanged behavior)
      *
      * @param config - Workflow configuration
      * @param detection - Input detection result
-     * @returns Story and dev phase results
+     * @returns Story, dev, and optional review phase results
      * @private
      */
     async executePipelinedWorkflow(config, detection) {
-        this.logger.info('Executing pipelined workflow (sequential dev starts as stories are created)');
+        const pipelineStartTime = Date.now();
+        const enableReview = config.review === true && this.reviewPhaseExecutor != null;
+        this.logger.info({ review: enableReview }, 'Executing pipelined workflow (sequential dev starts as stories are created)');
         const queue = new StoryQueue(this.logger);
+        const reviewQueue = enableReview ? new ReviewQueue(this.logger) : undefined;
         try {
             const storyPhasePromise = this.executeStoryPhaseWithQueue(config, detection, queue);
-            const devPhasePromise = this.executePipelinedDevPhase(queue, config);
+            const devPhasePromise = this.executePipelinedDevPhase(queue, config, reviewQueue);
+            if (enableReview && reviewQueue) {
+                // Three-phase pipeline: story → dev → review
+                const reviewPhasePromise = this.executePipelinedReviewPhase(reviewQueue, config);
+                const [storyResult, devResult, reviewResult] = await Promise.allSettled([
+                    storyPhasePromise,
+                    devPhasePromise,
+                    reviewPhasePromise,
+                ]);
+                const devPhase = this.handlePhaseResult(devResult, 'dev');
+                const storyPhase = this.handlePhaseResult(storyResult, 'story');
+                let reviewPhase;
+                if (reviewResult.status === 'fulfilled') {
+                    reviewPhase = reviewResult.value.phaseResult;
+                }
+                else {
+                    this.logger.error({ error: reviewResult.reason?.message }, 'Review phase promise rejected');
+                    reviewPhase = {
+                        duration: 0,
+                        failures: [{ error: reviewResult.reason?.message || 'Review phase failed', identifier: 'review-phase' }],
+                        phaseName: 'review',
+                        skipped: false,
+                        success: 0,
+                    };
+                }
+                // Timing instrumentation (NFR4)
+                const totalDuration = Date.now() - pipelineStartTime;
+                const devDuration = devPhase?.duration ?? 0;
+                const reviewDuration = reviewPhase?.duration ?? 0;
+                const reviewOverheadPercent = devDuration > 0 ? Math.round((reviewDuration / devDuration) * 100) : 0;
+                this.logger.info({
+                    devDuration,
+                    reviewDuration,
+                    reviewOverheadPercent,
+                    totalDuration,
+                }, 'Pipeline timing: dev + review phase durations');
+                return { devPhase, reviewPhase, storyPhase };
+            }
+            // Two-phase pipeline: story → dev (default, no review)
             const [storyResult, devResult] = await Promise.allSettled([storyPhasePromise, devPhasePromise]);
             return {
                 devPhase: this.handlePhaseResult(devResult, 'dev'),
@@ -1146,9 +1741,17 @@ Write output to: ${outputPath}`;
         const startTime = Date.now();
         const failures = [];
         let successCount = 0;
+        let itemCount = 0;
         this.logger.info({
             qaRetries: config.qaRetries ?? 2,
         }, 'Starting QA phase');
+        // Invoke onPhaseStart callback
+        this.invokeCallback('onPhaseStart', this.callbacks?.onPhaseStart, {
+            itemCount: 0,
+            metadata: { qaRetries: config.qaRetries ?? 2 },
+            phaseName: 'qa',
+            startTime,
+        });
         try {
             // Get QA story directory
             const qaStoryDir = await this.pathResolver.getQaStoryDir();
@@ -1158,6 +1761,17 @@ Write output to: ${outputPath}`;
             const storyFiles = await this.fileManager.listFiles(qaStoryDir, storyPattern);
             if (storyFiles.length === 0) {
                 this.logger.info('No stories found in QA folder, skipping QA phase');
+                // Invoke onPhaseComplete for skipped phase
+                this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                    duration: Date.now() - startTime,
+                    endTime: Date.now(),
+                    failureCount: 0,
+                    itemCount: 0,
+                    phaseName: 'qa',
+                    skipped: true,
+                    startTime,
+                    successCount: 0,
+                });
                 return {
                     duration: Date.now() - startTime,
                     failures: [],
@@ -1166,6 +1780,7 @@ Write output to: ${outputPath}`;
                     success: 0,
                 };
             }
+            itemCount = storyFiles.length;
             this.logger.info({ storyCount: storyFiles.length }, 'Found stories for QA phase');
             // Dynamically import QA command to avoid circular dependencies
             const { default: StoriesQaCommand } = await import('../../commands/stories/qa.js');
@@ -1190,8 +1805,29 @@ Write output to: ${outputPath}`;
                             qaFlags.push(`--reference=${ref}`);
                         }
                     }
-                    // Run QA command
-                    await StoriesQaCommand.run([...qaArgs, ...qaFlags]);
+                    // Forward MCP flags to QA command (when QA command supports them)
+                    if (config.mcp) {
+                        qaFlags.push('--mcp');
+                        if (config.mcpPhases && config.mcpPhases.length > 0) {
+                            qaFlags.push(`--mcp-phases=${config.mcpPhases.join(',')}`);
+                        }
+                    }
+                    // Suppress QA command's pino logger in non-verbose mode
+                    const prevLogLevel = process.env.LOG_LEVEL;
+                    if (!config.verbose) {
+                        process.env.LOG_LEVEL = 'silent';
+                    }
+                    try {
+                        await StoriesQaCommand.run([...qaArgs, ...qaFlags]);
+                    }
+                    finally {
+                        if (prevLogLevel === undefined) {
+                            delete process.env.LOG_LEVEL;
+                        }
+                        else {
+                            process.env.LOG_LEVEL = prevLogLevel;
+                        }
+                    }
                     successCount++;
                     this.logger.info({ storyPath }, 'QA workflow completed successfully for story');
                 }
@@ -1205,11 +1841,22 @@ Write output to: ${outputPath}`;
                 }
             }
             const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.info({
                 duration,
                 failures: failures.length,
                 success: successCount,
             }, 'QA phase completed');
+            // Invoke onPhaseComplete callback
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length,
+                itemCount,
+                phaseName: 'qa',
+                startTime,
+                successCount,
+            });
             return {
                 duration,
                 failures,
@@ -1219,9 +1866,28 @@ Write output to: ${outputPath}`;
             };
         }
         catch (error) {
+            const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.error({ error: error.message }, 'QA phase failed');
+            // Invoke onError callback
+            this.invokeErrorCallback(error, {
+                itemId: 'qa-phase',
+                phaseName: 'qa',
+                recoverable: false,
+            });
+            // Invoke onPhaseComplete callback even on error
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length + 1,
+                itemCount,
+                metadata: { error: error.message },
+                phaseName: 'qa',
+                startTime,
+                successCount,
+            });
             return {
-                duration: Date.now() - startTime,
+                duration,
                 failures: [
                     ...failures,
                     {
@@ -1319,6 +1985,43 @@ Write output to: ${outputPath}`;
             return { devPhase: this.createSkippedPhaseResult('dev'), storyPhase };
         }
         const devPhase = await this.executeSequentialDevPhase(config, detection, phaseFlags.shouldExecuteDevPhase);
+        // Review phase: after dev, before QA (sequential batch-style)
+        if (phaseFlags.shouldExecuteReviewPhase && this.reviewPhaseExecutor && devPhase && devPhase.success > 0) {
+            const reviewStartTime = Date.now();
+            const stories = await this.getStoriesForDevPhase(config, detection);
+            const reviewFailures = [];
+            let reviewSuccess = 0;
+            this.logger.info({ storyCount: stories.length }, 'Starting sequential review phase');
+            for (const story of stories) {
+                try {
+                    const result = await this.reviewPhaseExecutor.reviewStory(story, config);
+                    if (result.verdict === 'PASS') {
+                        reviewSuccess++;
+                    }
+                    else {
+                        reviewFailures.push({
+                            error: result.message || `Review failed with ${result.issues.length} issue(s)`,
+                            identifier: story.fullNumber,
+                        });
+                        this.logger.warn({ storyNumber: story.fullNumber, verdict: 'FAIL' }, 'Story review failed — excluded from QA');
+                    }
+                }
+                catch (error) {
+                    reviewFailures.push({
+                        error: error.message,
+                        identifier: story.fullNumber,
+                    });
+                }
+            }
+            const reviewPhase = {
+                duration: Date.now() - reviewStartTime,
+                failures: reviewFailures,
+                phaseName: 'review',
+                skipped: false,
+                success: reviewSuccess,
+            };
+            return { devPhase, reviewPhase, storyPhase };
+        }
         return { devPhase, storyPhase };
     }
     /**
@@ -1355,16 +2058,24 @@ Write output to: ${outputPath}`;
         const startTime = Date.now();
         const failures = [];
         let successCount = 0;
+        let itemCount = 0;
         // In pipeline mode, stories must be created sequentially (one at a time)
         // to ensure they are queued in the correct order for development
         const isPipelineMode = Boolean(onStoryComplete);
-        const effectiveParallel = isPipelineMode ? 1 : config.parallel;
+        const effectiveParallel = config.parallel;
         this.logger.info({
             epicCount: epics.length,
             interval: config.epicInterval,
             mode: isPipelineMode ? 'sequential (pipeline)' : 'parallel',
             parallel: effectiveParallel,
         }, 'Starting story creation phase');
+        // Invoke onPhaseStart callback
+        this.invokeCallback('onPhaseStart', this.callbacks?.onPhaseStart, {
+            itemCount: 0,
+            metadata: { epicCount: epics.length, parallel: effectiveParallel, pipelineMode: isPipelineMode },
+            phaseName: 'story',
+            startTime,
+        });
         try {
             const allStories = [];
             // Get epic directory
@@ -1397,8 +2108,19 @@ Write output to: ${outputPath}`;
             // Flatten the array of story arrays
             allStories.push(...epicStories.flat());
             this.logger.info({ storyCount: allStories.length }, 'Stories extracted from epics');
+            itemCount = allStories.length;
             if (allStories.length === 0) {
                 this.logger.warn('No stories found in epic files');
+                // Invoke onPhaseComplete for empty phase
+                this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                    duration: Date.now() - startTime,
+                    endTime: Date.now(),
+                    failureCount: 0,
+                    itemCount: 0,
+                    phaseName: 'story',
+                    startTime,
+                    successCount: 0,
+                });
                 return {
                     duration: Date.now() - startTime,
                     failures: [],
@@ -1420,8 +2142,18 @@ Write output to: ${outputPath}`;
                 if (onStoryComplete) {
                     await this.enqueueExistingStoriesSequentially(allStories, storyDir, prefix, onStoryComplete);
                 }
+                const duration = Date.now() - startTime;
+                this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                    duration,
+                    endTime: Date.now(),
+                    failureCount: 0,
+                    itemCount: allStories.length,
+                    phaseName: 'story',
+                    startTime,
+                    successCount: allStories.length,
+                });
                 return {
-                    duration: Date.now() - startTime,
+                    duration,
                     failures: [],
                     phaseName: 'story',
                     skipped: false,
@@ -1441,107 +2173,161 @@ Write output to: ${outputPath}`;
                 : this.batchProcessor;
             // Create story files using BatchProcessor and ClaudeAgentRunner
             const results = await storyBatchProcessor.processBatch(storiesToCreate, async (story) => {
-                // Generate story file path with prefix
-                const storyFileName = this.generateStoryFileName(prefix, story.fullNumber);
-                const storyFilePath = `${storyDir}/${storyFileName}`;
-                // Check if file already exists (might have been created by parallel process)
-                const fileExists = await this.fileManager.fileExists(storyFilePath);
-                if (fileExists) {
+                const spawnStartTime = Date.now();
+                const spawnId = `story-${story.fullNumber}`;
+                // Fire onSpawnStart so the reporter shows which story is being created
+                this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
+                    agentType: 'sm',
+                    itemId: `story-${story.fullNumber}`,
+                    itemTitle: story.title,
+                    phaseName: 'story',
+                    spawnId,
+                    startTime: spawnStartTime,
+                });
+                try {
+                    // Generate story file path with prefix
+                    const storyFileName = this.generateStoryFileName(prefix, story.fullNumber);
+                    const storyFilePath = `${storyDir}/${storyFileName}`;
+                    // Check if file already exists (might have been created by parallel process)
+                    const fileExists = await this.fileManager.fileExists(storyFilePath);
+                    if (fileExists) {
+                        this.logger.info({
+                            filePath: storyFilePath,
+                            storyNumber: story.fullNumber,
+                            storyTitle: story.title,
+                        }, 'Story file already exists, skipping creation');
+                        this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                            agentType: 'sm',
+                            duration: Date.now() - spawnStartTime,
+                            endTime: Date.now(),
+                            itemId: `story-${story.fullNumber}`,
+                            itemTitle: story.title,
+                            phaseName: 'story',
+                            spawnId,
+                            startTime: spawnStartTime,
+                            success: true,
+                        });
+                        return storyFilePath;
+                    }
+                    // Step 1: Create scaffolded file with structured sections and populated metadata
+                    const scaffoldedContent = this.fileScaffolder.scaffoldStory({
+                        epicNumber: story.epicNumber,
+                        storyNumber: story.number,
+                        storyTitle: story.title,
+                    });
+                    await this.fileManager.writeFile(storyFilePath, scaffoldedContent);
                     this.logger.info({
                         filePath: storyFilePath,
                         storyNumber: story.fullNumber,
                         storyTitle: story.title,
-                    }, 'Story file already exists, skipping creation');
-                    return storyFilePath;
-                }
-                // Step 1: Create scaffolded file with structured sections and populated metadata
-                const scaffoldedContent = this.fileScaffolder.scaffoldStory({
-                    epicNumber: story.epicNumber,
-                    storyNumber: story.number,
-                    storyTitle: story.title,
-                });
-                await this.fileManager.writeFile(storyFilePath, scaffoldedContent);
-                this.logger.info({
-                    filePath: storyFilePath,
-                    storyNumber: story.fullNumber,
-                    storyTitle: story.title,
-                }, 'Story scaffolded file created');
-                // Step 2: Generate epic file path for this story
-                const epicFileName = this.generateEpicFileName(prefix, story.epicNumber);
-                const epicFilePath = `${epicDir}/${epicFileName}`;
-                // Step 3: Build Claude prompt to populate the scaffolded file
-                const prompt = this.buildStoryPrompt(story, {
-                    cwd: config.cwd,
-                    epicPath: epicFilePath,
-                    outputPath: storyFilePath,
-                    prefix,
-                    references: config.references,
-                });
-                // Log prompt if verbose
-                if (config.verbose) {
-                    this.logger.info({
+                    }, 'Story scaffolded file created');
+                    // Step 2: Generate epic file path for this story
+                    const epicFileName = this.generateEpicFileName(prefix, story.epicNumber);
+                    const epicFilePath = `${epicDir}/${epicFileName}`;
+                    // Step 3: Build Claude prompt to populate the scaffolded file
+                    const mcpPrefix = await this.getMcpPromptPrefix('story', 'sm', config);
+                    const basePrompt = this.buildStoryPrompt(story, {
+                        cwd: config.cwd,
+                        epicPath: epicFilePath,
                         outputPath: storyFilePath,
-                        prompt,
-                        storyNumber: story.fullNumber,
-                        storyTitle: story.title,
-                    }, 'Claude Prompt (Story)');
-                }
-                // Step 4: Run Claude agent to populate content sections
-                const result = await runAgentWithRetry(this.agentRunner, prompt, {
-                    agentType: 'sm',
-                    references: config.references,
-                    timeout: config.timeout ?? 2_700_000,
-                }, {
-                    backoffMs: config.retryBackoffMs,
-                    logger: this.logger,
-                    maxRetries: config.maxRetries,
-                });
-                // Log output if verbose
-                if (config.verbose) {
-                    this.logger.info({
-                        duration: result.duration,
-                        errors: result.errors,
-                        output: result.output,
-                        outputLength: result.output.length,
-                        storyNumber: story.fullNumber,
-                        success: result.success,
-                    }, 'Claude Response (Story)');
-                }
-                if (!result.success) {
-                    throw new Error(result.errors);
-                }
-                // Step 5: Verify file was updated by Claude
-                const updatedContent = await this.fileManager.readFile(storyFilePath);
-                if (updatedContent === scaffoldedContent) {
-                    throw new Error(`Claude did not update the story file at ${storyFilePath}`);
-                }
-                // Invoke callback after successful story creation
-                if (onStoryComplete) {
-                    try {
-                        const metadata = {
-                            epicNumber: story.epicNumber,
-                            filePath: storyFilePath,
-                            id: story.fullNumber,
-                            number: story.fullNumber,
-                            status: 'Draft',
-                            storyNumber: story.number,
-                            title: story.title,
-                            type: 'epic-based',
-                        };
-                        this.logger.debug({
-                            metadata,
+                        prefix,
+                        references: config.references,
+                    });
+                    const prompt = mcpPrefix ? `${mcpPrefix}\n\n${basePrompt}` : basePrompt;
+                    // Log prompt if verbose
+                    if (config.verbose) {
+                        this.logger.info({
+                            outputPath: storyFilePath,
+                            prompt,
                             storyNumber: story.fullNumber,
-                        }, 'Invoking story completion callback');
-                        await onStoryComplete(metadata);
+                            storyTitle: story.title,
+                        }, 'Claude Prompt (Story)');
                     }
-                    catch (error) {
-                        this.logger.error({
-                            error: error.message,
+                    // Step 4: Run Claude agent to populate content sections
+                    const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                        agentType: 'sm',
+                        references: config.references,
+                        timeout: config.timeout ?? 2_700_000,
+                    }, {
+                        backoffMs: config.retryBackoffMs,
+                        logger: this.logger,
+                        maxRetries: config.maxRetries,
+                    });
+                    // Log output if verbose
+                    if (config.verbose) {
+                        this.logger.info({
+                            duration: result.duration,
+                            errors: result.errors,
+                            output: result.output,
+                            outputLength: result.output.length,
                             storyNumber: story.fullNumber,
-                        }, 'Story completion callback failed, continuing story creation');
+                            success: result.success,
+                        }, 'Claude Response (Story)');
+                    }
+                    if (!result.success) {
+                        throw new Error(result.errors);
                     }
+                    // Step 5: Verify file was updated by Claude
+                    const updatedContent = await this.fileManager.readFile(storyFilePath);
+                    if (updatedContent === scaffoldedContent) {
+                        throw new Error(`Claude did not update the story file at ${storyFilePath}`);
+                    }
+                    // Invoke callback after successful story creation
+                    if (onStoryComplete) {
+                        try {
+                            const metadata = {
+                                epicNumber: story.epicNumber,
+                                filePath: storyFilePath,
+                                id: story.fullNumber,
+                                number: story.fullNumber,
+                                status: 'Draft',
+                                storyNumber: story.number,
+                                title: story.title,
+                                type: 'epic-based',
+                            };
+                            this.logger.debug({
+                                metadata,
+                                storyNumber: story.fullNumber,
+                            }, 'Invoking story completion callback');
+                            await onStoryComplete(metadata);
+                        }
+                        catch (error) {
+                            this.logger.error({
+                                error: error.message,
+                                storyNumber: story.fullNumber,
+                            }, 'Story completion callback failed, continuing story creation');
+                        }
+                    }
+                    // Fire onSpawnComplete for success
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'sm',
+                        duration: Date.now() - spawnStartTime,
+                        endTime: Date.now(),
+                        itemId: `story-${story.fullNumber}`,
+                        itemTitle: story.title,
+                        phaseName: 'story',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: true,
+                    });
+                    return storyFilePath;
+                }
+                catch (spawnError) {
+                    // Fire onSpawnComplete for failure
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'sm',
+                        duration: Date.now() - spawnStartTime,
+                        endTime: Date.now(),
+                        error: spawnError.message,
+                        itemId: `story-${story.fullNumber}`,
+                        itemTitle: story.title,
+                        phaseName: 'story',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: false,
+                    });
+                    throw spawnError;
                 }
-                return storyFilePath;
             }, (info) => {
                 this.logger.info({
                     completedItems: info.completedItems,
@@ -1565,11 +2351,22 @@ Write output to: ${outputPath}`;
             // Add existing stories to success count
             successCount += existingStories.length;
             const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.info({
                 duration,
                 failures: failures.length,
                 success: successCount,
             }, 'Story creation phase completed');
+            // Invoke onPhaseComplete callback
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length,
+                itemCount,
+                phaseName: 'story',
+                startTime,
+                successCount,
+            });
             return {
                 duration,
                 failures,
@@ -1579,9 +2376,28 @@ Write output to: ${outputPath}`;
             };
         }
         catch (error) {
+            const duration = Date.now() - startTime;
+            const endTime = Date.now();
             this.logger.error({ error: error.message }, 'Story phase failed');
+            // Invoke onError callback
+            this.invokeErrorCallback(error, {
+                itemId: 'story-phase',
+                phaseName: 'story',
+                recoverable: false,
+            });
+            // Invoke onPhaseComplete callback even on error
+            this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                duration,
+                endTime,
+                failureCount: failures.length + 1,
+                itemCount,
+                metadata: { error: error.message },
+                phaseName: 'story',
+                startTime,
+                successCount,
+            });
             return {
-                duration: Date.now() - startTime,
+                duration,
                 failures: [
                     ...failures,
                     {
@@ -1613,7 +2429,7 @@ Write output to: ${outputPath}`;
         // In pipeline mode, stories must be created sequentially (one at a time)
         // to ensure they are queued in the correct order for development
         const isPipelineMode = Boolean(onStoryComplete);
-        const effectiveParallel = isPipelineMode ? 1 : config.parallel;
+        const effectiveParallel = config.parallel;
         this.logger.info({
             epicFilePath,
             mode: isPipelineMode ? 'sequential (pipeline)' : 'parallel',
@@ -1652,8 +2468,18 @@ Write output to: ${outputPath}`;
                 if (onStoryComplete) {
                     await this.enqueueExistingStoriesSequentially(allStories, storyDir, prefix, onStoryComplete);
                 }
+                const duration = Date.now() - startTime;
+                this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
+                    duration,
+                    endTime: Date.now(),
+                    failureCount: 0,
+                    itemCount: allStories.length,
+                    phaseName: 'story',
+                    startTime,
+                    successCount: allStories.length,
+                });
                 return {
-                    duration: Date.now() - startTime,
+                    duration,
                     failures: [],
                     phaseName: 'story',
                     skipped: false,
@@ -1673,106 +2499,160 @@ Write output to: ${outputPath}`;
                 : this.batchProcessor;
             // Create story files using BatchProcessor and ClaudeAgentRunner
             const results = await storyBatchProcessor.processBatch(storiesToCreate, async (story) => {
-                // Generate story file path with prefix
-                const storyFileName = this.generateStoryFileName(prefix, story.fullNumber);
-                const storyFilePath = `${storyDir}/${storyFileName}`;
-                // Check if file already exists (might have been created by parallel process)
-                const fileExists = await this.fileManager.fileExists(storyFilePath);
-                if (fileExists) {
+                const spawnStartTime = Date.now();
+                const spawnId = `story-${story.fullNumber}`;
+                // Fire onSpawnStart so the reporter shows which story is being created
+                this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
+                    agentType: 'sm',
+                    itemId: `story-${story.fullNumber}`,
+                    itemTitle: story.title,
+                    phaseName: 'story',
+                    spawnId,
+                    startTime: spawnStartTime,
+                });
+                try {
+                    // Generate story file path with prefix
+                    const storyFileName = this.generateStoryFileName(prefix, story.fullNumber);
+                    const storyFilePath = `${storyDir}/${storyFileName}`;
+                    // Check if file already exists (might have been created by parallel process)
+                    const fileExists = await this.fileManager.fileExists(storyFilePath);
+                    if (fileExists) {
+                        this.logger.info({
+                            filePath: storyFilePath,
+                            storyNumber: story.fullNumber,
+                            storyTitle: story.title,
+                        }, 'Story file already exists, skipping creation');
+                        this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                            agentType: 'sm',
+                            duration: Date.now() - spawnStartTime,
+                            endTime: Date.now(),
+                            itemId: `story-${story.fullNumber}`,
+                            itemTitle: story.title,
+                            phaseName: 'story',
+                            spawnId,
+                            startTime: spawnStartTime,
+                            success: true,
+                        });
+                        return storyFilePath;
+                    }
+                    // Step 1: Create scaffolded file with structured sections and populated metadata
+                    const scaffoldedContent = this.fileScaffolder.scaffoldStory({
+                        epicNumber: story.epicNumber,
+                        storyNumber: story.number,
+                        storyTitle: story.title,
+                    });
+                    await this.fileManager.writeFile(storyFilePath, scaffoldedContent);
                     this.logger.info({
                         filePath: storyFilePath,
                         storyNumber: story.fullNumber,
                         storyTitle: story.title,
-                    }, 'Story file already exists, skipping creation');
-                    return storyFilePath;
-                }
-                // Step 1: Create scaffolded file with structured sections and populated metadata
-                const scaffoldedContent = this.fileScaffolder.scaffoldStory({
-                    epicNumber: story.epicNumber,
-                    storyNumber: story.number,
-                    storyTitle: story.title,
-                });
-                await this.fileManager.writeFile(storyFilePath, scaffoldedContent);
-                this.logger.info({
-                    filePath: storyFilePath,
-                    storyNumber: story.fullNumber,
-                    storyTitle: story.title,
-                }, 'Story scaffolded file created');
-                // Step 2: Use the epic file path that was passed to this method
-                // Step 3: Build Claude prompt to populate the scaffolded file
-                const prompt = this.buildStoryPrompt(story, {
-                    cwd: config.cwd,
-                    epicPath: epicFilePath,
-                    outputPath: storyFilePath,
-                    prefix,
-                    references: config.references,
-                });
-                // Log prompt if verbose
-                if (config.verbose) {
-                    this.logger.info({
+                    }, 'Story scaffolded file created');
+                    // Step 2: Use the epic file path that was passed to this method
+                    // Step 3: Build Claude prompt to populate the scaffolded file
+                    const mcpPrefix = await this.getMcpPromptPrefix('story', 'sm', config);
+                    const basePrompt = this.buildStoryPrompt(story, {
+                        cwd: config.cwd,
                         epicPath: epicFilePath,
                         outputPath: storyFilePath,
-                        prompt,
-                        storyNumber: story.fullNumber,
-                        storyTitle: story.title,
-                    }, 'Claude Prompt (Story)');
-                }
-                // Step 4: Run Claude agent to populate content sections
-                const result = await runAgentWithRetry(this.agentRunner, prompt, {
-                    agentType: 'sm',
-                    references: config.references,
-                    timeout: config.timeout ?? 2_700_000,
-                }, {
-                    backoffMs: config.retryBackoffMs,
-                    logger: this.logger,
-                    maxRetries: config.maxRetries,
-                });
-                // Log output if verbose
-                if (config.verbose) {
-                    this.logger.info({
-                        duration: result.duration,
-                        errors: result.errors,
-                        output: result.output,
-                        outputLength: result.output.length,
-                        storyNumber: story.fullNumber,
-                        success: result.success,
-                    }, 'Claude Response (Story)');
-                }
-                if (!result.success) {
-                    throw new Error(result.errors);
-                }
-                // Step 5: Verify file was updated by Claude
-                const updatedContent = await this.fileManager.readFile(storyFilePath);
-                if (updatedContent === scaffoldedContent) {
-                    throw new Error(`Claude did not update the story file at ${storyFilePath}`);
-                }
-                // Invoke callback after successful story creation
-                if (onStoryComplete) {
-                    try {
-                        const metadata = {
-                            epicNumber: story.epicNumber,
-                            filePath: storyFilePath,
-                            id: story.fullNumber,
-                            number: story.fullNumber,
-                            status: 'Draft',
-                            storyNumber: story.number,
-                            title: story.title,
-                            type: 'epic-based',
-                        };
-                        this.logger.debug({
-                            metadata,
+                        prefix,
+                        references: config.references,
+                    });
+                    const prompt = mcpPrefix ? `${mcpPrefix}\n\n${basePrompt}` : basePrompt;
+                    // Log prompt if verbose
+                    if (config.verbose) {
+                        this.logger.info({
+                            epicPath: epicFilePath,
+                            outputPath: storyFilePath,
+                            prompt,
                             storyNumber: story.fullNumber,
-                        }, 'Invoking story completion callback');
-                        await onStoryComplete(metadata);
+                            storyTitle: story.title,
+                        }, 'Claude Prompt (Story)');
                     }
-                    catch (error) {
-                        this.logger.error({
-                            error: error.message,
+                    // Step 4: Run Claude agent to populate content sections
+                    const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                        agentType: 'sm',
+                        references: config.references,
+                        timeout: config.timeout ?? 2_700_000,
+                    }, {
+                        backoffMs: config.retryBackoffMs,
+                        logger: this.logger,
+                        maxRetries: config.maxRetries,
+                    });
+                    // Log output if verbose
+                    if (config.verbose) {
+                        this.logger.info({
+                            duration: result.duration,
+                            errors: result.errors,
+                            output: result.output,
+                            outputLength: result.output.length,
                             storyNumber: story.fullNumber,
-                        }, 'Story completion callback failed, continuing story creation');
+                            success: result.success,
+                        }, 'Claude Response (Story)');
+                    }
+                    if (!result.success) {
+                        throw new Error(result.errors);
+                    }
+                    // Step 5: Verify file was updated by Claude
+                    const updatedContent = await this.fileManager.readFile(storyFilePath);
+                    if (updatedContent === scaffoldedContent) {
+                        throw new Error(`Claude did not update the story file at ${storyFilePath}`);
                     }
+                    // Invoke callback after successful story creation
+                    if (onStoryComplete) {
+                        try {
+                            const metadata = {
+                                epicNumber: story.epicNumber,
+                                filePath: storyFilePath,
+                                id: story.fullNumber,
+                                number: story.fullNumber,
+                                status: 'Draft',
+                                storyNumber: story.number,
+                                title: story.title,
+                                type: 'epic-based',
+                            };
+                            this.logger.debug({
+                                metadata,
+                                storyNumber: story.fullNumber,
+                            }, 'Invoking story completion callback');
+                            await onStoryComplete(metadata);
+                        }
+                        catch (error) {
+                            this.logger.error({
+                                error: error.message,
+                                storyNumber: story.fullNumber,
+                            }, 'Story completion callback failed, continuing story creation');
+                        }
+                    }
+                    // Fire onSpawnComplete for success
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'sm',
+                        duration: Date.now() - spawnStartTime,
+                        endTime: Date.now(),
+                        itemId: `story-${story.fullNumber}`,
+                        itemTitle: story.title,
+                        phaseName: 'story',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: true,
+                    });
+                    return storyFilePath;
+                }
+                catch (spawnError) {
+                    // Fire onSpawnComplete for failure
+                    this.invokeCallback('onSpawnComplete', this.callbacks?.onSpawnComplete, {
+                        agentType: 'sm',
+                        duration: Date.now() - spawnStartTime,
+                        endTime: Date.now(),
+                        error: spawnError.message,
+                        itemId: `story-${story.fullNumber}`,
+                        itemTitle: story.title,
+                        phaseName: 'story',
+                        spawnId,
+                        startTime: spawnStartTime,
+                        success: false,
+                    });
+                    throw spawnError;
                 }
-                return storyFilePath;
             }, (info) => {
                 this.logger.info({
                     completedItems: info.completedItems,