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

Arrow Types (encode relationship strength)

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

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)

# 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

Rendering Commands

# 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