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

Instructions

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