@exaudeus/workrail 3.28.0 → 3.29.0

package/docs/reference/agent-context-cleaner-snippet.md

@@ -0,0 +1,94 @@
+# Context Cleaner for Agents
+
+## Quick Copy-Paste Function
+
+Add this to your agent implementation to automatically clean context before sending to `workflow_next`:
+
+```typescript
+function cleanContextForWorkflowNext(
+  fullContext: any,
+  modifiedFields: string[] = []
+): any {
+  // Start with only essential fields
+  const cleanContext: any = {};
+  
+  // Always include current loop variables if present
+  if (fullContext.currentStep) {
+    cleanContext.currentStep = fullContext.currentStep;
+  }
+  if (typeof fullContext.stepIndex === 'number') {
+    cleanContext.stepIndex = fullContext.stepIndex;
+  }
+  if (typeof fullContext.stepIteration === 'number') {
+    cleanContext.stepIteration = fullContext.stepIteration;
+  }
+  
+  // Add any fields the agent explicitly modified
+  modifiedFields.forEach(field => {
+    if (field in fullContext) {
+      cleanContext[field] = fullContext[field];
+    }
+  });
+  
+  // NEVER include these
+  const blocklist = [
+    'implementationSteps',
+    '_loopState',
+    '_currentLoop',
+    '_contextSize',
+    '_warnings',
+    'userRules',
+    'taskDescription'
+  ];
+  
+  // Remove any blocklisted fields that snuck in
+  blocklist.forEach(field => {
+    delete cleanContext[field];
+  });
+  
+  return cleanContext;
+}
+```
+
+## Usage Example
+
+```typescript
+// During your workflow execution:
+const response = await workflow_next({
+  workflowId: "coding-task-workflow-agentic",
+  completedSteps: ["phase-6-prep"],
+  context: cleanContextForWorkflowNext(fullContext, [
+    'featureBranch',      // I created this
+    'verificationResult', // I added this
+    'filesCreated'        // I added this
+  ])
+});
+```
+
+## Even Simpler: Manual Approach
+
+If you're manually calling workflow_next, just remember:
+
+```json
+{
+  "workflowId": "...",
+  "completedSteps": [...],
+  "context": {
+    // Only 3-5 fields max!
+    "currentStep": {...},
+    "stepIndex": 1,
+    "stepIteration": 2,
+    "yourNewData": "..."
+  }
+}
+```
+
+## Validation Check
+
+Before sending, ask yourself:
+- Is my context < 5KB? 
+- Did I remove all arrays I didn't modify?   
+- Did I remove all `_` fields? 
+- Am I only sending what I changed? 
+
+If yes to all, you're doing it right!

package/docs/reference/agent-context-guidance.md

@@ -0,0 +1,140 @@
+# Agent Context Optimization Guide
+
+## The Problem
+
+Agents currently send back the ENTIRE context (15-20KB) on every `workflow_next` call, even though they only need to send what changed.
+
+## The Solution: Send Only What Changed
+
+###  DON'T DO THIS (Current Behavior)
+
+```json
+{
+  "workflowId": "coding-task-workflow-agentic",
+  "completedSteps": ["phase-6-prep"],
+  "context": {
+    // All 17KB of data including:
+    "taskDescription": "...",
+    "userRules": "...", 
+    "implementationSteps": [/* all 14 items */],
+    "_loopState": {/* entire state */},
+    "_currentLoop": {/* full definition */},
+    // ... everything else unchanged
+  }
+}
+```
+
+###  DO THIS INSTEAD (Optimized)
+
+```json
+{
+  "workflowId": "coding-task-workflow-agentic", 
+  "completedSteps": ["phase-6-prep"],
+  "context": {
+    // Only what you need or changed:
+    "currentStep": {
+      "title": "Core Contracts...",
+      "description": "...",
+      "outputs": "..."
+    },
+    "stepIndex": 1,
+    "stepIteration": 2,
+    "featureBranch": "feat/new-feature", // NEW data you created
+    // That's it! 3KB instead of 17KB
+  }
+}
+```
+
+## Rules for Context Management
+
+### 1. Never Echo Arrays
+
+```json
+//  BAD: Sending back unchanged array
+"implementationSteps": [/* all 14 items */]
+
+//  GOOD: Only send current item
+"currentStep": { /* just this one */ }
+```
+
+### 2. Skip Internal Fields
+
+Never send these back:
+- `_loopState`
+- `_currentLoop` 
+- `_contextSize`
+- `_warnings`
+
+### 3. Only Send What You Modified
+
+```json
+// If you created a new variable:
+"verificationResult": true
+
+// If you modified existing data:
+"confidenceScore": 10  // was 9
+
+// DON'T send unchanged data:
+// "taskDescription": "..." // unchanged, don't send
+```
+
+## Specific Examples
+
+### For Loop Steps
+
+```json
+{
+  "workflowId": "coding-task-workflow-agentic",
+  "completedSteps": ["phase-6-prep", "phase-6-implement"],
+  "context": {
+    "currentStep": { /* current */ },
+    "stepIndex": 2,
+    "stepIteration": 3,
+    "filesCreated": ["new-file.ts"], // NEW data
+    "testsPassed": true              // NEW data
+  }
+}
+```
+
+### For Clarification Steps
+
+```json
+{
+  "workflowId": "coding-task-workflow-agentic",
+  "completedSteps": ["phase-2-informed-clarification"],
+  "context": {
+    "clarifiedRequirements": "Updated requirements...", // MODIFIED
+    "confidenceScore": 8                                // MODIFIED
+    // Don't send taskDescription, userRules, etc.
+  }
+}
+```
+
+## Why This Matters
+
+- **80-90% smaller requests** (3KB vs 17KB)
+- **Faster processing**
+- **Lower costs**
+- **Better performance**
+
+## Implementation Checklist
+
+When calling `workflow_next`:
+
+1. [ ] Remove all arrays you didn't modify
+2. [ ] Remove all `_` prefixed fields
+3. [ ] Only include fields you created or changed
+4. [ ] For loops: only send current item, not all items
+5. [ ] Check: Is my context < 5KB? (Good!)
+
+## Testing Your Implementation
+
+Before:
+```
+Context size: 17,104 bytes
+```
+
+After following this guide:
+```
+Context size: 2,048 bytes (88% reduction!)
+```

package/docs/reference/context-optimization.md

@@ -0,0 +1,284 @@
+# Context Optimization Guide for Workflows
+
+## Overview
+
+The MCP server now includes automatic context optimization instructions that help AI agents reduce the size of context sent with each `workflow_next` call. This guide explains how workflows can
+use this feature effectively.
+
+## Understanding the Stateless Nature
+
+The MCP server is **completely stateless**. This means:
+- It doesn't remember previous requests
+- Every `workflow_next` call must include ALL necessary data
+- Missing required variables will cause failures
+
+## What Gets Optimized
+
+### Before Optimization
+```json
+{
+      "workflowId": "coding-task-workflow-agentic",
+  "completedSteps": ["phase-1", "phase-2"],
+  "context": {
+    // 17KB of accumulated state including:
+    "taskDescription": "...",           // 2KB
+    "implementationSteps": [...],        // 10KB array
+    "_loopState": {...},                 // 3KB
+    "analysisResults": {...},            // 1KB
+    "userRules": [...],                  // 500B
+    "existingCode": "...",              // 500B
+    // ... and much more
+  }
+}
+```
+
+### After Optimization
+```json
+{
+      "workflowId": "coding-task-workflow-agentic",
+  "completedSteps": ["phase-1", "phase-2", "phase-3"],
+  "context": {
+    // Only what's needed for the next step:
+    "taskComplexity": "Medium",          // Used in conditions
+    "currentStepNumber": 3,              // Used in templates
+    "stepCompleted": true,               // New variable
+    "testResults": "passed"              // Modified variable
+    // Total: <2KB
+  }
+}
+```
+
+## Critical Rules for Context Preservation
+
+### 1. Variables in Conditions
+
+If a step has a `runCondition`, ALL referenced variables MUST be included:
+
+```json
+{
+  "id": "conditional-step",
+  "runCondition": {
+    "and": [
+      {"var": "taskComplexity", "equals": "Large"},
+      {"var": "needsReview", "equals": true}
+    ]
+  }
+}
+```
+
+**Required context:**
+```json
+{
+  "taskComplexity": "Large",
+  "needsReview": true
+}
+```
+
+### 2. Template Variables
+
+Any `{{variable}}` in prompts, titles, or guidance MUST be included:
+
+```json
+{
+  "id": "loop-step",
+  "title": "Step {{currentStepNumber}} of {{totalSteps}}",
+  "prompt": "Implement item {{currentItem.name}}"
+}
+```
+
+**Required context:**
+```json
+{
+  "currentStepNumber": 3,
+  "totalSteps": 10,
+  "currentItem": {"name": "User authentication"}
+}
+```
+
+### 3. Loop Variables
+
+When inside a loop, specific variables are injected and must be preserved:
+
+```json
+{
+  // For forEach loops:
+  "currentItem": {...},      // Current item being processed
+  "currentIndex": 2,         // Index in the array
+  "currentIteration": 3,     // 1-based iteration count
+  
+  // Only the active loop state:
+  "_loopState": {
+    "active-loop-id": {
+      "iteration": 2,
+      "index": 2
+    }
+  }
+}
+```
+
+## Best Practices for Workflow Design
+
+### 1. Avoid Large Array Storage
+
+ **Bad: Storing large arrays**
+```json
+{
+  "id": "prepare-implementation",
+  "prompt": "Extract all implementation steps into an array"
+  // Results in: implementationSteps: [30 items] = 15KB
+}
+```
+
+ **Good: Store count and read on-demand**
+```json
+{
+  "id": "count-steps",
+  "prompt": "Count the implementation steps in the plan"
+  // Results in: totalSteps: 30 = 4 bytes
+}
+```
+
+### 2. Use Explicit Variable Names
+
+Make it clear which variables are important:
+
+```json
+{
+  "id": "validation-step",
+  "prompt": "Validate the code. Set 'validationPassed' to true/false",
+  "guidance": ["Variable 'validationPassed' will be used in next step's condition"]
+}
+```
+
+### 3. Document Variable Dependencies
+
+Add guidance about what needs to be preserved:
+
+```json
+{
+  "id": "analysis-step",
+  "guidance": [
+    "Extract key findings into 'analysisResults'",
+    "This variable is needed until phase-5"
+  ]
+}
+```
+
+## Workflow-Specific Optimizations
+
+### 1. Coding Task Workflow
+
+The coding task workflow now includes explicit optimization instructions:
+
+```json
+{
+  "id": "phase-6-prep",
+  "prompt": "...\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"
+}
+```
+
+### 2. Custom Workflows
+
+You can add similar instructions to your workflows:
+
+```json
+{
+  "id": "data-processing",
+  "prompt": "Process the data...",
+  "guidance": [
+    "After processing, only send 'processingStatus' and 'errorCount'",
+    "The large 'rawData' array is no longer needed"
+  ]
+}
+```
+
+## Debugging Context Issues
+
+### Common Problems
+
+1. **Missing Condition Variable**
+   - Error: `Cannot read property 'X' of undefined`
+   - Fix: Ensure variable X is included in context
+
+2. **Missing Template Variable**
+   - Symptom: `{{variable}}` appears literally in output
+   - Fix: Include the variable in context
+
+3. **Loop State Lost**
+   - Symptom: Loop restarts or skips
+   - Fix: Preserve `_loopState[activeLoopId]`
+
+4. **Loop Count Variable Missing** 
+   - Symptom: Loop exits immediately, jumps to next major phase
+   - Error: "Invalid count value for 'for' loop: variableName"
+   - Fix: Ensure count variable (e.g., `totalImplementationSteps`) is preserved
+   - Common cause: Workflow step instructions override general template variable rules
+
+### Validation Checklist
+
+Before each `workflow_next` call, agents should verify:
+
+- [ ] `workflowId` is included
+- [ ] `completedSteps` array is complete
+- [ ] All condition variables are present
+- [ ] All template variables are included
+- [ ] Loop count variables are preserved (e.g., `totalImplementationSteps`)
+- [ ] New/modified variables are added
+- [ ] Active loop state is preserved
+- [ ] Context size is reasonable (<10KB)
+
+## Size Targets
+
+| Scenario | Target Size | Maximum |
+|----------|------------|---------|
+| Simple step | <1KB | 2KB |
+| With conditions | <2KB | 5KB |
+| Loop iteration | <3KB | 5KB |
+| Complex state | <5KB | 10KB |
+| Maximum allowed | - | 256KB |
+
+## Example: Complete Optimization Flow
+
+```typescript
+// Step 1: Agent receives response with optimization instructions
+const response = await workflow_next({
+  workflowId: "my-workflow",
+  completedSteps: ["step-1"],
+  context: fullContext // 15KB
+});
+
+// Step 2: Agent reads optimization requirements
+// Sees: "ALWAYS INCLUDE condition variables..."
+
+// Step 3: Agent analyzes next step requirements
+// Next step has: runCondition using 'status'
+// Next step has: "Review {{itemCount}} items"
+
+// Step 4: Agent sends optimized context
+const nextCall = await workflow_next({
+  workflowId: "my-workflow",
+  completedSteps: ["step-1", "step-2"],
+  context: {
+    // Required for condition:
+    status: "ready",
+    // Required for template:
+    itemCount: 5,
+    // New variable from this step:
+    reviewStarted: true
+    // Total: <1KB (vs 15KB)
+  }
+});
+```
+
+## Migration Guide
+
+For existing agents:
+1. Start logging context sizes
+2. Identify which variables are actually used
+3. Implement context filtering based on the requirements
+4. Test with reduced context
+5. Monitor for any missing variable errors
+
+## Summary
+
+The context optimization feature helps reduce token usage by 70-90% while maintaining full functionality. The key is understanding what the stateless server actually needs and sending only that data. When in doubt, err on the side of including data rather than breaking functionality.

package/docs/reference/example-workflow-repository-template/.github/workflows/validate.yml

@@ -0,0 +1,125 @@
+name: Validate Workflows
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install WorkRail
+        run: npm install -g workrail || echo "WorkRail not yet published, skipping validation"
+      
+      - name: Count workflows
+        id: count
+        run: |
+          count=$(ls -1 workflows/*.json 2>/dev/null | wc -l || echo 0)
+          echo "count=$count" >> $GITHUB_OUTPUT
+          echo "Found $count workflow(s)"
+      
+      - name: Validate workflow files
+        if: steps.count.outputs.count > 0
+        run: |
+          errors=0
+          for file in workflows/*.json; do
+            echo "Validating $file..."
+            
+            # Check if file exists and is readable
+            if [ ! -r "$file" ]; then
+              echo "❌ Cannot read file: $file"
+              errors=$((errors + 1))
+              continue
+            fi
+            
+            # Validate JSON syntax
+            if ! jq empty "$file" 2>/dev/null; then
+              echo "❌ Invalid JSON in $file"
+              errors=$((errors + 1))
+              continue
+            fi
+            
+            # Check required fields
+            if ! jq -e '.id' "$file" >/dev/null; then
+              echo "❌ Missing 'id' field in $file"
+              errors=$((errors + 1))
+            fi
+            
+            if ! jq -e '.name' "$file" >/dev/null; then
+              echo "❌ Missing 'name' field in $file"
+              errors=$((errors + 1))
+            fi
+            
+            if ! jq -e '.description' "$file" >/dev/null; then
+              echo "❌ Missing 'description' field in $file"
+              errors=$((errors + 1))
+            fi
+            
+            if ! jq -e '.version' "$file" >/dev/null; then
+              echo "❌ Missing 'version' field in $file"
+              errors=$((errors + 1))
+            fi
+            
+            if ! jq -e '.steps' "$file" >/dev/null; then
+              echo "❌ Missing 'steps' field in $file"
+              errors=$((errors + 1))
+            fi
+            
+            # Check filename matches workflow ID
+            workflow_id=$(jq -r '.id' "$file")
+            expected_filename="workflows/${workflow_id}.json"
+            if [ "$file" != "$expected_filename" ]; then
+              echo "⚠️  Warning: Workflow ID '$workflow_id' doesn't match filename '$file'"
+              echo "   Expected: $expected_filename"
+            fi
+            
+            echo "✅ $file is valid"
+          done
+          
+          if [ $errors -gt 0 ]; then
+            echo "❌ Found $errors error(s)"
+            exit 1
+          fi
+          
+          echo "✅ All workflows are valid"
+      
+      - name: Check for duplicate IDs
+        if: steps.count.outputs.count > 0
+        run: |
+          ids=$(jq -r '.id' workflows/*.json | sort)
+          duplicate_ids=$(echo "$ids" | uniq -d)
+          
+          if [ -n "$duplicate_ids" ]; then
+            echo "❌ Found duplicate workflow IDs:"
+            echo "$duplicate_ids"
+            exit 1
+          fi
+          
+          echo "✅ No duplicate workflow IDs found"
+      
+      - name: Generate workflow summary
+        if: steps.count.outputs.count > 0
+        run: |
+          echo "## Workflow Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| ID | Name | Version |" >> $GITHUB_STEP_SUMMARY
+          echo "|---|---|---|" >> $GITHUB_STEP_SUMMARY
+          
+          for file in workflows/*.json; do
+            id=$(jq -r '.id' "$file")
+            name=$(jq -r '.name' "$file")
+            version=$(jq -r '.version' "$file")
+            echo "| $id | $name | $version |" >> $GITHUB_STEP_SUMMARY
+          done
+