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

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

@@ -0,0 +1,248 @@
+{
+  "id": "refactor",
+  "name": "Refactor",
+  "description": "Transform outdated codebases into modern equivalents using Functional Core / Imperative Shell architecture. Separates pure business logic from side effects.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start",
+      "description": "Refactoring workflow begins"
+    },
+    "analyze_structure": {
+      "type": "task",
+      "name": "Analyze Structure",
+      "description": "Map current architecture: modules, dependencies, entry points. Identify coupling and cohesion issues.",
+      "agent": "Planner",
+      "stage": "analysis"
+    },
+    "identify_debt": {
+      "type": "task",
+      "name": "Identify Technical Debt",
+      "description": "Find code smells, anti-patterns, outdated practices. Document violations of SOLID, DRY, and separation of concerns.",
+      "agent": "Planner",
+      "stage": "analysis"
+    },
+    "classify_components": {
+      "type": "task",
+      "name": "Classify Components",
+      "description": "Categorize code into Functional Core (pure logic, no side effects) vs Imperative Shell (I/O, state, external calls).",
+      "agent": "Planner",
+      "stage": "analysis"
+    },
+    "design_refactor": {
+      "type": "task",
+      "name": "Design Refactor Plan",
+      "description": "Create transformation plan: define functional core boundaries, shell interfaces, and migration sequence.",
+      "agent": "Planner",
+      "stage": "planning"
+    },
+    "plan_review": {
+      "type": "gate",
+      "name": "Review Plan",
+      "description": "Verify refactor plan maintains behavioral equivalence while achieving architectural goals.",
+      "agent": "Reviewer",
+      "stage": "planning",
+      "maxRetries": 2,
+      "config": {
+        "scrutinyLevel": 3
+      }
+    },
+    "extract_core": {
+      "type": "task",
+      "name": "Extract Functional Core",
+      "description": "Refactor pure business logic into functional core: no side effects, deterministic, testable in isolation.",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "isolate_shell": {
+      "type": "task",
+      "name": "Isolate Imperative Shell",
+      "description": "Wrap side effects (I/O, state, external services) in thin imperative shell that coordinates functional core.",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "write_tests": {
+      "type": "task",
+      "name": "Write Tests",
+      "description": "Add tests verifying behavioral equivalence. Unit tests for functional core, integration tests for shell.",
+      "agent": "Tester",
+      "stage": "development"
+    },
+    "run_tests": {
+      "type": "gate",
+      "name": "Run Tests",
+      "description": "Execute test suite. Verify refactored code produces identical behavior to original.",
+      "agent": "Tester",
+      "stage": "verification",
+      "maxRetries": 3
+    },
+    "code_review": {
+      "type": "gate",
+      "name": "Code Review",
+      "description": "Review architecture: clean functional/shell separation, no hidden side effects in core, shell is minimal.",
+      "agent": "Reviewer",
+      "stage": "verification",
+      "maxRetries": 2,
+      "config": {
+        "scrutinyLevel": 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 all changes with a descriptive message summarizing the refactoring",
+      "agent": "Developer",
+      "stage": "delivery"
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Complete",
+      "description": "Refactoring completed successfully"
+    },
+    "hitl_analysis_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Analysis Blocked",
+      "description": "Analysis or planning needs human guidance"
+    },
+    "hitl_dev_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Development Blocked",
+      "description": "Development or verification needs human intervention"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "analyze_structure"
+    },
+    {
+      "from": "analyze_structure",
+      "to": "identify_debt"
+    },
+    {
+      "from": "identify_debt",
+      "to": "classify_components"
+    },
+    {
+      "from": "classify_components",
+      "to": "design_refactor"
+    },
+    {
+      "from": "design_refactor",
+      "to": "plan_review"
+    },
+    {
+      "from": "plan_review",
+      "to": "design_refactor",
+      "on": "failed",
+      "label": "Revise plan based on feedback"
+    },
+    {
+      "from": "plan_review",
+      "to": "hitl_analysis_failed",
+      "on": "failed",
+      "label": "Planning exhausted retries"
+    },
+    {
+      "from": "plan_review",
+      "to": "extract_core",
+      "on": "passed",
+      "label": "Plan approved, begin refactoring"
+    },
+    {
+      "from": "extract_core",
+      "to": "isolate_shell"
+    },
+    {
+      "from": "isolate_shell",
+      "to": "write_tests"
+    },
+    {
+      "from": "write_tests",
+      "to": "run_tests"
+    },
+    {
+      "from": "run_tests",
+      "to": "extract_core",
+      "on": "failed",
+      "label": "Fix failing tests"
+    },
+    {
+      "from": "run_tests",
+      "to": "hitl_dev_failed",
+      "on": "failed",
+      "label": "Tests keep failing"
+    },
+    {
+      "from": "run_tests",
+      "to": "code_review",
+      "on": "passed",
+      "label": "Tests pass, ready for review"
+    },
+    {
+      "from": "code_review",
+      "to": "extract_core",
+      "on": "failed",
+      "label": "Address review feedback"
+    },
+    {
+      "from": "code_review",
+      "to": "hitl_dev_failed",
+      "on": "failed",
+      "label": "Review issues persist"
+    },
+    {
+      "from": "code_review",
+      "to": "lint_format",
+      "on": "passed",
+      "label": "Code approved, run lint checks"
+    },
+    {
+      "from": "lint_format",
+      "to": "commit",
+      "on": "passed",
+      "label": "Lint passes, commit changes"
+    },
+    {
+      "from": "lint_format",
+      "to": "extract_core",
+      "on": "failed",
+      "label": "Fix lint/format issues"
+    },
+    {
+      "from": "lint_format",
+      "to": "hitl_dev_failed",
+      "on": "failed",
+      "label": "Lint issues persist"
+    },
+    {
+      "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/copier.js

@@ -12,78 +12,41 @@
 export function generateFlowReadme() {
   return `# Flow Plugin
 
-DAG-based workflow orchestration for Claude Code.
-
-## Overview
-
-Flow provides structured workflows that guide tasks through defined stages (planning → development → verification → delivery). Each step can be delegated to specialized subagents.
+DAG-based workflow orchestration for AI agents.
 
 ## Quick Start
 
-Workflows work immediately from the built-in catalog - no setup required:
-
 \`\`\`bash
-# Create a task with workflow tracking
-/flow:task-create "Add user authentication" [workflow] feature-development
+# Load the orchestrator at session start
+/flow:prime
 
-# Or use prefix shortcuts
-feat: Add user authentication    # → feature-development workflow
-bug: Fix login error             # → bug-fix workflow
-task: Update config file         # → quick-task workflow
+# Create a task using a command
+/flow:feat "add user authentication"
 
-# Run the task autonomously
-/flow:run
+# Execute all pending tasks
+/flow:go
 \`\`\`
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| \`/flow:prime\` | Load Orchestrator context (invoke at session start) |
-| \`/flow:task-create\` | Create a new task with workflow tracking |
-| \`/flow:task-list\` | List all flow tasks with current status |
-| \`/flow:task-get\` | Get detailed task info including workflow diagram |
-| \`/flow:task-advance\` | Advance task: \`<taskId> <passed|failed> [summary]\` |
-| \`/flow:run\` | Execute flow tasks autonomously |
-| \`/flow:list\` | List available workflows |
-| \`/flow:diagram\` | Generate mermaid diagram for a workflow |
-| \`/flow:init\` | Copy workflows to .flow/workflows/ for customization |
-| \`/flow:load\` | Reload workflows after editing .flow/workflows/ |
-
-## Available Workflows
-
-- **quick-task** - Minimal: understand → execute → verify (best for simple tasks)
-- **agile-task** - Simple: analyze → implement → test → review
-- **feature-development** - Full lifecycle: requirements → planning → implementation → testing → PR
-- **bug-fix** - Bug workflow: reproduce → investigate → fix → verify → PR
-- **test-coverage** - Analyze coverage gaps and write tests
-- **context-optimization** - Optimize agent context and instructions
-- **ui-reconstruction** - Reconstruct UI components from screenshots or designs
+| Command | Workflow | Description |
+| --- | --- | --- |
+| \`/flow:feat\` | feature-development | New feature with planning + review |
+| \`/flow:bug\` | bug-fix | Bug investigation and fix |
+| \`/flow:task\` | agile-task | General development task |
+| \`/flow:fix\` | quick-task | Quick fix, minimal ceremony |
+| \`/flow:spec\` | test-coverage | Analyze and improve test coverage |
+| \`/flow:ctx\` | context-optimization | Optimize agent context and prompts |
+| \`/flow:ui\` | ui-reconstruction | Reconstruct UI from reference |
+| \`/flow:go\` | _(runs queue)_ | Execute all pending tasks |
 
-## Customization (Optional)
+Use \`/flow:task-create "description" <workflow-id>\` for workflows without command shortcuts.
 
-Flow's workflows work directly from the catalog in the flow->navigator mcp. If you want to create custom workflows you can run \`/flow:init\` to select a workflow from the catalog to customize for your project, your agents, and your tools.
-
-\`\`\`bash
-# Copy catalog workflows to .flow/workflows/ for editing
-/flow:init
-
-# Edit .flow/workflows/{workflow}/workflow.json
-# Then reload
-/flow:load
-\`\`\`
-
-**Customization options:**
-- Modify step definitions in workflow.json
-- Add custom \`instructions\` to steps for project-specific guidance
-- Create new workflows by adding new directories
+## Available Workflows
 
-## How It Works
+Workflows are defined in \`.flow/workflows/\`. Edit \`workflow.json\` to customize, then run \`/flow:load\` to reload.
 
-1. **Navigate API** - Stateless MCP server computes next step based on workflow DAG
-2. **Task Metadata** - Workflow state stored in Claude Code task metadata
-3. **Subagent Delegation** - Steps delegated to specialized agents (planner, developer, tester, reviewer)
-4. **Retry Logic** - Failed steps retry with configurable limits, escalate to HITL if exceeded
+See [Flow Plugin docs](https://github.com/leclabs/agent-toolkit/tree/main/plugins/flow) for the full workflow catalog.
 `;
 }
 

package/engine.js

@@ -13,7 +13,8 @@
  * - Edge to end node = escalation (taken if retries exhausted)
  */
 
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
 
 /**
  * Read and parse a task file
@@ -52,13 +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;
-  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}`;
 }
 
 /**
@@ -68,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")) {
@@ -87,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.";
@@ -124,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;
 }
 
 /**
@@ -149,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;
@@ -164,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 {
@@ -184,6 +258,7 @@ function buildNavigateResponse(
     terminal: getTerminalType(stepDef),
     action,
     retriesIncremented,
+    maxRetries: stepDef.maxRetries || 0,
     orchestratorInstructions,
     metadata,
   };
@@ -354,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;
 
@@ -414,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
@@ -424,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
@@ -444,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";
@@ -454,14 +533,44 @@ export class WorkflowEngine {
       action = "advance";
     }
 
-    return buildNavigateResponse(
+    // 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,
       nextStepDef,
       action,
       isRetry,
       retryCount,
-      description
+      description,
+      resetRetryCount,
+      projectRoot
     );
+
+    // 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));
+      }
+    }
+
+    return response;
   }
 }