Aligner - Visual Feedback Loop for AI Agents

Generate flowcharts and diagrams that users can edit visually. Read their comments and iterate together.

Prerequisites

Aligner must be running for visual editing. Check or start it:

# Check if running
curl -s http://localhost:3001/diagrams > /dev/null && echo "Aligner running" || echo "Not running"

# To start (user runs in separate terminals):
# Terminal 1: cd ~/dev/aligner/server && node index.js
# Terminal 2: cd ~/dev/aligner && npm run dev
# Browser: http://localhost:5173

If Aligner is not running, instruct the user to start it before proceeding.

Workflow

1. Generate diagram → Write JSON to ~/.aligner/global/diagram-name.json
2. Notify user → "View/edit your diagram at http://localhost:5173"
3. Wait for feedback → User drags nodes, adds comments
4. Read comments → Use the read-comments script
5. Respond → Update diagram or reply to comments
6. Iterate → Repeat until satisfied

Creating a Diagram

Write a JSON file to ~/.aligner/global/ (for global diagrams) or <repo>/.aligner/ (for repo-specific diagrams):

{
  "version": "1.0",
  "name": "Descriptive Name",
  "type": "flowchart",
  "nodes": [
    {
      "id": "unique-id",
      "type": "rect",
      "label": "Node Label",
      "position": { "x": 100, "y": 100 },
      "size": { "width": 160, "height": 50 },
      "style": { "fill": "#dbeafe", "stroke": "#3b82f6", "cornerRadius": 8 }
    }
  ],
  "edges": [
    { "id": "e1", "from": "source-id", "to": "target-id", "type": "arrow", "label": "optional" }
  ],
  "metadata": { "description": "What this diagram shows" }
}

Node Types

| Type | Shape | Use For | |------|-------|---------| | rect | Rectangle | Actions, steps, processes | | diamond | Diamond | Decisions, conditionals | | circle | Circle | Start/end points |

Edge Types

| Type | Appearance | |------|------------| | arrow | Solid line with arrow | | dashed | Dashed line (optional/async paths) | | line | Solid line, no arrow |

Color Palette

Use consistent colors for semantic meaning:

| Meaning | Fill | Stroke | Example | |---------|------|--------|---------| | Primary/Action | #dbeafe | #3b82f6 | Main flow steps | | Success | #dcfce7 | #22c55e | Completion states | | Decision | #fef3c7 | #f59e0b | Conditionals | | Error | #fee2e2 | #ef4444 | Failure paths | | External | #e0e7ff | #6366f1 | Third-party systems | | Neutral | #f3f4f6 | #6b7280 | Secondary steps | | User | #fce7f3 | #ec4899 | User actions |

Reading User Feedback

To check for user comments on a diagram:

scripts/read-comments.py ~/.aligner/global/diagram-name.json

This outputs all nodes with comments in a readable format.

Replying to Comments

To reply to a user comment, add to the node's comments array:

{
  "id": "some-node",
  "label": "Some Step",
  "comments": [
    { "from": "user", "text": "Is this the right approach?" },
    { "from": "agent", "text": "Yes, this follows the existing pattern in the codebase." }
  ]
}

Always preserve existing comments when updating - append your reply, don't replace.

Layout Guidelines

• Vertical flow: Top to bottom, 100-120px between rows
• Horizontal flow: Left to right, 200-250px between columns
• Node sizes: 150-180px width, 50-80px height (larger for multi-line labels)
• Decision diamonds: 140-160px width, 70-90px height
• Use \n for multi-line labels

Example: Simple Auth Flow

{
  "version": "1.0",
  "name": "Login Flow",
  "type": "flowchart",
  "nodes": [
    {
      "id": "start",
      "type": "circle",
      "label": "Start",
      "position": { "x": 180, "y": 30 },
      "size": { "width": 60, "height": 60 },
      "style": { "fill": "#dcfce7", "stroke": "#22c55e" }
    },
    {
      "id": "login-form",
      "type": "rect",
      "label": "Show Login Form",
      "position": { "x": 130, "y": 120 },
      "size": { "width": 160, "height": 50 },
      "style": { "fill": "#dbeafe", "stroke": "#3b82f6", "cornerRadius": 8 }
    },
    {
      "id": "validate",
      "type": "diamond",
      "label": "Valid?",
      "position": { "x": 145, "y": 210 },
      "size": { "width": 130, "height": 80 },
      "style": { "fill": "#fef3c7", "stroke": "#f59e0b" }
    },
    {
      "id": "success",
      "type": "rect",
      "label": "Dashboard",
      "position": { "x": 30, "y": 330 },
      "size": { "width": 140, "height": 50 },
      "style": { "fill": "#dcfce7", "stroke": "#22c55e", "cornerRadius": 8 }
    },
    {
      "id": "error",
      "type": "rect",
      "label": "Show Error",
      "position": { "x": 250, "y": 330 },
      "size": { "width": 140, "height": 50 },
      "style": { "fill": "#fee2e2", "stroke": "#ef4444", "cornerRadius": 8 }
    }
  ],
  "edges": [
    { "id": "e1", "from": "start", "to": "login-form", "type": "arrow" },
    { "id": "e2", "from": "login-form", "to": "validate", "type": "arrow" },
    { "id": "e3", "from": "validate", "to": "success", "type": "arrow", "label": "Yes" },
    { "id": "e4", "from": "validate", "to": "error", "type": "arrow", "label": "No" },
    { "id": "e5", "from": "error", "to": "login-form", "type": "dashed" }
  ],
  "metadata": { "description": "User authentication flow" }
}

Tips

• Keep labels concise - detailed explanations go in comments
• Use the user's domain language in labels
• Start simple, let the user request more detail
• Always tell the user where to view the diagram after creating it