# Project Diagram

> Maintains living project diagrams using Mermaid with multiple outputs: Figma FigJam boards (via generate_diagram), GitHub/GitLab READMEs (native Mermaid render), SVG/PNG for Google Docs, and shareable URLs for Slack. Uses different shapes AND colors per category with a built-in legend. Connects to agent history, GitHub READMEs, and codebases to keep diagrams current. Use when the user says "update my diagram", "refresh project map", "add X to the diagram", "show me my workflow diagram", "diagram sync", "diagram my projects", "map my workflows", "export diagram to docs", "push diagram to figma", "share diagram in slack", or "mermaid my project". This skill is global and available across all workspaces.

- Skill: `jaquevan/project-diagram` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jaquevan/project-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jaquevan/project-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: jaquevan (https://skillmd.com/u/jaquevan)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/jaquevan/project-diagram

---


# Project Diagram

Maintains living, colorful diagrams that map your projects, repos, skills, and
agent workflows. Uses both shape and color to encode meaning so diagrams are
instantly readable by anyone without explanation.

## Output Pipeline

```
Data Sources → Mermaid Code → Multiple Outputs
                                ├── Figma FigJam (via generate_diagram MCP)
                                ├── GitHub/GitLab README (native render)
                                ├── SVG/PNG file (via mmdc)
                                ├── Google Doc (image embed)
                                ├── Slack (PNG upload or mermaid.ink URL)
                                └── Shareable link (mermaid.live)
```

## Prerequisites

- Figma MCP (`plugin-figma-figma`) enabled for FigJam output
- `mmdc` (mermaid-cli) installed globally: `npm install -g @mermaid-js/mermaid-cli`
- Config at `.diagrams/project-map.json` in the project workspace

## Visual System: Shape + Color

Every node encodes TWO dimensions of meaning:

1. **Shape** tells you WHAT TYPE of thing it is
2. **Color** confirms the category at a glance

| Category | Shape | Mermaid Syntax | Color | Hex |
|----------|-------|---------------|-------|-----|
| Project/Repo | Subroutine (double border) | `[["Label"]]` | Blue | #4262FF |
| Skill/Automation | Stadium (pill) | `(["Label"])` | Green | #00C875 |
| Integration | Hexagon | `{{"Label"}}` | Orange | #FF9900 |
| Blocker/Issue | Diamond | `{"Label"}` | Red | #E74C3C |
| Archived/Dormant | Rectangle | `["Label"]` | Gray | #A0A0A0 |

### Arrow Types (encode relationship strength)

| Arrow | Syntax | Meaning |
|-------|--------|---------|
| Solid | `-->` | Standard dependency or data flow |
| Thick | `==>` | Critical path (primary pipeline) |
| Dotted | `-.->` | Optional, async, or hosting relationship |

### Legend Subgraph

Every diagram MUST include a KEY subgraph showing the shape+color system:

```
subgraph legend ["KEY"]
    direction TB
    L1[["Project/Repo"]]
    L2(["Skill/Automation"])
    L3{{"Integration"}}
end
```

Style the legend nodes with their respective colors.

## Diagram Types

### 1. Project Map (LR)

Shows repos and tools as nodes grouped by domain. Left-to-right layout.

Groups: "Red Hat Work", "Personal", "Skills Layer", "Integrations"

### 2. Workflow Diagram (TD)

Shows the flow of data through agents, skills, and MCPs. Top-to-bottom layout.

Groups: "Trigger", "Context Gathering", "Drafting", "Output"

## How to Run

### Full Refresh

1. **Read config** -- load `.diagrams/project-map.json`
2. **Gather project data:**
   - Scan agent transcripts (last 20 sessions) for active projects
   - Read GitHub/GitLab READMEs for descriptions
   - Scan skill directories for skill inventory
   - Check Second Brain wiki for cross-links
   - Optionally query Jira for epic/ticket status
3. **Generate Mermaid** -- build diagram with:
   - Correct shape per category
   - Per-node style directives for color
   - Quoted labels on all nodes and edges
   - Subgraph groupings with direction
   - Legend subgraph
   - Arrow type matching relationship strength
4. **Write to file** -- save as `docs/diagrams/project-map.md`
5. **Render outputs** (any combination):
   - SVG: `mmdc -i project-map.md -o project-map.svg -t dark -b transparent`
   - PNG: `mmdc -i project-map.md -o project-map.png -t default -b white -s 2`
   - Figma: call `generate_diagram` MCP tool
   - Slack URL: generate mermaid.ink link
6. **Update config** -- save Figma fileKey and timestamp
7. **Confirm** -- show preview and all output links

### Incremental Update

1. Read config and existing Mermaid source
2. Apply the requested change (add/remove/modify nodes)
3. Re-render all active outputs
4. Update config

## Sharing Methods

### Slack (quick share)

**Option A: PNG upload**
```bash
mmdc -i docs/diagrams/project-map.md -o /tmp/project-map.png -t default -b white -s 2
```
Then upload the PNG to Slack.

**Option B: mermaid.ink URL (no file needed)**
```bash
# Base64-encode the Mermaid syntax and construct URL
MERMAID_CODE=$(sed -n '/```mermaid/,/```/p' docs/diagrams/project-map.md | sed '1d;$d')
ENCODED=$(echo "$MERMAID_CODE" | base64 | tr -d '\n' | tr '+/' '-_')
echo "https://mermaid.ink/img/${ENCODED}?type=png&bgColor=white"
```
Paste the URL in Slack -- it renders as an inline image.

**Option C: mermaid.live edit link**
Go to https://mermaid.live and paste the Mermaid code. Copy the URL from the
address bar -- it encodes the diagram and anyone with the link can view/edit.

### Figma FigJam

Call the Figma MCP `generate_diagram` tool:
- `name`: descriptive title with date
- `mermaidSyntax`: the full Mermaid code (no markdown fences)
- `userIntent`: what the diagram shows
- Optional `fileKey`: to add to an existing board

**Figma constraints:**
- Use LR direction by default
- ALL node labels in quotes: `[["Label"]]`
- ALL edge labels in quotes: `-->|"label"|`
- No emojis, no `\n`
- Color styling works in flowchart type
- Do NOT call `create_new_file` first -- `generate_diagram` makes its own

### Google Docs

Render to PNG then embed via gdoc-writer skill or manual upload.

### GitHub/GitLab README

The Mermaid block in the markdown file renders natively. Just commit and push.

## Data Sources

### Agent Transcripts

Read from `agent-transcripts/` in the workspace:
- Primary topic/project per session
- Skills invoked
- MCPs called
- Frequency of project mentions (more = more prominent node)

### GitHub/GitLab READMEs

For known project paths, read README.md:
- Project name and description
- Tech stack
- Status (active, archived, experimental)

### Skill Directories

Scan all skill locations to build inventory:
- `~/.cursor/skills/`
- `~/.cursor/skills-cursor/`
- `~/.claude/skills/`
- Project `.cursor/skills/`

### Second Brain

Read `~/second-brain/wiki/index.md` for cross-links and categories.

### Jira (optional)

If Atlassian MCP available:
- Active epics
- Assigned tickets
- Blockers (become red diamond nodes)

## File Locations

| File | Purpose |
|------|---------|
| `.diagrams/project-map.json` | Config: projects, edges, Figma fileKey |
| `docs/diagrams/project-map.md` | Project map Mermaid source |
| `docs/diagrams/project-map.svg` | SVG export |
| `docs/diagrams/project-map.png` | PNG for Slack/Docs |
| `docs/diagrams/workflow.md` | Workflow diagram source |
| `docs/diagrams/workflow.svg` | Workflow SVG export |

## Rendering Commands

```bash
# SVG (scales perfectly, best for docs)
mmdc -i docs/diagrams/project-map.md -o docs/diagrams/project-map.svg -t dark -b transparent

# PNG (Slack, Google Docs, email)
mmdc -i docs/diagrams/project-map.md -o docs/diagrams/project-map.png -t default -b white -s 2

# PDF (formal sharing)
mmdc -i docs/diagrams/project-map.md -o docs/diagrams/project-map.pdf -t default
```

## Tips for Readable Diagrams

- Keep node labels to 2-4 words
- Use `direction TB` inside subgraphs to stack nodes vertically within groups
- Limit to ~15 nodes per diagram; split into multiple if larger
- Thick arrows (`==>`) for the main pipeline, solid for dependencies, dotted for hosting
- Always include the KEY legend subgraph
- Group related nodes in subgraphs with descriptive quoted titles
- Use consistent node IDs (short, camelCase): `PC`, `RFE`, `EVAL`, `CLAW`