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 }; }