@hyperdrive.bot/bmad-workflow 1.0.2

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

@@ -0,0 +1,2201 @@
+/**
+ * WorkflowOrchestrator Service
+ *
+ * Coordinates the complete PRD → Epic → Story → Dev workflow with automatic
+ * input detection, conditional phase execution, and comprehensive result tracking.
+ *
+ * Responsibilities:
+ * - Detect input type (PRD, epic, or story pattern)
+ * - Execute phases conditionally based on skip flags and input type
+ * - Coordinate between PrdParser, EpicParser, and ClaudeAgentRunner
+ * - Track phase results with success/failure counts and durations
+ * - Handle cross-phase errors gracefully (fail early if critical phase fails)
+ * - Aggregate results across all phases into WorkflowResult
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'orchestrator' })
+ * const orchestrator = new WorkflowOrchestrator({
+ *   inputDetector,
+ *   prdParser,
+ *   epicParser,
+ *   agentRunner: claudeRunner,
+ *   batchProcessor,
+ *   fileManager,
+ *   pathResolver,
+ *   storyTypeDetector,
+ *   logger,
+ * })
+ *
+ * const result = await orchestrator.execute({
+ *   input: 'docs/PRD-feature.md',
+ *   prdInterval: 60,
+ *   epicInterval: 60,
+ *   storyInterval: 60,
+ *   parallel: 3,
+ *   prefix: 'PROJ-123',
+ *   references: [],
+ *   skipEpics: false,
+ *   skipStories: false,
+ *   skipDev: false,
+ *   dryRun: false,
+ *   verbose: false
+ * })
+ * ```
+ */
+import { isEpicStory } from '../../models/story.js';
+import { ParserError, ValidationError } from '../../utils/errors.js';
+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';
+/**
+ * WorkflowOrchestrator service for coordinating multi-phase workflows
+ *
+ * Orchestrates the complete workflow from PRD to development, executing
+ * phases conditionally based on input type and skip flags. Tracks results
+ * and handles cross-phase errors gracefully.
+ */
+export class WorkflowOrchestrator {
+    agentRunner;
+    batchProcessor;
+    epicParser;
+    fileManager;
+    fileScaffolder;
+    inputDetector;
+    logger;
+    pathResolver;
+    prdFixer;
+    prdParser;
+    storyTypeDetector;
+    workflowLogger;
+    /**
+     * Create a new WorkflowOrchestrator instance
+     *
+     * @param config - Configuration object containing all service dependencies
+     */
+    constructor(config) {
+        this.inputDetector = config.inputDetector;
+        this.prdParser = config.prdParser;
+        this.epicParser = config.epicParser;
+        this.agentRunner = config.agentRunner;
+        this.batchProcessor = config.batchProcessor;
+        this.fileManager = config.fileManager;
+        this.pathResolver = config.pathResolver;
+        this.storyTypeDetector = config.storyTypeDetector;
+        this.logger = config.logger;
+        this.workflowLogger = config.workflowLogger;
+        this.fileScaffolder = new FileScaffolder(config.logger);
+        this.prdFixer = new PrdFixer(config.agentRunner, config.fileManager, config.logger);
+        this.logger.debug('WorkflowOrchestrator initialized');
+    }
+    /**
+     * Execute the complete workflow
+     *
+     * Detects input type, executes phases conditionally based on skip flags
+     * and input type, tracks results, and handles cross-phase errors.
+     *
+     * @param config - Workflow configuration
+     * @returns WorkflowResult with all phase results and aggregate metrics
+     * @throws {ValidationError} If configuration is invalid
+     */
+    async execute(config) {
+        const startTime = Date.now();
+        this.logWorkflowStart(config);
+        this.validateConfig(config);
+        const detection = await this.detectInput(config.input);
+        const phaseFlags = this.determinePhaseExecution(detection, config);
+        const epicPhase = await this.executeEpicPhaseIfNeeded(config, detection, phaseFlags.shouldExecuteEpicPhase);
+        // Early return if epic phase failed completely
+        if (this.shouldAbortAfterEpicFailure(epicPhase)) {
+            return this.buildFailureResult(startTime, epicPhase);
+        }
+        const { devPhase, storyPhase } = await this.executeStoryAndDevPhases(config, detection, epicPhase, phaseFlags, startTime);
+        const qaPhase = await this.executeQaPhaseIfNeeded(config, devPhase, phaseFlags.shouldExecuteQaPhase);
+        return this.buildSuccessResult(startTime, epicPhase, storyPhase, devPhase, qaPhase);
+    }
+    /**
+     * Build prompt for epic creation
+     *
+     * @param epic - Epic to create
+     * @param options - Prompt configuration options
+     * @returns Agent prompt
+     * @private
+     */
+    buildEpicPrompt(epic, options) {
+        const { cwd, outputPath, prdPath, references } = options;
+        const referencesText = references.length > 0 ? `\nReferences: ${references.join(', ')}` : '';
+        const cwdText = cwd ? `\n\nWorking directory: ${cwd}` : '';
+        return `@.bmad-core/agents/sm.md${cwdText}
+
+Create epic '${epic.number}: ${epic.title}' for PRD '${prdPath}'.${referencesText}.
+
+IMPORTANT: The file at '${outputPath}' has been pre-scaffolded with structure and metadata.
+- DO NOT modify the Epic Header section (Epic ID, Status: Draft, Created date are already set)
+- DO NOT change the document structure or section headers
+- ONLY populate the empty content sections marked with [AI Agent will populate]
+- Follow the template structure at @.bmad-core/templates/epic-tmpl.yaml for content guidance
+
+Write output to: '${outputPath}'`;
+    }
+    /**
+     * Build failure result when epic phase fails completely
+     *
+     * @param startTime - Workflow start time
+     * @param epicPhase - Failed epic phase result
+     * @returns WorkflowResult
+     * @private
+     */
+    buildFailureResult(startTime, epicPhase) {
+        this.logger.error('Epic phase failed completely, skipping downstream phases');
+        const totalDuration = Date.now() - startTime;
+        return {
+            devPhase: this.createSkippedPhaseResult('dev'),
+            epicPhase,
+            overallSuccess: false,
+            qaPhase: this.createSkippedPhaseResult('qa'),
+            storyPhase: this.createSkippedPhaseResult('story'),
+            totalDuration,
+            totalFailures: epicPhase.failures.length,
+            totalFilesProcessed: 0,
+        };
+    }
+    /**
+     * Build prompt for story creation
+     *
+     * @param story - Story to create
+     * @param options - Prompt configuration options
+     * @returns Agent prompt
+     * @private
+     */
+    buildStoryPrompt(story, options) {
+        const { cwd, epicPath, outputPath, references } = options;
+        const referencesText = references.length > 0 ? `\nReferences: ${references.join(', ')}` : '';
+        const cwdText = cwd ? `\n\nWorking directory: ${cwd}` : '';
+        return `@.bmad-core/agents/sm.md${cwdText}
+
+Create story '${story.fullNumber}: ${story.title}' for epic '${epicPath}'. ${referencesText}
+
+IMPORTANT: The file at '${outputPath}' has been pre-scaffolded with structure and metadata.
+- DO NOT modify the Status section (already set to Draft)
+- DO NOT modify the Created date in Change Log
+- DO NOT change the document structure or section headers
+- ONLY populate the empty content sections marked with [AI Agent will populate]
+- Follow the template structure at @.bmad-core/templates/story-tmpl.yaml for content guidance
+
+Write output to: ${outputPath}`;
+    }
+    /**
+     * Build success result with all phase results
+     *
+     * @param startTime - Workflow start time
+     * @param epicPhase - Epic phase result
+     * @param storyPhase - Story phase result
+     * @param devPhase - Dev phase result
+     * @param qaPhase - QA phase result
+     * @returns WorkflowResult
+     * @private
+     */
+    buildSuccessResult(startTime, epicPhase, storyPhase, devPhase, qaPhase) {
+        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);
+        const overallSuccess = totalFailures === 0;
+        this.logger.info({
+            overallSuccess,
+            totalDuration,
+            totalFailures,
+            totalFilesProcessed,
+        }, 'Workflow execution completed');
+        return {
+            devPhase,
+            epicPhase,
+            overallSuccess,
+            qaPhase,
+            storyPhase,
+            totalDuration,
+            totalFailures,
+            totalFilesProcessed,
+        };
+    }
+    /**
+     * Check which files already exist in a directory
+     *
+     * @param directory - Directory to check
+     * @param fileNames - List of file names to check
+     * @returns List of existing file names
+     * @private
+     */
+    async checkExistingFiles(directory, fileNames) {
+        // Parallelize file existence checks for better performance
+        const existenceChecks = await Promise.all(fileNames.map(async (fileName) => {
+            const filePath = `${directory}/${fileName}`;
+            const exists = await this.fileManager.fileExists(filePath);
+            return { exists, fileName };
+        }));
+        // Filter to only existing files
+        return existenceChecks.filter((result) => result.exists).map((result) => result.fileName);
+    }
+    /**
+     * Check which story files already exist across all story directories
+     *
+     * Checks docs/stories, docs/qa/stories, and docs/done/stories to prevent
+     * recreating stories that have been moved for QA or marked as done.
+     *
+     * Stories found in docs/qa/stories or docs/done/stories are considered completed
+     * and are skipped, allowing the workflow to continue with the next story number
+     * in docs/stories.
+     *
+     * @param fileNames - List of story file names to check
+     * @returns List of existing file names that should be skipped
+     * @private
+     */
+    async checkExistingStoryFiles(fileNames) {
+        const allStoryDirs = this.pathResolver.getAllStoryDirs();
+        const storyDir = this.pathResolver.getStoryDir();
+        // Parallelize story file existence checks across all directories
+        const existenceChecks = await Promise.all(fileNames.map(async (fileName) => {
+            // Check all directories in parallel for this file
+            const dirChecks = await Promise.all(allStoryDirs.map(async (dir) => {
+                const filePath = `${dir}/${fileName}`;
+                const exists = await this.fileManager.fileExists(filePath);
+                return { dir, exists, filePath };
+            }));
+            // Find first directory where file exists
+            const foundIn = dirChecks.find((check) => check.exists);
+            if (foundIn) {
+                // Determine if story is in active development or completed
+                const isInActiveDevelopment = foundIn.dir === storyDir;
+                const status = isInActiveDevelopment ? 'in active development' : 'completed (in QA/done)';
+                this.logger.info({ directory: foundIn.dir, fileName, filePath: foundIn.filePath, status }, `Story file already exists - ${status}`);
+                return { exists: true, fileName };
+            }
+            return { exists: false, fileName };
+        }));
+        // Filter to only existing files
+        return existenceChecks.filter((result) => result.exists).map((result) => result.fileName);
+    }
+    /**
+     * Check if epic files are properly populated (not just scaffolded)
+     *
+     * @param directory - Directory containing epic files
+     * @param fileNames - List of file names to check
+     * @returns List of properly populated file names
+     * @private
+     */
+    async checkProperlyPopulatedEpics(directory, fileNames) {
+        // Parallelize epic file checks for better performance
+        const populationChecks = await Promise.all(fileNames.map(async (fileName) => {
+            const filePath = `${directory}/${fileName}`;
+            const exists = await this.fileManager.fileExists(filePath);
+            if (exists) {
+                // Check if file is properly populated (doesn't contain placeholder text)
+                const content = await this.fileManager.readFile(filePath);
+                const isScaffolded = content.includes('_[AI Agent will populate');
+                if (isScaffolded) {
+                    this.logger.warn({
+                        fileName,
+                        filePath,
+                    }, 'Epic file exists but is only scaffolded (will be re-populated)');
+                    return { fileName, properlyPopulated: false };
+                }
+                return { fileName, properlyPopulated: true };
+            }
+            return { fileName, properlyPopulated: false };
+        }));
+        // Filter to only properly populated files
+        return populationChecks.filter((result) => result.properlyPopulated).map((result) => result.fileName);
+    }
+    /**
+     * Create a skipped phase result
+     *
+     * @param phaseName - Name of the phase
+     * @returns PhaseResult marked as skipped
+     * @private
+     */
+    createSkippedPhaseResult(phaseName) {
+        return {
+            duration: 0,
+            failures: [],
+            phaseName,
+            skipped: true,
+            success: 0,
+        };
+    }
+    /**
+     * Detect input type using InputDetector
+     *
+     * @param input - Input file path or pattern
+     * @returns Input detection result
+     * @throws {ValidationError} If input is invalid or cannot be detected
+     * @private
+     */
+    async detectInput(input) {
+        this.logger.info({ input }, 'Detecting input type');
+        try {
+            const result = await this.inputDetector.detect(input);
+            this.logger.info({
+                filePath: result.filePath,
+                inputType: result.type,
+                metadata: result.metadata,
+            }, 'Input detected successfully');
+            return result;
+        }
+        catch (error) {
+            this.logger.error({ error: error.message, input }, 'Failed to detect input type');
+            throw new ValidationError(`Failed to detect input type: ${error.message}`, {
+                input,
+                originalError: error.message,
+            });
+        }
+    }
+    /**
+     * Determine which phases should execute based on input type and skip flags
+     *
+     * @param detection - Input detection result
+     * @param config - Workflow configuration
+     * @returns Object with boolean flags for each phase
+     * @private
+     */
+    determinePhaseExecution(detection, config) {
+        const shouldExecuteEpicPhase = detection.type === 'prd' && !config.skipEpics;
+        const shouldExecuteStoryPhase = !config.skipStories && detection.type !== 'story-pattern';
+        const shouldExecuteDevPhase = !config.skipDev;
+        const shouldExecuteQaPhase = config.qa === true && shouldExecuteDevPhase;
+        return {
+            shouldExecuteDevPhase,
+            shouldExecuteEpicPhase,
+            shouldExecuteQaPhase,
+            shouldExecuteStoryPhase,
+        };
+    }
+    /**
+     * Individual worker function for processing stories from the queue
+     *
+     * Continuously dequeues stories and processes them until the queue is closed and empty.
+     * Handles errors gracefully without crashing the worker pool.
+     *
+     * @param workerId - Unique identifier for this worker (for logging)
+     * @param queue - StoryQueue to dequeue stories from
+     * @param config - Workflow configuration
+     * @returns Worker result with success count and failures
+     * @private
+     */
+    /**
+     * Dev worker that consumes stories from the queue and processes them concurrently.
+     *
+     * Worker loop algorithm:
+     * 1. Dequeue next story (blocks/waits if queue empty)
+     * 2. If null returned, queue is closed and empty → terminate worker
+     * 3. For each story:
+     *    - Check if already in QA folder (skip if developed)
+     *    - Update story status to InProgress
+     *    - Execute dev agent with context
+     *    - On success: Update status to Done, move to QA
+     *    - On failure: Log error, continue to next story
+     *    - Respect story interval delay
+     * 4. Return aggregate success count and failures
+     *
+     * @param workerId - Worker identifier for logging and tracking (0-based index)
+     * @param queue - StoryQueue to dequeue stories from
+     * @param config - Workflow configuration with intervals and references
+     * @returns Promise resolving to object with success count and failure array
+     * @private
+     */
+    async devWorker(workerId, queue, config) {
+        const workerLogger = this.logger.child({ workerId });
+        let successCount = 0;
+        const failures = [];
+        workerLogger.info('Worker started');
+        try {
+            const storyDir = await this.pathResolver.getStoryDir();
+            const qaStoryDir = await this.pathResolver.getQaStoryDir();
+            while (true) {
+                // Dequeue next story (waits if queue is empty)
+                const story = await queue.dequeue();
+                // Queue closed and empty - terminate worker
+                if (!story) {
+                    workerLogger.info('Queue closed and empty, worker terminating');
+                    break;
+                }
+                workerLogger.info({
+                    storyNumber: story.fullNumber,
+                    storyTitle: story.title,
+                }, 'Worker processing story');
+                try {
+                    // Use the actual file path from the story object
+                    const storyFilePath = story.filePath || `${storyDir}/STORY-${story.fullNumber}.md`;
+                    // Extract just the filename for QA folder (preserve the same filename)
+                    const storyFileName = storyFilePath.split('/').pop() || `STORY-${story.fullNumber}.md`;
+                    const qaFilePath = `${qaStoryDir}/${storyFileName}`;
+                    // Check if story is already in QA folder (already developed)
+                    const alreadyInQa = await this.fileManager.fileExists(qaFilePath);
+                    if (alreadyInQa) {
+                        workerLogger.info({
+                            qaFilePath,
+                            storyNumber: story.fullNumber,
+                        }, 'Story already in QA folder, skipping development');
+                        successCount++;
+                        continue;
+                    }
+                    const storyExists = await this.fileManager.fileExists(storyFilePath);
+                    if (!storyExists) {
+                        workerLogger.warn({ storyNumber: story.fullNumber }, `Story file not found ${storyFilePath}, skipping`);
+                        failures.push({
+                            error: 'Story file not found',
+                            identifier: story.fullNumber,
+                        });
+                        continue;
+                    }
+                    // Update story status to InProgress
+                    await this.updateStoryStatus(storyFilePath, 'InProgress');
+                    // Log story developing in pipeline mode
+                    const storyStartTime = Date.now();
+                    if (this.workflowLogger) {
+                        await this.workflowLogger.logStoryDeveloping(story.fullNumber, workerId);
+                        // Log verbose transition if enabled
+                        if (config.verbose) {
+                            this.workflowLogger.logVerboseTransition(story.fullNumber, story.title, 'DEVELOPING', {
+                                workerId,
+                            });
+                        }
+                    }
+                    // Read story content for type detection
+                    const storyContent = await this.fileManager.readFile(storyFilePath);
+                    // Detect story type and get auto-documentation references
+                    const detection = this.storyTypeDetector.detectStoryType(storyContent);
+                    const autoReferences = this.storyTypeDetector.getDocumentationReferences(detection.type);
+                    workerLogger.info({
+                        autoReferencesCount: autoReferences.length,
+                        confidence: detection.confidence,
+                        storyNumber: story.fullNumber,
+                        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`;
+                    // Add working directory instruction if specified
+                    if (config.cwd) {
+                        prompt += `Working directory: ${config.cwd}\n\n`;
+                    }
+                    prompt += `*develop-story ${storyFilePath}\n\n`;
+                    // Combine auto-detected references with user-provided references
+                    const allReferences = [...autoReferences, ...(config.references || [])];
+                    if (allReferences.length > 0) {
+                        prompt += 'References:\n';
+                        for (const ref of allReferences) {
+                            prompt += `@${ref}\n`;
+                        }
+                        prompt += '\n';
+                    }
+                    prompt += '*yolo mode*\n';
+                    // Execute dev agent
+                    const result = await this.agentRunner.runAgent(prompt, {
+                        agentType: 'dev',
+                        references: config.references,
+                        timeout: 1_800_000, // 30 minutes
+                    });
+                    if (result.success) {
+                        // Update story status to Done
+                        await this.updateStoryStatus(storyFilePath, 'Done');
+                        // Move to QA folder
+                        await this.fileManager.moveFile(storyFilePath, qaFilePath);
+                        successCount++;
+                        // Log story completed in pipeline mode
+                        const storyDuration = Date.now() - storyStartTime;
+                        if (this.workflowLogger) {
+                            await this.workflowLogger.logStoryCompleted(story.fullNumber, storyDuration, true);
+                            // Log verbose transition if enabled
+                            if (config.verbose) {
+                                this.workflowLogger.logVerboseTransition(story.fullNumber, story.title, 'COMPLETED', {
+                                    duration: storyDuration,
+                                });
+                            }
+                        }
+                        workerLogger.info({ storyNumber: story.fullNumber }, 'Story development completed successfully');
+                    }
+                    else {
+                        // Log story failed in pipeline mode
+                        const storyDuration = Date.now() - storyStartTime;
+                        if (this.workflowLogger) {
+                            await this.workflowLogger.logStoryCompleted(story.fullNumber, storyDuration, false);
+                            // Log verbose transition if enabled
+                            if (config.verbose) {
+                                this.workflowLogger.logVerboseTransition(story.fullNumber, story.title, 'FAILED', {
+                                    duration: storyDuration,
+                                });
+                            }
+                        }
+                        workerLogger.error({
+                            error: result.errors,
+                            storyNumber: story.fullNumber,
+                        }, 'Story development failed');
+                        failures.push({
+                            error: result.errors,
+                            identifier: story.fullNumber,
+                        });
+                    }
+                }
+                catch (error) {
+                    // Catch errors for individual stories to prevent worker crash
+                    workerLogger.error({
+                        error: error.message,
+                        storyNumber: story.fullNumber,
+                    }, 'Error processing story, continuing with next story');
+                    failures.push({
+                        error: error.message,
+                        identifier: story.fullNumber,
+                    });
+                }
+                // Wait for configured interval before next story
+                if (config.storyInterval > 0) {
+                    workerLogger.debug({ interval: config.storyInterval }, 'Waiting before next story');
+                    await this.sleep(config.storyInterval * 1000);
+                }
+            }
+            workerLogger.info({
+                failureCount: failures.length,
+                successCount,
+            }, 'Worker completed');
+            return { failures, success: successCount };
+        }
+        catch (error) {
+            workerLogger.error({ error: error.message }, 'Worker failed with unhandled error');
+            // Return partial results even on worker failure
+            return { failures, success: successCount };
+        }
+    }
+    /**
+     * Enqueue existing stories sequentially for pipeline mode
+     *
+     * This method MUST process stories sequentially (not in parallel) to preserve
+     * story order in the queue. The development phase processes stories in order,
+     * so we must maintain that order when enqueuing existing stories.
+     *
+     * @param stories - List of stories to enqueue
+     * @param storyDir - Story directory path
+     * @param prefix - File name prefix
+     * @param onStoryComplete - Callback to enqueue each story
+     * @private
+     */
+    async enqueueExistingStoriesSequentially(stories, storyDir, prefix, onStoryComplete) {
+        this.logger.info({ storyCount: stories.length }, 'Enqueuing existing stories for development');
+        // MUST be sequential - do not parallelize this loop
+        // Story order must be preserved for correct queue processing
+        for (const story of stories) {
+            const storyFileName = this.generateStoryFileName(prefix, story.fullNumber);
+            const storyFilePath = `${storyDir}/${storyFileName}`;
+            const metadata = {
+                epicNumber: story.epicNumber,
+                filePath: storyFilePath,
+                id: story.fullNumber,
+                number: story.fullNumber,
+                status: 'Ready',
+                storyNumber: story.number,
+                title: story.title,
+                type: 'epic-based',
+            };
+            try {
+                await onStoryComplete(metadata);
+            }
+            catch (error) {
+                this.logger.error({
+                    error: error.message,
+                    storyNumber: story.fullNumber,
+                }, 'Failed to enqueue existing story, continuing');
+            }
+        }
+    }
+    /**
+     * Execute development phase
+     *
+     * Executes story development sequentially using ClaudeAgentRunner.
+     * Updates story status and moves completed stories to QA folder.
+     *
+     * @param config - Workflow configuration
+     * @param stories - List of stories to develop
+     * @returns PhaseResult with success count, failures, and duration
+     * @private
+     */
+    async executeDevelopmentPhase(config, stories) {
+        const startTime = Date.now();
+        const failures = [];
+        let successCount = 0;
+        this.logger.info({
+            interval: config.storyInterval,
+            storyCount: stories.length,
+        }, 'Starting development phase');
+        try {
+            const storyDir = await this.pathResolver.getStoryDir();
+            const qaStoryDir = await this.pathResolver.getQaStoryDir();
+            // Execute stories sequentially (NOT parallel - development must be sequential)
+            for (const story of stories) {
+                // Use the actual file path from the story object (already includes correct prefix)
+                const storyFilePath = story.filePath || `${storyDir}/STORY-${story.fullNumber}.md`;
+                // Extract just the filename for QA folder (preserve the same filename)
+                const storyFileName = storyFilePath.split('/').pop() || `STORY-${story.fullNumber}.md`;
+                const qaFilePath = `${qaStoryDir}/${storyFileName}`;
+                // Check if story is already in QA folder (already developed)
+                const alreadyInQa = await this.fileManager.fileExists(qaFilePath);
+                if (alreadyInQa) {
+                    this.logger.info({
+                        qaFilePath,
+                        storyNumber: story.fullNumber,
+                    }, 'Story already in QA folder, skipping development');
+                    successCount++;
+                    continue;
+                }
+                const storyExists = await this.fileManager.fileExists(storyFilePath);
+                if (!storyExists) {
+                    this.logger.warn({ storyNumber: story.fullNumber }, `Story file not found ${storyFilePath}, skipping`);
+                    failures.push({
+                        error: 'Story file not found',
+                        identifier: story.fullNumber,
+                    });
+                    continue;
+                }
+                this.logger.info({ storyNumber: story.fullNumber }, 'Developing story');
+                // Update story status to InProgress
+                await this.updateStoryStatus(storyFilePath, 'InProgress');
+                // Read story content for type detection
+                const storyContent = await this.fileManager.readFile(storyFilePath);
+                // Detect story type and get auto-documentation references
+                const detection = this.storyTypeDetector.detectStoryType(storyContent);
+                const autoReferences = this.storyTypeDetector.getDocumentationReferences(detection.type);
+                this.logger.info({
+                    autoReferencesCount: autoReferences.length,
+                    confidence: detection.confidence,
+                    matchedKeywordsCount: detection.matchedKeywords.length,
+                    storyNumber: story.fullNumber,
+                    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`;
+                // Add working directory instruction if specified
+                if (config.cwd) {
+                    prompt += `Working directory: ${config.cwd}\n\n`;
+                }
+                prompt += `Implement story: ${storyFilePath}\n\n`;
+                // Combine auto-detected references with user-provided references
+                const allReferences = [...autoReferences, ...(config.references || [])];
+                if (allReferences.length > 0) {
+                    prompt += 'References:\n';
+                    for (const ref of allReferences) {
+                        prompt += `@${ref}\n`;
+                    }
+                    prompt += '\n';
+                }
+                prompt += '*yolo mode*\n';
+                const result = await this.agentRunner.runAgent(prompt, {
+                    agentType: 'dev',
+                    references: config.references,
+                    timeout: 1_800_000, // 30 minutes
+                });
+                if (result.success) {
+                    // Update story status to Done
+                    await this.updateStoryStatus(storyFilePath, 'Done');
+                    // Move to QA folder (qaFilePath already defined above with correct filename)
+                    await this.fileManager.moveFile(storyFilePath, qaFilePath);
+                    successCount++;
+                    this.logger.info({ storyNumber: story.fullNumber }, 'Story development completed successfully');
+                }
+                else {
+                    this.logger.error({
+                        error: result.errors,
+                        storyNumber: story.fullNumber,
+                    }, 'Story development failed');
+                    failures.push({
+                        error: result.errors,
+                        identifier: story.fullNumber,
+                    });
+                }
+                // Wait for configured interval before next story
+                if (config.storyInterval > 0 && stories.indexOf(story) < stories.length - 1) {
+                    this.logger.debug({ interval: config.storyInterval }, 'Waiting before next story');
+                    await this.sleep(config.storyInterval * 1000);
+                }
+            }
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                failures: failures.length,
+                success: successCount,
+            }, 'Development phase completed');
+            return {
+                duration,
+                failures,
+                phaseName: 'dev',
+                skipped: false,
+                success: successCount,
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Development phase failed');
+            return {
+                duration: Date.now() - startTime,
+                failures: [
+                    ...failures,
+                    {
+                        error: error.message,
+                        identifier: 'dev-phase',
+                    },
+                ],
+                phaseName: 'dev',
+                skipped: false,
+                success: successCount,
+            };
+        }
+    }
+    /**
+     * Execute epic creation phase
+     *
+     * Parses PRD file, extracts epics, and creates epic markdown files
+     * using ClaudeAgentRunner and BatchProcessor.
+     *
+     * @param config - Workflow configuration
+     * @param prdFilePath - Path to PRD file
+     * @returns PhaseResult with success count, failures, and duration
+     * @private
+     */
+    async executeEpicPhase(config, prdFilePath) {
+        const startTime = Date.now();
+        const failures = [];
+        let successCount = 0;
+        this.logger.info({
+            interval: config.prdInterval,
+            parallel: config.parallel,
+            prdFile: prdFilePath,
+        }, 'Starting epic creation phase');
+        try {
+            // Read PRD file
+            let prdContent = await this.fileManager.readFile(prdFilePath);
+            // Generate prefix from PRD filename if not provided
+            const prefix = config.prefix || this.generatePrefixFromPrdPath(prdFilePath);
+            if (!config.prefix) {
+                this.logger.info({ generatedPrefix: prefix, prdPath: prdFilePath }, 'No prefix provided, generated from PRD filename');
+            }
+            // Parse epics from PRD (with auto-fix support)
+            let epics;
+            try {
+                epics = this.prdParser.parseEpics(prdContent, prdFilePath);
+            }
+            catch (parseError) {
+                // If parsing fails and auto-fix is enabled, attempt to fix the PRD
+                if (config.autoFix && parseError instanceof ParserError) {
+                    this.logger.warn({ error: parseError.message, prdPath: prdFilePath }, 'PRD parsing failed, attempting auto-fix');
+                    const fixResult = await this.prdFixer.fixPrd(prdFilePath, prdContent, config.references);
+                    if (fixResult.fixed) {
+                        this.logger.info({ prdPath: prdFilePath }, 'PRD auto-fixed successfully, retrying parse');
+                        prdContent = fixResult.content;
+                        // Retry parsing with fixed content
+                        epics = this.prdParser.parseEpics(prdContent, prdFilePath);
+                    }
+                    else {
+                        this.logger.error({ error: fixResult.error, prdPath: prdFilePath }, 'PRD auto-fix failed');
+                        throw parseError;
+                    }
+                }
+                else {
+                    throw parseError;
+                }
+            }
+            this.logger.info({ epicCount: epics.length }, 'Epics extracted from PRD');
+            if (epics.length === 0) {
+                this.logger.warn('No epics found in PRD file');
+                return {
+                    duration: Date.now() - startTime,
+                    failures: [],
+                    phaseName: 'epic',
+                    skipped: false,
+                    success: 0,
+                };
+            }
+            // Get epic directory
+            const epicDir = await this.pathResolver.getEpicDir();
+            // Check which epic files are properly populated (not just scaffolded)
+            const properlyPopulatedEpics = await this.checkProperlyPopulatedEpics(epicDir, epics.map((e) => this.generateEpicFileName(prefix, e.number)));
+            // Filter out properly populated epics (exclude scaffolded-only files)
+            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');
+                return {
+                    duration: Date.now() - startTime,
+                    failures: [],
+                    phaseName: 'epic',
+                    skipped: false,
+                    success: epics.length,
+                };
+            }
+            this.logger.info({
+                epicsProperlyPopulated: properlyPopulatedEpics.length,
+                epicsToCreate: epicsToCreate.length,
+            }, '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
+                        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.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({
+                        epicNumber: epic.number,
+                        epicTitle: epic.title,
+                        outputPath: epicFilePath,
+                        prompt,
+                    }, 'Claude Prompt (Epic)');
+                }
+                // Step 3: Run Claude agent to populate content sections
+                const result = await this.agentRunner.runAgent(prompt, {
+                    agentType: 'architect',
+                    references: config.references,
+                    timeout: 1_800_000, // 30 minutes
+                });
+                // 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}`);
+                }
+                return epicFilePath;
+            }, (info) => {
+                this.logger.info({
+                    completedItems: info.completedItems,
+                    currentBatch: info.currentBatch,
+                    totalBatches: info.totalBatches,
+                    totalItems: info.totalItems,
+                }, 'Epic creation progress');
+            });
+            // Track successes and failures
+            for (const [i, result] of results.entries()) {
+                if (result.success) {
+                    successCount++;
+                }
+                else {
+                    failures.push({
+                        error: result.error?.message ?? 'Unknown error',
+                        identifier: `${epicsToCreate[i].number}`,
+                    });
+                }
+            }
+            // Add properly populated epics to success count
+            successCount += properlyPopulatedEpics.length;
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                failures: failures.length,
+                success: successCount,
+            }, 'Epic creation phase completed');
+            return {
+                duration,
+                failures,
+                phaseName: 'epic',
+                skipped: false,
+                success: successCount,
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Epic phase failed');
+            return {
+                duration: Date.now() - startTime,
+                failures: [
+                    ...failures,
+                    {
+                        error: error.message,
+                        identifier: 'epic-phase',
+                    },
+                ],
+                phaseName: 'epic',
+                skipped: false,
+                success: successCount,
+            };
+        }
+    }
+    /**
+     * Execute epic phase if needed
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @param shouldExecute - Whether to execute epic phase
+     * @returns Epic phase result or skipped result
+     * @private
+     */
+    async executeEpicPhaseIfNeeded(config, detection, shouldExecute) {
+        if (!shouldExecute) {
+            return this.createSkippedPhaseResult('epic');
+        }
+        if (config.dryRun) {
+            this.logger.info('[DRY RUN] Would execute epic creation phase');
+            return this.createSkippedPhaseResult('epic');
+        }
+        return this.executeEpicPhase(config, detection.filePath);
+    }
+    /**
+     * Execute pipelined development phase
+     *
+     * Executes story development using concurrent workers that consume from a StoryQueue.
+     * Each worker dequeues stories, executes dev work, and updates story status independently.
+     * Workers terminate when the queue is closed and empty.
+     *
+     * @param queue - StoryQueue to consume stories from
+     * @param config - Workflow configuration
+     * @returns PhaseResult with aggregated success count, failures, and duration
+     * @private
+     */
+    /**
+     * Execute pipelined development phase with worker pool.
+     *
+     * Pipeline coordination algorithm:
+     * 1. Create worker pool of size config.parallel (default: 3 workers)
+     * 2. Each worker independently dequeues from StoryQueue
+     * 3. Workers run concurrently using Promise.all
+     * 4. Natural load balancing via FIFO queue
+     * 5. Workers terminate when queue closed and empty
+     * 6. Aggregate results from all workers
+     *
+     * Performance characteristics:
+     * - Concurrent story development (up to N workers processing simultaneously)
+     * - Queue-based coordination for thread-safe handoff
+     * - No worker starvation due to FIFO fairness
+     * - Graceful completion when story phase closes queue
+     *
+     * @param queue - StoryQueue for consuming completed stories
+     * @param config - Workflow configuration with worker count and intervals
+     * @returns PhaseResult with aggregate success/failure counts and duration
+     * @private
+     */
+    async executePipelinedDevPhase(queue, config) {
+        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
+        const workerCount = 1;
+        this.logger.info({
+            interval: config.storyInterval,
+            mode: 'sequential',
+            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));
+            // Wait for worker to complete
+            const workerResults = await Promise.all(workers);
+            // Aggregate results from all workers
+            let totalSuccess = 0;
+            const allFailures = [];
+            for (const result of workerResults) {
+                totalSuccess += result.success;
+                allFailures.push(...result.failures);
+            }
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                failures: allFailures.length,
+                success: totalSuccess,
+                workerCount,
+            }, 'Pipelined development phase completed');
+            return {
+                duration,
+                failures: allFailures,
+                phaseName: 'dev',
+                skipped: false,
+                success: totalSuccess,
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Pipelined development phase failed');
+            return {
+                duration: Date.now() - startTime,
+                failures: [
+                    {
+                        error: error.message,
+                        identifier: 'dev-phase',
+                    },
+                ],
+                phaseName: 'dev',
+                skipped: false,
+                success: 0,
+            };
+        }
+    }
+    /**
+     * Execute pipelined workflow (story and dev phases in parallel)
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @returns Story and dev phase results
+     * @private
+     */
+    async executePipelinedWorkflow(config, detection) {
+        this.logger.info('Executing pipelined workflow (sequential dev starts as stories are created)');
+        const queue = new StoryQueue(this.logger);
+        try {
+            const storyPhasePromise = this.executeStoryPhaseWithQueue(config, detection, queue);
+            const devPhasePromise = this.executePipelinedDevPhase(queue, config);
+            const [storyResult, devResult] = await Promise.allSettled([storyPhasePromise, devPhasePromise]);
+            return {
+                devPhase: this.handlePhaseResult(devResult, 'dev'),
+                storyPhase: this.handlePhaseResult(storyResult, 'story'),
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Pipelined execution failed');
+            return {
+                devPhase: this.createSkippedPhaseResult('dev'),
+                storyPhase: this.createSkippedPhaseResult('story'),
+            };
+        }
+    }
+    /**
+     * Execute QA phase
+     *
+     * Runs QA workflow on all stories in the QA folder.
+     * Dynamically imports and delegates to StoriesQaCommand.
+     *
+     * @param config - Workflow configuration
+     * @returns PhaseResult with success count, failures, and duration
+     * @private
+     */
+    async executeQaPhase(config) {
+        const startTime = Date.now();
+        const failures = [];
+        let successCount = 0;
+        this.logger.info({
+            qaRetries: config.qaRetries ?? 2,
+        }, 'Starting QA phase');
+        try {
+            // Get QA story directory
+            const qaStoryDir = await this.pathResolver.getQaStoryDir();
+            // Find all stories in QA folder
+            const storyPattern = '*.md';
+            const storyFiles = await this.fileManager.listFiles(qaStoryDir, storyPattern);
+            if (storyFiles.length === 0) {
+                this.logger.info('No stories found in QA folder, skipping QA phase');
+                return {
+                    duration: Date.now() - startTime,
+                    failures: [],
+                    phaseName: 'qa',
+                    skipped: true,
+                    success: 0,
+                };
+            }
+            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');
+            // Process each story through QA
+            for (const storyFile of storyFiles) {
+                const storyPath = `${qaStoryDir}/${storyFile}`;
+                this.logger.info({ storyPath }, 'Running QA workflow for story');
+                try {
+                    // Build args for QA command
+                    const qaArgs = [storyPath];
+                    // Build flags
+                    const qaFlags = [
+                        `--max-retries=${config.qaRetries ?? 2}`,
+                        `--interval=${config.storyInterval}`,
+                        `--provider=${config.provider ?? 'claude'}`,
+                    ];
+                    if (config.qaPrompt) {
+                        qaFlags.push(`--qa-prompt=${config.qaPrompt}`);
+                    }
+                    if (config.references && config.references.length > 0) {
+                        for (const ref of config.references) {
+                            qaFlags.push(`--reference=${ref}`);
+                        }
+                    }
+                    // Run QA command
+                    await StoriesQaCommand.run([...qaArgs, ...qaFlags]);
+                    successCount++;
+                    this.logger.info({ storyPath }, 'QA workflow completed successfully for story');
+                }
+                catch (error) {
+                    const err = error;
+                    this.logger.error({ error: err, storyPath }, 'QA workflow failed for story');
+                    failures.push({
+                        error: err.message,
+                        identifier: storyFile,
+                    });
+                }
+            }
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                failures: failures.length,
+                success: successCount,
+            }, 'QA phase completed');
+            return {
+                duration,
+                failures,
+                phaseName: 'qa',
+                skipped: false,
+                success: successCount,
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'QA phase failed');
+            return {
+                duration: Date.now() - startTime,
+                failures: [
+                    ...failures,
+                    {
+                        error: error.message,
+                        identifier: 'qa-phase',
+                    },
+                ],
+                phaseName: 'qa',
+                skipped: false,
+                success: successCount,
+            };
+        }
+    }
+    /**
+     * Execute QA phase if needed
+     *
+     * @param config - Workflow configuration
+     * @param devPhase - Dev phase result
+     * @param shouldExecute - Whether to execute QA phase
+     * @returns QA phase result
+     * @private
+     */
+    async executeQaPhaseIfNeeded(config, devPhase, shouldExecute) {
+        if (!shouldExecute || !devPhase || devPhase.success === 0) {
+            return this.createSkippedPhaseResult('qa');
+        }
+        if (config.dryRun) {
+            this.logger.info('[DRY RUN] Would execute QA phase');
+            return this.createSkippedPhaseResult('qa');
+        }
+        return this.executeQaPhase(config);
+    }
+    /**
+     * Execute dev phase in sequential mode
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @param shouldExecute - Whether to execute dev phase
+     * @returns Dev phase result
+     * @private
+     */
+    async executeSequentialDevPhase(config, detection, shouldExecute) {
+        if (!shouldExecute) {
+            return this.createSkippedPhaseResult('dev');
+        }
+        if (config.dryRun) {
+            this.logger.info('[DRY RUN] Would execute development phase');
+            return this.createSkippedPhaseResult('dev');
+        }
+        const stories = await this.getStoriesForDevPhase(config, detection);
+        return this.executeDevelopmentPhase(config, stories);
+    }
+    /**
+     * Execute story phase in sequential mode
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @param epicPhase - Epic phase result
+     * @param startTime - Workflow start time
+     * @returns Story phase result
+     * @private
+     */
+    async executeSequentialStoryPhase(config, detection, _epicPhase, _startTime) {
+        if (config.skipStories || detection.type === 'story-pattern') {
+            return this.createSkippedPhaseResult('story');
+        }
+        if (config.dryRun) {
+            this.logger.info('[DRY RUN] Would execute story creation phase');
+            return this.createSkippedPhaseResult('story');
+        }
+        if (detection.type === 'epic') {
+            return this.executeStoryPhaseFromEpicFile(config, detection.filePath);
+        }
+        const epics = await this.getEpicsForStoryPhase(config, detection);
+        return this.executeStoryPhase(config, epics);
+    }
+    /**
+     * Execute sequential workflow (phases one after another)
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @param epicPhase - Epic phase result
+     * @param phaseFlags - Phase execution flags
+     * @param startTime - Workflow start time
+     * @returns Story and dev phase results
+     * @private
+     */
+    async executeSequentialWorkflow(config, detection, epicPhase, phaseFlags, startTime) {
+        this.logger.info('Executing sequential workflow (backward compatibility mode)');
+        const storyPhase = await this.executeSequentialStoryPhase(config, detection, epicPhase, startTime);
+        // If story phase failed completely, skip dev phase
+        if (storyPhase && this.shouldAbortAfterStoryFailure(storyPhase)) {
+            this.logger.warn('Story phase failed completely, skipping dev phase');
+            return { devPhase: this.createSkippedPhaseResult('dev'), storyPhase };
+        }
+        const devPhase = await this.executeSequentialDevPhase(config, detection, phaseFlags.shouldExecuteDevPhase);
+        return { devPhase, storyPhase };
+    }
+    /**
+     * Execute story and dev phases (pipelined or sequential)
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @param epicPhase - Epic phase result
+     * @param phaseFlags - Phase execution flags
+     * @param startTime - Workflow start time
+     * @returns Story and dev phase results
+     * @private
+     */
+    async executeStoryAndDevPhases(config, detection, epicPhase, phaseFlags, startTime) {
+        const shouldPipeline = config.pipeline && phaseFlags.shouldExecuteStoryPhase && phaseFlags.shouldExecuteDevPhase && !config.dryRun;
+        if (shouldPipeline) {
+            return this.executePipelinedWorkflow(config, detection);
+        }
+        return this.executeSequentialWorkflow(config, detection, epicPhase, phaseFlags, startTime);
+    }
+    /**
+     * Execute story creation phase
+     *
+     * Parses epic files, extracts stories, and creates story markdown files
+     * using ClaudeAgentRunner and BatchProcessor.
+     *
+     * @param config - Workflow configuration
+     * @param epics - List of epics to extract stories from
+     * @param onStoryComplete - Optional callback invoked after each story is successfully created
+     * @returns PhaseResult with success count, failures, and duration
+     * @private
+     */
+    async executeStoryPhase(config, epics, onStoryComplete) {
+        const startTime = Date.now();
+        const failures = [];
+        let successCount = 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;
+        this.logger.info({
+            epicCount: epics.length,
+            interval: config.epicInterval,
+            mode: isPipelineMode ? 'sequential (pipeline)' : 'parallel',
+            parallel: effectiveParallel,
+        }, 'Starting story creation phase');
+        try {
+            const allStories = [];
+            // Get epic directory
+            const epicDir = await this.pathResolver.getEpicDir();
+            // Generate prefix from PRD filename if not provided (same as epic creation)
+            let { prefix } = config;
+            if (!prefix) {
+                prefix = this.generatePrefixFromPrdPath(config.input);
+                this.logger.info({ generatedPrefix: prefix, prdPath: config.input }, 'No prefix provided, generated from PRD filename');
+            }
+            // Parse stories from each epic in parallel for better performance
+            const epicStories = await Promise.all(epics.map(async (epic) => {
+                const epicFileName = this.generateEpicFileName(prefix, epic.number);
+                const epicFilePath = `${epicDir}/${epicFileName}`;
+                const epicExists = await this.fileManager.fileExists(epicFilePath);
+                if (!epicExists) {
+                    this.logger.warn({ epicNumber: epic.number }, 'Epic file not found, skipping');
+                    return [];
+                }
+                const epicContent = await this.fileManager.readFile(epicFilePath);
+                const stories = this.epicParser.parseStories(epicContent, epicFilePath);
+                return stories;
+            }));
+            // Flatten the array of story arrays
+            allStories.push(...epicStories.flat());
+            this.logger.info({ storyCount: allStories.length }, 'Stories extracted from epics');
+            if (allStories.length === 0) {
+                this.logger.warn('No stories found in epic files');
+                return {
+                    duration: Date.now() - startTime,
+                    failures: [],
+                    phaseName: 'story',
+                    skipped: false,
+                    success: 0,
+                };
+            }
+            // Get story directory
+            const storyDir = await this.pathResolver.getStoryDir();
+            // Check existing story files across all story directories
+            const storyFileNames = allStories.map((s) => this.generateStoryFileName(prefix, s.fullNumber));
+            const existingStories = await this.checkExistingStoryFiles(storyFileNames);
+            // Filter out existing stories
+            const storiesToCreate = allStories.filter((story) => !existingStories.includes(this.generateStoryFileName(prefix, story.fullNumber)));
+            if (storiesToCreate.length === 0) {
+                this.logger.info('All stories already exist, skipping creation');
+                // In pipeline mode, enqueue existing stories for development
+                if (onStoryComplete) {
+                    await this.enqueueExistingStoriesSequentially(allStories, storyDir, prefix, onStoryComplete);
+                }
+                return {
+                    duration: Date.now() - startTime,
+                    failures: [],
+                    phaseName: 'story',
+                    skipped: false,
+                    success: allStories.length,
+                };
+            }
+            this.logger.info({
+                mode: isPipelineMode ? 'sequential (pipeline)' : 'parallel',
+                parallel: effectiveParallel,
+                storiesSkipped: existingStories.length,
+                storiesToCreate: storiesToCreate.length,
+            }, 'Creating story files');
+            // Create appropriate batch processor based on mode
+            // Pipeline mode requires sequential processing to maintain story order in queue
+            const storyBatchProcessor = isPipelineMode
+                ? new BatchProcessor(effectiveParallel, 0, this.logger)
+                : 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) {
+                    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({
+                        outputPath: storyFilePath,
+                        prompt,
+                        storyNumber: story.fullNumber,
+                        storyTitle: story.title,
+                    }, 'Claude Prompt (Story)');
+                }
+                // Step 4: Run Claude agent to populate content sections
+                const result = await this.agentRunner.runAgent(prompt, {
+                    agentType: 'sm',
+                    references: config.references,
+                    timeout: 1_800_000, // 30 minutes
+                });
+                // 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,
+                            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');
+                    }
+                }
+                return storyFilePath;
+            }, (info) => {
+                this.logger.info({
+                    completedItems: info.completedItems,
+                    currentBatch: info.currentBatch,
+                    totalBatches: info.totalBatches,
+                    totalItems: info.totalItems,
+                }, 'Story creation progress');
+            });
+            // Track successes and failures
+            for (const [i, result] of results.entries()) {
+                if (result.success) {
+                    successCount++;
+                }
+                else {
+                    failures.push({
+                        error: result.error?.message ?? 'Unknown error',
+                        identifier: storiesToCreate[i].fullNumber,
+                    });
+                }
+            }
+            // Add existing stories to success count
+            successCount += existingStories.length;
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                failures: failures.length,
+                success: successCount,
+            }, 'Story creation phase completed');
+            return {
+                duration,
+                failures,
+                phaseName: 'story',
+                skipped: false,
+                success: successCount,
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Story phase failed');
+            return {
+                duration: Date.now() - startTime,
+                failures: [
+                    ...failures,
+                    {
+                        error: error.message,
+                        identifier: 'story-phase',
+                    },
+                ],
+                phaseName: 'story',
+                skipped: false,
+                success: successCount,
+            };
+        }
+    }
+    /**
+     * Execute story phase from a single epic file
+     *
+     * Parses stories from a specific epic file and creates story files.
+     *
+     * @param config - Workflow configuration
+     * @param epicFilePath - Path to the epic file
+     * @param onStoryComplete - Optional callback invoked after each story is successfully created
+     * @returns PhaseResult with success count, failures, and duration
+     * @private
+     */
+    async executeStoryPhaseFromEpicFile(config, epicFilePath, onStoryComplete) {
+        const startTime = Date.now();
+        const failures = [];
+        let successCount = 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;
+        this.logger.info({
+            epicFilePath,
+            mode: isPipelineMode ? 'sequential (pipeline)' : 'parallel',
+            parallel: effectiveParallel,
+        }, 'Starting story creation from epic file');
+        try {
+            // Read and parse stories from epic file
+            const epicContent = await this.fileManager.readFile(epicFilePath);
+            const allStories = this.epicParser.parseStories(epicContent, epicFilePath);
+            // Generate prefix from epic filename if not provided
+            const prefix = config.prefix || this.generatePrefixFromEpicPath(epicFilePath);
+            if (!config.prefix) {
+                this.logger.info({ epicPath: epicFilePath, generatedPrefix: prefix }, 'No prefix provided, generated from epic filename');
+            }
+            this.logger.info({ storyCount: allStories.length }, 'Stories extracted from epic');
+            if (allStories.length === 0) {
+                this.logger.warn('No stories found in epic file');
+                return {
+                    duration: Date.now() - startTime,
+                    failures: [],
+                    phaseName: 'story',
+                    skipped: false,
+                    success: 0,
+                };
+            }
+            // Get story directory
+            const storyDir = await this.pathResolver.getStoryDir();
+            // Check existing story files across all story directories
+            const storyFileNames = allStories.map((s) => this.generateStoryFileName(prefix, s.fullNumber));
+            const existingStories = await this.checkExistingStoryFiles(storyFileNames);
+            // Filter out existing stories
+            const storiesToCreate = allStories.filter((story) => !existingStories.includes(this.generateStoryFileName(prefix, story.fullNumber)));
+            if (storiesToCreate.length === 0) {
+                this.logger.info('All stories already exist, skipping creation');
+                // In pipeline mode, enqueue existing stories for development
+                if (onStoryComplete) {
+                    await this.enqueueExistingStoriesSequentially(allStories, storyDir, prefix, onStoryComplete);
+                }
+                return {
+                    duration: Date.now() - startTime,
+                    failures: [],
+                    phaseName: 'story',
+                    skipped: false,
+                    success: allStories.length,
+                };
+            }
+            this.logger.info({
+                mode: isPipelineMode ? 'sequential (pipeline)' : 'parallel',
+                parallel: effectiveParallel,
+                storiesSkipped: existingStories.length,
+                storiesToCreate: storiesToCreate.length,
+            }, 'Creating story files');
+            // Create appropriate batch processor based on mode
+            // Pipeline mode requires sequential processing to maintain story order in queue
+            const storyBatchProcessor = isPipelineMode
+                ? new BatchProcessor(effectiveParallel, 0, this.logger)
+                : 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) {
+                    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({
+                        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 this.agentRunner.runAgent(prompt, {
+                    agentType: 'sm',
+                    references: config.references,
+                    timeout: 1_800_000, // 30 minutes
+                });
+                // 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,
+                            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');
+                    }
+                }
+                return storyFilePath;
+            }, (info) => {
+                this.logger.info({
+                    completedItems: info.completedItems,
+                    currentBatch: info.currentBatch,
+                    totalBatches: info.totalBatches,
+                    totalItems: info.totalItems,
+                }, 'Story creation progress');
+            });
+            // Track successes and failures
+            for (const [i, result] of results.entries()) {
+                if (result.success) {
+                    successCount++;
+                }
+                else {
+                    failures.push({
+                        error: result.error?.message ?? 'Unknown error',
+                        identifier: storiesToCreate[i].fullNumber,
+                    });
+                }
+            }
+            // Add existing stories to success count
+            successCount += existingStories.length;
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                failures: failures.length,
+                success: successCount,
+            }, 'Story creation from epic file completed');
+            return {
+                duration,
+                failures,
+                phaseName: 'story',
+                skipped: false,
+                success: successCount,
+            };
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Story phase from epic file failed');
+            return {
+                duration: Date.now() - startTime,
+                failures: [
+                    ...failures,
+                    {
+                        error: error.message,
+                        identifier: 'story-phase',
+                    },
+                ],
+                phaseName: 'story',
+                skipped: false,
+                success: successCount,
+            };
+        }
+    }
+    /**
+     * Execute story phase with queue integration for pipelined workflow
+     *
+     * Wraps story phase execution and enqueues completed stories to the provided queue.
+     * Closes queue after story phase completes to signal dev workers to terminate.
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @param queue - StoryQueue instance to enqueue completed stories
+     * @returns PhaseResult from story phase
+     * @private
+     */
+    /**
+     * Execute story creation phase with queue integration for pipeline mode.
+     *
+     * Producer phase in pipelined architecture:
+     * 1. Parse epics from input (PRD or epic file)
+     * 2. Create stories using BatchProcessor with parallel execution
+     * 3. For each completed story, invoke onStoryComplete callback
+     * 4. onStoryComplete enqueues story to StoryQueue for dev workers
+     * 5. After all stories created, close queue to signal completion
+     * 6. Dev workers (running concurrently) consume from queue
+     *
+     * Queue closure semantics:
+     * - Queue.close() signals "no more stories will be added"
+     * - Dev workers terminate when queue returns null (closed + empty)
+     * - Ensures graceful pipeline completion
+     *
+     * Error handling:
+     * - Individual story creation failures logged but don't stop phase
+     * - Queue enqueueing failures logged but don't stop creation
+     * - Queue always closed in finally block to prevent worker deadlock
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result (PRD or epic file)
+     * @param queue - StoryQueue for enqueuing completed stories
+     * @returns PhaseResult with story creation metrics
+     * @private
+     */
+    async executeStoryPhaseWithQueue(config, detection, queue) {
+        try {
+            // Create callback to enqueue completed stories
+            const onStoryComplete = async (metadata) => {
+                try {
+                    // Only epic-based stories can be enqueued (standalone stories don't have epic numbering)
+                    if (!isEpicStory(metadata)) {
+                        this.logger.warn({ storyId: metadata.id }, 'Skipping standalone story - not supported in queue mode');
+                        return;
+                    }
+                    // Convert StoryMetadata to Story object for queue
+                    const story = {
+                        epicNumber: metadata.epicNumber,
+                        filePath: metadata.filePath,
+                        fullNumber: metadata.number,
+                        number: metadata.storyNumber,
+                        title: metadata.title,
+                    };
+                    // Log story created and queued in pipeline mode
+                    if (this.workflowLogger) {
+                        await this.workflowLogger.logStoryCreated(story.fullNumber);
+                        await this.workflowLogger.logStoryQueued(story.fullNumber, queue.getPendingCount());
+                        // Log verbose transitions if enabled
+                        if (config.verbose) {
+                            this.workflowLogger.logVerboseTransition(story.fullNumber, story.title, 'CREATING');
+                            this.workflowLogger.logVerboseTransition(story.fullNumber, story.title, 'QUEUED', {
+                                position: queue.getPendingCount(),
+                            });
+                        }
+                    }
+                    this.logger.debug({
+                        storyNumber: story.fullNumber,
+                        storyTitle: story.title,
+                    }, 'Enqueuing completed story');
+                    queue.enqueue(story);
+                }
+                catch (error) {
+                    this.logger.error({
+                        error: error.message,
+                        storyId: metadata.id,
+                    }, 'Failed to enqueue story, continuing story creation');
+                }
+            };
+            // Execute story phase with callback
+            let storyPhase;
+            if (detection.type === 'epic') {
+                // Single epic file - parse stories directly
+                storyPhase = await this.executeStoryPhaseFromEpicFile(config, detection.filePath, onStoryComplete);
+            }
+            else {
+                // Get epics for story phase
+                let epics = [];
+                if (detection.type === 'prd') {
+                    // Parse epics from PRD (with auto-fix support)
+                    let prdContent = await this.fileManager.readFile(detection.filePath);
+                    try {
+                        epics = this.prdParser.parseEpics(prdContent, detection.filePath);
+                    }
+                    catch (parseError) {
+                        // If parsing fails and auto-fix is enabled, attempt to fix the PRD
+                        if (config.autoFix && parseError instanceof ParserError) {
+                            this.logger.warn({ error: parseError.message, prdPath: detection.filePath }, 'PRD parsing failed in pipelined story phase, attempting auto-fix');
+                            const fixResult = await this.prdFixer.fixPrd(detection.filePath, prdContent, config.references);
+                            if (fixResult.fixed) {
+                                this.logger.info({ prdPath: detection.filePath }, 'PRD auto-fixed successfully, retrying parse');
+                                prdContent = fixResult.content;
+                                epics = this.prdParser.parseEpics(prdContent, detection.filePath);
+                            }
+                            else {
+                                throw parseError;
+                            }
+                        }
+                        else {
+                            throw parseError;
+                        }
+                    }
+                }
+                storyPhase = await this.executeStoryPhase(config, epics, onStoryComplete);
+            }
+            // Close queue to signal dev phase that no more stories will be added
+            this.logger.info('Story phase completed, closing queue');
+            queue.close();
+            return storyPhase;
+        }
+        catch (error) {
+            // Ensure queue is closed even if story phase fails
+            this.logger.error({ error: error.message }, 'Story phase failed, closing queue');
+            queue.close();
+            throw error;
+        }
+    }
+    /**
+     * Extract epic number from file path
+     *
+     * @param filePath - Epic file path (e.g., 'docs/epics/epic-1.md')
+     * @returns Epic number
+     * @private
+     */
+    extractEpicNumber(filePath) {
+        const match = filePath.match(/epic-(\d+)\.md/);
+        return match ? Number.parseInt(match[1], 10) : 1;
+    }
+    /**
+     * Extract story from file path
+     *
+     * @param filePath - Story file path (e.g., 'docs/stories/USER-GROUPS-story-1.001.md')
+     * @returns Story object
+     * @private
+     */
+    extractStoryFromFilePath(filePath) {
+        // Match story pattern: <PREFIX>-story-<epicNum>.<storyNum>.md
+        // Example: USER-GROUPS-story-1.001.md or STORY-1.2.md (legacy format)
+        const match = filePath.match(/-story-(\d+)\.(\d+)\.md/i);
+        if (!match) {
+            this.logger.warn({ filePath }, 'Failed to parse story number from file path');
+            return { epicNumber: 1, filePath, fullNumber: '1.1', number: 1, title: '' };
+        }
+        const epicNumber = Number.parseInt(match[1], 10);
+        const storyNumber = Number.parseInt(match[2], 10);
+        return {
+            epicNumber,
+            filePath,
+            fullNumber: `${epicNumber}.${storyNumber}`,
+            number: storyNumber,
+            title: '',
+        };
+    }
+    /**
+     * Generate epic file name with prefix and padded number
+     *
+     * @param prefix - File name prefix
+     * @param epicNumber - Epic number
+     * @returns Formatted file name (e.g., "USER-GROUPS-epic-001.md")
+     * @private
+     */
+    generateEpicFileName(prefix, epicNumber) {
+        const paddedNumber = String(epicNumber).padStart(3, '0');
+        return `${prefix}-epic-${paddedNumber}.md`;
+    }
+    /**
+     * Generate prefix from epic file path
+     *
+     * Extracts meaningful name from epic filename and converts to uppercase
+     * Example: "docs/epics/epic-1-user-authentication.md" -> "USER-AUTHENTICATION"
+     *
+     * @param epicPath - Path to epic file
+     * @returns Generated prefix
+     * @private
+     */
+    generatePrefixFromEpicPath(epicPath) {
+        // Get filename without extension
+        const filename = epicPath
+            .split('/')
+            .pop()
+            ?.replace(/\.(md|markdown)$/i, '') || 'EPIC';
+        // Remove epic-N- prefix if present and convert to uppercase
+        const prefix = filename
+            .replaceAll(/^epic-\d+-?/gi, '')
+            .toUpperCase()
+            .replaceAll(/\s+/g, '-');
+        // If no meaningful name remains, return EPIC
+        return prefix || 'EPIC';
+    }
+    /**
+     * Generate prefix from PRD file path
+     *
+     * Extracts the PRD name from the file path and converts it to uppercase
+     * Example: "docs/PRD-user-groups.md" -> "USER-GROUPS"
+     *
+     * @param prdPath - Path to PRD file
+     * @returns Generated prefix
+     * @private
+     */
+    generatePrefixFromPrdPath(prdPath) {
+        // Get filename without extension
+        const filename = prdPath
+            .split('/')
+            .pop()
+            ?.replace(/\.(md|markdown)$/i, '') || 'PRD';
+        // Remove PRD- prefix if present and convert to uppercase
+        const prefix = filename.replaceAll(/^PRD-/gi, '').toUpperCase().replaceAll(/\s+/g, '-');
+        return prefix;
+    }
+    /**
+     * Generate story file name with prefix
+     *
+     * @param prefix - File name prefix
+     * @param storyNumber - Story number (e.g., "1.1")
+     * @returns Formatted file name (e.g., "USER-GROUPS-story-1.001.md")
+     * @private
+     */
+    generateStoryFileName(prefix, storyNumber) {
+        // Parse epic number and story number from format "1.1"
+        const [epicNum, storyNum] = storyNumber.split('.');
+        // Zero-pad the story number to 3 digits
+        const paddedStoryNum = String(storyNum).padStart(3, '0');
+        return `${prefix}-story-${epicNum}.${paddedStoryNum}.md`;
+    }
+    /**
+     * Get epics for story phase execution
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @returns Array of epics
+     * @private
+     */
+    async getEpicsForStoryPhase(config, detection) {
+        if (detection.type !== 'prd') {
+            return [];
+        }
+        let prdContent = await this.fileManager.readFile(detection.filePath);
+        try {
+            return this.prdParser.parseEpics(prdContent, detection.filePath);
+        }
+        catch (parseError) {
+            if (config.autoFix && parseError instanceof ParserError) {
+                this.logger.warn({ error: parseError.message, prdPath: detection.filePath }, 'PRD parsing failed in story phase, attempting auto-fix');
+                const fixResult = await this.prdFixer.fixPrd(detection.filePath, prdContent, config.references);
+                if (fixResult.fixed) {
+                    this.logger.info({ prdPath: detection.filePath }, 'PRD auto-fixed successfully, retrying parse');
+                    prdContent = fixResult.content;
+                    return this.prdParser.parseEpics(prdContent, detection.filePath);
+                }
+            }
+            throw parseError;
+        }
+    }
+    /**
+     * Get stories for dev phase execution
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @returns Array of stories
+     * @private
+     */
+    async getStoriesForDevPhase(config, detection) {
+        const prefix = this.resolvePrefix(config, detection);
+        const storyPattern = `${prefix}-story-*.md`;
+        this.logger.info({ inputType: detection.type, prefix, storyPattern }, 'Looking for story files with pattern');
+        const storyDir = await this.pathResolver.getStoryDir();
+        const storyFiles = await this.fileManager.listFiles(storyDir, storyPattern);
+        return storyFiles.map((file) => this.extractStoryFromFilePath(file));
+    }
+    /**
+     * Handle phase result from Promise.allSettled
+     *
+     * @param result - PromiseSettledResult
+     * @param phaseName - Phase name for error reporting
+     * @returns PhaseResult
+     * @private
+     */
+    handlePhaseResult(result, phaseName) {
+        if (result.status === 'fulfilled') {
+            return result.value;
+        }
+        this.logger.error({ error: result.reason }, `${phaseName} phase failed`);
+        return {
+            duration: 0,
+            failures: [
+                {
+                    error: result.reason.message,
+                    identifier: `${phaseName}-phase`,
+                },
+            ],
+            phaseName,
+            skipped: false,
+            success: 0,
+        };
+    }
+    /**
+     * Log workflow start information
+     *
+     * @param config - Workflow configuration
+     * @private
+     */
+    logWorkflowStart(config) {
+        this.logger.info({
+            dryRun: config.dryRun,
+            input: config.input,
+            parallel: config.parallel,
+            pipelineMode: config.pipeline ? 'enabled' : 'disabled',
+            skipDev: config.skipDev,
+            skipEpics: config.skipEpics,
+            skipStories: config.skipStories,
+        }, 'Starting workflow execution');
+    }
+    /**
+     * Resolve prefix for story file pattern
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @returns Prefix string
+     * @private
+     */
+    resolvePrefix(config, detection) {
+        if (config.prefix) {
+            return config.prefix;
+        }
+        if (detection.type === 'epic') {
+            return this.generatePrefixFromEpicPath(detection.filePath);
+        }
+        if (detection.type === 'prd') {
+            return this.generatePrefixFromPrdPath(detection.filePath);
+        }
+        return this.generatePrefixFromPrdPath(config.input);
+    }
+    /**
+     * Check if workflow should abort after epic phase failure
+     *
+     * @param epicPhase - Epic phase result
+     * @returns True if should abort
+     * @private
+     */
+    shouldAbortAfterEpicFailure(epicPhase) {
+        return epicPhase !== undefined && epicPhase.success === 0 && epicPhase.failures.length > 0;
+    }
+    /**
+     * Check if workflow should abort after story phase failure
+     *
+     * @param storyPhase - Story phase result
+     * @returns True if should abort
+     * @private
+     */
+    shouldAbortAfterStoryFailure(storyPhase) {
+        return storyPhase.success === 0 && storyPhase.failures.length > 0;
+    }
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     * @private
+     */
+    async sleep(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Update story status in file
+     *
+     * @param storyFilePath - Path to story file
+     * @param status - New status
+     * @private
+     */
+    async updateStoryStatus(storyFilePath, status) {
+        const content = await this.fileManager.readFile(storyFilePath);
+        const updatedContent = content.replace(/^## Status\s*\n\n(.+?)$/m, `## Status\n\n${status}`);
+        await this.fileManager.writeFile(storyFilePath, updatedContent);
+    }
+    /**
+     * Validate workflow configuration
+     *
+     * @param config - Workflow configuration to validate
+     * @throws {ValidationError} If configuration is invalid
+     * @private
+     */
+    validateConfig(config) {
+        if (!config.input || config.input.trim().length === 0) {
+            throw new ValidationError('Input is required', { field: 'input' });
+        }
+        if (config.prdInterval < 0) {
+            throw new ValidationError('prdInterval must be >= 0', { field: 'prdInterval' });
+        }
+        if (config.epicInterval < 0) {
+            throw new ValidationError('epicInterval must be >= 0', { field: 'epicInterval' });
+        }
+        if (config.storyInterval < 0) {
+            throw new ValidationError('storyInterval must be >= 0', { field: 'storyInterval' });
+        }
+        if (config.parallel < 1) {
+            throw new ValidationError('parallel must be >= 1', { field: 'parallel' });
+        }
+    }
+}