@leclabs/agent-flow-navigator-mcp 1.3.0 → 1.4.1

package/engine.js

@@ -77,7 +77,16 @@ const WORKFLOW_EMOJIS = {
 /**
  * Build formatted task subject for write-through
  */
-export function buildTaskSubject(taskId, userDescription, workflowType, stepId, subagent, terminal, maxRetries, retryCount) {
+export function buildTaskSubject(
+  taskId,
+  userDescription,
+  workflowType,
+  stepId,
+  subagent,
+  terminal,
+  maxRetries,
+  retryCount
+) {
   const emoji = WORKFLOW_EMOJIS[workflowType] || "";
   const line1 = `#${taskId} ${userDescription}${emoji ? ` ${emoji}` : ""}`;
 
@@ -118,7 +127,13 @@ export function getBaselineInstructions(stepId, stepName) {
   }
 
   // Analysis/Requirements steps
-  if (id.includes("analyze") || id.includes("analysis") || id.includes("parse") || id.includes("requirements") || name.includes("analyze")) {
+  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")) {
@@ -173,13 +188,44 @@ 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 }) {
+export function buildContextInstructions({ contextFiles, projectRoot, sourceRoot }) {
   if (!contextFiles?.length || !projectRoot) return null;
-  const lines = contextFiles.map((file) => `- Read file: ${join(projectRoot, file)}`);
+  const lines = contextFiles.map((file) => `- Read file: ${resolveContextFile(file, projectRoot, sourceRoot)}`);
   return `## Context\n\nBefore beginning, load the following:\n${lines.join("\n")}`;
 }
 
@@ -187,7 +233,15 @@ export function buildContextInstructions({ contextFiles, projectRoot }) {
  * Build orchestrator instructions for task creation/update
  * Returns null for terminal nodes (no further work)
  */
-function buildOrchestratorInstructions(workflowType, stepId, stage, subagent, stepInstructions, description, contextBlock) {
+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: ` : "";
@@ -212,25 +266,27 @@ function buildNavigateResponse(
   retryCount = 0,
   description = null,
   resetRetryCount = false,
-  projectRoot = null
+  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 });
+    : buildContextInstructions({ contextFiles: stepDef.context_files, projectRoot, sourceRoot });
 
   // Build orchestrator instructions for all non-terminal actions
   const orchestratorInstructions = isTerminal
@@ -243,11 +299,7 @@ function buildNavigateResponse(
   const metadata = {
     workflowType,
     currentStep: stepId,
-    retryCount: retriesIncremented
-      ? retryCount + 1
-      : action === "start" || resetRetryCount
-        ? 0
-        : retryCount,
+    retryCount: retriesIncremented ? retryCount + 1 : action === "start" || resetRetryCount ? 0 : retryCount,
   };
 
   return {
@@ -261,6 +313,7 @@ function buildNavigateResponse(
     maxRetries: stepDef.maxRetries || 0,
     orchestratorInstructions,
     metadata,
+    sourceRoot,
   };
 }
 
@@ -469,6 +522,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
@@ -489,7 +545,18 @@ export class WorkflowEngine {
         throw new Error(`First step '${firstEdge.to}' not found in workflow`);
       }
 
-      return buildNavigateResponse(workflowType, firstEdge.to, firstStepDef, "start", false, 0, description, false, projectRoot);
+      return buildNavigateResponse(
+        workflowType,
+        firstEdge.to,
+        firstStepDef,
+        "start",
+        false,
+        0,
+        description,
+        false,
+        projectRoot,
+        sourceRoot
+      );
     }
 
     // Case 2: currentStep but no result - return current state
@@ -499,7 +566,18 @@ export class WorkflowEngine {
         throw new Error(`Step '${currentStep}' not found in workflow '${workflowType}'`);
       }
 
-      return buildNavigateResponse(workflowType, currentStep, stepDef, "current", false, retryCount, description, false, projectRoot);
+      return buildNavigateResponse(
+        workflowType,
+        currentStep,
+        stepDef,
+        "current",
+        false,
+        retryCount,
+        description,
+        false,
+        projectRoot,
+        sourceRoot
+      );
     }
 
     // Case 3: currentStep and result - advance to next step
@@ -546,7 +624,8 @@ export class WorkflowEngine {
       retryCount,
       description,
       resetRetryCount,
-      projectRoot
+      projectRoot,
+      sourceRoot
     );
 
     // Write-through: persist state transition and presentation to task file
@@ -556,13 +635,19 @@ export class WorkflowEngine {
         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.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
+          response.subagent,
+          response.terminal
         );
         if (response.orchestratorInstructions) {
           task.description = response.orchestratorInstructions;

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
  */
 
@@ -45,30 +46,25 @@ const store = new WorkflowStore();
 const engine = new WorkflowEngine(store);
 
 /**
- * Load workflows from project directory structure: {id}/workflow.json
+ * Load workflows from catalog: flat {id}.json files
  */
-function loadProjectWorkflows(dirPath) {
+function loadCatalogWorkflows(dirPath) {
   if (!existsSync(dirPath)) return [];
 
   const loaded = [];
-  const entries = readdirSync(dirPath, { withFileTypes: true });
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-
-    const id = entry.name;
-    const workflowFile = join(dirPath, id, "workflow.json");
+  const files = readdirSync(dirPath).filter((f) => f.endsWith(".json"));
 
-    if (!existsSync(workflowFile)) continue;
+  for (const file of files) {
+    const id = file.replace(".json", "");
 
     try {
-      const content = JSON.parse(readFileSync(workflowFile, "utf-8"));
+      const content = JSON.parse(readFileSync(join(dirPath, file), "utf-8"));
       if (validateWorkflow(id, content)) {
-        store.loadDefinition(id, content, "project");
+        store.loadDefinition(id, content, "catalog");
         loaded.push(id);
       }
     } catch (e) {
-      console.error(`Error loading workflow ${id}: ${e.message}`);
+      console.error(`Error loading catalog workflow ${id}: ${e.message}`);
     }
   }
 
@@ -76,25 +72,48 @@ function loadProjectWorkflows(dirPath) {
 }
 
 /**
- * Load workflows from catalog: flat {id}.json files
+ * 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 loadCatalogWorkflows(dirPath) {
+function loadExternalWorkflows(dirPath, sourceRoot) {
   if (!existsSync(dirPath)) return [];
 
   const loaded = [];
-  const files = readdirSync(dirPath).filter((f) => f.endsWith(".json"));
+  const entries = readdirSync(dirPath, { withFileTypes: true });
 
-  for (const file of files) {
-    const id = file.replace(".json", "");
+  for (const entry of entries) {
+    // Flat format: {id}.json
+    if (entry.isFile() && entry.name.endsWith(".json")) {
+      const id = entry.name.replace(".json", "");
+      try {
+        const content = JSON.parse(readFileSync(join(dirPath, entry.name), "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}`);
+      }
+      continue;
+    }
 
-    try {
-      const content = JSON.parse(readFileSync(join(dirPath, file), "utf-8"));
-      if (validateWorkflow(id, content)) {
-        store.loadDefinition(id, content, "catalog");
-        loaded.push(id);
+    // Directory format: {id}/workflow.json
+    if (entry.isDirectory()) {
+      const wfFile = join(dirPath, entry.name, "workflow.json");
+      if (!existsSync(wfFile)) continue;
+      const id = entry.name;
+      try {
+        const content = JSON.parse(readFileSync(wfFile, "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}`);
       }
-    } catch (e) {
-      console.error(`Error loading catalog workflow ${id}: ${e.message}`);
     }
   }
 
@@ -108,16 +127,9 @@ 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 fromProject = projectLoaded;
-
   return {
-    catalog: fromCatalog,
-    project: fromProject,
-    loaded: [...new Set([...catalogLoaded, ...projectLoaded])],
+    catalog: catalogLoaded,
+    loaded: catalogLoaded,
   };
 }
 
@@ -209,6 +221,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
         },
       },
+      {
+        name: "LoadWorkflows",
+        description:
+          "Load workflows at runtime. External plugins pass path + sourceRoot. For project workflows, pass workflowIds to load specific workflows from .flow/workflows/.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "Directory containing {id}.json workflow files. For external plugins only.",
+            },
+            sourceRoot: {
+              type: "string",
+              description:
+                "Root path for resolving ./ context_files entries. Defaults to path. For external plugins only.",
+            },
+            workflowIds: {
+              type: "array",
+              items: { type: "string" },
+              description:
+                "Specific workflow IDs to load from .flow/workflows/. Required when loading project workflows (no path). Omit to list available workflows without loading.",
+            },
+          },
+        },
+      },
       {
         name: "ListCatalog",
         description: "List workflows available in the catalog.",
@@ -337,6 +374,81 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         });
       }
 
+      case "LoadWorkflows": {
+        if (args.path) {
+          // External plugin: load all 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,
+          });
+        }
+
+        // Project: require explicit workflowIds or list available
+        if (!existsSync(WORKFLOWS_PATH)) {
+          return jsonResponse({
+            schemaVersion: 2,
+            available: [],
+            loaded: [],
+            source: "project",
+            path: WORKFLOWS_PATH,
+            hint: "No .flow/workflows/ directory found. Use /flow:init to set up workflows.",
+          });
+        }
+
+        const available = readdirSync(WORKFLOWS_PATH, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && existsSync(join(WORKFLOWS_PATH, e.name, "workflow.json")))
+          .map((e) => e.name);
+
+        if (!args.workflowIds || args.workflowIds.length === 0) {
+          // List only — don't load
+          return jsonResponse({
+            schemaVersion: 2,
+            available,
+            loaded: [],
+            source: "project",
+            path: WORKFLOWS_PATH,
+            hint: "Pass workflowIds to load specific workflows.",
+          });
+        }
+
+        // Load only the requested workflows
+        const loaded = [];
+        const errors = [];
+        for (const id of args.workflowIds) {
+          if (!available.includes(id)) {
+            errors.push({ id, error: "not found in .flow/workflows/" });
+            continue;
+          }
+          const wfFile = join(WORKFLOWS_PATH, id, "workflow.json");
+          try {
+            const content = JSON.parse(readFileSync(wfFile, "utf-8"));
+            if (validateWorkflow(id, content)) {
+              store.loadDefinition(id, content, "project");
+              loaded.push(id);
+            } else {
+              errors.push({ id, error: "invalid schema" });
+            }
+          } catch (e) {
+            errors.push({ id, error: e.message });
+          }
+        }
+
+        return jsonResponse({
+          schemaVersion: 2,
+          available,
+          loaded,
+          errors: errors.length > 0 ? errors : undefined,
+          source: "project",
+          path: WORKFLOWS_PATH,
+        });
+      }
+
       case "ListCatalog": {
         const catalogPath = join(CATALOG_PATH, "workflows");
         if (!existsSync(catalogPath)) {
@@ -371,31 +483,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
-/**
- * Ensure .flow/README.md exists (created on MCP server connect)
- */
-function ensureFlowReadme() {
-  const readmePath = join(FLOW_PATH, "README.md");
-  if (!existsSync(readmePath)) {
-    mkdirSync(FLOW_PATH, { recursive: true });
-    writeFileSync(readmePath, generateFlowReadme());
-    console.error(`  Created: ${readmePath}`);
-  }
-}
-
-// Load workflows and start server
+// Load catalog workflows and start server
 const workflowInfo = loadWorkflows();
-ensureFlowReadme();
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
 
 console.error(`Navigator MCP Server v2 running (stateless)`);
 console.error(`  Project: ${PROJECT_ROOT}`);
-console.error(`  Workflows: ${workflowInfo.loaded.length} total`);
-if (workflowInfo.catalog.length > 0) {
-  console.error(`    Catalog: ${workflowInfo.catalog.join(", ")}`);
-}
-if (workflowInfo.project.length > 0) {
-  console.error(`    Project: ${workflowInfo.project.join(", ")}`);
-}
+console.error(`  Catalog: ${workflowInfo.catalog.length} workflows`);
+console.error(`  Project/external workflows: load via LoadWorkflows tool`);

package/package.json

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

package/store.js

@@ -29,19 +29,26 @@ 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);
+    } else {
+      this.sourceRoots.delete(id);
+    }
     return id;
   }
 
@@ -56,7 +63,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 +93,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 +113,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 +137,7 @@ export class WorkflowStore {
   clear() {
     this.workflows.clear();
     this.sources.clear();
+    this.sourceRoots.clear();
   }
 
   /**

package/types.d.ts

@@ -133,3 +133,40 @@ 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";