Project Flow Map

---
name: project-flow-map
description: >-
  Analyze a codebase end-to-end, extract its functionalities, roles and access
  model, then produce a colorful, role-based user-flow map. Preferred output is a
  FigJam diagram in Figma (via the Figma MCP); when the Figma MCP is not set up,
  it falls back to writing a self-contained Markdown file with the flow drawn as
  a Mermaid diagram. Use when the user asks to "map the project", "map the user
  flow(s)", "diagram how the tool works", "make a flowchart of the app", "figjam
  of the project", "user journey / user flow mapping", or wants a visual overview
  of a tool's features, roles and screens. Works for any project (web app,
  back-office, SaaS, API+UI).
---

# 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).
2. **Routing** — the route table / router (`App.tsx`, `router.tsx`, `app/`
   folder, route configs). This is the module list.
3. **Navigation** — the sidebar / topbar / menu component. Gives the user-facing
   grouping of modules.
4. **Auth & access** — auth provider/context, login page, session gating,
   middleware. Capture the **entry flow**: login → session valid? → tenant/org
   check → app.
5. **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.
6. **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.
7. **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.
3. **One subgraph per role** — the modules & key actions that role owns; for an
   owner/admin include the **member lifecycle** (invite → active → change role →
   disable).
4. **Central lifecycle** — the core end-to-end journey with its status nodes and
   decision branches.
5. **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.
2. **Write Mermaid** following the conventions above.
3. **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:

```markdown
# <Project> — 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
<2–4 sentences: what the tool is, the core journey, roles.>

## Roles & access model
<bullet list of roles + whether permissions are enforced or only intended.>

## 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
<which flows are real vs placeholder; which role permissions are enforced vs intended.>

## 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".