@leclabs/agent-flow-navigator-mcp 1.0.0

package/README.md

@@ -0,0 +1,260 @@
+# @leclabs/agent-flow-navigator-mcp
+
+[![npm](https://img.shields.io/npm/v/@leclabs/agent-flow-navigator-mcp)](https://npmjs.com/package/@leclabs/agent-flow-navigator-mcp)
+
+A workflow state machine MCP server that navigates agents through DAG-based workflows.
+
+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
+
+Run directly with npx:
+
+```bash
+npx -y @leclabs/agent-flow-navigator-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g @leclabs/agent-flow-navigator-mcp
+```
+
+## Claude Code Configuration
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "navigator": {
+      "command": "npx",
+      "args": ["-y", "@leclabs/agent-flow-navigator-mcp"]
+    }
+  }
+}
+```
+
+## Quick Start
+
+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
+
+```
+User: "Add dark mode support"
+  ↓
+Navigate(workflowType: "feature-development", description: "Add dark mode support")
+  ↓
+Navigator returns: Step 1 of 8 - "Create implementation plan"
+  ↓
+Agent executes step, then calls Navigate(result: "passed")
+  ↓
+Navigator returns: Step 2 of 8 - "Implement changes"
+  ↓
+... continues through workflow ...
+```
+
+## MCP Tools Reference
+
+| Tool | Description |
+| ---- | ----------- |
+| `Navigate` | Start a workflow, get current state, or advance to next step |
+| `Diagram` | Generate a mermaid flowchart for a workflow |
+| `ListWorkflows` | List all available workflows |
+| `SelectWorkflow` | Get workflow selection dialog for user interaction |
+| `CopyWorkflows` | Copy workflows from catalog to project |
+| `ListCatalog` | List workflows available in the catalog |
+
+### Navigate
+
+The primary tool for workflow navigation.
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `workflowType` | string | Workflow ID (for start only, e.g., "feature-development") |
+| `description` | string | User's task description (for start) |
+| `taskFilePath` | string | Path to task file (for advance/current) |
+| `result` | "passed" \| "failed" | Step result (for advance) |
+
+### Diagram
+
+Generates a mermaid diagram for visualizing workflow structure.
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `workflowType` | string | Workflow ID to visualize (required) |
+| `currentStep` | string | Optional step to highlight |
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         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)          │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 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"`       |
+
+## Workflow Definition Schema
+
+### Node Types
+
+| Type      | Description                                                  |
+| --------- | ------------------------------------------------------------ |
+| `start`   | Workflow entry point (exactly one per workflow)              |
+| `end`     | Exit point with `result` (success/failure/blocked/cancelled) |
+| `task`    | Executable work unit                                         |
+| `gate`    | Quality gate / review checkpoint                             |
+| `subflow` | Connector to another workflow                                |
+
+### End Node Properties
+
+| Property     | Description                                             |
+| ------------ | ------------------------------------------------------- |
+| `result`     | `"success"`, `"failure"`, `"blocked"`, or `"cancelled"` |
+| `escalation` | Optional: `"hitl"`, `"alert"`, or `"ticket"`            |
+
+### 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 |
+
+### 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"
+  }
+}
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Links
+
+- [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

package/catalog/workflows/agile-task.json

@@ -0,0 +1,130 @@
+{
+  "id": "agile-task",
+  "name": "Agile Task",
+  "description": "Simple workflow for general development tasks: analyze, implement, test, review.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start",
+      "description": "Task entry point"
+    },
+    "analyze": {
+      "type": "task",
+      "name": "Analyze",
+      "description": "Understand requirements and plan approach",
+      "agent": "Planner",
+      "stage": "planning"
+    },
+    "implement": {
+      "type": "task",
+      "name": "Implement",
+      "description": "Write the code or make changes",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "test": {
+      "type": "task",
+      "name": "Test",
+      "description": "Verify the implementation works correctly",
+      "agent": "Tester",
+      "stage": "verification"
+    },
+    "review": {
+      "type": "gate",
+      "name": "Review",
+      "description": "Review code quality and correctness",
+      "agent": "Reviewer",
+      "stage": "verification",
+      "maxRetries": 2,
+      "config": {
+        "scrutinyLevel": 2
+      }
+    },
+    "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",
+      "agent": "Developer",
+      "stage": "delivery"
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Complete",
+      "description": "Task completed successfully"
+    },
+    "hitl_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Needs Help",
+      "description": "Task needs human intervention"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "analyze"
+    },
+    {
+      "from": "analyze",
+      "to": "implement"
+    },
+    {
+      "from": "implement",
+      "to": "test"
+    },
+    {
+      "from": "test",
+      "to": "review"
+    },
+    {
+      "from": "review",
+      "to": "implement",
+      "on": "failed",
+      "label": "Fix issues found in review"
+    },
+    {
+      "from": "review",
+      "to": "hitl_failed",
+      "on": "failed",
+      "label": "Too many review failures"
+    },
+    {
+      "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": "implement",
+      "on": "failed",
+      "label": "Fix lint/format issues"
+    },
+    {
+      "from": "lint_format",
+      "to": "hitl_failed",
+      "on": "failed",
+      "label": "Lint issues persist"
+    },
+    {
+      "from": "commit",
+      "to": "end_success"
+    }
+  ]
+}

package/catalog/workflows/bug-fix.json

@@ -0,0 +1,153 @@
+{
+  "id": "bug-fix",
+  "name": "Bug Fix",
+  "description": "Workflow for fixing bugs: reproduce, investigate, fix, verify, and create PR.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start",
+      "description": "Bug fix begins"
+    },
+    "reproduce": {
+      "type": "task",
+      "name": "Reproduce Bug",
+      "description": "Understand the bug and create a reliable reproduction case",
+      "agent": "Investigator",
+      "stage": "investigation"
+    },
+    "investigate": {
+      "type": "task",
+      "name": "Investigate",
+      "description": "Find root cause by tracing code paths and debugging",
+      "agent": "Investigator",
+      "stage": "investigation"
+    },
+    "write_fix": {
+      "type": "task",
+      "name": "Write Fix",
+      "description": "Implement the fix with minimal changes",
+      "agent": "Developer",
+      "stage": "development"
+    },
+    "add_regression_test": {
+      "type": "task",
+      "name": "Add Regression Test",
+      "description": "Write a test that would have caught this bug",
+      "agent": "Tester",
+      "stage": "development"
+    },
+    "verify_fix": {
+      "type": "task",
+      "name": "Verify Fix",
+      "description": "Run all tests and verify the bug is fixed",
+      "agent": "Tester",
+      "stage": "verification",
+      "maxRetries": 3
+    },
+    "lint_format": {
+      "type": "gate",
+      "name": "Lint & Format",
+      "description": "Run lint and format checks. Auto-fix issues where possible.",
+      "agent": "Developer",
+      "stage": "delivery",
+      "maxRetries": 3
+    },
+    "commit": {
+      "type": "task",
+      "name": "Commit Changes",
+      "description": "Commit the fix and regression test with a descriptive message",
+      "agent": "Developer",
+      "stage": "delivery"
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Fixed",
+      "description": "Bug fixed and PR created"
+    },
+    "hitl_cannot_reproduce": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Cannot Reproduce",
+      "description": "Unable to reproduce the bug - need more info"
+    },
+    "hitl_fix_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Fix Failed",
+      "description": "Unable to fix the bug - needs human help"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "reproduce"
+    },
+    {
+      "from": "reproduce",
+      "to": "investigate",
+      "on": "passed",
+      "label": "Bug reproduced successfully"
+    },
+    {
+      "from": "reproduce",
+      "to": "hitl_cannot_reproduce",
+      "on": "failed",
+      "label": "Could not reproduce bug"
+    },
+    {
+      "from": "investigate",
+      "to": "write_fix"
+    },
+    {
+      "from": "write_fix",
+      "to": "add_regression_test"
+    },
+    {
+      "from": "add_regression_test",
+      "to": "verify_fix"
+    },
+    {
+      "from": "verify_fix",
+      "to": "write_fix",
+      "on": "failed",
+      "label": "Fix didn't work, try again"
+    },
+    {
+      "from": "verify_fix",
+      "to": "hitl_fix_failed",
+      "on": "failed",
+      "label": "Cannot fix the bug"
+    },
+    {
+      "from": "verify_fix",
+      "to": "lint_format",
+      "on": "passed",
+      "label": "Bug verified fixed, run lint checks"
+    },
+    {
+      "from": "lint_format",
+      "to": "commit",
+      "on": "passed",
+      "label": "Lint passes, commit changes"
+    },
+    {
+      "from": "lint_format",
+      "to": "write_fix",
+      "on": "failed",
+      "label": "Fix lint/format issues"
+    },
+    {
+      "from": "lint_format",
+      "to": "hitl_fix_failed",
+      "on": "failed",
+      "label": "Lint issues persist"
+    },
+    {
+      "from": "commit",
+      "to": "end_success"
+    }
+  ]
+}

package/catalog/workflows/context-optimization.json

@@ -0,0 +1,130 @@
+{
+  "id": "context-optimization",
+  "name": "Context Optimization",
+  "description": "Workflow for optimizing agent context, instructions, and integration points. Use when improving how agents communicate and preserve state.",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "name": "Start",
+      "description": "Context optimization begins"
+    },
+    "map_connections": {
+      "type": "task",
+      "name": "Map Connections",
+      "description": "Identify all connection points between components (MCP, skills, agents, subagents)",
+      "agent": "Context Engineer",
+      "stage": "analysis"
+    },
+    "identify_pathologies": {
+      "type": "task",
+      "name": "Identify Pathologies",
+      "description": "Find context pathologies: specification bloat, attention dilution, redundant framing",
+      "agent": "Context Engineer",
+      "stage": "analysis"
+    },
+    "design_improvements": {
+      "type": "task",
+      "name": "Design Improvements",
+      "description": "Apply compression techniques: lead with conclusions, causal chains, precise terminology",
+      "agent": "Context Engineer",
+      "stage": "design"
+    },
+    "review_design": {
+      "type": "gate",
+      "name": "Review Design",
+      "description": "Verify improvements don't sacrifice meaning for brevity",
+      "agent": "Reviewer",
+      "stage": "design",
+      "maxRetries": 2,
+      "config": {
+        "scrutinyLevel": 2
+      }
+    },
+    "implement": {
+      "type": "task",
+      "name": "Implement",
+      "description": "Apply the optimizations to actual files and configurations",
+      "agent": "Developer",
+      "stage": "implementation"
+    },
+    "verify": {
+      "type": "task",
+      "name": "Verify",
+      "description": "Test that agents still function correctly with optimized context",
+      "agent": "Tester",
+      "stage": "verification",
+      "maxRetries": 2
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "name": "Complete",
+      "description": "Context optimization complete"
+    },
+    "hitl_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "name": "Needs Help",
+      "description": "Optimization needs human guidance"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "map_connections"
+    },
+    {
+      "from": "map_connections",
+      "to": "identify_pathologies"
+    },
+    {
+      "from": "identify_pathologies",
+      "to": "design_improvements"
+    },
+    {
+      "from": "design_improvements",
+      "to": "review_design"
+    },
+    {
+      "from": "review_design",
+      "to": "design_improvements",
+      "on": "failed",
+      "label": "Revise optimizations"
+    },
+    {
+      "from": "review_design",
+      "to": "hitl_failed",
+      "on": "failed",
+      "label": "Design needs human input"
+    },
+    {
+      "from": "review_design",
+      "to": "implement",
+      "on": "passed",
+      "label": "Design approved"
+    },
+    {
+      "from": "implement",
+      "to": "verify"
+    },
+    {
+      "from": "verify",
+      "to": "implement",
+      "on": "failed",
+      "label": "Fix issues"
+    },
+    {
+      "from": "verify",
+      "to": "hitl_failed",
+      "on": "failed",
+      "label": "Verification failed"
+    },
+    {
+      "from": "verify",
+      "to": "end_success",
+      "on": "passed",
+      "label": "Optimization verified"
+    }
+  ]
+}