@leclabs/agent-flow-navigator-mcp 1.1.0 → 1.2.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/build-review-murder-board.json

@@ -0,0 +1,110 @@
+{
+  "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"
+    }
+  ]
+}

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

@@ -0,0 +1,108 @@
+{
+  "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"
+    }
+  ]
+}

package/catalog/workflows/refactor.json

@@ -0,0 +1,236 @@
+{
+  "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"
+    }
+  ]
+}

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,7 @@
  * - Edge to end node = escalation (taken if retries exhausted)
  */
 
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync } from "fs";
 
 /**
  * Read and parse a task file
@@ -58,6 +58,9 @@ export function getTerminalType(node) {
 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}`;
 }
 
@@ -454,7 +457,7 @@ export class WorkflowEngine {
       action = "advance";
     }
 
-    return buildNavigateResponse(
+    const response = buildNavigateResponse(
       workflowType,
       evaluation.nextStep,
       nextStepDef,
@@ -463,5 +466,16 @@ export class WorkflowEngine {
       retryCount,
       description
     );
+
+    // Write-through: persist state transition to task file
+    if (taskFilePath) {
+      const task = readTaskFile(taskFilePath);
+      if (task) {
+        task.metadata = { ...task.metadata, ...response.metadata };
+        writeFileSync(taskFilePath, JSON.stringify(task, null, 2));
+      }
+    }
+
+    return response;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leclabs/agent-flow-navigator-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server that navigates agents through DAG-based workflows",
   "license": "MIT",
   "author": "leclabs",
@@ -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"
+    "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"
   },
   "keywords": [
     "mcp",