@hyperdrive.bot/bmad-workflow 1.0.13 → 1.0.15

package/dist/commands/prd/fix.js

@@ -78,19 +78,34 @@ export default class PrdFix extends Command {
             // First, check if the PRD already parses correctly
             this.log(Colors.info(`\nAnalyzing PRD: ${relativePath}`));
             let needsFix = false;
+            let fixReason = '';
             try {
                 const epics = this.prdParser.parseEpics(originalContent, prdPath);
-                this.log(Colors.success(`\n✓ PRD already valid - found ${epics.length} epic(s)`));
-                this.log(Colors.dim('  No changes needed.\n'));
-                // Show the epics found
-                for (const epic of epics) {
-                    this.log(Colors.dim(`  • Epic ${epic.number}: ${epic.title}`));
+                // Also validate that each epic contains stories
+                const storyCounts = this.prdParser.countStoriesPerEpic(originalContent, epics);
+                const epicsWithoutStories = epics.filter((e) => (storyCounts.get(e.number) || 0) === 0);
+                if (epicsWithoutStories.length > 0) {
+                    needsFix = true;
+                    const missing = epicsWithoutStories.map((e) => `Epic ${e.number}`).join(', ');
+                    fixReason = `Found ${epics.length} epic(s) but ${epicsWithoutStories.length} missing stories: ${missing}`;
+                    this.log(Colors.warning(`\n⚠ ${fixReason}`));
+                    this.log(Colors.warning('  Epics need story headers like: ### Story 1.1: Title'));
+                }
+                else {
+                    this.log(Colors.success(`\n✓ PRD already valid - found ${epics.length} epic(s)`));
+                    this.log(Colors.dim('  No changes needed.\n'));
+                    // Show the epics found with story counts
+                    for (const epic of epics) {
+                        const count = storyCounts.get(epic.number) || 0;
+                        this.log(Colors.dim(`  • Epic ${epic.number}: ${epic.title} (${count} stories)`));
+                    }
+                    this.log('');
+                    return;
                 }
-                this.log('');
-                return;
             }
             catch {
                 needsFix = true;
+                fixReason = 'No epics found';
                 this.log(Colors.warning('\n⚠ PRD format issues detected - attempting auto-fix...'));
             }
             if (needsFix) {

package/dist/services/orchestration/workflow-orchestrator.js

@@ -1376,9 +1376,15 @@ Write output to: ${outputPath}`;
                     this.logger.warn({ epicNumber: epic.number }, 'Epic file not found, skipping');
                     return [];
                 }
-                const epicContent = await this.fileManager.readFile(epicFilePath);
-                const stories = this.epicParser.parseStories(epicContent, epicFilePath);
-                return stories;
+                try {
+                    const epicContent = await this.fileManager.readFile(epicFilePath);
+                    const stories = this.epicParser.parseStories(epicContent, epicFilePath);
+                    return stories;
+                }
+                catch (error) {
+                    this.logger.warn({ epicNumber: epic.number, error: error.message }, 'Failed to parse stories from epic, skipping');
+                    return [];
+                }
             }));
             // Flatten the array of story arrays
             allStories.push(...epicStories.flat());

package/dist/services/parsers/epic-parser.js

@@ -137,13 +137,10 @@ export class EpicParser {
                 this.logger.debug({ matches: matches.length, patternName: pattern.name }, 'Pattern matched stories');
             }
         }
-        // Check if any stories were found
+        // If no stories found, return empty array (epic may legitimately have no stories)
         if (allMatches.length === 0) {
-            this.logger.error({ epicPath }, 'No stories found in epic');
-            throw new ParserError('No stories found in epic. Expected format: `### Story 1.1: Title` or similar', {
-                filePath: epicPath,
-                suggestion: 'Ensure epic has story headers like: ### Story 1.1: Initialize Project',
-            });
+            this.logger.warn({ epicPath }, 'No stories found in epic, returning empty array');
+            return [];
         }
         // Sort by position (natural document order)
         allMatches.sort((a, b) => a.position - b.position);

package/dist/services/parsers/prd-fixer.d.ts

@@ -2,8 +2,8 @@
  * PRD Fixer Service
  *
  * Uses AI to automatically reformat PRD documents that don't match
- * the expected epic/story format. This allows the workflow to handle
- * PRDs written in various formats by normalizing them before parsing.
+ * the expected epic/story format. The AI writes the fixed content
+ * directly to the file path, avoiding fragile stdout parsing.
  *
  * @example
  * ```typescript
@@ -38,7 +38,8 @@ export interface PrdFixResult {
  * PRD Fixer Service
  *
  * Automatically reformats PRD documents to match expected epic/story patterns
- * using AI. Creates a backup before modifying the original file.
+ * using AI. The AI agent writes the fixed content directly to the file,
+ * creating a backup first.
  */
 export declare class PrdFixer {
     private readonly agentRunner;
@@ -56,8 +57,8 @@ export declare class PrdFixer {
      * Fix a PRD document to match expected format
      *
      * Uses AI to analyze and reformat the PRD content to match the expected
-     * epic/story structure. Creates a backup of the original file before
-     * overwriting with the fixed content.
+     * epic/story structure. The AI creates a backup and writes the fixed
+     * content directly to the file path.
      *
      * @param prdPath - Path to the PRD file
      * @param originalContent - Original PRD content that failed parsing
@@ -68,19 +69,12 @@ export declare class PrdFixer {
     /**
      * Build the prompt for fixing the PRD
      *
+     * Instructs the AI to read the file at the given path, reformat it,
+     * and write it back directly to the same path.
+     *
      * @param prdPath - Path to the PRD file
-     * @param content - Original PRD content
      * @param references - Optional reference files
      * @returns Complete prompt string for the AI agent
      */
     private buildFixPrompt;
-    /**
-     * Extract the fixed PRD content from the AI response
-     *
-     * Looks for content wrapped in markdown code blocks and extracts it.
-     *
-     * @param output - Raw AI response output
-     * @returns Extracted PRD content or null if not found
-     */
-    private extractFixedContent;
 }

package/dist/services/parsers/prd-fixer.js

@@ -2,8 +2,8 @@
  * PRD Fixer Service
  *
  * Uses AI to automatically reformat PRD documents that don't match
- * the expected epic/story format. This allows the workflow to handle
- * PRDs written in various formats by normalizing them before parsing.
+ * the expected epic/story format. The AI writes the fixed content
+ * directly to the file path, avoiding fragile stdout parsing.
  *
  * @example
  * ```typescript
@@ -18,7 +18,8 @@
  * PRD Fixer Service
  *
  * Automatically reformats PRD documents to match expected epic/story patterns
- * using AI. Creates a backup before modifying the original file.
+ * using AI. The AI agent writes the fixed content directly to the file,
+ * creating a backup first.
  */
 export class PrdFixer {
     agentRunner;
@@ -40,8 +41,8 @@ export class PrdFixer {
      * Fix a PRD document to match expected format
      *
      * Uses AI to analyze and reformat the PRD content to match the expected
-     * epic/story structure. Creates a backup of the original file before
-     * overwriting with the fixed content.
+     * epic/story structure. The AI creates a backup and writes the fixed
+     * content directly to the file path.
      *
      * @param prdPath - Path to the PRD file
      * @param originalContent - Original PRD content that failed parsing
@@ -51,9 +52,13 @@ export class PrdFixer {
     async fixPrd(prdPath, originalContent, references) {
         this.logger.info({ prdPath, references: references?.length ?? 0 }, 'Attempting to auto-fix PRD format');
         try {
+            // Create backup before AI modifies the file
+            const backupPath = `${prdPath}.bak`;
+            await this.fileManager.writeFile(backupPath, originalContent);
+            this.logger.info({ backupPath }, 'Created backup of original PRD');
             // Build the prompt for fixing the PRD
-            const prompt = this.buildFixPrompt(prdPath, originalContent, references);
-            // Execute the AI agent to fix the PRD
+            const prompt = this.buildFixPrompt(prdPath, references);
+            // Execute the AI agent to fix the PRD (writes directly to prdPath)
             const result = await this.agentRunner.runAgent(prompt, {
                 agentType: 'prd-fixer',
                 timeout: 300_000, // 5 minutes should be enough for reformatting
@@ -66,23 +71,29 @@ export class PrdFixer {
                     fixed: false,
                 };
             }
-            // Extract the fixed content from the AI response
-            const fixedContent = this.extractFixedContent(result.output);
-            if (!fixedContent) {
-                this.logger.error({ prdPath }, 'Could not extract fixed content from AI response');
+            // Read the file back to verify the AI wrote it
+            const fixedContent = await this.fileManager.readFile(prdPath);
+            // Validate the AI actually changed the file and it looks like a PRD
+            if (fixedContent === originalContent) {
+                this.logger.error({ prdPath }, 'AI agent did not modify the PRD file');
                 return {
                     content: originalContent,
-                    error: 'Could not extract fixed PRD content from AI response',
+                    error: 'AI agent did not modify the PRD file',
                     fixed: false,
                 };
             }
-            // Create backup of original file
-            const backupPath = `${prdPath}.bak`;
-            await this.fileManager.writeFile(backupPath, originalContent);
-            this.logger.info({ backupPath }, 'Created backup of original PRD');
-            // Write the fixed content to the original path
-            await this.fileManager.writeFile(prdPath, fixedContent);
-            this.logger.info({ prdPath }, 'Wrote fixed PRD content');
+            if (!/##\s+Epic\s+\d+/i.test(fixedContent)) {
+                this.logger.error({ prdPath }, 'Fixed file does not contain valid epic headers');
+                // Restore from backup
+                await this.fileManager.writeFile(prdPath, originalContent);
+                this.logger.info({ prdPath }, 'Restored original PRD from backup');
+                return {
+                    content: originalContent,
+                    error: 'AI output did not contain valid epic headers, original restored',
+                    fixed: false,
+                };
+            }
+            this.logger.info({ prdPath }, 'PRD fixed successfully');
             return {
                 content: fixedContent,
                 fixed: true,
@@ -101,94 +112,30 @@ export class PrdFixer {
     /**
      * Build the prompt for fixing the PRD
      *
+     * Instructs the AI to read the file at the given path, reformat it,
+     * and write it back directly to the same path.
+     *
      * @param prdPath - Path to the PRD file
-     * @param content - Original PRD content
      * @param references - Optional reference files
      * @returns Complete prompt string for the AI agent
      */
-    buildFixPrompt(prdPath, content, references) {
-        // Build reference context if provided
+    buildFixPrompt(prdPath, references) {
         let referenceContext = '';
         if (references && references.length > 0) {
-            referenceContext = `
-
-REFERENCE FILES FOR CONTEXT:
-${references.map((ref) => `- ${ref}`).join('\n')}
-
-Read these reference files to understand the project context and patterns.`;
+            referenceContext = `\nAlso read these reference files for project context:\n${references.map((ref) => `- ${ref}`).join('\n')}\n`;
         }
-        return `You are a PRD formatting expert. Your task is to reformat a Product Requirements Document (PRD) to match the expected structure for automated workflow processing.
-
-TASK: Reformat the PRD file at "${prdPath}" to use the correct epic and story format.
-
-EXPECTED FORMAT:
-1. Epic headers MUST use this exact format: ## Epic N: Title
-   - Examples: "## Epic 1: Foundation & Setup", "## Epic 2: Core Features"
-   - The "Epic" keyword is REQUIRED
-   - The number MUST be sequential (1, 2, 3...)
-   - A colon separates the number from the title
-
-2. Story sections within epics should use:
-   - ### Stories (as a section header)
-   - Bullet points: - Story N.M: Description
-   - Example: "- Story 1.1: Initialize project structure"
-
-3. Each epic should have:
-   - A description paragraph after the header
-   - A ### Goals section with bullet points
-   - A ### Stories section with story bullet points
-
-CURRENT PRD CONTENT:
-\`\`\`markdown
-${content}
-\`\`\`
+        return `You are a PRD formatting expert. Read the PRD file at "${prdPath}", reformat it to match the expected structure, and write the result back to the same file.
 ${referenceContext}
+EXPECTED FORMAT:
+1. Epic headers: ## Epic N: Title (keyword "Epic" required, sequential numbering, colon separator)
+2. Story headers within epics: ### Story N.M: Title (N=epic number, M=story number)
+3. Each story should have acceptance criteria
 
 INSTRUCTIONS:
-1. Analyze the current PRD structure
+1. Read "${prdPath}"
 2. Identify all epics/features/phases (they might be labeled differently)
-3. Reformat them to use "## Epic N: Title" format
-4. Ensure stories are properly formatted under each epic
-5. Preserve ALL original content and meaning - only change the formatting
-6. Number epics sequentially starting from 1
-7. Number stories as N.M where N is the epic number and M is the story number within that epic
-
-OUTPUT FORMAT:
-Output ONLY the reformatted PRD content wrapped in a markdown code block.
-Do not include any explanation before or after the code block.
-The output must be a complete, valid markdown document.
-
-\`\`\`markdown
-[Your reformatted PRD here]
-\`\`\``;
-    }
-    /**
-     * Extract the fixed PRD content from the AI response
-     *
-     * Looks for content wrapped in markdown code blocks and extracts it.
-     *
-     * @param output - Raw AI response output
-     * @returns Extracted PRD content or null if not found
-     */
-    extractFixedContent(output) {
-        // Try to extract content from markdown code block
-        const codeBlockMatch = output.match(/```(?:markdown)?\s*\n([\s\S]*?)\n```/);
-        if (codeBlockMatch && codeBlockMatch[1]) {
-            const extracted = codeBlockMatch[1].trim();
-            // Validate it looks like a PRD (has at least one epic header)
-            if (/##\s+Epic\s+\d+/i.test(extracted)) {
-                return extracted;
-            }
-        }
-        // Fallback: if the output itself looks like a valid PRD
-        if (/##\s+Epic\s+\d+/i.test(output)) {
-            // Strip any leading/trailing explanation text
-            const lines = output.split('\n');
-            const prdStart = lines.findIndex((line) => line.startsWith('#'));
-            if (prdStart !== -1) {
-                return lines.slice(prdStart).join('\n').trim();
-            }
-        }
-        return null;
+3. Reformat epic headers to "## Epic N: Title" and story headers to "### Story N.M: Title"
+4. Preserve ALL original content and meaning — only change the formatting
+5. Write the complete reformatted PRD back to "${prdPath}"`;
     }
 }

package/dist/services/parsers/prd-parser.d.ts

@@ -53,6 +53,14 @@ export declare class PrdParser {
      *
      * CRITICAL: Pattern order matches prd-tmpl.yaml output format
      * Template generates: ## Epic 1 Title (space-separated)
+     *
+     * Patterns support both H2 (##) and H3 (###) epic headers.
+     * PRDs may use H3 for epics when H2 is used for document sections
+     * (e.g., ## 6. Epic Details → ### Epic 1: Title).
+     *
+     * Generic patterns (N: and N.) are only used as fallback when no
+     * explicit "Epic N" patterns match — they can false-positive on
+     * numbered document sections like "## 1. Goals".
      */
     private readonly patterns;
     /**
@@ -82,6 +90,17 @@ export declare class PrdParser {
      * ```
      */
     parseEpics(prdContent: string, prdPath: string): Epic[];
+    /**
+     * Count stories per epic within a PRD document
+     *
+     * Splits the PRD into epic sections and counts story headers in each.
+     * Used by `prd fix` to validate that epics contain stories.
+     *
+     * @param prdContent - Full PRD markdown content
+     * @param epics - Parsed epics from `parseEpics()`
+     * @returns Map of epic number to story count
+     */
+    countStoriesPerEpic(prdContent: string, epics: Epic[]): Map<number, number>;
     /**
      * Deduplicate matches that appear at the same position
      *

package/dist/services/parsers/prd-parser.js

@@ -32,12 +32,32 @@ export class PrdParser {
      *
      * CRITICAL: Pattern order matches prd-tmpl.yaml output format
      * Template generates: ## Epic 1 Title (space-separated)
+     *
+     * Patterns support both H2 (##) and H3 (###) epic headers.
+     * PRDs may use H3 for epics when H2 is used for document sections
+     * (e.g., ## 6. Epic Details → ### Epic 1: Title).
+     *
+     * Generic patterns (N: and N.) are only used as fallback when no
+     * explicit "Epic N" patterns match — they can false-positive on
+     * numbered document sections like "## 1. Goals".
      */
     patterns = [
         {
             name: 'Epic N Nested (N. Epic M:)',
             regex: /^##\s+\d+\.\s+Epic\s+(\d+)\s*:\s*(.+?)$/gim,
         },
+        {
+            name: 'H3 Epic N: Title',
+            regex: /^###\s+Epic\s+(\d+)\s*:\s*(.+?)$/gim,
+        },
+        {
+            name: 'H3 Epic N - Title',
+            regex: /^###\s+Epic\s+(\d+)\s+-\s+(.+?)$/gim,
+        },
+        {
+            name: 'H3 Epic N Title (space)',
+            regex: /^###\s+Epic\s+(\d+)\s+(?![:-])(.+?)$/gim,
+        },
         {
             name: 'Epic N: Title',
             regex: /^##\s+Epic\s+(\d+)\s*:\s*(.+?)$/gim,
@@ -106,16 +126,27 @@ export class PrdParser {
         // Collect matches from all patterns - patterns are ordered by specificity
         // More specific "Epic N" patterns come first in the array
         const allMatches = [];
+        let hasExplicitEpicMatches = false;
         for (const pattern of this.patterns) {
             // Skip "N. Title" pattern if nested format found (N. is used for sections)
             if (hasNestedEpicFormat && pattern.name === 'N. Title') {
                 this.logger.debug({ patternName: pattern.name }, 'Skipping N. pattern - nested Epic format found in PRD');
                 continue;
             }
+            // Skip generic number-only patterns when explicit "Epic N" patterns already matched
+            // Generic patterns like "## 1. Goals" false-positive on document section headers
+            if (hasExplicitEpicMatches && (pattern.name === 'N: Title' || pattern.name === 'N. Title')) {
+                this.logger.debug({ patternName: pattern.name }, 'Skipping generic pattern - explicit Epic patterns already matched');
+                continue;
+            }
             const matches = this.matchPattern(pattern, lines, prdContent);
             if (matches.length > 0) {
                 allMatches.push(...matches);
                 this.logger.debug({ matches: matches.length, patternName: pattern.name }, 'Pattern matched epics');
+                // Track if we found explicit "Epic N" patterns (any pattern with "Epic" in the name)
+                if (pattern.name.includes('Epic')) {
+                    hasExplicitEpicMatches = true;
+                }
             }
         }
         // Check if any epics were found
@@ -135,6 +166,45 @@ export class PrdParser {
         this.logger.info({ epicCount: epics.length, prdPath }, 'Successfully parsed epics from PRD');
         return epics;
     }
+    /**
+     * Count stories per epic within a PRD document
+     *
+     * Splits the PRD into epic sections and counts story headers in each.
+     * Used by `prd fix` to validate that epics contain stories.
+     *
+     * @param prdContent - Full PRD markdown content
+     * @param epics - Parsed epics from `parseEpics()`
+     * @returns Map of epic number to story count
+     */
+    countStoriesPerEpic(prdContent, epics) {
+        const lines = prdContent.split('\n');
+        const result = new Map();
+        // Story header patterns matching EpicParser patterns
+        const storyPatterns = [
+            /^###\s+Story\s+(\d+)\.(\d+)\s*:\s*.+$/i,
+            /^###\s+Story\s+(\d+)\.(\d+)\s+-\s+.+$/i,
+            /^###\s+(\d+)\.(\d+)\s*:\s*.+$/i,
+            /^###\s+(\d+)\.(\d+)\s*\.\s+.+$/i,
+        ];
+        for (const epic of epics) {
+            // Find the end of this epic's section (next epic's position or EOF)
+            const nextEpic = epics.find((e) => e.position > epic.position);
+            const sectionEnd = nextEpic ? nextEpic.position : lines.length;
+            const sectionLines = lines.slice(epic.position, sectionEnd);
+            let storyCount = 0;
+            for (const line of sectionLines) {
+                for (const pattern of storyPatterns) {
+                    if (pattern.test(line)) {
+                        storyCount++;
+                        break;
+                    }
+                }
+            }
+            result.set(epic.number, storyCount);
+            this.logger.debug({ epicNumber: epic.number, storyCount }, 'Counted stories in epic section');
+        }
+        return result;
+    }
     /**
      * Deduplicate matches that appear at the same position
      *
@@ -212,12 +282,8 @@ export class PrdParser {
             const position = this.findLineNumber(lines, fullMatch);
             // Extract fullNumber based on pattern type
             let fullNumber;
-            if (pattern.name.includes('Nested')) {
-                // For nested format "## N. Epic M:", use "Epic M"
-                fullNumber = `Epic ${epicNumber}`;
-            }
-            else if (pattern.name.startsWith('Epic N')) {
-                // For Epic patterns, use "Epic N"
+            if (pattern.name.includes('Nested') || pattern.name.includes('Epic N') || pattern.name.includes('H3 Epic')) {
+                // For explicit Epic patterns (H2, H3, nested), use "Epic N"
                 fullNumber = `Epic ${epicNumber}`;
             }
             else {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hyperdrive.bot/bmad-workflow",
   "description": "AI-driven development workflow orchestration CLI for BMAD projects",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "author": {
     "name": "DevSquad",
     "email": "marcelo@devsquad.email",