@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/commands/stories/create.js

@@ -0,0 +1,431 @@
+/**
+ * Stories Create Command
+ *
+ * Automatically generates story markdown files from an epic using parallel Claude AI agent execution.
+ * Creates story files with configurable concurrency and batch processing.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow stories create docs/epics/epic-1-foundation.md
+ * bmad-workflow stories create epic.md --parallel 10
+ * bmad-workflow stories create epic.md --start 3
+ * bmad-workflow stories create epic.md --reference docs/architecture.md
+ * ```
+ */
+import { Args, Command, Flags } from '@oclif/core';
+import path from 'node:path';
+import { createAgentRunner } 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 { EpicParser } from '../../services/parsers/epic-parser.js';
+import { FileScaffolder } from '../../services/scaffolding/file-scaffolder.js';
+import * as colors from '../../utils/colors.js';
+import { ValidationError } from '../../utils/errors.js';
+import { createLogger, generateCorrelationId } from '../../utils/logger.js';
+import { createSpinner } from '../../utils/progress.js';
+import { agentFlags } from '../../utils/shared-flags.js';
+/**
+ * Stories Create Command
+ *
+ * Creates story files from epic using Claude AI agents with parallel processing.
+ */
+export default class StoriesCreateCommand extends Command {
+    static args = {
+        'epic-path': Args.string({
+            description: 'Path to epic markdown file',
+            required: true,
+        }),
+    };
+    static description = 'Create story files from epic using Claude AI agents';
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %> docs/epics/epic-1-foundation.md',
+            description: 'Create all stories from epic',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> epic.md --parallel 10',
+            description: 'Create stories with 10 concurrent agents',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> epic.md --start 3',
+            description: 'Create stories starting from story number 3',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> epic.md --reference docs/architecture.md --reference docs/api-spec.md',
+            description: 'Create stories with additional context files',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> epic.md --agent po --task create-next-story',
+            description: 'Use Product Owner agent with custom task for story creation',
+        },
+    ];
+    static flags = {
+        ...agentFlags,
+        interval: Flags.integer({
+            default: 30,
+            description: 'Seconds between batches',
+        }),
+        parallel: Flags.integer({
+            default: 7,
+            description: 'Max concurrent story creations',
+        }),
+        prefix: Flags.string({
+            description: 'Filename prefix for stories',
+        }),
+        reference: Flags.string({
+            description: 'Additional context files for AI agents',
+            multiple: true,
+        }),
+        start: Flags.integer({
+            description: 'Story number to start from',
+        }),
+    };
+    // Service instances
+    agentRunner;
+    batchProcessor;
+    epicParser;
+    fileManager;
+    fileScaffolder;
+    logger;
+    pathResolver;
+    /**
+     * Run the command
+     */
+    async run() {
+        const { args, flags } = await this.parse(StoriesCreateCommand);
+        const startTime = Date.now();
+        const correlationId = generateCorrelationId();
+        // Initialize services with selected provider
+        const provider = (flags.provider || 'claude');
+        this.initializeServices(flags.parallel, flags.interval, provider);
+        this.logger.info({
+            correlationId,
+            epicPath: args['epic-path'],
+            flags,
+        }, 'Starting stories create command');
+        try {
+            // Validate parallel flag
+            this.validateParallelFlag(flags.parallel);
+            // Parse epic and extract stories
+            const epicPath = path.resolve(args['epic-path']);
+            const stories = await this.parseEpicStories(epicPath);
+            // Filter stories based on --start flag
+            const filteredStories = this.filterStoriesByStart(stories, flags.start);
+            // Check for existing story files (idempotent)
+            const { existingStories, newStories } = await this.checkExistingStories(filteredStories, flags.prefix);
+            // Display summary before creation
+            this.logger.info({
+                existing: existingStories.length,
+                new: newStories.length,
+                total: filteredStories.length,
+            }, 'Story file check complete');
+            if (newStories.length === 0) {
+                this.log(colors.info('All story files already exist, nothing to create'));
+                return;
+            }
+            // Create stories with parallel processing
+            const results = await this.createStoriesInParallel(newStories, epicPath, flags);
+            // Display summary report
+            const duration = Date.now() - startTime;
+            this.displaySummaryReport(results, existingStories.length, duration);
+            this.logger.info({
+                correlationId,
+                created: results.filter((r) => r.success).length,
+                duration,
+                failed: results.filter((r) => !r.success).length,
+            }, 'Stories create command completed');
+        }
+        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 creation
+     */
+    buildClaudePrompt(options) {
+        const { agent = 'sm', epicPath, references, story, storyFilePath, task = 'draft' } = options;
+        const agentFile = agent;
+        const taskCommand = task;
+        let prompt = `@.bmad-core/agents/${agentFile}.md\n\n`;
+        prompt += 'Create story document from epic story definition:\n\n';
+        prompt += `Epic Number: ${story.epicNumber}\n`;
+        prompt += `Story Number: ${story.number}\n`;
+        prompt += `Story Title: ${story.title}\n\n`;
+        prompt += `Target file: @${storyFilePath}\n\n`;
+        prompt += 'References:\n';
+        prompt += `@${epicPath}\n`;
+        if (references && references.length > 0) {
+            for (const ref of references) {
+                prompt += `@${path.resolve(ref)}\n`;
+            }
+        }
+        prompt += '\nIMPORTANT: The target file has been pre-scaffolded with structure and metadata.\n';
+        prompt += '- DO NOT modify the Status section (already set to Draft)\n';
+        prompt += '- DO NOT modify the Created date in Change Log\n';
+        prompt += '- DO NOT change the document structure or section headers\n';
+        prompt += '- ONLY populate the empty content sections marked with [AI Agent will populate]\n';
+        prompt += '- Follow the template structure at @.bmad-core/templates/story-tmpl.yaml\n\n';
+        prompt += `Execute the *${taskCommand} command to populate the story document.\n`;
+        prompt += 'Update the file at the target path with the story content in the empty sections.\n';
+        return prompt;
+    }
+    /**
+     * Check for existing story files 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.
+     */
+    async checkExistingStories(stories, prefix) {
+        const allStoryDirs = this.pathResolver.getAllStoryDirs();
+        const existingStories = [];
+        const newStories = [];
+        this.logger.info({ directories: allStoryDirs }, 'Checking for existing story files across all directories');
+        /* eslint-disable no-await-in-loop */
+        for (const story of stories) {
+            const filename = this.generateStoryFilename(story, prefix);
+            let foundInAnyDir = false;
+            // Check all story directories
+            for (const dir of allStoryDirs) {
+                const filePath = path.join(dir, filename);
+                const exists = await this.fileManager.fileExists(filePath);
+                if (exists) {
+                    this.logger.info({ directory: dir, filePath, storyNumber: story.fullNumber }, 'Story already exists');
+                    foundInAnyDir = true;
+                    break;
+                }
+            }
+            if (foundInAnyDir) {
+                existingStories.push(story);
+            }
+            else {
+                this.logger.debug({ filename, storyNumber: story.fullNumber }, 'Story needs to be created');
+                newStories.push(story);
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return { existingStories, newStories };
+    }
+    /**
+     * Create stories in parallel batches
+     */
+    async createStoriesInParallel(stories, epicPath, flags) {
+        const spinner = createSpinner('Creating stories...');
+        spinner.start();
+        const results = [];
+        try {
+            // Define processor function for each story
+            const processor = async (story) => this.createStory({
+                agent: flags.agent,
+                epicPath,
+                prefix: flags.prefix,
+                references: flags.reference,
+                story,
+                task: flags.task,
+            });
+            // Progress callback for batch updates
+            const onProgress = (info) => {
+                spinner.text = `Processing batch ${info.currentBatch} of ${info.totalBatches} (${info.completedItems}/${info.totalItems} completed)...`;
+                this.logger.info({
+                    batchNum: info.currentBatch,
+                    completedItems: info.completedItems,
+                    totalBatches: info.totalBatches,
+                    totalItems: info.totalItems,
+                }, 'Processing batch');
+            };
+            // Process stories in batches
+            const batchResults = await this.batchProcessor.processBatch(stories, processor, onProgress);
+            // Extract results from BatchResult wrapper
+            for (const batchResult of batchResults) {
+                if (batchResult.success && batchResult.result) {
+                    results.push(batchResult.result);
+                }
+                else if (!batchResult.success) {
+                    // Create error result for failed items
+                    results.push({
+                        error: batchResult.error?.message || 'Unknown error',
+                        filePath: '',
+                        story: stories[results.length],
+                        success: false,
+                    });
+                }
+            }
+            const successCount = results.filter((r) => r.success).length;
+            spinner.succeed(colors.success(`Created ${successCount} story files`));
+        }
+        catch (error) {
+            const err = error;
+            spinner.fail(colors.error(`Failed to create stories: ${err.message}`));
+            throw error;
+        }
+        return results;
+    }
+    /**
+     * Create a single story file
+     */
+    async createStory(options) {
+        const { agent, epicPath, prefix, references, story, task } = options;
+        const storyDir = this.pathResolver.getStoryDir();
+        const filename = this.generateStoryFilename(story, prefix);
+        const filePath = path.join(storyDir, filename);
+        const absolutePath = path.resolve(filePath);
+        this.logger.info({ filePath, storyNumber: story.fullNumber }, 'Creating story file');
+        try {
+            // Step 1: Create scaffolded file with structured sections and populated metadata
+            const scaffoldedContent = this.fileScaffolder.scaffoldStory({
+                epicNumber: story.epicNumber,
+                storyNumber: story.number,
+                storyTitle: story.title,
+            });
+            await this.fileManager.writeFile(filePath, scaffoldedContent);
+            this.logger.debug({ filePath }, 'Scaffolded file created');
+            // Step 2: Build Claude CLI prompt
+            const prompt = this.buildClaudePrompt({
+                agent,
+                epicPath,
+                references,
+                story,
+                storyFilePath: absolutePath,
+                task,
+            });
+            // Step 3: Run Claude agent
+            const result = await this.agentRunner.runAgent(prompt, {
+                agentType: 'sm',
+                timeout: 1_800_000, // 30 minutes
+            });
+            // Step 4: Verify file was updated
+            if (result.success) {
+                const content = await this.fileManager.readFile(filePath);
+                if (content === scaffoldedContent) {
+                    throw new Error('AI agent did not update story file');
+                }
+                this.logger.info({ filePath, storyNumber: story.fullNumber }, 'Story created successfully');
+                return {
+                    filePath,
+                    story,
+                    success: true,
+                };
+            }
+            // Cleanup placeholder file on failure
+            // await this.fileManager.deleteFile(filePath) // Not implemented in FileManager yet
+            throw new Error(`AI agent failed: ${result.errors}`);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err, filePath, storyNumber: story.fullNumber }, 'Story creation failed');
+            return {
+                error: err.message,
+                filePath,
+                story,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Display summary report
+     */
+    displaySummaryReport(results, skippedCount, 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 Creation Summary          │');
+        this.log(boxDivider);
+        this.log(`│ ${colors.success('Created:')}         ${successCount.toString().padEnd(20)}│`);
+        this.log(`│ ${colors.dim('Skipped:')}         ${skippedCount.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.story.fullNumber}: ${result.story.title} - ${result.error || 'Unknown error'}`));
+            }
+        }
+        this.log('');
+    }
+    /**
+     * Filter stories by start number
+     */
+    filterStoriesByStart(stories, startNumber) {
+        if (!startNumber) {
+            return stories;
+        }
+        const filtered = stories.filter((story) => story.number >= startNumber);
+        this.logger.info({
+            filtered: filtered.length,
+            startNumber,
+            total: stories.length,
+        }, 'Filtered stories by start number');
+        return filtered;
+    }
+    /**
+     * Generate story filename from story metadata
+     */
+    generateStoryFilename(story, prefix) {
+        // Generate slug from title
+        const slug = story.title
+            .toLowerCase()
+            .replaceAll(/[^\w\s-]/g, '')
+            .replaceAll(/\s+/g, '-')
+            .slice(0, 50);
+        // Build filename: {prefix}{epicNum}.{storyNum}-{slug}.md
+        const effectivePrefix = prefix || '';
+        return `${effectivePrefix}${story.epicNumber}.${story.number}-${slug}.md`;
+    }
+    /**
+     * Initialize service dependencies
+     */
+    initializeServices(maxConcurrency, intervalSeconds, provider = 'claude') {
+        this.logger = createLogger({ namespace: 'commands:stories:create' });
+        this.logger.info({ provider }, 'Initializing services with AI provider');
+        this.fileManager = new FileManager(this.logger);
+        this.pathResolver = new PathResolver(this.fileManager, this.logger);
+        this.epicParser = new EpicParser(this.logger);
+        this.agentRunner = createAgentRunner(provider, this.logger);
+        this.batchProcessor = new BatchProcessor(maxConcurrency, intervalSeconds * 1000, this.logger);
+        this.fileScaffolder = new FileScaffolder(this.logger);
+        this.logger.debug({ provider }, 'Services initialized successfully');
+    }
+    /**
+     * Parse epic file and extract stories
+     */
+    async parseEpicStories(epicPath) {
+        this.logger.info({ epicPath }, 'Reading epic file');
+        // Read epic file
+        const epicContent = await this.fileManager.readFile(epicPath);
+        this.logger.debug({ epicPath, length: epicContent.length }, 'Epic file read');
+        // Parse stories from epic
+        const stories = this.epicParser.parseStories(epicContent, epicPath);
+        if (stories.length === 0) {
+            throw new ValidationError('No stories found in epic. Expected format: ### Story 1.1: Title', {
+                epicPath,
+                suggestion: 'Ensure epic has story headers like: ### Story 1.1: Initialize Project',
+            });
+        }
+        this.logger.info({ epicPath, storyCount: stories.length }, 'Stories extracted from epic successfully');
+        return stories;
+    }
+    /**
+     * Validate parallel flag value
+     */
+    validateParallelFlag(parallel) {
+        if (parallel < 1 || parallel > 10) {
+            throw new ValidationError('Parallel flag must be between 1 and 10 to prevent overwhelming the system', {
+                actual: parallel,
+                suggestion: 'Use --parallel with a value between 1 and 10',
+            });
+        }
+    }
+}

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

@@ -0,0 +1,91 @@
+/**
+ * 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 { Command } from '@oclif/core';
+/**
+ * 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: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        interval: import("@oclif/core/interfaces").OptionFlag<number, 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>;
+        agent: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        cwd: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        task: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private agentRunner;
+    private fileManager;
+    private globMatcher;
+    private logger;
+    private pathResolver;
+    private storyParserFactory;
+    private storyTypeDetector;
+    /**
+     * Run the command
+     */
+    run(): Promise<void>;
+    /**
+     * Build Claude CLI prompt for story development
+     */
+    private buildClaudePrompt;
+    /**
+     * Develop stories sequentially (CRITICAL: No parallelism)
+     */
+    private developStoriesSequentially;
+    /**
+     * Develop a single story
+     */
+    private developStory;
+    /**
+     * Display countdown timer between stories
+     */
+    private displayCountdown;
+    /**
+     * Display summary report
+     */
+    private displaySummaryReport;
+    /**
+     * Initialize service dependencies
+     */
+    private initializeServices;
+    /**
+     * Match story files using glob pattern
+     */
+    private matchStoryFiles;
+    /**
+     * Run QA workflow for successfully developed stories
+     * Dynamically imports and delegates to StoriesQaCommand
+     */
+    private runQaWorkflow;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}