@exaudeus/workrail 0.1.7 → 0.1.9

package/README.md

@@ -86,15 +86,52 @@ Add to your agent's `config.json`:
 
 ---
 
+## 💾 Using Local Workflows (when configuring MCP via JSON)
+
+WorkRail will auto-discover workflows even when added to your agent via JSON config. It searches, in priority order:
+
+- User: `~/.workrail/workflows` (recommended)
+- Project: `./workflows` relative to the MCP process `cwd`
+- Custom: directories listed in `WORKFLOW_STORAGE_PATH` (colon-separated on macOS/Linux)
+
+Example agent config passing env and `cwd` so your local workflows are picked up:
+
+```json
+{
+  "mcpServers": {
+    "workrail": {
+      "command": "npx",
+      "args": ["-y", "@exaudeus/workrail"],
+      "env": {
+        "WORKFLOW_STORAGE_PATH": "/absolute/path/my-workflows:/absolute/path/shared-workflows"
+      },
+      "cwd": "/absolute/path/my-project"
+    }
+  }
+}
+```
+
+Quick tips:
+
+- Initialize your user dir once: `workrail init`
+- Validate a file: `workrail validate /abs/path/my-workflows/my-workflow.json`
+- List all discovered workflows: `workrail list`
+
+See also: `docs/workflow-management.md` for more details.
+
+---
+
 ## 📋 Available Workflows
 
 WorkRail comes with battle-tested workflows for common development tasks:
 
 ### 🔧 **Development Workflows**
-- **`coding-task-workflow`** - Comprehensive coding workflow with analysis, planning, implementation, and review
-- **`coding-task-workflow-with-loops`** - Enhanced version with iterative refinement loops
-- **`systematic-bug-investigation`** - Systematic debugging methodology that prevents jumping to conclusions
-- **`systemic-bug-investigation-with-loops`** - Enhanced debugging with iterative analysis loops
+- **`coding-task-workflow-with-loops`** - Enhanced coding workflow with iterative refinement loops, analysis, planning, implementation, and review *(Recommended)*
+- **`systematic-bug-investigation-with-loops`** - Enhanced debugging with iterative analysis loops and systematic methodology *(Recommended)*
+
+#### Deprecated Workflows
+- ~~**`coding-task-workflow`** - [DEPRECATED] Use `coding-task-workflow-with-loops` instead~~
+- ~~**`systematic-bug-investigation`** - [DEPRECATED] Use `systematic-bug-investigation-with-loops` instead~~
 
 ### 🚀 **Project Management**  
 - **`adaptive-ticket-creation`** - Create well-structured tickets with proper requirements

package/dist/application/app.d.ts

@@ -22,4 +22,9 @@ export declare const METHOD_NAMES: {
     readonly SHUTDOWN: "shutdown";
 };
 export type MethodName = typeof METHOD_NAMES[keyof typeof METHOD_NAMES];
-export declare function buildWorkflowApplication(workflowService: WorkflowService, validator?: MethodValidator): ApplicationMediator;
+export interface IApplicationMediator {
+    execute(method: string, params: any): Promise<any>;
+    register(method: string, handler: any): void;
+    setResponseValidator(fn: (method: string, result: any) => void): void;
+}
+export declare function buildWorkflowApplication(workflowService: WorkflowService, validator?: MethodValidator, enableOutputOptimization?: boolean): IApplicationMediator;

package/dist/application/app.js

@@ -71,6 +71,7 @@ const list_workflows_1 = require("./use-cases/list-workflows");
 const get_workflow_1 = require("./use-cases/get-workflow");
 const get_next_step_1 = require("./use-cases/get-next-step");
 const validate_step_output_1 = require("./use-cases/validate-step-output");
+const simple_output_decorator_1 = require("./decorators/simple-output-decorator");
 exports.METHOD_NAMES = {
     WORKFLOW_LIST: 'workflow_list',
     WORKFLOW_GET: 'workflow_get',
@@ -80,7 +81,7 @@ exports.METHOD_NAMES = {
     TOOLS_LIST: 'tools/list',
     SHUTDOWN: 'shutdown'
 };
-function buildWorkflowApplication(workflowService, validator = request_validator_1.requestValidator) {
+function buildWorkflowApplication(workflowService, validator = request_validator_1.requestValidator, enableOutputOptimization = true) {
     const app = new ApplicationMediator(validator);
     app.setResponseValidator((method, result) => response_validator_1.responseValidator.validate(method, result));
     const listWorkflowsUseCase = (0, list_workflows_1.createListWorkflows)(workflowService);
@@ -112,5 +113,8 @@ function buildWorkflowApplication(workflowService, validator = request_validator
         const { shutdownHandler } = await Promise.resolve().then(() => __importStar(require('../tools/mcp_shutdown')));
         return (await shutdownHandler({ id: 0, params, method: 'shutdown', jsonrpc: '2.0' })).result;
     });
+    if (enableOutputOptimization) {
+        return new simple_output_decorator_1.SimpleOutputDecorator(app);
+    }
     return app;
 }

package/dist/application/decorators/simple-output-decorator.d.ts

@@ -0,0 +1,8 @@
+import { IApplicationMediator } from '../app';
+export declare class SimpleOutputDecorator implements IApplicationMediator {
+    private readonly wrapped;
+    constructor(wrapped: IApplicationMediator);
+    execute(method: string, params: any): Promise<any>;
+    register(method: string, handler: any): void;
+    setResponseValidator(fn: (method: string, result: any) => void): void;
+}

package/dist/application/decorators/simple-output-decorator.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleOutputDecorator = void 0;
+const CONTEXT_OPTIMIZATION_TEXT = `
+
+**CONTEXT OPTIMIZATION REQUIREMENTS**:
+
+The MCP server is STATELESS. You MUST send required data with each request:
+
+**ALWAYS INCLUDE:**
+1. \`workflowId\` - Required for all calls
+2. \`completedSteps\` - Full array of completed step IDs
+3. **Condition Variables** - ANY variable used in step \`runCondition\` fields
+4. **Template Variables** - ANY variable referenced in {{templates}} in prompts/titles
+5. **Your New/Modified Variables** - Variables you created or changed in this step
+
+**CONDITIONALLY INCLUDE:**
+- **Loop Variables** (when in a loop): \`currentIteration\`, \`currentItem\`, \`currentIndex\`
+- **Active Loop State**: Only \`_loopState[currentLoopId]\` if currently in a loop
+- **Referenced Variables**: Any variable that future steps might need
+
+**NEVER INCLUDE:**
+- Large arrays that aren't being actively iterated (e.g., \`implementationSteps\` array)
+- Stale loop states from completed loops
+- Unreferenced historical data
+- Variables only used in completed steps
+
+**SIZE TARGETS:**
+- Normal steps: < 2KB
+- Loop iterations: < 5KB
+- Complex state: < 10KB
+
+**EXAMPLE - Loop Context:**
+\`\`\`json
+{
+  "workflowId": "coding-task-workflow",
+  "completedSteps": ["phase-1", "phase-2", "loop-step-1"],
+  "context": {
+    // Required: condition/template variables
+    "taskComplexity": "Medium",
+    "totalImplementationSteps": 8,
+    "currentStepNumber": 3,
+    
+    // Required: your changes
+    "stepCompleted": true,
+    "testResults": "passed",
+    
+    // Required: active loop state only
+    "_loopState": {
+      "phase-6-loop": { "iteration": 3 }
+    },
+    
+    // DON'T include:
+    // - implementationSteps: [...] // Large array
+    // - analysisResults: {...} // From phase 1
+    // - _loopState.oldLoop: {...} // Completed loop
+  }
+}
+\`\`\`
+
+**VALIDATION CHECK**: Before sending, verify you have ALL variables referenced in:
+- The next step's \`runCondition\`
+- Any {{variable}} in the next step's prompts
+- Variables needed for loop control`;
+class SimpleOutputDecorator {
+    constructor(wrapped) {
+        this.wrapped = wrapped;
+    }
+    async execute(method, params) {
+        const result = await this.wrapped.execute(method, params);
+        if (method === 'workflow_next' && result?.guidance?.prompt) {
+            return {
+                ...result,
+                guidance: {
+                    ...result.guidance,
+                    prompt: result.guidance.prompt + CONTEXT_OPTIMIZATION_TEXT
+                }
+            };
+        }
+        return result;
+    }
+    register(method, handler) {
+        this.wrapped.register(method, handler);
+    }
+    setResponseValidator(fn) {
+        this.wrapped.setResponseValidator(fn);
+    }
+}
+exports.SimpleOutputDecorator = SimpleOutputDecorator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "MCP server for structured workflow orchestration and step-by-step task guidance",
   "license": "MIT",
   "bin": {

package/workflows/coding-task-workflow.json

@@ -1,8 +1,8 @@
 {
     "id": "coding-task-workflow",
-    "name": "Excellent Adaptive Coding Workflow with Devil's Advocate Review",
+    "name": "[DEPRECATED] Excellent Adaptive Coding Workflow with Devil's Advocate Review",
     "version": "0.8.0",
-    "description": "Comprehensive AI coding workflow with bidirectional re-triage, deep analysis, intelligent clarification, devil's advocate review, automation levels, failure bounds, tool fallbacks, and context documentation for production-ready development.",
+    "description": "[DEPRECATED] This workflow has been superseded by 'coding-task-workflow-with-loops' which includes enhanced loop capabilities for better iterative development. Use 'coding-task-workflow-with-loops' for new projects. Comprehensive AI coding workflow with bidirectional re-triage, deep analysis, intelligent clarification, devil's advocate review, automation levels, failure bounds, tool fallbacks, and context documentation for production-ready development.",
 
     "preconditions": [
         "User has a clear task description (e.g., from Jira, a dev doc, or a BRD).",
@@ -11,6 +11,7 @@
         "Git repository is recommended for version control and commits (workflow degrades gracefully if unavailable)."
     ],
     "metaGuidance": [
+        "⚠️ DEPRECATION NOTICE: This workflow is deprecated. Use 'coding-task-workflow-with-loops' instead for enhanced iterative development capabilities with loop support.",
         "This workflow follows the ANALYZE -> CLARIFY -> PREP -> IMPLEMENT -> VERIFY pattern with bidirectional dynamic re-triage capabilities.",
         "Deep codebase analysis occurs early to inform intelligent requirements clarification and all subsequent planning phases.",
         "Dynamic re-triage allows complexity upgrades and safe downgrades based on new insights from analysis and clarifications.",

package/workflows/systemic-bug-investigation.json

@@ -1,8 +1,8 @@
 {
     "id": "systematic-bug-investigation",
-    "name": "Systematic Bug Investigation Workflow",
+    "name": "[DEPRECATED] Systematic Bug Investigation Workflow",
     "version": "1.0.0",
-    "description": "A comprehensive workflow for systematic bug and failing test investigation that prevents LLMs from jumping to conclusions. Enforces thorough evidence gathering, hypothesis formation, debugging instrumentation, and validation to achieve near 100% certainty about root causes. This workflow does NOT fix bugs - it produces detailed diagnostic writeups that enable effective fixing by providing complete understanding of what is happening, why it's happening, and supporting evidence.",
+    "description": "[DEPRECATED] This workflow has been superseded by 'systematic-bug-investigation-with-loops' which includes enhanced loop capabilities for iterative debugging and investigation. Use 'systematic-bug-investigation-with-loops' for new bug investigations. A comprehensive workflow for systematic bug and failing test investigation that prevents LLMs from jumping to conclusions. Enforces thorough evidence gathering, hypothesis formation, debugging instrumentation, and validation to achieve near 100% certainty about root causes. This workflow does NOT fix bugs - it produces detailed diagnostic writeups that enable effective fixing by providing complete understanding of what is happening, why it's happening, and supporting evidence.",
     "clarificationPrompts": [
         "What type of system is this? (web app, mobile app, backend service, desktop app, etc.)",
         "How consistently can you reproduce this bug? (always reproducible, sometimes reproducible, rarely reproducible)",
@@ -19,6 +19,7 @@
         "Bug is reproducible with specific steps or a minimal test case"
     ],
     "metaGuidance": [
+        "⚠️ DEPRECATION NOTICE: This workflow is deprecated. Use 'systematic-bug-investigation-with-loops' instead for enhanced iterative debugging capabilities with loop support.",
         "INVESTIGATION DISCIPLINE: Never propose fixes or solutions until Phase 6 (Comprehensive Diagnostic Writeup). Focus entirely on systematic evidence gathering and analysis.",
         "HYPOTHESIS RIGOR: All hypotheses must be based on concrete evidence from code analysis with quantified scoring (1-10 scales). Maximum 5 hypotheses per investigation.",
         "DEBUGGING INSTRUMENTATION: Always implement debugging mechanisms before running tests - logs, print statements, or test modifications that will provide evidence.",