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

package/README.md

@@ -4,7 +4,7 @@
 
 A workflow state machine MCP server that navigates agents through DAG-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.
+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.
 
 ## Installation
 
@@ -39,21 +39,21 @@ Add to your `.mcp.json`:
 
 Navigator works with the [flow plugin](https://github.com/leclabs/agent-toolkit/tree/main/plugins/flow) to provide structured workflow execution:
 
-1. **Initialize workflows** - Copy workflow templates to your project with `CopyWorkflows`
-2. **Start a task** - Use `Navigate` with a workflow type and description
-3. **Follow the flow** - Navigator tells you the current step and what to do
-4. **Advance on completion** - Report `passed` or `failed` to move to the next step
+1. **Initialize workflows** -- Copy workflow templates to your project with `CopyWorkflows`
+2. **Start a task** -- Use `Navigate` with a workflow type and description
+3. **Follow the flow** -- Navigator tells you the current step and what to do
+4. **Advance on completion** -- Report `passed` or `failed` to move to the next step
 
 ```
 User: "Add dark mode support"
   ↓
 Navigate(workflowType: "feature-development", description: "Add dark mode support")
   ↓
-Navigator returns: Step 1 of 8 - "Create implementation plan"
+Navigator returns: currentStep: "parse_requirements", stage: "planning"
   ↓
-Agent executes step, then calls Navigate(result: "passed")
+Agent executes step, then calls Navigate(taskFilePath: "...", result: "passed")
   ↓
-Navigator returns: Step 2 of 8 - "Implement changes"
+Navigator returns: currentStep: "explore_codebase", stage: "planning"
   ↓
 ... continues through workflow ...
 ```
@@ -71,7 +71,11 @@ Navigator returns: Step 2 of 8 - "Implement changes"
 
 ### Navigate
 
-The primary tool for workflow navigation.
+The primary tool. Operates in 3 modes:
+
+- **Start**: Pass `workflowType` + `description` to begin a workflow
+- **Current**: Pass `taskFilePath` to get current step state
+- **Advance**: Pass `taskFilePath` + `result` to move to the next step
 
 | Parameter      | Type                 | Description                                               |
 | -------------- | -------------------- | --------------------------------------------------------- |
@@ -89,54 +93,65 @@ Generates a mermaid diagram for visualizing workflow structure.
 | `workflowType` | string | Workflow ID to visualize (required) |
 | `currentStep`  | string | Optional step to highlight          |
 
-## Architecture Overview
+### ListWorkflows
+
+Lists available workflows, filterable by source.
+
+| Parameter | Type   | Description                                                                 |
+| --------- | ------ | --------------------------------------------------------------------------- |
+| `source`  | string | Filter: `"project"`, `"catalog"`, or `"all"`. Defaults to project if exists |
+
+### SelectWorkflow
+
+Returns a workflow selection dialog for user interaction. No parameters.
+
+### CopyWorkflows
+
+Copies workflows from catalog to the project's `.flow/workflows/` directory.
+
+| Parameter     | Type     | Description                            |
+| ------------- | -------- | -------------------------------------- |
+| `workflowIds` | string[] | Workflow IDs to copy. Empty = copy all |
+
+### ListCatalog
+
+Lists workflows available in the built-in catalog. No parameters.
+
+## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         ORCHESTRATOR                                 │
-│  (Source of Truth: GitHub Issues, External DB, etc.)                │
-│  (Executes tasks, makes decisions, drives the workflow)             │
-└─────────────────────────┬───────────────────────────────────────────┘
-                          │
-          ┌───────────────┼───────────────┐
-          │ load_workflow │ load_task_tree│
-          │               │               │
-          ▼               ▼               │
-┌─────────────────────────────────────────┴───────────────────────────┐
-│                         NAVIGATOR                                    │
-│               (Workflow State Machine MCP Server)                    │
-│                                                                      │
-│  ┌──────────────────┐    ┌──────────────────┐                       │
-│  │ Workflow Store   │    │ Task Tree        │                       │
-│  │ (Graph Defs)     │    │ (State Tracker)  │                       │
-│  └──────────────────┘    └──────────────────┘                       │
-│                                                                      │
-│  ┌──────────────────┐    ┌──────────────────┐                       │
-│  │ Edge Evaluator   │    │ Sync Tracker     │                       │
-│  │ (Next Step?)     │    │ (Pending Syncs)  │                       │
-│  └──────────────────┘    └──────────────────┘                       │
-│                                                                      │
-└─────────────────────────┬───────────────────────────────────────────┘
-                          │
-          ┌───────────────┼───────────────┐
-          │ get_next_tasks│ advance_task  │
-          │ "What's next?"│ "I got X"     │
-          ▼               ▼               │
-┌─────────────────────────────────────────┴───────────────────────────┐
-│                         ORCHESTRATOR                                 │
-│  (Receives directions, executes, persists, confirms syncs)          │
-└─────────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────┐
+│                  ORCHESTRATOR                     │
+│  (Executes tasks, delegates to subagents)        │
+└──────────────────────┬──────────────────────────┘
+                       │
+       Navigate ───────┼─────── Diagram
+       ListWorkflows ──┤        CopyWorkflows
+       SelectWorkflow ─┤        ListCatalog
+                       │
+┌──────────────────────┴──────────────────────────┐
+│                   NAVIGATOR                      │
+│          (Workflow State Machine MCP)             │
+│                                                  │
+│  ┌──────────────────┐  ┌──────────────────┐      │
+│  │  Workflow Store  │  │  Edge Evaluator  │      │
+│  │  (Graph Defs)    │  │  (Next Step?)    │      │
+│  └──────────────────┘  └──────────────────┘      │
+│                                                  │
+│  Write-through: state transitions persist        │
+│  atomically to the task file on disk             │
+└─────────────────────────────────────────────────┘
 ```
 
 ### Key Concepts
 
-| Concept                 | Description                                                                          |
-| ----------------------- | ------------------------------------------------------------------------------------ |
-| **Workflow Definition** | A DAG blueprint describing how to execute a type of work (nodes + conditional edges) |
-| **Task Tree**           | A runtime priority queue of actual work items across multiple workflow types         |
-| **Sync Tracking**       | Mutations are tracked; orchestrator is reminded to persist to primary store          |
-| **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 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"`        |
 
 ## Workflow Definition Schema
 
@@ -159,89 +174,24 @@ Generates a mermaid diagram for visualizing workflow structure.
 
 ### Task/Gate Node Properties
 
-| Property     | Description                                                |
-| ------------ | ---------------------------------------------------------- |
-| `name`       | Human-readable name (required)                             |
-| `outputs`    | Possible outcomes (default: `["passed", "failed"]`)        |
-| `maxRetries` | Retry count on failure before following "failed" edge      |
-| `agent`      | Agent type to perform this task                            |
-| `stage`      | Workflow phase: planning/development/verification/delivery |
+| Property     | Description                                                          |
+| ------------ | -------------------------------------------------------------------- |
+| `name`       | Human-readable name (required)                                       |
+| `outputs`    | Possible outcomes (default: `["passed", "failed"]`)                  |
+| `maxRetries` | Retry count on failure before following "failed" edge                |
+| `agent`      | Agent type to perform this task                                      |
+| `stage`      | Workflow phase (e.g., planning, development, verification, delivery) |
+| `metadata`   | Arbitrary key-value data for workflow tooling and extensions         |
 
 ### Edge Properties
 
-| Property | Description                                                    |
-| -------- | -------------------------------------------------------------- |
-| `from`   | Source node ID                                                 |
-| `to`     | Target node ID                                                 |
-| `on`     | Output value that triggers this edge (for conditional routing) |
-| `label`  | Human-readable edge description                                |
-
-## Advanced Usage
-
-### Loading Workflow Definitions
-
-```json
-{
-  "tool": "load_workflow",
-  "arguments": {
-    "id": "ui-reconstruction",
-    "definition": {
-      "nodes": {
-        "start": { "type": "start" },
-        "analyze": { "type": "task", "name": "Analyze Components" },
-        "review": { "type": "gate", "name": "Review Analysis", "maxRetries": 3 },
-        "end": { "type": "end", "result": "success" },
-        "hitl": { "type": "end", "result": "blocked", "escalation": "hitl" }
-      },
-      "edges": [
-        { "from": "start", "to": "analyze" },
-        { "from": "analyze", "to": "review" },
-        { "from": "review", "to": "analyze", "on": "failed", "label": "Retry on failure" },
-        { "from": "review", "to": "hitl", "on": "max_retries_exceeded", "label": "Escalate after 3 failures" },
-        { "from": "review", "to": "end", "on": "passed" }
-      ]
-    }
-  }
-}
-```
-
-### Task Tree Management
-
-Load a priority queue of tasks:
-
-```json
-{
-  "tool": "load_task_tree",
-  "arguments": {
-    "tasks": [
-      {
-        "id": "task-001",
-        "issueId": "ISSUE-042",
-        "workflowType": "ui-reconstruction",
-        "currentStep": "start",
-        "priority": 100,
-        "status": "PENDING",
-        "context": { "targetUrl": "https://example.com" }
-      }
-    ]
-  }
-}
-```
-
-### Advancing Tasks
-
-After executing a task step:
-
-```json
-{
-  "tool": "advance_task",
-  "arguments": {
-    "taskId": "task-001",
-    "result": "passed",
-    "output": "Analysis complete, found 5 components"
-  }
-}
-```
+| Property    | Description                                                    |
+| ----------- | -------------------------------------------------------------- |
+| `from`      | Source node ID                                                 |
+| `to`        | Target node ID                                                 |
+| `on`        | Output value that triggers this edge (for conditional routing) |
+| `label`     | Human-readable edge description                                |
+| `condition` | Expression for future conditional routing (informational)      |
 
 ## Testing
 
@@ -253,8 +203,7 @@ npm test
 
 - [GitHub Repository](https://github.com/leclabs/agent-toolkit)
 - [Flow Plugin](https://github.com/leclabs/agent-toolkit/tree/main/plugins/flow)
-- [Full Documentation](https://github.com/leclabs/agent-toolkit/tree/main/packages/agent-flow-navigator-mcp)
 
 ## License
 
-MIT
+ISC

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

@@ -0,0 +1,116 @@
+{
+  "id": "build-review-murder-board",
+  "name": "Build-Review Murder Board",
+  "description": "High-scrutiny iterative build-review loop. A fresh reviewer agent tears apart each build attempt with maximum rigor. Ideal for critical changes requiring independent verification.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start",
+      "description": "Build-review cycle begins"
+    },
+    "build": {
+      "type": "task",
+      "name": "Build",
+      "description": "Implement or revise the changes based on requirements or review feedback",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "review": {
+      "type": "gate",
+      "name": "Murder Board Review",
+      "description": "Independent high-scrutiny review. Reviewer must be a fresh agent with no prior context of this build. Approval requires confidence score >= 80.",
+      "agent": "Reviewer",
+      "stage": "verification",
+      "maxRetries": 3,
+      "config": {
+        "scrutinyLevel": 5,
+        "blindShot": true,
+        "approvalThreshold": 80
+      }
+    },
+    "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 work done",
+      "agent": "Developer",
+      "stage": "delivery"
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Approved",
+      "description": "Build passed murder board review and delivered"
+    },
+    "hitl_blocked": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Review Blocked",
+      "description": "Build failed murder board review after all retries - needs human intervention"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "build"
+    },
+    {
+      "from": "build",
+      "to": "review"
+    },
+    {
+      "from": "review",
+      "to": "build",
+      "on": "failed",
+      "label": "Revise build based on review feedback"
+    },
+    {
+      "from": "review",
+      "to": "hitl_blocked",
+      "on": "failed",
+      "label": "Review failures exhausted retries"
+    },
+    {
+      "from": "review",
+      "to": "lint_format",
+      "on": "passed",
+      "label": "Review passed, run lint checks"
+    },
+    {
+      "from": "lint_format",
+      "to": "commit",
+      "on": "passed",
+      "label": "Lint passes, commit changes"
+    },
+    {
+      "from": "lint_format",
+      "to": "build",
+      "on": "failed",
+      "label": "Fix lint/format issues"
+    },
+    {
+      "from": "lint_format",
+      "to": "hitl_blocked",
+      "on": "failed",
+      "label": "Lint issues persist"
+    },
+    {
+      "from": "commit",
+      "to": "end_success"
+    },
+    {
+      "from": "hitl_blocked",
+      "to": "build",
+      "on": "passed",
+      "label": "Human resolved issue, resume"
+    }
+  ]
+}

package/catalog/workflows/build-review-quick.json

@@ -0,0 +1,114 @@
+{
+  "id": "build-review-quick",
+  "name": "Build-Review Quick",
+  "description": "Low-scrutiny iterative build-review loop. A lightweight review pass ensures basic correctness before delivery. Suited for low-risk or well-understood changes.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start",
+      "description": "Build-review cycle begins"
+    },
+    "build": {
+      "type": "task",
+      "name": "Build",
+      "description": "Implement or revise the changes based on requirements or review feedback",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "review": {
+      "type": "gate",
+      "name": "Quick Review",
+      "description": "Lightweight review checking basic correctness and completeness",
+      "agent": "Reviewer",
+      "stage": "verification",
+      "maxRetries": 2,
+      "config": {
+        "scrutinyLevel": 1
+      }
+    },
+    "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 work done",
+      "agent": "Developer",
+      "stage": "delivery"
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Complete",
+      "description": "Build passed review and delivered"
+    },
+    "hitl_blocked": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Blocked",
+      "description": "Build failed review after all retries - needs human intervention"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "build"
+    },
+    {
+      "from": "build",
+      "to": "review"
+    },
+    {
+      "from": "review",
+      "to": "build",
+      "on": "failed",
+      "label": "Revise build based on review feedback"
+    },
+    {
+      "from": "review",
+      "to": "hitl_blocked",
+      "on": "failed",
+      "label": "Review failures exhausted retries"
+    },
+    {
+      "from": "review",
+      "to": "lint_format",
+      "on": "passed",
+      "label": "Review passed, run lint checks"
+    },
+    {
+      "from": "lint_format",
+      "to": "commit",
+      "on": "passed",
+      "label": "Lint passes, commit changes"
+    },
+    {
+      "from": "lint_format",
+      "to": "build",
+      "on": "failed",
+      "label": "Fix lint/format issues"
+    },
+    {
+      "from": "lint_format",
+      "to": "hitl_blocked",
+      "on": "failed",
+      "label": "Lint issues persist"
+    },
+    {
+      "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" }
+  ]
+}