@hyperdrive.bot/bmad-workflow 1.0.18 → 1.0.19

package/dist/services/orchestration/workflow-orchestrator.d.ts

@@ -53,6 +53,8 @@ import { EpicParser } from '../parsers/epic-parser.js';
 import { PrdParser } from '../parsers/prd-parser.js';
 import { BatchProcessor } from './batch-processor.js';
 import { StoryTypeDetector } from './story-type-detector.js';
+import type { McpContextInjector } from '../mcp/mcp-context-injector.js';
+import type { ReviewPhaseExecutor } from '../review/review-phase-executor.js';
 /**
  * InputDetector interface (to be implemented in Story 4.2)
  *
@@ -87,10 +89,14 @@ export interface WorkflowOrchestratorConfig {
     inputDetector: InputDetector;
     /** Logger instance for structured logging */
     logger: pino.Logger;
+    /** Optional MCP context injector for tool discovery in agent prompts */
+    mcpContextInjector?: McpContextInjector;
     /** Service to resolve file paths from config */
     pathResolver: PathResolver;
     /** Service to parse PRD files and extract epics */
     prdParser: PrdParser;
+    /** Optional ReviewPhaseExecutor for automated code review */
+    reviewPhaseExecutor?: ReviewPhaseExecutor;
     /** Service to detect story type for auto-documentation */
     storyTypeDetector: StoryTypeDetector;
     /** Optional WorkflowLogger for pipeline progress tracking */
@@ -144,9 +150,11 @@ export declare class WorkflowOrchestrator {
     private readonly fileScaffolder;
     private readonly inputDetector;
     private readonly logger;
+    private readonly mcpContextInjector?;
     private readonly pathResolver;
     private readonly prdFixer;
     private readonly prdParser;
+    private readonly reviewPhaseExecutor?;
     private readonly storyTypeDetector;
     private readonly workflowLogger?;
     /**
@@ -166,6 +174,20 @@ export declare class WorkflowOrchestrator {
      * @throws {ValidationError} If configuration is invalid
      */
     execute(config: WorkflowConfig): Promise<WorkflowResult>;
+    /**
+     * 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
+     */
+    private getMcpPromptPrefix;
     /**
      * Build prompt for epic creation
      *
@@ -411,11 +433,41 @@ export declare class WorkflowOrchestrator {
      */
     private executePipelinedDevPhase;
     /**
-     * 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
+     */
+    private reviewWorker;
+    /**
+     * 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
+     */
+    private executePipelinedReviewPhase;
+    /**
+     * 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
      */
     private executePipelinedWorkflow;

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
  *
@@ -66,9 +67,11 @@ export class WorkflowOrchestrator {
     fileScaffolder;
     inputDetector;
     logger;
+    mcpContextInjector;
     pathResolver;
     prdFixer;
     prdParser;
+    reviewPhaseExecutor;
     storyTypeDetector;
     workflowLogger;
     /**
@@ -83,7 +86,9 @@ 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;
@@ -113,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
@@ -199,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,
@@ -218,6 +263,7 @@ Write output to: ${outputPath}`;
             epicPhase,
             overallSuccess,
             qaPhase,
+            reviewPhase,
             storyPhase,
             totalDuration,
             totalFailures,
@@ -452,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,
         };
     }
@@ -493,7 +541,7 @@ 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 = [];
@@ -574,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`;
@@ -636,6 +686,11 @@ Write output to: ${outputPath}`;
                         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;
@@ -842,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`;
@@ -1177,13 +1234,15 @@ Write output to: ${outputPath}`;
                         }, 'Epic scaffolded file created');
                     }
                     // Step 2: Build Claude prompt to populate the scaffolded file
-                    const prompt = this.buildEpicPrompt(epic, {
+                    const mcpPrefix = await this.getMcpPromptPrefix('epic', 'architect', config);
+                    const basePrompt = this.buildEpicPrompt(epic, {
                         cwd: config.cwd,
                         outputPath: epicFilePath,
                         prdPath: prdFilePath,
                         prefix,
                         references: config.references,
                     });
+                    const prompt = mcpPrefix ? `${mcpPrefix}\n\n${basePrompt}` : basePrompt;
                     // Log prompt if verbose
                     if (config.verbose) {
                         this.logger.info({
@@ -1389,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
@@ -1397,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 = [];
@@ -1437,6 +1502,11 @@ 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(),
@@ -1461,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'),
@@ -1567,6 +1805,13 @@ Write output to: ${outputPath}`;
                             qaFlags.push(`--reference=${ref}`);
                         }
                     }
+                    // 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) {
@@ -1740,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 };
     }
     /**
@@ -1943,13 +2225,15 @@ Write output to: ${outputPath}`;
                     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, {
+                    const mcpPrefix = await this.getMcpPromptPrefix('story', 'sm', config);
+                    const basePrompt = this.buildStoryPrompt(story, {
                         cwd: config.cwd,
                         epicPath: epicFilePath,
                         outputPath: storyFilePath,
                         prefix,
                         references: config.references,
                     });
+                    const prompt = mcpPrefix ? `${mcpPrefix}\n\n${basePrompt}` : basePrompt;
                     // Log prompt if verbose
                     if (config.verbose) {
                         this.logger.info({
@@ -2265,13 +2549,15 @@ Write output to: ${outputPath}`;
                     }, '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, {
+                    const mcpPrefix = await this.getMcpPromptPrefix('story', 'sm', config);
+                    const basePrompt = this.buildStoryPrompt(story, {
                         cwd: config.cwd,
                         epicPath: epicFilePath,
                         outputPath: storyFilePath,
                         prefix,
                         references: config.references,
                     });
+                    const prompt = mcpPrefix ? `${mcpPrefix}\n\n${basePrompt}` : basePrompt;
                     // Log prompt if verbose
                     if (config.verbose) {
                         this.logger.info({

package/dist/services/review/ai-review-scanner.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AI Review Scanner
+ *
+ * Spawns a QA agent to perform structured code review on story implementations.
+ * Produces RawReviewOutput with source 'ai' for downstream SeverityClassifier parsing.
+ *
+ * Prompt enforces strict output format: SEVERITY/FILE/LINE/ISSUE/FIX blocks
+ * separated by `---`, or `REVIEW_PASS: No issues found` sentinel for clean reviews.
+ */
+import type pino from 'pino';
+import type { AIProviderRunner } from '../agents/agent-runner.js';
+import type { RawReviewOutput, ReviewContext, ReviewScanner } from './types.js';
+/** Path-specific review rule loaded from core-config.yaml */
+export interface PathRule {
+    /** Review focus areas for files matching this pattern */
+    focus: string[];
+    /** Glob pattern to match against changed files */
+    pattern: string;
+}
+/** Review configuration — subset of core-config relevant to AI review */
+export interface ReviewConfig {
+    /** Set to false to disable AI review scanner */
+    aiReview?: boolean;
+    /** Set to true to enable CodeRabbit scanner (requires CLI installed) */
+    coderabbit?: boolean;
+    /** Path-specific review rules */
+    pathRules?: PathRule[];
+}
+/**
+ * AIReviewScanner — spawns a QA agent and parses structured review output.
+ *
+ * Implements ReviewScanner interface. Uses composition over inheritance —
+ * composes AIProviderRunner, doesn't extend it.
+ */
+export declare class AIReviewScanner implements ReviewScanner {
+    private readonly agentRunner;
+    private readonly config;
+    private readonly logger;
+    private readonly timeout;
+    constructor(agentRunner: AIProviderRunner, config: ReviewConfig, logger: pino.Logger, timeout?: number);
+    /**
+     * Scan the given context by spawning a QA agent for AI-powered code review
+     *
+     * @param context - Review context describing what to scan
+     * @returns Raw output from the AI agent with source 'ai'
+     */
+    scan(context: ReviewContext): Promise<RawReviewOutput>;
+    /**
+     * Build the review prompt with severity definitions, output format spec,
+     * changed files, and path-specific rules.
+     */
+    private buildReviewPrompt;
+    /**
+     * Get path rules that match any of the changed files
+     */
+    private getMatchingPathRules;
+    /**
+     * Parse agent output into RawReviewOutput
+     *
+     * Handles three cases:
+     * 1. REVIEW_PASS sentinel → clean result
+     * 2. Structured output → pass raw text for SeverityClassifier
+     * 3. Malformed/empty output → graceful fallback
+     */
+    private parseAgentOutput;
+}