---
name: diagram
version: 1.0.0
description: |
  Turn an English description (or mermaid source) into a diagram triplet:
  the source, an editable .excalidraw file you can open on excalidraw.com,
  and rendered SVG + PNG. Hand-drawn excalidraw aesthetic, fully offline.
  Use when asked to "make a diagram", "draw the architecture", "create a
  flowchart", "diagram this", or "visualize this flow". (gstack)
allowed-tools:
  - Bash
  - Read
  - Write
  - AskUserQuestion
triggers:
  - make a diagram
  - draw a diagram
  - create a flowchart
  - diagram this
  - visualize this flow
  - architecture diagram
---

{{PREAMBLE}}

# /diagram — English in, editable diagram out

Every run emits a **triplet**, never a dead pixel dump:

| Artifact | What it's for |
|---|---|
| `<slug>.mmd` | the mermaid source — the LLM-friendly interchange format |
| `<slug>.excalidraw` | editable scene — open it at excalidraw.com, move a box, keep working |
| `<slug>.svg` + `<slug>.png` | crisp vector for docs + raster for chat/issues/READMEs |

Rendering is fully offline via the diagram-render bundle in the browse daemon
(`lib/diagram-render/dist/diagram-render.html`). No CDN, no network.

## Step 1 — Author the diagram

Write mermaid for the user's request. Rules:

- **Flowcharts (`graph LR`/`graph TD`)** are the sweet spot: they convert to a
  fully editable excalidraw scene. Prefer `graph LR` for pipelines/flows,
  `graph TD` for hierarchies.
- Sequence, state, gantt, and other mermaid types render to SVG/PNG fine, but
  the official converter only supports flowcharts — for those types the
  `.excalidraw` artifact is skipped and you MUST tell the user:
  "sequence diagrams render but aren't excalidraw-editable yet (upstream
  converter limitation — flowcharts are)."
- Keep node labels short; put detail in edge labels. 5-15 nodes is the
  readable range. If the user's ask needs more, split into multiple diagrams
  and say why.

Decide the output directory: `./diagrams/` when the cwd is a git repo
(artifacts the user can commit), else `/tmp/gstack-diagrams/`. Derive
`<slug>` from the diagram's subject (kebab-case, ≤40 chars).

## Step 2 — Stage the render bundle (once per session)

```bash
BUNDLE=""
for c in "$HOME/.claude/skills/gstack/lib/diagram-render/dist/diagram-render.html" \
         "$(git rev-parse --show-toplevel 2>/dev/null)/lib/diagram-render/dist/diagram-render.html"; do
  [ -f "$c" ] && BUNDLE="$c" && break
done
[ -z "$BUNDLE" ] && echo "BUNDLE_MISSING — run: cd ~/.claude/skills/gstack && bun run build:diagram-render" && exit 1
STAGED="/tmp/gstack-diagram-render-skill.html"
cp "$BUNDLE" "$STAGED"
$B newtab >/dev/null 2>&1 || true
$B load-html "$STAGED"
$B wait '#done'
echo "RENDER_TAB_READY"
```

If `BUNDLE_MISSING`: stop and show the user the build command. Do not improvise
a CDN fallback — offline is the contract.

## Step 3 — Render the triplet

Write the mermaid source to `<outdir>/<slug>.mmd` first (Write tool). Then,
with `MMD` holding the mermaid text (escape for a JS string literal — the
safest path is reading it back inside the page is NOT possible; pass it via a
single-quoted JS template through `$B js`):

```bash
# SVG (always)
$B js "window.__renderMermaid('diagram-1', \`$(cat <outdir>/<slug>.mmd)\`).then(s => { window.__svg = s; return 'SVG OK ' + s.length })"
$B js "window.__svg" --out <outdir>/<slug>.svg

# PNG at 300dpi of a 6.5in placement (1950px)
$B js "window.__rasterize(window.__svg, 1950)" --out <outdir>/<slug>.png

# Editable scene (flowcharts only)
$B js "window.__mermaidToExcalidraw(\`$(cat <outdir>/<slug>.mmd)\`).then(j => { window.__scene = j; return 'SCENE OK ' + JSON.parse(j).elements.length + ' elements' })"
$B js "window.__scene" --out <outdir>/<slug>.excalidraw
```

If the mermaid render returns an error, show the parse error to the user, fix
the mermaid, and retry — do not hand the user a broken source file. If
`__mermaidToExcalidraw` fails on a non-flowchart type, skip the `.excalidraw`
artifact and deliver the rest with the limitation note from Step 1.

## Step 4 — Show and deliver

1. Read the PNG with the Read tool so the user sees the diagram inline.
2. List the triplet paths.
3. One-line editability note: "The `.excalidraw` file opens at excalidraw.com
   (File → Open) — edit it there and I can re-render from the edited scene."
4. If the user wants changes, edit the `.mmd` source and re-run Step 3 — the
   source is the single source of truth.

Re-rendering an EDITED `.excalidraw` (user round-trip): load the scene file
and export without touching the mermaid:

```bash
$B js "window.__excalidrawToSvg(\`$(cat <outdir>/<slug>.excalidraw)\`).then(s => { window.__svg = s; return 'OK' })"
$B js "window.__svg" --out <outdir>/<slug>.svg
$B js "window.__rasterize(window.__svg, 1950)" --out <outdir>/<slug>.png
```

## Rules

- **Never ship the triplet without rendering it.** A `.mmd` file alone is not
  a diagram. If rendering is impossible (bundle missing, browse down), say so
  and stop.
- **Cleanup:** close the render tab when the conversation's diagram work is
  done (`$B closetab`), not between diagrams.
- For diagrams destined for a PDF: remind the user that `make-pdf` renders
  ` ```mermaid ` fences natively — embedding the `.mmd` in their markdown is
  better than embedding the PNG.

## Completion status

- DONE — triplet (or SVG/PNG pair + limitation note) delivered and shown.
- BLOCKED — bundle or browse unavailable; build/setup command surfaced.