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

Instructions

Implementation Reference

• src/domains/workflow-rules/mcp-operations/workflow-execution-mcp.service.ts:230-234 (registration)

  Tool registration via @Tool decorator with name 'workflow_execution_operations' and the entry point handler function.
  @Tool({ name: 'workflow_execution_operations', description: `Manages workflow execution state through strongly-typed operations for creating, querying, updating, and completing workflow executions. Handles execution context and progress tracking with validated parameters.`, parameters: WorkflowExecutionSchema, })
• src/domains/workflow-rules/mcp-operations/workflow-execution-mcp.service.ts:235-319 (handler)

  Handler logic that parses input.operation and delegates to corresponding methods in WorkflowExecutionOperationsService.
  async executeWorkflowOperation( input: WorkflowExecutionInputSchema, ): Promise<McpResponse> { try { const workflowInput: WorkflowExecutionInput = { taskId: input.taskId, executionId: input.executionId, roleName: input.roleName, executionMode: input.executionMode, executionContext: input.executionContext, updateData: input.updateData, stepId: input.stepId, orchestrationConfig: input.orchestrationConfig, }; let result: any; switch (input.operation) { case 'create_execution': result = await this.executionOps.createExecution(workflowInput); break; case 'get_execution': result = await this.executionOps.getExecution(workflowInput); break; case 'update_execution': result = await this.executionOps.updateExecution(workflowInput); break; case 'complete_execution': result = await this.executionOps.completeExecution(workflowInput); break; case 'get_active_executions': result = await this.executionOps.getActiveExecutions(); break; case 'get_execution_context': if (!input.executionId) { throw new Error( 'executionId is required for get_execution_context', ); } result = await this.executionOps.getExecutionContext({ executionId: input.executionId, dataKey: input.dataKey, }); break; case 'update_execution_context': if (!input.executionId) { throw new Error( 'executionId is required for update_execution_context', ); } if (!input.contextUpdates) { throw new Error( 'contextUpdates is required for update_execution_context', ); } result = await this.executionOps.updateExecutionContext({ executionId: input.executionId, contextUpdates: input.contextUpdates, }); break; default: { const exhaustiveCheck: never = input.operation; throw new Error(`Unknown operation: ${String(exhaustiveCheck)}`); } } // Return MINIMAL state data only - NO guidance generation, NO envelopes return this.buildResponse({ success: true, data: result, timestamp: new Date().toISOString(), }); } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : 'Unknown error'; return this.buildErrorResponse( errorMessage, '', 'WORKFLOW_EXECUTION_FAILED', ); } } }
• src/domains/workflow-rules/mcp-operations/workflow-execution-mcp.service.ts:123-205 (schema)

  Primary Zod schema for tool input validation, including operation enum and conditional requirements via refine.
  const WorkflowExecutionSchema = z .object({ operation: z .enum([ 'create_execution', 'get_execution', 'update_execution', 'complete_execution', 'get_active_executions', 'get_execution_context', 'update_execution_context', ]) .describe('Operation to execute'), // Identifiers taskId: z .number() .optional() .describe('Task ID (optional for bootstrap executions)'), executionId: z .string() .optional() .describe('Execution ID for operations requiring it'), // Role and execution settings roleName: z .enum(['product-manager', 'architect', 'senior-developer', 'code-review']) .optional() .describe('Role name for execution'), executionMode: z .enum(['GUIDED', 'AUTOMATED', 'HYBRID']) .optional() .describe('Execution mode'), autoCreatedTask: z .boolean() .optional() .describe('Whether task was auto-created'), // Structured data fields - NO MORE z.any() executionContext: ExecutionContextSchema.optional(), updateData: UpdateDataSchema.optional(), stepId: z.string().optional().describe('Current step ID'), orchestrationConfig: OrchestrationConfigSchema.optional(), // Context operation fields dataKey: z .string() .optional() .describe('Specific data key to retrieve from context'), contextUpdates: ContextUpdatesSchema.optional(), }) .refine( (data) => { // Validation rules for different operations if (data.operation === 'get_execution') { return data.taskId !== undefined || data.executionId !== undefined; } if ( [ 'update_execution', 'complete_execution', 'get_execution_context', 'update_execution_context', ].includes(data.operation) ) { return data.executionId !== undefined; } if (data.operation === 'create_execution') { return data.roleName !== undefined; } if (data.operation === 'update_execution_context') { return data.contextUpdates !== undefined; } return true; }, { message: 'Invalid operation parameters - check required fields for each operation', }, ) .describe('Workflow execution operation with strongly typed parameters');
• src/domains/workflow-rules/workflow-rules.module.ts:68-97 (registration)

  NestJS module registration of WorkflowExecutionMcpService in providers and exports arrays.
  WorkflowGuidanceMcpService, StepExecutionMcpService, RoleTransitionMcpService, WorkflowExecutionMcpService, WorkflowBootstrapMcpService, // Core Services WorkflowGuidanceService, ProgressCalculatorService, StepExecutionService, StepGuidanceService, StepProgressTrackerService, StepQueryService, RoleTransitionService, WorkflowExecutionService, WorkflowExecutionOperationsService, ExecutionDataEnricherService, WorkflowBootstrapService, ExecutionAnalyticsService, WorkflowContextCacheService, // Guards WorkflowContextValidationGuard, ], exports: [ // MCP Operations WorkflowGuidanceMcpService, StepExecutionMcpService, RoleTransitionMcpService, WorkflowExecutionMcpService,
• src/domains/workflow-rules/services/workflow-execution-operations.service.ts:83-354 (helper)

  Core service implementing the execution operations (create, get, update, complete, etc.) delegated by the MCP handler.
  export class WorkflowExecutionOperationsService extends ConfigurableService<ExecutionOperationsConfig> { // Configuration with sensible defaults protected readonly defaultConfig: ExecutionOperationsConfig = { defaults: { executionMode: 'GUIDED', orchestrationMode: 'sequential', continueOnFailure: false, }, validation: { requireExecutionId: true, requireRoleName: true, maxServiceCalls: 20, }, performance: { operationTimeoutMs: 30000, maxConcurrentExecutions: 10, cacheResultsMs: 300000, // 5 minutes }, }; constructor( private readonly workflowExecution: WorkflowExecutionService, private readonly dataEnricher: ExecutionDataEnricherService, private readonly analytics: ExecutionAnalyticsService, ) { super(); this.initializeConfig(); } /** * Validate input parameters */ private validateInput( input: WorkflowExecutionInput, operation: string, ): void { // Special handling for operations that can work without taskId // get_execution can work with either taskId OR executionId if (operation === 'get_execution') { if (!input.taskId && !input.executionId) { throw new Error(`get_execution requires either taskId or executionId`); } } if ( operation === 'create' && this.getConfigValue('validation').requireRoleName && !input.roleName ) { throw new Error(`roleName is required for ${operation}`); } if ( ['update', 'complete'].includes(operation) && this.getConfigValue('validation').requireExecutionId && !input.executionId ) { throw new Error(`executionId is required for ${operation}`); } if (input.orchestrationConfig?.serviceCalls) { const serviceCallCount = input.orchestrationConfig.serviceCalls.length; const maxServiceCalls = this.getConfigValue('validation').maxServiceCalls; if (serviceCallCount > maxServiceCalls) { throw new Error( `Too many service calls: ${serviceCallCount}. Maximum allowed: ${maxServiceCalls}`, ); } } } /** * Create new workflow execution */ async createExecution( input: WorkflowExecutionInput, ): Promise<ExecutionResult> { this.validateInput(input, 'create'); const createInput: CreateWorkflowExecutionInput = { taskId: input.taskId, currentRoleId: input.roleName!, // Safe after validation executionMode: input.executionMode || this.getConfigValue('defaults').executionMode, executionContext: input.executionContext, }; const execution = await this.workflowExecution.createExecution(createInput); const nextSteps = await this.dataEnricher.getNextStepsForExecution( execution.id, ); return { execution, nextSteps, }; } /** * Get execution with enriched context */ async getExecution(input: WorkflowExecutionInput): Promise<ExecutionResult> { this.validateInput(input, 'get'); let execution: WorkflowExecutionWithRelations | null; if (!input.executionId) { if (!input.taskId) { throw new Error( `Either taskId or executionId is required for get operation`, ); } execution = await this.workflowExecution.getExecutionByTaskId( input.taskId, ); if (!execution) { throw new Error(`No execution found for task ${input.taskId}`); } } else { execution = await this.workflowExecution.getExecutionById( input.executionId, // Safe after validation ); } return await this.dataEnricher.enrichExecutionData(execution); } /** * Get execution context data * Used by product-manager workflow to retrieve task creation data */ async getExecutionContext(input: { executionId: string; dataKey?: string; }): Promise<any> { const execution = await this.workflowExecution.getExecutionById( input.executionId, ); if (input.dataKey) { // Return specific data from execution context if ( execution.executionContext && typeof execution.executionContext === 'object' && execution.executionContext !== null && input.dataKey in execution.executionContext ) { return (execution.executionContext as Record<string, any>)[ input.dataKey ]; } // Also check in taskCreationData for backward compatibility if (execution.taskCreationData && input.dataKey === 'taskCreationData') { return execution.taskCreationData; } throw new Error( `Data key '${input.dataKey}' not found in execution context`, ); } // Return full execution context return { executionContext: execution.executionContext, taskCreationData: execution.taskCreationData, executionState: execution.executionState, }; } /** * Update execution context * Used by product-manager workflow to update context after task updates */ async updateExecutionContext(input: { executionId: string; contextUpdates: Record<string, any>; }): Promise<any> { const execution = await this.workflowExecution.getExecutionById( input.executionId, ); // Merge context updates with existing context const currentContext = execution.executionContext && typeof execution.executionContext === 'object' && execution.executionContext !== null ? (execution.executionContext as Record<string, any>) : {}; const updatedContext = { ...currentContext, ...input.contextUpdates, }; const updatedExecution = await this.workflowExecution.updateExecution( input.executionId, { executionContext: updatedContext, }, ); return { success: true, updatedContext: updatedExecution.executionContext, executionId: input.executionId, }; } /** * Update execution state */ async updateExecution( input: WorkflowExecutionInput, ): Promise<ExecutionResult> { this.validateInput(input, 'update'); const execution = await this.workflowExecution.updateExecution( input.executionId!, // Safe after validation input.updateData || {}, ); const nextActions = await this.dataEnricher.getNextStepsForExecution( execution.id, ); const progressMatrix = this.dataEnricher.calculateProgressMetrics(execution); return { execution, progressMatrix, nextActions, }; } /** * Complete execution */ async completeExecution( input: WorkflowExecutionInput, ): Promise<ExecutionResult> { this.validateInput(input, 'complete'); const execution = await this.workflowExecution.completeExecution( input.executionId!, // Safe after validation ); const completionSummary = this.analytics.generateCompletionSummary(execution); const finalRecommendations = this.analytics.getFinalRecommendations(); return { execution, completionSummary, finalRecommendations, }; } /** * Get active executions with summary */ async getActiveExecutions(): Promise<ExecutionsSummary> { const executions = await this.workflowExecution.getActiveExecutions(); return { executions, summary: { total: executions.length, byRole: this.analytics.groupExecutionsByRole(executions), progressOverview: this.analytics.calculateOverallProgress(executions), }, }; } }