@hyperdrive.bot/bmad-workflow 1.0.2

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

@@ -0,0 +1,262 @@
+/**
+ * StoryParser Service
+ *
+ * Extracts metadata from story files and provides utilities for updating story status.
+ * Supports multiple status formats (inline and section-based) with resilient parsing.
+ */
+import { basename } from 'node:path';
+import { ParserError } from '../../utils/errors.js';
+/**
+ * StoryParser service for extracting metadata from story files
+ *
+ * Provides methods to parse story files and extract key metadata including
+ * story number, title, and status. Supports resilient parsing with multiple
+ * status format patterns.
+ */
+export class StoryParser {
+    /**
+     * FileManager instance for file operations
+     */
+    fileManager;
+    /**
+     * Logger instance for parsing operations
+     */
+    logger;
+    /**
+     * Create a new StoryParser instance
+     *
+     * @param fileManager - FileManager service for file operations
+     * @param logger - Pino logger instance for logging parsing operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:parsers:story' })
+     * const fileManager = new FileManager(logger)
+     * const parser = new StoryParser(fileManager, logger)
+     */
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Parse epic-based story metadata from a story file
+     *
+     * Extracts story number from filename, title from H1 header, and status
+     * from either inline format (**Status**: Draft) or section-based format
+     * (## Status\n\nDraft). Validates story file structure and throws errors
+     * for malformed files.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @returns Epic story metadata with number, title, status, and file path
+     * @throws If file cannot be read
+     * @throws {ParserError} If story structure is invalid (missing title, missing status, missing epic.story number)
+     * @example
+     * const metadata = await parser.parseStoryMetadata('docs/stories/BMAD-2.3-story.md')
+     * console.log(metadata.number) // "2.3"
+     * console.log(metadata.status) // "Draft"
+     * console.log(metadata.type) // "epic-based"
+     */
+    async parseStoryMetadata(storyPath) {
+        this.logger.info('Parsing story metadata from: %s', storyPath);
+        // Read story file content
+        const content = await this.fileManager.readFile(storyPath);
+        // Extract story number from filename
+        const { epicNumber, number, storyNumber } = this.extractStoryNumber(storyPath);
+        // Extract title from H1 header
+        const title = this.extractTitle(content, storyPath);
+        // Extract status using multiple pattern strategies
+        const status = this.extractStatus(content, storyPath);
+        this.logger.info('Successfully parsed story metadata: %s (Epic: %d, Story: %d, Status: %s)', number, epicNumber, storyNumber, status);
+        return {
+            epicNumber,
+            filePath: storyPath,
+            id: number,
+            number,
+            status,
+            storyNumber,
+            title,
+            type: 'epic-based',
+        };
+    }
+    /**
+     * Update story status in a story file
+     *
+     * Reads the story file, detects the current status format (inline or section-based),
+     * and updates the status value while preserving the original format. This ensures
+     * that inline status remains inline and section-based status remains section-based.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @param newStatus - New status value to set
+     * @throws If file cannot be read or written
+     * @throws {ParserError} If status format cannot be detected
+     * @example
+     * await parser.updateStoryStatus('docs/stories/BMAD-2.3-story.md', 'Ready')
+     */
+    async updateStoryStatus(storyPath, newStatus) {
+        this.logger.info('Updating story status in %s to: %s', storyPath, newStatus);
+        // Read current story file content
+        const content = await this.fileManager.readFile(storyPath);
+        // Detect current status and format
+        const { format, oldStatus } = this.detectStatusFormat(content, storyPath);
+        // Update status based on detected format
+        let updatedContent;
+        if (format === 'inline') {
+            // Inline format: **Status**: Draft
+            updatedContent = content.replace(/\*\*Status\*\*:\s*\w+/, `**Status**: ${newStatus}`);
+        }
+        else if (format === 'section-bold') {
+            // Section with bold: ## Status\n\n**Draft**
+            updatedContent = content.replace(/^## Status\s*\n\s*\n\s*\*\*\w+\*\*/m, `## Status\n\n**${newStatus}**`);
+        }
+        else {
+            // Section plain: ## Status\n\nDraft
+            updatedContent = content.replace(/^## Status\s*\n\s*\n\s*\w+/m, `## Status\n\n${newStatus}`);
+        }
+        // Write updated content back to file
+        await this.fileManager.writeFile(storyPath, updatedContent);
+        this.logger.info('Story status updated successfully: %s → %s (format: %s)', oldStatus, newStatus, format);
+    }
+    /**
+     * Detect status format (inline vs section-based) and extract current status
+     *
+     * Used by updateStoryStatus to determine how to update the status value
+     * while preserving the original format.
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Object with format type and old status value
+     * @throws {ParserError} If status format cannot be detected
+     */
+    detectStatusFormat(content, storyPath) {
+        // Check for inline format: **Status**: Draft
+        const inlineMatch = /\*\*Status\*\*:\s*(\w+)/.exec(content);
+        if (inlineMatch) {
+            return { format: 'inline', oldStatus: inlineMatch[1].trim() };
+        }
+        // Check for section with bold: ## Status\n\n**Draft**
+        const boldSectionMatch = /^## Status\s*\n\s*\n\s*\*\*(\w+)\*\*/m.exec(content);
+        if (boldSectionMatch) {
+            return { format: 'section-bold', oldStatus: boldSectionMatch[1].trim() };
+        }
+        // Check for section plain: ## Status\n\nDraft (no bold markers)
+        const plainSectionMatch = /^## Status\s*\n\s*\n\s*(?!\*\*)(\w+)/m.exec(content);
+        if (plainSectionMatch) {
+            return { format: 'section', oldStatus: plainSectionMatch[1].trim() };
+        }
+        // Status format not detected
+        this.logger.error('Unable to detect status format in: %s', storyPath);
+        throw new ParserError('Unable to detect status format', {
+            filePath: storyPath,
+            suggestion: 'Ensure story has valid Status section in one of the supported formats',
+        });
+    }
+    /**
+     * Extract story status using multiple pattern strategies
+     *
+     * Tries multiple patterns to extract status (in order of specificity):
+     * 1. Inline format: **Status**: Draft
+     * 2. Section with bold: ## Status\n\n**Draft**
+     * 3. Section plain: ## Status\n\nDraft
+     * 4. Fallback: any word after Status header
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted status value
+     * @throws {ParserError} If status cannot be found in any supported format
+     */
+    extractStatus(content, storyPath) {
+        // Pattern 1: Inline format - **Status**: Draft
+        const inlineMatch = /\*\*Status\*\*:\s*(\w+)/.exec(content);
+        if (inlineMatch) {
+            const status = inlineMatch[1].trim();
+            this.logger.debug('Extracted status (inline format): %s', status);
+            return status;
+        }
+        // Pattern 2: Section with bold - ## Status\n\n**Draft**
+        const boldSectionMatch = /^## Status\s*\n\s*\n\s*\*\*(\w+)\*\*/m.exec(content);
+        if (boldSectionMatch) {
+            const status = boldSectionMatch[1].trim();
+            this.logger.debug('Extracted status (section bold format): %s', status);
+            return status;
+        }
+        // Pattern 3: Section plain - ## Status\n\nDraft (no bold markers)
+        const plainSectionMatch = /^## Status\s*\n\s*\n\s*(?!\*\*)(\w+)/m.exec(content);
+        if (plainSectionMatch) {
+            const status = plainSectionMatch[1].trim();
+            this.logger.debug('Extracted status (section plain format): %s', status);
+            return status;
+        }
+        // Pattern 4: Fallback - any text after ## Status (more lenient)
+        const fallbackMatch = /^## Status\s*\n+\s*(.+?)(?:\n|$)/m.exec(content);
+        if (fallbackMatch) {
+            // Clean up the match: remove markdown formatting, trim whitespace
+            const rawStatus = fallbackMatch[1]
+                .replaceAll('**', '') // Remove bold markers
+                .replaceAll(/[_*]/g, '') // Remove italic/emphasis markers
+                .replaceAll('---', '') // Remove horizontal rules
+                .trim();
+            if (rawStatus && /^\w+$/.test(rawStatus)) {
+                const status = rawStatus;
+                this.logger.debug('Extracted status (fallback format): %s', status);
+                return status;
+            }
+        }
+        // Status not found in any supported format
+        this.logger.error('Story file missing Status section or field: %s', storyPath);
+        throw new ParserError('Story file missing Status section or field', {
+            filePath: storyPath,
+            suggestion: 'Ensure story has "## Status" section followed by status value (Draft, Ready, In Progress, etc.)',
+        });
+    }
+    /**
+     * Extract story number from filename
+     *
+     * Parses filename to extract epic and story numbers. Supports patterns like:
+     * - BMAD-2.3-story.md → epicNumber: 2, storyNumber: 3
+     * - PREFIX-1.5-description.md → epicNumber: 1, storyNumber: 5
+     *
+     * @param storyPath - Path to the story file
+     * @returns Object with epicNumber, storyNumber, and full number string
+     * @throws {ParserError} If filename does not contain valid story number pattern
+     */
+    extractStoryNumber(storyPath) {
+        const filename = basename(storyPath);
+        const match = /(\d+)\.(\d+)/.exec(filename);
+        if (!match) {
+            this.logger.error('Invalid story filename format: %s', filename);
+            throw new ParserError('Story filename must contain epic.story number (e.g., 2.3)', {
+                filename,
+                filePath: storyPath,
+            });
+        }
+        const epicNumber = Number.parseInt(match[1], 10);
+        const storyNumber = Number.parseInt(match[2], 10);
+        const number = `${epicNumber}.${storyNumber}`;
+        this.logger.debug('Extracted story number: %s (epic: %d, story: %d)', number, epicNumber, storyNumber);
+        return { epicNumber, number, storyNumber };
+    }
+    /**
+     * Extract story title from H1 header
+     *
+     * Finds the first H1 header in the content and extracts the title.
+     * Removes the "Story X.Y:" prefix if present.
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted title without "Story X.Y:" prefix
+     * @throws {ParserError} If H1 header is not found
+     */
+    extractTitle(content, storyPath) {
+        // Match first H1 header: # Story 2.3: Create Story Parser Service
+        const match = /^# (.+)$/m.exec(content);
+        if (!match) {
+            this.logger.error('Story file missing H1 title header: %s', storyPath);
+            throw new ParserError('Story file missing H1 title header', {
+                filePath: storyPath,
+            });
+        }
+        const rawTitle = match[1].trim();
+        // Remove "Story X.Y:" prefix if present
+        const title = rawTitle.replace(/^Story\s+\d+\.\d+:\s*/, '');
+        this.logger.debug('Extracted title: %s', title);
+        return title;
+    }
+}

package/dist/services/scaffolding/decompose-session-scaffolder.d.ts

@@ -0,0 +1,74 @@
+/**
+ * DecomposeSessionScaffolder
+ *
+ * Creates the directory structure and initial files for a decompose session.
+ * Organizes task graphs, prompts, outputs, and reports in a structured format.
+ */
+import type pino from 'pino';
+import type { DecomposeSessionConfig, GraphExecutionResult, TaskGraph } from '../../types/task-graph.js';
+import type { FileManager } from '../file-system/file-manager.js';
+/**
+ * Scaffolder for decompose session directory structure
+ */
+export declare class DecomposeSessionScaffolder {
+    private readonly fileManager;
+    private readonly logger;
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Create the session directory structure
+     *
+     * Creates:
+     * - Session root directory
+     * - prompts/ subdirectory for task-specific prompts
+     * - outputs/ or stories/ subdirectory for task execution results (depends on story mode)
+     *
+     * @param sessionDir - Root directory for the session
+     * @param storyFormat - Whether to create stories/ instead of outputs/
+     * @returns Session directory path
+     */
+    createSessionStructure(sessionDir: string, storyFormat?: boolean): Promise<string>;
+    /**
+     * Write the execution report file (after execution completes)
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     * @param executionResult - Result of graph execution
+     */
+    writeExecutionReport(sessionDir: string, taskGraph: TaskGraph, executionResult: GraphExecutionResult): Promise<void>;
+    /**
+     * Write the goal description file
+     *
+     * @param sessionDir - Session directory
+     * @param config - Session configuration
+     */
+    writeGoalFile(sessionDir: string, config: DecomposeSessionConfig): Promise<void>;
+    /**
+     * Write the master prompt file
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     */
+    writeMasterPromptFile(sessionDir: string, taskGraph: TaskGraph): Promise<void>;
+    /**
+     * Create a README for the session
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     * @param storyFormat - Whether this is story format mode
+     */
+    writeSessionReadme(sessionDir: string, taskGraph: TaskGraph, storyFormat?: boolean): Promise<void>;
+    /**
+     * Write the task graph YAML file
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     */
+    writeTaskGraphFile(sessionDir: string, taskGraph: TaskGraph): Promise<void>;
+    /**
+     * Write individual task prompt files
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     */
+    writeTaskPromptFiles(sessionDir: string, taskGraph: TaskGraph): Promise<void>;
+}

package/dist/services/scaffolding/decompose-session-scaffolder.js

@@ -0,0 +1,315 @@
+/**
+ * DecomposeSessionScaffolder
+ *
+ * Creates the directory structure and initial files for a decompose session.
+ * Organizes task graphs, prompts, outputs, and reports in a structured format.
+ */
+import * as yaml from 'js-yaml';
+import { join } from 'node:path';
+/**
+ * Scaffolder for decompose session directory structure
+ */
+export class DecomposeSessionScaffolder {
+    fileManager;
+    logger;
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Create the session directory structure
+     *
+     * Creates:
+     * - Session root directory
+     * - prompts/ subdirectory for task-specific prompts
+     * - outputs/ or stories/ subdirectory for task execution results (depends on story mode)
+     *
+     * @param sessionDir - Root directory for the session
+     * @param storyFormat - Whether to create stories/ instead of outputs/
+     * @returns Session directory path
+     */
+    async createSessionStructure(sessionDir, storyFormat = false) {
+        this.logger.info({ sessionDir, storyFormat }, 'Creating decompose session structure');
+        // Create root session directory
+        await this.fileManager.createDirectory(sessionDir);
+        // Create subdirectories
+        await this.fileManager.createDirectory(join(sessionDir, 'prompts'));
+        // Create either stories/ or outputs/ directory depending on mode
+        const subDir = storyFormat ? 'stories' : 'outputs';
+        await this.fileManager.createDirectory(join(sessionDir, subDir));
+        this.logger.info({ sessionDir, storyFormat }, 'Session structure created');
+        return sessionDir;
+    }
+    /**
+     * Write the execution report file (after execution completes)
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     * @param executionResult - Result of graph execution
+     */
+    async writeExecutionReport(sessionDir, taskGraph, executionResult) {
+        const reportPath = join(sessionDir, 'execution-report.yaml');
+        const yamlContent = yaml.dump({
+            completedAt: new Date().toISOString(),
+            completedTasks: executionResult.completedTasks,
+            failedTasks: executionResult.failedTasks,
+            goal: taskGraph.goal,
+            layerResults: executionResult.executionSummary.layerResults,
+            sessionId: taskGraph.session.id,
+            skippedTasks: executionResult.skippedTasks,
+            startedAt: taskGraph.session.createdAt,
+            success: executionResult.success,
+            taskResults: executionResult.taskResults.map((r) => ({
+                duration: r.duration,
+                errors: r.errors,
+                exitCode: r.exitCode,
+                success: r.success,
+                taskId: r.taskId,
+            })),
+            totalDuration: executionResult.totalDuration,
+            totalTasks: executionResult.totalTasks,
+        }, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+        });
+        await this.fileManager.writeFile(reportPath, yamlContent);
+        this.logger.info({ reportPath }, 'Execution report written');
+    }
+    /**
+     * Write the goal description file
+     *
+     * @param sessionDir - Session directory
+     * @param config - Session configuration
+     */
+    async writeGoalFile(sessionDir, config) {
+        const goalPath = join(sessionDir, 'goal.md');
+        const content = `# Goal
+
+**Session ID:** ${config.sessionId}
+**Created:** ${config.createdAt.toISOString()}
+**Working Directory:** ${config.options.cwd ?? 'current directory'}
+
+## Objective
+
+${config.goal}
+
+## Options
+
+- **Per-File Mode:** ${config.options.perFile ? 'Enabled' : 'Disabled'}
+${config.options.filePattern ? `- **File Pattern:** \`${config.options.filePattern}\`` : ''}
+- **Max Parallel:** ${config.options.maxParallel ?? 3}
+- **Plan Only:** ${config.options.planOnly ? 'Yes' : 'No'}
+
+## Context Files
+
+${config.options.contextFiles && config.options.contextFiles.length > 0 ? config.options.contextFiles.map((f) => `- \`${f}\``).join('\n') : '_None provided_'}
+
+---
+
+<!-- Powered by BMAD™ Core -->
+`;
+        await this.fileManager.writeFile(goalPath, content);
+        this.logger.debug({ goalPath }, 'Goal file written');
+    }
+    /**
+     * Write the master prompt file
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     */
+    async writeMasterPromptFile(sessionDir, taskGraph) {
+        const masterPath = join(sessionDir, 'master-prompt.md');
+        const content = `# Master Prompt Template
+
+**Session ID:** ${taskGraph.session.id}
+**Goal:** ${taskGraph.goal}
+
+## Reusable Template
+
+This prompt template applies to all tasks in this session and can be reused for similar goals.
+
+\`\`\`
+${taskGraph.masterPrompt}
+\`\`\`
+
+## Usage
+
+This master prompt is automatically included in each task execution. It provides:
+- Common guidelines and best practices
+- Project-specific coding standards
+- Quality expectations
+- General instructions that apply to all tasks
+
+When executing tasks individually, prepend this master prompt to the task-specific prompt.
+
+---
+
+<!-- Powered by BMAD™ Core -->
+`;
+        await this.fileManager.writeFile(masterPath, content);
+        this.logger.debug({ masterPath }, 'Master prompt file written');
+    }
+    /**
+     * Create a README for the session
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     * @param storyFormat - Whether this is story format mode
+     */
+    async writeSessionReadme(sessionDir, taskGraph, storyFormat = false) {
+        const readmePath = join(sessionDir, 'SESSION_README.md');
+        const outputDirName = storyFormat ? 'stories' : 'outputs';
+        const outputDescription = storyFormat ? 'Story files (BMAD format)' : 'Task execution results';
+        const content = `# Decompose Session: ${taskGraph.session.id}
+
+**Goal:** ${taskGraph.goal}
+**Created:** ${taskGraph.session.createdAt}
+**Total Tasks:** ${taskGraph.metadata.totalTasks}
+**Estimated Duration:** ${taskGraph.metadata.estimatedDuration} minutes
+**Execution Layers:** ${taskGraph.metadata.executionLayers.length}
+${storyFormat ? `**Format:** Story Mode (BMAD Stories)\n` : ''}
+
+## Directory Structure
+
+\`\`\`
+${taskGraph.session.id}/
+├── SESSION_README.md          # This file
+├── goal.md                    # Original goal and options
+├── master-prompt.md           # Reusable prompt template
+├── task-graph.yaml            # Complete task dependency graph
+├── execution-report.yaml      # Execution results (after completion)
+├── prompts/                   # Individual ${storyFormat ? 'story' : 'task'} prompts
+│   ├── ${storyFormat ? `${taskGraph.tasks[0]?.id || 'STORY-001'}` : 'task-001'}-prompt.md
+│   ├── ${storyFormat ? `${taskGraph.tasks[1]?.id || 'STORY-002'}` : 'task-002'}-prompt.md
+│   └── ...
+└── ${outputDirName}/                   # ${outputDescription}
+    ├── ${storyFormat ? `${taskGraph.tasks[0]?.id || 'STORY-001'}` : 'task-001-output'}.md
+    ├── ${storyFormat ? `${taskGraph.tasks[1]?.id || 'STORY-002'}` : 'task-002-output'}.md
+    └── ...
+\`\`\`
+
+## Execution Layers
+
+${taskGraph.metadata.executionLayers
+            .map((layer, idx) => `### Layer ${idx + 1} (${layer.length} task${layer.length > 1 ? 's' : ''} in parallel)
+
+${layer.map((taskId) => `- \`${taskId}\``).join('\n')}
+`)
+            .join('\n')}
+
+## Task Overview
+
+${taskGraph.tasks
+            .map((task) => `### ${task.id}: ${task.title}
+
+- **Estimated Time:** ${task.estimatedMinutes} min
+- **Dependencies:** ${task.dependencies.length > 0 ? task.dependencies.join(', ') : 'None'}
+- **Agent:** ${task.agentType ?? 'dev'}
+`)
+            .join('\n')}
+
+## How to Use This Session
+
+1. **Review the task graph:** Check \`task-graph.yaml\` for the complete plan
+2. **Execute tasks:** Run \`bmad-cli decompose --execute\` or execute manually
+3. **Check outputs:** Review task results in \`outputs/\` directory
+4. **Reuse prompts:** Use \`master-prompt.md\` for similar projects
+
+---
+
+<!-- Powered by BMAD™ Core -->
+`;
+        await this.fileManager.writeFile(readmePath, content);
+        this.logger.info({ readmePath }, 'Session README written');
+    }
+    /**
+     * Write the task graph YAML file
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     */
+    async writeTaskGraphFile(sessionDir, taskGraph) {
+        const graphPath = join(sessionDir, 'task-graph.yaml');
+        // Convert task graph to YAML-friendly format
+        const yamlContent = yaml.dump({
+            goal: taskGraph.goal,
+            masterPrompt: taskGraph.masterPrompt,
+            metadata: taskGraph.metadata,
+            session: taskGraph.session,
+            tasks: taskGraph.tasks.map((t) => ({
+                agentType: t.agentType,
+                dependencies: t.dependencies,
+                description: t.description,
+                estimatedMinutes: t.estimatedMinutes,
+                id: t.id,
+                outputFile: t.outputFile,
+                parallelizable: t.parallelizable,
+                prompt: t.prompt,
+                targetFiles: t.targetFiles,
+                title: t.title,
+            })),
+        }, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+        });
+        await this.fileManager.writeFile(graphPath, yamlContent);
+        this.logger.info({ graphPath, totalTasks: taskGraph.tasks.length }, 'Task graph YAML written');
+    }
+    /**
+     * Write individual task prompt files
+     *
+     * @param sessionDir - Session directory
+     * @param taskGraph - Complete task graph
+     */
+    async writeTaskPromptFiles(sessionDir, taskGraph) {
+        this.logger.info({ taskCount: taskGraph.tasks.length }, 'Writing individual task prompt files');
+        // Write task files sequentially to avoid overwhelming file system
+        for (const task of taskGraph.tasks) {
+            const promptPath = join(sessionDir, 'prompts', `${task.id}-prompt.md`);
+            const content = `# ${task.title}
+
+**Task ID:** ${task.id}
+**Estimated Time:** ${task.estimatedMinutes} minutes
+**Agent Type:** ${task.agentType ?? 'dev'}
+**Parallelizable:** ${task.parallelizable ? 'Yes' : 'No'}
+
+## Description
+
+${task.description}
+
+## Dependencies
+
+${task.dependencies.length > 0 ? task.dependencies.map((d) => `- ${d}`).join('\n') : '_None - can run immediately_'}
+
+## Target Files
+
+${task.targetFiles && task.targetFiles.length > 0 ? task.targetFiles.map((f) => `- \`${f}\``).join('\n') : '_No specific files_'}
+
+## Prompt
+
+\`\`\`
+${task.prompt}
+\`\`\`
+
+## Master Prompt Context
+
+\`\`\`
+${taskGraph.masterPrompt}
+\`\`\`
+
+## Output File
+
+\`${task.outputFile}\`
+
+---
+
+<!-- Powered by BMAD™ Core -->
+`;
+            // eslint-disable-next-line no-await-in-loop -- sequential file writes prevent overwhelming filesystem
+            await this.fileManager.writeFile(promptPath, content);
+        }
+        this.logger.info({ taskCount: taskGraph.tasks.length }, 'Task prompt files written');
+    }
+}