@leclabs/agent-flow-navigator-mcp 1.5.2 → 1.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@leclabs/agent-flow-navigator-mcp)](https://npmjs.com/package/@leclabs/agent-flow-navigator-mcp)
 
-A workflow state machine MCP server that navigates agents through DAG-based workflows.
+A workflow state machine MCP server that navigates agents through graph-based workflows.
 
 Navigator tracks task state and evaluates graph edges -- it tells the orchestrator _where to go next_, but doesn't drive. Think of it like a GPS: you tell it where you are and what happened, it tells you where to go.
 
@@ -145,13 +145,13 @@ Lists workflows available in the built-in catalog. No parameters.
 
 ### Key Concepts
 
-| Concept                 | Description                                                                           |
-| ----------------------- | ------------------------------------------------------------------------------------- |
-| **Workflow Definition** | A DAG blueprint describing how to execute a type of work (nodes + conditional edges)  |
-| **Navigate 3-Mode API** | Start a workflow, get current state, or advance -- one tool, three calling patterns   |
-| **Write-Through**       | State transitions are persisted to the task file atomically on every advance          |
-| **Conditional Edges**   | Edges with `on` condition (passed/failed) -- retry logic is on nodes via `maxRetries` |
-| **HITL Escalation**     | When retries are exhausted, tasks route to end nodes with `escalation: "hitl"`        |
+| Concept                 | Description                                                                            |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| **Workflow Definition** | A graph blueprint describing how to execute a type of work (nodes + conditional edges) |
+| **Navigate 3-Mode API** | Start a workflow, get current state, or advance -- one tool, three calling patterns    |
+| **Write-Through**       | State transitions are persisted to the task file atomically on every advance           |
+| **Conditional Edges**   | Edges with `on` condition (passed/failed) -- retry logic is on nodes via `maxRetries`  |
+| **HITL Escalation**     | When retries are exhausted, tasks route to end nodes with `escalation: "hitl"`         |
 
 ## Workflow Definition Schema
 
@@ -163,6 +163,8 @@ Lists workflows available in the built-in catalog. No parameters.
 | `end`     | Exit point with `result` (success/failure/blocked/cancelled) |
 | `task`    | Executable work unit                                         |
 | `gate`    | Quality gate / review checkpoint                             |
+| `fork`    | Fan out into parallel branches (paired with a `join`)        |
+| `join`    | Collect parallel branches back together                      |
 | `subflow` | Connector to another workflow                                |
 
 ### End Node Properties
@@ -193,6 +195,77 @@ Lists workflows available in the built-in catalog. No parameters.
 | `label`     | Human-readable edge description                                |
 | `condition` | Expression for future conditional routing (informational)      |
 
+### Fork/Join (Parallel Branches)
+
+Fork/join lets a workflow fan out into parallel investigation tracks that converge at a join point. Each fork must be paired 1:1 with a join, and nested forks are not supported.
+
+#### Fork Node
+
+```json
+{
+  "type": "fork",
+  "name": "Fork Investigation",
+  "join": "join_investigate",
+  "branches": {
+    "reproduce": {
+      "entryStep": "reproduce",
+      "description": "Try to trigger the bug"
+    },
+    "code_archaeology": {
+      "entryStep": "code_archaeology",
+      "description": "Trace code paths related to symptoms"
+    }
+  }
+}
+```
+
+| Property   | Description                                                    |
+| ---------- | -------------------------------------------------------------- |
+| `join`     | ID of the paired join node (required)                          |
+| `branches` | Map of branch name to `{ entryStep, description? }` (required) |
+
+Each branch's `entryStep` must reference an existing task/gate node in the workflow. The orchestrator creates a child task per branch and runs them from their entry step.
+
+#### Join Node
+
+```json
+{
+  "type": "join",
+  "name": "Join Investigation",
+  "fork": "fork_investigate",
+  "strategy": "all-pass"
+}
+```
+
+| Property   | Description                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------------- |
+| `fork`     | ID of the paired fork node (required)                                                        |
+| `strategy` | `"all-pass"` (all branches must pass) or `"any-pass"` (one is enough). Default: `"all-pass"` |
+
+#### Edges
+
+Wire the fork and join like any other nodes. Branches run from their `entryStep` until they reach the join node via normal edges:
+
+```json
+{ "from": "triage", "to": "fork_investigate" },
+{ "from": "fork_investigate", "to": "reproduce" },
+{ "from": "fork_investigate", "to": "code_archaeology" },
+{ "from": "reproduce", "to": "join_investigate" },
+{ "from": "code_archaeology", "to": "join_investigate" },
+{ "from": "join_investigate", "to": "synthesize", "on": "passed" },
+{ "from": "join_investigate", "to": "hitl_inconclusive", "on": "failed" }
+```
+
+The join node supports conditional edges (`on: "passed"` / `on: "failed"`) so the workflow can route to different paths depending on whether the branches succeeded.
+
+#### Validation Rules
+
+- Fork and join must reference each other (1:1 pairing)
+- All branch `entryStep` values must reference existing nodes
+- Branch entry steps cannot be fork nodes (no nesting)
+
+See `catalog/workflows/bug-hunt.json` for a complete working example.
+
 ## Testing
 
 ```bash

package/catalog/workflows/bug-hunt.json

@@ -0,0 +1,242 @@
+{
+  "id": "bug-hunt",
+  "name": "Bug Hunt",
+  "description": "Parallel investigation workflow for vague bug reports. Fans out into reproduction, code archaeology, and git forensics tracks, then synthesizes findings into a root cause analysis and fix.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start",
+      "description": "Bug hunt begins"
+    },
+    "triage": {
+      "type": "task",
+      "name": "Triage Report",
+      "description": "Parse the vague report. Extract symptoms, affected area, timing, severity. Form 2-3 hypotheses to test.",
+      "agent": "Investigator",
+      "stage": "planning"
+    },
+    "fork_investigate": {
+      "type": "fork",
+      "name": "Fork Investigation",
+      "join": "join_investigate",
+      "branches": {
+        "reproduce": {
+          "entryStep": "reproduce",
+          "description": "Try to trigger the bug"
+        },
+        "code_archaeology": {
+          "entryStep": "code_archaeology",
+          "description": "Trace code paths related to symptoms"
+        },
+        "git_forensics": {
+          "entryStep": "git_forensics",
+          "description": "Check recent commits and git blame"
+        }
+      }
+    },
+    "reproduce": {
+      "type": "task",
+      "name": "Reproduce Bug",
+      "description": "Try to trigger the bug. Document exact reproduction steps, environment, and observed vs expected behavior.",
+      "agent": "Tester",
+      "stage": "investigation"
+    },
+    "code_archaeology": {
+      "type": "task",
+      "name": "Code Archaeology",
+      "description": "Trace the code paths related to the reported symptoms. Map data flow, identify suspect modules, check edge cases.",
+      "agent": "Investigator",
+      "stage": "investigation"
+    },
+    "git_forensics": {
+      "type": "task",
+      "name": "Git Forensics",
+      "description": "Check recent commits touching affected areas. Run git blame on suspect files. Look for correlated changes or regressions.",
+      "agent": "Investigator",
+      "stage": "investigation"
+    },
+    "join_investigate": {
+      "type": "join",
+      "name": "Join Investigation",
+      "fork": "fork_investigate",
+      "strategy": "all-pass"
+    },
+    "synthesize": {
+      "type": "task",
+      "name": "Synthesize Findings",
+      "description": "Combine findings from all investigation tracks into a root cause analysis. Identify the most likely cause, supporting evidence, and a fix strategy.",
+      "agent": "Architect",
+      "stage": "planning"
+    },
+    "write_fix": {
+      "type": "task",
+      "name": "Write Fix",
+      "description": "Implement the fix with minimal changes",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "add_regression_test": {
+      "type": "task",
+      "name": "Add Regression Test",
+      "description": "Write a test that would have caught this bug",
+      "agent": "Tester",
+      "stage": "development"
+    },
+    "verify_fix": {
+      "type": "gate",
+      "name": "Verify Fix",
+      "description": "Run tests, verify fix addresses root cause",
+      "agent": "Tester",
+      "stage": "verification",
+      "maxRetries": 3
+    },
+    "lint_format": {
+      "type": "gate",
+      "name": "Lint & Format",
+      "description": "Run lint and format checks. Auto-fix issues where possible.",
+      "agent": "Developer",
+      "stage": "delivery",
+      "maxRetries": 3
+    },
+    "commit": {
+      "type": "task",
+      "name": "Commit Changes",
+      "description": "Commit the fix and regression test with a descriptive message",
+      "agent": "Developer",
+      "stage": "delivery"
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Bug Fixed",
+      "description": "Bug hunted down and fixed"
+    },
+    "hitl_inconclusive": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Inconclusive",
+      "description": "Investigation tracks couldn't determine root cause - needs human context"
+    },
+    "hitl_fix_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Fix Failed",
+      "description": "Unable to fix the bug - needs human help"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "triage"
+    },
+    {
+      "from": "triage",
+      "to": "fork_investigate"
+    },
+    {
+      "from": "fork_investigate",
+      "to": "reproduce",
+      "label": "Branch: reproduce"
+    },
+    {
+      "from": "fork_investigate",
+      "to": "code_archaeology",
+      "label": "Branch: code archaeology"
+    },
+    {
+      "from": "fork_investigate",
+      "to": "git_forensics",
+      "label": "Branch: git forensics"
+    },
+    {
+      "from": "reproduce",
+      "to": "join_investigate"
+    },
+    {
+      "from": "code_archaeology",
+      "to": "join_investigate"
+    },
+    {
+      "from": "git_forensics",
+      "to": "join_investigate"
+    },
+    {
+      "from": "join_investigate",
+      "to": "synthesize",
+      "on": "passed",
+      "label": "All tracks complete"
+    },
+    {
+      "from": "join_investigate",
+      "to": "hitl_inconclusive",
+      "on": "failed",
+      "label": "Investigation couldn't determine root cause"
+    },
+    {
+      "from": "synthesize",
+      "to": "write_fix"
+    },
+    {
+      "from": "write_fix",
+      "to": "add_regression_test"
+    },
+    {
+      "from": "add_regression_test",
+      "to": "verify_fix"
+    },
+    {
+      "from": "verify_fix",
+      "to": "lint_format",
+      "on": "passed",
+      "label": "Fix verified, run lint checks"
+    },
+    {
+      "from": "verify_fix",
+      "to": "write_fix",
+      "on": "failed",
+      "label": "Fix didn't work, try again"
+    },
+    {
+      "from": "verify_fix",
+      "to": "hitl_fix_failed",
+      "on": "failed",
+      "label": "Cannot fix the bug"
+    },
+    {
+      "from": "lint_format",
+      "to": "commit",
+      "on": "passed",
+      "label": "Lint passes, commit changes"
+    },
+    {
+      "from": "lint_format",
+      "to": "write_fix",
+      "on": "failed",
+      "label": "Fix lint/format issues"
+    },
+    {
+      "from": "lint_format",
+      "to": "hitl_fix_failed",
+      "on": "failed",
+      "label": "Lint issues persist"
+    },
+    {
+      "from": "commit",
+      "to": "end_success"
+    },
+    {
+      "from": "hitl_inconclusive",
+      "to": "triage",
+      "on": "passed",
+      "label": "Human provided context, re-triage"
+    },
+    {
+      "from": "hitl_fix_failed",
+      "to": "write_fix",
+      "on": "passed",
+      "label": "Human resolved issue, resume fix"
+    }
+  ]
+}

package/copier.js

@@ -12,7 +12,7 @@
 export function generateFlowReadme() {
   return `# Flow Plugin
 
-DAG-based workflow orchestration for AI agents.
+Graph-based workflow orchestration for AI agents.
 
 ## Quick Start
 
@@ -65,7 +65,7 @@ This directory contains workflow definitions for the flow plugin.
 .flow/workflows/
 ├── README.md              # This file
 └── {workflow}/
-    └── workflow.json      # DAG definition (steps + edges)
+    └── workflow.json      # Workflow definition (steps + edges)
 \`\`\`
 
 ## How Step Instructions Work
@@ -105,11 +105,11 @@ To add custom instructions for a step, add an \`instructions\` field to the node
 
 ### workflow.json
 
-Defines the workflow DAG:
+Defines the workflow graph:
 - \`nodes\`: Map of node definitions (type, name, description, agent, maxRetries)
 - \`edges\`: Array of transitions between nodes (from, to, on, label)
 
-Do NOT edit edge logic unless you understand DAG flow control.
+Do NOT edit edge logic unless you understand workflow flow control.
 
 ## Adding Custom Workflows
 
@@ -135,8 +135,8 @@ export function isValidWorkflowForCopy(content) {
  * @returns {string[]} IDs to copy
  */
 export function computeWorkflowsToCopy(requestedIds, availableIds) {
-  if (requestedIds && requestedIds.length > 0) {
-    return requestedIds;
+  if (!requestedIds || requestedIds.length === 0) {
+    throw new Error("workflowIds is required. Use ListCatalog to see available workflows, then pass specific IDs.");
   }
-  return availableIds;
+  return requestedIds;
 }

package/diagram.js

@@ -58,6 +58,8 @@ export function generateDiagram(workflowDef, currentStep = null) {
       lines.push(`    ${stepId}[["${label}"]]`);
     } else if (termType === "hitl" || termType === "failure") {
       lines.push(`    ${stepId}{{"${label}"}}`);
+    } else if (step.type === "fork" || step.type === "join") {
+      lines.push(`    ${stepId}{{{"${label}"}}}`);
     } else if (step.type === "gate") {
       lines.push(`    ${stepId}{"${label}"}`);
     } else {
@@ -82,6 +84,7 @@ export function generateDiagram(workflowDef, currentStep = null) {
   lines.push("    classDef successStep fill:#87CEEB,stroke:#4169E1");
   lines.push("    classDef hitlStep fill:#FFB6C1,stroke:#DC143C");
   lines.push("    classDef gateStep fill:#E6E6FA,stroke:#9370DB");
+  lines.push("    classDef forkJoinStep fill:#FFEAA7,stroke:#FDCB6E");
   lines.push("    classDef currentStep fill:#FFD700,stroke:#FF8C00,stroke-width:3px");
 
   const startSteps = Object.entries(nodes)
@@ -97,10 +100,15 @@ export function generateDiagram(workflowDef, currentStep = null) {
     .filter(([, s]) => s.type === "gate")
     .map(([id]) => id);
 
+  const forkJoinSteps = Object.entries(nodes)
+    .filter(([, s]) => s.type === "fork" || s.type === "join")
+    .map(([id]) => id);
+
   if (startSteps.length) lines.push(`    class ${startSteps.join(",")} startStep`);
   if (successSteps.length) lines.push(`    class ${successSteps.join(",")} successStep`);
   if (hitlSteps.length) lines.push(`    class ${hitlSteps.join(",")} hitlStep`);
   if (gateSteps.length) lines.push(`    class ${gateSteps.join(",")} gateStep`);
+  if (forkJoinSteps.length) lines.push(`    class ${forkJoinSteps.join(",")} forkJoinStep`);
 
   if (currentStep && nodes[currentStep]) {
     lines.push(`    class ${currentStep} currentStep`);
@@ -111,8 +119,10 @@ export function generateDiagram(workflowDef, currentStep = null) {
   tableRows.push("| Stage | Step | Name | Agent | Instructions |");
   tableRows.push("|-------|------|------|-------|--------------|");
 
-  // Group steps by stage for organized display - filter out terminal/start/end nodes
-  const stepEntries = Object.entries(nodes).filter(([, step]) => !isTerminalNode(step));
+  // Group steps by stage for organized display - filter out terminal/start/end and fork/join nodes
+  const stepEntries = Object.entries(nodes).filter(
+    ([, step]) => !isTerminalNode(step) && step.type !== "fork" && step.type !== "join"
+  );
 
   for (const [stepId, step] of stepEntries) {
     const stage = step.stage || "-";

package/engine.js

@@ -1,7 +1,7 @@
 /**
  * Workflow Engine
  *
- * Evaluates DAG transitions based on node outputs and retry state.
+ * Evaluates graph transitions based on node outputs and retry state.
  *
  * Schema:
  * - nodes: { [id]: { type, name, maxRetries?, ... } }
@@ -32,12 +32,21 @@ export function readTaskFile(taskFilePath) {
 
 /**
  * Check if a node is a terminal node (start or end)
+ * Fork/join are control-flow nodes, not terminal.
  */
 export function isTerminalNode(node) {
   if (!node) return false;
   return node.type === "start" || node.type === "end";
 }
 
+/**
+ * Check if a node is a fork or join control-flow node
+ */
+export function isForkJoinNode(node) {
+  if (!node) return false;
+  return node.type === "fork" || node.type === "join";
+}
+
 /**
  * Get terminal type for a node
  * Returns: "start" | "success" | "hitl" | "failure" | null
@@ -67,6 +76,7 @@ export function toSubagentRef(agentId) {
 const WORKFLOW_EMOJIS = {
   "feature-development": "✨",
   "bug-fix": "🐛",
+  "bug-hunt": "🔍",
   "agile-task": "📋",
   "context-optimization": "🔧",
   "quick-task": "⚡",
@@ -253,6 +263,47 @@ ${description || "{task description}"}`;
   return result;
 }
 
+/**
+ * Build response for fork/join control-flow nodes.
+ * These nodes are declarative — the engine returns metadata for the orchestrator to act on.
+ */
+function buildForkJoinResponse(workflowType, stepId, stepDef, action, retryCount = 0, sourceRoot = null) {
+  const base = {
+    currentStep: stepId,
+    stage: null,
+    subagent: null,
+    stepInstructions: null,
+    terminal: null,
+    action,
+    retriesIncremented: false,
+    autonomyContinued: false,
+    maxRetries: 0,
+    orchestratorInstructions: null,
+    metadata: {
+      workflowType,
+      currentStep: stepId,
+      retryCount,
+    },
+    sourceRoot,
+  };
+
+  if (stepDef.type === "fork") {
+    base.action = "fork";
+    base.fork = {
+      branches: stepDef.branches,
+      joinStep: stepDef.join,
+    };
+  } else if (stepDef.type === "join") {
+    base.action = "join";
+    base.join = {
+      forkStep: stepDef.fork,
+      strategy: stepDef.strategy || "all-pass",
+    };
+  }
+
+  return base;
+}
+
 /**
  * Build unified response shape for Navigate
  * Minimal output: only what Orchestrator needs for control flow and delegation
@@ -481,9 +532,10 @@ export class WorkflowEngine {
    * @param {string} [options.workflowType] - Workflow ID (for start only)
    * @param {string} [options.result] - Step result: "passed" | "failed" (for advance)
    * @param {string} [options.description] - User's task description
+   * @param {string} [options.stepId] - Start at a specific step (mid-flow recovery). Only used when starting a workflow (no currentStep).
    * @returns {Object} Navigation response with currentStep, stepInstructions, terminal, action, metadata, etc.
    */
-  navigate({ taskFilePath, workflowType, result, description, projectRoot, autonomy } = {}) {
+  navigate({ taskFilePath, workflowType, result, description, projectRoot, autonomy, stepId } = {}) {
     let currentStep = null;
     let retryCount = 0;
 
@@ -533,28 +585,52 @@ export class WorkflowEngine {
 
     const { nodes } = wfDef;
 
-    // Case 1: No currentStep - start at first work step
+    // Case 1: No currentStep - start at first work step (or stepId if provided)
     if (!currentStep) {
-      const startEntry = Object.entries(nodes).find(([, node]) => node.type === "start");
-      if (!startEntry) {
-        throw new Error(`Workflow '${workflowType}' has no start node`);
-      }
-      const startStepId = startEntry[0];
+      let targetStepId;
+      let targetStepDef;
+
+      if (stepId) {
+        // Mid-flow start: validate and use the provided stepId
+        targetStepDef = nodes[stepId];
+        if (!targetStepDef) {
+          throw new Error(`Step '${stepId}' not found in workflow '${workflowType}'`);
+        }
+        if (isTerminalNode(targetStepDef)) {
+          throw new Error(
+            `Cannot start at ${targetStepDef.type} node '${stepId}'. Provide a task, gate, or fork/join step.`
+          );
+        }
+        targetStepId = stepId;
+      } else {
+        // Default: find first step after start node
+        const startEntry = Object.entries(nodes).find(([, node]) => node.type === "start");
+        if (!startEntry) {
+          throw new Error(`Workflow '${workflowType}' has no start node`);
+        }
+        const startNodeId = startEntry[0];
 
-      const firstEdge = wfDef.edges.find((e) => e.from === startStepId);
-      if (!firstEdge) {
-        throw new Error(`No edge from start step in workflow '${workflowType}'`);
+        const firstEdge = wfDef.edges.find((e) => e.from === startNodeId);
+        if (!firstEdge) {
+          throw new Error(`No edge from start step in workflow '${workflowType}'`);
+        }
+
+        targetStepDef = nodes[firstEdge.to];
+        if (!targetStepDef) {
+          throw new Error(`First step '${firstEdge.to}' not found in workflow`);
+        }
+        targetStepId = firstEdge.to;
       }
 
-      const firstStepDef = nodes[firstEdge.to];
-      if (!firstStepDef) {
-        throw new Error(`First step '${firstEdge.to}' not found in workflow`);
+      // Fork/join at start position — return control-flow response
+      if (isForkJoinNode(targetStepDef)) {
+        return buildForkJoinResponse(workflowType, targetStepId, targetStepDef, "start", 0, sourceRoot);
       }
 
       return buildNavigateResponse(
         workflowType,
-        firstEdge.to,
-        firstStepDef,
+        targetStepId,
+        targetStepDef,
         "start",
         false,
         0,
@@ -572,6 +648,11 @@ export class WorkflowEngine {
         throw new Error(`Step '${currentStep}' not found in workflow '${workflowType}'`);
       }
 
+      // Fork/join — return control-flow response
+      if (isForkJoinNode(stepDef)) {
+        return buildForkJoinResponse(workflowType, currentStep, stepDef, "current", retryCount, sourceRoot);
+      }
+
       return buildNavigateResponse(
         workflowType,
         currentStep,
@@ -602,6 +683,42 @@ export class WorkflowEngine {
       throw new Error(`Next step '${evaluation.nextStep}' not found in workflow`);
     }
 
+    // Fork/join on advance — return control-flow response
+    if (isForkJoinNode(nextStepDef)) {
+      const forkJoinResponse = buildForkJoinResponse(
+        workflowType,
+        evaluation.nextStep,
+        nextStepDef,
+        nextStepDef.type, // "fork" or "join"
+        0,
+        sourceRoot
+      );
+
+      // Write-through for fork/join advance
+      if (taskFilePath) {
+        const task = readTaskFile(taskFilePath);
+        if (task) {
+          const filenameId = basename(taskFilePath, ".json");
+          if (task.id !== filenameId) {
+            console.error(
+              `[Navigator] WARNING: task.id "${task.id}" does not match filename "${filenameId}.json" — auto-correcting`
+            );
+          }
+          const canonicalId = filenameId;
+          task.metadata = { ...task.metadata, ...forkJoinResponse.metadata };
+          task.id = canonicalId;
+          writeFileSync(taskFilePath, JSON.stringify(task, null, 2));
+        }
+      }
+
+      // Persist autonomy in metadata
+      if (autonomy) {
+        forkJoinResponse.metadata.autonomy = true;
+      }
+
+      return forkJoinResponse;
+    }
+
     // Determine action and whether retries incremented
     const currentStepDef = nodes[currentStep];
     const isHitlResume = getTerminalType(currentStepDef) === "hitl";

package/index.js

@@ -169,6 +169,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               description:
                 "When true, auto-continue through stage boundary end nodes (non-HITL end nodes with outgoing edges).",
             },
+            stepId: {
+              type: "string",
+              description:
+                "Start at a specific step instead of the beginning (mid-flow recovery). Only used when starting a workflow (no taskFilePath). Ignored during advance.",
+            },
           },
         },
       },
@@ -221,7 +226,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             workflowIds: {
               type: "array",
               items: { type: "string" },
-              description: "Workflow IDs to copy. Empty = all.",
+              description: "Workflow IDs to copy. Required. Use ListCatalog to see available workflows.",
             },
           },
         },
@@ -277,6 +282,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           description: args.description,
           projectRoot: PROJECT_ROOT,
           autonomy: args.autonomy,
+          stepId: args.stepId,
         });
         return jsonResponse(result);
       }
@@ -365,7 +371,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             writeFileSync(join(workflowDir, "workflow.json"), JSON.stringify(content, null, 2));
 
             // Load into memory
-            store.loadDefinition(id, content);
+            store.loadDefinition(id, content, "project", PROJECT_ROOT);
             copied.push(id);
           } catch (e) {
             errors.push({ id, error: e.message });
@@ -435,7 +441,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           try {
             const content = JSON.parse(readFileSync(wfFile, "utf-8"));
             if (validateWorkflow(id, content)) {
-              store.loadDefinition(id, content, "project");
+              store.loadDefinition(id, content, "project", PROJECT_ROOT);
               loaded.push(id);
             } else {
               errors.push({ id, error: "invalid schema" });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leclabs/agent-flow-navigator-mcp",
-  "version": "1.5.2",
-  "description": "MCP server that navigates agents through DAG-based workflows",
+  "version": "1.7.0",
+  "description": "MCP server that navigates agents through graph-based workflows",
   "license": "MIT",
   "author": "leclabs",
   "homepage": "https://github.com/leclabs/agent-toolkit",
@@ -15,7 +15,7 @@
   "type": "module",
   "scripts": {
     "start": "node index.js",
-    "test": "node --test engine.test.js diagram.test.js store.test.js dialog.test.js copier.test.js catalog.test.js refactor-workflow.test.js build-review-workflow.test.js"
+    "test": "node --test engine.test.js diagram.test.js store.test.js dialog.test.js copier.test.js catalog.test.js refactor-workflow.test.js build-review-workflow.test.js bug-hunt-workflow.test.js"
   },
   "keywords": [
     "mcp",

package/store.js

@@ -20,6 +20,73 @@ export function validateWorkflow(id, content) {
     console.error(`Invalid workflow ${id}: missing 'edges' array`);
     return false;
   }
+
+  // Validate fork/join nodes
+  const nodes = content.nodes;
+  const forkNodes = Object.entries(nodes).filter(([, n]) => n.type === "fork");
+  const joinNodes = Object.entries(nodes).filter(([, n]) => n.type === "join");
+
+  for (const [forkId, forkDef] of forkNodes) {
+    // Fork's join field must reference an existing join node
+    if (!forkDef.join || !nodes[forkDef.join]) {
+      console.error(`Invalid workflow ${id}: fork '${forkId}' references missing join node '${forkDef.join}'`);
+      return false;
+    }
+    if (nodes[forkDef.join].type !== "join") {
+      console.error(`Invalid workflow ${id}: fork '${forkId}' join field '${forkDef.join}' is not a join node`);
+      return false;
+    }
+
+    // All branch entryStep values must reference existing nodes
+    if (!forkDef.branches || typeof forkDef.branches !== "object") {
+      console.error(`Invalid workflow ${id}: fork '${forkId}' missing branches`);
+      return false;
+    }
+    for (const [branchName, branchDef] of Object.entries(forkDef.branches)) {
+      if (!branchDef.entryStep || !nodes[branchDef.entryStep]) {
+        console.error(
+          `Invalid workflow ${id}: fork '${forkId}' branch '${branchName}' references missing node '${branchDef.entryStep}'`
+        );
+        return false;
+      }
+    }
+
+    // No nested forks in v1: branch paths must not contain fork nodes
+    for (const [branchName, branchDef] of Object.entries(forkDef.branches)) {
+      if (nodes[branchDef.entryStep]?.type === "fork") {
+        console.error(
+          `Invalid workflow ${id}: fork '${forkId}' branch '${branchName}' entry step '${branchDef.entryStep}' is a nested fork (not supported in v1)`
+        );
+        return false;
+      }
+    }
+  }
+
+  for (const [joinId, joinDef] of joinNodes) {
+    // Join's fork field must reference an existing fork node
+    if (!joinDef.fork || !nodes[joinDef.fork]) {
+      console.error(`Invalid workflow ${id}: join '${joinId}' references missing fork node '${joinDef.fork}'`);
+      return false;
+    }
+    if (nodes[joinDef.fork].type !== "fork") {
+      console.error(`Invalid workflow ${id}: join '${joinId}' fork field '${joinDef.fork}' is not a fork node`);
+      return false;
+    }
+  }
+
+  // Fork-join pairs must be matched 1:1
+  const forkToJoin = new Map(forkNodes.map(([id, def]) => [id, def.join]));
+  const joinToFork = new Map(joinNodes.map(([id, def]) => [id, def.fork]));
+
+  for (const [forkId, joinId] of forkToJoin) {
+    if (joinToFork.get(joinId) !== forkId) {
+      console.error(
+        `Invalid workflow ${id}: fork '${forkId}' → join '${joinId}' pair mismatch (join points to '${joinToFork.get(joinId)}')`
+      );
+      return false;
+    }
+  }
+
   return true;
 }
 

package/types.d.ts

@@ -13,7 +13,7 @@
 // Node Types (Discriminated Union)
 // =============================================================================
 
-export type Node = StartNode | EndNode | TaskNode | GateNode | SubflowNode;
+export type Node = StartNode | EndNode | TaskNode | GateNode | SubflowNode | ForkNode | JoinNode;
 
 export interface StartNode {
   type: "start";
@@ -81,6 +81,30 @@ export interface SubflowNode {
   inputs?: Record<string, string>;
 }
 
+/**
+ * Fork node - declares parallel branches within the same workflow.
+ * Each branch names an entry step. Links to a join node that collects results.
+ */
+export interface ForkNode {
+  type: "fork";
+  name: string;
+  description?: string;
+  branches: Record<string, { entryStep: string; description?: string }>;
+  join: string; // join node ID
+}
+
+/**
+ * Join node - collects results from parallel branches.
+ * Strategy determines how branch results are evaluated.
+ */
+export interface JoinNode {
+  type: "join";
+  name: string;
+  description?: string;
+  fork: string; // fork node ID
+  strategy?: "all-pass" | "any-pass"; // default: "all-pass"
+}
+
 export type Stage = "planning" | "development" | "verification" | "delivery";
 
 // =============================================================================
@@ -145,6 +169,8 @@ export interface NavigateOptions {
   description?: string;
   projectRoot?: string;
   autonomy?: boolean;
+  /** Start at a specific step instead of the beginning (mid-flow recovery). Only used when starting a workflow (no taskFilePath). Ignored during advance. */
+  stepId?: string;
 }
 
 export interface NavigateResponse {
@@ -158,6 +184,8 @@ export interface NavigateResponse {
   autonomyContinued: boolean;
   maxRetries: number;
   orchestratorInstructions: string | null;
+  fork?: { branches: Record<string, { entryStep: string; description?: string }>; joinStep: string };
+  join?: { forkStep: string; strategy: string };
   metadata: {
     workflowType: string;
     currentStep: string;