@leclabs/agent-flow-navigator-mcp 1.0.0

package/catalog/workflows/ui-reconstruction.json

@@ -0,0 +1,241 @@
+{
+  "id": "ui-reconstruction",
+  "name": "UI Reconstruction",
+  "description": "Extract semantic IR from existing UI, rebuild from specification. Implements the 'Platonic Form' philosophy - capturing the essence (what) not the implementation (how).",
+  "nodes": {
+    "start": {
+      "type": "start",
+      "description": "Workflow entry point"
+    },
+    "ir_component_tree": {
+      "type": "task",
+      "name": "ir_component_tree",
+      "description": "Extract UI component hierarchy with element types, nesting, and framework imports. Output: Component tree with semantic roles.",
+      "agent": "Planner",
+      "stage": "semantic-ir-extraction"
+    },
+    "ir_feature_boundary": {
+      "type": "task",
+      "name": "ir_feature_boundary",
+      "description": "Determine logical groupings of components that form discrete features. Output: Feature map with parent-child relationships.",
+      "agent": "Planner",
+      "stage": "semantic-ir-extraction"
+    },
+    "ir_interactivity": {
+      "type": "task",
+      "name": "ir_interactivity",
+      "description": "Document user interactions: click handlers, form submissions, state mutations, and data flow. Output: Interaction inventory.",
+      "agent": "Planner",
+      "stage": "semantic-ir-extraction"
+    },
+    "ir_business_object": {
+      "type": "task",
+      "name": "ir_business_object",
+      "description": "Identify domain entities displayed or manipulated by the UI and their CRUD operations. Output: Business object catalog.",
+      "agent": "Planner",
+      "stage": "semantic-ir-extraction"
+    },
+    "ir_annotate": {
+      "type": "task",
+      "name": "ir_annotate",
+      "description": "Overlay visual markers on screenshot identifying components, features, and interactions. Output: Annotated screenshot.",
+      "agent": "Planner",
+      "stage": "semantic-ir-extraction"
+    },
+    "ir_ascii": {
+      "type": "task",
+      "name": "ir_ascii",
+      "description": "Create text-based diagrams showing UI state transitions and user flows. Output: ASCII state machine diagram.",
+      "agent": "Planner",
+      "stage": "semantic-ir-extraction"
+    },
+    "ir_review": {
+      "type": "gate",
+      "name": "Review",
+      "description": "Validate completeness and accuracy of Semantic IR against source UI. Criteria: All visible elements mapped, interactions documented.",
+      "agent": "Reviewer",
+      "stage": "semantic-ir-extraction",
+      "maxRetries": 3,
+      "config": {
+        "scrutinyLevel": 3
+      }
+    },
+    "uiRebuild_build": {
+      "type": "task",
+      "name": "uiRebuild_build",
+      "description": "Implement UI from Semantic IR specification, matching visual layout and behavior. Preserve semantic structure over visual mimicry.",
+      "agent": "Developer",
+      "stage": "ui-build-from-ir"
+    },
+    "uiRebuild_review": {
+      "type": "gate",
+      "name": "Review",
+      "description": "Compare rebuilt UI against original screenshot and Semantic IR. Verify functional equivalence and semantic fidelity.",
+      "agent": "Reviewer",
+      "stage": "ui-build-from-ir",
+      "maxRetries": 3,
+      "config": {
+        "scrutinyLevel": 4
+      }
+    },
+    "final_review": {
+      "type": "gate",
+      "name": "Review",
+      "description": "Verify rebuilt UI captures essential purpose (Platonic Form) not just appearance. Test: Could this IR reconstruct the UI in a different framework?",
+      "agent": "Reviewer",
+      "stage": "unbiased-review",
+      "maxRetries": 1,
+      "config": {
+        "scrutinyLevel": 2
+      }
+    },
+    "end_success": {
+      "type": "end",
+      "result": "success",
+      "description": "Workflow completed successfully"
+    },
+    "hitl_ir_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "description": "IR extraction failed after max retries - requires human intervention"
+    },
+    "hitl_build_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "description": "UI rebuild failed after max retries - requires human intervention"
+    },
+    "hitl_final_failed": {
+      "type": "end",
+      "result": "blocked",
+      "escalation": "hitl",
+      "description": "Final review failed after max retries - requires human intervention"
+    },
+    "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"
+    }
+  },
+  "edges": [
+    {
+      "from": "start",
+      "to": "ir_component_tree"
+    },
+    {
+      "from": "ir_component_tree",
+      "to": "ir_feature_boundary"
+    },
+    {
+      "from": "ir_feature_boundary",
+      "to": "ir_interactivity"
+    },
+    {
+      "from": "ir_interactivity",
+      "to": "ir_business_object"
+    },
+    {
+      "from": "ir_business_object",
+      "to": "ir_annotate"
+    },
+    {
+      "from": "ir_annotate",
+      "to": "ir_ascii"
+    },
+    {
+      "from": "ir_ascii",
+      "to": "ir_review"
+    },
+    {
+      "from": "ir_review",
+      "to": "ir_component_tree",
+      "on": "failed",
+      "label": "Reviewer feedback is provided to the analyzer"
+    },
+    {
+      "from": "ir_review",
+      "to": "hitl_ir_failed",
+      "on": "failed",
+      "label": "IR extraction exhausted retries"
+    },
+    {
+      "from": "ir_review",
+      "to": "uiRebuild_build",
+      "on": "passed",
+      "label": "Semantic IR is verified"
+    },
+    {
+      "from": "uiRebuild_build",
+      "to": "uiRebuild_review"
+    },
+    {
+      "from": "uiRebuild_review",
+      "to": "uiRebuild_build",
+      "on": "failed",
+      "label": "Reviewer feedback is provided to the builder"
+    },
+    {
+      "from": "uiRebuild_review",
+      "to": "hitl_build_failed",
+      "on": "failed",
+      "label": "UI rebuild exhausted retries"
+    },
+    {
+      "from": "uiRebuild_review",
+      "to": "final_review",
+      "on": "passed",
+      "label": "Build review passed"
+    },
+    {
+      "from": "final_review",
+      "to": "uiRebuild_build",
+      "on": "failed",
+      "label": "Reviewer feedback is provided to the builder"
+    },
+    {
+      "from": "final_review",
+      "to": "hitl_final_failed",
+      "on": "failed",
+      "label": "Final review exhausted retries"
+    },
+    {
+      "from": "final_review",
+      "to": "lint_format",
+      "on": "passed",
+      "label": "Platonic form verified"
+    },
+    {
+      "from": "lint_format",
+      "to": "commit",
+      "on": "passed",
+      "label": "Lint passes, commit changes"
+    },
+    {
+      "from": "lint_format",
+      "to": "uiRebuild_build",
+      "on": "failed",
+      "label": "Fix lint/format issues"
+    },
+    {
+      "from": "lint_format",
+      "to": "hitl_final_failed",
+      "on": "failed",
+      "label": "Lint issues persist"
+    },
+    {
+      "from": "commit",
+      "to": "end_success"
+    }
+  ]
+}

package/catalog.js

@@ -0,0 +1,64 @@
+/**
+ * catalog.js - Pure catalog reader module
+ *
+ * Transforms workflow data into catalog listings and selection options.
+ * Actual file I/O handled by MCP handler.
+ */
+
+/**
+ * Build a workflow summary from workflow content
+ * @param {string} fileId - File name without .json extension
+ * @param {Object} content - Workflow content from JSON
+ * @returns {Object} Workflow summary
+ */
+export function buildWorkflowSummary(fileId, content) {
+  return {
+    id: content.id || fileId,
+    name: content.name || content.id || fileId,
+    description: content.description || "",
+    stepCount: Object.keys(content.nodes || {}).length,
+  };
+}
+
+/**
+ * Build selection options for AskUserQuestion from workflow list
+ * @param {Array} workflows - Array of workflow summaries
+ * @returns {Array} Selection options with "All" first
+ */
+export function buildCatalogSelectionOptions(workflows) {
+  return [
+    {
+      label: "All workflows (Recommended)",
+      description: `Copy all ${workflows.length} workflows to your project`,
+    },
+    ...workflows.map((wf) => ({
+      label: wf.name,
+      description: `${wf.description} (${wf.stepCount} steps)`,
+    })),
+  ];
+}
+
+/**
+ * Build the complete catalog response
+ * @param {Array} workflows - Array of workflow summaries
+ * @returns {Object} Catalog response object
+ */
+export function buildCatalogResponse(workflows) {
+  return {
+    schemaVersion: 2,
+    workflows,
+    selectionOptions: buildCatalogSelectionOptions(workflows),
+  };
+}
+
+/**
+ * Build empty catalog response
+ * @returns {Object} Empty catalog response
+ */
+export function buildEmptyCatalogResponse() {
+  return {
+    schemaVersion: 2,
+    workflows: [],
+    selectionOptions: [],
+  };
+}

package/copier.js

@@ -0,0 +1,179 @@
+/**
+ * copier.js - Pure workflow copier module
+ *
+ * Generates README content and provides helpers for workflow copying.
+ * Actual file I/O handled by MCP handler.
+ */
+
+/**
+ * Generate root README.md content for .flow/
+ * @returns {string} README content
+ */
+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.
+
+## 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
+
+# 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
+
+# Run the task autonomously
+/flow:run
+\`\`\`
+
+## 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
+
+## Customization (Optional)
+
+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
+
+## How It Works
+
+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
+`;
+}
+
+/**
+ * Generate README.md content for .flow/workflows/
+ * @returns {string} README content
+ */
+export function generateWorkflowsReadme() {
+  return `# Flow Workflows
+
+This directory contains workflow definitions for the flow plugin.
+
+## Directory Structure
+
+\`\`\`
+.flow/workflows/
+├── README.md              # This file
+└── {workflow}/
+    └── workflow.json      # DAG definition (steps + edges)
+\`\`\`
+
+## How Step Instructions Work
+
+Step instructions are generated automatically from:
+1. **workflow.json** - \`name\` and \`description\` fields for each step
+2. **Baseline patterns** - Default guidance based on step type (analyze, implement, test, etc.)
+
+The \`Navigate\` API returns \`stepInstructions\` with all this combined.
+
+## Customizing Step Instructions
+
+To add custom instructions for a step, add an \`instructions\` field to the node definition in \`workflow.json\`:
+
+\`\`\`json
+{
+  "nodes": {
+    "implement": {
+      "type": "task",
+      "name": "Implement Feature",
+      "description": "Build the feature according to the plan",
+      "instructions": "Run /my-skill before starting. Load context from .claude/context/impl-guide.md",
+      "agent": "Developer"
+    }
+  }
+}
+\`\`\`
+
+### Custom Instruction Ideas
+
+- **Run a skill**: \`"Run /lint-fix after making changes"\`
+- **Load context**: \`"Read .claude/context/api-patterns.md first"\`
+- **Project conventions**: \`"Follow the error handling pattern in src/utils/errors.ts"\`
+- **Specific tools**: \`"Use the Grep tool to find existing implementations"\`
+
+## Editing Workflows
+
+### workflow.json
+
+Defines the workflow DAG:
+- \`nodes\`: Map of node definitions (type, name, description, agent, maxRetries)
+- \`edges\`: Array of transitions between nodes (from, to, on, label)
+
+Do NOT edit edge logic unless you understand DAG flow control.
+
+## Adding Custom Workflows
+
+1. Create a new directory: \`.flow/workflows/my-workflow/\`
+2. Add \`workflow.json\` with steps and edges
+3. Run \`/flow:load\` to reload workflows
+`;
+}
+
+/**
+ * Validate a workflow for copying
+ * @param {Object} content - Workflow content from JSON
+ * @returns {boolean} True if valid for copying
+ */
+export function isValidWorkflowForCopy(content) {
+  return !!(content && content.nodes && content.edges);
+}
+
+/**
+ * Compute which workflow IDs to copy
+ * @param {string[]} requestedIds - Specifically requested workflow IDs (may be empty)
+ * @param {string[]} availableIds - All available workflow IDs in catalog
+ * @returns {string[]} IDs to copy
+ */
+export function computeWorkflowsToCopy(requestedIds, availableIds) {
+  if (requestedIds && requestedIds.length > 0) {
+    return requestedIds;
+  }
+  return availableIds;
+}

package/diagram.js

@@ -0,0 +1,146 @@
+/**
+ * diagram.js - Pure diagram generation module
+ *
+ * Generates mermaid flowchart diagrams from workflow definitions.
+ * No I/O operations - file saving handled by MCP handler.
+ */
+
+import { isTerminalNode, getTerminalType, toSubagentRef } from "./engine.js";
+
+/**
+ * Sanitize a label for mermaid flowcharts
+ */
+function sanitizeMermaidLabel(label, maxLen = 40) {
+  if (!label) return "";
+  let clean = label
+    .replace(/"/g, "'")
+    .replace(/[&]/g, "and")
+    .replace(/[<>]/g, "")
+    .replace(/[[\]{}()]/g, "")
+    .replace(/[|]/g, "-")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (clean.length > maxLen) {
+    clean = clean.substring(0, maxLen - 3) + "...";
+  }
+  return clean;
+}
+
+/**
+ * Sanitize edge labels for mermaid
+ */
+function sanitizeEdgeLabel(on) {
+  if (!on) return "";
+  return on.replace(/[|"]/g, "");
+}
+
+/**
+ * Generate a mermaid flowchart diagram from a workflow definition
+ *
+ * @param {Object} workflowDef - The workflow definition object
+ * @param {string} [currentStep] - Optional step ID to highlight
+ * @returns {string} Markdown string with mermaid diagram and step instructions table
+ */
+export function generateDiagram(workflowDef, currentStep = null) {
+  const { nodes, edges } = workflowDef;
+
+  // Build mermaid diagram
+  const lines = ["flowchart TD"];
+
+  for (const [stepId, step] of Object.entries(nodes)) {
+    const label = sanitizeMermaidLabel(step.name || step.description || stepId);
+    const agent = step.agent ? `<br/><small>${step.agent}</small>` : "";
+    const termType = getTerminalType(step);
+    if (termType === "start") {
+      lines.push(`    ${stepId}(("${label}"))`);
+    } else if (termType === "success") {
+      lines.push(`    ${stepId}[["${label}"]]`);
+    } else if (termType === "hitl" || termType === "failure") {
+      lines.push(`    ${stepId}{{"${label}"}}`);
+    } else if (step.type === "gate") {
+      lines.push(`    ${stepId}{"${label}"}`);
+    } else {
+      lines.push(`    ${stepId}["${label}${agent}"]`);
+    }
+  }
+
+  lines.push("");
+
+  for (const edge of edges) {
+    const { from, to, on } = edge;
+    const edgeLabel = sanitizeEdgeLabel(on);
+    if (edgeLabel) {
+      lines.push(`    ${from} -->|${edgeLabel}| ${to}`);
+    } else {
+      lines.push(`    ${from} --> ${to}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("    classDef startStep fill:#90EE90,stroke:#228B22");
+  lines.push("    classDef successStep fill:#87CEEB,stroke:#4169E1");
+  lines.push("    classDef hitlStep fill:#FFB6C1,stroke:#DC143C");
+  lines.push("    classDef gateStep fill:#E6E6FA,stroke:#9370DB");
+  lines.push("    classDef currentStep fill:#FFD700,stroke:#FF8C00,stroke-width:3px");
+
+  const startSteps = Object.entries(nodes)
+    .filter(([, s]) => getTerminalType(s) === "start")
+    .map(([id]) => id);
+  const successSteps = Object.entries(nodes)
+    .filter(([, s]) => getTerminalType(s) === "success")
+    .map(([id]) => id);
+  const hitlSteps = Object.entries(nodes)
+    .filter(([, s]) => getTerminalType(s) === "hitl" || getTerminalType(s) === "failure")
+    .map(([id]) => id);
+  const gateSteps = Object.entries(nodes)
+    .filter(([, s]) => s.type === "gate")
+    .map(([id]) => id);
+
+  if (startSteps.length) lines.push(`    class ${startSteps.join(",")} startStep`);
+  if (successSteps.length) lines.push(`    class ${successSteps.join(",")} successStep`);
+  if (hitlSteps.length) lines.push(`    class ${hitlSteps.join(",")} hitlStep`);
+  if (gateSteps.length) lines.push(`    class ${gateSteps.join(",")} gateStep`);
+
+  if (currentStep && nodes[currentStep]) {
+    lines.push(`    class ${currentStep} currentStep`);
+  }
+
+  // Build instructions table
+  const tableRows = [];
+  tableRows.push("| Stage | Step | Name | Agent | Instructions |");
+  tableRows.push("|-------|------|------|-------|--------------|");
+
+  // Group steps by stage for organized display - filter out terminal/start/end nodes
+  const stepEntries = Object.entries(nodes).filter(([, step]) => !isTerminalNode(step));
+
+  for (const [stepId, step] of stepEntries) {
+    const stage = step.stage || "-";
+    const name = step.name || stepId;
+    const agent = step.agent ? toSubagentRef(step.agent) : "-";
+    const instructions = step.instructions || step.description || "-";
+    // Escape pipes in table cells
+    const safeInstructions = instructions.replace(/\|/g, "\\|");
+    tableRows.push(`| ${stage} | ${stepId} | ${name} | ${agent} | ${safeInstructions} |`);
+  }
+
+  // Assemble output with markdown code block for mermaid
+  return [
+    `## Workflow: ${workflowDef.name || workflowDef.id}`,
+    "",
+    workflowDef.description || "",
+    "",
+    "### Diagram",
+    "",
+    "```mermaid",
+    ...lines,
+    "```",
+    "",
+    "### Step Instructions",
+    "",
+    ...tableRows,
+  ].join("\n");
+}
+
+// Export helpers for testing
+export { sanitizeMermaidLabel, sanitizeEdgeLabel };

package/dialog.js

@@ -0,0 +1,63 @@
+/**
+ * dialog.js - Pure dialog builder module
+ *
+ * Builds dialog structures for workflow selection.
+ * No I/O operations - just data transformation.
+ */
+
+/**
+ * Build an option object from a workflow
+ * @param {Object} workflow - Workflow summary object
+ * @returns {Object} Option for dialog
+ */
+function buildOption(workflow) {
+  return {
+    label: workflow.name,
+    description: `${workflow.description} (${workflow.stepCount} steps)`,
+  };
+}
+
+/**
+ * Build workflow selection dialog structure
+ *
+ * @param {Array} workflows - Array of workflow summaries from store.listWorkflows()
+ * @returns {Object} Dialog structure with workflows and dialog panels
+ */
+export function buildWorkflowSelectionDialog(workflows) {
+  const byId = Object.fromEntries(workflows.map((w) => [w.id, w]));
+
+  const opt = (id) => (byId[id] ? buildOption(byId[id]) : null);
+
+  return {
+    schemaVersion: 2,
+    workflows,
+    dialog: [
+      {
+        question: "Which workflow?",
+        header: "Primary",
+        multiSelect: false,
+        options: [opt("feature-development"), opt("bug-fix"), opt("context-optimization"), opt("test-coverage")].filter(
+          Boolean
+        ),
+      },
+      {
+        question: "Or a simpler/specialized workflow?",
+        header: "Other",
+        multiSelect: false,
+        options: [opt("agile-task"), opt("quick-task"), opt("ui-reconstruction")].filter(Boolean),
+      },
+      {
+        question: "Include documentation?",
+        header: "Docs",
+        multiSelect: false,
+        options: [
+          { label: "Yes", description: "Generate documentation for the workflow" },
+          { label: "No", description: "Skip documentation" },
+        ],
+      },
+    ],
+  };
+}
+
+// Export helper for testing
+export { buildOption };