@exaudeus/workrail 0.1.5 → 0.1.7

package/README.md

@@ -3,7 +3,7 @@
 > **Transform chaotic AI interactions into structured, reliable workflows**
 
 [![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.org)
-[![Version](https://img.shields.io/badge/version-0.1.0-blue)]()
+[![Version](https://img.shields.io/badge/version-0.2.0-blue)]()
 
 ---
 
@@ -123,6 +123,15 @@ WorkRail supports powerful iteration patterns for complex tasks:
 
 Perfect for batch operations, retries, polling, and iterative refinement.
 
+### 🚀 v0.2.0: Optimized Loop Execution
+
+- **60-80% smaller context** after first iteration
+- **Progressive disclosure** pattern for loop information
+- **Native function DSL** to reduce duplication
+- **Automatic empty loop detection** and skipping
+
+See [Loop Optimization Guide](docs/features/loop-optimization.md) for details.
+
 ---
 
 ## 📖 Quick Example

package/dist/application/services/loop-context-optimizer.d.ts

@@ -0,0 +1,8 @@
+import { EnhancedContext, OptimizedLoopContext, LoopPhaseReference, LoopStep } from '../../types/workflow-types';
+import { ILoopContextOptimizer } from '../../types/loop-context-optimizer';
+export declare class LoopContextOptimizer implements ILoopContextOptimizer {
+    optimizeLoopContext(context: EnhancedContext, iteration: number): OptimizedLoopContext;
+    createPhaseReference(loopStep: LoopStep): LoopPhaseReference;
+    hasLoopItems(context: EnhancedContext, loopStep: LoopStep): boolean;
+    stripLoopMetadata(context: EnhancedContext): OptimizedLoopContext;
+}

package/dist/application/services/loop-context-optimizer.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopContextOptimizer = void 0;
+class LoopContextOptimizer {
+    optimizeLoopContext(context, iteration) {
+        if (!context._currentLoop) {
+            throw new Error('Cannot optimize context without active loop');
+        }
+        const { loopId, loopStep } = context._currentLoop;
+        const isFirstIteration = iteration === 0;
+        const optimizedContext = {
+            ...context,
+            _currentLoop: {
+                loopId,
+                loopType: loopStep.loop.type,
+                iteration,
+                isFirstIteration
+            }
+        };
+        if (!isFirstIteration && optimizedContext._currentLoop) {
+            optimizedContext._currentLoop.phaseReference = this.createPhaseReference(loopStep);
+            return this.stripLoopMetadata(optimizedContext);
+        }
+        return optimizedContext;
+    }
+    createPhaseReference(loopStep) {
+        const reference = {
+            loopId: loopStep.id,
+            phaseTitle: loopStep.title,
+            totalSteps: Array.isArray(loopStep.body) ? loopStep.body.length : 1
+        };
+        if (loopStep.functionDefinitions && loopStep.functionDefinitions.length > 0) {
+            reference.functionDefinitions = loopStep.functionDefinitions;
+        }
+        return reference;
+    }
+    hasLoopItems(context, loopStep) {
+        const { loop } = loopStep;
+        switch (loop.type) {
+            case 'forEach':
+                if (loop.items) {
+                    const items = context[loop.items];
+                    return Array.isArray(items) && items.length > 0;
+                }
+                return false;
+            case 'for':
+                const count = typeof loop.count === 'number'
+                    ? loop.count
+                    : (loop.count ? context[loop.count] : 0);
+                return count > 0;
+            case 'while':
+            case 'until':
+                return true;
+            default:
+                return false;
+        }
+    }
+    stripLoopMetadata(context) {
+        let optimizedContext;
+        if ('loopType' in (context._currentLoop || {})) {
+            optimizedContext = context;
+        }
+        else if (context._currentLoop) {
+            const { loopId, loopStep } = context._currentLoop;
+            const iteration = context._loopState?.[loopId]?.iteration || 0;
+            optimizedContext = {
+                ...context,
+                _currentLoop: {
+                    loopId,
+                    loopType: loopStep.loop.type,
+                    iteration,
+                    isFirstIteration: iteration === 0
+                }
+            };
+        }
+        else {
+            return context;
+        }
+        const strippedContext = { ...optimizedContext };
+        if (strippedContext._currentLoop?.loopType === 'forEach') {
+            const loopState = strippedContext._loopState;
+            if (loopState) {
+                Object.keys(loopState).forEach(loopId => {
+                    const state = loopState[loopId];
+                    if (state.items && Array.isArray(state.items)) {
+                        const currentIndex = state.index || 0;
+                        if (currentIndex < state.items.length) {
+                            state.items = [state.items[currentIndex]];
+                            state.index = 0;
+                        }
+                    }
+                });
+            }
+        }
+        const keysToCheck = Object.keys(strippedContext);
+        keysToCheck.forEach(key => {
+            if (key.startsWith('_'))
+                return;
+            const value = strippedContext[key];
+            if (Array.isArray(value) && value.length > 10) {
+                const currentLoop = strippedContext._currentLoop;
+                if (currentLoop?.loopType === 'forEach') {
+                    const loopState = strippedContext._loopState?.[currentLoop.loopId];
+                    if (loopState?.items === value) {
+                        return;
+                    }
+                }
+                delete strippedContext[key];
+            }
+        });
+        return strippedContext;
+    }
+}
+exports.LoopContextOptimizer = LoopContextOptimizer;

package/dist/application/services/loop-execution-context.d.ts

@@ -1,4 +1,4 @@
-import { LoopConfig, LoopState, EnhancedContext } from '../../types/workflow-types';
+import { LoopConfig, LoopState, EnhancedContext, OptimizedLoopContext, LoopPhaseReference, LoopStep } from '../../types/workflow-types';
 import { ConditionContext } from '../../utils/condition-evaluator';
 export declare class LoopExecutionContext {
     private loopId;
@@ -10,9 +10,14 @@ export declare class LoopExecutionContext {
     getCurrentState(): LoopState[string];
     shouldContinue(context: ConditionContext): boolean;
     initializeForEach(context: ConditionContext): void;
-    injectVariables(context: ConditionContext): EnhancedContext;
     private resolveCount;
     private addWarning;
     getLoopId(): string;
     getLoopConfig(): LoopConfig;
+    getMinimalContext(context: ConditionContext): OptimizedLoopContext;
+    getPhaseReference(loopStep: LoopStep): LoopPhaseReference;
+    injectVariables(context: ConditionContext, minimal?: boolean): EnhancedContext | OptimizedLoopContext;
+    private injectVariablesFull;
+    isFirstIteration(): boolean;
+    isEmpty(context: ConditionContext): boolean;
 }

package/dist/application/services/loop-execution-context.js

@@ -68,7 +68,72 @@ class LoopExecutionContext {
             }
         }
     }
-    injectVariables(context) {
+    resolveCount(context) {
+        if (this.loopConfig.type !== 'for' || !this.loopConfig.count) {
+            return 0;
+        }
+        if (typeof this.loopConfig.count === 'number') {
+            return this.loopConfig.count;
+        }
+        const count = context[this.loopConfig.count];
+        if (typeof count === 'number') {
+            return count;
+        }
+        this.addWarning(`Invalid count value for 'for' loop: ${this.loopConfig.count}`);
+        return 0;
+    }
+    addWarning(message) {
+        if (!this.state.warnings) {
+            this.state.warnings = [];
+        }
+        this.state.warnings.push(message);
+    }
+    getLoopId() {
+        return this.loopId;
+    }
+    getLoopConfig() {
+        return { ...this.loopConfig };
+    }
+    getMinimalContext(context) {
+        const optimizedContext = {
+            ...context,
+            _loopState: {
+                ...context._loopState,
+                [this.loopId]: this.getCurrentState()
+            },
+            _currentLoop: {
+                loopId: this.loopId,
+                loopType: this.loopConfig.type,
+                iteration: this.state.iteration,
+                isFirstIteration: false
+            }
+        };
+        if (this.loopConfig.type === 'forEach' && this.state.items) {
+            const index = this.state.index || 0;
+            const itemVar = this.loopConfig.itemVar || 'currentItem';
+            const indexVar = this.loopConfig.indexVar || 'currentIndex';
+            optimizedContext[itemVar] = this.state.items[index];
+            optimizedContext[indexVar] = index;
+        }
+        const iterationVar = this.loopConfig.iterationVar || 'currentIteration';
+        optimizedContext[iterationVar] = this.state.iteration + 1;
+        return optimizedContext;
+    }
+    getPhaseReference(loopStep) {
+        return {
+            loopId: this.loopId,
+            phaseTitle: loopStep.title,
+            totalSteps: Array.isArray(loopStep.body) ? loopStep.body.length : 1,
+            functionDefinitions: loopStep.functionDefinitions
+        };
+    }
+    injectVariables(context, minimal = false) {
+        if (minimal) {
+            return this.getMinimalContext(context);
+        }
+        return this.injectVariablesFull(context);
+    }
+    injectVariablesFull(context) {
         const enhancements = {
             _loopState: {
                 ...context._loopState,
@@ -97,31 +162,27 @@ class LoopExecutionContext {
         }
         return { ...context, ...enhancements };
     }
-    resolveCount(context) {
-        if (this.loopConfig.type !== 'for' || !this.loopConfig.count) {
-            return 0;
-        }
-        if (typeof this.loopConfig.count === 'number') {
-            return this.loopConfig.count;
-        }
-        const count = context[this.loopConfig.count];
-        if (typeof count === 'number') {
-            return count;
-        }
-        this.addWarning(`Invalid count value for 'for' loop: ${this.loopConfig.count}`);
-        return 0;
+    isFirstIteration() {
+        return this.state.iteration === 0;
     }
-    addWarning(message) {
-        if (!this.state.warnings) {
-            this.state.warnings = [];
+    isEmpty(context) {
+        switch (this.loopConfig.type) {
+            case 'forEach':
+                return !this.state.items || this.state.items.length === 0;
+            case 'for':
+                const count = this.resolveCount(context);
+                return count <= 0;
+            case 'while':
+                return this.loopConfig.condition
+                    ? !(0, condition_evaluator_1.evaluateCondition)(this.loopConfig.condition, context)
+                    : true;
+            case 'until':
+                return this.loopConfig.condition
+                    ? (0, condition_evaluator_1.evaluateCondition)(this.loopConfig.condition, context)
+                    : true;
+            default:
+                return false;
         }
-        this.state.warnings.push(message);
-    }
-    getLoopId() {
-        return this.loopId;
-    }
-    getLoopConfig() {
-        return { ...this.loopConfig };
     }
 }
 exports.LoopExecutionContext = LoopExecutionContext;

package/dist/application/services/workflow-service.d.ts

@@ -18,11 +18,13 @@ import { IWorkflowStorage } from '../../types/storage';
 import { ConditionContext } from '../../utils/condition-evaluator';
 import { ValidationEngine } from './validation-engine';
 import { EnhancedContext } from '../../types/workflow-types';
+import { ILoopContextOptimizer } from '../../types/loop-context-optimizer';
 export declare class DefaultWorkflowService implements WorkflowService {
     private readonly storage;
     private readonly validationEngine;
+    private readonly loopContextOptimizer?;
     private loopStepResolver;
-    constructor(storage?: IWorkflowStorage, validationEngine?: ValidationEngine);
+    constructor(storage?: IWorkflowStorage, validationEngine?: ValidationEngine, loopContextOptimizer?: ILoopContextOptimizer | undefined);
     listWorkflowSummaries(): Promise<WorkflowSummary[]>;
     getWorkflowById(id: string): Promise<Workflow | null>;
     getNextStep(workflowId: string, completedSteps: string[], context?: ConditionContext): Promise<{

package/dist/application/services/workflow-service.js

@@ -11,9 +11,10 @@ const loop_step_resolver_1 = require("./loop-step-resolver");
 const context_size_1 = require("../../utils/context-size");
 const context_optimizer_1 = require("./context-optimizer");
 class DefaultWorkflowService {
-    constructor(storage = (0, storage_1.createDefaultWorkflowStorage)(), validationEngine = new validation_engine_1.ValidationEngine()) {
+    constructor(storage = (0, storage_1.createDefaultWorkflowStorage)(), validationEngine = new validation_engine_1.ValidationEngine(), loopContextOptimizer) {
         this.storage = storage;
         this.validationEngine = validationEngine;
+        this.loopContextOptimizer = loopContextOptimizer;
         this.loopStepResolver = new loop_step_resolver_1.LoopStepResolver();
     }
     async listWorkflowSummaries() {
@@ -56,15 +57,26 @@ class DefaultWorkflowService {
             if (loopContext.shouldContinue(context)) {
                 const bodyStep = this.loopStepResolver.resolveLoopBody(workflow, loopStep.body, loopStep.id);
                 if (!Array.isArray(bodyStep)) {
-                    const loopEnhancedContext = loopContext.injectVariables(context);
-                    const loopSizeCheck = (0, context_size_1.checkContextSize)(loopEnhancedContext);
+                    const isFirst = loopContext.isFirstIteration();
+                    if (isFirst && loopContext.isEmpty(context)) {
+                        const skipContext = context_optimizer_1.ContextOptimizer.createEnhancedContext(context, completed);
+                        delete skipContext._currentLoop;
+                        const nextStep = await this.getNextStep(workflow.id, completed, skipContext);
+                        return nextStep;
+                    }
+                    const useMinimal = !isFirst && !!this.loopContextOptimizer;
+                    const loopEnhancedContext = loopContext.injectVariables(context, useMinimal);
+                    const optimizedContext = useMinimal && this.loopContextOptimizer
+                        ? this.loopContextOptimizer.stripLoopMetadata(loopEnhancedContext)
+                        : loopEnhancedContext;
+                    const loopSizeCheck = (0, context_size_1.checkContextSize)(optimizedContext);
                     if (loopSizeCheck.isError) {
                         throw new Error(`Context size (${Math.round(loopSizeCheck.sizeBytes / 1024)}KB) exceeds maximum allowed size (256KB) during loop execution`);
                     }
                     return {
                         step: bodyStep,
                         guidance: {
-                            prompt: this.buildStepPrompt(bodyStep, loopContext)
+                            prompt: this.buildStepPrompt(bodyStep, loopContext, useMinimal)
                         },
                         isComplete: false,
                         context: loopSizeCheck.context
@@ -81,15 +93,26 @@ class DefaultWorkflowService {
                         return true;
                     });
                     if (uncompletedBodyStep) {
-                        const loopEnhancedContext = loopContext.injectVariables(context);
-                        const loopSizeCheck = (0, context_size_1.checkContextSize)(loopEnhancedContext);
+                        const isFirst = loopContext.isFirstIteration();
+                        if (isFirst && loopContext.isEmpty(context)) {
+                            const skipContext = context_optimizer_1.ContextOptimizer.createEnhancedContext(context, completed);
+                            delete skipContext._currentLoop;
+                            const nextStep = await this.getNextStep(workflow.id, completed, skipContext);
+                            return nextStep;
+                        }
+                        const useMinimal = !isFirst && !!this.loopContextOptimizer;
+                        const loopEnhancedContext = loopContext.injectVariables(context, useMinimal);
+                        const optimizedContext = useMinimal && this.loopContextOptimizer
+                            ? this.loopContextOptimizer.stripLoopMetadata(loopEnhancedContext)
+                            : loopEnhancedContext;
+                        const loopSizeCheck = (0, context_size_1.checkContextSize)(optimizedContext);
                         if (loopSizeCheck.isError) {
                             throw new Error(`Context size (${Math.round(loopSizeCheck.sizeBytes / 1024)}KB) exceeds maximum allowed size (256KB) during loop execution`);
                         }
                         return {
                             step: uncompletedBodyStep,
                             guidance: {
-                                prompt: this.buildStepPrompt(uncompletedBodyStep, loopContext)
+                                prompt: this.buildStepPrompt(uncompletedBodyStep, loopContext, useMinimal)
                             },
                             isComplete: false,
                             context: loopSizeCheck.context
@@ -180,7 +203,7 @@ class DefaultWorkflowService {
             context: enhancedContext
         };
     }
-    buildStepPrompt(step, loopContext) {
+    buildStepPrompt(step, loopContext, useMinimal = false) {
         let stepGuidance = '';
         if (step.guidance && step.guidance.length > 0) {
             const guidanceHeader = '## Step Guidance';
@@ -193,10 +216,18 @@ class DefaultWorkflowService {
         }
         if (loopContext) {
             const state = loopContext.getCurrentState();
-            finalPrompt += `\n\n## Loop Context\n- Iteration: ${state.iteration + 1}`;
-            if (state.items) {
-                finalPrompt += `\n- Total Items: ${state.items.length}`;
-                finalPrompt += `\n- Current Index: ${state.index}`;
+            if (useMinimal && this.loopContextOptimizer) {
+                finalPrompt += `\n\n## Loop Context\n- Iteration: ${state.iteration + 1}`;
+                if (!loopContext.isFirstIteration()) {
+                    finalPrompt += '\n\n_Note: Refer to the phase overview provided in the first iteration for overall context._';
+                }
+            }
+            else {
+                finalPrompt += `\n\n## Loop Context\n- Iteration: ${state.iteration + 1}`;
+                if (state.items) {
+                    finalPrompt += `\n- Total Items: ${state.items.length}`;
+                    finalPrompt += `\n- Current Index: ${state.index}`;
+                }
             }
         }
         return finalPrompt;

package/dist/container.d.ts

@@ -2,9 +2,11 @@ import { WorkflowService } from './application/services/workflow-service.js';
 import { ValidationEngine } from './application/services/validation-engine.js';
 import { IWorkflowStorage } from './types/storage.js';
 import { WorkflowLookupServer } from './types/server.js';
+import { ILoopContextOptimizer } from './types/loop-context-optimizer.js';
 export interface AppContainer {
     storage: IWorkflowStorage;
     validationEngine: ValidationEngine;
+    loopContextOptimizer: ILoopContextOptimizer;
     workflowService: WorkflowService;
     server: WorkflowLookupServer;
 }

package/dist/container.js

@@ -5,14 +5,17 @@ const storage_js_1 = require("./infrastructure/storage/storage.js");
 const workflow_service_js_1 = require("./application/services/workflow-service.js");
 const validation_engine_js_1 = require("./application/services/validation-engine.js");
 const server_js_1 = require("./infrastructure/rpc/server.js");
+const loop_context_optimizer_js_1 = require("./application/services/loop-context-optimizer.js");
 function createAppContainer(overrides = {}) {
     const storage = overrides.storage ?? (0, storage_js_1.createDefaultWorkflowStorage)();
     const validationEngine = overrides.validationEngine ?? new validation_engine_js_1.ValidationEngine();
-    const workflowService = overrides.workflowService ?? new workflow_service_js_1.DefaultWorkflowService(storage, validationEngine);
+    const loopContextOptimizer = overrides.loopContextOptimizer ?? new loop_context_optimizer_js_1.LoopContextOptimizer();
+    const workflowService = overrides.workflowService ?? new workflow_service_js_1.DefaultWorkflowService(storage, validationEngine, loopContextOptimizer);
     const server = overrides.server ?? (0, server_js_1.createWorkflowLookupServer)(workflowService);
     return {
         storage,
         validationEngine,
+        loopContextOptimizer,
         workflowService,
         server
     };

package/dist/types/loop-context-optimizer.d.ts

@@ -0,0 +1,7 @@
+import { EnhancedContext, OptimizedLoopContext, LoopPhaseReference, LoopStep } from './workflow-types';
+export interface ILoopContextOptimizer {
+    optimizeLoopContext(context: EnhancedContext, iteration: number): OptimizedLoopContext;
+    createPhaseReference(loopStep: LoopStep): LoopPhaseReference;
+    hasLoopItems(context: EnhancedContext, loopStep: LoopStep): boolean;
+    stripLoopMetadata(context: EnhancedContext): OptimizedLoopContext;
+}

package/dist/types/loop-context-optimizer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/workflow-types.d.ts

@@ -8,6 +8,7 @@ export interface Workflow {
     clarificationPrompts?: string[];
     steps: (WorkflowStep | LoopStep)[];
     metaGuidance?: string[];
+    functionDefinitions?: FunctionDefinition[];
 }
 export interface WorkflowStep {
     id: string;
@@ -18,6 +19,8 @@ export interface WorkflowStep {
     askForFiles?: boolean;
     requireConfirmation?: boolean;
     runCondition?: object;
+    functionDefinitions?: FunctionDefinition[];
+    functionReferences?: string[];
 }
 export interface LoopStep extends WorkflowStep {
     type: 'loop';
@@ -56,7 +59,36 @@ export interface EnhancedContext extends ConditionContext {
         loopStep: LoopStep;
     };
 }
+export interface OptimizedLoopContext extends ConditionContext {
+    _loopState?: LoopState;
+    _warnings?: {
+        loops?: {
+            [loopId: string]: string[];
+        };
+    };
+    _contextSize?: number;
+    _currentLoop?: {
+        loopId: string;
+        loopType: 'for' | 'forEach' | 'while' | 'until';
+        iteration: number;
+        isFirstIteration: boolean;
+        phaseReference?: LoopPhaseReference;
+    };
+    _loopPhaseReference?: LoopPhaseReference;
+}
+export interface LoopPhaseReference {
+    loopId: string;
+    phaseTitle: string;
+    totalSteps: number;
+    functionDefinitions?: FunctionDefinition[];
+}
+export interface FunctionDefinition {
+    name: string;
+    definition: string;
+    scope?: 'workflow' | 'loop' | 'step';
+}
 export declare function isLoopStep(step: WorkflowStep | LoopStep): step is LoopStep;
+export declare function isFirstLoopIteration(context: EnhancedContext | OptimizedLoopContext): boolean;
 export interface WorkflowValidationResult {
     valid: boolean;
     errors: WorkflowValidationError[];

package/dist/types/workflow-types.js

@@ -1,6 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isLoopStep = isLoopStep;
+exports.isFirstLoopIteration = isFirstLoopIteration;
 function isLoopStep(step) {
     return 'type' in step && step.type === 'loop';
 }
+function isFirstLoopIteration(context) {
+    if ('isFirstIteration' in (context._currentLoop || {})) {
+        return context._currentLoop?.isFirstIteration === true;
+    }
+    const loopState = context._loopState;
+    if (loopState) {
+        const currentLoopId = context._currentLoop?.loopId;
+        if (currentLoopId && loopState[currentLoopId]) {
+            return loopState[currentLoopId].iteration === 0;
+        }
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "MCP server for structured workflow orchestration and step-by-step task guidance",
   "license": "MIT",
   "bin": {
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "release": "./scripts/release.sh",
+    "release": "bash -c './scripts/release.sh'",
     "dev": "npm run build && node dist/mcp-server.js",
     "prepare": "npm run build",
     "watch": "tsc --watch"

package/spec/workflow.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://workflowlookup.io/schemas/workflow/v0.1.0",
+  "$id": "https://workflowlookup.io/schemas/workflow/v0.2.0",
   "title": "Workflow Schema",
   "description": "Schema for defining workflows in the Workflow Orchestration System",
   "type": "object",
@@ -74,6 +74,32 @@
         "maxLength": 256
       },
       "uniqueItems": true
+    },
+    "functionDefinitions": {
+      "type": "array",
+      "description": "Function definitions for reducing duplication. Agents can reference these definitions to understand repeated patterns without full expansion.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+            "description": "Function name following JavaScript identifier rules"
+          },
+          "definition": {
+            "type": "string",
+            "description": "The function definition explaining what it does"
+          },
+          "scope": {
+            "type": "string",
+            "enum": ["workflow", "loop", "step"],
+            "description": "Scope where this function is available"
+          }
+        },
+        "required": ["name", "definition"],
+        "additionalProperties": false
+      },
+      "uniqueItems": true
     }
   },
   "required": [
@@ -91,6 +117,27 @@
       "minLength": 3,
       "maxLength": 64
     },
+    "functionDefinition": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+          "description": "Function name following JavaScript identifier rules"
+        },
+        "definition": {
+          "type": "string",
+          "description": "The function definition explaining what it does"
+        },
+        "scope": {
+          "type": "string",
+          "enum": ["workflow", "loop", "step"],
+          "description": "Scope where this function is available"
+        }
+      },
+      "required": ["name", "definition"],
+      "additionalProperties": false
+    },
     "standardStep": {
       "type": "object",
       "properties": {
@@ -153,6 +200,21 @@
               "$ref": "#/$defs/validationComposition"
             }
           ]
+        },
+        "functionDefinitions": {
+          "type": "array",
+          "description": "Function definitions specific to this step. Agents can reference these for understanding step-specific patterns.",
+          "items": {
+            "$ref": "#/$defs/functionDefinition"
+          }
+        },
+        "functionReferences": {
+          "type": "array",
+          "description": "References to functions defined at workflow or loop level that this step uses.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*\\(\\)$"
+          }
         }
       },
       "required": [
@@ -198,6 +260,13 @@
             }
           ]
         },
+        "functionDefinitions": {
+          "type": "array",
+          "description": "Function definitions specific to this loop. Available to all steps within the loop body.",
+          "items": {
+            "$ref": "#/$defs/functionDefinition"
+          }
+        },
         "requireConfirmation": {
           "$ref": "#/$defs/confirmationRule"
         },

package/workflows/coding-task-workflow-with-loops.json

@@ -404,15 +404,14 @@
             "requireConfirmation": false
         },
         {
-            "id": "phase-6-prepare-steps",
-            "title": "Phase 6 Preparation: Extract Implementation Steps",
-            "prompt": "Before starting the implementation loop, extract the discrete implementation steps from the approved `implementation_plan.md` into a context array.\n\n**Your task:**\n1. Read the implementation_plan.md\n2. Identify each discrete, actionable step from the Implementation Strategy section\n3. Create an array called `implementationSteps` where each item has:\n   - `title`: Brief title of the step\n   - `description`: Detailed description of what to do\n   - `outputs`: Expected outputs or changes\n\n**Example format:**\n```json\n[\n  {\n    \"title\": \"Create user authentication module\",\n    \"description\": \"Implement the authentication service with login/logout methods\",\n    \"outputs\": \"auth.service.ts file with login() and logout() methods\"\n  },\n  {\n    \"title\": \"Add validation middleware\",\n    \"description\": \"Create middleware to validate user credentials\",\n    \"outputs\": \"validation.middleware.ts with credential validation logic\"\n  }\n]\n```\n\n**Set this array as the `implementationSteps` context variable for the loop to consume.**",
-            "agentRole": "You are preparing the implementation phase by extracting actionable steps from the plan into a structured format for iteration.",
+            "id": "phase-6-count-steps",
+            "title": "Phase 6 Preparation: Count Implementation Steps",
+            "prompt": "Before starting the implementation loop, count the discrete implementation steps in the approved `implementation_plan.md`.\n\n**Your task:**\n1. Read the implementation_plan.md\n2. Count each discrete, actionable step from the Implementation Strategy section\n3. Set `totalImplementationSteps` to the count (e.g., 8)\n\n**What counts as a step:**\n- Each bullet point or numbered item that represents a concrete implementation task\n- Each item that would result in a code change or file creation\n- Each item that could be a logical git commit\n\n**Example:**\nIf the plan has:\n- Create user model\n- Add authentication service\n- Implement validation\n- Write tests\n\nThen set `totalImplementationSteps` = 4\n\n**IMPORTANT:** Only count, don't extract or store the steps. You'll read them directly from the plan during implementation.",
+            "agentRole": "You are preparing the implementation phase by counting the steps to enable progress tracking.",
             "guidance": [
-                "Each step should be a logical, committable chunk of work",
-                "Steps should be ordered as they appear in the plan",
-                "Include enough detail for clear implementation",
-                "This enables the loop to iterate over a concrete list"
+                "Count only actionable implementation steps",
+                "Don't include meta-tasks like 'review' or 'document'",
+                "This enables progress tracking without bloating context"
             ],
             "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
             "requireConfirmation": false
@@ -423,22 +422,20 @@
             "title": "Phase 6: Iterative Implementation Loop (PREP -> IMPLEMENT -> VERIFY)",
             "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
             "loop": {
-                "type": "forEach",
-                "items": "implementationSteps",
-                "itemVar": "currentStep",
-                "indexVar": "stepIndex",
-                "maxIterations": 25,
-                "iterationVar": "stepIteration"
+                "type": "for",
+                "count": "totalImplementationSteps",
+                "indexVar": "currentStepNumber",
+                "maxIterations": 25
             },
             "body": [
                 {
                     "id": "phase-6-prep",
-                    "title": "PREP: Prepare for {{currentStep.title}}",
-                    "prompt": "**PREPARATION PHASE for Step {{stepIndex + 1}}/{{implementationSteps.length}}: {{currentStep.title}}**\n\nBefore implementing this step, you must first PREPARE:\n\n1. **Review the step description**: {{currentStep.description}}\n2. **Confirm prerequisites**: Verify the previous step (if any) was completed correctly\n3. **Validate current state**: Ensure the plan for this step is still valid in the current codebase\n4. **List requirements**: Identify all required inputs, files, or dependencies\n\n**BRANCH SETUP (first iteration only):** If this is the first implementation step ({{stepIndex}} === 0):\n- Check git availability with 'git status'\n- If available, create feature branch: 'git checkout -b wip-[unique-task-id]'\n- Track the featureBranch variable for later use\n- If git unavailable: Skip branching, log in CONTEXT.md\n\n**Do not proceed if anything is unclear or missing.**",
+                    "title": "PREP: Prepare for Step {{currentStepNumber + 1}}",
+                    "prompt": "**PREPARATION PHASE for Step {{currentStepNumber + 1}}/{{totalImplementationSteps}}**\n\nBefore implementing this step, you must first PREPARE:\n\n1. **Read implementation_plan.md** and locate step #{{currentStepNumber + 1}}\n2. **Extract step details**: Note the title, description, and expected outputs\n3. **Confirm prerequisites**: Verify the previous step (if any) was completed correctly\n4. **Validate current state**: Ensure the plan for this step is still valid in the current codebase\n5. **List requirements**: Identify all required inputs, files, or dependencies\n\n**BRANCH SETUP (first iteration only):** If this is the first implementation step ({{currentStepNumber}} === 0):\n- Check git availability with 'git status'\n- If available, create feature branch: 'git checkout -b wip-[unique-task-id]'\n- Track the featureBranch variable for later use\n- If git unavailable: Skip branching, log in CONTEXT.md\n\n**CRITICAL CONTEXT OPTIMIZATION:**\nWhen calling workflow_next after this step, send ONLY:\n- currentStepNumber and totalImplementationSteps\n- Any NEW variables you created (like featureBranch)\n- DO NOT send: arrays, plans, _loopState, _currentLoop, unchanged data\n\n**Do not proceed if anything is unclear or missing.**",
                     "agentRole": "You are preparing to implement a specific step from the plan. Be meticulous in verifying all prerequisites are met before proceeding.",
                     "guidance": [
-                        "This is step {{stepIndex + 1}} of {{implementationSteps.length}} total implementation steps",
-                        "Current iteration: {{stepIteration}} (for tracking purposes)",
+                        "This is step {{currentStepNumber + 1}} of {{totalImplementationSteps}} total implementation steps",
+                        "Read the step directly from implementation_plan.md",
                         "Focus only on preparation - implementation comes next",
                         "If this is the first step, handle git branch setup"
                     ],
@@ -446,8 +443,8 @@
                 },
                 {
                     "id": "phase-6-implement",
-                    "title": "IMPLEMENT: Execute {{currentStep.title}}",
-                    "prompt": "**IMPLEMENTATION PHASE for {{currentStep.title}}**\n\nNow implement this specific step:\n\n**Step Details:**\n- Title: {{currentStep.title}}\n- Description: {{currentStep.description}}\n- Expected Outputs: {{currentStep.outputs}}\n\n**Remember:** applyUserRules() and matchPatterns() throughout.\n\n**Instructions:**\n1. Focus only on this single step\n2. useTools() to make code changes\n3. Follow quality standards\n4. Adapt to unexpected discoveries\n5. createFile() for ALL code changes\n\n**Progress Tracking:**\n- This is step {{stepIndex + 1}} of {{implementationSteps.length}}\n- Total steps executed so far: {{stepIteration}}\n- If total steps > 20, pause for user intervention\n\n**CONTEXT UPDATES:** If this is every 3rd step ({{stepIteration}} % 3 === 0):\n- Update CONTEXT.md\n- addResumptionJson(phase-6-implement)\n- updateDecisionLog()\n- List files modified with line ranges",
+                    "title": "IMPLEMENT: Execute Step {{currentStepNumber + 1}}",
+                    "prompt": "**IMPLEMENTATION PHASE for Step {{currentStepNumber + 1}}/{{totalImplementationSteps}}**\n\nNow implement the step you just prepared for:\n\n**Instructions:**\n1. Re-read step #{{currentStepNumber + 1}} from implementation_plan.md\n2. Focus only on this single step\n3. useTools() to make code changes\n4. Follow quality standards\n5. Adapt to unexpected discoveries\n6. createFile() for ALL code changes\n\n**Remember:** applyUserRules() and matchPatterns() throughout.\n\n**Progress Tracking:**\n- This is step {{currentStepNumber + 1}} of {{totalImplementationSteps}}\n- If we've done > 20 steps total, pause for user intervention\n\n**CONTEXT UPDATES:** If this is every 3rd step ({{currentStepNumber + 1}} % 3 === 0):\n- Update CONTEXT.md\n- addResumptionJson(phase-6-implement)\n- updateDecisionLog()\n- List files modified with line ranges\n\n**CONTEXT OPTIMIZATION for workflow_next:**\nSend ONLY: currentStepNumber, totalImplementationSteps, filesCreated (new), any other NEW data\nDO NOT send: arrays, plans, _loopState, unchanged fields",
                     "agentRole": "You are implementing a specific step from the approved plan. Focus on precise execution while maintaining code quality.",
                     "guidance": [
                         "Implement only what this step requires",
@@ -458,8 +455,8 @@
                 },
                 {
                     "id": "phase-6-verify",
-                    "title": "VERIFY: Validate {{currentStep.title}}",
-                    "prompt": "**VERIFICATION PHASE for {{currentStep.title}}**\n\nVerify the implementation is complete and correct:\n\n**Required:** verifyImplementation()\n\n**COMMIT Decision (if all passes):**\n- checkAutomation(commit)\n- gitCommit(type, scope: description)\n- If git unavailable: Log in CONTEXT.md\n\n**FAILURE PROTOCOL:** If verification fails after 2 attempts:\n1. Do not try a third time\n2. Fall back to alternative tools\n3. updateDecisionLog() with failure details\n4. Present summary and recommendations\n5. Set 'verificationFailed' context variable to true",
+                    "title": "VERIFY: Validate Step {{currentStepNumber + 1}}",
+                    "prompt": "**VERIFICATION PHASE for Step {{currentStepNumber + 1}}/{{totalImplementationSteps}}**\n\nVerify the implementation is complete and correct:\n\n**Required:** verifyImplementation()\n\n**COMMIT Decision (if all passes):**\n- checkAutomation(commit)\n- gitCommit(type, scope: description)\n- If git unavailable: Log in CONTEXT.md\n\n**FAILURE PROTOCOL:** If verification fails after 2 attempts:\n1. Do not try a third time\n2. Fall back to alternative tools\n3. updateDecisionLog() with failure details\n4. Present summary and recommendations\n5. Set 'verificationFailed' context variable to true\n\n**CONTEXT OPTIMIZATION:**\nFor workflow_next, send ONLY what changed: currentStepNumber, verificationResult, verificationFailed (if true)\nNEVER send back the full context!",
                     "agentRole": "You are verifying the implementation meets all quality standards. Be thorough but respect failure bounds.",
                     "guidance": [
                         "All three verification steps must pass",

package/workflows/exploration-workflow.json

@@ -1,8 +1,8 @@
 {
     "id": "exploration-workflow",
     "name": "Comprehensive Adaptive Exploration Workflow",
-    "version": "0.0.1",
-    "description": "A sophisticated workflow for systematically exploring and determining optimal approaches to accomplish tasks or solve problems. Features adaptive complexity paths, intelligent clarification, devil's advocate analysis, automation levels, failure bounds, and comprehensive documentation for production-ready research.",
+    "version": "0.1.0",
+    "description": "An enterprise-grade exploration workflow featuring multi-phase research loops with saturation detection, evidence-based validation, diverse solution generation, and adversarial challenge patterns. Adapts methodology based on domain type (technical/business/creative) while ensuring depth through triangulation, confidence scoring, and systematic quality gates.",
     "clarificationPrompts": [
         "What specific task, problem, or question do you need to explore?",
         "What constraints or requirements should guide the exploration? (time, budget, technical, etc.)",
@@ -13,22 +13,26 @@
     ],
     "preconditions": [
         "User has a clear task, problem, or question to explore",
-        "Agent has access to research tools (web search, codebase search, etc.)",
         "User can provide initial context, constraints, or requirements",
         "Agent can maintain context variables throughout the workflow"
     ],
     "metaGuidance": [
-        "This workflow follows ANALYZE -> CLARIFY -> RESEARCH -> EVALUATE -> RECOMMEND pattern with dynamic re-triage capabilities.",
-        "Automation levels (Low/Medium/High) control confirmation requirements to balance thoroughness with efficiency.",
-        "Dynamic re-triage allows complexity upgrades and safe downgrades based on new insights from research.",
-        "Always base recommendations on evidence from multiple sources with quantified evaluations.",
-        "Context documentation is maintained throughout to enable seamless handoffs between chat sessions.",
-        "Failure bounds prevent analysis paralysis: word limits (2000), step tracking (>15), and escalation protocols.",
-        "Include trade-offs, pros, cons, and alternatives for transparency and informed decision-making.",
-        "Document all sources, methodology, and reasoning for reproducibility and validation.",
-        "Limit exploration depth based on complexity to prevent resource waste while ensuring thoroughness.",
-        "Human approval is required after Devil's Advocate review and before final recommendations.",
-        "Always provide actionable next steps and implementation guidance, not just theoretical analysis."
+        "FUNCTION DEFINITIONS: fun trackEvidence(source, grade) = 'Add to context.evidenceLog[] with {source, grade, timestamp}. Grade: High (peer-reviewed/official), Medium (expert/established), Low (anecdotal/emerging)'",
+        "fun checkSaturation() = 'Calculate novelty score: (new_insights / total_insights). If <0.1 for last 3 iterations, set context.saturationReached=true'",
+        "fun generateSolution(index, approach) = 'Create solution in context.solutions[index] with {approach, evidence, confidence, tradeoffs, risks}'",
+        "fun calculateConfidence() = '(0.4 × evidenceStrength) + (0.3 × triangulation) + (0.2 × sourceDiversity) + (0.1 × recency). Result in context.confidenceScores[]'",
+        "fun triggerDeepDive() = 'If confidence < 0.7 OR evidenceGaps.length > 0 OR contradictions found, set context.needsDeepDive=true'",
+        "CONTEXT ARCHITECTURE: Track explorationDomain (technical/business/creative), solutions[], evidenceLog[], confidenceScores[], researchPhases[], currentPhase, saturationMetrics, contradictions[], evidenceGaps[]",
+        "EVIDENCE STANDARDS: Minimum 3 sources per key claim (from available sources: web, agent knowledge, user environment), at least 1 contrasting perspective required, formal grading using adapted RAND scale (High/Medium/Limited)",
+        "SOLUTION DIVERSITY: Generate minimum 5 solutions: Quick/Simple, Thorough/Proven, Creative/Novel, Optimal/Balanced, Contrarian/Alternative",
+        "VALIDATION GATES: Phase transitions require validation; solutions need confidence ≥0.7; evidence must pass triangulation check",
+        "This workflow follows ANALYZE -> CLARIFY -> RESEARCH (loop) -> GENERATE (divergent) -> EVALUATE (convergent) -> CHALLENGE -> RECOMMEND pattern.",
+        "Automation levels (Low/Medium/High) control confirmation requirements. High: auto-proceed if confidence >0.8",
+        "Dynamic re-triage allows complexity upgrades and safe downgrades based on research insights and saturation metrics.",
+        "TOOL ADAPTATION: Workflow adapts to available tools. Check MCPs and adjust strategy based on what's available.",
+        "Context documentation updated at phase boundaries. Include function definitions for resumption.",
+        "Failure bounds: word limits (2000), max iterations (5 per loop), total steps (>20 triggers review).",
+        "Human approval required after adversarial challenge and before final recommendations."
     ],
     "steps": [
         {
@@ -46,6 +50,32 @@
             ],
             "requireConfirmation": true
         },
+        {
+            "id": "phase-0a-user-context",
+            "title": "Phase 0a: User Context & Preferences Check",
+            "prompt": "**GATHER USER CONTEXT**: Before proceeding, check for relevant user preferences, rules, and past decisions that should influence this exploration.\n\n**CHECK FOR:**\n1. **User Rules/Preferences**: Use memory tools to check for:\n   - Organizational standards or guidelines\n   - Preferred technologies or approaches\n   - Constraints or requirements from past decisions\n   - Specific methodologies or frameworks to follow/avoid\n\n2. **Environmental Context**:\n   - Current tech stack (if technical)\n   - Business constraints (budget, timeline, resources)\n   - Regulatory or compliance requirements\n   - Team capabilities and preferences\n\n3. **Historical Decisions**:\n   - Similar problems solved before\n   - Lessons learned from past explorations\n   - Established patterns to follow\n\n**ACTIONS:**\n1. Query memory/knowledge base for relevant rules\n2. Set context.userRules[] with applicable preferences\n3. Set context.constraints[] with hard requirements\n4. Note any past decisions that create precedent\n\nIf no specific rules found, note that and proceed with general best practices.",
+            "agentRole": "You are gathering user-specific context that will influence all subsequent exploration phases. Your role is to ensure the exploration aligns with the user's established preferences and constraints.",
+            "guidance": [
+                "This context check happens for all complexity levels",
+                "Rules and preferences should influence solution generation",
+                "Document which rules apply and why",
+                "If conflicts exist between rules and task requirements, flag for clarification"
+            ],
+            "requireConfirmation": false
+        },
+        {
+            "id": "phase-0b-domain-classification",
+            "title": "Phase 0b: Domain Classification & Tool Selection",
+            "prompt": "**CLASSIFY EXPLORATION DOMAIN**: Based on the task, classify the exploration into one of these domains:\n\n**Technical Domain:**\n- Code implementation, architecture design, debugging\n- Tool selection, framework comparison, performance optimization\n- Primary tools: codebase_search, grep_search (if available), technical documentation\n- Fallback: Agent's technical knowledge, architectural patterns from training\n\n**Business Domain:**\n- Strategy formulation, market analysis, process improvement\n- Cost-benefit analysis, resource allocation, risk assessment\n- Primary tools: web_search for market data (if available), case studies, industry reports\n- Fallback: Business frameworks and principles from agent knowledge\n\n**Creative Domain:**\n- Content creation, design systems, user experience\n- Innovation, brainstorming, conceptual development\n- Primary tools: web_search for inspiration (if available), trend analysis\n- Fallback: Creative methodologies and patterns from agent training\n\n**IMPLEMENT:**\n1. Analyze task characteristics\n2. Set context.explorationDomain = 'technical' | 'business' | 'creative'\n3. Set context.primaryTools[] based on domain\n4. Set context.evaluationCriteria[] appropriate for domain\n\n**DOMAIN-SPECIFIC SUCCESS METRICS:**\n- Technical: Feasibility, performance, maintainability, scalability\n- Business: ROI, time-to-value, risk mitigation, strategic alignment\n- Creative: Innovation, user satisfaction, aesthetics, differentiation",
+            "agentRole": "You are a domain classification specialist who identifies the nature of exploration tasks and configures appropriate methodologies, tools, and success criteria for each domain type.",
+            "guidance": [
+                "Some tasks may span domains - choose primary domain",
+                "This classification affects tool selection and evaluation criteria",
+                "Document reasoning for domain choice",
+                "Set domain-specific context variables for later steps"
+            ],
+            "requireConfirmation": false
+        },
         {
             "id": "phase-1-simple-lookup",
             "runCondition": {"var": "explorationComplexity", "equals": "Simple"},
@@ -152,6 +182,97 @@
                 ]
             }
         },
+        {
+            "id": "phase-2c-iterative-research-loop",
+            "type": "loop",
+            "title": "Phase 2c: Multi-Phase Deep Research with Saturation Detection",
+            "runCondition": {"var": "explorationComplexity", "not_equals": "Simple"},
+            "loop": {
+                "type": "for",
+                "count": 5,
+                "maxIterations": 5,
+                "iterationVar": "researchPhase"
+            },
+            "body": [
+                {
+                    "id": "research-phase-1-broad",
+                    "title": "Research Phase 1/5: Broad Scan",
+                    "runCondition": { "var": "researchPhase", "equals": 1 },
+                    "prompt": "**OBJECTIVE**: Cast a wide net to map the solution landscape, identify key themes, and find conflicting viewpoints.",
+                    "agentRole": "Systematic Researcher: Broad Scan Specialist",
+                    "guidance": [
+                        "Use multiple search strategies (e.g., 'how to [task]', 'alternatives to [tool]').",
+                        "Identify 3-5 high-level solution categories.",
+                        "Note sources that directly conflict with each other.",
+                        "ACTIONS: Update context.evidenceLog[], context.broadScanThemes[], context.contradictions[]"
+                    ]
+                },
+                {
+                    "id": "research-phase-2-deep-dive",
+                    "title": "Research Phase 2/5: Deep Dive",
+                    "runCondition": { "var": "researchPhase", "equals": 2 },
+                    "prompt": "**OBJECTIVE**: Focus on the most promising themes from the broad scan. Investigate technical details, find implementation examples, and assess feasibility.",
+                    "agentRole": "Systematic Researcher: Deep Dive Analyst",
+                    "guidance": [
+                        "Focus on the themes in context.broadScanThemes[].",
+                        "Find specific, real-world implementation examples or case studies.",
+                        "Assess complexity, dependencies, and requirements for each.",
+                        "ACTIONS: Update context.evidenceLog[], context.deepDiveFindings[]"
+                    ]
+                },
+                {
+                    "id": "research-phase-3-contrarian",
+                    "title": "Research Phase 3/5: Contrarian Research",
+                    "runCondition": { "var": "researchPhase", "equals": 3 },
+                    "prompt": "**OBJECTIVE**: Actively seek out opposing viewpoints, failure cases, and critiques of the promising solutions. The goal is to challenge assumptions.",
+                    "agentRole": "Systematic Researcher: Devil's Advocate",
+                    "guidance": [
+                        "Search for '[solution] problems', '[approach] failures', 'why not use [tool]'.",
+                        "Identify hidden assumptions in the mainstream approaches.",
+                        "Look for entirely different paradigms that were missed.",
+                        "ACTIONS: Update context.evidenceLog[], context.contrarianEvidence[]"
+                    ]
+                },
+                {
+                    "id": "research-phase-4-synthesis",
+                    "title": "Research Phase 4/5: Evidence Synthesis",
+                    "runCondition": { "var": "researchPhase", "equals": 4 },
+                    "prompt": "**OBJECTIVE**: Consolidate all findings. Resolve contradictions, identify patterns, and build a coherent narrative of the solution landscape.",
+                    "agentRole": "Systematic Researcher: Synthesizer",
+                    "guidance": [
+                        "Review evidence from all previous phases.",
+                        "Where sources conflict, try to understand the reason for the disagreement.",
+                        "Build a framework or matrix to compare the approaches.",
+                        "ACTIONS: Update context.synthesisFramework, context.evidenceGaps[]"
+                    ]
+                },
+                {
+                    "id": "research-phase-5-gap-filling",
+                    "title": "Research Phase 5/5: Gap Filling & Closure",
+                    "runCondition": { "var": "researchPhase", "equals": 5 },
+                    "prompt": "**OBJECTIVE**: Address the specific, critical unknowns identified during synthesis. Verify key assumptions and prepare for solution generation.",
+                    "agentRole": "Systematic Researcher: Finisher",
+                    "guidance": [
+                        "Focus only on the critical gaps listed in context.evidenceGaps[].",
+                        "Perform targeted searches to answer these specific questions.",
+                        "This is the final research step. The goal is to be 'done', not perfect.",
+                        "ACTIONS: Update context.evidenceLog[], set context.researchComplete = true"
+                    ]
+                },
+                {
+                    "id": "research-phase-validation",
+                    "title": "Validation: Research Quality Check",
+                    "prompt": "**OBJECTIVE**: After each research phase, perform a quick quality check.",
+                    "agentRole": "Quality Analyst",
+                    "guidance": [
+                        "EVIDENCE CHECK: Have we gathered at least 3 new sources in this phase? (unless it was gap-filling).",
+                        "QUALITY CHECK: Is there at least one 'High' or 'Medium' grade source?",
+                        "SATURATION CHECK: Use checkSaturation() to assess if we are still gathering novel information. If not, we can consider exiting the loop early by setting context.researchComplete = true.",
+                        "ACTIONS: Update context.qualityMetrics[]"
+                    ]
+                }
+            ]
+        },
         {
             "id": "phase-3-context-documentation",
             "runCondition": {"var": "explorationComplexity", "not_equals": "Simple"},
@@ -168,11 +289,71 @@
             ],
             "requireConfirmation": false
         },
+        {
+            "id": "phase-3a-prepare-solutions",
+            "title": "Phase 3a: Prepare Solution Generation",
+            "runCondition": {"var": "explorationComplexity", "not_equals": "Simple"},
+            "prompt": "**PREPARE SOLUTION GENERATION**\n\nBased on your research findings, prepare for systematic solution generation:\n\n**SETUP TASKS:**\n1. Review research synthesis from Phase 2c\n2. Identify top solution categories/approaches\n3. Create solution generation framework\n\n**CREATE SOLUTION APPROACHES ARRAY:**\nSet context.solutionApproaches with these 5 types:\n```json\n[\n  {\"type\": \"Quick/Simple\", \"focus\": \"Minimal time, proven approaches, immediate value\"},\n  {\"type\": \"Thorough/Proven\", \"focus\": \"Best practices, comprehensive, long-term sustainability\"},\n  {\"type\": \"Creative/Novel\", \"focus\": \"Innovation, emerging tech, competitive advantage\"},\n  {\"type\": \"Optimal/Balanced\", \"focus\": \"Best trade-offs, practical yet forward-thinking\"},\n  {\"type\": \"Contrarian/Alternative\", \"focus\": \"Challenge assumptions, overlooked approaches\"}\n]\n```\n\n**Also set:**\n- context.solutionCriteria[] from research findings\n- context.evaluationFramework for comparing solutions\n- context.userConstraints from Phase 0a\n\n**This enables the next loop to generate each solution type systematically.**",
+            "agentRole": "You are preparing the solution generation phase by creating a structured framework based on research findings.",
+            "guidance": [
+                "This step makes the loop cleaner by preparing the array",
+                "Each solution type should address different user needs",
+                "Framework should incorporate research insights"
+            ],
+            "requireConfirmation": false
+        },
+        {
+            "id": "phase-3b-solution-generation-loop",
+            "type": "loop",
+            "title": "Phase 3b: Diverse Solution Portfolio Generation",
+            "runCondition": {"var": "explorationComplexity", "not_equals": "Simple"},
+            "loop": {
+                "type": "forEach",
+                "items": "solutionApproaches",
+                "itemVar": "approach",
+                "indexVar": "solutionIndex",
+                "maxIterations": 5
+            },
+            "body": [
+                {
+                    "id": "generate-solution",
+                    "title": "Generate {{approach.type}} Solution ({{solutionIndex + 1}}/5)",
+                    "prompt": "**GENERATE SOLUTION: {{approach.type}}**\n\n**Focus for this solution type**: {{approach.focus}}\n\n**DIVERGENT THINKING MODE - NO JUDGMENT**\nYou are in pure generation mode. Do NOT evaluate, compare, or judge this solution against others. Focus solely on creating a complete solution that embodies the {{approach.type}} approach.\n\n**SOLUTION REQUIREMENTS:**\n1. Generate a solution that embodies the {{approach.type}} approach\n2. Base it on evidence from all research phases\n3. Make it genuinely different from other solutions (not just variations)\n4. DEFER ALL JUDGMENT - no scoring, ranking, or comparison\n\n**INCORPORATE USER CONTEXT:**\n- Apply all relevant rules from context.userRules[]\n- Respect constraints from context.constraints[]\n- Align with organizational standards and preferences\n- Consider environment-specific factors\n\n**SOLUTION STRUCTURE:**\n1. **Core Approach**: Clear description (what makes this {{approach.type}}?)\n2. **Implementation Path**: 3-5 key steps to execute\n3. **Evidence Base**: Which research findings support this approach?\n4. **Key Features**: What distinguishes this approach?\n5. **Resource Requirements**: What's needed to implement?\n6. **Success Indicators**: Observable outcomes when working\n\n**NO EVALUATION ELEMENTS:**\n- Do NOT include confidence scores\n- Do NOT compare to other solutions\n- Do NOT rank or judge quality\n- Simply generate and document\n\n**ACTIONS:**\n- generateSolution({{solutionIndex}}, '{{approach.type}}')\n- Store complete solution in context.solutions[{{solutionIndex}}]\n- Track which evidence supports this approach",
+                    "agentRole": "You are in DIVERGENT THINKING mode, generating the {{approach.type}} solution. Focus on creation without judgment. Draw from research to build a complete solution.",
+                    "guidance": [
+                        "DIVERGENT PHASE: Generate without evaluating or comparing",
+                        "Each solution should be genuinely different, not just variations",
+                        "Ground each solution in evidence from research phases",
+                        "Align with user rules and preferences from Phase 0a",
+                        "Include enough detail to be actionable",
+                        "Reference specific sources from evidenceLog",
+                        "If a solution conflicts with user rules, note it factually without judgment",
+                        "DEFER ALL EVALUATION until Phase 4"
+                    ],
+                    "hasValidation": true,
+                    "validationCriteria": {
+                        "and": [
+                            {
+                                "type": "contains",
+                                "value": "Evidence:",
+                                "message": "Must include evidence section"
+                            },
+                            {
+                                "type": "contains",
+                                "value": "Key Features:",
+                                "message": "Must describe distinguishing features"
+                            }
+                        ]
+                    },
+                    "requireConfirmation": false
+                }
+            ]
+        },
         {
             "id": "phase-4-option-evaluation",
             "runCondition": {"var": "explorationComplexity", "not_equals": "Simple"},
-            "title": "Phase 4: Comprehensive Option Evaluation & Ranking",
-            "prompt": "**PREP**: Define evaluation criteria based on clarified requirements, constraints, and priorities.\n\n**IMPLEMENT**: \n1. Create weighted scoring matrix with 4-6 evaluation criteria based on clarifications\n2. Score each option quantitatively (1-10 scale) with detailed rationale\n3. Calculate weighted scores and rank options\n4. Perform sensitivity analysis on key criteria weights\n5. Identify decision breakpoints and scenario dependencies\n6. Document evaluation methodology and assumptions\n\n**VERIFY**: Ensure evaluation is objective, comprehensive, and incorporates all clarified priorities.",
+            "title": "Phase 4: CONVERGENT THINKING - Option Evaluation & Ranking",
+            "prompt": "**TRANSITION TO CONVERGENT THINKING MODE**\n\nThe divergent generation phase is complete. Now shift to analytical, convergent thinking to systematically evaluate all solutions.\n\n**CONVERGENT THINKING PRINCIPLES:**\n- This is NOW the time for judgment and comparison\n- Apply critical analysis to all generated solutions\n- Use evidence-based evaluation criteria\n- Be rigorous and systematic\n\n**PREP**: Define evaluation criteria based on clarified requirements, constraints, and priorities.\n\n**IMPLEMENT**: \n1. Create weighted scoring matrix with 4-6 evaluation criteria based on clarifications\n2. Score each option quantitatively (1-10 scale) with detailed rationale\n3. Calculate weighted scores and rank options\n4. Perform sensitivity analysis on key criteria weights\n5. Identify decision breakpoints and scenario dependencies\n6. Document evaluation methodology and assumptions\n\n**VERIFY**: Ensure evaluation is objective, comprehensive, and incorporates all clarified priorities.",
             "agentRole": "You are an objective decision analyst expert in multi-criteria evaluation and quantitative assessment. Your expertise lies in translating qualitative factors into structured, defensible evaluations.",
             "guidance": [
                 "Use at least 4-6 evaluation criteria based on clarifications",
@@ -200,7 +381,7 @@
             "id": "phase-4b-devil-advocate-review",
             "runCondition": {"var": "explorationComplexity", "not_equals": "Simple"},
             "title": "Phase 4b: Devil's Advocate Evaluation Review",
-            "prompt": "Perform a 'devil's advocate' review of your option evaluation from Phase 4. The objective is to rigorously stress-test your analysis and strengthen the final recommendation. Your critique must be balanced and evidence-based.\n\nAnalyze the evaluation through these lenses, citing specific evidence:\n\n1. **Hidden Assumptions**: What assumptions does your evaluation make about user context, implementation reality, or future conditions that might be incorrect?\n2. **Evaluation Bias**: Are there systematic biases in your scoring? Do criteria weights reflect stated priorities? Are any important factors missing?\n3. **Option Blind Spots**: What alternatives or hybrid approaches might you have overlooked? Are there emerging options not fully considered?\n4. **Risk Assessment**: What are the biggest risks of the top-ranked option? What could go wrong that isn't reflected in the scoring?\n5. **Evaluation Strengths**: What aspects of your analysis are most robust and reliable? What gives you confidence in the methodology?\n\nConclude with balanced summary. If you found issues, provide concrete suggestions for improving the evaluation. **Set the confidenceScore variable to your 1-10 rating** for the evaluation quality *if* suggestions are implemented.",
+            "prompt": "Perform a rigorous 'devil's advocate' review of your solutions and evaluation. This is a mandatory adversarial self-challenge to prevent overconfidence and blind spots.\n\n**STRUCTURED ADVERSARIAL ANALYSIS:**\n\n1. **Evidence Challenge**: For each solution's top 3 claims:\n   - Is the evidence truly supporting this claim?\n   - Are there contradicting sources we dismissed?\n   - What evidence grade did we assign vs. what it deserves?\n\n2. **Hidden Failure Modes**: For the top-ranked solution:\n   - What could cause catastrophic failure?\n   - What assumptions could be completely wrong?\n   - What context changes would invalidate this approach?\n\n3. **Overlooked Alternatives**:\n   - What hybrid approaches could combine solution strengths?\n   - What completely different paradigm did we miss?\n   - Are we solving the right problem?\n\n4. **Bias Detection**:\n   - Did we favor familiar over novel?\n   - Did recent sources overshadow established wisdom?\n   - Did domain bias affect our evaluation?\n\n5. **Confidence Calibration**:\n   - Where are we overconfident?\n   - What unknowns are we treating as knowns?\n   - calculateConfidence() with penalty for identified weaknesses\n\n**OUTPUT REQUIREMENTS:**\n- Identify at least 3 significant concerns\n- Propose specific remedies for each\n- Re-calculate confidence scores\n- Set context.confidenceScore (1-10) for overall analysis quality\n- Set context.criticalIssues[] with must-address items\n\ntriggerDeepDive() if confidence drops below 0.7",
             "agentRole": "You are a skeptical but fair senior research analyst with 15+ years of experience in strategic decision analysis. Your role is to identify potential blind spots, biases, and overlooked factors in evaluation methodologies. You excel at constructive criticism that strengthens analysis rather than destroys it.",
             "guidance": [
                 "This is critical thinking step to find weaknesses in your own analysis",