@codemcp/workflows 4.4.2 → 4.6.0

package/dist/tool-handlers/whats-next.js

@@ -5,6 +5,7 @@
  * determines the next development phase with specific instructions for the LLM.
  */
 import { ConversationRequiredToolHandler } from './base-tool-handler.js';
+import { TaskBackendManager, BeadsIntegration } from '@codemcp/workflows-core';
 /**
  * WhatsNext tool handler implementation
  */
@@ -85,6 +86,11 @@ export class WhatsNextHandler extends ConversationRequiredToolHandler {
             const commitMessage = requestContext || 'Step completion';
             finalInstructions += `\n\n**Git Commit Required**: Create a commit for this step using:\n\`\`\`bash\ngit add . && git commit -m "${commitMessage}"\n\`\`\``;
         }
+        // Add beads instructions if beads backend is active
+        const beadsInstructions = await this.generateBeadsInstructions(conversationContext, transitionResult.newPhase);
+        if (beadsInstructions) {
+            finalInstructions += '\n\n' + beadsInstructions;
+        }
         // Prepare response
         const response = {
             phase: transitionResult.newPhase,
@@ -125,5 +131,87 @@ export class WhatsNextHandler extends ConversationRequiredToolHandler {
         }
         return true;
     }
+    /**
+     * Generate beads-specific instructions if beads backend is active
+     */
+    async generateBeadsInstructions(conversationContext, currentPhase) {
+        // Check if beads backend is configured
+        const taskBackendConfig = TaskBackendManager.detectTaskBackend();
+        if (taskBackendConfig.backend !== 'beads' ||
+            !taskBackendConfig.isAvailable) {
+            return null;
+        }
+        try {
+            // Read plan file to extract current phase task ID
+            const phaseTaskId = await this.extractPhaseTaskId(conversationContext.planFilePath, currentPhase);
+            if (!phaseTaskId) {
+                this.logger.warn('Could not find beads phase task ID for current phase', {
+                    phase: currentPhase,
+                    planFilePath: conversationContext.planFilePath,
+                });
+                return null;
+            }
+            // Generate beads instructions using BeadsIntegration utility
+            const beadsIntegration = new BeadsIntegration(conversationContext.projectPath);
+            const phaseName = this.capitalizePhase(currentPhase);
+            return beadsIntegration.generateBeadsInstructions(phaseTaskId, phaseName);
+        }
+        catch (error) {
+            this.logger.warn('Failed to generate beads instructions', {
+                phase: currentPhase,
+                projectPath: conversationContext.projectPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Extract beads phase task ID from plan file for the given phase
+     */
+    async extractPhaseTaskId(planFilePath, phase) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const content = await readFile(planFilePath, 'utf-8');
+            const phaseName = this.capitalizePhase(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) {
+            this.logger.warn('Failed to read plan file for phase task ID extraction', {
+                planFilePath,
+                phase,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Capitalize phase name for display
+     */
+    capitalizePhase(phase) {
+        return phase
+            .split('_')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
 }
 //# sourceMappingURL=whats-next.js.map

package/dist/tool-handlers/whats-next.js.map

@@ -1 +1 @@
-{"version":3,"file":"whats-next.js","sourceRoot":"","sources":["../../src/tool-handlers/whats-next.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"whats-next.js","sourceRoot":"","sources":["../../src/tool-handlers/whats-next.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/workflows",
-  "version": "4.4.2",
+  "version": "4.6.0",
   "description": "MCP server implementation for responsible-vibe",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.17.5",
-    "@codemcp/workflows-core": "4.4.2"
+    "@codemcp/workflows-core": "4.6.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.23",

package/src/server-config.ts

@@ -325,6 +325,12 @@ export async function registerMcpTools(
           .describe(
             'Whether to require reviews before phase transitions. When enabled, use conduct_review tool before proceeding to next phase.'
           ),
+        project_path: z
+          .string()
+          .optional()
+          .describe(
+            'Project directory path. Pass the .vibe subdirectory path if a .vibe directory exists in your project, otherwise pass the project root directory. The implementation will automatically detect and use the correct project root.'
+          ),
       },
       annotations: {
         title: 'Development Initializer',
@@ -481,6 +487,12 @@ export async function registerMcpTools(
           .describe(
             `Design documentation: template name (${availableTemplates.design.join(', ')}, none) OR file path to existing document`
           ),
+        project_path: z
+          .string()
+          .optional()
+          .describe(
+            'Project directory path. Pass the .vibe subdirectory path if a .vibe directory exists in your project, otherwise pass the project root directory. The implementation will automatically detect and use the correct project root.'
+          ),
       },
       annotations: {
         title: 'Project Documentation Setup Tool',

package/src/server-helpers.ts

@@ -222,3 +222,24 @@ export function logHandlerCompletion(
     hasError: !!result.error,
   });
 }
+
+/**
+ * Strip /.vibe suffix from project path if present
+ *
+ * @param providedPath - Optional project path provided by user
+ * @param defaultPath - Default project path from context
+ * @returns Normalized project root path
+ */
+export function stripVibePathSuffix(
+  providedPath: string | undefined,
+  defaultPath: string
+): string {
+  if (!providedPath) {
+    return defaultPath;
+  }
+
+  // Strip /.vibe suffix if present to get project root
+  return providedPath.endsWith('/.vibe')
+    ? providedPath.slice(0, -6) // Remove '/.vibe'
+    : providedPath;
+}

package/src/tool-handlers/setup-project-docs.ts

@@ -7,6 +7,7 @@
  */
 
 import { BaseToolHandler } from './base-tool-handler.js';
+import { stripVibePathSuffix } from '../server-helpers.js';
 import { ProjectDocsManager } from '@codemcp/workflows-core';
 import { TemplateOptions } from '@codemcp/workflows-core';
 import { PathValidationUtils } from '@codemcp/workflows-core';
@@ -16,6 +17,7 @@ export interface SetupProjectDocsArgs {
   architecture: string; // Template name OR file path
   requirements: string; // Template name OR file path
   design: string; // Template name OR file path
+  project_path?: string; // Optional project path override
 }
 
 export interface SetupProjectDocsResult {
@@ -46,7 +48,11 @@ export class SetupProjectDocsHandler extends BaseToolHandler<
     args: SetupProjectDocsArgs,
     context: ServerContext
   ): Promise<SetupProjectDocsResult> {
-    const projectPath = context.projectPath || process.cwd();
+    // Normalize project path - strip /.vibe suffix if present
+    const projectPath = stripVibePathSuffix(
+      args.project_path,
+      context.projectPath || process.cwd()
+    );
 
     this.logger.info(
       'Setting up project docs with enhanced file linking support',

package/src/tool-handlers/start-development.ts

@@ -6,7 +6,10 @@
  */
 
 import { BaseToolHandler } from './base-tool-handler.js';
-import { validateRequiredArgs } from '../server-helpers.js';
+import {
+  validateRequiredArgs,
+  stripVibePathSuffix,
+} from '../server-helpers.js';
 import { basename } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -14,6 +17,7 @@ import { GitCommitConfig } from '@codemcp/workflows-core';
 import { GitManager } from '@codemcp/workflows-core';
 import type { YamlStateMachine } from '@codemcp/workflows-core';
 import { ProjectDocsManager, ProjectDocsInfo } from '@codemcp/workflows-core';
+import { TaskBackendManager, BeadsIntegration } from '@codemcp/workflows-core';
 import { ServerContext } from '../types.js';
 
 /**
@@ -23,6 +27,7 @@ export interface StartDevelopmentArgs {
   workflow: string;
   commit_behaviour?: 'step' | 'phase' | 'end' | 'none';
   require_reviews?: boolean;
+  project_path?: string;
 }
 
 /**
@@ -58,11 +63,20 @@ export class StartDevelopmentHandler extends BaseToolHandler<
     // Validate required arguments
     validateRequiredArgs(args, ['workflow']);
 
+    // Validate task backend configuration
+    const taskBackendConfig = TaskBackendManager.validateTaskBackend();
+
     const selectedWorkflow = args.workflow;
     const requireReviews = args.require_reviews ?? false;
 
+    // Normalize project path - strip /.vibe suffix if present
+    const projectPath = stripVibePathSuffix(
+      args.project_path,
+      context.projectPath
+    );
+
     // Process git commit configuration
-    const isGitRepository = GitManager.isGitRepository(context.projectPath);
+    const isGitRepository = GitManager.isGitRepository(projectPath);
 
     // Translate commit_behaviour to internal git config
     const commitBehaviour =
@@ -77,22 +91,22 @@ export class StartDevelopmentHandler extends BaseToolHandler<
         commitBehaviour === 'phase',
       initialMessage: 'Development session',
       startCommitHash:
-        GitManager.getCurrentCommitHash(context.projectPath) || undefined,
+        GitManager.getCurrentCommitHash(projectPath) || undefined,
     };
 
     this.logger.debug('Processing start_development request', {
       selectedWorkflow,
-      projectPath: context.projectPath,
+      projectPath: projectPath,
       commitBehaviour,
       gitCommitConfig,
     });
 
     // Validate workflow selection (ensure project workflows are loaded first)
-    context.workflowManager.loadProjectWorkflows(context.projectPath);
+    context.workflowManager.loadProjectWorkflows(projectPath);
     if (
       !context.workflowManager.validateWorkflowName(
         selectedWorkflow,
-        context.projectPath
+        projectPath
       )
     ) {
       const availableWorkflows = context.workflowManager.getWorkflowNames();
@@ -103,7 +117,7 @@ export class StartDevelopmentHandler extends BaseToolHandler<
 
     // Check for project documentation artifacts and guide setup if needed
     const artifactGuidance = await this.checkProjectArtifacts(
-      context.projectPath,
+      projectPath,
       selectedWorkflow,
       context
     );
@@ -112,7 +126,7 @@ export class StartDevelopmentHandler extends BaseToolHandler<
     }
 
     // Check if user is on main/master branch and prompt for branch creation
-    const currentBranch = this.getCurrentGitBranch(context.projectPath);
+    const currentBranch = this.getCurrentGitBranch(projectPath);
     if (currentBranch === 'main' || currentBranch === 'master') {
       const suggestedBranchName = this.generateBranchSuggestion();
       const branchPromptResponse: StartDevelopmentResult = {
@@ -137,7 +151,8 @@ export class StartDevelopmentHandler extends BaseToolHandler<
     // Create or get conversation context with the selected workflow
     const conversationContext =
       await context.conversationManager.createConversationContext(
-        selectedWorkflow
+        selectedWorkflow,
+        args.project_path ? projectPath : undefined
       );
     const currentPhase = conversationContext.currentPhase;
 
@@ -163,7 +178,7 @@ export class StartDevelopmentHandler extends BaseToolHandler<
       await context.transitionEngine.handleExplicitTransition(
         currentPhase,
         targetPhase,
-        conversationContext.projectPath,
+        projectPath,
         'Development initialization',
         selectedWorkflow
       );
@@ -182,15 +197,30 @@ export class StartDevelopmentHandler extends BaseToolHandler<
     // Set state machine on plan manager before creating plan file
     context.planManager.setStateMachine(stateMachine);
 
+    // Set task backend configuration if supported (for backwards compatibility)
+    if (typeof context.planManager.setTaskBackend === 'function') {
+      context.planManager.setTaskBackend(taskBackendConfig);
+    }
+
     // Ensure plan file exists
     await context.planManager.ensurePlanFile(
       conversationContext.planFilePath,
-      conversationContext.projectPath,
+      projectPath,
       conversationContext.gitBranch
     );
 
+    // Handle beads integration if beads backend is configured
+    if (taskBackendConfig.backend === 'beads') {
+      await this.setupBeadsIntegration(
+        projectPath,
+        stateMachine,
+        selectedWorkflow,
+        conversationContext.planFilePath
+      );
+    }
+
     // Ensure .vibe/.gitignore exists to exclude SQLite files for git repositories
-    this.ensureGitignoreEntry(conversationContext.projectPath);
+    this.ensureGitignoreEntry(projectPath);
 
     // Generate workflow documentation URL
     const workflowDocumentationUrl =
@@ -610,6 +640,119 @@ ${templateOptionsText}
     return `feature/development-${timestamp}`;
   }
 
+  /**
+   * Setup beads integration - create project epic and phase tasks
+   */
+  private async setupBeadsIntegration(
+    projectPath: string,
+    stateMachine: YamlStateMachine,
+    workflowName: string,
+    planFilePath: string
+  ): Promise<void> {
+    try {
+      const beadsIntegration = new BeadsIntegration(projectPath);
+      const projectName = projectPath.split('/').pop() || 'Unknown Project';
+
+      // Create project epic
+      const epicId = await beadsIntegration.createProjectEpic(
+        projectName,
+        workflowName
+      );
+
+      // Create phase tasks for all workflow phases
+      const phases = Object.keys(stateMachine.states);
+      const phaseTasks = await beadsIntegration.createPhaseTasks(
+        epicId,
+        phases,
+        workflowName
+      );
+
+      // Update plan file with phase task IDs
+      await this.updatePlanFileWithPhaseTaskIds(planFilePath, phaseTasks);
+
+      this.logger.info('Beads integration setup complete', {
+        projectPath,
+        epicId,
+        phaseCount: phaseTasks.length,
+        planFilePath,
+      });
+    } catch (error) {
+      this.logger.error(
+        'Failed to setup beads integration',
+        error instanceof Error ? error : new Error(String(error)),
+        {
+          projectPath,
+          workflowName,
+        }
+      );
+      throw new Error(
+        `Failed to setup beads integration: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Update plan file to include beads phase task IDs in comments
+   */
+  private async updatePlanFileWithPhaseTaskIds(
+    planFilePath: string,
+    phaseTasks: Array<{ phaseId: string; phaseName: string; taskId: string }>
+  ): Promise<void> {
+    try {
+      const { readFile, writeFile } = await import('node:fs/promises');
+      let content = await readFile(planFilePath, 'utf-8');
+
+      // Replace TBD placeholders with actual task IDs
+      for (const phaseTask of phaseTasks) {
+        const phaseHeader = `## ${phaseTask.phaseName}`;
+        const placeholderPattern = new RegExp(
+          `(${phaseHeader.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\n)<!-- beads-phase-id: TBD -->`,
+          'g'
+        );
+        content = content.replace(
+          placeholderPattern,
+          `$1<!-- beads-phase-id: ${phaseTask.taskId} -->`
+        );
+      }
+
+      // Validate that all TBD placeholders were replaced
+      const remainingTBDs = content.match(/<!-- beads-phase-id: TBD -->/g);
+      if (remainingTBDs && remainingTBDs.length > 0) {
+        throw new Error(
+          `Failed to replace ${remainingTBDs.length} TBD placeholder(s) in plan file. ` +
+            `This indicates that phase names in the plan file don't match the workflow phases, ` +
+            `or the beads task creation process failed for some phases.`
+        );
+      }
+
+      await writeFile(planFilePath, content, 'utf-8');
+
+      this.logger.info(
+        'Successfully updated plan file with beads phase task IDs',
+        {
+          planFilePath,
+          phaseTaskCount: phaseTasks.length,
+          replacedTasks: phaseTasks.map(
+            task => `${task.phaseName}: ${task.taskId}`
+          ),
+        }
+      );
+    } catch (error) {
+      this.logger.error(
+        'Failed to update plan file with phase task IDs',
+        error instanceof Error ? error : new Error(String(error)),
+        {
+          planFilePath,
+        }
+      );
+      // For beads integration, TBD replacement failure is critical
+      throw new Error(
+        `Failed to update plan file with beads task IDs: ${error instanceof Error ? error.message : String(error)}. ` +
+          `This indicates beads integration setup is incomplete. Check that beads CLI is working and task IDs were created successfully.`
+      );
+    }
+  }
+
   /**
    * Ensure .gitignore exists in .vibe folder to exclude SQLite files
    * This function is idempotent and self-contained within the .vibe directory

package/src/tool-handlers/whats-next.ts

@@ -7,6 +7,7 @@
 
 import { ConversationRequiredToolHandler } from './base-tool-handler.js';
 import type { ConversationContext } from '@codemcp/workflows-core';
+import { TaskBackendManager, BeadsIntegration } from '@codemcp/workflows-core';
 import { ServerContext } from '../types.js';
 
 /**
@@ -180,6 +181,15 @@ export class WhatsNextHandler extends ConversationRequiredToolHandler<
       finalInstructions += `\n\n**Git Commit Required**: Create a commit for this step using:\n\`\`\`bash\ngit add . && git commit -m "${commitMessage}"\n\`\`\``;
     }
 
+    // Add beads instructions if beads backend is active
+    const beadsInstructions = await this.generateBeadsInstructions(
+      conversationContext,
+      transitionResult.newPhase
+    );
+    if (beadsInstructions) {
+      finalInstructions += '\n\n' + beadsInstructions;
+    }
+
     // Prepare response
     const response: WhatsNextResult = {
       phase: transitionResult.newPhase,
@@ -248,4 +258,114 @@ export class WhatsNextHandler extends ConversationRequiredToolHandler<
 
     return true;
   }
+
+  /**
+   * Generate beads-specific instructions if beads backend is active
+   */
+  private async generateBeadsInstructions(
+    conversationContext: ConversationContext,
+    currentPhase: string
+  ): Promise<string | null> {
+    // Check if beads backend is configured
+    const taskBackendConfig = TaskBackendManager.detectTaskBackend();
+    if (
+      taskBackendConfig.backend !== 'beads' ||
+      !taskBackendConfig.isAvailable
+    ) {
+      return null;
+    }
+
+    try {
+      // Read plan file to extract current phase task ID
+      const phaseTaskId = await this.extractPhaseTaskId(
+        conversationContext.planFilePath,
+        currentPhase
+      );
+      if (!phaseTaskId) {
+        this.logger.warn(
+          'Could not find beads phase task ID for current phase',
+          {
+            phase: currentPhase,
+            planFilePath: conversationContext.planFilePath,
+          }
+        );
+        return null;
+      }
+
+      // Generate beads instructions using BeadsIntegration utility
+      const beadsIntegration = new BeadsIntegration(
+        conversationContext.projectPath
+      );
+      const phaseName = this.capitalizePhase(currentPhase);
+      return beadsIntegration.generateBeadsInstructions(phaseTaskId, phaseName);
+    } catch (error) {
+      this.logger.warn('Failed to generate beads instructions', {
+        phase: currentPhase,
+        projectPath: conversationContext.projectPath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Extract beads phase task ID from plan file for the given phase
+   */
+  private async extractPhaseTaskId(
+    planFilePath: string,
+    phase: string
+  ): Promise<string | null> {
+    try {
+      const { readFile } = await import('node:fs/promises');
+      const content = await readFile(planFilePath, 'utf-8');
+
+      const phaseName = this.capitalizePhase(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) {
+      this.logger.warn(
+        'Failed to read plan file for phase task ID extraction',
+        {
+          planFilePath,
+          phase,
+          error: error instanceof Error ? error.message : String(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(' ');
+  }
 }