@hyperdrive.bot/bmad-workflow 1.0.2

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

@@ -0,0 +1,659 @@
+/**
+ * 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 type pino from 'pino';
+import type { InputDetectionResult, WorkflowConfig, WorkflowResult } from '../../models/index.js';
+import type { AIProviderRunner } from '../agents/agent-runner.js';
+import type { WorkflowLogger } from '../logging/workflow-logger.js';
+import { FileManager } from '../file-system/file-manager.js';
+import { PathResolver } from '../file-system/path-resolver.js';
+import { EpicParser } from '../parsers/epic-parser.js';
+import { PrdParser } from '../parsers/prd-parser.js';
+import { BatchProcessor } from './batch-processor.js';
+import { StoryTypeDetector } from './story-type-detector.js';
+/**
+ * InputDetector interface (to be implemented in Story 4.2)
+ *
+ * Detects the type of input file (PRD, epic, or story pattern)
+ * to determine which phase the workflow should start from.
+ */
+export interface InputDetector {
+    /**
+     * Detect the type of input file
+     *
+     * @param input - Input file path or pattern
+     * @returns Detection result with type, file path, and metadata
+     */
+    detect(input: string): Promise<InputDetectionResult>;
+}
+/**
+ * Configuration object for WorkflowOrchestrator constructor
+ *
+ * Groups all service dependencies into a single configuration object
+ * to reduce constructor parameter count and improve maintainability.
+ */
+export interface WorkflowOrchestratorConfig {
+    /** Service to execute AI agents (Claude or Gemini) */
+    agentRunner: AIProviderRunner;
+    /** Service to handle parallel batch processing */
+    batchProcessor: BatchProcessor;
+    /** Service to parse epic files and extract stories */
+    epicParser: EpicParser;
+    /** Service for file system operations */
+    fileManager: FileManager;
+    /** Service to detect input file type (PRD, epic, or story pattern) */
+    inputDetector: InputDetector;
+    /** Logger instance for structured logging */
+    logger: pino.Logger;
+    /** Service to resolve file paths from config */
+    pathResolver: PathResolver;
+    /** Service to parse PRD files and extract epics */
+    prdParser: PrdParser;
+    /** Service to detect story type for auto-documentation */
+    storyTypeDetector: StoryTypeDetector;
+    /** Optional WorkflowLogger for pipeline progress tracking */
+    workflowLogger?: WorkflowLogger;
+}
+/**
+ * Options for building an epic creation prompt
+ */
+export interface EpicPromptOptions {
+    /** Working directory (optional) */
+    cwd?: string;
+    /** Output file path */
+    outputPath: string;
+    /** Path to PRD file */
+    prdPath: string;
+    /** File name prefix */
+    prefix: string;
+    /** Reference file paths */
+    references: string[];
+}
+/**
+ * Options for building a story creation prompt
+ */
+export interface StoryPromptOptions {
+    /** Working directory (optional) */
+    cwd?: string;
+    /** Path to epic file */
+    epicPath: string;
+    /** Output file path */
+    outputPath: string;
+    /** File name prefix */
+    prefix: string;
+    /** Reference file paths */
+    references: string[];
+}
+/**
+ * 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 declare class WorkflowOrchestrator {
+    private readonly agentRunner;
+    private readonly batchProcessor;
+    private readonly epicParser;
+    private readonly fileManager;
+    private readonly fileScaffolder;
+    private readonly inputDetector;
+    private readonly logger;
+    private readonly pathResolver;
+    private readonly prdFixer;
+    private readonly prdParser;
+    private readonly storyTypeDetector;
+    private readonly workflowLogger?;
+    /**
+     * Create a new WorkflowOrchestrator instance
+     *
+     * @param config - Configuration object containing all service dependencies
+     */
+    constructor(config: WorkflowOrchestratorConfig);
+    /**
+     * 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
+     */
+    execute(config: WorkflowConfig): Promise<WorkflowResult>;
+    /**
+     * Build prompt for epic creation
+     *
+     * @param epic - Epic to create
+     * @param options - Prompt configuration options
+     * @returns Agent prompt
+     * @private
+     */
+    private buildEpicPrompt;
+    /**
+     * Build failure result when epic phase fails completely
+     *
+     * @param startTime - Workflow start time
+     * @param epicPhase - Failed epic phase result
+     * @returns WorkflowResult
+     * @private
+     */
+    private buildFailureResult;
+    /**
+     * Build prompt for story creation
+     *
+     * @param story - Story to create
+     * @param options - Prompt configuration options
+     * @returns Agent prompt
+     * @private
+     */
+    private buildStoryPrompt;
+    /**
+     * 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
+     */
+    private buildSuccessResult;
+    /**
+     * 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
+     */
+    private checkExistingFiles;
+    /**
+     * 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
+     */
+    private checkExistingStoryFiles;
+    /**
+     * 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
+     */
+    private checkProperlyPopulatedEpics;
+    /**
+     * Create a skipped phase result
+     *
+     * @param phaseName - Name of the phase
+     * @returns PhaseResult marked as skipped
+     * @private
+     */
+    private createSkippedPhaseResult;
+    /**
+     * 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
+     */
+    private detectInput;
+    /**
+     * 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
+     */
+    private determinePhaseExecution;
+    /**
+     * 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
+     */
+    private devWorker;
+    /**
+     * 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
+     */
+    private enqueueExistingStoriesSequentially;
+    /**
+     * 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
+     */
+    private executeDevelopmentPhase;
+    /**
+     * 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
+     */
+    private executeEpicPhase;
+    /**
+     * 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
+     */
+    private executeEpicPhaseIfNeeded;
+    /**
+     * 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
+     */
+    private executePipelinedDevPhase;
+    /**
+     * 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
+     */
+    private executePipelinedWorkflow;
+    /**
+     * 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
+     */
+    private executeQaPhase;
+    /**
+     * 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
+     */
+    private executeQaPhaseIfNeeded;
+    /**
+     * 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
+     */
+    private executeSequentialDevPhase;
+    /**
+     * 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
+     */
+    private executeSequentialStoryPhase;
+    /**
+     * 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
+     */
+    private executeSequentialWorkflow;
+    /**
+     * 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
+     */
+    private executeStoryAndDevPhases;
+    /**
+     * 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
+     */
+    private executeStoryPhase;
+    /**
+     * 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
+     */
+    private executeStoryPhaseFromEpicFile;
+    /**
+     * 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
+     */
+    private executeStoryPhaseWithQueue;
+    /**
+     * Extract epic number from file path
+     *
+     * @param filePath - Epic file path (e.g., 'docs/epics/epic-1.md')
+     * @returns Epic number
+     * @private
+     */
+    private extractEpicNumber;
+    /**
+     * Extract story from file path
+     *
+     * @param filePath - Story file path (e.g., 'docs/stories/USER-GROUPS-story-1.001.md')
+     * @returns Story object
+     * @private
+     */
+    private extractStoryFromFilePath;
+    /**
+     * 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
+     */
+    private generateEpicFileName;
+    /**
+     * 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
+     */
+    private generatePrefixFromEpicPath;
+    /**
+     * 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
+     */
+    private generatePrefixFromPrdPath;
+    /**
+     * 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
+     */
+    private generateStoryFileName;
+    /**
+     * Get epics for story phase execution
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @returns Array of epics
+     * @private
+     */
+    private getEpicsForStoryPhase;
+    /**
+     * Get stories for dev phase execution
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @returns Array of stories
+     * @private
+     */
+    private getStoriesForDevPhase;
+    /**
+     * Handle phase result from Promise.allSettled
+     *
+     * @param result - PromiseSettledResult
+     * @param phaseName - Phase name for error reporting
+     * @returns PhaseResult
+     * @private
+     */
+    private handlePhaseResult;
+    /**
+     * Log workflow start information
+     *
+     * @param config - Workflow configuration
+     * @private
+     */
+    private logWorkflowStart;
+    /**
+     * Resolve prefix for story file pattern
+     *
+     * @param config - Workflow configuration
+     * @param detection - Input detection result
+     * @returns Prefix string
+     * @private
+     */
+    private resolvePrefix;
+    /**
+     * Check if workflow should abort after epic phase failure
+     *
+     * @param epicPhase - Epic phase result
+     * @returns True if should abort
+     * @private
+     */
+    private shouldAbortAfterEpicFailure;
+    /**
+     * Check if workflow should abort after story phase failure
+     *
+     * @param storyPhase - Story phase result
+     * @returns True if should abort
+     * @private
+     */
+    private shouldAbortAfterStoryFailure;
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     * @private
+     */
+    private sleep;
+    /**
+     * Update story status in file
+     *
+     * @param storyFilePath - Path to story file
+     * @param status - New status
+     * @private
+     */
+    private updateStoryStatus;
+    /**
+     * Validate workflow configuration
+     *
+     * @param config - Workflow configuration to validate
+     * @throws {ValidationError} If configuration is invalid
+     * @private
+     */
+    private validateConfig;
+}