@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/commands/epics/create.js

@@ -0,0 +1,459 @@
+/**
+ * Epics Create Command
+ *
+ * Creates epic files from a PRD document using Claude AI agents.
+ * Supports batch processing with progress indicators and idempotent behavior.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow epics create docs/prd.md
+ * bmad-workflow epics create docs/prd.md --start 2 --count 3
+ * bmad-workflow epics create docs/prd.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 { PrdParser } from '../../services/parsers/prd-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';
+/**
+ * Epics Create Command
+ *
+ * Creates epic markdown files from a PRD document by:
+ * 1. Parsing epics from PRD
+ * 2. Filtering based on flags (start, count)
+ * 3. Skipping existing epic files (idempotent)
+ * 4. Creating placeholder files
+ * 5. Running Claude AI agents to populate content
+ * 6. Displaying progress and summary
+ */
+export default class EpicsCreate extends Command {
+    static args = {
+        'prd-path': Args.string({
+            description: 'Path to PRD markdown file',
+            required: true,
+        }),
+    };
+    static description = 'Create epic files from PRD document';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> docs/prd.md',
+        '<%= config.bin %> <%= command.id %> docs/prd.md --start 2 --count 3',
+        '<%= config.bin %> <%= command.id %> docs/prd.md --reference docs/architecture.md --interval 5',
+        '<%= config.bin %> <%= command.id %> docs/prd.md --prefix "PROJECT-" --start 1',
+        '<%= config.bin %> <%= command.id %> docs/prd.md --agent architect --task create-doc',
+    ];
+    static flags = {
+        ...agentFlags,
+        count: Flags.integer({
+            char: 'c',
+            description: 'Number of epics to create (default: all remaining)',
+            min: 1,
+        }),
+        interval: Flags.integer({
+            char: 'i',
+            default: 0,
+            description: 'Seconds to wait between epic creations',
+            min: 0,
+        }),
+        prefix: Flags.string({
+            char: 'p',
+            description: 'Filename prefix for epic files (e.g., "PROJECT-")',
+        }),
+        reference: Flags.string({
+            char: 'r',
+            description: 'Reference file paths for AI agent context (repeatable)',
+            multiple: true,
+        }),
+        start: Flags.integer({
+            char: 's',
+            default: 1,
+            description: 'Start from epic number N',
+            min: 1,
+        }),
+    };
+    /**
+     * AI agent runner service (Claude or Gemini)
+     */
+    agentRunner;
+    /**
+     * File manager service
+     */
+    fileManager;
+    /**
+     * File scaffolder service
+     */
+    fileScaffolder;
+    /**
+     * Logger instance
+     */
+    logger;
+    /**
+     * Path resolver service
+     */
+    pathResolver;
+    /**
+     * PRD parser service
+     */
+    prdParser;
+    /**
+     * Execute the command
+     */
+    async run() {
+        const { args, flags } = await this.parse(EpicsCreate);
+        // Initialize services with selected provider
+        const provider = (flags.provider || 'claude');
+        this.initializeServices(provider);
+        const correlationId = generateCorrelationId();
+        this.logger.info({
+            command: 'epics:create',
+            correlationId,
+            flags,
+            prdPath: args['prd-path'],
+        }, 'Executing epics create command');
+        try {
+            // Validate PRD path
+            await this.validatePrdPath(args['prd-path']);
+            // Parse PRD and extract epics
+            const allEpics = await this.parsePrd(args['prd-path']);
+            // Filter epics based on start/count flags
+            const filteredEpics = this.filterEpics(allEpics, flags.start, flags.count);
+            // Get epic directory
+            const epicDir = this.pathResolver.getEpicDir();
+            // Check for existing epics (idempotent behavior)
+            const { skipped, toCreate } = await this.checkExistingEpics(filteredEpics, epicDir, flags.prefix);
+            // Display initial status
+            this.displayInitialStatus(allEpics.length, filteredEpics.length, toCreate.length, skipped.length);
+            // Create epics
+            const results = await this.createEpics({
+                agent: flags.agent,
+                epicDir,
+                epics: toCreate,
+                interval: flags.interval,
+                prdPath: args['prd-path'],
+                prefix: flags.prefix || '',
+                references: flags.reference,
+                task: flags.task,
+            });
+            // Display summary
+            this.displaySummary({
+                created: results.filter((r) => r.success).length,
+                failed: results.filter((r) => !r.success).length,
+                results,
+                skipped: skipped.length,
+                total: allEpics.length,
+            });
+            this.logger.info({ correlationId }, 'Epics create command completed successfully');
+        }
+        catch (error) {
+            this.logger.error({ correlationId, error }, 'Epics create command failed');
+            throw error;
+        }
+    }
+    /**
+     * Build Claude CLI prompt for epic population
+     */
+    buildClaudePrompt(options) {
+        const { agent = 'sm', epic, epicPath, prdPath, references, task = 'draft' } = options;
+        const agentFile = agent;
+        const taskCommand = task;
+        let prompt = `@.bmad-core/agents/${agentFile}.md\n\n`;
+        prompt += `Create epic '${epic.number}: ${epic.title}' for PRD '${prdPath}'.\n\n`;
+        prompt += `Target file: @${epicPath}\n\n`;
+        prompt += 'References:\n';
+        prompt += `@${prdPath}\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 Epic Header section (Epic ID, Status: Draft, Created date are already set)\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/epic-tmpl.yaml for content guidance\n\n';
+        prompt += `Execute the *${taskCommand} command to populate the epic document.\n`;
+        prompt += 'Update the file at the target path with the epic content in the empty sections.\n';
+        return prompt;
+    }
+    /**
+     * Check for existing epic files to support idempotent behavior
+     */
+    async checkExistingEpics(epics, epicDir, prefix) {
+        const toCreate = [];
+        const skipped = [];
+        /* eslint-disable no-await-in-loop */
+        for (const epic of epics) {
+            const fileName = this.generateEpicFileName(epic, prefix || '');
+            const filePath = path.join(epicDir, fileName);
+            const exists = await this.fileManager.fileExists(filePath);
+            if (exists) {
+                this.logger.info({ epicNumber: epic.number, filePath }, 'Epic file already exists, skipping');
+                skipped.push(epic);
+            }
+            else {
+                toCreate.push(epic);
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return { skipped, toCreate };
+    }
+    /**
+     * Create epic files using Claude AI agents
+     */
+    async createEpics(options) {
+        const { agent, epicDir, epics, interval, prdPath, prefix, references, task } = options;
+        const results = [];
+        /* eslint-disable no-await-in-loop */
+        for (let i = 0; i < epics.length; i++) {
+            const epic = epics[i];
+            const result = await this.createSingleEpic({
+                agent,
+                epic,
+                epicDir,
+                prdPath,
+                prefix,
+                references,
+                task,
+            });
+            results.push(result);
+            // Wait interval if not last epic
+            if (i < epics.length - 1 && interval > 0) {
+                await this.waitInterval(interval);
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return results;
+    }
+    /**
+     * Create a single epic file
+     */
+    async createSingleEpic(options) {
+        const { agent, epic, epicDir, prdPath, prefix, references, task } = options;
+        const fileName = this.generateEpicFileName(epic, prefix);
+        const filePath = path.join(epicDir, fileName);
+        const spinner = createSpinner(`Creating Epic ${epic.number}: ${epic.title}...`);
+        spinner.start();
+        const startTime = Date.now();
+        try {
+            // Step 1: Create scaffolded file with structured sections and populated metadata
+            const scaffoldedContent = this.generateScaffoldedContent(epic, prefix);
+            await this.fileManager.writeFile(filePath, scaffoldedContent);
+            this.logger.info({
+                epicNumber: epic.number,
+                filePath,
+            }, 'Epic scaffolded file created');
+            // Step 2: Build Claude prompt to populate the scaffolded file
+            const absolutePrdPath = path.resolve(prdPath);
+            const absoluteEpicPath = path.resolve(filePath);
+            const prompt = this.buildClaudePrompt({
+                agent,
+                epic,
+                epicPath: absoluteEpicPath,
+                prdPath: absolutePrdPath,
+                references: references || [],
+                task,
+            });
+            // Step 3: Run Claude AI agent to populate epic content sections
+            spinner.text = `Populating epic ${epic.number} with AI agent...`;
+            const result = await this.agentRunner.runAgent(prompt, {
+                agentType: 'sm',
+                references,
+                timeout: 1_800_000, // 30 minutes
+            });
+            if (!result.success) {
+                throw new Error(result.errors || 'Claude agent failed to populate epic');
+            }
+            // Step 4: Verify file was updated by Claude
+            const updatedContent = await this.fileManager.readFile(filePath);
+            if (updatedContent === scaffoldedContent) {
+                throw new Error('Claude did not update the epic file');
+            }
+            const duration = Date.now() - startTime;
+            const durationSec = (duration / 1000).toFixed(1);
+            spinner.succeed(colors.success(`Epic ${epic.number} created successfully (${durationSec}s)`));
+            this.logger.info({
+                duration,
+                epicNumber: epic.number,
+                filePath,
+            }, 'Epic created successfully');
+            return {
+                duration,
+                epic,
+                filePath,
+                success: true,
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const err = error;
+            spinner.fail(colors.error(`Epic ${epic.number} creation failed - ${err.message}`));
+            this.logger.error({
+                duration,
+                epicNumber: epic.number,
+                error: err,
+                filePath,
+            }, 'Epic creation failed');
+            return {
+                duration,
+                epic,
+                error: err.message,
+                filePath,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Display initial status before creating epics
+     */
+    displayInitialStatus(totalEpics, filteredCount, toCreateCount, skippedCount) {
+        const boxTop = '┌─────────────────────────────────────────┐';
+        const boxDivider = '├─────────────────────────────────────────┤';
+        const boxBottom = '└─────────────────────────────────────────┘';
+        this.log('');
+        this.log(boxTop);
+        this.log('│         Epic Creation Status            │');
+        this.log(boxDivider);
+        this.log(`│ Total epics in PRD: ${colors.bold(totalEpics.toString().padEnd(17))}│`);
+        this.log(`│ Epics in range:     ${colors.bold(filteredCount.toString().padEnd(17))}│`);
+        this.log(`│ ${colors.success('To create:')}         ${toCreateCount.toString().padEnd(17)}│`);
+        this.log(`│ ${colors.dim('Already exist:')}     ${skippedCount.toString().padEnd(17)}│`);
+        this.log(boxBottom);
+        this.log('');
+        if (toCreateCount === 0) {
+            this.log(colors.info('All epics already exist. Nothing to create.'));
+            this.log('');
+        }
+    }
+    /**
+     * Display summary report after creating epics
+     */
+    displaySummary(summary) {
+        const boxTop = '┌─────────────────────────────────────────┐';
+        const boxDivider = '├─────────────────────────────────────────┤';
+        const boxBottom = '└─────────────────────────────────────────┘';
+        this.log('');
+        this.log(boxTop);
+        this.log('│         Epic Creation Summary           │');
+        this.log(boxDivider);
+        this.log(`│ Total epics:        ${colors.bold(summary.total.toString().padEnd(17))}│`);
+        this.log(`│ ${colors.success('Created:')}           ${summary.created.toString().padEnd(17)}│`);
+        this.log(`│ ${colors.dim('Skipped:')}           ${summary.skipped.toString().padEnd(17)}│`);
+        this.log(`│ ${colors.error('Failed:')}            ${summary.failed.toString().padEnd(17)}│`);
+        this.log(boxBottom);
+        // Display failed epics if any
+        const failedResults = summary.results.filter((r) => !r.success);
+        if (failedResults.length > 0) {
+            this.log('');
+            this.log(colors.bold('Failed Epics:'));
+            for (const result of failedResults) {
+                this.log(colors.error(`  ✗ Epic ${result.epic.number}: ${result.epic.title}`));
+                this.log(colors.dim(`    ${result.error}`));
+            }
+        }
+        this.log('');
+    }
+    /**
+     * Filter epics based on start and count flags
+     */
+    filterEpics(epics, start, count) {
+        // Filter by start
+        let filtered = epics.filter((epic) => epic.number >= start);
+        // Apply count limit if specified
+        if (count !== undefined && count > 0) {
+            filtered = filtered.slice(0, count);
+        }
+        this.logger.debug({
+            count,
+            filteredCount: filtered.length,
+            start,
+            totalEpics: epics.length,
+        }, 'Filtered epics based on flags');
+        return filtered;
+    }
+    /**
+     * Generate epic filename from epic data
+     */
+    generateEpicFileName(epic, prefix) {
+        // Convert title to slug (lowercase, replace spaces with hyphens, remove special chars)
+        const slug = epic.title
+            .toLowerCase()
+            .replaceAll(/[^\da-z\s-]/g, '')
+            .trim()
+            .replaceAll(/\s+/g, '-');
+        return `${prefix}epic-${epic.number}-${slug}.md`;
+    }
+    /**
+     * Generate scaffolded content for epic file
+     */
+    generateScaffoldedContent(epic, prefix) {
+        return this.fileScaffolder.scaffoldEpic({
+            epicNumber: epic.number,
+            epicTitle: epic.title,
+            prefix,
+        });
+    }
+    /**
+     * Initialize service dependencies
+     */
+    initializeServices(provider = 'claude') {
+        this.logger = createLogger({ namespace: 'commands:epics: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.prdParser = new PrdParser(this.logger);
+        this.fileScaffolder = new FileScaffolder(this.logger);
+        this.agentRunner = createAgentRunner(provider, this.logger);
+    }
+    /**
+     * Parse PRD file and extract epics
+     */
+    async parsePrd(prdPath) {
+        this.logger.info({ prdPath }, 'Parsing PRD file');
+        const spinner = createSpinner('Parsing PRD file...');
+        spinner.start();
+        try {
+            const prdContent = await this.fileManager.readFile(prdPath);
+            const epics = this.prdParser.parseEpics(prdContent, prdPath);
+            spinner.succeed(colors.success(`Found ${epics.length} epic(s) in PRD`));
+            this.logger.info({ epicCount: epics.length, prdPath }, 'PRD parsed successfully');
+            return epics;
+        }
+        catch (error) {
+            spinner.fail(colors.error('Failed to parse PRD'));
+            throw error;
+        }
+    }
+    /**
+     * Validate PRD path exists
+     */
+    async validatePrdPath(prdPath) {
+        const exists = await this.fileManager.fileExists(prdPath);
+        if (!exists) {
+            throw new ValidationError(`PRD file not found: ${prdPath}`, {
+                prdPath,
+                suggestion: 'Check the path and ensure the file exists',
+            });
+        }
+        this.logger.debug({ prdPath }, 'PRD path validation passed');
+    }
+    /**
+     * Wait for specified interval with countdown
+     */
+    async waitInterval(seconds) {
+        if (seconds <= 0)
+            return;
+        const spinner = createSpinner(`Waiting ${seconds} seconds before next epic...`);
+        spinner.start();
+        await new Promise((resolve) => {
+            setTimeout(resolve, seconds * 1000);
+        });
+        spinner.stop();
+    }
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Epics List Command
+ *
+ * Lists all epic files with their metadata in a formatted table.
+ * Scans docs/epics/ directory for epic files and displays:
+ * - Epic number
+ * - Epic title
+ * - Story count
+ * - File path
+ *
+ * Supports JSON output mode for machine-readable consumption.
+ *
+ * @example
+ * ```bash
+ * # Display epics in table format
+ * bmad-workflow epics list
+ *
+ * # Output as JSON
+ * bmad-workflow epics list --json
+ * ```
+ */
+import { Command } from '@oclif/core';
+/**
+ * Epics List Command
+ *
+ * Lists all epic files with metadata in table or JSON format.
+ */
+export default class EpicsList extends Command {
+    /**
+     * Command description
+     */
+    static description: string;
+    /**
+     * Command examples
+     */
+    static examples: string[];
+    /**
+     * Command flags
+     */
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    /**
+     * Logger instance
+     */
+    private logger;
+    /**
+     * EpicParser instance
+     */
+    private epicParser;
+    /**
+     * FileManager instance
+     */
+    private fileManager;
+    /**
+     * PathResolver instance
+     */
+    private pathResolver;
+    /**
+     * Run the command
+     */
+    run(): Promise<void>;
+    /**
+     * Discover epic files and extract metadata
+     *
+     * @returns Array of epic metadata objects
+     */
+    private discoverEpics;
+    /**
+     * Extract epic number from filename
+     *
+     * @param filePath - Epic file path
+     * @returns Epic number
+     */
+    private extractEpicNumber;
+    /**
+     * Extract epic title from content
+     *
+     * Looks for first # heading in content, or derives from filename.
+     *
+     * @param content - Epic file content
+     * @param filePath - Epic file path (for fallback title)
+     * @returns Epic title
+     */
+    private extractEpicTitle;
+    /**
+     * Check if a file is an epic file
+     *
+     * @param filePath - File path to check
+     * @returns True if file matches epic pattern
+     */
+    private isEpicFile;
+    /**
+     * Output epic metadata as JSON
+     *
+     * @param epicMetadata - Array of epic metadata
+     */
+    private outputJson;
+    /**
+     * Output epic metadata as formatted table
+     *
+     * @param epicMetadata - Array of epic metadata
+     */
+    private outputTable;
+    /**
+     * Parse epic file to extract metadata
+     *
+     * @param epicFile - Path to epic file
+     * @returns Epic metadata
+     */
+    private parseEpicMetadata;
+    /**
+     * Truncate title if too long
+     *
+     * @param title - Title to truncate
+     * @param maxLength - Maximum length
+     * @returns Truncated title with ellipsis if needed
+     */
+    private truncateTitle;
+}