@hyperdrive.bot/bmad-workflow 1.0.16 → 1.0.18

package/dist/commands/workflow.js

@@ -1,4 +1,5 @@
 import { Args, Command, Flags } from '@oclif/core';
+import { basename } from 'node:path';
 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';
@@ -8,6 +9,8 @@ import { StoryTypeDetector } from '../services/orchestration/story-type-detector
 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 { WorkflowSessionScaffolder } from '../services/scaffolding/workflow-session-scaffolder.js';
+import { WorkflowReporter } from '../services/WorkflowReporter.js';
 import * as colors from '../utils/colors.js';
 import { formatBox, formatTable } from '../utils/formatters.js';
 import { createLogger } from '../utils/logger.js';
@@ -77,7 +80,10 @@ export default class Workflow extends Command {
         }),
         prefix: Flags.string({
             default: '',
-            description: 'Filename prefix for generated files',
+            description: 'Filename prefix for generated files and session directory name',
+        }),
+        'session-prefix': Flags.string({
+            description: 'Session directory prefix (default: derived from input filename, e.g., PRD-feature.md → feature)',
         }),
         provider: Flags.string({
             default: 'claude',
@@ -133,12 +139,15 @@ export default class Workflow extends Command {
         verbose: Flags.boolean({
             char: 'v',
             default: false,
-            description: 'Detailed output mode',
+            description: 'Show detailed output with spawn output streamed inline. In verbose mode, each spawn\'s output is displayed in real-time with visual delimiters. In non-TTY environments (e.g., CI/CD pipelines), output automatically falls back to plain-text format without ANSI escape codes.',
         }),
     };
     cancelled = false;
     logger;
     orchestrator;
+    reporter;
+    scaffolder;
+    sessionDir = null;
     /**
      * Main command execution
      *
@@ -147,14 +156,24 @@ export default class Workflow extends Command {
     async run() {
         const { args, flags } = await this.parse(Workflow);
         try {
+            // Early validation: check input file exists before initializing anything
+            const inputPath = args.input;
+            if (!inputPath.includes('*') && !inputPath.includes('?')) {
+                const { existsSync } = await import('node:fs');
+                if (!existsSync(inputPath)) {
+                    this.error(`File not found: ${inputPath}`, { exit: 1 });
+                }
+            }
             // Validate provider
             if (!isProviderSupported(flags.provider)) {
                 this.error(`Unsupported provider: ${flags.provider}. Use 'claude', 'gemini', or 'opencode'.`, { exit: 1 });
             }
             // Initialize services with parallel concurrency and provider
-            await this.initializeServices(flags.parallel, flags.provider);
+            await this.initializeServices(flags.parallel, flags.provider, flags.verbose);
             // Register signal handlers
             this.registerSignalHandlers();
+            // Initialize session scaffolder and create session structure
+            await this.initializeSession(args.input, flags['session-prefix']);
             // Show dry-run banner if applicable
             if (flags['dry-run']) {
                 this.displayDryRunBanner();
@@ -193,28 +212,289 @@ export default class Workflow extends Command {
             // Execute workflow
             this.log(colors.info('\nStarting workflow orchestration...\n'));
             const result = await this.orchestrator.execute(config);
+            // Wait for reporter listr2 tasks to complete and clean up
+            await this.reporter?.waitForCompletion();
+            // Write session report on completion (includes cancellation case)
+            await this.finalizeSession(result, config);
+            // Build dashboard summary from workflow result
+            const dashboardSummary = this.buildDashboardSummary(result);
+            // Display final dashboard using reporter (AC: #4)
+            this.reporter?.displayFinalDashboard(dashboardSummary);
+            this.reporter?.dispose();
+            // Display failure details if any
+            if (result.totalFailures > 0) {
+                this.displayFailureDetails(result);
+            }
+            // Dry run reminder
+            if (config.dryRun) {
+                this.log('\n' + colors.warning('No files were created (dry-run mode)'));
+            }
             // 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!'));
+            this.log('\n' + colors.success('Workflow completed successfully!'));
         }
         catch (error) {
-            this.logger.error({ error: error.message }, 'Workflow command failed');
+            // Clean up reporter on error
+            this.reporter?.dispose();
+            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 });
         }
     }
+    /**
+     * Collect all errors from workflow result into a flat list
+     *
+     * @param result - Workflow execution result
+     * @returns Array of error entries with phase context
+     * @private
+     */
+    collectErrors(result) {
+        const errors = [];
+        const now = new Date().toISOString();
+        if (result.epicPhase?.failures) {
+            for (const failure of result.epicPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'epic',
+                    timestamp: now,
+                });
+            }
+        }
+        if (result.storyPhase?.failures) {
+            for (const failure of result.storyPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'story',
+                    timestamp: now,
+                });
+            }
+        }
+        if (result.devPhase?.failures) {
+            for (const failure of result.devPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'dev',
+                    timestamp: now,
+                });
+            }
+        }
+        if (result.qaPhase?.failures) {
+            for (const failure of result.qaPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'qa',
+                    timestamp: now,
+                });
+            }
+        }
+        return errors;
+    }
+    /**
+     * Build dashboard summary from workflow result for final display
+     *
+     * @param result - Workflow execution result
+     * @returns DashboardSummary for the reporter's final dashboard
+     * @private
+     */
+    buildDashboardSummary(result) {
+        const phases = [];
+        // Add phases in order: epic, story, dev, qa
+        if (result.epicPhase && !result.epicPhase.skipped) {
+            phases.push({
+                duration: result.epicPhase.duration,
+                failed: result.epicPhase.failures.length,
+                name: 'epic',
+                passed: result.epicPhase.success,
+            });
+        }
+        if (result.storyPhase && !result.storyPhase.skipped) {
+            phases.push({
+                duration: result.storyPhase.duration,
+                failed: result.storyPhase.failures.length,
+                name: 'story',
+                passed: result.storyPhase.success,
+            });
+        }
+        if (result.devPhase && !result.devPhase.skipped) {
+            phases.push({
+                duration: result.devPhase.duration,
+                failed: result.devPhase.failures.length,
+                name: 'dev',
+                passed: result.devPhase.success,
+            });
+        }
+        if (result.qaPhase && !result.qaPhase.skipped) {
+            phases.push({
+                duration: result.qaPhase.duration,
+                failed: result.qaPhase.failures.length,
+                name: 'qa',
+                passed: result.qaPhase.success,
+            });
+        }
+        // Build session report path from session directory
+        const sessionReportPath = this.sessionDir ? `${this.sessionDir}/SESSION_REPORT.md` : undefined;
+        return {
+            failedCount: result.totalFailures,
+            passedCount: result.totalFilesProcessed - result.totalFailures,
+            phases,
+            sessionReportPath,
+            totalDuration: result.totalDuration,
+            totalSpawns: result.totalFilesProcessed,
+        };
+    }
+    /**
+     * Create callbacks object wired to scaffolder for incremental artifact writing
+     *
+     * All callbacks are wrapped in try-catch to prevent scaffolder errors from
+     * interrupting workflow execution (AC: #9).
+     * @returns WorkflowCallbacks object with scaffolder integration
+     * @private
+     */
+    createScaffolderCallbacks() {
+        return {
+            onSpawnComplete: (context) => {
+                // Write spawn output immediately for crash resilience (AC: #8)
+                try {
+                    // Map phaseName to spawn type
+                    const typeMap = {
+                        dev: 'dev',
+                        epic: 'epic',
+                        story: 'story',
+                    };
+                    const spawnType = typeMap[context.phaseName] || 'dev';
+                    // Fire-and-forget write to not block workflow
+                    this.scaffolder
+                        .writeSpawnOutput({
+                        completedAt: context.endTime ? new Date(context.endTime).toISOString() : undefined,
+                        content: context.output || '',
+                        duration: context.duration,
+                        errors: context.error,
+                        spawnId: context.spawnId,
+                        success: context.success,
+                        type: spawnType,
+                    })
+                        .catch((writeError) => {
+                        this.logger.warn({ error: writeError.message, spawnId: context.spawnId }, 'Async spawn output write failed');
+                    });
+                }
+                catch (error) {
+                    // Log but don't propagate - workflow must continue (AC: #9)
+                    this.logger.warn({ error: error.message, spawnId: context.spawnId }, 'Failed to write spawn output');
+                }
+            },
+        };
+    }
+    /**
+     * Merge multiple callback objects into a single callbacks object
+     *
+     * When the same callback is defined in multiple sources, all handlers are called
+     * in sequence (fire-and-forget). This enables dual-channel output where scaffolder
+     * and reporter receive events independently.
+     *
+     * @param sources - Array of WorkflowCallbacks objects to merge
+     * @returns Merged WorkflowCallbacks object
+     * @private
+     */
+    mergeCallbacks(...sources) {
+        const merged = {};
+        const callbackNames = [
+            'onPhaseStart',
+            'onPhaseComplete',
+            'onLayerStart',
+            'onLayerComplete',
+            'onSpawnStart',
+            'onSpawnComplete',
+            'onSpawnOutput',
+            'onError',
+        ];
+        for (const name of callbackNames) {
+            const handlers = sources.map((s) => s[name]).filter(Boolean);
+            if (handlers.length > 0) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ;
+                merged[name] = (...args) => {
+                    for (const handler of handlers) {
+                        try {
+                            handler(...args);
+                        }
+                        catch (error) {
+                            // Fire-and-forget: log but don't propagate callback errors
+                            const errMsg = error instanceof Error ? error.message : String(error);
+                            this.logger?.warn({ callback: name, error: errMsg }, 'Callback error');
+                        }
+                    }
+                };
+            }
+        }
+        return merged;
+    }
+    /**
+     * Derive session prefix from input filename
+     *
+     * Extracts meaningful prefix from input path:
+     * - PRD-feature.md → feature
+     * - PRD-my-project.md → my-project
+     * - epic-001.md → epic-001
+     *
+     * @param inputPath - Input file path
+     * @returns Derived prefix string
+     * @private
+     */
+    derivePrefixFromFilename(inputPath) {
+        const filename = basename(inputPath, '.md');
+        // Handle PRD-* pattern
+        if (filename.startsWith('PRD-')) {
+            return filename.slice(4); // Remove 'PRD-' prefix
+        }
+        // Use filename as-is for other patterns
+        return filename;
+    }
+    /**
+     * Display detailed failure information for each phase
+     *
+     * @param result - Workflow result with all phase data
+     * @private
+     */
+    displayFailureDetails(result) {
+        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}`));
+            }
+        }
+    }
     /**
      * Display dry-run banner
      *
@@ -337,6 +617,11 @@ export default class Workflow extends Command {
         if (config.dryRun) {
             this.log('\n' + colors.warning('No files were created (dry-run mode)'));
         }
+        // Display session directory path (AC: #7)
+        if (this.sessionDir) {
+            const sessionBanner = formatBox('Session Directory', `${this.sessionDir}\n\nView spawn outputs, session report, and workflow log at this location.`);
+            this.log('\n' + colors.info(sessionBanner));
+        }
     }
     /**
      * Display phase header with visual separator
@@ -353,17 +638,73 @@ export default class Workflow extends Command {
         this.log(colors.bold(`║  ${header}  ║`));
         this.log(colors.bold(`╚${separator}╝`) + '\n');
     }
+    /**
+     * Finalize session by writing session report and workflow log
+     *
+     * Called on workflow completion (success or failure).
+     * Errors are caught and logged but don't interrupt workflow completion.
+     *
+     * @param result - Workflow execution result
+     * @param _config - Workflow configuration used (unused for now)
+     * @private
+     */
+    async finalizeSession(result, _config) {
+        if (!this.sessionDir) {
+            this.logger.warn('Session directory not initialized, skipping session finalization');
+            return;
+        }
+        try {
+            // Build session report summary from workflow result
+            const sessionId = basename(this.sessionDir);
+            const now = new Date().toISOString();
+            const summary = {
+                duration: result.totalDuration,
+                endedAt: now,
+                errors: this.collectErrors(result),
+                overallSuccess: result.overallSuccess,
+                phases: {
+                    developments: {
+                        completed: result.devPhase?.success ?? 0,
+                        failed: result.devPhase?.failures.length ?? 0,
+                        total: (result.devPhase?.success ?? 0) + (result.devPhase?.failures.length ?? 0),
+                    },
+                    epics: {
+                        completed: result.epicPhase?.success ?? 0,
+                        failed: result.epicPhase?.failures.length ?? 0,
+                        total: (result.epicPhase?.success ?? 0) + (result.epicPhase?.failures.length ?? 0),
+                    },
+                    stories: {
+                        completed: result.storyPhase?.success ?? 0,
+                        failed: result.storyPhase?.failures.length ?? 0,
+                        total: (result.storyPhase?.success ?? 0) + (result.storyPhase?.failures.length ?? 0),
+                    },
+                },
+                sessionId,
+                spawnFiles: [], // Will be populated by scaffolder internals if needed
+                startedAt: new Date(Date.now() - result.totalDuration).toISOString(),
+            };
+            await this.scaffolder.writeSessionReport(summary);
+            this.logger.info({ sessionDir: this.sessionDir }, 'Session report written');
+            // Note: workflow-log.yaml would require WorkflowLogger integration
+            // which is optional per the orchestrator config. For now, session report
+            // is the primary artifact.
+        }
+        catch (error) {
+            this.logger.warn({ error: error.message }, 'Failed to finalize session');
+        }
+    }
     /**
      * 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)
+     * @param verbose - Enable verbose output mode
      * @private
      */
-    async initializeServices(maxConcurrency = 3, provider = 'claude') {
-        // Create logger
-        this.logger = createLogger({ namespace: 'commands:workflow' });
+    async initializeServices(maxConcurrency = 3, provider = 'claude', verbose = false) {
+        // Create logger — suppress INFO logs in non-verbose mode to keep terminal clean
+        this.logger = createLogger({ level: verbose ? 'info' : 'warn', namespace: 'commands:workflow' });
         this.logger.info({ provider }, 'Initializing services with AI provider');
         // Create file system services
         const fileManager = new FileManager(this.logger);
@@ -379,10 +720,20 @@ export default class Workflow extends Command {
         const inputDetector = new InputDetector(fileManager, this.logger);
         // Create story type detector for auto-documentation
         const storyTypeDetector = new StoryTypeDetector(this.logger);
-        // Create orchestrator
+        // Create session scaffolder for workflow artifacts
+        this.scaffolder = new WorkflowSessionScaffolder(fileManager, this.logger);
+        // Create workflow reporter for live progress visualization (AC: #1)
+        this.reporter = new WorkflowReporter({
+            nonTTY: !process.stdout.isTTY,
+            verbose,
+        });
+        // Merge scaffolder callbacks with reporter callbacks for dual-channel output (AC: #1)
+        const callbacks = this.mergeCallbacks(this.createScaffolderCallbacks(), this.reporter.getCallbacks());
+        // Create orchestrator with merged callbacks
         this.orchestrator = new WorkflowOrchestrator({
             agentRunner,
             batchProcessor,
+            callbacks,
             epicParser,
             fileManager,
             inputDetector,
@@ -391,7 +742,29 @@ export default class Workflow extends Command {
             prdParser,
             storyTypeDetector,
         });
-        this.logger.info({ provider }, 'Services initialized successfully');
+        this.logger.info({ provider, verbose }, 'Services initialized successfully');
+    }
+    /**
+     * Initialize session scaffolder and create session directory structure
+     *
+     * @param inputPath - Input file path for prefix derivation
+     * @param sessionPrefix - Optional explicit session prefix
+     * @private
+     */
+    async initializeSession(inputPath, sessionPrefix) {
+        try {
+            // Derive prefix: explicit flag > derived from filename
+            const prefix = sessionPrefix || this.derivePrefixFromFilename(inputPath);
+            this.sessionDir = await this.scaffolder.createSessionStructure({
+                baseDir: 'docs/workflow-sessions',
+                prefix,
+            });
+            this.logger.info({ prefix, sessionDir: this.sessionDir }, 'Workflow session initialized');
+        }
+        catch (error) {
+            // Log but don't fail workflow - session is optional (AC: #9)
+            this.logger.warn({ error: error.message }, 'Failed to initialize session structure');
+        }
     }
     /**
      * Register SIGINT handler for graceful cancellation

package/dist/models/index.d.ts

@@ -6,5 +6,6 @@ export * from './agent-result.js';
 export * from './phase-result.js';
 export * from './provider.js';
 export * from './story.js';
+export * from './workflow-callbacks.js';
 export * from './workflow-config.js';
 export * from './workflow-result.js';

package/dist/models/index.js

@@ -6,5 +6,6 @@ export * from './agent-result.js';
 export * from './phase-result.js';
 export * from './provider.js';
 export * from './story.js';
+export * from './workflow-callbacks.js';
 export * from './workflow-config.js';
 export * from './workflow-result.js';