𓂀𓁢𓋹𝔸ℕ𝕌𝔹𝕀𝕊𓋹𓁢𓂀 - Intelligent Guidance for

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/domains/workflow-rules/mcp-operations/step-execution-mcp.service.ts:19-38 (schema)

  Zod input schema for the get_step_guidance tool defining parameters: taskId, executionId, roleId, stepId with validation that either taskId or executionId is provided.
  const GetStepGuidanceInputSchema = z .object({ taskId: z .number() .optional() .describe('Task ID for context (optional if executionId provided)'), executionId: z .string() .optional() .describe('Execution ID for context (optional if taskId provided)'), roleId: z.string().describe('Role ID for step guidance'), stepId: z.string().optional().describe('Optional specific step ID'), }) .refine( (data) => data.taskId !== undefined || data.executionId !== undefined, { message: 'Either taskId or executionId must be provided', path: ['taskId', 'executionId'], }, );
• src/domains/workflow-rules/mcp-operations/step-execution-mcp.service.ts:153-157 (registration)

  @Tool decorator that registers the get_step_guidance MCP tool with name, description, and input schema.
  @Tool({ name: 'get_step_guidance', description: `Provides focused guidance for executing the current workflow step, including commands and validation checklist.`, parameters: GetStepGuidanceInputSchema as ZodSchema<GetStepGuidanceInput>, })
• src/domains/workflow-rules/mcp-operations/step-execution-mcp.service.ts:158-267 (handler)

  The primary handler for get_step_guidance tool. Resolves execution context, delegates to StepGuidanceService for core logic, updates workflow context cache, and returns formatted response or error.
  async getStepGuidance(input: GetStepGuidanceInput) { try { // 🔧 CRITICAL FIX: Enhanced to handle post-transition scenarios let currentStepId = input.stepId; let currentRoleId = input.roleId; let actualTaskId = input.taskId; let resolvedExecutionId = input.executionId; // Get execution context if needed if (!currentStepId || !actualTaskId) { const executionQuery = input.taskId !== undefined ? { taskId: input.taskId } : { executionId: input.executionId }; const executionResult = await this.workflowExecutionOperationsService.getExecution( executionQuery, ); if (!executionResult.execution) { return this.buildResponse({ error: 'No active execution found', guidance: 'Please ensure workflow is properly initialized', }); } const currentExecution = executionResult.execution; // 🔧 BOOTSTRAP FIX: Update context from execution - HANDLE BOOTSTRAP CASE if (currentExecution.taskId) { actualTaskId = actualTaskId || currentExecution.taskId; } else { // Bootstrap case: execution has no task yet actualTaskId = 0; // Signal bootstrap mode to resolveStepId } currentRoleId = currentExecution.currentRoleId; // 🔧 CRITICAL FIX: Don't require currentStepId - let guidance service auto-detect if (currentExecution.currentStepId) { currentStepId = currentExecution.currentStepId; } if (!currentRoleId) { return this.buildResponse({ error: 'Missing execution context', details: { hasRoleId: Boolean(currentRoleId), hasTaskId: Boolean(actualTaskId), isBootstrapMode: actualTaskId === 0, }, }); } resolvedExecutionId = executionResult.execution.id; } // ✅ ENHANCED: Use transition-aware StepGuidanceService const guidance = await this.stepGuidanceService.getStepGuidance({ taskId: actualTaskId, roleId: currentRoleId, executionId: resolvedExecutionId, stepId: currentStepId, // May be undefined - guidance service handles this validateTransitionState: true, // Enable transition state detection }); // 🧠 UPDATE WORKFLOW CONTEXT CACHE // Store latest workflow state after successful guidance generation if (resolvedExecutionId) { try { const cacheKey = WorkflowContextCacheService.generateKey( resolvedExecutionId, 'step_guidance', ); // Get current execution to extract latest state const currentExecution = await this.workflowExecutionOperationsService.getExecution({ executionId: resolvedExecutionId, }); if (currentExecution.execution) { const execution = currentExecution.execution; this.workflowContextCache.storeContext(cacheKey, { executionId: resolvedExecutionId, taskId: execution.taskId || actualTaskId, currentRoleId: execution.currentRoleId || currentRoleId, currentStepId: execution.currentStepId || undefined, roleName: execution.currentRole?.name || 'Unknown', stepName: execution.currentStep?.name, taskName: execution.task?.name, projectPath: process.cwd(), source: 'step_completion', }); } } catch (_cacheError) { // Don't fail the main operation if cache update fails // Silent fail to avoid disrupting workflow } } // Return clean guidance without artificial fields return this.buildResponse(guidance); } catch (error) { return this.buildErrorResponse( 'Failed to get step guidance', getErrorMessage(error), 'STEP_GUIDANCE_ERROR', ); } }
• src/domains/workflow-rules/services/step-guidance.service.ts:61-150 (helper)

  Supporting helper service method implementing core guidance logic: auto-resolves step ID, queries step data, handles role transitions, generates quality checklist and step-by-step guidance.
  async getStepGuidance( context: StepGuidanceContext, ): Promise<StepGuidanceResult> { // 🔧 CRITICAL FIX: Auto-detect step if not provided (common after transitions) let stepId = context.stepId; if (!stepId || context.validateTransitionState !== false) { const resolvedStepId = await this.resolveStepId(context); if (!resolvedStepId) { throw new StepNotFoundError( 'unknown', 'StepGuidanceService', 'getStepGuidance - could not resolve stepId for current context', ); } stepId = resolvedStepId; } // Get step with MCP actions const step = await this.stepQueryService.getStepWithDetails(stepId); if (!step) { throw new StepNotFoundError( stepId, 'StepGuidanceService', 'getStepGuidance', ); } // Validate step belongs to current role if (step.roleId !== context.roleId) { // Try to find correct step for current role const correctStep = await this.stepQueryService.getNextAvailableStep( context.taskId.toString(), context.roleId, { checkTransitionState: true }, ); if (correctStep) { return await this.getStepGuidance({ ...context, stepId: correctStep.id, validateTransitionState: false, // Avoid infinite recursion }); } else { throw new StepNotFoundError( stepId, 'StepGuidanceService', `Step role mismatch: step belongs to ${step.roleId}, requested for ${context.roleId}`, ); } } // Get guidance from database step data (fix type mismatch) const guidanceData = { stepGuidance: Array.isArray(step.stepGuidance) && step.stepGuidance.length > 0 ? step.stepGuidance[0] : null, qualityChecks: step.qualityChecks, }; const enhancedGuidance = extractStreamlinedGuidance(guidanceData); return { step: StepDataUtils.extractStepInfo({ id: step.id, name: step.name, description: step.description, stepType: step.stepType, roleId: step.roleId, approach: step.approach, sequenceNumber: step.sequenceNumber, isRequired: step.isRequired, createdAt: new Date(), // Provide default dates updatedAt: new Date(), }), qualityChecklist: enhancedGuidance.qualityChecklist, stepByStep: enhancedGuidance.stepByStep, approach: step.approach, guidance: step.stepGuidance, transitionContext: { stepResolved: stepId !== context.stepId, originalStepId: context.stepId, resolvedStepId: stepId, }, }; }