@codemcp/workflows 4.7.0 → 4.9.0

package/src/components/beads/beads-instruction-generator.ts

@@ -0,0 +1,261 @@
+/**
+ * Beads Instruction Generator
+ *
+ * Beads-specific implementation of IInstructionGenerator.
+ * Generates instructions optimized for beads task management workflow.
+ */
+
+import {
+  type IInstructionGenerator,
+  type InstructionContext,
+  type GeneratedInstructions,
+  type YamlStateMachine,
+  ProjectDocsManager,
+  TaskBackendManager,
+  type TaskBackendConfig,
+} from '@codemcp/workflows-core';
+import { BeadsTaskBackendClient } from './beads-task-backend-client.js';
+
+/**
+ * Beads-specific instruction generator
+ */
+export class BeadsInstructionGenerator implements IInstructionGenerator {
+  private projectDocsManager: ProjectDocsManager;
+
+  constructor(
+    _taskBackendClient?: BeadsTaskBackendClient,
+    _taskBackendDetector: () => TaskBackendConfig = TaskBackendManager.detectTaskBackend
+  ) {
+    this.projectDocsManager = new ProjectDocsManager();
+    // Task backend client and detector may be used in future enhancements
+  }
+
+  /**
+   * Set the state machine definition (kept for interface compatibility)
+   */
+  setStateMachine(_stateMachine: YamlStateMachine): void {
+    // Not needed for beads implementation but kept for interface compliance
+    return;
+  }
+
+  /**
+   * Generate comprehensive instructions optimized for beads workflow
+   */
+  async generateInstructions(
+    baseInstructions: string,
+    context: InstructionContext
+  ): Promise<GeneratedInstructions> {
+    // Apply variable substitution to base instructions
+    const substitutedInstructions = this.applyVariableSubstitution(
+      baseInstructions,
+      context.conversationContext.projectPath,
+      context.conversationContext.gitBranch
+    );
+
+    // Enhance base instructions with beads-specific guidance
+    const enhancedInstructions = await this.enhanceBeadsInstructions(
+      substitutedInstructions,
+      context
+    );
+
+    return {
+      instructions: enhancedInstructions,
+      planFileGuidance:
+        'Using beads CLI for task management - plan file serves as context only',
+      metadata: {
+        phase: context.phase,
+        planFilePath: context.conversationContext.planFilePath,
+        transitionReason: context.transitionReason,
+        isModeled: context.isModeled,
+      },
+    };
+  }
+
+  /**
+   * Apply variable substitution to instructions
+   */
+  private applyVariableSubstitution(
+    instructions: string,
+    projectPath: string,
+    gitBranch?: string
+  ): string {
+    const substitutions = this.projectDocsManager.getVariableSubstitutions(
+      projectPath,
+      gitBranch
+    );
+
+    let result = instructions;
+    for (const [variable, value] of Object.entries(substitutions)) {
+      result = result.replace(
+        new RegExp(this.escapeRegExp(variable), 'g'),
+        value
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Escape special regex characters in variable names
+   */
+  private escapeRegExp(string: string): string {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  /**
+   * Enhance instructions with beads-specific guidance
+   */
+  private async enhanceBeadsInstructions(
+    baseInstructions: string,
+    context: InstructionContext
+  ): Promise<string> {
+    const {
+      phase,
+      conversationContext,
+      transitionReason,
+      isModeled,
+      planFileExists,
+    } = context;
+
+    // Generate beads-specific task management guidance
+    const beadsTaskGuidance = await this.generateBeadsTaskGuidance(context);
+
+    // Beads-optimized instruction structure
+    const enhanced = `You are in the ${phase} phase.
+${baseInstructions}
+
+**Plan File Guidance:**
+Use the plan file as memory for the current objective
+- Update the "Key Decisions" section with important choices made
+- Add relevant notes to help maintain context
+- Do NOT enter tasks in the plan file, use beads CLI exclusively for task management
+
+**🔧 BD CLI Task Management:**
+${beadsTaskGuidance}`;
+
+    // Add project context
+    const enhancedWithContext =
+      enhanced +
+      `\n\n**Project Context:**
+- Project: ${conversationContext.projectPath}
+- Branch: ${conversationContext.gitBranch}
+- Current Phase: ${phase}`;
+
+    // Add transition context if this is a modeled transition
+    let final = enhancedWithContext;
+    if (isModeled && transitionReason) {
+      final += `\n\n**Phase Context:**
+- ${transitionReason}`;
+    }
+
+    // Add plan file creation note if needed
+    if (!planFileExists) {
+      final +=
+        '\n\n**Note**: Plan file will be created when you first update it.';
+    }
+
+    // Add beads-specific reminders
+    final += `\n\n**Important Reminders:**
+- Use ONLY bd CLI tool for task management - do not use your own task management tools
+- Call whats_next() after the next user message to maintain the development workflow`;
+
+    return final;
+  }
+
+  /**
+   * Generate beads-specific task management guidance
+   */
+  private async generateBeadsTaskGuidance(
+    context: InstructionContext
+  ): Promise<string> {
+    const { phase } = context;
+
+    // Extract phase task ID from plan file (this would need to be implemented)
+    const phaseTaskId = await this.extractPhaseTaskId(context);
+
+    if (!phaseTaskId) {
+      return `- Use bd CLI tool exclusively
+- **Start by listing ready tasks**: \`bd list --parent <phase-task-id> --status open\`
+- **Create new tasks**: \`bd create 'Task title' --parent <phase-task-id> -p 2\`
+- **Update status when working**: \`bd update <task-id> --status in_progress\`
+- **Complete tasks**: \`bd close <task-id>\`
+- **Focus on ready tasks first** - let beads handle dependencies
+- Add new tasks as they are identified during your work with the user`;
+    }
+
+    return `
+You are currently in the ${this.capitalizePhase(phase)} phase. All work items should be created as children of ${phaseTaskId}.
+
+**Focus on ${this.capitalizePhase(phase)} Phase Tasks** (subtasks of \`${phaseTaskId}\`):
+• \`bd list --parent ${phaseTaskId} --status open\` - List ready work items
+• \`bd update <task-id> --status in_progress\` - Start working on a specific task
+• \`bd close <task-id>\` - Mark task complete when finished
+
+**Create New Tasks for Current Phase**:
+• \`bd create 'Task description' --parent ${phaseTaskId} -p 2\` - Create work item under current phase
+
+**Essential Commands**:
+• \`bd list --parent ${phaseTaskId} --status open\` - List ready work items
+• \`bd create 'Task description' --parent ${phaseTaskId} -p 2\` - Create work item
+• \`bd update <task-id> --status in_progress\` - Start working
+• \`bd close <task-id>\` - Complete work item
+• \`bd show ${phaseTaskId}\` - View phase and its work items
+
+**Immediate Action**: Run \`bd list --parent ${phaseTaskId} --status open\` to see ready tasks.`;
+  }
+
+  /**
+   * Extract phase task ID from plan file (simplified implementation)
+   */
+  private async extractPhaseTaskId(
+    context: InstructionContext
+  ): Promise<string | null> {
+    try {
+      const { readFile } = await import('node:fs/promises');
+      const content = await readFile(
+        context.conversationContext.planFilePath,
+        'utf-8'
+      );
+
+      const phaseName = this.capitalizePhase(context.phase);
+      const phaseHeader = `## ${phaseName}`;
+
+      // Look for the phase header followed by beads-phase-id comment
+      const phaseSection = content.split('\n');
+      let foundPhaseHeader = false;
+
+      for (const line of phaseSection) {
+        if (line.trim() === phaseHeader) {
+          foundPhaseHeader = true;
+          continue;
+        }
+
+        if (foundPhaseHeader && line.includes('beads-phase-id:')) {
+          const match = line.match(/beads-phase-id:\s*([\w\d.-]+)/);
+          if (match) {
+            return match[1] || null;
+          }
+        }
+
+        // Stop looking if we hit the next phase header
+        if (foundPhaseHeader && line.startsWith('##') && line !== phaseHeader) {
+          break;
+        }
+      }
+
+      return null;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  /**
+   * Capitalize phase name for display
+   */
+  private capitalizePhase(phase: string): string {
+    return phase
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+}

package/src/components/beads/beads-plan-manager.ts

@@ -0,0 +1,358 @@
+/**
+ * Beads Plan Manager
+ *
+ * Beads-specific implementation of IPlanManager.
+ * Manages plan files optimized for beads task management workflow.
+ */
+
+import {
+  type IPlanManager,
+  type PlanFileInfo,
+  type YamlStateMachine,
+  type TaskBackendConfig,
+  createLogger,
+} from '@codemcp/workflows-core';
+import { writeFile, readFile, access } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+const logger = createLogger('BeadsPlanManager');
+
+/**
+ * Beads-specific plan manager implementation
+ */
+export class BeadsPlanManager implements IPlanManager {
+  private stateMachine: YamlStateMachine | null = null;
+
+  /**
+   * Set the state machine definition for dynamic plan generation
+   */
+  setStateMachine(stateMachine: YamlStateMachine): void {
+    this.stateMachine = stateMachine;
+    logger.debug('State machine set for beads plan manager', {
+      name: stateMachine.name,
+      phases: Object.keys(stateMachine.states),
+    });
+  }
+
+  /**
+   * Set the task backend configuration
+   */
+  setTaskBackend(taskBackend: TaskBackendConfig): void {
+    // Task backend is implicit for beads plan manager (always beads)
+    logger.debug('Task backend set for beads plan manager', {
+      backend: taskBackend.backend,
+      available: taskBackend.isAvailable,
+    });
+  }
+
+  /**
+   * Get plan file information
+   */
+  async getPlanFileInfo(planFilePath: string): Promise<PlanFileInfo> {
+    try {
+      await access(planFilePath);
+      const content = await readFile(planFilePath, 'utf-8');
+      return {
+        path: planFilePath,
+        exists: true,
+        content,
+      };
+    } catch (_error) {
+      return {
+        path: planFilePath,
+        exists: false,
+      };
+    }
+  }
+
+  /**
+   * Create initial plan file if it doesn't exist
+   */
+  async ensurePlanFile(
+    planFilePath: string,
+    projectPath: string,
+    gitBranch: string
+  ): Promise<void> {
+    logger.debug('Ensuring beads plan file exists', {
+      planFilePath,
+      projectPath,
+      gitBranch,
+    });
+
+    const planInfo = await this.getPlanFileInfo(planFilePath);
+
+    if (!planInfo.exists) {
+      logger.info('Plan file not found, creating beads-optimized plan', {
+        planFilePath,
+      });
+      await this.createInitialBeadsPlanFile(
+        planFilePath,
+        projectPath,
+        gitBranch
+      );
+      logger.info('Beads plan file created successfully', { planFilePath });
+    } else {
+      logger.debug('Plan file already exists', { planFilePath });
+    }
+  }
+
+  /**
+   * Create initial plan file optimized for beads workflow
+   */
+  private async createInitialBeadsPlanFile(
+    planFilePath: string,
+    projectPath: string,
+    gitBranch: string
+  ): Promise<void> {
+    logger.debug('Creating beads-optimized plan file', { planFilePath });
+
+    try {
+      // Ensure directory exists
+      await mkdir(dirname(planFilePath), { recursive: true });
+      logger.debug('Plan file directory ensured', {
+        directory: dirname(planFilePath),
+      });
+
+      const projectName = projectPath.split('/').pop() || 'Unknown Project';
+      const branchInfo = gitBranch !== 'no-git' ? ` (${gitBranch} branch)` : '';
+
+      const initialContent = this.generateBeadsInitialPlanContent(
+        projectName,
+        branchInfo
+      );
+
+      await writeFile(planFilePath, initialContent, 'utf-8');
+      logger.info('Beads plan file written successfully', {
+        planFilePath,
+        contentLength: initialContent.length,
+        projectName,
+      });
+    } catch (error) {
+      logger.error('Failed to create beads plan file', error as Error, {
+        planFilePath,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Generate initial plan file content optimized for beads workflow
+   */
+  private generateBeadsInitialPlanContent(
+    projectName: string,
+    branchInfo: string
+  ): string {
+    const timestamp = new Date().toISOString().split('T')[0];
+
+    if (!this.stateMachine) {
+      throw new Error(
+        'State machine not set. This should not happen as state machine is always loaded.'
+      );
+    }
+
+    const phases = Object.keys(this.stateMachine.states);
+    const initialPhase = this.stateMachine.initial_state;
+
+    const documentationUrl = this.generateWorkflowDocumentationUrl(
+      this.stateMachine.name
+    );
+
+    let content = `# Development Plan: ${projectName}${branchInfo}
+
+*Generated on ${timestamp} by Vibe Feature MCP*
+*Workflow: ${
+      documentationUrl
+        ? '[' + this.stateMachine.name + ']' + '(' + documentationUrl + ')'
+        : this.stateMachine.name
+    }*
+*Task Management: Beads Issue Tracker*
+
+## Goal
+*Define what you're building or fixing - this will be updated as requirements are gathered*
+
+## ${this.capitalizePhase(initialPhase)}
+<!-- beads-phase-id: TBD -->
+### Tasks
+
+**🔧 TASK MANAGEMENT VIA CLI TOOL bd**
+
+Tasks are managed via bd CLI tool. Use bd commands to create and manage tasks with proper hierarchy:
+
+- \`bd list --parent <phase-task-id> --status open\`
+- \`bd create "Task title" --parent <phase-task-id> -p 2\`
+- \`bd close <task-id>\`
+
+**Never use [ ] or [x] checkboxes - use bd commands only!**
+
+### Completed
+- [x] Created development plan file
+
+`;
+
+    // Generate sections for each phase with beads-specific guidance
+    for (const phase of phases) {
+      if (phase !== initialPhase) {
+        content += `## ${this.capitalizePhase(phase)}
+<!-- beads-phase-id: TBD -->
+### Tasks
+
+**🔧 TASK MANAGEMENT VIA CLI TOOL bd**
+
+Tasks are managed via bd CLI tool. Use bd commands to create and manage tasks with proper hierarchy:
+
+- \`bd list --parent <phase-task-id> --status open\`
+- \`bd create "Task title" --parent <phase-task-id> -p 2\`
+- \`bd close <task-id>\`
+
+**Never use [ ] or [x] checkboxes - use bd commands only!**
+
+### Completed
+*None yet*
+
+`;
+      }
+    }
+
+    content += `## Key Decisions
+*Important decisions will be documented here as they are made*
+
+## Notes
+*Additional context and observations*
+
+---
+*This plan is maintained by the LLM and uses beads CLI for task management. Tool responses provide guidance on which bd commands to use for task management.*
+`;
+
+    return content;
+  }
+
+  /**
+   * Update plan file with new content
+   */
+  async updatePlanFile(planFilePath: string, content: string): Promise<void> {
+    // Ensure directory exists
+    await mkdir(dirname(planFilePath), { recursive: true });
+
+    await writeFile(planFilePath, content, 'utf-8');
+  }
+
+  /**
+   * Get plan file content for LLM context
+   */
+  async getPlanFileContent(planFilePath: string): Promise<string> {
+    const planInfo = await this.getPlanFileInfo(planFilePath);
+
+    if (!planInfo.exists) {
+      return 'Plan file does not exist yet. It will be created when the LLM updates it.';
+    }
+
+    return planInfo.content || '';
+  }
+
+  /**
+   * Generate phase-specific plan file guidance optimized for beads
+   */
+  generatePlanFileGuidance(phase: string): string {
+    if (!this.stateMachine) {
+      throw new Error(
+        'State machine not set. This should not happen as state machine is always loaded.'
+      );
+    }
+
+    const phaseDefinition = this.stateMachine.states[phase];
+    if (!phaseDefinition) {
+      logger.warn('Unknown phase for beads plan file guidance', { phase });
+      return `Update the ${this.capitalizePhase(phase)} section with current progress. Use bd CLI for all task management.`;
+    }
+
+    const capitalizedPhase = this.capitalizePhase(phase);
+
+    return `Update the ${capitalizedPhase} section with progress. Use bd CLI exclusively for task management - never use checkboxes. Document important decisions in the Key Decisions section.`;
+  }
+
+  /**
+   * Delete plan file
+   */
+  async deletePlanFile(planFilePath: string): Promise<boolean> {
+    logger.debug('Deleting beads plan file', { planFilePath });
+
+    try {
+      // Check if file exists first
+      await access(planFilePath);
+
+      // Import unlink dynamically to avoid issues
+      const { unlink } = await import('node:fs/promises');
+      await unlink(planFilePath);
+
+      logger.info('Beads plan file deleted successfully', { planFilePath });
+      return true;
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        logger.debug('Beads plan file does not exist, nothing to delete', {
+          planFilePath,
+        });
+        return true; // Consider it successful if file doesn't exist
+      }
+
+      logger.error('Failed to delete beads plan file', error as Error, {
+        planFilePath,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Ensure plan file is deleted (verify deletion)
+   */
+  async ensurePlanFileDeleted(planFilePath: string): Promise<boolean> {
+    logger.debug('Ensuring beads plan file is deleted', { planFilePath });
+
+    try {
+      await access(planFilePath);
+      // If we reach here, file still exists
+      logger.warn('Beads plan file still exists after deletion attempt', {
+        planFilePath,
+      });
+      return false;
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        logger.debug('Beads plan file successfully deleted (does not exist)', {
+          planFilePath,
+        });
+        return true;
+      }
+
+      // Some other error occurred
+      logger.error('Error checking beads plan file deletion', error as Error, {
+        planFilePath,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Capitalize phase name for display
+   */
+  private capitalizePhase(phase: string): string {
+    return phase
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  /**
+   * Generate workflow documentation URL for predefined workflows
+   */
+  private generateWorkflowDocumentationUrl(
+    workflowName: string
+  ): string | undefined {
+    // Don't generate URL for custom workflows
+    if (workflowName === 'custom') {
+      return undefined;
+    }
+
+    // Generate URL for predefined workflows
+    return `https://mrsimpson.github.io/responsible-vibe-mcp/workflows/${workflowName}`;
+  }
+}