@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/orchestration/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Orchestration Services
+ *
+ * Services for orchestrating workflows and batch processing
+ */
+export { BatchProcessor } from './batch-processor.js';
+export type { BatchProcessorOptions, BatchResult, ProcessorFunction, ProgressCallback, ProgressInfo, } from './batch-processor.js';
+export { StoryQueue } from './story-queue.js';
+export { WorkflowOrchestrator } from './workflow-orchestrator.js';
+export type { InputDetector } from './workflow-orchestrator.js';

package/dist/services/orchestration/index.js

@@ -0,0 +1,8 @@
+/**
+ * Orchestration Services
+ *
+ * Services for orchestrating workflows and batch processing
+ */
+export { BatchProcessor } from './batch-processor.js';
+export { StoryQueue } from './story-queue.js';
+export { WorkflowOrchestrator } from './workflow-orchestrator.js';

package/dist/services/orchestration/input-detector.d.ts

@@ -0,0 +1,125 @@
+/**
+ * InputDetector Service
+ *
+ * Automatically detects whether input is a PRD file, epic file, or story pattern
+ * to determine the correct workflow entry point.
+ */
+import type pino from 'pino';
+import type { InputDetectionResult } from '../../models/index.js';
+import { FileManager } from '../file-system/file-manager.js';
+/**
+ * InputDetector service for automatic input type detection
+ *
+ * Examines file content and filenames to detect PRD files, epic files,
+ * or story patterns, returning a typed detection result with confidence score.
+ */
+export declare class InputDetector {
+    /**
+     * FileManager instance for file system operations
+     */
+    private readonly fileManager;
+    /**
+     * Logger instance for detection operations
+     */
+    private readonly logger;
+    /**
+     * Create a new InputDetector instance
+     *
+     * @param fileManager - FileManager instance for file operations
+     * @param logger - Pino logger instance for logging detection operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:orchestration:input-detector' })
+     * const fileManager = new FileManager(logger)
+     * const detector = new InputDetector(fileManager, logger)
+     */
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Detect input type from file path or pattern (alias for detectInputType)
+     *
+     * @param input - File path or pattern to analyze
+     * @returns Detection result with type, confidence, and metadata
+     */
+    detect(input: string): Promise<InputDetectionResult>;
+    /**
+     * Detect input type from file path or pattern
+     *
+     * Examines the input to determine if it's a PRD file, epic file, or story pattern.
+     * Detection order: story pattern → PRD content → epic filename
+     *
+     * @param input - File path or pattern to analyze
+     * @returns Detection result with type, confidence, and metadata
+     * @example
+     * const result = await detector.detectInputType('docs/prd.md')
+     * if (result.type === 'prd') {
+     *   // Start epic creation phase
+     * }
+     */
+    detectInputType(input: string): Promise<InputDetectionResult>;
+    /**
+     * Calculate confidence score from detection checks
+     *
+     * @param checks - Array of detection checks performed
+     * @returns Confidence score (0.0 to 1.0)
+     * @private
+     */
+    private calculateConfidence;
+    /**
+     * Extract epic number from filename
+     *
+     * @param filename - Filename containing epic number
+     * @returns Epic number or undefined if not found
+     * @private
+     */
+    private extractEpicNumber;
+    /**
+     * Check if filename matches epic pattern
+     *
+     * @param filename - Filename to analyze (not full path)
+     * @returns True if epic pattern matched
+     * @private
+     */
+    private isEpicFile;
+    /**
+     * Check if file path indicates an epic file
+     *
+     * @param filePath - Full file path to analyze
+     * @returns True if path indicates epic file
+     * @private
+     */
+    private isEpicPath;
+    /**
+     * Check if content contains PRD markers
+     *
+     * @param content - File content to analyze
+     * @returns True if PRD markers found
+     * @private
+     */
+    private isPrdFile;
+    /**
+     * Check if filename indicates a PRD file
+     *
+     * @param filename - Filename to analyze (not full path)
+     * @returns True if PRD filename pattern matched
+     * @private
+     */
+    private isPrdFilename;
+    /**
+     * Check if file path indicates a story file
+     *
+     * Checks docs/stories, docs/qa/stories, and docs/done/stories to recognize
+     * all valid story locations (active, in QA, and completed).
+     *
+     * @param filePath - Full file path to analyze
+     * @returns True if path indicates story file
+     * @private
+     */
+    private isStoryPath;
+    /**
+     * Check if input is a story pattern (glob wildcards or story directory reference)
+     *
+     * @param input - Input string to analyze
+     * @returns True if story pattern detected
+     * @private
+     */
+    private isStoryPattern;
+}

package/dist/services/orchestration/input-detector.js

@@ -0,0 +1,381 @@
+/**
+ * InputDetector Service
+ *
+ * Automatically detects whether input is a PRD file, epic file, or story pattern
+ * to determine the correct workflow entry point.
+ */
+import { basename } from 'node:path';
+/**
+ * InputDetector service for automatic input type detection
+ *
+ * Examines file content and filenames to detect PRD files, epic files,
+ * or story patterns, returning a typed detection result with confidence score.
+ */
+export class InputDetector {
+    /**
+     * FileManager instance for file system operations
+     */
+    fileManager;
+    /**
+     * Logger instance for detection operations
+     */
+    logger;
+    /**
+     * Create a new InputDetector instance
+     *
+     * @param fileManager - FileManager instance for file operations
+     * @param logger - Pino logger instance for logging detection operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:orchestration:input-detector' })
+     * const fileManager = new FileManager(logger)
+     * const detector = new InputDetector(fileManager, logger)
+     */
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Detect input type from file path or pattern (alias for detectInputType)
+     *
+     * @param input - File path or pattern to analyze
+     * @returns Detection result with type, confidence, and metadata
+     */
+    async detect(input) {
+        return this.detectInputType(input);
+    }
+    /**
+     * Detect input type from file path or pattern
+     *
+     * Examines the input to determine if it's a PRD file, epic file, or story pattern.
+     * Detection order: story pattern → PRD content → epic filename
+     *
+     * @param input - File path or pattern to analyze
+     * @returns Detection result with type, confidence, and metadata
+     * @example
+     * const result = await detector.detectInputType('docs/prd.md')
+     * if (result.type === 'prd') {
+     *   // Start epic creation phase
+     * }
+     */
+    async detectInputType(input) {
+        this.logger.info({ input, strategy: 'multi-strategy' }, 'Starting input type detection');
+        const checks = [];
+        try {
+            // Strategy 1: Check for story pattern (no file system access needed)
+            if (this.isStoryPattern(input)) {
+                this.logger.info({ input, type: 'story-pattern' }, 'Detected story pattern');
+                return {
+                    confidence: 1,
+                    filePath: input,
+                    metadata: {
+                        markers: ['glob-wildcard'],
+                    },
+                    type: 'story-pattern',
+                };
+            }
+            // Strategy 2: Check if file exists
+            const exists = await this.fileManager.fileExists(input);
+            if (!exists) {
+                const error = `File not found: ${input}. Check path and current directory.`;
+                this.logger.error({ error, input }, 'File not found during detection');
+                return {
+                    confidence: 0,
+                    error,
+                    filePath: input,
+                    type: null,
+                };
+            }
+            // Strategy 3: Read file content for PRD detection
+            const content = await this.fileManager.readFile(input);
+            const filename = basename(input);
+            // Check PRD markers in content
+            const prdContentCheck = this.isPrdFile(content);
+            checks.push({
+                evidence: prdContentCheck ? 'PRD markers found in content' : undefined,
+                name: 'prd-content',
+                passed: prdContentCheck,
+                weight: 0.8,
+            });
+            // Check PRD filename pattern (e.g., PRD-feature.md, prd.md)
+            const prdFilenameCheck = this.isPrdFilename(filename);
+            checks.push({
+                evidence: prdFilenameCheck ? `PRD filename pattern: ${filename}` : undefined,
+                name: 'prd-filename',
+                passed: prdFilenameCheck,
+                weight: 0.7,
+            });
+            // Combined PRD check - either content or filename indicates PRD
+            const prdCheck = prdContentCheck || prdFilenameCheck;
+            // Check epic filename pattern
+            const epicCheck = this.isEpicFile(filename);
+            const epicNumber = epicCheck ? this.extractEpicNumber(filename) : undefined;
+            checks.push({
+                evidence: epicCheck ? `Epic pattern matched: ${filename}` : undefined,
+                name: 'epic-filename',
+                passed: epicCheck,
+                weight: 0.8,
+            });
+            // Check path-based indicators (strongest signal)
+            const epicPathCheck = this.isEpicPath(input);
+            if (epicPathCheck) {
+                checks.push({
+                    evidence: `File in epics directory: ${input}`,
+                    name: 'epic-path',
+                    passed: true,
+                    weight: 1,
+                });
+            }
+            const storyPathCheck = this.isStoryPath(input);
+            if (storyPathCheck) {
+                checks.push({
+                    evidence: `File in stories directory: ${input}`,
+                    name: 'story-path',
+                    passed: true,
+                    weight: 1,
+                });
+            }
+            // Determine type based on checks
+            // Priority order (highest to lowest):
+            // 1. Path-based detection (most reliable - user explicitly placed file in typed directory)
+            // 2. Content patterns (PRD markers are explicit and should override filename ambiguity)
+            // 3. Filename patterns (when no content markers found)
+            let detectedType = null;
+            if (storyPathCheck) {
+                detectedType = 'story-pattern';
+            }
+            else if (epicPathCheck) {
+                detectedType = 'epic';
+            }
+            else if (prdCheck) {
+                // PRD content markers take priority over epic filename patterns
+                detectedType = 'prd';
+            }
+            else if (epicCheck) {
+                detectedType = 'epic';
+            }
+            // Calculate confidence score
+            const confidence = this.calculateConfidence(checks);
+            const result = {
+                confidence,
+                filePath: input,
+                metadata: {
+                    epicNumber,
+                    filename,
+                    markers: checks.filter((c) => c.passed).map((c) => c.name),
+                },
+                type: detectedType,
+            };
+            // Add ambiguity reason for low confidence
+            if (confidence < 0.7 && detectedType) {
+                result.metadata = {
+                    ...result.metadata,
+                    ambiguityReason: 'File exists but no clear type markers found',
+                };
+            }
+            this.logger.info({ confidence, input, metadata: result.metadata, type: detectedType }, 'Detection complete');
+            return result;
+        }
+        catch (error) {
+            const err = error;
+            const errorMessage = `Failed to detect input type: ${err.message}`;
+            this.logger.error({ error: err.message, input, operation: 'detectInputType' }, errorMessage);
+            return {
+                confidence: 0,
+                error: errorMessage,
+                filePath: input,
+                type: null,
+            };
+        }
+    }
+    /**
+     * Calculate confidence score from detection checks
+     *
+     * @param checks - Array of detection checks performed
+     * @returns Confidence score (0.0 to 1.0)
+     * @private
+     */
+    calculateConfidence(checks) {
+        if (checks.length === 0) {
+            return 0.5; // Low confidence for no checks
+        }
+        const passedChecks = checks.filter((c) => c.passed);
+        if (passedChecks.length === 0) {
+            return 0.5; // Low confidence - no indicators matched
+        }
+        if (passedChecks.length === 1) {
+            return 0.7; // Medium confidence - single strong indicator
+        }
+        // High confidence - multiple indicators
+        return 1;
+    }
+    /**
+     * Extract epic number from filename
+     *
+     * @param filename - Filename containing epic number
+     * @returns Epic number or undefined if not found
+     * @private
+     */
+    extractEpicNumber(filename) {
+        const match = /epic-(\d+)/i.exec(filename);
+        if (match?.[1]) {
+            const epicNumber = Number.parseInt(match[1], 10);
+            this.logger.debug({ epicNumber, filename }, 'Extracted epic number');
+            return epicNumber;
+        }
+        return undefined;
+    }
+    /**
+     * Check if filename matches epic pattern
+     *
+     * @param filename - Filename to analyze (not full path)
+     * @returns True if epic pattern matched
+     * @private
+     */
+    isEpicFile(filename) {
+        this.logger.debug({ filename }, 'Checking for epic filename pattern');
+        const epicPatterns = [
+            /epic-\d+-.+\.md$/i, // epic-1-foundation.md
+            /.+epic-\d+.+\.md$/i, // BMAD-epic-1.md
+            /^epic-\d+\.md$/i, // epic-3.md
+        ];
+        for (const pattern of epicPatterns) {
+            if (pattern.test(filename)) {
+                this.logger.debug({ filename, pattern: pattern.source }, 'Epic filename pattern matched');
+                return true;
+            }
+        }
+        this.logger.debug({ filename }, 'No epic filename pattern matched');
+        return false;
+    }
+    /**
+     * Check if file path indicates an epic file
+     *
+     * @param filePath - Full file path to analyze
+     * @returns True if path indicates epic file
+     * @private
+     */
+    isEpicPath(filePath) {
+        this.logger.debug({ filePath }, 'Checking for epic path pattern');
+        // Normalize path separators for cross-platform compatibility
+        const normalizedPath = filePath.replaceAll('\\', '/');
+        // Check for epics directory in path
+        const hasEpicsDir = /\/epics\//i.test(normalizedPath) || normalizedPath.startsWith('epics/');
+        if (hasEpicsDir) {
+            this.logger.debug({ filePath }, 'Epic path pattern matched: epics directory');
+            return true;
+        }
+        this.logger.debug({ filePath }, 'No epic path pattern matched');
+        return false;
+    }
+    /**
+     * Check if content contains PRD markers
+     *
+     * @param content - File content to analyze
+     * @returns True if PRD markers found
+     * @private
+     */
+    isPrdFile(content) {
+        this.logger.debug('Checking for PRD markers in content');
+        const prdMarkers = [
+            /^##\s+Epic\s+List/im, // ## Epic List
+            /^##\s+Epics?\s*$/im, // ## Epics or ## Epic (as section header)
+            /^#\s+Epics?(?:\s+List)?$/im, // # Epic List, # Epics, # Epics List (but not # Epic N:)
+            /^##\s+(?:\d+\.\s+)?Epic\s+\d+:/im, // ## Epic 1: or ## 7. Epic 1:
+            /^##\s+\d+\.\s+Epic\s+and\s+Story\s+Structure/im, // ## 6. Epic and Story Structure
+        ];
+        for (const marker of prdMarkers) {
+            if (marker.test(content)) {
+                this.logger.debug({ marker: marker.source }, 'PRD marker matched');
+                return true;
+            }
+        }
+        this.logger.debug('No PRD markers found');
+        return false;
+    }
+    /**
+     * Check if filename indicates a PRD file
+     *
+     * @param filename - Filename to analyze (not full path)
+     * @returns True if PRD filename pattern matched
+     * @private
+     */
+    isPrdFilename(filename) {
+        this.logger.debug({ filename }, 'Checking for PRD filename pattern');
+        // PRD filename patterns
+        const prdPatterns = [
+            /^prd[-_]/i, // prd-feature.md, prd_feature.md
+            /^prd\.md$/i, // prd.md
+            /[-_]prd[-_]/i, // feature-prd-v1.md
+            /[-_]prd\.md$/i, // feature-prd.md
+        ];
+        for (const pattern of prdPatterns) {
+            if (pattern.test(filename)) {
+                this.logger.debug({ filename, pattern: pattern.source }, 'PRD filename pattern matched');
+                return true;
+            }
+        }
+        this.logger.debug({ filename }, 'No PRD filename pattern matched');
+        return false;
+    }
+    /**
+     * Check if file path indicates a story file
+     *
+     * Checks docs/stories, docs/qa/stories, and docs/done/stories to recognize
+     * all valid story locations (active, in QA, and completed).
+     *
+     * @param filePath - Full file path to analyze
+     * @returns True if path indicates story file
+     * @private
+     */
+    isStoryPath(filePath) {
+        this.logger.debug({ filePath }, 'Checking for story path pattern');
+        // Normalize path separators for cross-platform compatibility
+        const normalizedPath = filePath.replaceAll('\\', '/');
+        // Check for stories directory in any of the three valid locations:
+        // - docs/stories (active development)
+        // - docs/qa/stories (in QA review)
+        // - docs/done/stories (completed)
+        const hasStoriesDir = /\/stories\//i.test(normalizedPath) ||
+            normalizedPath.startsWith('stories/') ||
+            /\/qa\/stories\//i.test(normalizedPath) ||
+            normalizedPath.startsWith('qa/stories/') ||
+            /\/done\/stories\//i.test(normalizedPath) ||
+            normalizedPath.startsWith('done/stories/');
+        if (hasStoriesDir) {
+            this.logger.debug({ filePath }, 'Story path pattern matched: stories directory');
+            return true;
+        }
+        this.logger.debug({ filePath }, 'No story path pattern matched');
+        return false;
+    }
+    /**
+     * Check if input is a story pattern (glob wildcards or story directory reference)
+     *
+     * @param input - Input string to analyze
+     * @returns True if story pattern detected
+     * @private
+     */
+    isStoryPattern(input) {
+        this.logger.debug({ input }, 'Checking for story pattern indicators');
+        // Check for glob wildcards
+        const hasWildcards = /[*?[\]]/.test(input);
+        if (hasWildcards) {
+            this.logger.debug({ input }, 'Story pattern: glob wildcards detected');
+            return true;
+        }
+        // Check for story directory reference
+        const hasStoryDirectory = input.includes('stories/');
+        if (hasStoryDirectory) {
+            this.logger.debug({ input }, 'Story pattern: stories/ directory detected');
+            return true;
+        }
+        // Check for story filename format: N.N-*.md
+        const storyFilenamePattern = /\d+\.\d+-.*\.md/;
+        if (storyFilenamePattern.test(input)) {
+            this.logger.debug({ input }, 'Story pattern: N.N-*.md format detected');
+            return true;
+        }
+        this.logger.debug({ input }, 'No story pattern indicators found');
+        return false;
+    }
+}

package/dist/services/orchestration/story-queue.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Story Queue
+ *
+ * Thread-safe queue mechanism for capturing completed stories during the story creation phase
+ * and making them available to the development phase. Supports concurrent consumers with
+ * async waiting when queue is empty.
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino'
+ * import { StoryQueue } from './story-queue.js'
+ *
+ * const logger = pino()
+ * const queue = new StoryQueue(logger)
+ *
+ * // Producer: enqueue completed stories
+ * queue.enqueue(story1)
+ * queue.enqueue(story2)
+ *
+ * // Consumer: dequeue stories for processing
+ * const story = await queue.dequeue() // Waits if queue is empty
+ * if (story === null) {
+ *   // Queue is closed and empty
+ *   return
+ * }
+ *
+ * // When all stories are created, close the queue
+ * queue.close()
+ * ```
+ */
+import type pino from 'pino';
+import type { Story } from '../../models/story.js';
+/**
+ * Thread-safe queue for story pipeline coordination.
+ *
+ * Provides FIFO queueing with async waiting for consumers. Safe for concurrent
+ * access in Node.js event loop (no mutex needed due to single-threaded execution).
+ */
+export declare class StoryQueue {
+    /**
+     * Flag indicating no more stories will be added
+     */
+    private closed;
+    /**
+     * Structured logger instance
+     */
+    private readonly logger;
+    /**
+     * Internal FIFO queue of stories
+     */
+    private queue;
+    /**
+     * Array of waiting dequeue promises
+     */
+    private waiters;
+    /**
+     * Creates a new StoryQueue instance
+     *
+     * @param logger - Pino logger for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Signals that no more stories will be added to the queue.
+     * All waiting dequeue calls will be resolved with null.
+     */
+    close(): void;
+    /**
+     * Removes and returns the next story from the queue.
+     * If queue is empty and not closed, waits asynchronously for a story to be enqueued.
+     * If queue is closed and empty, returns null.
+     *
+     * @returns Promise that resolves to the next story, or null if queue is closed and empty
+     */
+    dequeue(): Promise<null | Story>;
+    /**
+     * Adds a story to the queue
+     *
+     * @param story - The story to enqueue
+     * @throws Error if queue is already closed
+     */
+    enqueue(story: Story): void;
+    /**
+     * Gets the number of pending stories in the queue
+     *
+     * @returns Number of stories waiting to be dequeued
+     */
+    getPendingCount(): number;
+    /**
+     * Checks if the queue is empty
+     *
+     * @returns true if queue has no items, false otherwise
+     */
+    isEmpty(): boolean;
+}