Project Flow Map

Project Flow Map

Turn a codebase into a role-based, color-coded user-flow map.

There are two output modes:

• FigJam (preferred) — a Mermaid flowchart generated through the Figma MCP

(generate_diagram), organized in swimlane zones (access, one per role, central lifecycle, entity states) with a legend and consistent colors.

• Markdown fallback — when the Figma MCP is not available, write a

self-contained PROJECT-FLOW-MAP.md file with the same analysis and the flow drawn as a `mermaid block. This renders as a diagram on GitHub, GitLab, VS Code, Obsidian, Notion and most Markdown viewers — no Figma account needed.

This skill has four phases: Analyze → Confirm scope → Generate → Present. Do the analysis for real from the code — never invent modules or roles.

---

Phase 1 — Analyze the project

Read the code to build a factual model. Prefer delegating broad reads to Explore/general-purpose agents when the repo is large; otherwise read directly. Look for, in roughly this order:

1. Entry & stack — package.json, framework (Next/Vite/etc.), README, and

any AGENTS.md / CLAUDE.md (often the richest summary — read it first if present, but verify against real code).

1. Routing — the route table / router (App.tsx, router.tsx, app/

folder, route configs). This is the module list.

1. Navigation — the sidebar / topbar / menu component. Gives the user-facing

grouping of modules.

1. Auth & access — auth provider/context, login page, session gating,

middleware. Capture the entry flow: login → session valid? → tenant/org check → app.

1. Roles & permissions — role enums (DB migrations, roles /

memberships / *_user_roles tables, constraints like CHECK (role IN ...)), membership status lifecycle (invited/active/disabled), and whether roles are actually enforced in the UI or only modeled. Note this explicitly.

1. Domain model & lifecycles — entity types and their status enums

(reservation, order, ticket, invoice, vehicle, etc.). Each status enum is a mini state machine worth drawing.

1. Per-module functionality + maturity — for each module, list what it does

and flag real vs placeholder (look for "coming soon" modals, disabled buttons, mock/stub data, TODO, feature flags). The as-built vs intended distinction matters a lot for an honest map.

Produce (in your head or as a short written analysis for the user): module map, roles + access model, entity lifecycles, and the central operational flow (the one core end-to-end journey the whole tool exists to serve — e.g. a reservation lifecycle, an order-to-cash, a ticket resolution).

Deliver a concise written summary of this analysis to the user before drawing — it is valuable on its own and lets them correct you.

---

Phase 2 — Confirm scope & pick output mode

Detect the output mode first. Check whether the Figma MCP is available:

• If Figma MCP tools are present (possibly deferred — searchable via

ToolSearch for mcp__*Figma__generate_diagram), use FigJam (Phase 3A).

• If they are not available / not configured, tell the user briefly that

Figma MCP isn't set up so you'll produce a Markdown flow map instead (Phase 3B), and mention they can wire up the Figma MCP later for a live FigJam board (see the repo README). Do not block on it — just proceed with Markdown.

Then, unless the user already told you, ask once (use AskUserQuestion) with sane defaults:

• Structure — by role (default when the app has ≥2 roles) · single

end-to-end flow · by module.

If Figma MCP is available, also confirm Format — FigJam flowchart (default, recommended) · Markdown file · both.

If the app has no real role system, skip the role question and default to end-to-end or by-module. Don't over-ask — if the user said "like before" or gave enough direction, just build it.

---

Mermaid conventions (shared by both output modes — respect exactly)

• flowchart LR at the top; give each zone its own subgraph ... direction TB.
• Quote every label and edge label: ["Text"], -->|"label"|,

-. "label" .->.

• No emojis. No literal \n. Keep node IDs short, unique, alphanumeric.
• Never use the word end as a node id or in a className.
• Use {"..."} diamonds for decision points.
• Use dotted links -. "..." .-> for cross-zone relations (supervision,

hand-offs, status side-effects); solid arrows for the primary path within a zone.

• Keep it detailed only as far as it stays readable (~40–70 nodes is a good

ceiling). If bigger, split into multiple diagrams.

Zone structure (typical, adapt to the project)

1. Legend — one node per color + what dashed/diamonds mean.
2. Access & session — login → {session valid?} → {tenant/role?} →

dashboard.

1. One subgraph per role — the modules & key actions that role owns; for an

owner/admin include the member lifecycle (invite → active → change role → disable).

1. Central lifecycle — the core end-to-end journey with its status nodes and

decision branches.

1. Entity state machines (optional) — e.g. vehicle/order status, linked with

dotted "status change" edges from the steps that trigger them.

Route each role from the access aiguillage: ROLE -->|"role name"| firstNode.

Reusable color palette (paste, then assign classes)

classDef entry    fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
classDef decision fill:#fde68a,stroke:#d97706,color:#78350f
classDef roleA    fill:#ede9fe,stroke:#7c3aed,color:#4c1d95
classDef roleB    fill:#ffedd5,stroke:#ea580c,color:#7c2d12
classDef roleC    fill:#cffafe,stroke:#0891b2,color:#164e63
classDef roleD    fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef core     fill:#ffe4e6,stroke:#e11d48,color:#881337
classDef state    fill:#f1f5f9,stroke:#64748b,color:#0f172a
classDef planned  fill:#faf5ff,stroke:#a855f7,color:#6b21a8,stroke-dasharray:5 4
classDef legend   fill:#f8fafc,stroke:#94a3b8,color:#334155

Then class Node1,Node2 roleA etc. Give decision diamonds the decision class, and placeholder / not-yet-built / target-V1 actions the planned (dashed) class — this makes as-built vs intended visible at a glance.

---

Phase 3A — Generate the FigJam diagram (Figma MCP available)

Use the Figma MCP tool generate_diagram (it creates its own FigJam file — do NOT call create_new_file first). In this harness the Figma tools may be deferred: load them with ToolSearch (select:mcp__claude_ai_Figma__whoami, mcp__claude_ai_Figma__generate_diagram) before calling.

Steps:

1. Get the plan key — call whoami. Use the single plan's key

(team::... / organization::...). If several plans, ask which.

1. Write Mermaid following the conventions above.
2. Call generate_diagram with name, mermaidSyntax, planKey, and a

short userIntent. To add to an existing board instead of a new one, pass its fileKey.

---

Phase 3B — Generate the Markdown flow map (Figma MCP not set up)

Write a single self-contained file, default name PROJECT-FLOW-MAP.md, in the repo root (or a path the user asked for). Use this structure:

#  — User Flow Map

> Generated by the `project-flow-map` skill. Diagram renders on GitHub, GitLab,
> VS Code (Markdown preview), Obsidian and Notion. For a live, editable board,
> set up the Figma MCP and re-run (see below).

## Overview

## Roles & access model

## Flow map

​```mermaid
flowchart LR
  %% ...full diagram following the Mermaid conventions above...
​```

## Legend
- Blue = entry/session · Yellow diamond = decision · Purple/Orange/… = per role
- Red = core lifecycle · Grey = entity states · Dashed = placeholder / target (not built)

## Honest caveats

## Upgrade to a live FigJam board
Set up the Figma MCP (see repo README), then re-run the skill for an editable diagram.

Notes:

• Put the diagram in a fenced `mermaid block so it renders as a picture,

not code. The exact same Mermaid conventions and color palette above apply — classDef colors render on GitHub and most viewers.

• Keep everything in one .md file so it's trivial to commit and share.
• After writing, tell the user the file path and that they can preview it in VS

Code (Cmd/Ctrl+Shift+V) or view it on GitHub.

---

Phase 4 — Present

If FigJam:

• Give the claim URL as a clickable link and note that opening it the first

time attaches the board to the user's Figma account (mention their seat may be View only, so editing shapes may need an Edit seat).

If Markdown:

• Give the file path as a clickable link and how to preview it (VS Code

Markdown preview / push to GitHub). Note that Figma MCP would produce an editable board instead.

Both:

• Summarize the zones and the color key.
• State the honest caveats surfaced in analysis: which flows are real vs

placeholder, and — critically — whether role permissions are enforced or only intended (mark intended paths as "cible / target", drawn dashed).

• Offer concrete next steps: add a zone (e.g. Documents), detail a sub-flow,

produce an end-to-end variant, or generate screen frames.

Gotchas

• generate_diagram supports only graph/flowchart/sequence/state/gantt/ER — not

arbitrary Figma design. For screen mockups use the design-generation Figma flow instead (see the Figma MCP use_figma / figma-generate-design skill).

• It can't reposition individual shapes or change fonts after creation — tell the

user to open the board in Figma for manual tweaks.

• If a generate_diagram call fails, read the returned error; usually it's a

Mermaid syntax issue (unquoted label, stray end, or an emoji). The same syntax rules make the Markdown fallback render cleanly — so if you ever fail in FigJam, you can still deliver the identical diagram as Markdown.

• Base every node on real code. If unsure whether something is wired up, read the

handler/page before drawing it as "real".

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lmohamed95
• Source: lmohamed95/claude-project-flow-map
• License: MIT

Install and usage instructions live in the source repository linked above.