@exaudeus/workrail 0.8.1 → 0.8.4

package/dist/application/app.d.ts

@@ -16,7 +16,6 @@ export declare const METHOD_NAMES: {
     readonly WORKFLOW_LIST: "workflow_list";
     readonly WORKFLOW_GET: "workflow_get";
     readonly WORKFLOW_NEXT: "workflow_next";
-    readonly WORKFLOW_VALIDATE: "workflow_validate";
     readonly INITIALIZE: "initialize";
     readonly TOOLS_LIST: "tools/list";
     readonly SHUTDOWN: "shutdown";

package/dist/application/app.js

@@ -70,13 +70,11 @@ const response_validator_1 = require("../validation/response-validator");
 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',
     WORKFLOW_NEXT: 'workflow_next',
-    WORKFLOW_VALIDATE: 'workflow_validate',
     INITIALIZE: 'initialize',
     TOOLS_LIST: 'tools/list',
     SHUTDOWN: 'shutdown'
@@ -87,7 +85,6 @@ function buildWorkflowApplication(workflowService, validator = request_validator
     const listWorkflowsUseCase = (0, list_workflows_1.createListWorkflows)(workflowService);
     const getWorkflowUseCase = (0, get_workflow_1.createGetWorkflow)(workflowService);
     const getNextStepUseCase = (0, get_next_step_1.createGetNextStep)(workflowService);
-    const validateStepOutputUseCase = (0, validate_step_output_1.createValidateStepOutput)(workflowService);
     app.register(exports.METHOD_NAMES.WORKFLOW_LIST, async (_params) => {
         const workflows = await listWorkflowsUseCase();
         return { workflows };
@@ -98,9 +95,6 @@ function buildWorkflowApplication(workflowService, validator = request_validator
     app.register(exports.METHOD_NAMES.WORKFLOW_NEXT, async (params) => {
         return getNextStepUseCase(params.workflowId, params.completedSteps || [], params.context);
     });
-    app.register(exports.METHOD_NAMES.WORKFLOW_VALIDATE, async (params) => {
-        return validateStepOutputUseCase(params.workflowId, params.stepId, params.output);
-    });
     app.register(exports.METHOD_NAMES.INITIALIZE, async (params) => {
         const { initializeHandler } = await Promise.resolve().then(() => __importStar(require('../tools/mcp_initialize')));
         return (await initializeHandler({ id: 0, params, method: 'initialize', jsonrpc: '2.0' })).result;

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

@@ -40,14 +40,55 @@ class DefaultWorkflowService {
         const completed = [...(completedSteps || [])];
         const enhancedContext = checkedContext;
         const loopBodySteps = new Set();
+        const bodyStepToLoop = new Map();
         for (const step of workflow.steps) {
             if ((0, workflow_types_1.isLoopStep)(step)) {
                 const loopStep = step;
                 if (typeof loopStep.body === 'string') {
                     loopBodySteps.add(loopStep.body);
+                    bodyStepToLoop.set(loopStep.body, loopStep);
                 }
                 else if (Array.isArray(loopStep.body)) {
-                    loopStep.body.forEach(bodyStep => loopBodySteps.add(bodyStep.id));
+                    loopStep.body.forEach(bodyStep => {
+                        loopBodySteps.add(bodyStep.id);
+                        bodyStepToLoop.set(bodyStep.id, loopStep);
+                    });
+                }
+            }
+        }
+        if (!enhancedContext._currentLoop) {
+            const completedLoopBodySteps = completed.filter(stepId => loopBodySteps.has(stepId));
+            if (completedLoopBodySteps.length > 0) {
+                const loopStep = bodyStepToLoop.get(completedLoopBodySteps[0]);
+                if (loopStep && !completed.includes(loopStep.id)) {
+                    enhancedContext._currentLoop = {
+                        loopId: loopStep.id,
+                        loopStep: loopStep
+                    };
+                    if (!enhancedContext._loopState || !enhancedContext._loopState[loopStep.id]) {
+                        const resolvedBody = this.loopStepResolver.resolveLoopBody(workflow, loopStep.body, loopStep.id);
+                        let completedIterations = 0;
+                        if (Array.isArray(resolvedBody)) {
+                            const hasConditionalSteps = resolvedBody.some(step => step.runCondition);
+                            if (hasConditionalSteps) {
+                                completedIterations = completedLoopBodySteps.length;
+                            }
+                            else {
+                                completedIterations = 0;
+                            }
+                        }
+                        else {
+                            completedIterations = completedLoopBodySteps.length;
+                        }
+                        if (!enhancedContext._loopState) {
+                            enhancedContext._loopState = {};
+                        }
+                        enhancedContext._loopState[loopStep.id] = {
+                            iteration: completedIterations,
+                            started: Date.now(),
+                            warnings: []
+                        };
+                    }
                 }
             }
         }
@@ -55,9 +96,20 @@ class DefaultWorkflowService {
             const { loopId, loopStep } = enhancedContext._currentLoop;
             const loopContext = new loop_execution_context_1.LoopExecutionContext(loopId, loopStep.loop, enhancedContext._loopState?.[loopId]);
             const bodyStep = this.loopStepResolver.resolveLoopBody(workflow, loopStep.body, loopStep.id);
-            const bodyIsCompleted = Array.isArray(bodyStep)
-                ? bodyStep.every(step => completed.includes(step.id))
-                : completed.includes(bodyStep.id);
+            let bodyIsCompleted;
+            if (Array.isArray(bodyStep)) {
+                const loopEnhancedContext = loopContext.injectVariables(enhancedContext, false);
+                const eligibleSteps = bodyStep.filter(step => {
+                    if (!step.runCondition) {
+                        return true;
+                    }
+                    return (0, condition_evaluator_1.evaluateCondition)(step.runCondition, loopEnhancedContext);
+                });
+                bodyIsCompleted = eligibleSteps.length === 0 || eligibleSteps.every(step => completed.includes(step.id));
+            }
+            else {
+                bodyIsCompleted = completed.includes(bodyStep.id);
+            }
             if (bodyIsCompleted) {
                 loopContext.incrementIteration();
                 if (!enhancedContext._loopState) {

package/dist/config/feature-flags.js

@@ -27,6 +27,14 @@ exports.FEATURE_FLAG_DEFINITIONS = [
         since: '0.6.0',
         stable: true,
     },
+    {
+        key: 'agenticRoutines',
+        envVar: 'WORKRAIL_ENABLE_AGENTIC_ROUTINES',
+        defaultValue: false,
+        description: 'Enable Agentic Orchestration features (subagent delegation, .agentic.json overrides, routines)',
+        since: '0.8.3',
+        stable: false,
+    },
 ];
 function parseBoolean(value, defaultValue) {
     if (value === undefined) {

package/dist/infrastructure/storage/file-workflow-storage.d.ts

@@ -1,10 +1,12 @@
 import { IWorkflowStorage } from '../../types/storage';
 import { Workflow, WorkflowSummary } from '../../types/mcp-types';
+import { IFeatureFlagProvider } from '../../config/feature-flags';
 interface FileWorkflowStorageOptions {
     maxFileSizeBytes?: number;
     cacheTTLms?: number;
     cacheSize?: number;
     indexCacheTTLms?: number;
+    featureFlagProvider?: IFeatureFlagProvider;
 }
 export declare class FileWorkflowStorage implements IWorkflowStorage {
     private readonly baseDirReal;
@@ -13,9 +15,11 @@ export declare class FileWorkflowStorage implements IWorkflowStorage {
     private readonly cacheLimit;
     private readonly indexCacheTTL;
     private readonly cache;
+    private readonly featureFlags;
     private workflowIndex;
     private indexExpires;
     constructor(directory: string, options?: FileWorkflowStorageOptions);
+    private findJsonFiles;
     private buildWorkflowIndex;
     private getWorkflowIndex;
     private loadWorkflowFromFile;

package/dist/infrastructure/storage/file-workflow-storage.js

@@ -9,6 +9,7 @@ const promises_1 = __importDefault(require("fs/promises"));
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
 const error_handler_1 = require("../../core/error-handler");
+const feature_flags_1 = require("../../config/feature-flags");
 function sanitizeId(id) {
     if (id.includes('\u0000')) {
         throw new error_handler_1.SecurityError('Null byte detected in identifier', 'sanitizeId');
@@ -35,45 +36,85 @@ class FileWorkflowStorage {
         this.cacheTTL = options.cacheTTLms ?? 5000;
         this.cacheLimit = options.cacheSize ?? 100;
         this.indexCacheTTL = options.indexCacheTTLms ?? 30000;
+        this.featureFlags = options.featureFlagProvider ?? (0, feature_flags_1.createFeatureFlagProvider)();
+    }
+    async findJsonFiles(dir) {
+        const files = [];
+        async function scan(currentDir) {
+            const entries = await promises_1.default.readdir(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path_1.default.join(currentDir, entry.name);
+                if (entry.isDirectory()) {
+                    await scan(fullPath);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.json')) {
+                    files.push(fullPath);
+                }
+            }
+        }
+        await scan(dir);
+        return files;
     }
     async buildWorkflowIndex() {
-        const dirEntries = await promises_1.default.readdir(this.baseDirReal);
-        const jsonFiles = dirEntries.filter((f) => f.endsWith('.json'));
+        const allJsonFiles = await this.findJsonFiles(this.baseDirReal);
+        const relativeFiles = allJsonFiles.map(f => path_1.default.relative(this.baseDirReal, f));
         const index = new Map();
-        for (const file of jsonFiles) {
-            const filePathRaw = path_1.default.resolve(this.baseDirReal, file);
-            assertWithinBase(filePathRaw, this.baseDirReal);
+        const idToFiles = new Map();
+        for (const file of relativeFiles) {
             try {
+                if (!this.featureFlags.isEnabled('agenticRoutines')) {
+                    if (file.includes('routines/') || path_1.default.basename(file).startsWith('routine-')) {
+                        continue;
+                    }
+                }
+                const filePathRaw = path_1.default.resolve(this.baseDirReal, file);
+                assertWithinBase(filePathRaw, this.baseDirReal);
                 const stats = (0, fs_1.statSync)(filePathRaw);
-                if (stats.size > this.maxFileSize) {
-                    console.warn(`[FileWorkflowStorage] Skipping oversized file: ${file}`);
+                if (stats.size > this.maxFileSize)
                     continue;
-                }
                 const raw = await promises_1.default.readFile(filePathRaw, 'utf-8');
                 const data = JSON.parse(raw);
-                if (!data.id) {
-                    console.warn(`[FileWorkflowStorage] Skipping file without id: ${file}`);
+                if (!data.id)
                     continue;
-                }
-                const entry = {
-                    id: data.id,
-                    filename: file,
-                    lastModified: stats.mtimeMs,
-                    summary: {
-                        id: data.id,
-                        name: data.name,
-                        description: data.description,
-                        category: 'default',
-                        version: data.version
-                    }
-                };
-                index.set(data.id, entry);
+                const files = idToFiles.get(data.id) || [];
+                files.push(file);
+                idToFiles.set(data.id, files);
             }
-            catch (err) {
-                console.warn(`[FileWorkflowStorage] Skipping invalid file: ${file}`, err);
+            catch (e) {
                 continue;
             }
         }
+        for (const [id, files] of idToFiles) {
+            let selectedFile = files[0];
+            if (this.featureFlags.isEnabled('agenticRoutines')) {
+                const agenticFile = files.find(f => f.includes('.agentic.'));
+                if (agenticFile) {
+                    selectedFile = agenticFile;
+                }
+            }
+            else {
+                const standardFile = files.find(f => !f.includes('.agentic.'));
+                if (standardFile) {
+                    selectedFile = standardFile;
+                }
+            }
+            const filePath = path_1.default.resolve(this.baseDirReal, selectedFile);
+            const stats = (0, fs_1.statSync)(filePath);
+            const raw = await promises_1.default.readFile(filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            index.set(id, {
+                id: data.id,
+                filename: selectedFile,
+                lastModified: stats.mtimeMs,
+                summary: {
+                    id: data.id,
+                    name: data.name,
+                    description: data.description,
+                    category: 'default',
+                    version: data.version
+                }
+            });
+        }
         return index;
     }
     async getWorkflowIndex() {

package/dist/mcp-server.js

@@ -285,32 +285,6 @@ const WORKFLOW_NEXT_TOOL = {
         additionalProperties: false
     }
 };
-const WORKFLOW_VALIDATE_TOOL = {
-    name: "workflow_validate",
-    description: `(Optional but Recommended) Verifies the output of a step before proceeding. Use this after completing a step to check if your work is valid to prevent errors.`,
-    inputSchema: {
-        type: "object",
-        properties: {
-            workflowId: {
-                type: "string",
-                description: "The unique identifier of the workflow",
-                pattern: "^[A-Za-z0-9_-]+$"
-            },
-            stepId: {
-                type: "string",
-                description: "The unique identifier of the step to validate",
-                pattern: "^[A-Za-z0-9_-]+$"
-            },
-            output: {
-                type: "string",
-                description: "The output or result produced for this step",
-                maxLength: 10000
-            }
-        },
-        required: ["workflowId", "stepId", "output"],
-        additionalProperties: false
-    }
-};
 const WORKFLOW_VALIDATE_JSON_TOOL = {
     name: "workflow_validate_json",
     description: `Validates workflow JSON content directly without external tools. Use this tool when you need to verify that a workflow JSON file is syntactically correct and follows the proper schema.
@@ -386,7 +360,6 @@ async function runServer() {
             WORKFLOW_LIST_TOOL,
             WORKFLOW_GET_TOOL,
             WORKFLOW_NEXT_TOOL,
-            WORKFLOW_VALIDATE_TOOL,
             WORKFLOW_VALIDATE_JSON_TOOL,
             WORKFLOW_GET_SCHEMA_TOOL,
             ...workflowServer.getSessionTools()
@@ -429,14 +402,6 @@ async function runServer() {
                     };
                 }
                 return await workflowServer.getNextStep(args['workflowId'], args['completedSteps'] || [], args['context']);
-            case "workflow_validate":
-                if (!args?.['workflowId'] || !args?.['stepId'] || !args?.['output']) {
-                    return {
-                        content: [{ type: "text", text: "Error: workflowId, stepId, and output parameters are required" }],
-                        isError: true
-                    };
-                }
-                return await workflowServer.validateStep(args['workflowId'], args['stepId'], args['output']);
             case "workflow_validate_json":
                 if (!args?.['workflowJson']) {
                     return {

package/package.json

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

package/workflows/bug-investigation.agentic.json

@@ -0,0 +1,112 @@
+{
+  "id": "bug-investigation",
+  "name": "Bug Investigation (Agentic)",
+  "version": "2.0.0",
+  "description": "Agentic-enhanced bug investigation workflow with strategic delegation to specialized subagents. Delegates context gathering, hypothesis challenge, execution simulation, and adversarial validation to optimize investigation quality and efficiency.",
+  "clarificationPrompts": [
+    "What type of system is this? (web app, backend service, CLI tool, etc.)",
+    "How reproducible is this bug? (always, sometimes, rarely)",
+    "What access do you have? (full codebase, logs, tests, etc.)"
+  ],
+  "preconditions": [
+    "User has a specific bug or failing test to investigate",
+    "Agent has codebase access and can run tests/build",
+    "Bug is reproducible with specific steps"
+  ],
+  "metaGuidance": [
+    "WHO YOU ARE: You are a special investigator - one of the few who has the patience, determination, and skill to find the TRUE source of bugs.",
+    "Most investigators stop at the obvious explanation. You don't. You look past red herrings, challenge assumptions, and dig until you have certainty.",
+    "YOUR MISSION: Find the REAL cause of this bug. Not the apparent cause, not the first explanation, but the actual source with evidence to prove it.",
+    "WHY THIS WORKFLOW EXISTS: It gives you a systematic process to avoid the traps that catch other investigators - jumping to conclusions, confirmation bias, surface-level analysis.",
+    "HOW IT WORKS: Each phase has two steps: First you PLAN your approach (think strategically), then you EXECUTE it (do the work).",
+    "This planning step is critical - it forces you to think about HOW you'll investigate before diving in. Better plans lead to better investigations.",
+    "THE PHASES:",
+    "Phase 0: Understand what you're investigating and set up your workspace",
+    "Phase 1: Trace how execution flows from entry point to error (follow the code path)",
+    "Phase 2: Form multiple hypotheses about what could be causing this (stay open-minded)",
+    "Phase 3: Design and add instrumentation to gather evidence (set up your surveillance)",
+    "Phase 4: Run instrumented code and collect evidence (gather proof, not assumptions)",
+    "Phase 5: Validate your conclusion rigorously (be your harshest critic)",
+    "Phase 6: Document your findings so others can understand and fix it (prove your case)",
+    "CRITICAL DISTINCTION - THEORY VS PROOF:",
+    "When you read code and think 'I found it!', you have a THEORY. Theories feel certain but are often wrong.",
+    "PROOF comes from running instrumented code, collecting evidence, ruling out alternatives, and validating rigorously.",
+    "You must complete all phases to get from theory to proof. No shortcuts, even with high confidence.",
+    "YOUR DELIVERABLE: A diagnostic writeup that proves you found the true source - complete with evidence, alternative explanations ruled out, and reproduction steps.",
+    "SUCCESS MEANS: Someone reading your writeup can fix the bug confidently because you've proven what's actually happening and why.",
+    "WORKFLOW MECHANICS: Call workflow_next to get each phase. Complete the phase (both plan and execute). Call workflow_next again. Repeat until isComplete=true."
+  ],
+  "steps": [
+    {
+      "id": "phase-0-setup",
+      "title": "Phase 0: Investigation Setup (Agentic)",
+      "prompt": "**UNDERSTAND THE PROBLEM & SET UP YOUR WORKSPACE**\n\nBefore you start investigating, you need to understand what you're looking for and prepare your workspace.\n\n**DELEGATION OPPORTUNITY: Context Gathering**\n\nThis phase benefits from systematic codebase exploration. Consider delegating to your Context Researcher subagent.\n\n**DELEGATION WORK PACKAGE:**\n```\nMISSION: Gather comprehensive context about this bug\n\nTARGETS:\n- Bug description: [Insert bug description]\n- Error messages/stack traces: [Insert if available]\n- Reproduction steps: [Insert if known]\n- Affected areas: [Insert suspected files/features]\n\nROUTINE: routine-context-gathering\nDEPTH: 2 (Explore - balance breadth and detail)\n\nDELIVERABLE:\n- File structure map of affected areas\n- Key files identified (entry points, error locations, dependencies)\n- Patterns observed (architecture, data flow, error handling)\n- Initial suspects (files/functions that could be involved)\n- Gaps (missing information or unclear areas)\n```\n\n**AFTER DELEGATION:**\nReview the Context Researcher's deliverable and use it to:\n\n**Set Up Your Investigation**:\n- Create INVESTIGATION_CONTEXT.md to track your investigation\n- Document the bug description and reproduction steps\n- Note the key files and areas identified by the researcher\n- List initial assumptions you'll need to verify\n- Set up a workspace (branch or directory) if appropriate\n- Clarify any user preferences\n\n**OUTPUT**: INVESTIGATION_CONTEXT.md with:\n- Clear description of the bug\n- Reproduction steps\n- Initial information (stack traces, logs, errors)\n- Key files and areas to investigate (from context gathering)\n- Your workspace location\n- Any early assumptions to verify later\n\n**Before Proceeding**: Can you clearly explain this bug to someone else? Do you know how to reproduce it? Do you know where to start looking?",
+      "agentRole": "You are an investigative coordinator, leveraging specialized researchers to build a comprehensive understanding before diving into analysis.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-1a-plan",
+      "title": "Phase 1A: Plan Your Investigation Approach",
+      "prompt": "**PLAN HOW YOU'LL TRACK DOWN THIS BUG**\n\nYou're about to analyze the codebase. But first, think strategically about HOW you'll investigate.\n\n**Think Through**:\n\n1. **Where does execution start?**\n   - What triggers this bug? (API call, user action, test, scheduled job?)\n   - Where in the code does execution begin?\n\n2. **What's your investigation strategy?**\n   - Will you trace execution flow from entry to error?\n   - Will you start at the error and work backwards?\n   - Will you examine recent changes first?\n   - How will you identify the key points to investigate?\n\n3. **What could cause you to miss the real issue?**\n   - Focusing too narrowly on one area?\n   - Missing indirect causes or side effects?\n   - Assuming things work as documented?\n   - Not checking alternative execution paths?\n\n4. **What's your analysis plan?**\n   - List the sequence of investigations you'll do\n   - What will you look for at each step?\n   - How will you know when you understand enough?\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with \"Phase 1 Investigation Plan\" section:\n- Your investigation strategy\n- Sequence of steps you'll take\n- Key questions you need to answer\n- Risks you're watching out for\n\n**Self-Check**: Is your plan specific enough to follow? Does it account for the ways you might miss the real cause?",
+      "agentRole": "You are a strategic investigator planning your approach. Think before you dive in.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-1b-execute",
+      "title": "Phase 1B: Execute Your Investigation",
+      "prompt": "**CARRY OUT YOUR INVESTIGATION PLAN**\n\nNow execute the investigation strategy you designed.\n\n**Execute Your Plan**:\n- Follow the sequence of investigations you planned\n- Trace execution flow from entry point to error\n- Track how data flows and state changes\n- Read the actual code at key points\n- Note anything suspicious or unexpected\n- Adapt your plan if you discover new information\n\n**Document As You Go**:\nCreate ExecutionFlow.md with:\n- **Entry Point**: Where execution begins\n- **Call Chain**: Step-by-step path from entry to error (with file:line)\n- **Data Flow**: How data transforms along the way\n- **State Changes**: What gets modified\n- **Suspicious Points**: Code that could be problematic\n- **Patterns**: How things normally work vs how they work in failing case\n\n**Self-Critique**:\n- Did you follow your plan or skip steps?\n- Did you actually trace the execution flow, or just read code?\n- What did you learn that surprised you?\n- What are you still uncertain about?\n- Did your plan work, or should you investigate differently?\n\n**Critical Reminder**: You're building understanding of what the code DOES. You don't have a diagnosis yet - that comes later after you form and test hypotheses.",
+      "agentRole": "You are executing your investigation plan. Stay systematic and document what you find.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-2a-plan",
+      "title": "Phase 2A: Plan Your Hypothesis Development",
+      "prompt": "**PLAN HOW YOU'LL FORM HYPOTHESES**\n\nBased on your investigation, you'll now develop hypotheses about what's causing the bug.\n\n**Think Through**:\n\n1. **What patterns did you notice?**\n   - From your execution flow tracing, what stood out?\n   - What code seemed suspicious?\n   - What assumptions are baked into the code?\n\n2. **What types of causes should you consider?**\n   - Logic errors in the code?\n   - Data issues (wrong format, corruption, missing)?\n   - Timing or race conditions?\n   - Environment or configuration issues?\n   - Integration problems with dependencies?\n\n3. **How will you avoid anchoring on your first idea?**\n   - How many alternative hypotheses will you generate?\n   - How will you challenge your initial impressions?\n   - What evidence would contradict your leading theory?\n\n4. **What makes a good hypothesis?**\n   - Specific enough to test\n   - Explains all the symptoms\n   - Has clear evidence for/against\n   - Can be proven or disproven\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with \"Phase 2 Hypothesis Strategy\":\n- How you'll generate multiple hypotheses\n- What types of causes you'll consider\n- How you'll avoid confirmation bias\n- How you'll test your hypotheses\n\n**Self-Check**: Are you committed to generating multiple hypotheses, or are you already attached to one idea?",
+      "agentRole": "You are strategizing about hypothesis formation. Commit to staying open-minded.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-2b-execute",
+      "title": "Phase 2B: Develop and Prioritize Hypotheses",
+      "prompt": "**FORM MULTIPLE HYPOTHESES ABOUT THE BUG**\n\nNow generate your hypotheses following your strategy.\n\n**Generate Hypotheses**:\n\nFor each possible cause, create a hypothesis:\n\n**Hypothesis Template**:\n- **ID**: H1, H2, H3, etc.\n- **Statement**: \"The bug occurs because [specific cause]\"\n- **Evidence For**: What from your investigation supports this?\n- **Evidence Against**: What contradicts this or makes it unlikely?\n- **How to Test**: What evidence would prove/disprove this?\n- **Likelihood** (1-10): Based on current evidence\n\n**Generate 3-7 hypotheses**. Force yourself to consider alternatives even if one seems obvious.\n\n**DELEGATION OPPORTUNITY: Adversarial Challenge**\n\nOnce you have initial hypotheses, consider delegating to your Hypothesis Challenger subagent for rigorous critique.\n\n**DELEGATION WORK PACKAGE:**\n```\nMISSION: Challenge and stress-test my bug hypotheses\n\nHYPOTHESES: [Paste your 3-7 hypotheses from above]\n\nEVIDENCE:\n- ExecutionFlow.md (file reference)\n- INVESTIGATION_CONTEXT.md (file reference)\n- [Any other evidence files]\n\nROUTINE: routine-hypothesis-challenge\nRIGOR: 3 (Deep - thorough adversarial review)\n\nDELIVERABLE:\nFor each hypothesis:\n- Strengths (what evidence supports it)\n- Weaknesses (gaps, contradictions, assumptions)\n- Alternative explanations (what else could cause this)\n- Verdict (Keep/Revise/Reject/Insufficient Evidence)\n- Recommendations (how to strengthen or what to test)\n```\n\n**AFTER DELEGATION:**\nReview the Hypothesis Challenger's critique and refine your hypotheses.\n\n**Prioritize**:\nRank by:\n1. Likelihood (evidence strength after challenge)\n2. Testability (can you validate it?)\n3. Completeness (explains all symptoms?)\n\n**Plan Validation**:\nFor top 3-5 hypotheses:\n- What instrumentation would prove/disprove each?\n- What tests should you run?\n- What experiments could distinguish between them?\n\n**OUTPUT**: Create Hypotheses.md with all hypotheses, challenger feedback, rankings, and validation strategy.\n\n**🚨 CRITICAL - YOU ARE NOT DONE:**\n\nYou now have theories. You do NOT have proof.\n\nEven if H1 has 10/10 likelihood, it's based on reading code, not evidence from running code.\n\nYou MUST continue to Phase 3 (design instrumentation) and Phase 4 (collect evidence).\n\nThis is not optional. High confidence without evidence = educated guess, not diagnosis.\n\nCall workflow_next to continue.",
+      "agentRole": "You are forming competing hypotheses and subjecting them to rigorous challenge. Stay open to alternatives even if one seems obvious.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-3a-plan",
+      "title": "Phase 3A: Design Your Instrumentation Strategy",
+      "prompt": "**PLAN HOW YOU'LL GATHER EVIDENCE**\n\nYou have hypotheses. Now design how you'll gather evidence to test them.\n\n**Think Through**:\n\n1. **What evidence would prove each hypothesis?**\n   - For H1, what specific data points would confirm it?\n   - For H2, what would you observe if it's correct?\n   - How can you distinguish between competing hypotheses?\n\n2. **Where should you add instrumentation?**\n   - What points in the execution flow are critical?\n   - Where could you observe the data/state you need?\n   - What's already being logged vs what do you need to add?\n\n3. **What's the right level of detail?**\n   - Too much logging = noise and hard to analyze\n   - Too little = gaps and missing evidence\n   - How will you balance this?\n\n4. **Can you use existing tests?**\n   - Are there tests you can enhance instead of adding new logging?\n   - Can you modify tests to expose the state you need?\n   - Should you write new targeted tests?\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with \"Phase 3 Instrumentation Plan\":\n- What evidence you need for each hypothesis\n- Where you'll add instrumentation (file:line)\n- What you'll log/observe at each point\n- Test scenarios you'll prepare\n- How you'll organize output to distinguish hypotheses\n\n**Self-Check**: Will this instrumentation actually give you the evidence you need? What might you miss?",
+      "agentRole": "You are designing your evidence collection strategy. Think carefully about what you need to prove.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-3b-execute",
+      "title": "Phase 3B: Implement Your Instrumentation",
+      "prompt": "**ADD INSTRUMENTATION AND PREPARE TEST SCENARIOS**\n\nNow implement the instrumentation strategy you designed.\n\n**DELEGATION OPPORTUNITY: Execution Simulation**\n\nBefore adding instrumentation, consider simulating execution to predict outcomes and refine your strategy.\n\n**DELEGATION WORK PACKAGE:**\n```\nMISSION: Simulate execution paths for my top hypotheses\n\nHYPOTHESES: [Paste top 3-5 hypotheses]\n\nCONTEXT:\n- ExecutionFlow.md (file reference)\n- Hypotheses.md (file reference)\n- Key files: [List critical files from investigation]\n\nROUTINE: routine-execution-simulation\nMODE: trace (Detailed execution path analysis)\n\nDELIVERABLE:\nFor each hypothesis:\n- Predicted execution path (step-by-step)\n- State changes at each step\n- Where instrumentation would be most revealing\n- Expected outputs if hypothesis is correct\n- Distinguishing characteristics between hypotheses\n```\n\n**AFTER DELEGATION:**\nUse the simulation results to refine your instrumentation plan.\n\n**Implement**:\n- Add debug logging at the points identified by simulation\n- Enhance or create tests to expose necessary state\n- Add assertions to catch violations\n- Set up controlled experiments if needed\n- Label everything clearly ([H1], [H2], etc.)\n\n**Prepare Test Scenarios**:\n- Minimal reproduction case\n- Edge cases that might behave differently\n- Working scenarios for comparison\n- Variations that test specific hypotheses\n\n**OUTPUT**: Update INVESTIGATION_CONTEXT.md with:\n- List of instrumentation added (what/where/why)\n- Test scenarios prepared\n- Expected outcomes for each hypothesis (from simulation)\n- How you'll analyze results\n\n**Self-Critique**:\n- Did you add the instrumentation you planned?\n- Did you skip any because it seemed unnecessary?\n- Is your instrumentation labeled clearly?\n- Are your test scenarios sufficient?\n\n**Readiness Check**: If you run these tests, will you get the evidence you need to prove/disprove your hypotheses?",
+      "agentRole": "You are implementing your evidence collection plan with precision, informed by execution simulation. Good instrumentation is the foundation of proof.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-4-execute",
+      "title": "Phase 4: Collect Evidence",
+      "prompt": "**RUN INSTRUMENTED CODE AND COLLECT EVIDENCE**\n\nNow run your test scenarios and collect the evidence.\n\n**Execute**:\n- Run minimal reproduction case\n- Run edge cases and variations\n- Run working scenarios for comparison\n- Capture all output (logs, errors, test results)\n\n**Organize Evidence**:\nFor each hypothesis, create Evidence_H1.md, Evidence_H2.md, etc.:\n- What did the instrumentation reveal?\n- Does behavior match predictions?\n- What unexpected findings emerged?\n- Quality rating (1-10): How strong is this evidence?\n\n**Analyze Patterns**:\n- Which hypotheses are supported by evidence?\n- Which are contradicted?\n- Are there patterns you didn't predict?\n- Do you need different instrumentation?\n- Should you form new hypotheses?\n\n**Update Hypotheses**:\nUpdate Hypotheses.md with:\n- Evidence collected for each\n- New likelihood scores based on evidence\n- Evidence quality ratings\n- New insights or remaining questions\n\n**Decision Point**:\n- Strong evidence (8+/10) for one hypothesis? → Proceed to validation\n- Need more instrumentation? → Go back and add it\n- Need to revise hypotheses? → Update them\n\nBut you're not done until you have strong evidence. Keep investigating.",
+      "agentRole": "You are collecting evidence systematically. Let the data guide you, not your assumptions.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-5-validate",
+      "title": "Phase 5: Validate Your Conclusion",
+      "prompt": "**RIGOROUSLY VALIDATE YOUR FINDING**\n\nYou have a leading hypothesis with evidence. Now be your harshest critic.\n\n**State Your Conclusion**:\n- What hypothesis has the strongest evidence?\n- What's your confidence (1-10)?\n- What evidence supports it?\n\n**DELEGATION OPPORTUNITY: Adversarial Validation**\n\nYour conclusion needs rigorous challenge. Delegate to your Hypothesis Challenger for maximum-rigor adversarial review.\n\n**DELEGATION WORK PACKAGE:**\n```\nMISSION: Rigorously validate my bug diagnosis\n\nHYPOTHESES:\n- Leading hypothesis: [Your conclusion]\n- Alternatives considered: [List other hypotheses you ruled out]\n\nEVIDENCE:\n- Evidence_H*.md files (file references)\n- Hypotheses.md (file reference)\n- INVESTIGATION_CONTEXT.md (file reference)\n- Instrumentation output/logs (file references or inline)\n\nROUTINE: routine-hypothesis-challenge\nRIGOR: 5 (Maximum - exhaustive adversarial review)\n\nDELIVERABLE:\n- Strengths of leading hypothesis\n- Weaknesses and gaps\n- Alternative explanations not yet ruled out\n- Contradicting evidence\n- Edge cases that might break the explanation\n- Verdict with confidence assessment\n- Recommendations for additional validation\n```\n\n**AFTER DELEGATION:**\nReview the Hypothesis Challenger's adversarial critique.\n\n**If confidence < 9/10**:\n- What specific test would raise confidence?\n- What alternative should you rule out?\n- What additional evidence do you need?\n- Go collect that evidence\n\n**Final Assessment**:\nAnswer these YES/NO:\n- Does this explain all observed symptoms?\n- Have you ruled out major alternatives?\n- Can you reproduce the bug based on this understanding?\n- Would you stake your reputation on this diagnosis?\n- Is there any contradicting evidence?\n- Did the adversarial review strengthen or weaken your confidence?\n\n**OUTPUT**: ValidationReport.md with:\n- Leading hypothesis and evidence\n- Alternatives considered and ruled out\n- Adversarial review findings (from Hypothesis Challenger)\n- Final confidence score\n- Remaining uncertainties\n\n**Threshold**: 9+/10 confidence with strong evidence to proceed. If not, keep investigating.",
+      "agentRole": "You are validating your conclusion with maximum rigor, leveraging adversarial challenge to ensure you haven't missed anything.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-6-writeup",
+      "title": "Phase 6: Prove Your Case",
+      "prompt": "**DOCUMENT YOUR INVESTIGATION - PROVE YOU FOUND THE TRUE SOURCE**\n\nYou've found the true source of the bug. Now prove it to others.\n\n**Your Task**: Create a diagnostic writeup that proves your case.\n\n**Structure**:\n\n**1. EXECUTIVE SUMMARY** (3-5 sentences)\n- What's the bug?\n- What's the true cause?\n- How confident are you? (should be 9-10/10)\n- What's the impact?\n\n**2. THE TRUE SOURCE** (detailed)\n- Explain the root cause\n- Why this causes the observed symptoms\n- Code locations (file:line)\n- Relevant code snippets\n\n**3. THE PROOF** (your evidence)\n- Key evidence that proves this diagnosis\n- How you collected it (instrumentation, tests)\n- Evidence quality and sources\n- Why alternative explanations don't fit\n\n**4. HOW TO REPRODUCE**\n- Minimal steps to reproduce\n- What to observe that confirms the diagnosis\n- Conditions required\n\n**5. YOUR INVESTIGATION**\n- What you analyzed\n- Hypotheses you tested\n- How you arrived at the conclusion\n- Key turning points\n\n**6. FIXING IT**\n- Suggested approach (conceptual)\n- Risks to consider\n- How to verify the fix\n- Tests that should be added\n\n**7. UNCERTAINTIES** (if any)\n- What you're still unsure about\n- Edge cases needing more investigation\n\n**OUTPUT**: DIAGNOSTIC_WRITEUP.md\n\n**Quality Check**:\n- Could someone fix this bug confidently from your writeup?\n- Have you proven your case with evidence?\n- Is it clear WHY this is the true source, not just a symptom?\n\n**Mission Complete**: You've tracked down the true source and proven it. Well done.",
+      "agentRole": "You are documenting your successful investigation. You found the truth - now prove it to others.",
+      "requireConfirmation": false
+    }
+  ]
+}
+

package/workflows/routines/context-gathering.json

@@ -0,0 +1,149 @@
+{
+  "id": "routine-context-gathering",
+  "name": "Context Gathering Routine",
+  "version": "2.1.0",
+  "description": "Systematic codebase exploration using an Ideate -> Plan -> Execute strategy. Configurable depth levels (0-4) allow for progressively deeper understanding.",
+  "clarificationPrompts": [
+    "What specific area or files should I investigate?",
+    "What depth level do you need? (0=Survey, 1=Scan, 2=Explore, 3=Analyze, 4=Dissect)",
+    "What are you trying to understand? (bug investigation, feature planning, refactoring, etc.)"
+  ],
+  "preconditions": [
+    "Target areas are broadly identified",
+    "Depth level (0-4) is specified",
+    "Mission/goal is clear",
+    "Agent has read access to codebase"
+  ],
+  "metaGuidance": [
+    "**ROUTINE PURPOSE:**",
+    "This routine performs systematic codebase investigation. It separates strategy (Ideate/Plan) from execution (Survey/Scan/Explore/etc.).",
+    "**PHASES:**",
+    "1. IDEATE: Brainstorm relevant areas and potential connections",
+    "2. PLAN: Define specific targets and search strategy",
+    "3. EXECUTE: Run the investigation at the requested depth",
+    "4. SYNTHESIZE: Combine findings into actionable insights",
+    "**CORE PRINCIPLES:**",
+    "- STRATEGY FIRST: Don't start reading files until you know WHY and WHERE",
+    "- SYSTEMATIC: Follow the plan, don't rabbit-hole",
+    "- HONEST: Note gaps and limitations",
+    "- CITED: Support findings with file:line references"
+  ],
+  "steps": [
+    {
+      "id": "step-0-ideate-targets",
+      "title": "Step 0: Ideate Research Targets",
+      "prompt": "**EXPLORE POTENTIAL TARGETS**\n\nBefore diving in, brainstorm what areas of the codebase might be relevant to your mission.\n\n**YOUR MISSION:** Identify all potential areas of interest and why they might matter.\n\n**EXECUTE:**\n1. Review the Mission/Goal\n2. List all potential subsystems, modules, or directories that could be involved\n3. Consider indirect connections (shared utils, config, infrastructure)\n4. Brainstorm keywords or patterns to look for\n\n**REFLECT:**\n- Am I missing any obvious areas?\n- Are there dependencies I should check?\n- Is my scope too narrow or too broad?\n\n**WORKING NOTES:**\n- Mission Summary\n- Potential Targets (List)\n- Keywords/Patterns to search\n- Why each area matters",
+      "agentRole": "You are a scout surveying the landscape. Look for signals and potential paths.",
+      "requireConfirmation": false,
+      "guidance": [
+        "BRAINSTORM: List widely before narrowing down",
+        "KEYWORDS: Think of specific terms to grep for later",
+        "CONNECTIONS: Think about how components interact"
+      ]
+    },
+    {
+      "id": "step-1-plan-strategy",
+      "title": "Step 1: Plan Research Strategy",
+      "prompt": "**DEFINE RESEARCH PLAN**\n\nNow select the specific targets and define your strategy for the requested depth.\n\n**YOUR MISSION:** Create a concrete plan for your investigation.\n\n**EXECUTE:**\n1. Select the primary targets from Step 0\n2. Define the **Search Scope** (specific directories/files)\n3. Define the **Exclusions** (what to ignore, e.g., tests, legacy)\n4. Define the **Focus** for the requested depth (e.g., \"Map structure\" for D0, \"Trace logic\" for D2)\n\n**DELIVERABLE:**\nCreate `research-plan.md` with:\n- Primary Targets\n- Search Scope\n- Key Questions to Answer\n- Depth Strategy",
+      "agentRole": "You are a research lead defining the scope and method. Be specific.",
+      "requireConfirmation": false,
+      "guidance": [
+        "SCOPE: Be specific about directories (e.g., src/auth, not just 'auth')",
+        "FOCUS: Align the strategy with the requested depth level",
+        "QUESTIONS: List the specific questions you want to answer"
+      ]
+    },
+    {
+      "id": "step-execute-depth-0",
+      "title": "Execution: Depth 0 (Survey)",
+      "runCondition": {
+        "var": "depth",
+        "gte": 0
+      },
+      "prompt": "**EXECUTE DEPTH 0: SURVEY**\n\nExecute your research plan at Depth 0 (Map the territory).\n\n**MISSION:** Understand what exists in the target area without reading contents.\n\n**EXECUTE:**\n1. Follow `research-plan.md`\n2. Use `list_dir` on target scopes\n3. Map file structure and purpose\n4. Identify architectural patterns\n\n**WORKING NOTES:**\n- File Tree & Purpose\n- Observed Patterns\n- Suspicious Areas",
+      "agentRole": "You are a systematic cartographer mapping the territory.",
+      "requireConfirmation": false,
+      "guidance": [
+        "TOOL: Use list_dir only",
+        "CONSTRAINT: Do not read file contents yet",
+        "OUTPUT: Structural map and high-level observations"
+      ]
+    },
+    {
+      "id": "step-execute-depth-1",
+      "title": "Execution: Depth 1 (Scan)",
+      "runCondition": {
+        "var": "depth",
+        "gte": 1
+      },
+      "prompt": "**EXECUTE DEPTH 1: SCAN**\n\nExecute your research plan at Depth 1 (Identify components).\n\n**MISSION:** Understand components and relationships without reading implementations.\n\n**EXECUTE:**\n1. Follow `research-plan.md`\n2. Read file headers (top 50 lines)\n3. Map imports/exports and dependencies\n4. Identify architectural layers\n\n**WORKING NOTES:**\n- Component Map\n- Dependency Graph\n- Key Interfaces",
+      "agentRole": "You are an architect mapping component relationships.",
+      "requireConfirmation": false,
+      "guidance": [
+        "TOOL: read_file --limit 50 for headers",
+        "TOOL: grep for cross-references",
+        "CONSTRAINT: Don't read full implementations"
+      ]
+    },
+    {
+      "id": "step-execute-depth-2",
+      "title": "Execution: Depth 2 (Explore)",
+      "runCondition": {
+        "var": "depth",
+        "gte": 2
+      },
+      "prompt": "**EXECUTE DEPTH 2: EXPLORE**\n\nExecute your research plan at Depth 2 (Understand functionality).\n\n**MISSION:** Trace execution flows and understand behavior.\n\n**EXECUTE:**\n1. Follow `research-plan.md`\n2. Read function signatures and docstrings\n3. Trace key execution paths\n4. Map data flow and transformations\n\n**WORKING NOTES:**\n- Execution Flow Diagrams\n- Functional Summaries\n- Data Flow Maps",
+      "agentRole": "You are a systems analyst tracing flows and data.",
+      "requireConfirmation": false,
+      "guidance": [
+        "TOOL: Read full signatures and docstrings",
+        "TRACE: Follow the call chain",
+        "DATA: Track how data transforms"
+      ]
+    },
+    {
+      "id": "step-execute-depth-3",
+      "title": "Execution: Depth 3 (Analyze)",
+      "runCondition": {
+        "var": "depth",
+        "gte": 3
+      },
+      "prompt": "**EXECUTE DEPTH 3: ANALYZE**\n\nExecute your research plan at Depth 3 (Deep implementation analysis).\n\n**MISSION:** Understand exact behavior, edge cases, and potential issues.\n\n**EXECUTE:**\n1. Follow `research-plan.md`\n2. Read full implementations\n3. Analyze conditionals and loops\n4. Check for race conditions and edge cases\n\n**WORKING NOTES:**\n- Detailed Implementation Analysis\n- Edge Case Analysis\n- Potential Issues",
+      "agentRole": "You are a code reviewer looking for logic errors and edge cases.",
+      "requireConfirmation": false,
+      "guidance": [
+        "TOOL: Read full files",
+        "EDGE CASES: Check nulls, boundaries, empty states",
+        "LOGIC: Verify all conditional branches"
+      ]
+    },
+    {
+      "id": "step-execute-depth-4",
+      "title": "Execution: Depth 4 (Dissect)",
+      "runCondition": {
+        "var": "depth",
+        "gte": 4
+      },
+      "prompt": "**EXECUTE DEPTH 4: DISSECT**\n\nExecute your research plan at Depth 4 (Forensic line-by-line).\n\n**MISSION:** Find every bug, vulnerability, and subtle issue.\n\n**EXECUTE:**\n1. Follow `research-plan.md`\n2. Analyze critical sections line-by-line\n3. Verify every assumption and state\n4. Check security and performance\n\n**WORKING NOTES:**\n- Line-by-Line Analysis\n- Security Vulnerabilities\n- Performance Bottlenecks",
+      "agentRole": "You are a forensic analyst performing exhaustive checks.",
+      "requireConfirmation": false,
+      "guidance": [
+        "LINE-BY-LINE: Analyze every single line",
+        "SECURITY: Check for injection, auth bypass, data leaks",
+        "PERFORMANCE: Check for N+1, loops, memory leaks"
+      ]
+    },
+    {
+      "id": "step-synthesize",
+      "title": "Step 5: Synthesize Findings",
+      "prompt": "**SYNTHESIZE FINDINGS**\n\nSynthesize all your findings from the execution steps.\n\n**MISSION:** Create a clear, actionable report.\n\n**EXECUTE:**\n1. Review all Working Notes\n2. Identify key patterns and insights\n3. Structure the final deliverable\n\n**DELIVERABLE:**\nCreate `{deliverableName}`:\n- Summary\n- Detailed Findings (by depth)\n- Suspicious Points\n- Gaps & Limitations\n- Recommendations",
+      "agentRole": "You are a senior consultant synthesizing insights.",
+      "requireConfirmation": false,
+      "guidance": [
+        "SYNTHESIS: Connect the dots, don't just list facts",
+        "ACTIONABLE: Give clear next steps",
+        "CITED: Support everything with file:line refs"
+      ]
+    }
+  ]
+}