@exaudeus/workrail 0.8.2 → 0.8.5

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,88 @@ 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()) {
+                    if (entry.name === 'examples') {
+                        continue;
+                    }
+                    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/package.json

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

package/workflows/bug-investigation.agentic.json

@@ -1,8 +1,8 @@
 {
   "id": "bug-investigation",
   "name": "Bug Investigation (Agentic)",
-  "version": "2.0.0-beta",
-  "description": "An Agentic-enhanced bug investigation workflow. Supports Subagent Delegation for research and hypothesis generation.",
+  "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)",
@@ -40,8 +40,8 @@
     {
       "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**CHOOSE YOUR EXECUTION PATH:**\n\n**PATH A: DELEGATE (If you have a Researcher Subagent)**\nInstruct your Researcher Subagent to execute the `routine-context-gathering` workflow. Tell them:\n> \"Run the context gathering routine. Focus on identifying the files related to this bug description: [Insert Bug Description].\"\n\n**PATH B: PROXY (If your Subagent cannot use tools)**\nAct as a proxy for your Researcher. Read the steps from `routine-context-gathering` yourself, and instruct your subagent via natural language to perform the scans.\n\n**PATH C: SOLO (If you have no Subagent)**\nPerform the setup yourself.\n\n**Your Task**: Set up everything you need for a systematic investigation.\n\n**Questions to Answer**:\n- What exactly is the reported problem?\n- What's the expected vs actual behavior?\n- How is it reproduced?\n- What error messages or symptoms exist?\n- What information do you have (logs, stack traces, etc.)?\n- What tools and access do you have?\n- What workspace do you need (branch, investigation directory)?\n\n**Set Up**:\n- Create INVESTIGATION_CONTEXT.md to track your investigation\n- Document the bug description and reproduction steps\n- Note any 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- 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?",
-      "agentRole": "You are beginning your investigation. Take time to understand what you're looking for before you start looking.",
+      "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
     },
     {
@@ -68,8 +68,8 @@
     {
       "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**Prioritize**:\nRank by:\n1. Likelihood (evidence strength)\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, 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. Stay open to alternatives even if one seems obvious.",
+      "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
     },
     {
@@ -82,8 +82,8 @@
     {
       "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**Implement**:\n- Add debug logging at the points you identified\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\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. Good instrumentation is the foundation of proof.",
+      "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
     },
     {
@@ -96,8 +96,8 @@
     {
       "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**Challenge Yourself (Adversarial Review)**:\n\n1. **Alternative Explanations**: What else could explain the evidence you collected?\n2. **Contradicting Evidence**: What evidence doesn't fit your conclusion?\n3. **Bias Check**: Are you seeing what you expect to see?\n4. **Completeness**: Does this explain ALL symptoms, or just some?\n5. **Edge Cases**: Does your explanation hold for all scenarios?\n6. **Reproducibility**: Can you reliably reproduce the bug based on your understanding?\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\n**OUTPUT**: ValidationReport.md with:\n- Leading hypothesis and evidence\n- Alternatives considered and ruled out\n- Adversarial review findings\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 rigorously. Be skeptical of your own findings.",
+      "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
     },
     {

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"
+      ]
+    }
+  ]
+}

package/workflows/routines/execution-simulation.json

@@ -0,0 +1,84 @@
+{
+  "id": "routine-execution-simulation",
+  "name": "Execution Simulation Routine",
+  "version": "1.1.0",
+  "description": "Simulates code execution step-by-step through mental tracing and state tracking. Uses an Ideate -> Plan -> Execute strategy to identify the best simulation paths before tracing.",
+  "clarificationPrompts": [
+    "What function should I simulate? (function name, file, line)",
+    "What is the goal? (e.g., understand failure, trace happy path)",
+    "What inputs or conditions are relevant?",
+    "How deep should I trace? (shallow, follow all calls, until error)"
+  ],
+  "preconditions": [
+    "Target code is available",
+    "Goal is clear",
+    "Agent has read access to all relevant code files"
+  ],
+  "metaGuidance": [
+    "**ROUTINE PURPOSE:**",
+    "This routine simulates code execution mentally. It deliberately separates deciding WHAT to simulate from the actual simulation.",
+    "**PHASES:**",
+    "1. IDEATE: Brainstorm possible execution paths and scenarios",
+    "2. PLAN: Select the best scenario and define inputs/state",
+    "3. EXECUTE: Perform the step-by-step mental trace",
+    "4. ANALYZE: Identify divergence and root cause",
+    "**CORE PRINCIPLES:**",
+    "- THINK BEFORE TRACING: Don't start tracing until you have a plan",
+    "- DEFINE INPUTS FIRST: Know exactly what values you're passing in",
+    "- MENTAL EXECUTION: Simulate in your mind, don't run code",
+    "- PRECISION: Cite file:line for every step"
+  ],
+  "steps": [
+    {
+      "id": "step-0-ideate-scenarios",
+      "title": "Step 0: Ideate Simulation Scenarios",
+      "prompt": "**EXPLORE EXECUTION PATHS**\n\nBefore you start tracing, look at the code and brainstorm what scenarios are worth simulating.\n\n**YOUR MISSION:** Identify possible execution paths and scenarios relevant to the goal.\n\n**EXECUTE:**\n1. Read the target function and its dependencies\n2. Identify the control flow (if/else branches, loops, error handling)\n3. Brainstorm 3-5 possible execution scenarios (e.g., Happy Path, Invalid Input, Network Error)\n4. For each scenario, identify:\n   - What inputs/state trigger it?\n   - What makes it interesting/relevant?\n   - How complex is it to trace?\n\n**REFLECT:**\n- Did I miss any edge cases?\n- Which scenario is most likely to reveal the issue?\n- Are there dependencies I need to understand first?\n\n**WORKING NOTES:**\n- Target Function Summary\n- List of Scenarios (Option A, B, C...)\n- Pros/Cons of simulating each\n- Key dependencies identified",
+      "agentRole": "You are an explorer mapping out the territory. You're looking for the most interesting paths to investigate.",
+      "requireConfirmation": false,
+      "guidance": [
+        "BRAINSTORM: Don't settle for the first path you see",
+        "DIVERSITY: Include success, failure, and edge case scenarios",
+        "TRIGGERS: Be specific about what inputs trigger each path",
+        "RELEVANCE: Focus on scenarios that align with the user's goal"
+      ]
+    },
+    {
+      "id": "step-1-plan-simulation",
+      "title": "Step 1: Plan the Simulation Strategy",
+      "prompt": "**DEFINE THE SIMULATION PLAN**\n\nNow select the best scenario and define the exact parameters for your trace.\n\n**YOUR MISSION:** Create a concrete plan for the simulation so you don't get lost while tracing.\n\n**EXECUTE:**\n1. Select the most relevant scenario from Step 0\n2. Define the **Entry Point** (function, file, line)\n3. Define the exact **Inputs** (parameters, arguments)\n4. Define the **Initial State** (global variables, database state, environment)\n5. Define the **Trace Depth** (how deep to go into function calls)\n6. Note specific **Watch Variables** (state to track closely)\n\n**REFLECT:**\n- Do I have all the values I need?\n- Is the scope manageable?\n- Will this path give me the answer I need?\n\n**DELIVERABLE:**\nCreate `simulation-plan.md` with:\n- Selected Scenario\n- Entry Point (file:line)\n- Concrete Inputs (JSON/values)\n- Initial State\n- Trace Strategy (depth, focus)\n- Expected Outcome",
+      "agentRole": "You are a test engineer designing a precise test case. Specificity is key.",
+      "requireConfirmation": false,
+      "guidance": [
+        "CONCRETE VALUES: Don't use abstract inputs, pick specific values (e.g., user_id=123)",
+        "SCOPE: Define clearly when to stop tracing (depth)",
+        "STATE: Don't forget implicit state (config, env vars)",
+        "FOCUS: Identify what variables matter most"
+      ]
+    },
+    {
+      "id": "step-2-trace-execution",
+      "title": "Step 2: Execute the Mental Trace",
+      "prompt": "**EXECUTE THE TRACE**\n\nNow perform the mental execution following your plan exactly.\n\n**YOUR MISSION:** Simulate execution line-by-line, tracking state changes.\n\n**EXECUTE:**\nFollow `simulation-plan.md`:\n1. Start at Entry Point with defined Inputs\n2. For each line:\n   - Cite file:line\n   - Show code\n   - Show state BEFORE\n   - Show state AFTER\n   - Note result (Success/Error)\n3. Track all Watch Variables\n4. Follow function calls according to depth strategy\n5. Stop when completion or error is reached\n\n**WORKING NOTES:**\nCreate detailed execution trace:\n- Step N: Line X\n- State changes\n- Function calls\n- Results",
+      "agentRole": "You are a CPU executing instructions. Be mechanical, precise, and track state without guessing.",
+      "requireConfirmation": false,
+      "guidance": [
+        "FOLLOW PLAN: Stick to the inputs and state defined in Step 1",
+        "NO GUESSING: If state is unknown, mark it as UNKNOWN",
+        "CITATIONS: File:line for every step",
+        "STATE TRACKING: Explicitly show variable values changing"
+      ]
+    },
+    {
+      "id": "step-3-analyze-results",
+      "title": "Step 3: Analyze Divergence & Root Cause",
+      "prompt": "**ANALYZE THE TRACE**\n\nNow look at your trace to understand what happened.\n\n**YOUR MISSION:** Identify where execution went wrong and why.\n\n**EXECUTE:**\n1. Compare Actual Outcome vs Expected Outcome\n2. Identify the **Divergence Point** (exact line where it went off track)\n3. Analyze the **Root Cause** (why did it diverge?)\n4. Check if other scenarios (from Step 0) would have behaved differently\n5. Formulate a fix recommendation\n\n**DELIVERABLE:**\nCreate `simulation-report.md`:\n- Summary\n- Execution Trace (from Step 2)\n- Divergence Analysis\n- Root Cause\n- Recommendations",
+      "agentRole": "You are a forensic analyst connecting the dots. Turn the trace into insights.",
+      "requireConfirmation": false,
+      "guidance": [
+        "ROOT CAUSE: distinguish between the error (symptom) and the cause (bug)",
+        "EVIDENCE: Point to specific steps in the trace",
+        "FIX: Suggest how to correct the logic"
+      ]
+    }
+  ]
+}

package/workflows/routines/feature-implementation.json

@@ -0,0 +1,119 @@
+{
+  "id": "routine-feature-implementation",
+  "name": "Feature Implementation Routine",
+  "version": "1.0.0",
+  "description": "Implements code precisely according to detailed plans and specifications. Follows existing patterns, writes tests, and maintains code quality. Designed for delegation to Builder subagent or manual execution by main agent.",
+  "clarificationPrompts": [
+    "What plan file should I implement? (e.g., implementation-plan.md)",
+    "What files should I modify or create?",
+    "What patterns should I follow? (pattern docs, example files)",
+    "What are the acceptance criteria?"
+  ],
+  "preconditions": [
+    "Implementation plan is available as a file",
+    "Target files are identified (modify/create)",
+    "Patterns and examples are available",
+    "Acceptance criteria are clearly defined",
+    "Agent has write access to codebase"
+  ],
+  "metaGuidance": [
+    "**ROUTINE PURPOSE:**",
+    "This routine implements code following a detailed plan. It emphasizes precision, pattern adherence, incremental progress, and thorough testing.",
+    "**CORE PRINCIPLES:**",
+    "- FOLLOW THE PLAN: Implement exactly as specified, don't improvise",
+    "- MATCH PATTERNS: Follow existing codebase conventions",
+    "- TEST AS YOU GO: Write tests for each step before moving on",
+    "- FLAG AMBIGUITIES: Don't guess, ask for clarification",
+    "**EXPECTED INPUT FORMAT:**",
+    "Plan: Must be a file reference (e.g., 'implementation-plan.md')",
+    "Target: List of files to modify or create",
+    "Context: { background: string, patterns: string[], userRules: string[], constraints: string[], priorWork: string[] }",
+    "Acceptance Criteria: List of requirements that must be met",
+    "**IMPLEMENTATION STRATEGY:**",
+    "Read-Implement-Test: For each step, read the plan, implement the code, write tests, verify tests pass, then move to next step",
+    "Incremental Verification: After each step, check compilation, tests, and pattern adherence",
+    "Flag Early: If you encounter ambiguity, missing patterns, or conflicts, stop and flag immediately"
+  ],
+  "steps": [
+    {
+      "id": "step-0-understand-plan",
+      "title": "Step 0: Understand the Plan",
+      "prompt": "**UNDERSTAND WHAT YOU'RE IMPLEMENTING**\n\nBefore writing any code, thoroughly understand the plan.\n\n**YOUR MISSION:** Comprehend the implementation plan, patterns, and constraints.\n\n**PLAN YOUR APPROACH:**\nBefore diving in, think:\n- What is this feature trying to accomplish?\n- What are the major steps in the plan?\n- What patterns should I follow?\n- What constraints must I respect?\n\n**EXECUTE:**\n1. Read the implementation plan file completely\n2. Break down the plan into discrete steps\n3. Identify dependencies between steps\n4. Read pattern documentation and example files\n5. Read user rules (.cursor/rules, .cursorrules)\n6. Note all constraints (backward compatibility, API stability, etc.)\n7. Review acceptance criteria\n8. Identify potential ambiguities or blockers\n\n**REFLECT:**\nAs you read, ask yourself:\n- Is the plan clear and complete?\n- Do I understand the patterns I need to follow?\n- Are there any ambiguities I need to flag?\n- Do I have all the information I need to proceed?\n- Are there any conflicts between constraints?\n\n**WORKING NOTES:**\nCapture your understanding:\n- Feature summary (what's being built)\n- Plan steps (numbered list)\n- Dependencies (what depends on what)\n- Patterns to follow (with file references)\n- User rules and constraints\n- Acceptance criteria checklist\n- Ambiguities or blockers (if any)",
+      "agentRole": "You are a disciplined implementer preparing to follow a plan precisely. Understand the landscape before writing code.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-1-implement-incrementally",
+      "title": "Step 1: Implement Step-by-Step",
+      "prompt": "**IMPLEMENT THE PLAN INCREMENTALLY**\n\nNow implement the plan, one step at a time, with testing and verification.\n\n**YOUR MISSION:** Implement each step of the plan precisely, following patterns and writing tests.\n\n**PLAN YOUR APPROACH:**\nBefore implementing, decide:\n- What order should I implement steps in?\n- How will I verify each step before moving on?\n- What tests do I need for each step?\n- How will I track my progress?\n\n**EXECUTE:**\nFor each step in the plan:\n\n1. **Read the Step**\n   - Understand what this step requires\n   - Identify files to modify/create\n   - Note the expected outcome\n\n2. **Implement the Code**\n   - Follow the plan exactly\n   - Match existing patterns\n   - Add/update inline comments\n   - Follow user rules and constraints\n\n3. **Write/Update Tests**\n   - Write unit tests for new functions\n   - Write integration tests for new features\n   - Update existing tests if needed\n   - Follow testing patterns\n\n4. **Verify**\n   - Run tests (ensure they pass)\n   - Check compilation/build\n   - Check linter\n   - Verify pattern adherence\n\n5. **Track Progress**\n   - Mark step as complete\n   - Note any deviations from plan\n   - Note any issues encountered\n\n6. **Move to Next Step**\n   - Only proceed if current step is verified\n   - If blocked, flag immediately\n\n**REFLECT:**\nAs you implement, ask yourself:\n- Am I following the plan exactly?\n- Am I matching the patterns?\n- Are my tests comprehensive?\n- Did I introduce any breaking changes?\n- Should I flag anything?\n\n**WORKING NOTES:**\nTrack your implementation:\n- Steps completed (with checkmarks)\n- Files modified (with summary of changes)\n- Files created (with purpose)\n- Tests added/updated (with results)\n- Deviations from plan (with reasons)\n- Issues flagged (with details)",
+      "agentRole": "You are implementing code step-by-step with discipline and precision. Follow the plan, match patterns, test thoroughly.",
+      "requireConfirmation": false,
+      "guidance": [
+        "INCREMENTAL: Implement one step at a time, verify before moving on",
+        "PATTERNS: Match existing code style, conventions, and architecture",
+        "TESTING: Write tests for every new function or feature",
+        "VERIFICATION: After each step, check compilation, tests, and linter",
+        "CITATIONS: Reference file:line for all changes",
+        "DEVIATIONS: If you deviate from the plan, note it explicitly with reason",
+        "AMBIGUITIES: If a step is unclear, flag it immediately (don't guess)",
+        "BREAKING CHANGES: Never introduce breaking changes without explicit approval",
+        "USER RULES: Respect all rules from .cursor/rules, .cursorrules",
+        "QUALITY: Maintain code quality (readability, maintainability, testability)",
+        "DOCUMENTATION: Update inline comments and docs as needed",
+        "PROGRESS TRACKING: Keep a running list of completed steps"
+      ]
+    },
+    {
+      "id": "step-2-verify-acceptance-criteria",
+      "title": "Step 2: Verify Acceptance Criteria",
+      "prompt": "**VERIFY ALL ACCEPTANCE CRITERIA ARE MET**\n\nNow verify that your implementation meets all acceptance criteria.\n\n**YOUR MISSION:** Systematically check each acceptance criterion and verify it's met.\n\n**PLAN YOUR APPROACH:**\nBefore verifying, think:\n- How will I test each criterion?\n- What evidence proves each criterion is met?\n- Are there any criteria I might have missed?\n- What manual testing should I do?\n\n**EXECUTE:**\nFor each acceptance criterion:\n\n1. **State the Criterion**\n   - Quote the exact criterion from the plan\n\n2. **Verify It's Met**\n   - Run relevant tests\n   - Perform manual testing if needed\n   - Check code implementation\n   - Gather evidence\n\n3. **Mark Status**\n   - \u2705 Met (with evidence)\n   - \u274c Not Met (with reason)\n   - \u26a0\ufe0f Partially Met (with details)\n\n4. **Provide Evidence**\n   - Test results\n   - Code references (file:line)\n   - Manual test outcomes\n   - Metrics or measurements\n\n**REFLECT:**\nAs you verify, ask yourself:\n- Did I test each criterion thoroughly?\n- Is my evidence convincing?\n- Are there edge cases I should test?\n- Did I miss any criteria?\n\n**WORKING NOTES:**\nCapture your verification:\n- Acceptance criteria checklist (with status)\n- Evidence for each criterion\n- Test results\n- Manual testing performed\n- Edge cases tested\n- Any criteria not met (with reasons)",
+      "agentRole": "You are a quality assurance specialist verifying that all requirements are met. Be thorough and provide evidence.",
+      "requireConfirmation": false,
+      "guidance": [
+        "SYSTEMATIC: Check each criterion one by one",
+        "EVIDENCE: Provide concrete evidence (test results, code refs, measurements)",
+        "THOROUGHNESS: Don't just check happy path, test edge cases",
+        "HONESTY: If a criterion isn't met, flag it clearly",
+        "MANUAL TESTING: Perform manual tests where appropriate",
+        "METRICS: If criteria involve performance, measure it",
+        "COMPLETENESS: Ensure you haven't missed any criteria",
+        "EDGE CASES: Test boundary conditions and error scenarios"
+      ]
+    },
+    {
+      "id": "step-3-run-full-verification",
+      "title": "Step 3: Run Full Verification Suite",
+      "prompt": "**RUN COMPREHENSIVE VERIFICATION**\n\nNow run a full verification suite to ensure everything works.\n\n**YOUR MISSION:** Verify build, tests, linter, and overall code quality.\n\n**PLAN YOUR APPROACH:**\nBefore running verification, think:\n- What verification steps should I run?\n- What order makes sense?\n- What should I do if something fails?\n- How will I document the results?\n\n**EXECUTE:**\n\n1. **Run All Tests**\n   - Run unit tests\n   - Run integration tests\n   - Run end-to-end tests (if applicable)\n   - Capture results\n\n2. **Check Build**\n   - Compile/build the project\n   - Check for type errors\n   - Check for compilation warnings\n   - Capture results\n\n3. **Check Linter**\n   - Run linter (ESLint, etc.)\n   - Check for warnings\n   - Check for errors\n   - Capture results\n\n4. **Manual Verification**\n   - Test critical paths manually\n   - Verify UI changes (if applicable)\n   - Test error scenarios\n   - Capture observations\n\n5. **Check for Breaking Changes**\n   - Review public API changes\n   - Verify backward compatibility\n   - Check for unintended side effects\n\n**REFLECT:**\nAs you verify, ask yourself:\n- Did everything pass?\n- Are there any warnings I should address?\n- Did I introduce any breaking changes?\n- Is the code production-ready?\n\n**WORKING NOTES:**\nCapture verification results:\n- Test results (pass/fail counts, output)\n- Build results (success/failure, warnings)\n- Linter results (errors, warnings)\n- Manual testing observations\n- Breaking changes identified (if any)\n- Overall status (ready/not ready)",
+      "agentRole": "You are running comprehensive verification to ensure production readiness. Be thorough and document everything.",
+      "requireConfirmation": false,
+      "guidance": [
+        "COMPREHENSIVE: Run all verification steps (tests, build, linter)",
+        "DOCUMENTATION: Capture all results (pass/fail, output, warnings)",
+        "MANUAL TESTING: Don't rely solely on automated tests",
+        "BREAKING CHANGES: Explicitly check for backward compatibility issues",
+        "WARNINGS: Address linter warnings, don't ignore them",
+        "ERROR SCENARIOS: Test error handling and edge cases",
+        "PRODUCTION READINESS: Assess if code is ready to deploy"
+      ]
+    },
+    {
+      "id": "step-4-synthesize-deliverable",
+      "title": "Step 4: Synthesize & Deliver Implementation Report",
+      "prompt": "**DELIVER YOUR IMPLEMENTATION REPORT**\n\nNow compile your work into a clear, comprehensive deliverable.\n\n**YOUR MISSION:** Create an implementation report that documents all changes, tests, and verification.\n\n**PLAN YOUR APPROACH:**\nBefore writing, think:\n- Who will read this and what do they need?\n- How can I make it easy to review?\n- What's the most important information?\n- How can I prove I met all criteria?\n\n**EXECUTE:**\nCreate your implementation report with these sections:\n\n1. **Summary** (3-5 bullets)\n   - What was implemented\n   - Key changes made\n   - Test coverage added\n   - Any deviations from plan\n\n2. **Implementation Details**\n   - Files modified (with summary of changes and code snippets)\n   - Files created (with purpose and key code)\n   - Files deleted (if any)\n   - Pattern adherence notes\n\n3. **Tests Added/Updated**\n   - New tests (with descriptions)\n   - Updated tests (with reasons)\n   - Test results (pass/fail counts)\n   - Test coverage metrics (if available)\n\n4. **Verification Steps**\n   - How to run tests\n   - How to check linter\n   - How to manually verify\n   - How to check metrics (if applicable)\n\n5. **Deviations from Plan**\n   - Any deviations (with reasons and impact)\n   - Approval status (needed/not needed)\n\n6. **Acceptance Criteria Status**\n   - Checklist of all criteria (\u2705/\u274c/\u26a0\ufe0f)\n   - Evidence for each\n   - Overall status\n\n7. **Known Issues / TODOs**\n   - Issues encountered\n   - TODOs for future work\n   - Blockers (if any)\n\n8. **Build & Lint Status**\n   - Build results\n   - Linter results\n   - Overall quality status\n\n**REFLECT:**\nBefore delivering, ask yourself:\n- Is my report complete and accurate?\n- Did I document all changes?\n- Can someone review this easily?\n- Did I provide enough evidence?\n- Are there any issues I should flag?\n\n**DELIVERABLE:**\nA comprehensive implementation report (markdown format) with all sections above.",
+      "agentRole": "You are a technical writer synthesizing your implementation work into a clear, reviewable report. Make it easy to understand and verify.",
+      "requireConfirmation": false,
+      "guidance": [
+        "STRUCTURE: Follow the 8-section format (Summary, Implementation, Tests, Verification, Deviations, Acceptance, Issues, Status)",
+        "CLARITY: Make it easy to review with clear headings and formatting",
+        "EVIDENCE: Include code snippets, test results, and verification output",
+        "COMPLETENESS: Document all changes, don't leave anything out",
+        "CITATIONS: Reference file:line for all changes",
+        "DEVIATIONS: Be transparent about any deviations from the plan",
+        "ISSUES: Flag any issues, blockers, or TODOs clearly",
+        "REVIEWABILITY: Organize information so someone can quickly assess quality",
+        "VERIFICATION: Provide clear steps for others to verify your work",
+        "HONESTY: If something isn't perfect, say so (don't hide issues)"
+      ]
+    }
+  ]
+}