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

Instructions

Implementation Reference

• src/domains/workflow-rules/mcp-operations/workflow-guidance-mcp.service.ts:61-160 (handler)

  The primary MCP tool handler for 'get_workflow_guidance'. It processes input, retrieves or creates execution context, ensures current step is assigned, fetches role guidance from the service, and returns structured response with execution context.

  @Tool({
    name: 'get_workflow_guidance',
    description: `Provides minimal role identity and basic capabilities for workflow execution.`,
    parameters:
      GetWorkflowGuidanceInputSchema as ZodSchema<GetWorkflowGuidanceInput>,
  })
  async getWorkflowGuidance(input: GetWorkflowGuidanceInput): Promise<any> {
    try {
      // 🔧 BOOTSTRAP FIX: Handle both taskId and executionId
      let currentExecution;
      let contextTaskId: number;
  
      if (input.executionId) {
        // Query by executionId (bootstrap mode)
        currentExecution = await this.workflowExecutionRepository.findById(
          input.executionId,
          {
            currentRole: true,
            currentStep: true,
          },
        );
        contextTaskId = currentExecution?.taskId || 0; // Use 0 for bootstrap mode
      } else if (input.taskId !== undefined) {
        // Query by taskId (normal mode)
        const taskId =
          typeof input.taskId === 'string'
            ? parseInt(input.taskId)
            : input.taskId;
  
        if (isNaN(taskId)) {
          throw new Error(`Invalid taskId: ${input.taskId}`);
        }
  
        currentExecution = await this.workflowExecutionRepository.findByTaskId(
          taskId,
          {
            currentRole: true,
            currentStep: true,
          },
        );
        contextTaskId = taskId;
      } else {
        throw new Error('Either taskId or executionId must be provided');
      }
  
      if (currentExecution) {
        // Check if execution has proper step assignment
        if (!currentExecution.currentStepId) {
          // Try to find and assign the first step for the current role
          const firstStepForRole =
            await this.workflowStepRepository.findFirstStepForRole(
              currentExecution.currentRoleId,
            );
  
          if (firstStepForRole) {
            await this.fixMissingCurrentStep(
              currentExecution,
              firstStepForRole,
            );
          }
        }
      }
  
      const context = {
        taskId: contextTaskId,
        projectPath: input.projectPath,
      };
  
      // Get ONLY essential role identity - NO verbose behavioral context
      // The guidance service now returns minimal role data without relations
      const roleGuidance =
        await this.workflowGuidanceService.getWorkflowGuidance(
          input.roleName,
          context,
        );
  
      // 🆕 ENHANCEMENT: Include execution context in response
      const executionContext = currentExecution
        ? {
            executionId: currentExecution.id,
            currentStepId: currentExecution.currentStepId,
            executionState: currentExecution.executionState,
            hasCurrentStep: !!currentExecution.currentStepId,
          }
        : null;
  
      // Return minimal essential-only response with execution context
      return this.buildResponse({
        success: true,
        currentRole: roleGuidance.currentRole,
        executionContext: executionContext,
      });
    } catch (error: any) {
      return this.buildErrorResponse(
        'Failed to get workflow guidance',
        error.message,
        'GUIDANCE_ERROR',
      );
    }
  }

• src/domains/workflow-rules/mcp-operations/workflow-guidance-mcp.service.ts:11-36 (schema)

  Zod schema defining the input parameters for the get_workflow_guidance tool, including roleName, taskId/executionId, etc., with validation that at least one of taskId or executionId is provided.

  const GetWorkflowGuidanceInputSchema = z
    .object({
      roleName: z
        .enum(['product-manager', 'architect', 'senior-developer', 'code-review'])
        .describe('Current role name for workflow guidance'),
      taskId: z
        .number()
        .optional()
        .describe('Task ID for context (optional during bootstrap)'),
      roleId: z.string().describe('Role ID for transition context'),
      executionId: z
        .string()
        .optional()
        .describe('Execution ID (alternative to taskId)'),
      projectPath: z
        .string()
        .optional()
        .describe('Project path for project-specific context'),
    })
    .refine(
      (data) => data.taskId !== undefined || data.executionId !== undefined,
      {
        message: 'Either taskId or executionId must be provided',
        path: ['taskId', 'executionId'],
      },
    );

• src/domains/workflow-rules/services/workflow-guidance.service.ts:84-101 (helper)

  Helper service method that fetches the WorkflowRole by name (without relations) and returns minimal role guidance structure. Called by the MCP handler.

  async getWorkflowGuidance(
    roleName: string,
    _context: RoleContext,
  ): Promise<WorkflowGuidance> {
    // Get role information WITHOUT relations to keep response minimal
    // Explicitly pass empty include to avoid loading any relations
    const role = await this.getWorkflowRole(roleName, {});
    if (!role) {
      throw new Error(`Workflow role '${roleName}' not found`);
    }
  
    // FOCUSED: Build role-only guidance structure (NO step details)
    const roleGuidance: WorkflowGuidance = {
      currentRole: role,
    };
  
    return roleGuidance;
  }

• src/domains/workflow-rules/mcp-operations/workflow-guidance-mcp.service.ts:61-66 (registration)

  @Tool decorator registration of the get_workflow_guidance tool with name, description, and input schema.

  @Tool({
    name: 'get_workflow_guidance',
    description: `Provides minimal role identity and basic capabilities for workflow execution.`,
    parameters:
      GetWorkflowGuidanceInputSchema as ZodSchema<GetWorkflowGuidanceInput>,
  })