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

Instructions

Implementation Reference

• src/domains/workflow-rules/mcp-operations/role-transition-mcp.service.ts:31-39 (schema)

  Zod input schema and inferred TypeScript type for the execute_transition tool.

  const ExecuteTransitionInputSchema = z.object({
    transitionId: z.string().describe('Transition ID to execute'),
    taskId: z.number().describe('Task ID for transition context'),
    roleId: z.string().describe('Role ID for transition context'),
    handoffMessage: z.string().optional().describe('Optional handoff message'),
  });
  type GetRoleTransitionsInput = z.infer<typeof GetRoleTransitionsInputSchema>;
  type ValidateTransitionInput = z.infer<typeof ValidateTransitionInputSchema>;
  type ExecuteTransitionInput = z.infer<typeof ExecuteTransitionInputSchema>;

• src/domains/workflow-rules/mcp-operations/role-transition-mcp.service.ts:164-169 (registration)

  Registration of the execute_transition MCP tool using @Tool decorator with name, description, and schema.

  @Tool({
    name: 'execute_transition',
    description: `Executes role transition and returns execution status with essential details for next steps.`,
    parameters:
      ExecuteTransitionInputSchema as ZodSchema<ExecuteTransitionInput>,
  })

• src/domains/workflow-rules/mcp-operations/role-transition-mcp.service.ts:170-225 (handler)

  Main handler function for execute_transition tool: processes input, calls RoleTransitionService.executeTransition, updates workflow context cache, and returns structured MCP response.

  async executeTransition(input: ExecuteTransitionInput) {
    try {
      const context = {
        taskId: input.taskId.toString(),
        roleId: input.roleId,
      };
  
      const result = await this.roleTransitionService.executeTransition(
        input.transitionId,
        context,
        input.handoffMessage,
      );
  
      // 🧠 UPDATE WORKFLOW CONTEXT CACHE
      // Store latest workflow state after successful transition
      if (result.success && result.newRoleId) {
        try {
          // Try to find existing cache entry to update
          const existingContext = this.workflowContextCache.findContextByTaskId(
            input.taskId,
          );
  
          const cacheKey = existingContext
            ? WorkflowContextCacheService.generateKey(
                existingContext.executionId,
                'transition',
              )
            : WorkflowContextCacheService.generateKey(
                `task-${input.taskId}`,
                'transition',
              );
  
          this.workflowContextCache.updateContext(cacheKey, {
            currentRoleId: result.newRoleId,
          });
        } catch (_cacheError) {
          // Don't fail transition if cache update fails
        }
      }
  
      // ✅ MINIMAL RESPONSE: Only essential execution data
      return this.buildResponse({
        transitionId: input.transitionId,
        success: result.success,
        status: result.success ? 'completed' : 'failed',
        message: result.message,
        newRoleId: result.newRoleId,
      });
    } catch (error) {
      return this.buildErrorResponse(
        'Failed to execute transition',
        getErrorMessage(error),
        'TRANSITION_EXECUTION_ERROR',
      );
    }
  }

• src/domains/workflow-rules/services/role-transition.service.ts:188-237 (helper)

  Core helper service method implementing the transition logic: validates transition, records it, updates task ownership and workflow execution state.

  async executeTransition(
    transitionId: string,
    context: { roleId: string; taskId: string; projectPath?: string },
    handoffMessage?: string,
  ): Promise<{ success: boolean; message: string; newRoleId?: string }> {
    try {
      // First validate the transition
      const validation = await this.validateTransition(transitionId, context);
      if (!validation.valid) {
        return {
          success: false,
          message: `Transition validation failed: ${validation.errors.join(', ')}`,
        };
      }
  
      const transition =
        await this.workflowRoleRepository.findTransitionById(transitionId);
  
      if (!transition) {
        return { success: false, message: 'Transition not found' };
      }
  
      // Record the transition in the task workflow
      await this.recordTransition(transition, context, handoffMessage);
  
      // Update task ownership if needed
      await this.updateTaskOwnership(
        String(context.taskId),
        transition.toRole.name,
      );
  
      // 🔧 FIX: Update workflow execution state after role transition
      await this.updateWorkflowExecutionStateForTransition(
        context.taskId,
        transition.toRole.id,
        handoffMessage,
      );
  
      return {
        success: true,
        message: `Successfully transitioned from ${transition.fromRole.description} to ${transition.toRole.description}`,
        newRoleId: transition.toRole.id,
      };
    } catch (error) {
      return {
        success: false,
        message: `Transition execution failed: ${error.message}`,
      };
    }
  }