@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/commands/workflow.d.ts

@@ -0,0 +1,97 @@
+import { Command } from '@oclif/core';
+/**
+ * Workflow Command
+ *
+ * Orchestrates the complete PRD → Epic → Story → Dev pipeline from a single entry point.
+ * Provides visual progress indicators, dry-run support, and graceful cancellation.
+ *
+ * @example
+ * ```bash
+ * # Start workflow from PRD
+ * bmad-workflow workflow docs/PRD-feature.md
+ *
+ * # Start from epic, skip dev
+ * bmad-workflow workflow docs/epics/epic-1.md --skip-dev
+ *
+ * # Dry run to preview actions
+ * bmad-workflow workflow docs/PRD-feature.md --dry-run
+ * ```
+ */
+export default class Workflow extends Command {
+    static args: {
+        input: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'auto-fix': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        cwd: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'epic-interval': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        parallel: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        pipeline: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'prd-interval': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        prefix: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        qa: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'qa-prompt': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'qa-retries': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        reference: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'skip-dev': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'skip-epics': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'skip-stories': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'story-interval': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    private cancelled;
+    private logger;
+    private orchestrator;
+    /**
+     * Main command execution
+     *
+     * Orchestrates the complete workflow with progress tracking and summary display.
+     */
+    run(): Promise<void>;
+    /**
+     * Display dry-run banner
+     *
+     * Shows prominent message that workflow is in dry-run mode.
+     * @private
+     */
+    private displayDryRunBanner;
+    /**
+     * Display final summary with phase results
+     *
+     * Shows table with success/failure counts and durations for each phase.
+     *
+     * @param result - Workflow result with all phase data
+     * @param config - Workflow configuration used
+     * @private
+     */
+    private displayFinalSummary;
+    /**
+     * Display phase header with visual separator
+     *
+     * @param phaseNumber - Current phase number (1-based)
+     * @param totalPhases - Total number of phases
+     * @param phaseName - Name of the phase
+     * @private
+     */
+    private displayPhaseHeader;
+    /**
+     * Initialize services and dependencies
+     *
+     * Creates all service instances needed for workflow orchestration.
+     * @param maxConcurrency - Maximum number of concurrent operations
+     * @param provider - AI provider to use (claude or gemini)
+     * @private
+     */
+    private initializeServices;
+    /**
+     * Register SIGINT handler for graceful cancellation
+     *
+     * Allows user to cancel workflow with Ctrl+C, completing current operation first.
+     * @private
+     */
+    private registerSignalHandlers;
+}

package/dist/commands/workflow.js

@@ -0,0 +1,390 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { createAgentRunner, isProviderSupported } from '../services/agents/agent-runner-factory.js';
+import { FileManager } from '../services/file-system/file-manager.js';
+import { PathResolver } from '../services/file-system/path-resolver.js';
+import { BatchProcessor } from '../services/orchestration/batch-processor.js';
+import { InputDetector } from '../services/orchestration/input-detector.js';
+import { StoryTypeDetector } from '../services/orchestration/story-type-detector.js';
+import { WorkflowOrchestrator } from '../services/orchestration/workflow-orchestrator.js';
+import { EpicParser } from '../services/parsers/epic-parser.js';
+import { PrdParser } from '../services/parsers/prd-parser.js';
+import * as colors from '../utils/colors.js';
+import { formatBox, formatTable } from '../utils/formatters.js';
+import { createLogger } from '../utils/logger.js';
+/**
+ * Workflow Command
+ *
+ * Orchestrates the complete PRD → Epic → Story → Dev pipeline from a single entry point.
+ * Provides visual progress indicators, dry-run support, and graceful cancellation.
+ *
+ * @example
+ * ```bash
+ * # Start workflow from PRD
+ * bmad-workflow workflow docs/PRD-feature.md
+ *
+ * # Start from epic, skip dev
+ * bmad-workflow workflow docs/epics/epic-1.md --skip-dev
+ *
+ * # Dry run to preview actions
+ * bmad-workflow workflow docs/PRD-feature.md --dry-run
+ * ```
+ */
+export default class Workflow extends Command {
+    static args = {
+        input: Args.string({
+            description: 'PRD file, epic file, or story pattern to start workflow from',
+            required: true,
+        }),
+    };
+    static description = 'Execute complete PRD → Epic → Story → Dev workflow with progress tracking';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> docs/PRD-feature.md',
+        '<%= config.bin %> <%= command.id %> docs/epics/epic-1.md --skip-dev',
+        '<%= config.bin %> <%= command.id %> docs/PRD-feature.md --dry-run --verbose',
+        '<%= config.bin %> <%= command.id %> "docs/stories/STORY-*.md" --skip-epics --skip-stories',
+    ];
+    static flags = {
+        'auto-fix': Flags.boolean({
+            default: false,
+            description: 'Auto-fix PRD format using AI when parsing fails',
+        }),
+        cwd: Flags.string({
+            description: 'Working directory path to pass to AI agents. Agents will operate in this directory.',
+        }),
+        'dry-run': Flags.boolean({
+            default: false,
+            description: 'Preview actions without execution',
+        }),
+        'epic-interval': Flags.integer({
+            default: 60,
+            description: 'Seconds between story creation batches',
+        }),
+        parallel: Flags.integer({
+            default: 3,
+            description: 'Max concurrent epic/story creations',
+        }),
+        pipeline: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Enable pipelined workflow (start dev on stories sequentially as they are created)',
+        }),
+        'prd-interval': Flags.integer({
+            default: 60,
+            description: 'Seconds between epic creation batches',
+        }),
+        prefix: Flags.string({
+            default: '',
+            description: 'Filename prefix for generated files',
+        }),
+        provider: Flags.string({
+            default: 'claude',
+            description: 'AI provider to use (claude or gemini)',
+            options: ['claude', 'gemini'],
+        }),
+        qa: Flags.boolean({
+            default: false,
+            description: 'Run QA workflow after development completes',
+            helpGroup: 'QA Workflow',
+        }),
+        'qa-prompt': Flags.string({
+            description: 'Custom prompt/instructions for QA review phase',
+            helpGroup: 'QA Workflow',
+        }),
+        'qa-retries': Flags.integer({
+            default: 2,
+            description: 'Maximum QA → Dev fix cycles (only used with --qa)',
+            helpGroup: 'QA Workflow',
+        }),
+        reference: Flags.string({
+            description: 'Additional context files for AI agents (can be used multiple times)',
+            multiple: true,
+        }),
+        'skip-dev': Flags.boolean({
+            default: false,
+            description: 'Skip development phase',
+        }),
+        'skip-epics': Flags.boolean({
+            default: false,
+            description: 'Skip epic creation phase',
+        }),
+        'skip-stories': Flags.boolean({
+            default: false,
+            description: 'Skip story creation phase',
+        }),
+        'story-interval': Flags.integer({
+            default: 60,
+            description: 'Seconds between story development',
+        }),
+        verbose: Flags.boolean({
+            char: 'v',
+            default: false,
+            description: 'Detailed output mode',
+        }),
+    };
+    cancelled = false;
+    logger;
+    orchestrator;
+    /**
+     * Main command execution
+     *
+     * Orchestrates the complete workflow with progress tracking and summary display.
+     */
+    async run() {
+        const { args, flags } = await this.parse(Workflow);
+        try {
+            // Validate provider
+            if (!isProviderSupported(flags.provider)) {
+                this.error(`Unsupported provider: ${flags.provider}. Use 'claude' or 'gemini'.`, { exit: 1 });
+            }
+            // Initialize services with parallel concurrency and provider
+            await this.initializeServices(flags.parallel, flags.provider);
+            // Register signal handlers
+            this.registerSignalHandlers();
+            // Show dry-run banner if applicable
+            if (flags['dry-run']) {
+                this.displayDryRunBanner();
+            }
+            // Build workflow configuration
+            const config = {
+                autoFix: flags['auto-fix'],
+                cwd: flags.cwd,
+                dryRun: flags['dry-run'],
+                epicInterval: flags['epic-interval'],
+                input: args.input,
+                parallel: flags.parallel,
+                pipeline: flags.pipeline,
+                prdInterval: flags['prd-interval'],
+                prefix: flags.prefix,
+                provider: flags.provider,
+                qa: flags.qa,
+                qaPrompt: flags['qa-prompt'],
+                qaRetries: flags['qa-retries'],
+                references: flags.reference || [],
+                skipDev: flags['skip-dev'],
+                skipEpics: flags['skip-epics'],
+                skipStories: flags['skip-stories'],
+                storyInterval: flags['story-interval'],
+                verbose: flags.verbose,
+            };
+            // Log configuration if verbose
+            if (flags.verbose) {
+                this.logger.info({ config }, 'Workflow configuration');
+                this.log(colors.info(`Pipeline mode: ${config.pipeline ? 'enabled' : 'disabled'}`));
+            }
+            // Execute workflow
+            this.log(colors.info('\nStarting workflow orchestration...\n'));
+            const result = await this.orchestrator.execute(config);
+            // Check for cancellation
+            if (this.cancelled) {
+                this.log('\n' + colors.warning('Workflow cancelled by user'));
+                this.displayFinalSummary(result, config);
+                process.exit(130); // Standard interrupted exit code
+            }
+            // Display final summary
+            this.displayFinalSummary(result, config);
+            // Exit with appropriate code
+            if (!result.overallSuccess) {
+                this.error('Workflow completed with failures', { exit: 1 });
+            }
+            this.log('\n' + colors.success('✓ Workflow completed successfully!'));
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Workflow command failed');
+            // Display user-friendly error
+            this.log('\n' + colors.error('✗ Workflow failed:'));
+            this.log(colors.error(`  ${error.message}`));
+            this.error('Workflow execution failed', { exit: 1 });
+        }
+    }
+    /**
+     * Display dry-run banner
+     *
+     * Shows prominent message that workflow is in dry-run mode.
+     * @private
+     */
+    displayDryRunBanner() {
+        const banner = formatBox('DRY RUN MODE', 'Actions will be previewed but NOT executed.\nNo files will be created or modified.');
+        this.log('\n' + colors.warning(banner));
+    }
+    /**
+     * Display final summary with phase results
+     *
+     * Shows table with success/failure counts and durations for each phase.
+     *
+     * @param result - Workflow result with all phase data
+     * @param config - Workflow configuration used
+     * @private
+     */
+    // eslint-disable-next-line complexity -- Display method with multiple phases to format
+    displayFinalSummary(result, config) {
+        this.log('\n' + colors.bold('╔════════════════════════════════════════════════════════╗'));
+        this.log(colors.bold('║                   Workflow Summary                     ║'));
+        this.log(colors.bold('╚════════════════════════════════════════════════════════╝') + '\n');
+        // Build table rows
+        const rows = [];
+        if (result.epicPhase) {
+            const status = result.epicPhase.skipped
+                ? colors.dim('Skipped')
+                : result.epicPhase.failures.length > 0
+                    ? colors.error(`${result.epicPhase.failures.length} failed`)
+                    : colors.success('✓ Complete');
+            rows.push([
+                'Epic Creation',
+                result.epicPhase.success.toString(),
+                result.epicPhase.failures.length.toString(),
+                `${(result.epicPhase.duration / 1000).toFixed(1)}s`,
+                status,
+            ]);
+        }
+        if (result.storyPhase) {
+            const status = result.storyPhase.skipped
+                ? colors.dim('Skipped')
+                : result.storyPhase.failures.length > 0
+                    ? colors.error(`${result.storyPhase.failures.length} failed`)
+                    : colors.success('✓ Complete');
+            rows.push([
+                'Story Creation',
+                result.storyPhase.success.toString(),
+                result.storyPhase.failures.length.toString(),
+                `${(result.storyPhase.duration / 1000).toFixed(1)}s`,
+                status,
+            ]);
+        }
+        if (result.devPhase) {
+            const status = result.devPhase.skipped
+                ? colors.dim('Skipped')
+                : result.devPhase.failures.length > 0
+                    ? colors.error(`${result.devPhase.failures.length} failed`)
+                    : colors.success('✓ Complete');
+            rows.push([
+                'Development',
+                result.devPhase.success.toString(),
+                result.devPhase.failures.length.toString(),
+                `${(result.devPhase.duration / 1000).toFixed(1)}s`,
+                status,
+            ]);
+        }
+        if (result.qaPhase && !result.qaPhase.skipped) {
+            const status = result.qaPhase.failures.length > 0
+                ? colors.error(`${result.qaPhase.failures.length} failed`)
+                : colors.success('✓ Complete');
+            rows.push([
+                'QA Review',
+                result.qaPhase.success.toString(),
+                result.qaPhase.failures.length.toString(),
+                `${(result.qaPhase.duration / 1000).toFixed(1)}s`,
+                status,
+            ]);
+        }
+        // Add totals row
+        rows.push([
+            colors.bold('Total'),
+            colors.bold(result.totalFilesProcessed.toString()),
+            colors.bold(result.totalFailures.toString()),
+            colors.bold(`${(result.totalDuration / 1000).toFixed(1)}s`),
+            result.overallSuccess ? colors.success('✓ Success') : colors.error('✗ Failed'),
+        ]);
+        const table = formatTable(['Phase', 'Success', 'Failed', 'Duration', 'Status'], rows);
+        this.log(table);
+        // Display failures if any
+        if (result.totalFailures > 0) {
+            this.log('\n' + colors.error('Failures:'));
+            if (result.epicPhase?.failures.length) {
+                this.log(colors.error(`  Epic Phase:`));
+                for (const failure of result.epicPhase.failures) {
+                    this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+                }
+            }
+            if (result.storyPhase?.failures.length) {
+                this.log(colors.error(`  Story Phase:`));
+                for (const failure of result.storyPhase.failures) {
+                    this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+                }
+            }
+            if (result.devPhase?.failures.length) {
+                this.log(colors.error(`  Development Phase:`));
+                for (const failure of result.devPhase.failures) {
+                    this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+                }
+            }
+            if (result.qaPhase?.failures.length) {
+                this.log(colors.error(`  QA Phase:`));
+                for (const failure of result.qaPhase.failures) {
+                    this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+                }
+            }
+        }
+        // Dry run reminder
+        if (config.dryRun) {
+            this.log('\n' + colors.warning('No files were created (dry-run mode)'));
+        }
+    }
+    /**
+     * Display phase header with visual separator
+     *
+     * @param phaseNumber - Current phase number (1-based)
+     * @param totalPhases - Total number of phases
+     * @param phaseName - Name of the phase
+     * @private
+     */
+    displayPhaseHeader(phaseNumber, totalPhases, phaseName) {
+        const header = `Phase ${phaseNumber}/${totalPhases}: ${phaseName}`;
+        const separator = '═'.repeat(header.length + 4);
+        this.log('\n' + colors.bold(`╔${separator}╗`));
+        this.log(colors.bold(`║  ${header}  ║`));
+        this.log(colors.bold(`╚${separator}╝`) + '\n');
+    }
+    /**
+     * Initialize services and dependencies
+     *
+     * Creates all service instances needed for workflow orchestration.
+     * @param maxConcurrency - Maximum number of concurrent operations
+     * @param provider - AI provider to use (claude or gemini)
+     * @private
+     */
+    async initializeServices(maxConcurrency = 3, provider = 'claude') {
+        // Create logger
+        this.logger = createLogger({ namespace: 'commands:workflow' });
+        this.logger.info({ provider }, 'Initializing services with AI provider');
+        // Create file system services
+        const fileManager = new FileManager(this.logger);
+        const pathResolver = new PathResolver(fileManager, this.logger);
+        // Create parser services
+        const prdParser = new PrdParser(this.logger);
+        const epicParser = new EpicParser(this.logger);
+        // Create agent runner using factory (supports Claude or Gemini)
+        const agentRunner = createAgentRunner(provider, this.logger);
+        // Create batch processor with configured concurrency
+        const batchProcessor = new BatchProcessor(maxConcurrency, 0, this.logger);
+        // Create input detector
+        const inputDetector = new InputDetector(fileManager, this.logger);
+        // Create story type detector for auto-documentation
+        const storyTypeDetector = new StoryTypeDetector(this.logger);
+        // Create orchestrator
+        this.orchestrator = new WorkflowOrchestrator({
+            agentRunner,
+            batchProcessor,
+            epicParser,
+            fileManager,
+            inputDetector,
+            logger: this.logger,
+            pathResolver,
+            prdParser,
+            storyTypeDetector,
+        });
+        this.logger.info({ provider }, 'Services initialized successfully');
+    }
+    /**
+     * Register SIGINT handler for graceful cancellation
+     *
+     * Allows user to cancel workflow with Ctrl+C, completing current operation first.
+     * @private
+     */
+    registerSignalHandlers() {
+        process.on('SIGINT', () => {
+            this.cancelled = true;
+            this.logger.warn('Cancellation requested... completing current operation');
+            this.log('\n' + colors.warning('⚠️  Cancellation requested... completing current operation'));
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/models/agent-options.d.ts

@@ -0,0 +1,50 @@
+import type { AgentResult } from './agent-result.js';
+/**
+ * Available BMAD agent types
+ */
+export type AgentType = 'analyst' | 'architect' | 'dev' | 'pm' | 'prd-fixer' | 'quick-flow-solo-dev' | 'sm' | 'tea' | 'tech-writer' | 'ux-designer';
+/**
+ * Agent options without prompt and callbacks (used internally)
+ */
+export type AgentOptionsWithoutPrompt = Omit<AgentOptions, 'onPrompt' | 'onResponse' | 'prompt'>;
+/**
+ * Callback invoked when a prompt is about to be sent to Claude
+ */
+export type OnPromptCallback = (prompt: string, options: AgentOptionsWithoutPrompt) => Promise<void> | void;
+/**
+ * Callback invoked when a response is received from Claude
+ */
+export type OnResponseCallback = (result: AgentResult) => Promise<void> | void;
+/**
+ * Options for executing a Claude AI agent
+ */
+export interface AgentOptions {
+    /**
+     * The type of agent to execute
+     */
+    agentType: AgentType;
+    /**
+     * Additional CLI flags to pass to the Claude executable
+     */
+    flags?: string[];
+    /**
+     * Callback invoked when prompt is sent (for logging)
+     */
+    onPrompt?: OnPromptCallback;
+    /**
+     * Callback invoked when response is received (for logging)
+     */
+    onResponse?: OnResponseCallback;
+    /**
+     * The prompt to execute with the agent
+     */
+    prompt: string;
+    /**
+     * File references to include in the agent execution
+     */
+    references?: string[];
+    /**
+     * Timeout in milliseconds (default: 1800000ms = 30 minutes)
+     */
+    timeout?: number;
+}

package/dist/models/agent-options.js

@@ -0,0 +1 @@
+export {};

package/dist/models/agent-result.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result of executing a Claude AI agent
+ */
+export interface AgentResult {
+    /**
+     * The type of agent that was executed
+     */
+    agentType: string;
+    /**
+     * Execution duration in milliseconds
+     */
+    duration: number;
+    /**
+     * Error messages from stderr
+     */
+    errors: string;
+    /**
+     * The process exit code
+     */
+    exitCode: number;
+    /**
+     * The output from stdout
+     */
+    output: string;
+    /**
+     * Whether the agent execution was successful
+     */
+    success: boolean;
+}

package/dist/models/agent-result.js

@@ -0,0 +1 @@
+export {};

package/dist/models/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Model exports
+ */
+export * from './agent-options.js';
+export * from './agent-result.js';
+export * from './phase-result.js';
+export * from './provider.js';
+export * from './story.js';
+export * from './workflow-config.js';
+export * from './workflow-result.js';

package/dist/models/index.js

@@ -0,0 +1,10 @@
+/**
+ * Model exports
+ */
+export * from './agent-options.js';
+export * from './agent-result.js';
+export * from './phase-result.js';
+export * from './provider.js';
+export * from './story.js';
+export * from './workflow-config.js';
+export * from './workflow-result.js';

package/dist/models/phase-result.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Phase Result
+ *
+ * Represents the result of executing a single workflow phase
+ * (epic creation, story creation, or development).
+ */
+/**
+ * Result of a single workflow phase execution
+ *
+ * Tracks successes, failures, and execution metrics for a phase.
+ * Phases include epic creation, story creation, and development.
+ */
+export interface PhaseResult {
+    /**
+     * Execution time in milliseconds
+     *
+     * Time from phase start to phase completion.
+     */
+    duration: number;
+    /**
+     * Details of failed operations
+     *
+     * Empty array if all operations succeeded.
+     */
+    failures: PhaseFailure[];
+    /**
+     * Name of the phase that was executed
+     *
+     * One of: 'epic', 'story', 'dev'
+     */
+    phaseName: string;
+    /**
+     * Phase was skipped
+     *
+     * True if phase was skipped due to flag (skipEpics, skipStories, skipDev)
+     * or due to input type (e.g., starting from epic file skips epic phase).
+     * @default false
+     */
+    skipped: boolean;
+    /**
+     * Count of successful operations in this phase
+     *
+     * For epic phase: number of epics created successfully
+     * For story phase: number of stories created successfully
+     * For dev phase: number of stories developed successfully
+     */
+    success: number;
+}
+/**
+ * Details of a single failure within a phase
+ */
+export interface PhaseFailure {
+    /**
+     * Error message describing the failure
+     */
+    error: string;
+    /**
+     * Identifier for the failed operation
+     *
+     * For epic phase: epic number (e.g., '1', '2')
+     * For story phase: story number (e.g., '1.1', '2.3')
+     * For dev phase: story file path
+     */
+    identifier: string;
+}

package/dist/models/phase-result.js

@@ -0,0 +1,7 @@
+/**
+ * Phase Result
+ *
+ * Represents the result of executing a single workflow phase
+ * (epic creation, story creation, or development).
+ */
+export {};