claude-project-flow-map

# 🗺️ project-flow-map A [Claude Code](https://claude.com/claude-code) **skill** that reads any codebase end-to-end and turns it into a **colorful, role-based user-flow map** — either a live **FigJam** board (via the Figma MCP) or a self-contained **Markdown file** with the flow drawn as a Mermaid diagram. Point Claude at a repo, say *"map the user flows"*, and get an honest visual of how the tool actually works: the login/session gate, one swimlane per role, the core end-to-end lifecycle, and entity state machines — with placeholder / not-yet-built paths clearly marked as dashed so **as-built vs intended** is obvious at a glance. > Works for any project: web app, back-office, SaaS, API+UI. --- ## ✨ What you get Two output modes, picked automatically: | Mode | When | Output | |------|------|--------| | **FigJam board** *(preferred)* | Figma MCP is set up | A live, editable FigJam diagram in your Figma account, with a claim URL | | **Markdown file** *(fallback)* | Figma MCP **not** set up | A single `PROJECT-FLOW-MAP.md` with a `mermaid` diagram that renders on GitHub, GitLab, VS Code, Obsidian & Notion | Both use the same analysis, the same swimlane structure, and the same color palette — so you're never blocked just because you haven't wired up Figma yet. See [`examples/EXAMPLE-FLOW-MAP.md`](examples/EXAMPLE-FLOW-MAP.md) for a sample of the Markdown output (view it on GitHub to see the diagram render). --- ## 📦 Requirements - **[Claude Code](https://claude.com/claude-code)** (CLI, desktop, or IDE extension). Skills live in `~/.claude/skills/`. - **(Optional) Figma MCP** — only needed for the live FigJam board. Without it, the skill automatically produces the Markdown flow map instead. See [Setting up the Figma MCP](#-optional-setting-up-the-figma-mcp) below. You do **not** need a Figma account to use this skill — the Markdown mode needs nothing beyond Claude Code. --- ## 🚀 Installation Skills are just a folder containing a `SKILL.md`. Install it once into your Claude Code skills directory and it's available in every project. ### Option A — one-line install (macOS / Linux) ```bash git clone https://github.com/lmohamed95/claude-project-flow-map.git cd claude-project-flow-map ./install.sh ``` ### Option B — manual copy ```bash git clone https://github.com/lmohamed95/claude-project-flow-map.git cp -r claude-project-flow-map/project-flow-map ~/.claude/skills/ ``` ### Option C — per-project (share it with a repo/team) Commit the skill into a project so everyone who clones it gets it: ```bash mkdir -p .claude/skills cp -r /path/to/claude-project-flow-map/project-flow-map .claude/skills/ ``` **Verify it's installed:** start Claude Code and run `/project-flow-map` — it should appear in the skill list. --- ## 💡 Usage Just ask, in plain language, inside the repo you want mapped. Any of these will trigger the skill: - `map the user flows` - `/project-flow-map` - `make a flowchart of how this app works` - `figjam of the project` - `diagram the user journey by role` **What happens next:** 1. **Analyze** — Claude reads your routing, navigation, auth, roles/permissions, domain models and per-module maturity to build a factual model, and gives you a short written summary first. 2. **Confirm scope** — it asks once (with sane defaults) whether to structure the map *by role*, as a *single end-to-end flow*, or *by module*. 3. **Generate** — - If the **Figma MCP is set up** → a FigJam board + a claim URL. - If **not** → a `PROJECT-FLOW-MAP.md` in your repo you can preview in VS Code (`Cmd/Ctrl+Shift+V`) or push to GitHub. 4. **Present** — a summary of the zones, the color key, and honest caveats (which flows are real vs placeholder, which role permissions are enforced vs only intended). ### Reading the map | Color | Meaning | |-------|---------| | 🔵 Blue | Entry / session | | 🟡 Yellow diamond | Decision point | | 🟣🟠🔵🟢 | One color per role | | 🔴 Red | Core lifecycle (the main journey) | | ⬜ Grey | Entity state machine | | ⬛ Dashed | Placeholder / target — **not built yet** | --- ## 🎨 (Optional) Setting up the Figma MCP Only needed if you want the live, editable **FigJam** board instead of Markdown. The skill uses Figma's official MCP server. Add it as a connector in Claude: - **Claude Code / claude.ai:** add the **Figma** connector in your MCP / connector settings and authorize it, then in Claude Code confirm with `/mcp`. - **CLI:** `claude mcp add` and follow the prompts for the Figma server, then authorize via `/mcp`. Once connected, re-run the skill and it will produce a FigJam board automatically. See Figma's docs for the current MCP setup steps: <https://help.figma.com/hc/en-us/articles/32132100833559>. > **No Figma? No problem.** Skip this entirely — the skill detects the missing MCP > and writes the Markdown flow map instead. --- ## 🧠 How it works (under the hood) The whole skill is a single [`SKILL.md`](project-flow-map/SKILL.md) — a Markdown file with YAML frontmatter that Claude Code loads on demand. It defines four phases (Analyze → Confirm scope → Generate → Present) and a strict set of Mermaid conventions and a color palette so the diagrams come out consistent and readable. Everything is grounded in your real code — the skill is explicitly told to never invent modules or roles, and to mark anything it isn't sure is wired up as a dashed "planned" node. --- ## ❓ Troubleshooting - **`/project-flow-map` doesn't show up** — make sure the folder is at `~/.claude/skills/project-flow-map/SKILL.md` (not nested deeper) and restart Claude Code. - **The Mermaid diagram shows as code, not a picture** — you're viewing it in a renderer that doesn't support Mermaid. GitHub, VS Code preview, Obsidian and Notion all render it; plain text editors won't. - **FigJam generation fails** — it's almost always a Mermaid syntax issue (unquoted label, a stray `end`, or an emoji). The skill's conventions avoid these; if it still fails, the same diagram is delivered as Markdown. --- ## 🤝 Sharing & contributing This repo *is* the shareable package — send friends the link and point them at the [Installation](#-installation) section. Issues and PRs welcome: improvements to the Mermaid conventions, more color palettes, or new zone templates. ## 📄 License [MIT](LICENSE) — do whatever you want, no warranty.