@exaudeus/workrail 0.1.6 → 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.6",
+  "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",