---
name: update-workflow-diagram
description: Convert the mermaid diagram in docs/workflow.md to a blueprint-styled SVG for the website. Use when the workflow diagram in agents.md is updated and needs to be reflected on the website.
---

# Update Workflow Diagram from Mermaid

## Purpose

Regenerate the `website/ai-workflow.svg` file from the canonical mermaid diagram in `docs/workflow.md`. The website uses a hand-crafted blueprint-styled SVG that preserves the exact layout generated by mermaid but applies a custom visual style (technical drawing aesthetic with cyan/white on dark blue).

## When to Use

- After changes to the mermaid diagram in `docs/workflow.md`
- When adding, removing, or renaming agents/artifacts
- When modifying the workflow connections

## Hard Rules

### Must

- Use mermaid-cli (`mmdc`) to render the mermaid diagram to SVG
- Parse the generated SVG to extract node positions and path definitions
- Preserve exact node positions and path routing from mermaid output
- Apply blueprint styling consistently per node type
- Keep the SVG self-contained (all styles inline or in `<style>` block)

### Must Not

- Manually calculate node positions (extract from rendered mermaid SVG)
- Manually recreate path curves (copy exact `d` attributes from mermaid paths)
- Change the visual styling without updating this skill documentation

## Blueprint Style Reference

### Colors

| Element | Color | Notes |
|---------|-------|-------|
| Background | `#0d1b2a` | Dark navy blue |
| Grid lines | `rgba(255,255,255,0.1)` | Subtle white grid |
| Agent borders | `#00ffff` (cyan) | Solid 2px |
| Agent text | `#ffffff` (white) | Monospace font |
| Meta-agent borders | `#34d399` (green) | Solid 2px |
| Meta-agent text | `#34d399` (green) | Monospace font |
| Artifact borders | `#ffffff` (white) | Dashed 2px (`2,2`) |
| Artifact fill | `rgba(0,255,255,0.1)` | Subtle cyan |
| Artifact text | `#00ffff` (cyan) | Monospace font |
| Human borders | `#ffffff` (white) | Dashed 2px (`4,2`) |
| Human text | `#00ffff` (cyan) | Monospace font |
| Paths (solid) | `#00ffff` (cyan) | 2px with glow |
| Paths (dashed/feedback) | `#ff6b6b` (coral red) | 2px, dasharray `6,3` |
| Arrow markers | Same as path color | |

### Node Classes (from mermaid)

| Mermaid Class | SVG Class | Description |
|---------------|-----------|-------------|
| `human` | `node-human` | Maintainer (dashed white border) |
| `agent` | `node-agent` | Regular agents (solid cyan border) |
| `metaagent` | `node-metaagent` | Workflow Engineer (solid green border) |
| `artifact` | `node-artifact` | Produced documents (dashed white, cyan fill) |

### Glow Effects

All nodes and paths have CSS filter glow:

```css
/* Nodes */
filter: drop-shadow(0 0 4px rgba(0,255,255,0.6));

/* Paths */
filter: drop-shadow(0 0 2px rgba(0,255,255,0.4));
```

## Actions

One command. It extracts the mermaid block from `docs/workflow.md`, renders it with
`mmdc` for layout, and restyles the result:

```bash
scripts/render-workflow-diagram.py
```

`--check` verifies the committed SVG was generated from the diagram as it stands now,
by comparing a `source-sha256` stamp written into the file. It does not re-render, so it
needs no browser and runs in milliseconds — this is the CI check.

That indirection is not laziness. Mermaid lays out text by measuring it in a browser, so
node coordinates depend on which fonts the machine has; a byte-for-byte comparison passes
locally and fails in CI for no reason a reader could act on. The stamp catches the
failure that matters — editing the diagram and forgetting to regenerate.

`--check-render` does the strict byte comparison against a fresh render. Use it on the
machine that generated the file, not in CI.

The stamp covers the diagram source, not this script: change the styling logic without
regenerating and `--check` still passes. If you edit the script, re-run it and commit the
SVG.

The script exists because this was a ten-step manual parse, and doing it by hand loses
things quietly. Two failures found the first time it ran, neither visible in the output
text:

- The Maintainer node vanished. It is a **stadium**, drawn as a free `<path>` inside an
  `outer-path` group — matching neither the `<rect>` nor the `<polygon>` pattern, so the
  node was skipped without an error.
- The gate hexagons rendered ~100px from their own labels, because a mermaid
  `<polygon>` carries its own inner `transform` in addition to the node group's.

**Always look at the rendered image before committing.** A grep for the node names
passes in both broken cases above.

```bash
npx --yes sharp-cli -i website/src/media-root/ai-workflow.svg -o /tmp/check.png resize 900
```

## Node styling

| Mermaid classDef | SVG class | Appearance |
|------------------|-----------|------------|
| `role` | `node-agent` | solid cyan border, white text |
| `meta` | `node-metaagent` | solid green border, green text |
| `external` | `node-external` | solid pink border — the Codex reviewer |
| `gate` | `node-gate` | amber hexagon, amber text |
| `artifact` | `node-artifact` | dashed white border, cyan fill |
| *(unclassed)* | `node-human` | dashed white border, cyan text |

Adding a new `classDef` to the diagram means adding it to `NODE_CLASS` and `STYLE` in
the script; an unmapped class falls back to the human style, which will look wrong.