@leclabs/agent-flow-navigator-mcp 1.2.0 → 1.3.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,30 @@ export function getBaselineInstructions(stepId, stepName) {
   return "Complete this step thoroughly. Document your findings and any decisions made.";
 }
 
+/**
+ * Build context loading instructions from step-level context_files.
+ * Returns a markdown section or null if no context declared.
+ */
+export function buildContextInstructions({ contextFiles, projectRoot }) {
+  if (!contextFiles?.length || !projectRoot) return null;
+  const lines = contextFiles.map((file) => `- Read file: ${join(projectRoot, file)}`);
+  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,7 +210,9 @@ function buildNavigateResponse(
   action,
   retriesIncremented = false,
   retryCount = 0,
-  description = null
+  description = null,
+  resetRetryCount = false,
+  projectRoot = null
 ) {
   const stage = stepDef.stage || null;
   const subagent = stepDef.agent ? toSubagentRef(stepDef.agent) : null;
@@ -167,16 +227,27 @@ function buildNavigateResponse(
         guidance: stepDef.instructions || getBaselineInstructions(stepId, stepDef.name),
       };
 
+  // Build context block from step-level context_files
+  const contextBlock = isTerminal
+    ? null
+    : buildContextInstructions({ contextFiles: stepDef.context_files, projectRoot });
+
   // 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 +258,7 @@ function buildNavigateResponse(
     terminal: getTerminalType(stepDef),
     action,
     retriesIncremented,
+    maxRetries: stepDef.maxRetries || 0,
     orchestratorInstructions,
     metadata,
   };
@@ -357,7 +429,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;
 
@@ -417,7 +489,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);
     }
 
     // Case 2: currentStep but no result - return current state
@@ -427,7 +499,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);
     }
 
     // Case 3: currentStep and result - advance to next step
@@ -447,9 +519,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 +533,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 +544,29 @@ export class WorkflowEngine {
       action,
       isRetry,
       retryCount,
-      description
+      description,
+      resetRetryCount,
+      projectRoot
     );
 
-    // 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

@@ -186,6 +186,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"],
         },
@@ -229,6 +233,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           workflowType: args.workflowType,
           result: args.result,
           description: args.description,
+          projectRoot: PROJECT_ROOT,
         });
         return jsonResponse(result);
       }
@@ -264,11 +269,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 });

package/package.json

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

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[];
 }
 
 /**