@leclabs/agent-flow-navigator-mcp 1.2.0 → 1.4.0

package/catalog/workflows/agile-task.json

@@ -125,6 +125,12 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_failed",
+      "to": "implement",
+      "on": "passed",
+      "label": "Human resolved issue, resume"
     }
   ]
 }

package/catalog/workflows/bug-fix.json

@@ -148,6 +148,18 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_cannot_reproduce",
+      "to": "reproduce",
+      "on": "passed",
+      "label": "Human provided reproduction info, resume"
+    },
+    {
+      "from": "hitl_fix_failed",
+      "to": "write_fix",
+      "on": "passed",
+      "label": "Human resolved fix issue, resume"
     }
   ]
 }

package/catalog/workflows/build-review-murder-board.json

@@ -105,6 +105,12 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_blocked",
+      "to": "build",
+      "on": "passed",
+      "label": "Human resolved issue, resume"
     }
   ]
 }

package/catalog/workflows/build-review-quick.json

@@ -103,6 +103,12 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_blocked",
+      "to": "build",
+      "on": "passed",
+      "label": "Human resolved issue, resume"
     }
   ]
 }

package/catalog/workflows/context-optimization.json

@@ -61,12 +61,19 @@
       "name": "Complete",
       "description": "Context optimization complete"
     },
-    "hitl_failed": {
+    "hitl_design_failed": {
       "type": "end",
       "result": "blocked",
       "escalation": "hitl",
-      "name": "Needs Help",
-      "description": "Optimization needs human guidance"
+      "name": "Design Needs Help",
+      "description": "Design optimization needs human guidance"
+    },
+    "hitl_verify_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Verification Needs Help",
+      "description": "Verification needs human intervention"
     }
   },
   "edges": [
@@ -94,7 +101,7 @@
     },
     {
       "from": "review_design",
-      "to": "hitl_failed",
+      "to": "hitl_design_failed",
       "on": "failed",
       "label": "Design needs human input"
     },
@@ -116,7 +123,7 @@
     },
     {
       "from": "verify",
-      "to": "hitl_failed",
+      "to": "hitl_verify_failed",
       "on": "failed",
       "label": "Verification failed"
     },
@@ -125,6 +132,18 @@
       "to": "end_success",
       "on": "passed",
       "label": "Optimization verified"
+    },
+    {
+      "from": "hitl_design_failed",
+      "to": "design_improvements",
+      "on": "passed",
+      "label": "Human resolved design issue, resume"
+    },
+    {
+      "from": "hitl_verify_failed",
+      "to": "implement",
+      "on": "passed",
+      "label": "Human resolved verification issue, resume"
     }
   ]
 }

package/catalog/workflows/feature-development.json

@@ -220,6 +220,18 @@
     {
       "from": "create_pr",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_plan_failed",
+      "to": "create_plan",
+      "on": "passed",
+      "label": "Human resolved planning issue, resume"
+    },
+    {
+      "from": "hitl_impl_failed",
+      "to": "implement",
+      "on": "passed",
+      "label": "Human resolved implementation issue, resume"
     }
   ]
 }

package/catalog/workflows/hitl-test.json

@@ -0,0 +1,46 @@
+{
+  "id": "hitl-test",
+  "name": "HITL Test",
+  "description": "Minimal workflow for testing HITL recovery: work, gate, escalate, human resumes.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start"
+    },
+    "work": {
+      "type": "task",
+      "name": "Do Work",
+      "description": "Do the thing",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "check": {
+      "type": "gate",
+      "name": "Check",
+      "description": "Pass or fail",
+      "agent": "Reviewer",
+      "stage": "verification",
+      "maxRetries": 1
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Done"
+    },
+    "hitl_blocked": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Blocked",
+      "description": "Needs human help"
+    }
+  },
+  "edges": [
+    { "from": "start", "to": "work" },
+    { "from": "work", "to": "check" },
+    { "from": "check", "to": "end_success", "on": "passed" },
+    { "from": "check", "to": "work", "on": "failed", "label": "Retry" },
+    { "from": "check", "to": "hitl_blocked", "on": "failed", "label": "Escalate" },
+    { "from": "hitl_blocked", "to": "work", "on": "passed", "label": "Human fixed it, resume" }
+  ]
+}

package/catalog/workflows/quick-task.json

@@ -110,6 +110,12 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_blocked",
+      "to": "execute",
+      "on": "passed",
+      "label": "Human resolved issue, resume"
     }
   ]
 }

package/catalog/workflows/refactor.json

@@ -231,6 +231,18 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_analysis_failed",
+      "to": "design_refactor",
+      "on": "passed",
+      "label": "Human resolved analysis issue, resume"
+    },
+    {
+      "from": "hitl_dev_failed",
+      "to": "extract_core",
+      "on": "passed",
+      "label": "Human resolved development issue, resume"
     }
   ]
 }

package/catalog/workflows/test-coverage.json

@@ -148,6 +148,12 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_failed",
+      "to": "write_tests",
+      "on": "passed",
+      "label": "Human resolved issue, resume"
     }
   ]
 }

package/catalog/workflows/ui-reconstruction.json

@@ -236,6 +236,24 @@
     {
       "from": "commit",
       "to": "end_success"
+    },
+    {
+      "from": "hitl_ir_failed",
+      "to": "ir_component_tree",
+      "on": "passed",
+      "label": "Human resolved IR issue, resume"
+    },
+    {
+      "from": "hitl_build_failed",
+      "to": "uiRebuild_build",
+      "on": "passed",
+      "label": "Human resolved build issue, resume"
+    },
+    {
+      "from": "hitl_final_failed",
+      "to": "uiRebuild_build",
+      "on": "passed",
+      "label": "Human resolved final review issue, resume"
     }
   ]
 }

package/engine.js

@@ -14,6 +14,7 @@
  */
 
 import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
 
 /**
  * Read and parse a task file
@@ -52,16 +53,56 @@ export function getTerminalType(node) {
 }
 
 /**
- * Convert agent ID to subagent reference
- * e.g., "developer" -> "@flow:developer"
+ * Return agent ID as-is from workflow definition.
+ * Prefixing (e.g., @flow:) is the caller's responsibility.
  */
 export function toSubagentRef(agentId) {
   if (!agentId) return null;
-  if (agentId.startsWith("@")) return agentId;
-  // Namespaced: "org:developer" -> "@org:developer"
-  if (agentId.includes(":")) return `@${agentId}`;
-  // Simple: "developer" -> "@flow:developer"
-  return `@flow:${agentId}`;
+  return agentId;
+}
+
+/**
+ * Workflow emoji mapping for task subjects
+ */
+const WORKFLOW_EMOJIS = {
+  "feature-development": "✨",
+  "bug-fix": "🐛",
+  "agile-task": "📋",
+  "context-optimization": "🔧",
+  "quick-task": "⚡",
+  "ui-reconstruction": "🎨",
+  "test-coverage": "🧪",
+};
+
+/**
+ * Build formatted task subject for write-through
+ */
+export function buildTaskSubject(taskId, userDescription, workflowType, stepId, subagent, terminal, maxRetries, retryCount) {
+  const emoji = WORKFLOW_EMOJIS[workflowType] || "";
+  const line1 = `#${taskId} ${userDescription}${emoji ? ` ${emoji}` : ""}`;
+
+  let line2;
+  if (terminal === "success") {
+    line2 = `→ ${workflowType} · completed ✓`;
+  } else if (terminal === "hitl" || terminal === "failure") {
+    line2 = `→ ${workflowType} · ${stepId} · HITL`;
+  } else {
+    const agent = subagent ? `(${subagent})` : "(direct)";
+    const retries = maxRetries > 0 ? ` · retries: ${retryCount}/${maxRetries}` : "";
+    line2 = `→ ${workflowType} · ${stepId} ${agent}${retries}`;
+  }
+
+  return `${line1}\n${line2}`;
+}
+
+/**
+ * Build activeForm for task spinner display
+ */
+export function buildTaskActiveForm(stepName, subagent, terminal) {
+  if (terminal === "success") return "Completed";
+  if (terminal === "hitl" || terminal === "failure") return "HITL - Needs human help";
+  const agent = subagent ? ` (${subagent})` : "";
+  return `${stepName}${agent}`;
 }
 
 /**
@@ -71,8 +112,13 @@ export function getBaselineInstructions(stepId, stepName) {
   const id = stepId.toLowerCase();
   const name = (stepName || "").toLowerCase();
 
-  // Analysis/Planning steps
-  if (id.includes("analyze") || id.includes("analysis") || name.includes("analyze")) {
+  // Review steps (checked early — "plan_review" is a review, not a plan)
+  if (id.includes("review")) {
+    return "Check for correctness, code quality, and adherence to project standards. Verify the implementation meets requirements.";
+  }
+
+  // Analysis/Requirements steps
+  if (id.includes("analyze") || id.includes("analysis") || id.includes("parse") || id.includes("requirements") || name.includes("analyze")) {
     return "Review the task requirements carefully. Identify key constraints, dependencies, and acceptance criteria. Create a clear plan before proceeding.";
   }
   if (id.includes("plan") || id.includes("design") || name.includes("plan")) {
@@ -90,16 +136,16 @@ export function getBaselineInstructions(stepId, stepName) {
     return "Improve code structure without changing behavior. Ensure all tests pass before and after changes.";
   }
 
+  // Lint/format steps
+  if (id.includes("lint") || id.includes("format")) {
+    return "Run linting and formatting checks. Auto-fix issues where possible. Flag any issues that require manual attention.";
+  }
+
   // Testing steps
   if (id.includes("test") || id.includes("verify") || id.includes("validate")) {
     return "Verify the implementation works correctly. Test happy paths, edge cases, and error conditions. Document any issues found.";
   }
 
-  // Review steps
-  if (id.includes("review")) {
-    return "Check for correctness, code quality, and adherence to project standards. Verify the implementation meets requirements.";
-  }
-
   // Documentation steps
   if (id.includes("document") || id.includes("readme")) {
     return "Write clear, concise documentation. Focus on what users need to know, not implementation details.";
@@ -127,18 +173,61 @@ export function getBaselineInstructions(stepId, stepName) {
   return "Complete this step thoroughly. Document your findings and any decisions made.";
 }
 
+/**
+ * Resolve a context_files entry to an absolute path.
+ *
+ * Convention (follows Claude Code plugin path rules):
+ * - "./path" → relative to the workflow's source root (plugin root, project root, etc.)
+ * - "path"   → relative to projectRoot
+ *
+ * @param {string} file - Context file entry
+ * @param {string} projectRoot - Project root directory
+ * @param {string|null} sourceRoot - Root directory of the workflow's source
+ * @returns {string} Absolute file path
+ */
+export function resolveContextFile(file, projectRoot, sourceRoot) {
+  if (file.startsWith("./") && sourceRoot) {
+    return join(sourceRoot, file);
+  }
+  return join(projectRoot, file);
+}
+
+/**
+ * Resolve ./ prefixed paths in prose text against sourceRoot.
+ * Leaves text unchanged when sourceRoot is null or text has no ./ references.
+ * @param {string|null} text - Prose text that may contain ./ paths
+ * @param {string|null} sourceRoot - Root directory for ./ resolution
+ * @returns {string|null} Text with ./ paths resolved to absolute paths
+ */
+export function resolveProseRefs(text, sourceRoot) {
+  if (!text || !sourceRoot) return text;
+  return text.replace(/\.\/[\w\-\.\/]+/g, (match) => join(sourceRoot, match));
+}
+
+/**
+ * Build context loading instructions from step-level context_files.
+ * Returns a markdown section or null if no context declared.
+ */
+export function buildContextInstructions({ contextFiles, projectRoot, sourceRoot }) {
+  if (!contextFiles?.length || !projectRoot) return null;
+  const lines = contextFiles.map((file) => `- Read file: ${resolveContextFile(file, projectRoot, sourceRoot)}`);
+  return `## Context\n\nBefore beginning, load the following:\n${lines.join("\n")}`;
+}
+
 /**
  * Build orchestrator instructions for task creation/update
  * Returns null for terminal nodes (no further work)
  */
-function buildOrchestratorInstructions(workflowType, stepId, stage, subagent, stepInstructions, description) {
+function buildOrchestratorInstructions(workflowType, stepId, stage, subagent, stepInstructions, description, contextBlock) {
   if (!stepInstructions) return null; // Terminal nodes have no instructions
 
   const delegationPrefix = subagent ? `Invoke ${subagent} to complete the following task: ` : "";
 
-  return `${delegationPrefix}${stepInstructions.guidance}
+  let result = `${delegationPrefix}${stepInstructions.guidance}
 
 ${description || "{task description}"}`;
+  if (contextBlock) result += `\n\n${contextBlock}`;
+  return result;
 }
 
 /**
@@ -152,31 +241,46 @@ function buildNavigateResponse(
   action,
   retriesIncremented = false,
   retryCount = 0,
-  description = null
+  description = null,
+  resetRetryCount = false,
+  projectRoot = null,
+  sourceRoot = null
 ) {
   const stage = stepDef.stage || null;
   const subagent = stepDef.agent ? toSubagentRef(stepDef.agent) : null;
 
   // Build step instructions from workflow definition + baseline
+  // Resolve ./ paths in prose fields against sourceRoot (same convention as context_files)
   const isTerminal = isTerminalNode(stepDef);
   const stepInstructions = isTerminal
     ? null
     : {
         name: stepDef.name || stepId,
-        description: stepDef.description || null,
-        guidance: stepDef.instructions || getBaselineInstructions(stepId, stepDef.name),
+        description: resolveProseRefs(stepDef.description, sourceRoot) || null,
+        guidance: resolveProseRefs(stepDef.instructions, sourceRoot) || getBaselineInstructions(stepId, stepDef.name),
       };
 
+  // Build context block from step-level context_files
+  const contextBlock = isTerminal
+    ? null
+    : buildContextInstructions({ contextFiles: stepDef.context_files, projectRoot, sourceRoot });
+
   // Build orchestrator instructions for all non-terminal actions
   const orchestratorInstructions = isTerminal
     ? null
-    : buildOrchestratorInstructions(workflowType, stepId, stage, subagent, stepInstructions, description);
+    : buildOrchestratorInstructions(workflowType, stepId, stage, subagent, stepInstructions, description, contextBlock);
 
   // Build metadata for task storage
+  // Increment on retry, reset on start or explicit forward progress (conditional advance),
+  // preserve on unconditional advances within retry loops and escalations
   const metadata = {
     workflowType,
     currentStep: stepId,
-    retryCount: retriesIncremented ? retryCount + 1 : retryCount,
+    retryCount: retriesIncremented
+      ? retryCount + 1
+      : action === "start" || resetRetryCount
+        ? 0
+        : retryCount,
   };
 
   return {
@@ -187,6 +291,7 @@ function buildNavigateResponse(
     terminal: getTerminalType(stepDef),
     action,
     retriesIncremented,
+    maxRetries: stepDef.maxRetries || 0,
     orchestratorInstructions,
     metadata,
   };
@@ -357,7 +462,7 @@ export class WorkflowEngine {
    * @param {string} [options.description] - User's task description
    * @returns {Object} Navigation response with currentStep, stepInstructions, terminal, action, metadata, etc.
    */
-  navigate({ taskFilePath, workflowType, result, description } = {}) {
+  navigate({ taskFilePath, workflowType, result, description, projectRoot } = {}) {
     let currentStep = null;
     let retryCount = 0;
 
@@ -397,6 +502,9 @@ export class WorkflowEngine {
       throw new Error(`Workflow '${workflowType}' must have nodes`);
     }
 
+    // Resolve source root for context_files with ./ prefix
+    const sourceRoot = this.store.getSourceRoot?.(workflowType) || null;
+
     const { nodes } = wfDef;
 
     // Case 1: No currentStep - start at first work step
@@ -417,7 +525,7 @@ export class WorkflowEngine {
         throw new Error(`First step '${firstEdge.to}' not found in workflow`);
       }
 
-      return buildNavigateResponse(workflowType, firstEdge.to, firstStepDef, "start", false, 0, description);
+      return buildNavigateResponse(workflowType, firstEdge.to, firstStepDef, "start", false, 0, description, false, projectRoot, sourceRoot);
     }
 
     // Case 2: currentStep but no result - return current state
@@ -427,7 +535,7 @@ export class WorkflowEngine {
         throw new Error(`Step '${currentStep}' not found in workflow '${workflowType}'`);
       }
 
-      return buildNavigateResponse(workflowType, currentStep, stepDef, "current", false, retryCount, description);
+      return buildNavigateResponse(workflowType, currentStep, stepDef, "current", false, retryCount, description, false, projectRoot, sourceRoot);
     }
 
     // Case 3: currentStep and result - advance to next step
@@ -447,9 +555,13 @@ export class WorkflowEngine {
     }
 
     // Determine action and whether retries incremented
+    const currentStepDef = nodes[currentStep];
+    const isHitlResume = getTerminalType(currentStepDef) === "hitl";
     const isRetry = evaluation.action === "retry";
     let action;
-    if (isRetry) {
+    if (isHitlResume) {
+      action = "advance"; // Human fixed it → fresh advance, retryCount resets
+    } else if (isRetry) {
       action = "retry";
     } else if (getTerminalType(nextStepDef) === "hitl") {
       action = "escalate";
@@ -457,6 +569,10 @@ export class WorkflowEngine {
       action = "advance";
     }
 
+    // Only reset retryCount on genuine forward progress (conditional edge like on:"passed")
+    // Unconditional advances within retry loops (e.g., work → gate) preserve the count
+    const resetRetryCount = action === "advance" && evaluation.action === "conditional";
+
     const response = buildNavigateResponse(
       workflowType,
       evaluation.nextStep,
@@ -464,14 +580,30 @@ export class WorkflowEngine {
       action,
       isRetry,
       retryCount,
-      description
+      description,
+      resetRetryCount,
+      projectRoot,
+      sourceRoot
     );
 
-    // Write-through: persist state transition to task file
+    // Write-through: persist state transition and presentation to task file
     if (taskFilePath) {
       const task = readTaskFile(taskFilePath);
       if (task) {
+        const userDesc = task.metadata?.userDescription || "";
         task.metadata = { ...task.metadata, ...response.metadata };
+        task.subject = buildTaskSubject(
+          task.id, userDesc, response.metadata.workflowType,
+          response.currentStep, response.subagent, response.terminal,
+          response.maxRetries, response.metadata.retryCount
+        );
+        task.activeForm = buildTaskActiveForm(
+          response.stepInstructions?.name || response.currentStep,
+          response.subagent, response.terminal
+        );
+        if (response.orchestratorInstructions) {
+          task.description = response.orchestratorInstructions;
+        }
         writeFileSync(taskFilePath, JSON.stringify(task, null, 2));
       }
     }

package/index.js

@@ -10,6 +10,7 @@
  * - ListWorkflows: List available workflows
  * - Diagram: Generate mermaid diagram for workflow
  * - CopyWorkflows: Copy workflows from catalog to project
+ * - LoadWorkflows: Load workflows from a directory at runtime (external plugins or project reload)
  * - ListCatalog: List workflows available in catalog
  */
 
@@ -101,23 +102,51 @@ function loadCatalogWorkflows(dirPath) {
   return loaded;
 }
 
+/**
+ * Load external workflows from a directory: flat {id}.json files
+ * Used by the LoadWorkflows tool at runtime.
+ * @param {string} dirPath - Directory containing {id}.json workflow files
+ * @param {string} sourceRoot - Root path for resolving ./ context_files
+ * @returns {string[]} Array of loaded workflow IDs
+ */
+function loadExternalWorkflows(dirPath, sourceRoot) {
+  if (!existsSync(dirPath)) return [];
+
+  const loaded = [];
+  const files = readdirSync(dirPath).filter((f) => f.endsWith(".json"));
+
+  for (const file of files) {
+    const id = file.replace(".json", "");
+    try {
+      const content = JSON.parse(readFileSync(join(dirPath, file), "utf-8"));
+      if (validateWorkflow(id, content)) {
+        store.loadDefinition(id, content, "external", sourceRoot);
+        loaded.push(id);
+      }
+    } catch (e) {
+      console.error(`Error loading external workflow ${id}: ${e.message}`);
+    }
+  }
+
+  return loaded;
+}
+
 /**
  * Load workflows: catalog first, then project overwrites (project takes precedence)
  */
 function loadWorkflows() {
   const catalogPath = join(CATALOG_PATH, "workflows");
   const catalogLoaded = loadCatalogWorkflows(catalogPath);
-
   const projectLoaded = existsSync(WORKFLOWS_PATH) ? loadProjectWorkflows(WORKFLOWS_PATH) : [];
 
-  // Determine which IDs came from where (project overwrites catalog)
-  const fromCatalog = catalogLoaded.filter((id) => !projectLoaded.includes(id));
+  const allLoaded = [...new Set([...catalogLoaded, ...projectLoaded])];
   const fromProject = projectLoaded;
+  const fromCatalog = catalogLoaded.filter((id) => !projectLoaded.includes(id));
 
   return {
     catalog: fromCatalog,
     project: fromProject,
-    loaded: [...new Set([...catalogLoaded, ...projectLoaded])],
+    loaded: allLoaded,
   };
 }
 
@@ -186,6 +215,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             workflowType: { type: "string", description: "Workflow ID to visualize" },
             currentStep: { type: "string", description: "Optional: highlight this step" },
+            filePath: {
+              type: "string",
+              description: "Optional: absolute path to save the diagram. Defaults to .flow/diagrams/{workflowType}.md",
+            },
           },
           required: ["workflowType"],
         },
@@ -205,6 +238,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
         },
       },
+      {
+        name: "LoadWorkflows",
+        description:
+          "Load workflows from a directory at runtime. External plugins pass their root path; omit path to reload project workflows.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description:
+                "Directory containing {id}.json workflow files. Omit to reload project workflows from .flow/workflows/.",
+            },
+            sourceRoot: {
+              type: "string",
+              description:
+                "Root path for resolving ./ context_files entries. Defaults to path (or project root when path omitted).",
+            },
+          },
+        },
+      },
       {
         name: "ListCatalog",
         description: "List workflows available in the catalog.",
@@ -229,6 +282,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           workflowType: args.workflowType,
           result: args.result,
           description: args.description,
+          projectRoot: PROJECT_ROOT,
         });
         return jsonResponse(result);
       }
@@ -264,11 +318,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const source = store.getSource(args.workflowType);
         const markdown = generateDiagram(wfDef, args.currentStep);
 
-        // Save diagram to file
-        if (!existsSync(DIAGRAMS_PATH)) {
-          mkdirSync(DIAGRAMS_PATH, { recursive: true });
+        // Save diagram to file (use provided path or default)
+        const filePath = args.filePath || join(DIAGRAMS_PATH, `${args.workflowType}.md`);
+        const fileDir = dirname(filePath);
+        if (!existsSync(fileDir)) {
+          mkdirSync(fileDir, { recursive: true });
         }
-        const filePath = join(DIAGRAMS_PATH, `${args.workflowType}.md`);
         writeFileSync(filePath, markdown);
 
         return jsonResponse({ savedTo: filePath, source });
@@ -331,6 +386,32 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         });
       }
 
+      case "LoadWorkflows": {
+        if (args.path) {
+          // External plugin: load from provided path
+          const dirPath = resolve(args.path);
+          const root = args.sourceRoot ? resolve(args.sourceRoot) : dirPath;
+          const loaded = loadExternalWorkflows(dirPath, root);
+          return jsonResponse({
+            schemaVersion: 2,
+            loaded,
+            source: "external",
+            sourceRoot: root,
+            path: dirPath,
+          });
+        } else {
+          // Project: reload from .flow/workflows/
+          const loaded = existsSync(WORKFLOWS_PATH) ? loadProjectWorkflows(WORKFLOWS_PATH) : [];
+          return jsonResponse({
+            schemaVersion: 2,
+            loaded,
+            source: "project",
+            sourceRoot: PROJECT_ROOT,
+            path: WORKFLOWS_PATH,
+          });
+        }
+      }
+
       case "ListCatalog": {
         const catalogPath = join(CATALOG_PATH, "workflows");
         if (!existsSync(catalogPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leclabs/agent-flow-navigator-mcp",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "MCP server that navigates agents through DAG-based workflows",
   "license": "MIT",
   "author": "leclabs",

package/store.js

@@ -29,19 +29,24 @@ export function validateWorkflow(id, content) {
 export class WorkflowStore {
   constructor() {
     this.workflows = new Map();
-    this.sources = new Map(); // Track source: "catalog" | "project"
+    this.sources = new Map(); // Track source: "catalog" | "project" | "external"
+    this.sourceRoots = new Map(); // Track source root path per workflow (for ./ resolution)
   }
 
   /**
    * Load a workflow definition into the store
    * @param {string} id - Workflow identifier
    * @param {Object} workflow - Workflow definition
-   * @param {string} source - Source: "catalog" | "project"
+   * @param {string} source - Source: "catalog" | "project" | "external"
+   * @param {string|null} sourceRoot - Root path for resolving ./ context_files
    * @returns {string} The workflow id
    */
-  loadDefinition(id, workflow, source = "catalog") {
+  loadDefinition(id, workflow, source = "catalog", sourceRoot = null) {
     this.workflows.set(id, workflow);
     this.sources.set(id, source);
+    if (sourceRoot) {
+      this.sourceRoots.set(id, sourceRoot);
+    }
     return id;
   }
 
@@ -56,7 +61,7 @@ export class WorkflowStore {
 
   /**
    * List all loaded workflows with metadata
-   * @param {string} filter - Filter by source: "all" | "project" | "catalog"
+   * @param {string} filter - Filter by source: "all" | "project" | "catalog" | "external"
    * @returns {Array} Array of workflow summaries
    */
   listWorkflows(filter = "all") {
@@ -86,6 +91,17 @@ export class WorkflowStore {
     return false;
   }
 
+  /**
+   * Check if any external workflows exist
+   * @returns {boolean}
+   */
+  hasExternalWorkflows() {
+    for (const source of this.sources.values()) {
+      if (source === "external") return true;
+    }
+    return false;
+  }
+
   /**
    * Get the source of a workflow
    * @param {string} id - Workflow identifier
@@ -95,6 +111,15 @@ export class WorkflowStore {
     return this.sources.get(id);
   }
 
+  /**
+   * Get the source root path for a workflow (for ./ context_files resolution)
+   * @param {string} id - Workflow identifier
+   * @returns {string|undefined} Source root path or undefined
+   */
+  getSourceRoot(id) {
+    return this.sourceRoots.get(id);
+  }
+
   /**
    * Check if a workflow exists
    * @param {string} id - Workflow identifier
@@ -110,6 +135,7 @@ export class WorkflowStore {
   clear() {
     this.workflows.clear();
     this.sources.clear();
+    this.sourceRoots.clear();
   }
 
   /**

package/types.d.ts

@@ -51,6 +51,7 @@ export interface TaskNode {
   outputs?: string[];
   maxRetries?: number;
   config?: Record<string, unknown>;
+  context_files?: string[];
 }
 
 /**
@@ -66,6 +67,7 @@ export interface GateNode {
   outputs?: string[];
   maxRetries?: number;
   config?: Record<string, unknown>;
+  context_files?: string[];
 }
 
 /**
@@ -131,3 +133,47 @@ export type EdgeAction =
   | "escalate" // Failed and exceeded retry limit
   | "no_outgoing_edges" // Terminal node (no edges)
   | "no_matching_edge"; // No edge matched the output
+
+// =============================================================================
+// Navigate Options
+// =============================================================================
+
+export interface NavigateOptions {
+  taskFilePath?: string;
+  workflowType?: string;
+  result?: "passed" | "failed";
+  description?: string;
+  projectRoot?: string;
+}
+
+// =============================================================================
+// Context Resolution
+// =============================================================================
+
+/**
+ * Resolve a context_files entry to an absolute path.
+ * - "./path" → relative to sourceRoot (the workflow's source directory)
+ * - "path"   → relative to projectRoot
+ */
+export function resolveContextFile(
+  file: string,
+  projectRoot: string,
+  sourceRoot?: string | null
+): string;
+
+export function resolveProseRefs(
+  text: string | null,
+  sourceRoot: string | null
+): string | null;
+
+export function buildContextInstructions(options: {
+  contextFiles?: string[];
+  projectRoot?: string | null;
+  sourceRoot?: string | null;
+}): string | null;
+
+// =============================================================================
+// Store Types
+// =============================================================================
+
+export type WorkflowSource = "catalog" | "project" | "external";