Structured Workflow MCP

Instructions

Implementation Reference

• src/tools/userInputRequired.ts:33-192 (handler)

  Main handler function for 'user_input_required_guidance' tool. Processes escalation triggers, updates session phase, generates user input report file, provides detailed guidance and blocking messages based on trigger type, and returns PhaseGuidance object.

  export async function handleUserInputRequired(
    params: {
      trigger: 'iteration_limit' | 'user_checkpoint' | 'validation_failure' | 'time_limit';
      context?: any;
    },
    sessionManager: SessionManager
  ): Promise<PhaseGuidance> {
    const session = sessionManager.getSession();
    
    if (!session) {
      throw new Error('No active session. Use build_custom_workflow first.');
    }
  
    // Update to USER_INPUT_REQUIRED phase
    sessionManager.updatePhase('USER_INPUT_REQUIRED');
    
    const config = session.workflowConfig;
    const outputDir = config?.outputPreferences.outputDirectory || 'workflow-output';
    const escalationContext = params.context || {};
  
    // Generate escalation report file
    const userInputFile: OutputFileInstruction = {
      path: `${outputDir}/user-input-needed.md`,
      description: 'User input escalation report with options and context',
      required: true,
      format: 'markdown',
      template: generateUserInputTemplate(params.trigger, escalationContext, session),
      validationRules: [
        'Must explain escalation trigger clearly',
        'Must provide specific user options',
        'Must include current workflow context'
      ]
    };
  
    // Define escalation-specific guidance based on trigger
    let escalationGuidance: PhaseGuidance;
  
    switch (params.trigger) {
      case 'iteration_limit':
        escalationGuidance = {
          phase: 'USER_INPUT_REQUIRED',
          objective: '⚠️ ITERATION LIMIT REACHED - User guidance needed to proceed',
          
          directiveInstructions: [
            '🛑 STOP ALL WORKFLOW ACTIVITY: You have reached the configured iteration limit',
            '📋 MANDATORY: You MUST create user input escalation report',
            '⏳ WAIT: You MUST pause workflow until user provides direction',
            '📞 ESCALATE: Present clear options for user to choose from'
          ],
  
          instructions: [
            'Document exactly why the iteration limit was reached',
            'Summarize the current state and what has been attempted',
            'Present clear, actionable options for the user',
            'Create comprehensive escalation report',
            'Pause all further workflow activity'
          ],
  
          expectedOutput: {
            escalationReason: `Iteration limit reached for ${escalationContext.failedPhase || 'unknown'} phase`,
            attemptsSummary: `${escalationContext.attemptCount || 'Unknown'} attempts made`,
            currentStatus: 'Summary of what has been accomplished and what failed',
            userOptions: 'Clear options for how to proceed',
            escalationReport: 'User input escalation document created'
          },
  
          requiredOutputFiles: [userInputFile],
  
          blockingMessages: [
            '⛔ WORKFLOW PAUSED: Iteration limit exceeded',
            '⛔ USER INPUT REQUIRED: Cannot proceed without user guidance',
            '⛔ NO FURTHER ACTIONS: All workflow activity must stop until user responds'
          ],
  
          nextPhase: 'Workflow paused - awaiting user input and direction'
        };
        break;
  
      case 'validation_failure':
        escalationGuidance = {
          phase: 'USER_INPUT_REQUIRED',
          objective: '⚠️ VALIDATION FAILURES - User review needed for quality issues',
          
          directiveInstructions: [
            '🛑 VALIDATION BLOCKED: Multiple validation attempts have failed',
            '📋 MANDATORY: You MUST document specific validation failures',
            '🔍 REQUIRED: You MUST provide detailed failure analysis',
            '📞 ESCALATE: Request user review of validation criteria'
          ],
  
          instructions: [
            'Document all validation failures encountered',
            'Analyze patterns in validation issues',
            'Suggest potential solutions or criteria adjustments',
            'Request user review of validation requirements'
          ],
  
          expectedOutput: {
            validationFailures: 'Specific validation issues encountered',
            failurePatterns: 'Common themes in validation problems',
            suggestedSolutions: 'Potential ways to resolve issues',
            criteriaReview: 'Validation criteria that may need adjustment'
          },
  
          requiredOutputFiles: [userInputFile]
        };
        break;
  
      case 'user_checkpoint':
        escalationGuidance = {
          phase: 'USER_INPUT_REQUIRED',
          objective: '📋 USER CHECKPOINT - Scheduled user review point',
          
          directiveInstructions: [
            '⏸️ CHECKPOINT REACHED: User review configured for this point',
            '📊 MANDATORY: You MUST provide comprehensive progress summary',
            '🎯 REQUIRED: You MUST highlight key decisions and changes',
            '📞 PRESENT: Show user current state and next planned actions'
          ],
  
          instructions: [
            'Summarize progress made since last checkpoint',
            'Highlight significant decisions and changes',
            'Present current state and upcoming plans',
            'Request user confirmation to proceed'
          ],
  
          expectedOutput: {
            progressSummary: 'What has been accomplished since last checkpoint',
            keyDecisions: 'Important decisions made during workflow',
            currentState: 'Current status of refactoring',
            upcomingActions: 'Next planned phases and activities'
          },
  
          requiredOutputFiles: [userInputFile]
        };
        break;
  
      default:
        escalationGuidance = {
          phase: 'USER_INPUT_REQUIRED',
          objective: '⚠️ ESCALATION TRIGGERED - User input needed',
          
          instructions: [
            'Document the escalation trigger',
            'Provide current workflow context',
            'Request user guidance on how to proceed'
          ],
  
          expectedOutput: {
            escalationContext: 'Why escalation was triggered',
            workflowState: 'Current status of refactoring workflow'
          },
  
          requiredOutputFiles: [userInputFile]
        };
    }
  
    return escalationGuidance;
  }

• src/tools/userInputRequired.ts:5-30 (schema)

  Defines the Tool object for 'user_input_required_guidance' including name, description, and detailed inputSchema for trigger and context parameters.

  export function createUserInputRequiredTool(): Tool {
    return {
      name: 'user_input_required_guidance',
      description: 'Handle escalation to user input when iteration limits reached or checkpoints triggered',
      inputSchema: {
        type: 'object',
        properties: {
          trigger: {
            type: 'string',
            enum: ['iteration_limit', 'user_checkpoint', 'validation_failure', 'time_limit'],
            description: 'What triggered the escalation'
          },
          context: {
            type: 'object',
            description: 'Additional context about the escalation',
            properties: {
              failedPhase: { type: 'string' },
              attemptCount: { type: 'number' },
              lastError: { type: 'string' },
              specificIssues: { type: 'array', items: { type: 'string' } }
            }
          }
        },
        required: ['trigger']
      }
    };

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

  Registers the tool by calling createUserInputRequiredTool() and including it in the tools array provided to the MCP Server's listTools handler.

  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:193-199 (registration)

  Registers the tool handler dispatch in the main CallToolRequestSchema switch statement, calling handleUserInputRequired with sessionManager.

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

• src/tools/userInputRequired.ts:194-252 (helper)

  Helper function that generates the Markdown template content for the user-input-needed.md escalation report file.

  function generateUserInputTemplate(
    trigger: string,
    context: any,
    session: any
  ): string {
    const timestamp = new Date().toISOString();
    const failedPhase = context.failedPhase || 'Unknown';
    const attemptCount = context.attemptCount || 0;
    const lastError = context.lastError || 'Not specified';
  
    return `# User Input Required - Workflow Escalation
  
  ## Escalation Details
  - **Timestamp**: ${timestamp}
  - **Trigger**: ${trigger.toUpperCase().replace('_', ' ')}
  - **Session ID**: ${session.id}
  - **Failed Phase**: ${failedPhase}
  - **Attempt Count**: ${attemptCount}
  
  ## Current Situation
  ${generateSituationDescription(trigger, context)}
  
  ## Last Error/Issue
  \`\`\`
  ${lastError}
  \`\`\`
  
  ## User Options
  
  ${generateUserOptions(trigger, context)}
  
  ## Current Workflow Status
  - **Total Phases Completed**: ${session.completedPhases.length}
  - **Current Phase**: ${session.currentPhase}
  - **Time Elapsed**: ${Math.round((Date.now() - session.startedAt) / 1000 / 60)} minutes
  - **Files Modified**: ${session.metrics.filesModified}
  
  ## Workflow Configuration
  - **Selected Phases**: ${session.workflowConfig?.selectedPhases.join(', ') || 'Default'}
  - **Iteration Limits**: TEST=${session.workflowConfig?.iterationLimits.TEST}, LINT=${session.workflowConfig?.iterationLimits.LINT}, ITERATE=${session.workflowConfig?.iterationLimits.ITERATE}
  
  ## Recommendations
  
  ${generateRecommendations(trigger, context)}
  
  ## How to Proceed
  
  1. **Review the situation** described above
  2. **Choose one of the user options** listed
  3. **Modify workflow configuration** if needed
  4. **Resume workflow** with updated guidance
  5. **Or request human intervention** if issues are complex
  
  ---
  
  **⚠️ WORKFLOW PAUSED**: No further automatic actions will be taken until user input is provided.
  
  *Generated by USER_INPUT_REQUIRED phase at ${timestamp}*`;
  }