Structured Workflow MCP

Instructions

Implementation Reference

• src/tools/validation.ts:88-172 (handler)

  The core handler function that implements the validate_phase_completion tool. It validates phase completion by checking criteria, updating session validation state, handling escalations, and returning detailed results including whether the phase can proceed.

  export async function handleValidatePhaseCompletion(
    params: {
      phase: Phase;
      completedWork: any;
      createdFiles?: string[];
    },
    sessionManager: SessionManager
  ) {
    const session = sessionManager.getSession();
    
    if (!session) {
      return {
        isValid: false,
        error: 'No active session. Use build_custom_workflow first.',
        blockers: ['No active workflow session']
      };
    }
  
    // Get current validation state for this phase
    let validationState = sessionManager.getValidationState(params.phase);
    if (!validationState) {
      validationState = {
        isComplete: false,
        completedRequirements: [],
        failedRequirements: [],
        lastValidatedAt: Date.now(),
        attempts: 0
      };
    }
  
    // Increment validation attempts
    validationState.attempts++;
    validationState.lastValidatedAt = Date.now();
  
    // Get phase-specific validation criteria
    const criteria = getValidationCriteriaForPhase(params.phase, session.workflowConfig?.outputPreferences.outputDirectory || 'workflow-output');
    
    // Perform validation checks
    const validationResults = performPhaseValidation(params.phase, params.completedWork, params.createdFiles || [], criteria);
  
    // Update validation state
    validationState.completedRequirements = validationResults.passed;
    validationState.failedRequirements = validationResults.failed;
    validationState.isComplete = validationResults.isComplete;
  
    // Store updated validation state
    sessionManager.setValidationState(params.phase, validationState);
  
    // Check for escalation conditions
    const escalationContext = sessionManager.shouldEscalateToUserInput(params.phase);
    
    if (escalationContext) {
      return {
        isValid: false,
        escalationRequired: true,
        escalationContext,
        message: '⚠️ ESCALATION REQUIRED: Validation issues require user input',
        validationAttempts: validationState.attempts,
        failedRequirements: validationResults.failed,
        recommendation: 'Use user_input_required_guidance to escalate to user'
      };
    }
  
    if (!validationResults.isComplete) {
      return {
        isValid: false,
        message: '⛔ VALIDATION FAILED: Phase completion requirements not met',
        validationAttempts: validationState.attempts,
        passedRequirements: validationResults.passed,
        failedRequirements: validationResults.failed,
        blockingMessages: validationResults.blockingMessages,
        nextSteps: validationResults.nextSteps,
        selfCheckQuestions: criteria.selfCheckQuestions
      };
    }
  
    return {
      isValid: true,
      message: '✅ VALIDATION PASSED: Phase completion requirements met',
      validationAttempts: validationState.attempts,
      completedRequirements: validationResults.passed,
      nextPhase: getNextPhaseRecommendation(params.phase, session),
      canProceed: true
    };
  }

• src/tools/validation.ts:26-50 (schema)

  The input schema definition for the validate_phase_completion tool, specifying parameters like phase, completedWork, and optional createdFiles.

  {
    name: 'validate_phase_completion',
    description: 'Validate that current phase meets all completion requirements before allowing progression',
    inputSchema: {
      type: 'object',
      properties: {
        phase: {
          type: 'string',
          enum: ['SETUP', 'AUDIT_INVENTORY', 'COMPARE_ANALYZE', 'QUESTION_DETERMINE', 'WRITE_OR_REFACTOR', 'TEST', 'LINT', 'ITERATE', 'PRESENT'],
          description: 'The phase to validate'
        },
        completedWork: {
          type: 'object',
          description: 'Description of work completed in this phase',
          additionalProperties: true
        },
        createdFiles: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of files created during this phase'
        }
      },
      required: ['phase', 'completedWork']
    }
  }

• src/index.ts:137-157 (registration)

  Registration of the tool in the MCP server by including the result of createValidationTools() (which provides the validate_phase_completion schema) in the tools array used for list_tools requests.

  const tools = [
    // Workflow entry points
    createRefactorWorkflowTool(),                 // Refactoring workflow
    createFeatureWorkflowTool(),                  // Feature creation workflow
    createTestWorkflowTool(),                     // Test writing workflow
    createTddWorkflowTool(),                      // TDD workflow
    createBuildCustomWorkflowTool(),              // Custom workflow builder
    
    // Phase guidance tools
    ...createPhaseGuidanceTools(),                // Handles both suggestive and directive modes
    createTestGuidanceTool(),                     // TEST phase guidance
    
    // Validation tools
    ...createValidationTools(),                   // Both validate_action and validate_phase_completion
    
    // Workflow management
    createUserInputRequiredTool(),                // Escalation handling
    createWorkflowStatusTool(),                   // Workflow status
    createPhaseOutputTool(),                      // Phase output recording
    createDiscoverWorkflowToolsTool()             // Tool discovery
  ];

• src/index.ts:201-207 (registration)

  Dispatch handler in the MCP call_tool request that routes validate_phase_completion calls to the handleValidatePhaseCompletion function.

  case 'validate_phase_completion':
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(await handleValidatePhaseCompletion(args as any, sessionManager), null, 2)
      }]
    };

• src/tools/validation.ts:397-461 (helper)

  Key helper function that performs the actual validation logic by checking minimum requirements and expected files against the provided completedWork and createdFiles.

  function performPhaseValidation(
    _phase: Phase, 
    completedWork: any, 
    createdFiles: string[], 
    criteria: ValidationCriteria
  ): {
    isComplete: boolean;
    passed: string[];
    failed: string[];
    blockingMessages: string[];
    nextSteps: string[];
  } {
    const passed: string[] = [];
    const failed: string[] = [];
    const blockingMessages: string[] = [];
    const nextSteps: string[] = [];
  
    // Check minimum requirements
    Object.entries(criteria.minimumRequirements).forEach(([requirement, expectedValue]) => {
      const actualValue = completedWork[requirement];
      
      if (typeof expectedValue === 'number') {
        if (actualValue >= expectedValue) {
          passed.push(`${requirement}: ${actualValue} (meets minimum ${expectedValue})`);
        } else {
          failed.push(`${requirement}: ${actualValue || 0} (need minimum ${expectedValue})`);
          blockingMessages.push(`⛔ ${requirement} insufficient: need ${expectedValue}, have ${actualValue || 0}`);
        }
      } else if (typeof expectedValue === 'boolean') {
        if (!!actualValue === expectedValue) {
          passed.push(`${requirement}: completed`);
        } else {
          failed.push(`${requirement}: not completed`);
          blockingMessages.push(`⛔ ${requirement} not completed`);
        }
      }
    });
  
    // Check expected files
    criteria.expectedFiles.forEach(expectedFile => {
      if (createdFiles.includes(expectedFile)) {
        passed.push(`File created: ${expectedFile}`);
      } else {
        failed.push(`Missing file: ${expectedFile}`);
        blockingMessages.push(`⛔ Required file not created: ${expectedFile}`);
        nextSteps.push(`Create file: ${expectedFile}`);
      }
    });
  
    // Add criteria-specific blocking messages if validation failed
    if (failed.length > 0) {
      blockingMessages.push(...criteria.blockingMessages);
      nextSteps.push('Review self-check questions');
      nextSteps.push('Complete failed requirements');
      nextSteps.push('Re-run validation');
    }
  
    return {
      isComplete: failed.length === 0,
      passed,
      failed,
      blockingMessages: [...new Set(blockingMessages)], // Remove duplicates
      nextSteps: [...new Set(nextSteps)] // Remove duplicates
    };
  }