@leclabs/agent-flow-navigator-mcp 1.5.1 → 1.6.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
 

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?, ... } }
@@ -14,7 +14,7 @@
  */
 
 import { existsSync, readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { basename, join } from "path";
 
 /**
  * Read and parse a task file
@@ -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
@@ -551,6 +602,11 @@ export class WorkflowEngine {
         throw new Error(`First step '${firstEdge.to}' not found in workflow`);
       }
 
+      // Fork/join at start position — return control-flow response
+      if (isForkJoinNode(firstStepDef)) {
+        return buildForkJoinResponse(workflowType, firstEdge.to, firstStepDef, "start", 0, sourceRoot);
+      }
+
       return buildNavigateResponse(
         workflowType,
         firstEdge.to,
@@ -572,6 +628,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 +663,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";
@@ -672,11 +769,19 @@ export class WorkflowEngine {
     if (taskFilePath) {
       const task = readTaskFile(taskFilePath);
       if (task) {
-        const originalId = task.id;
+        // Derive canonical ID from filename — this is the source of truth.
+        // Auto-corrects if task.id was corrupted by an external write.
+        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;
         const userDesc = task.metadata?.userDescription || "";
         task.metadata = { ...task.metadata, ...response.metadata };
         task.subject = buildTaskSubject(
-          originalId,
+          canonicalId,
           userDesc,
           response.metadata.workflowType,
           response.currentStep,
@@ -693,7 +798,7 @@ export class WorkflowEngine {
         if (response.orchestratorInstructions) {
           task.description = response.orchestratorInstructions;
         }
-        task.id = originalId;
+        task.id = canonicalId;
         writeFileSync(taskFilePath, JSON.stringify(task, null, 2));
       }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leclabs/agent-flow-navigator-mcp",
-  "version": "1.5.1",
-  "description": "MCP server that navigates agents through DAG-based workflows",
+  "version": "1.6.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";
 
 // =============================================================================
@@ -158,6 +182,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;