Structured Workflow MCP

Instructions

Implementation Reference

• src/tools/phaseGuidance.ts:22-25 (registration)

  Tool registration: Defines the MCP Tool object with name, description, and empty input schema.
  { name: 'question_determine_guidance', description: 'Get guidance for the QUESTION_DETERMINE phase - clarify and finalize plan', inputSchema: { type: 'object', properties: {} }
• src/index.ts:213-223 (handler)

  Handler dispatch: Switch case that handles the tool call by invoking handlePhaseGuidance with the phase name.
  case 'question_determine_guidance': case 'refactor_guidance': case 'lint_guidance': case 'iterate_guidance': case 'present_guidance': return { content: [{ type: 'text', text: JSON.stringify(await handlePhaseGuidance(name, sessionManager), null, 2) }] };
• src/tools/phaseGuidance.ts:52-65 (handler)

  Core handler function: Routes to directive or suggestive guidance based on session configuration.
  export async function handlePhaseGuidance( phaseName: string, sessionManager: SessionManager ): Promise<PhaseGuidance> { const session = sessionManager.getSession(); const isDirectiveMode = session?.workflowConfig !== undefined; // Route to appropriate guidance based on mode if (isDirectiveMode) { return getDirectiveGuidance(phaseName, sessionManager); } else { return getSuggestiveGuidance(phaseName, sessionManager); } }
• src/tools/phaseGuidance.ts:188-233 (handler)

  Suggestive mode guidance: The static PhaseGuidance object returned for this tool in non-directive mode.
  question_determine_guidance: { phase: 'QUESTION_DETERMINE', objective: 'Clarify any ambiguities AND determine your final implementation plan', instructions: [ '--- QUESTION PHASE (Clarification) ---', 'Review your understanding from the analysis and inventory', 'Identify any ambiguous requirements or unclear aspects', 'Formulate specific, answerable questions', 'Document assumptions you\'re making', 'If critical questions need user input, consider using user_input_required_guidance', '--- DETERMINE PHASE (Planning) ---', 'Based on all clarifications, create a detailed implementation plan', 'Break down your chosen approach into specific steps', 'Order the steps logically based on dependencies', 'Define clear success criteria for each step', 'Plan validation points throughout the implementation' ], suggestedApproach: [ 'QUESTION: Be specific with questions - vague questions get vague answers', 'QUESTION: Prioritize questions that would block progress', 'QUESTION: Document assumptions clearly if answers aren\'t available', 'DETERMINE: Start with foundation changes that others depend on', 'DETERMINE: Keep implementation steps small and focused', 'DETERMINE: Plan to test after each major change', 'DETERMINE: Include rollback strategies for risky changes' ], importantNotes: [ 'Questions and planning go hand-in-hand', 'A clear plan requires all ambiguities to be resolved', 'This phase finalizes your strategy before any code changes', 'If you need user input for critical questions, don\'t hesitate to escalate' ], expectedOutput: { // Question outputs questions: 'List of specific questions (if any)', assumptions: 'What you\'re assuming if not clarified', clarifications: 'Any resolved ambiguities', // Determine outputs implementationSteps: 'Numbered list of specific changes to make', dependencies: 'Which steps depend on others', validation: 'How to verify each step', successCriteria: 'Definition of completion', rollbackPlan: 'How to undo changes if needed' }, nextPhase: 'Use refactor_guidance to begin implementation' },
• src/tools/phaseGuidance.ts:868-1017 (handler)

  Directive mode guidance: Enhanced PhaseGuidance object with validation criteria, required files, etc., for directive mode.
  question_determine_guidance: { phase: 'QUESTION_DETERMINE', objective: 'Clarify ambiguities AND determine final implementation plan - CRITICAL DECISION PHASE', directiveInstructions: [ '--- QUESTION REQUIREMENTS ---', '🔴 MANDATORY: You MUST identify all ambiguous requirements', '📋 REQUIRED: You MUST formulate specific, answerable questions', '📊 CRITICAL: You MUST document assumptions for unclear aspects', '--- DETERMINE REQUIREMENTS ---', '🔴 MANDATORY: You MUST create detailed step-by-step implementation plan', '🎯 REQUIRED: You MUST define success criteria for each step', '📊 CRITICAL: You MUST plan validation and rollback strategies', '--- OUTPUT REQUIREMENTS ---', '📁 BLOCKING: You MUST create all required planning files' ], instructions: [ '--- QUESTION PHASE (Clarification) ---', 'Review all findings from AUDIT_INVENTORY and COMPARE_ANALYZE', 'Identify any ambiguous requirements or unclear aspects', 'Formulate specific questions that need answers', 'Document assumptions you\'re making', 'Consider if user input is needed for critical decisions', '--- DETERMINE PHASE (Planning) ---', 'Based on all information and clarifications, finalize implementation plan', 'Break down chosen approach into specific, ordered steps', 'Define success criteria and validation points for each step', 'Plan rollback strategies for risky changes', 'Create comprehensive implementation roadmap' ], blockingMessages: [ '⛔ CANNOT PROCEED: Ambiguities not properly identified', '⛔ CANNOT PROCEED: Implementation plan not detailed enough', '⛔ CANNOT PROCEED: Success criteria not defined', '⛔ CANNOT PROCEED: Validation strategy not planned', '⛔ CANNOT PROCEED: Required output files not created' ], requiredOutputFiles: [ { path: 'structured-workflow/{task-name}/04-question-clarifications.md', description: 'Questions, assumptions, and clarifications', required: true, format: 'markdown', validationRules: [ 'Must identify any ambiguous requirements', 'Must list specific questions (if any)', 'Must document assumptions being made', 'Must indicate if user input is needed' ] }, { path: 'structured-workflow/{task-name}/04-determine-implementation-plan.json', description: 'Detailed step-by-step implementation plan', required: true, format: 'json', validationRules: [ 'Must contain ordered implementation steps', 'Must include success criteria for each step', 'Must define validation points', 'Must include rollback strategies' ] }, { path: 'structured-workflow/{task-name}/04-determine-roadmap.md', description: 'Visual implementation roadmap', required: true, format: 'markdown', validationRules: [ 'Must show implementation sequence', 'Must highlight dependencies', 'Must indicate risk points', 'Must include validation checkpoints' ] } ], validationCriteria: { minimumRequirements: { ambiguitiesReviewed: true, questionsFormulated: true, assumptionsDocumented: true, implementationStepsCreated: true, successCriteriaDefined: true, validationPlanned: true, rollbackStrategies: true, filesCreated: 3 }, blockingMessages: [ '⛔ CANNOT PROCEED: Clarifications incomplete', '⛔ CANNOT PROCEED: Implementation plan not finalized', '⛔ CANNOT PROCEED: Success criteria missing', '⛔ CANNOT PROCEED: Required files not created' ], expectedFiles: [ 'structured-workflow/{task-name}/04-question-clarifications.md', 'structured-workflow/{task-name}/04-determine-implementation-plan.json', 'structured-workflow/{task-name}/04-determine-roadmap.md' ], selfCheckQuestions: [ 'Have I reviewed all ambiguities from previous phases?', 'Have I formulated specific questions where needed?', 'Have I documented all assumptions?', 'Have I created a detailed implementation plan?', 'Have I defined success criteria for each step?', 'Have I planned validation and rollback strategies?', 'Have I created all 3 required output files?' ], completionCriteria: [ 'All ambiguities addressed or documented', 'Questions formulated where clarification needed', 'Assumptions clearly documented', 'Step-by-step implementation plan created', 'Success criteria defined for each step', 'Validation strategy planned', 'Rollback approach documented', 'All output files generated' ], cannotProceedUntil: [ 'All clarifications complete', 'Implementation plan finalized', 'All required files created' ] }, expectedOutput: { // Question outputs questions: 'Specific questions needing answers', assumptions: 'Documented assumptions for unclear aspects', clarifications: 'Any resolved ambiguities', userInputNeeded: 'Whether critical decisions need user input', // Determine outputs implementationSteps: 'Detailed, ordered list of changes', successCriteria: 'Definition of completion for each step', validationStrategy: 'How to verify each step', rollbackPlan: 'How to undo changes if needed', outputFiles: '3 required documentation files created' }, nextPhase: 'After validation complete, use refactor_guidance', prerequisites: { completed: ['AUDIT_INVENTORY', 'COMPARE_ANALYZE'], warning: !session || !session.completedPhases.includes('AUDIT_INVENTORY') || !session.completedPhases.includes('COMPARE_ANALYZE') ? '⚠️ WARNING: Previous phases not completed. Planning may lack necessary context.' : null } }