@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/commands/stories/develop.js

@@ -0,0 +1,460 @@
+/**
+ * Stories Develop Command
+ *
+ * Executes development workflow for stories matching glob patterns sequentially.
+ * Updates story status from Draft to Ready, spawns Claude dev agents, and moves
+ * completed stories to QA folder. Optionally runs QA workflow after development.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow stories develop "docs/stories/AUTH-*.md"
+ * bmad-workflow stories develop "stories/**-auth-*.md" --interval 60
+ * bmad-workflow stories develop "stories/*.md" --reference docs/architecture.md
+ * bmad-workflow stories develop "stories/*.md" --qa --qa-retries 2
+ * ```
+ */
+import { Args, Command, Flags } from '@oclif/core';
+import path from 'node:path';
+import { isEpicStory } from '../../models/story.js';
+import { createAgentRunner } from '../../services/agents/agent-runner-factory.js';
+import { FileManager } from '../../services/file-system/file-manager.js';
+import { GlobMatcher } from '../../services/file-system/glob-matcher.js';
+import { PathResolver } from '../../services/file-system/path-resolver.js';
+import { StoryTypeDetector } from '../../services/orchestration/story-type-detector.js';
+import { StoryParserFactory } from '../../services/parsers/story-parser-factory.js';
+import * as colors from '../../utils/colors.js';
+import { createLogger, generateCorrelationId } from '../../utils/logger.js';
+import { createSpinner } from '../../utils/progress.js';
+import { agentFlags } from '../../utils/shared-flags.js';
+/**
+ * Agent timeout in milliseconds (30 minutes)
+ * Dev agents need sufficient time for comprehensive implementation
+ */
+const DEV_AGENT_TIMEOUT_MS = 1_800_000;
+/**
+ * Stories Develop Command
+ *
+ * Develops stories sequentially using Claude AI dev agents.
+ * CRITICAL: No parallel execution - stories are developed one at a time to prevent conflicts.
+ */
+export default class StoriesDevelopCommand extends Command {
+    static args = {
+        pattern: Args.string({
+            description: 'Glob pattern to match story files',
+            required: true,
+        }),
+    };
+    static description = 'Execute development workflow for stories matching glob pattern (sequential only)';
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %> "docs/stories/AUTH-*.md"',
+            description: 'Develop all AUTH stories',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "**/*-auth-*.md" --interval 60',
+            description: 'Develop stories with 60s countdown between each',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --reference docs/architecture.md',
+            description: 'Develop stories with architecture reference',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --agent qa --task review-story',
+            description: 'Use QA agent with custom task instead of dev agent',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --qa',
+            description: 'Develop stories and automatically run QA workflow after',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --qa --qa-retries 3',
+            description: 'Develop with QA workflow using 3 fix-forward retries',
+        },
+    ];
+    static flags = {
+        ...agentFlags,
+        interval: Flags.integer({
+            default: 30,
+            description: 'Seconds to wait between stories',
+        }),
+        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 dev agents',
+            multiple: true,
+        }),
+    };
+    // Service instances
+    agentRunner;
+    fileManager;
+    globMatcher;
+    logger;
+    pathResolver;
+    storyParserFactory;
+    storyTypeDetector;
+    /**
+     * Run the command
+     */
+    async run() {
+        const { args, flags } = await this.parse(StoriesDevelopCommand);
+        const startTime = Date.now();
+        const correlationId = generateCorrelationId();
+        // Initialize services with selected provider
+        const provider = (flags.provider || 'claude');
+        this.initializeServices(provider);
+        this.logger.info({
+            correlationId,
+            flags,
+            pattern: args.pattern,
+        }, 'Starting stories develop command');
+        try {
+            // Match story files using glob pattern
+            const storyFiles = await this.matchStoryFiles(args.pattern);
+            if (storyFiles.length === 0) {
+                this.log(colors.warning(`No story files matched pattern: ${args.pattern}`));
+                return;
+            }
+            this.log(colors.info(`Found ${storyFiles.length} story file(s) to develop`));
+            this.log('');
+            // Develop stories sequentially
+            const results = await this.developStoriesSequentially(storyFiles, flags);
+            // Display summary report
+            const duration = Date.now() - startTime;
+            this.displaySummaryReport(results, duration);
+            this.logger.info({
+                correlationId,
+                duration,
+                failed: results.filter((r) => !r.success).length,
+                succeeded: results.filter((r) => r.success).length,
+                total: results.length,
+            }, 'Stories develop command completed');
+            // Exit with error if any stories failed (before QA)
+            const failedCount = results.filter((r) => !r.success).length;
+            if (failedCount > 0) {
+                this.error(colors.error(`${failedCount} story development(s) failed`), { exit: 1 });
+            }
+            // Run QA workflow if --qa flag is set
+            if (flags.qa) {
+                const successfulStories = results.filter((r) => r.success && r.qaStoryPath !== '');
+                if (successfulStories.length > 0) {
+                    this.log('');
+                    this.log(colors.bold('═══════════════════════════════════════════'));
+                    this.log(colors.bold('  Starting QA Workflow for developed stories'));
+                    this.log(colors.bold('═══════════════════════════════════════════'));
+                    this.log('');
+                    await this.runQaWorkflow(successfulStories, {
+                        interval: flags.interval,
+                        maxRetries: flags['qa-retries'],
+                        qaPrompt: flags['qa-prompt'],
+                        reference: flags.reference,
+                    });
+                }
+                else {
+                    this.log(colors.warning('No successful stories to run QA workflow on'));
+                }
+            }
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ correlationId, error: err }, 'Command failed');
+            this.error(colors.error(err.message), { exit: 1 });
+        }
+    }
+    /**
+     * Build Claude CLI prompt for story development
+     */
+    async buildClaudePrompt(options) {
+        const { agent = 'dev', cwd, references, storyContent, storyPath, task = 'develop-story' } = options;
+        const agentFile = agent;
+        const taskCommand = task;
+        let prompt = `@.bmad-core/agents/${agentFile}.md\n\n`;
+        // Add working directory instruction if specified
+        if (cwd) {
+            prompt += `Working directory: ${cwd}\n\n`;
+        }
+        prompt += `*${taskCommand} ${storyPath}\n\n`;
+        // Detect story type and auto-include relevant documentation
+        const detection = this.storyTypeDetector.detectStoryType(storyContent);
+        const autoReferences = this.storyTypeDetector.getDocumentationReferences(detection.type);
+        this.logger.info({
+            autoReferencesCount: autoReferences.length,
+            confidence: detection.confidence,
+            matchedKeywordsCount: detection.matchedKeywords.length,
+            storyType: detection.type,
+        }, 'Story type detected, auto-including documentation references');
+        // Combine auto-detected references with user-provided references
+        const allReferences = [...(references || [])];
+        if (allReferences.length > 0) {
+            prompt += 'References:\n';
+            for (const ref of allReferences) {
+                const resolvedPath = path.resolve(ref);
+                prompt += `@${resolvedPath}\n`;
+            }
+            prompt += '\n';
+        }
+        // Log which references were included
+        if (autoReferences.length > 0) {
+            this.log(colors.info(`  Auto-included ${autoReferences.length} ${detection.type} documentation reference(s)`));
+        }
+        prompt += '*yolo mode* always update the story file as you go\n';
+        return prompt;
+    }
+    /**
+     * Develop stories sequentially (CRITICAL: No parallelism)
+     */
+    async developStoriesSequentially(storyFiles, flags) {
+        const results = [];
+        const total = storyFiles.length;
+        /* eslint-disable no-await-in-loop */
+        // Sequential loop - DO NOT use Promise.all - await in loop is REQUIRED here
+        for (let index = 0; index < storyFiles.length; index++) {
+            const storyPath = storyFiles[index];
+            const storyNum = index + 1;
+            this.log(colors.bold(`\n[${storyNum}/${total}] Developing: ${path.basename(storyPath)}`));
+            // Parse story metadata
+            const spinner = createSpinner('Parsing story metadata...');
+            spinner.start();
+            let storyMetadata;
+            try {
+                storyMetadata = await this.storyParserFactory.parseStory(storyPath);
+                const storyId = storyMetadata.id;
+                spinner.succeed(colors.success(`Story ${storyId}: ${storyMetadata.title}`));
+            }
+            catch (error) {
+                const err = error;
+                spinner.fail(colors.error(`Failed to parse story: ${err.message}`));
+                results.push({
+                    error: `Parse error: ${err.message}`,
+                    movedToQa: false,
+                    qaStoryPath: '',
+                    storyNumber: 'unknown',
+                    storyPath,
+                    success: false,
+                });
+                continue; // Skip to next story
+            }
+            // Develop story
+            const devSpinner = createSpinner('Running dev agent...');
+            devSpinner.start();
+            const result = await this.developStory({
+                agent: flags.agent,
+                cwd: flags.cwd,
+                references: flags.reference,
+                storyMetadata,
+                storyPath,
+                task: flags.task,
+            });
+            results.push(result);
+            if (result.success) {
+                devSpinner.succeed(colors.success(`✓ Development completed, moved to QA`));
+            }
+            else {
+                devSpinner.fail(colors.error(`✗ Development failed: ${result.error}`));
+            }
+            // Display countdown timer before next story (except for last story)
+            if (index < storyFiles.length - 1) {
+                await this.displayCountdown(flags.interval);
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return results;
+    }
+    /**
+     * Develop a single story
+     */
+    async developStory(options) {
+        const { agent, cwd, references, storyMetadata, storyPath, task } = options;
+        const storyNumber = isEpicStory(storyMetadata) ? storyMetadata.number : storyMetadata.id;
+        this.logger.info({ storyNumber, storyPath }, 'Starting story development');
+        try {
+            // Step 1: Update status from Draft to Ready if needed
+            if (storyMetadata.status === 'Draft') {
+                this.logger.info({ storyNumber }, 'Updating story status from Draft to Ready');
+                // Use the appropriate parser to update status
+                if (isEpicStory(storyMetadata)) {
+                    const { StoryParser } = await import('../../services/parsers/story-parser.js');
+                    const parser = new StoryParser(this.fileManager, this.logger);
+                    await parser.updateStoryStatus(storyPath, 'Ready');
+                }
+                else {
+                    const { StandaloneStoryParser } = await import('../../services/parsers/standalone-story-parser.js');
+                    const parser = new StandaloneStoryParser(this.fileManager, this.logger);
+                    await parser.updateStoryStatus(storyPath, 'Ready');
+                }
+            }
+            // Step 2: Read story content for type detection
+            const storyContent = await this.fileManager.readFile(storyPath);
+            // Step 3: Build Claude CLI prompt with auto-detected documentation references
+            const prompt = await this.buildClaudePrompt({
+                agent,
+                cwd,
+                references,
+                storyContent,
+                storyPath,
+                task,
+            });
+            // Step 4: Run Claude dev agent
+            this.logger.info({ storyNumber }, 'Running Claude dev agent');
+            const result = await this.agentRunner.runAgent(prompt, {
+                agentType: 'dev',
+                timeout: DEV_AGENT_TIMEOUT_MS,
+            });
+            if (!result.success) {
+                throw new Error(`Dev agent failed: ${result.errors}`);
+            }
+            // Step 5: Move completed story to QA folder
+            const qaStoryDir = this.pathResolver.getQaStoryDir();
+            const destPath = path.join(qaStoryDir, path.basename(storyPath));
+            this.logger.info({ destPath, storyNumber }, 'Moving completed story to QA folder');
+            await this.fileManager.moveFile(storyPath, destPath);
+            this.logger.info({ storyNumber, storyPath }, 'Story development completed successfully');
+            return {
+                movedToQa: true,
+                qaStoryPath: destPath,
+                storyNumber,
+                storyPath,
+                success: true,
+            };
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err, storyNumber, storyPath }, 'Story development failed');
+            return {
+                error: err.message,
+                movedToQa: false,
+                qaStoryPath: '',
+                storyNumber,
+                storyPath,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Display countdown timer between stories
+     */
+    async displayCountdown(intervalSeconds) {
+        /* eslint-disable no-await-in-loop */
+        for (let remaining = intervalSeconds; remaining > 0; remaining--) {
+            process.stdout.write(`\r${colors.warning(`⏳ Next story in ${remaining}s...`)}`);
+            await this.sleep(1000);
+        }
+        /* eslint-enable no-await-in-loop */
+        process.stdout.write('\r' + ' '.repeat(40) + '\r'); // Clear countdown line
+    }
+    /**
+     * Display summary report
+     */
+    displaySummaryReport(results, duration) {
+        const successCount = results.filter((r) => r.success).length;
+        const failedCount = results.filter((r) => !r.success).length;
+        // Box drawing
+        const boxTop = '┌─────────────────────────────────────────┐';
+        const boxDivider = '├─────────────────────────────────────────┤';
+        const boxBottom = '└─────────────────────────────────────────┘';
+        this.log('');
+        this.log(boxTop);
+        this.log('│      Story Development Summary          │');
+        this.log(boxDivider);
+        this.log(`│ ${colors.success('Succeeded:')}       ${successCount.toString().padEnd(20)}│`);
+        if (failedCount > 0) {
+            this.log(`│ ${colors.error('Failed:')}          ${failedCount.toString().padEnd(20)}│`);
+        }
+        this.log(boxDivider);
+        this.log(`│ Duration:           ${(duration / 1000).toFixed(2)}s${' '.repeat(15)}│`);
+        this.log(boxBottom);
+        // List failures if any
+        if (failedCount > 0) {
+            this.log('');
+            this.log(colors.bold('Failed Stories:'));
+            for (const result of results.filter((r) => !r.success)) {
+                this.log(colors.error(`  ✗ ${result.storyNumber}: ${path.basename(result.storyPath)} - ${result.error || 'Unknown error'}`));
+            }
+        }
+        this.log('');
+    }
+    /**
+     * Initialize service dependencies
+     */
+    initializeServices(provider = 'claude') {
+        this.logger = createLogger({ namespace: 'commands:stories:develop' });
+        this.logger.info({ provider }, 'Initializing services with AI provider');
+        this.fileManager = new FileManager(this.logger);
+        this.pathResolver = new PathResolver(this.fileManager, this.logger);
+        this.globMatcher = new GlobMatcher(this.fileManager, this.logger);
+        this.storyParserFactory = new StoryParserFactory(this.fileManager, this.logger);
+        this.storyTypeDetector = new StoryTypeDetector(this.logger);
+        this.agentRunner = createAgentRunner(provider, this.logger);
+        this.logger.debug({ provider }, 'Services initialized successfully');
+    }
+    /**
+     * Match story files using glob pattern
+     */
+    async matchStoryFiles(pattern) {
+        this.logger.info({ pattern }, 'Matching story files with glob pattern');
+        // Expand glob pattern
+        const matches = await this.globMatcher.expandPattern(pattern);
+        this.logger.info({ matchCount: matches.length, pattern }, 'Glob pattern matching complete');
+        return matches;
+    }
+    /**
+     * Run QA workflow for successfully developed stories
+     * Dynamically imports and delegates to StoriesQaCommand
+     */
+    async runQaWorkflow(successfulStories, options) {
+        // Dynamically import QA command to avoid circular dependencies
+        const { default: StoriesQaCommand } = await import('./qa.js');
+        // Create a temporary glob pattern from successful story paths
+        // We'll run QA on each story individually to maintain proper tracking
+        for (const story of successfulStories) {
+            if (story.qaStoryPath === '')
+                continue;
+            this.log(colors.bold(`\nQA Workflow: ${path.basename(story.qaStoryPath)}`));
+            try {
+                // Build args for QA command - use the exact path as pattern
+                const qaArgs = [story.qaStoryPath];
+                // Build flags
+                const qaFlags = [`--max-retries=${options.maxRetries}`, `--interval=${options.interval}`];
+                if (options.qaPrompt) {
+                    qaFlags.push(`--qa-prompt=${options.qaPrompt}`);
+                }
+                if (options.reference && options.reference.length > 0) {
+                    for (const ref of options.reference) {
+                        qaFlags.push(`--reference=${ref}`);
+                    }
+                }
+                // Run QA command (sequential by design - one story at a time)
+                // eslint-disable-next-line no-await-in-loop
+                await StoriesQaCommand.run([...qaArgs, ...qaFlags]);
+                this.log(colors.success(`  ✓ QA workflow completed for ${story.storyNumber}`));
+            }
+            catch (error) {
+                const err = error;
+                this.logger.error({ error: err, storyNumber: story.storyNumber }, 'QA workflow failed for story');
+                this.log(colors.error(`  ✗ QA workflow failed: ${err.message}`));
+                // Continue with other stories even if one fails
+            }
+        }
+        this.log('');
+        this.log(colors.bold('QA Workflow Complete'));
+        this.log('');
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    async sleep(ms) {
+        // eslint-disable-next-line no-promise-executor-return -- Simple setTimeout wrapper
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/commands/stories/list.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Stories List Command
+ *
+ * Lists all stories with filtering by status and epic number.
+ * Displays results in table format or JSON format with counts summary.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow stories list
+ * bmad-workflow stories list --status=draft
+ * bmad-workflow stories list --epic=4
+ * bmad-workflow stories list --status=ready --epic=4 --json
+ * ```
+ */
+import { Command } from '@oclif/core';
+/**
+ * Stories List Command
+ *
+ * Lists all stories with optional filtering by status and epic number.
+ */
+export default class StoriesListCommand extends Command {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        epic: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private fileManager;
+    private logger;
+    private pathResolver;
+    private storyParserFactory;
+    /**
+     * Run command
+     */
+    run(): Promise<void>;
+    /**
+     * Apply filters to stories
+     */
+    private applyFilters;
+    /**
+     * Display count summary
+     */
+    private displaySummary;
+    /**
+     * Get color for status
+     */
+    private getStatusColor;
+    /**
+     * Handle errors with user-friendly messages
+     */
+    private handleError;
+    /**
+     * Initialize services
+     */
+    private initServices;
+    /**
+     * Output stories as JSON
+     */
+    private outputJson;
+    /**
+     * Output stories as table
+     */
+    private outputTable;
+    /**
+     * Parse stories from file paths
+     */
+    private parseStories;
+    /**
+     * Sort stories by type and ID
+     *
+     * Epic stories are sorted by epic.story number ascending.
+     * Standalone stories are sorted alphabetically by ID.
+     * Epic stories appear before standalone stories.
+     */
+    private sortStories;
+    /**
+     * Truncate string to max length
+     */
+    private truncate;
+}