Flowi - Visual Planning & Diagramming

Workflow

1. Create

   .flowi/

   directory in the project root if it doesn't exist
2. Write JSON diagram files to

   .flowi/*.json

3. Start the viewer if not already running (tell the user to run the server)
4. Read back any changes the user makes visually
5. Iterate based on visual feedback

Starting the Viewer

node ~/.claude/skills/flowi/server.js

http://localhost:3333

• Renders all

  .flowi/*.json

  files as interactive diagrams
• Live-reloads when you write new JSON
• Saves the user's visual edits back to the JSON files

JSON Schema

.flowi/*.json

{
  "title": "Diagram Title",
  "type": "flowchart",
  "nodes": [
    {
      "id": "unique-id",
      "type": "start|process|decision|end|io|database|component|note",
      "label": "Node Label",
      "description": "",
      "x": 100,
      "y": 100,
      "color": ""
    }
  ],
  "edges": [
    {
      "from": "source-node-id",
      "to": "target-node-id",
      "label": ""
    }
  ]
}

Node Types

start

end

process

decision

io

database

component

note

Diagram Types

"type"

• "flowchart"

  - Top-to-bottom flow (default)

• "architecture"

  - Free-form system diagram

• "sequence"

  - Left-to-right sequence

• "statechart"

  - State machine

• "mockup"

  - UI wireframe layout

Layout Guidelines

• Place nodes on a grid: x increments of 200, y increments of 150
• Start nodes at top (y: 50), flow downward
• Decision branches: place "yes" path to the right, "no" path below
• Keep diagrams readable: max ~15 nodes per diagram, split into multiple files if larger
• Use descriptive file names:

  auth-flow.json

  ,

  database-schema.json

  ,

  checkout-states.json

Reading User Edits

1. Read the JSON file back from

   .flowi/

2. Note changed positions, added/removed nodes, edited labels
3. Ask the user what they'd like you to do with the changes
4. Update your implementation plan accordingly

Example: Simple Auth Flow

.flowi/auth-flow.json

{
  "title": "Authentication Flow",
  "type": "flowchart",
  "nodes": [
    { "id": "start", "type": "start", "label": "User visits app", "x": 300, "y": 50 },
    { "id": "check", "type": "decision", "label": "Has session?", "x": 300, "y": 200 },
    { "id": "login", "type": "process", "label": "Show login form", "x": 100, "y": 350 },
    { "id": "auth", "type": "io", "label": "Call auth API", "x": 100, "y": 500 },
    { "id": "dashboard", "type": "process", "label": "Load dashboard", "x": 500, "y": 350 },
    { "id": "end", "type": "end", "label": "App ready", "x": 300, "y": 650 }
  ],
  "edges": [
    { "from": "start", "to": "check" },
    { "from": "check", "to": "login", "label": "No" },
    { "from": "check", "to": "dashboard", "label": "Yes" },
    { "from": "login", "to": "auth" },
    { "from": "auth", "to": "dashboard", "label": "Success" },
    { "from": "dashboard", "to": "end" }
  ]
}

Best Practices

• Always create the

  .flowi/

  directory first with

  mkdir -p .flowi

• Write one diagram per concept/flow
• After writing JSON, remind the user to check

  http://localhost:3333

• When the user says they've made edits, read the file back before proceeding
• Use the diagram as the source of truth for planning, then implement based on it