@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/orchestration/task-decomposition-service.js

@@ -0,0 +1,607 @@
+/**
+ * TaskDecompositionService
+ *
+ * Decomposes large goals into executable task graphs with dependency management.
+ * Leverages Claude AI to intelligently break down complex objectives into
+ * small, actionable tasks with proper sequencing and parallelization.
+ */
+import * as yaml from 'js-yaml';
+/**
+ * Service for decomposing goals into task graphs
+ */
+export class TaskDecompositionService {
+    agentRunner;
+    fileManager;
+    globMatcher;
+    logger;
+    constructor(agentRunner, fileManager, globMatcher, logger) {
+        this.agentRunner = agentRunner;
+        this.fileManager = fileManager;
+        this.globMatcher = globMatcher;
+        this.logger = logger;
+    }
+    /**
+     * Decompose a goal into an executable task graph
+     *
+     * @param options - Decomposition options including goal, context, and mode
+     * @param sessionDir - Directory where session outputs will be stored
+     * @returns Complete task graph with dependencies
+     */
+    async decomposeGoal(options, sessionDir) {
+        this.logger.info({ goal: options.goal, perFile: options.perFile }, 'Starting goal decomposition');
+        // If per-file mode is enabled, gather target files first
+        let targetFiles = [];
+        if (options.perFile && options.filePattern) {
+            targetFiles = await this.gatherTargetFiles(options.filePattern);
+            this.logger.info({ fileCount: targetFiles.length, pattern: options.filePattern }, 'Gathered target files');
+        }
+        // Build decomposition prompt
+        const prompt = this.buildDecompositionPrompt(options, targetFiles, sessionDir);
+        this.logger.debug({ promptLength: prompt.length }, 'Built decomposition prompt');
+        // Execute Claude agent to generate task graph
+        const result = await this.agentRunner.runAgent(prompt, {
+            agentType: (options.agent ?? 'architect'),
+            references: options.contextFiles,
+            timeout: options.taskTimeout ?? 600_000, // 10 min default for planning
+        });
+        if (!result.success) {
+            throw new Error(`Failed to decompose goal: ${result.errors}`);
+        }
+        // Save raw output for debugging
+        try {
+            const debugOutputPath = `${sessionDir}/raw-claude-output.txt`;
+            await this.fileManager.writeFile(debugOutputPath, result.output);
+            this.logger.debug({ debugOutputPath }, 'Saved raw Claude output for debugging');
+        }
+        catch (error) {
+            this.logger.warn({ error: error.message }, 'Failed to save debug output');
+        }
+        // Validate and fix YAML before parsing
+        const validatedOutput = await this.validateAndFixYaml(result.output, options, sessionDir);
+        // Parse YAML output into task graph
+        const taskGraph = this.parseTaskGraph(validatedOutput, options, sessionDir, targetFiles);
+        this.logger.info({
+            estimatedDuration: taskGraph.metadata.estimatedDuration,
+            layers: taskGraph.metadata.executionLayers.length,
+            totalTasks: taskGraph.metadata.totalTasks,
+        }, 'Goal decomposition complete');
+        return taskGraph;
+    }
+    /**
+     * Build the decomposition prompt for Claude
+     */
+    buildDecompositionPrompt(options, targetFiles, sessionDir) {
+        let prompt = `You are an expert system architect specializing in task decomposition.
+
+## GOAL
+${options.goal}
+
+## YOUR MISSION
+Break this goal into small, executable tasks that can be completed by Claude AI agents in approximately 10 minutes each.
+
+## CONSTRAINTS
+- Each task must be atomic and independently executable
+- Tasks should have clear dependencies (what must complete before this task)
+- Identify opportunities for parallel execution
+- Maximum parallel tasks: ${options.maxParallel ?? 3}
+- Tasks must be actionable with specific prompts
+
+## AGENT ASSIGNMENT
+For each task, you MUST choose the most appropriate agent type based on what the task actually does:
+- "dev" - Code implementation, refactoring, bug fixes, feature development
+- "architect" - System design, technical decisions, infrastructure, API design
+- "analyst" - Requirements gathering, data analysis, research, documentation
+- "tea" - Test architecture, testing strategy, test automation, quality validation
+- "pm" - Project planning, coordination, stakeholder communication
+- "sm" - Sprint/process management, team coordination, agile ceremonies
+- "tech-writer" - Technical documentation, API docs, user guides
+- "ux-designer" - UI/UX design, user flows, wireframes, design systems
+- "quick-flow-solo-dev" - Rapid prototyping, solo development, quick iterations
+
+Assign agentType based on the task's nature, NOT the overall goal. A refactoring goal may have architect tasks for planning, dev tasks for implementation, and tea tasks for test validation.
+
+## CRITICAL: TASKS MUST MAKE CODE CHANGES
+**ANALYSIS-ONLY TASKS ARE NOT ACCEPTABLE.**
+
+Every task MUST result in actual source code modifications. Do NOT create tasks that:
+- Only analyze or investigate without making changes
+- Document findings without fixing the issues found
+- Report "no changes needed" without attempting fixes
+- Write summaries instead of making code changes
+
+Each task prompt MUST explicitly specify:
+1. What SOURCE FILES will be MODIFIED (not just read)
+2. What specific CHANGES will be made
+3. How to VERIFY the changes work (run tests, lint, etc.)
+
+If a task cannot make changes (e.g., all issues already fixed), the agent should:
+1. Verify with evidence (show lint output, test results)
+2. Proceed to make any IMPROVEMENTS possible (refactoring, better types, cleaner code)
+3. Only mark complete after exhausting ALL improvement opportunities
+
+`;
+        // Add per-file mode instructions
+        if (options.perFile && targetFiles.length > 0) {
+            // Show a small sample of files for context
+            const sampleSize = Math.min(10, targetFiles.length);
+            const sample = targetFiles.slice(0, sampleSize);
+            prompt += `## PER-FILE MODE ENABLED
+You MUST create one task per file for the main work. This is critical for file-heavy operations like migrations.
+
+**Total Files to Process:** ${targetFiles.length}
+
+**Sample Files (showing ${sampleSize} of ${targetFiles.length}):**
+${sample.join('\n')}
+${targetFiles.length > sampleSize ? `\n... (${targetFiles.length - sampleSize} more files not shown - you'll create tasks for ALL ${targetFiles.length} files)` : ''}
+
+**Task Structure:**
+1. Create analysis/planning tasks first (1-3 tasks)
+2. Create ONE task per file for the core work (${targetFiles.length} tasks total)
+3. Create verification/cleanup tasks last (1-2 tasks)
+
+**CRITICAL:** Each file task should:
+- Have sequential IDs (task-001, task-002, ... task-${targetFiles.length + 3})
+- Reference the specific file in "targetFiles" array
+- Include the file path in the title
+- Have appropriate dependencies on planning tasks
+- Be parallelizable (set parallelizable: true for file tasks)
+
+You don't need to see all file paths - just know there are ${targetFiles.length} files total.
+The system will provide the correct file path for each task in the targetFiles array.
+
+`;
+        }
+        // Add context files
+        if (options.contextFiles && options.contextFiles.length > 0) {
+            prompt += `## CONTEXT FILES
+${options.contextFiles.map((f) => `- ${f}`).join('\n')}
+
+`;
+        }
+        // Add output format instructions (varies based on story format mode)
+        prompt += options.storyFormat ? `## OUTPUT FORMAT - STORY MODE
+You MUST output tasks as BMAD-formatted STORIES with proper structure.
+Output ONLY valid YAML. DO NOT include markdown code fences or any other text.
+
+Each task will become a full story with:
+- Story ID: ${options.storyPrefix}-<number> (e.g., ${options.storyPrefix}-001, ${options.storyPrefix}-002)
+- User story format: "As a... I want... so that..."
+- Acceptance Criteria
+- Tasks/Subtasks breakdown
+- Dev Notes with testing info
+
+\`\`\`yaml
+masterPrompt: |
+  A reusable prompt template that applies to all stories.
+  Include best practices, coding standards, and common guidelines for implementing these stories.
+
+tasks:
+  - id: ${options.storyPrefix}-001
+    title: "Clear, specific story title"
+    description: "High-level description of what this story delivers"
+    estimatedMinutes: 10
+    dependencies: []  # Array of story IDs that must complete first
+    parallelizable: true
+    agentType: "dev"
+    targetFiles:  # Optional: specific files this story operates on
+      - "path/to/file.js"
+    prompt: |
+      Create a story following BMAD story format:
+
+      # Story ${options.storyPrefix}-001: [Title]
+
+      ## Status
+      Draft
+
+      ## Story
+      **As a** [role/persona],
+      **I want** [capability/feature],
+      **so that** [benefit/value]
+
+      ## Acceptance Criteria
+      1. [Specific, testable criterion]
+      2. [Another criterion]
+      3. [Another criterion]
+
+      ## Tasks / Subtasks
+      - [ ] Task 1: [Description] (AC: #1)
+        - [ ] Subtask 1.1: [Specific action]
+        - [ ] Subtask 1.2: [Specific action]
+      - [ ] Task 2: [Description] (AC: #2)
+        - [ ] Subtask 2.1: [Specific action]
+
+      ## Dev Notes
+      [Relevant architecture info, integration points, file locations]
+
+      ### Testing
+      - Test file location: [path]
+      - Test standards: [requirements]
+      - Testing frameworks: [tools being used]
+      - Specific requirements: [any special test needs]
+
+      ## Change Log
+      | Date | Version | Description | Author |
+      |------|---------|-------------|--------|
+      | [Date] | 1.0 | Story created | AI Agent |
+    outputFile: "${sessionDir}/stories/${options.storyPrefix}-001.md"
+
+  - id: ${options.storyPrefix}-002
+    title: "Next story"
+    description: "Story description"
+    estimatedMinutes: 5
+    dependencies: ["${options.storyPrefix}-001"]
+    parallelizable: false
+    agentType: "dev"
+    prompt: |
+      [Story-formatted prompt as above]
+    outputFile: "${sessionDir}/stories/${options.storyPrefix}-002.md"
+
+  # ... more tasks (as stories)
+\`\`\`
+
+**CRITICAL FOR STORY MODE:**
+- Task IDs MUST be story IDs: ${options.storyPrefix}-001, ${options.storyPrefix}-002, etc.
+- Output files MUST go to stories/ directory
+- Prompts MUST generate full story structure (not simple task outputs)
+- Each story must have user story format, acceptance criteria, and tasks breakdown
+
+## IMPORTANT RULES
+1. Each story ID must be unique
+2. Dependencies must reference valid story IDs
+3. Circular dependencies are not allowed
+4. Stories with no dependencies can run immediately
+5. Stories with the same dependencies can run in parallel (if parallelizable: true)
+6. All file paths in outputFile should use the session directory: ${sessionDir}/stories/
+${options.perFile ? '7. **CRITICAL**: Create one story per file for the main work (per-file mode is ON)' : ''}
+
+## EXAMPLE DEPENDENCY PATTERNS
+
+Sequential:
+${options.storyPrefix}-001 (deps: []) → ${options.storyPrefix}-002 (deps: [${options.storyPrefix}-001])
+
+Parallel then join:
+${options.storyPrefix}-001 (deps: []) → [${options.storyPrefix}-002, ${options.storyPrefix}-003] → ${options.storyPrefix}-004
+
+Now, decompose the goal into stories. Output ONLY the YAML structure.
+` : `## OUTPUT FORMAT
+You MUST output ONLY valid YAML in the following structure. DO NOT include markdown code fences or any other text.
+
+\`\`\`yaml
+masterPrompt: |
+  A reusable prompt template that applies to all tasks.
+  Include best practices, coding standards, and common guidelines.
+
+tasks:
+  - id: task-001
+    title: "Clear, specific task title"
+    description: "Detailed description of what this task accomplishes"
+    estimatedMinutes: 10
+    dependencies: []  # Array of task IDs that must complete first
+    parallelizable: true  # Can this run in parallel with other tasks?
+    agentType: "dev"  # Agent type: dev, architect, qa, etc.
+    targetFiles:  # Optional: specific files this task operates on
+      - "path/to/file.js"
+    prompt: |
+      Specific prompt for the agent to execute this task.
+      Include:
+      - What to do
+      - Where to do it (file paths)
+      - Expected outcome
+      - Any validation steps
+    outputFile: "${sessionDir}/outputs/task-001-output.md"
+
+  - id: task-002
+    title: "Next task"
+    description: "Task description"
+    estimatedMinutes: 5
+    dependencies: ["task-001"]  # Must wait for task-001
+    parallelizable: false
+    agentType: "dev"
+    prompt: |
+      Task-specific prompt here
+    outputFile: "${sessionDir}/outputs/task-002-output.md"
+
+  # ... more tasks
+\`\`\`
+
+## IMPORTANT RULES
+1. Each task ID must be unique
+2. Dependencies must reference valid task IDs
+3. Circular dependencies are not allowed
+4. Tasks with no dependencies can run immediately
+5. Tasks with the same dependencies can run in parallel (if parallelizable: true)
+6. All file paths in outputFile should use the session directory: ${sessionDir}/outputs/
+${options.perFile ? '7. **CRITICAL**: Create one task per file for the main work (per-file mode is ON)' : ''}
+
+## EXAMPLE DEPENDENCY PATTERNS
+
+Sequential:
+task-001 (deps: []) → task-002 (deps: [task-001]) → task-003 (deps: [task-002])
+
+Parallel then join:
+task-001 (deps: []) → [task-002, task-003] (deps: [task-001]) → task-004 (deps: [task-002, task-003])
+
+Now, decompose the goal into tasks. Output ONLY the YAML structure.
+`;
+        return prompt;
+    }
+    /**
+     * Build execution layers using topological sort (Kahn's algorithm)
+     * Each layer contains tasks that can run in parallel
+     */
+    buildExecutionLayers(tasks) {
+        const layers = [];
+        const inDegree = new Map();
+        const taskMap = new Map(tasks.map((t) => [t.id, t]));
+        // Calculate in-degree for each task
+        for (const task of tasks) {
+            if (!inDegree.has(task.id)) {
+                inDegree.set(task.id, 0);
+            }
+            for (const depId of task.dependencies) {
+                inDegree.set(depId, (inDegree.get(depId) ?? 0));
+            }
+        }
+        // Set in-degree based on dependencies
+        for (const task of tasks) {
+            inDegree.set(task.id, task.dependencies.length);
+        }
+        // Build layers
+        const remaining = new Set(tasks.map((t) => t.id));
+        while (remaining.size > 0) {
+            // Find all tasks with no remaining dependencies
+            const currentLayer = [...remaining].filter((id) => inDegree.get(id) === 0);
+            if (currentLayer.length === 0) {
+                throw new Error('Cannot build execution layers: possible circular dependency');
+            }
+            layers.push(currentLayer);
+            // Remove current layer tasks and update in-degrees
+            for (const taskId of currentLayer) {
+                remaining.delete(taskId);
+                // Reduce in-degree for tasks that depend on this one
+                for (const otherId of remaining) {
+                    const task = taskMap.get(otherId);
+                    if (task && task.dependencies.includes(taskId)) {
+                        inDegree.set(otherId, (inDegree.get(otherId) ?? 1) - 1);
+                    }
+                }
+            }
+        }
+        return layers;
+    }
+    /**
+     * Detect circular dependencies using DFS
+     */
+    detectCircularDependencies(tasks) {
+        const visited = new Set();
+        const recursionStack = new Set();
+        const taskMap = new Map(tasks.map((t) => [t.id, t]));
+        const dfs = (taskId) => {
+            visited.add(taskId);
+            recursionStack.add(taskId);
+            const task = taskMap.get(taskId);
+            if (!task)
+                return false;
+            for (const depId of task.dependencies) {
+                if (!visited.has(depId)) {
+                    if (dfs(depId))
+                        return true;
+                }
+                else if (recursionStack.has(depId)) {
+                    throw new Error(`Circular dependency detected involving task: ${taskId} -> ${depId}`);
+                }
+            }
+            recursionStack.delete(taskId);
+            return false;
+        };
+        for (const task of tasks) {
+            if (!visited.has(task.id)) {
+                dfs(task.id);
+            }
+        }
+    }
+    /**
+     * Extract YAML content from output (handles markdown code fences)
+     */
+    extractYaml(output) {
+        // Try to extract from markdown code fence first
+        const yamlMatch = output.match(/```(?:yaml|yml)?\s*\n([\s\S]*?)\n```/);
+        if (yamlMatch) {
+            return yamlMatch[1].trim();
+        }
+        // Try to find yaml content without code fences
+        // Look for lines starting with "masterPrompt:" or "tasks:"
+        const lines = output.split('\n');
+        let startIndex = lines.findIndex((line) => line.trim().startsWith('masterPrompt:'));
+        if (startIndex === -1) {
+            // Try finding "tasks:" if masterPrompt not found
+            startIndex = lines.findIndex((line) => line.trim().startsWith('tasks:'));
+        }
+        if (startIndex !== -1) {
+            // Find the end of YAML content (stop at empty lines or obvious non-YAML content)
+            let endIndex = lines.length;
+            for (let i = startIndex + 1; i < lines.length; i++) {
+                const line = lines[i].trim();
+                // Stop if we hit obvious non-YAML content
+                if (line.startsWith('#') && !line.startsWith('# ') && i > startIndex + 5) {
+                    // Could be a comment, but if far from start, likely end of YAML
+                    endIndex = i;
+                    break;
+                }
+            }
+            const yamlContent = lines.slice(startIndex, endIndex).join('\n');
+            return yamlContent.trim();
+        }
+        // Last resort: return everything and let yaml parser try
+        return output.trim();
+    }
+    /**
+     * Gather target files using glob pattern
+     */
+    async gatherTargetFiles(pattern) {
+        try {
+            const files = await this.globMatcher.expandPattern(pattern);
+            return files;
+        }
+        catch (error) {
+            this.logger.error({ error: error.message, pattern }, 'Failed to gather target files');
+            throw new Error(`Failed to expand file pattern: ${pattern}`);
+        }
+    }
+    /**
+     * Generate unique session ID
+     */
+    generateSessionId() {
+        const now = new Date();
+        const timestamp = now.toISOString().replaceAll(/[:.]/g, '-').replace('T', '-').split('.')[0];
+        return `decompose-${timestamp}`;
+    }
+    /**
+     * Parse Claude's YAML output into a structured TaskGraph
+     */
+    parseTaskGraph(output, options, sessionDir, targetFiles) {
+        this.logger.debug('Parsing task graph from YAML output');
+        try {
+            // Extract YAML from output (handle potential markdown code fences)
+            const yamlContent = this.extractYaml(output);
+            this.logger.debug({ yamlLength: yamlContent.length }, 'Extracted YAML content');
+            // Log first 500 chars of YAML for debugging
+            this.logger.debug({ yamlPreview: yamlContent.slice(0, 500) }, 'YAML preview (first 500 chars)');
+            // Parse YAML
+            const parsed = yaml.load(yamlContent);
+            if (!parsed.masterPrompt || !parsed.tasks || !Array.isArray(parsed.tasks)) {
+                throw new Error('Invalid task graph structure: missing masterPrompt or tasks array');
+            }
+            // Convert to TaskNode array
+            const tasks = parsed.tasks.map((t) => ({
+                agentType: t.agentType ?? 'dev',
+                dependencies: t.dependencies ?? [],
+                description: t.description,
+                estimatedMinutes: t.estimatedMinutes,
+                id: t.id,
+                outputFile: t.outputFile,
+                parallelizable: t.parallelizable ?? true,
+                prompt: t.prompt,
+                targetFiles: t.targetFiles,
+                title: t.title,
+            }));
+            // Validate task graph
+            this.validateTaskGraph(tasks);
+            // Build execution layers (topological sort)
+            const executionLayers = this.buildExecutionLayers(tasks);
+            // Calculate metadata
+            const totalMinutes = tasks.reduce((sum, t) => sum + t.estimatedMinutes, 0);
+            const maxParallel = Math.max(...executionLayers.map((layer) => layer.length));
+            // Generate session ID
+            const sessionId = this.generateSessionId();
+            const taskGraph = {
+                goal: options.goal,
+                masterPrompt: parsed.masterPrompt,
+                metadata: {
+                    estimatedDuration: totalMinutes,
+                    executionLayers,
+                    maxParallelism: maxParallel,
+                    perFileMode: options.perFile ?? false,
+                    storyFormat: options.storyFormat ?? false,
+                    totalFiles: targetFiles.length > 0 ? targetFiles.length : undefined,
+                    totalTasks: tasks.length,
+                },
+                session: {
+                    createdAt: new Date().toISOString(),
+                    id: sessionId,
+                    outputDirectory: sessionDir,
+                },
+                tasks,
+            };
+            return taskGraph;
+        }
+        catch (error) {
+            this.logger.error({ error: error.message, outputLength: output.length }, 'Failed to parse task graph');
+            throw new Error(`Failed to parse task graph: ${error.message}`);
+        }
+    }
+    /**
+     * Validate YAML and ask Claude to fix it if invalid
+     */
+    async validateAndFixYaml(output, options, sessionDir) {
+        this.logger.debug('Validating YAML output');
+        // Try to extract and parse the YAML
+        try {
+            const yamlContent = this.extractYaml(output);
+            yaml.load(yamlContent); // Just validate, don't use the result yet
+            this.logger.info('YAML validation passed');
+            return output; // YAML is valid, return as-is
+        }
+        catch (error) {
+            this.logger.warn({ error: error.message }, 'YAML validation failed, asking Claude to fix it');
+            // YAML is invalid, ask Claude to fix it
+            const fixPrompt = `The following YAML has syntax errors. Please fix ALL syntax errors and return ONLY the corrected YAML (no explanations, no markdown code fences, just the raw YAML):
+
+ERROR: ${error.message}
+
+INVALID YAML:
+${output}
+
+Please output the CORRECTED YAML only. Ensure:
+1. Proper indentation (2 spaces per level)
+2. All strings with special characters are quoted
+3. All lists and mappings are properly formatted
+4. No syntax errors remain
+
+Output ONLY the corrected YAML:
+`;
+            this.logger.info('Asking Claude to fix YAML errors');
+            const fixResult = await this.agentRunner.runAgent(fixPrompt, {
+                agentType: 'architect',
+                timeout: 60_000, // 1 minute for fix
+            });
+            if (!fixResult.success) {
+                throw new Error(`Failed to fix YAML: ${fixResult.errors}`);
+            }
+            // Validate the fixed YAML
+            try {
+                const fixedYaml = this.extractYaml(fixResult.output);
+                yaml.load(fixedYaml); // Validate the fix
+                this.logger.info('Claude successfully fixed the YAML');
+                // Save the fixed YAML for reference
+                try {
+                    const fixedYamlPath = `${sessionDir}/fixed-yaml.txt`;
+                    await this.fileManager.writeFile(fixedYamlPath, fixResult.output);
+                    this.logger.debug({ fixedYamlPath }, 'Saved fixed YAML');
+                }
+                catch {
+                    // Ignore save errors
+                }
+                return fixResult.output;
+            }
+            catch (fixError) {
+                this.logger.error({ error: fixError.message }, 'Claude failed to fix YAML properly');
+                throw new Error(`Claude could not fix the YAML errors.\n` +
+                    `Original error: ${error.message}\n` +
+                    `Fix attempt error: ${fixError.message}\n\n` +
+                    `Raw output saved to: ${sessionDir}/raw-claude-output.txt`);
+            }
+        }
+    }
+    /**
+     * Validate task graph for common errors
+     */
+    validateTaskGraph(tasks) {
+        const ids = new Set();
+        for (const task of tasks) {
+            // Check unique IDs
+            if (ids.has(task.id)) {
+                throw new Error(`Duplicate task ID: ${task.id}`);
+            }
+            ids.add(task.id);
+            // Check dependencies exist
+            for (const depId of task.dependencies) {
+                if (!tasks.some((t) => t.id === depId)) {
+                    throw new Error(`Task ${task.id} has invalid dependency: ${depId}`);
+                }
+            }
+        }
+        // Check for circular dependencies
+        this.detectCircularDependencies(tasks);
+    }
+}