update-workflow-diagram

name	update-workflow-diagram
description	Convert the mermaid diagram in docs/agents.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/agents.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/agents.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:

/* 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

1. Extract Mermaid Diagram from agents.md

The mermaid diagram is embedded in docs/agents.md within a fenced code block. Extract it to a temporary file:

# Create temp directory if needed
scripts/setup-tmp.sh

# Extract the mermaid diagram from agents.md
sed -n '/^```mermaid$/,/^```$/p' docs/agents.md | sed '1d;$d' > .tmp/workflow.mmd

This extracts everything between ```mermaid and the closing ```.

2. Render Mermaid to SVG using mermaid-cli

Use the mermaid-cli (mmdc) to render the diagram to SVG. Install if needed:

# Option A: Use npx (no global install needed)
npx -p @mermaid-js/mermaid-cli mmdc -i .tmp/workflow.mmd -o .tmp/workflow-raw.svg -t dark

# Option B: Global install
npm install -g @mermaid-js/mermaid-cli
mmdc -i .tmp/workflow.mmd -o .tmp/workflow-raw.svg -t dark

# Option C: Docker (no Node.js required)
docker run --rm -v "$(pwd)/.tmp:/data" minlag/mermaid-cli -i /data/workflow.mmd -o /data/workflow-raw.svg -t dark

The -t dark flag uses dark theme which matches our target styling better.

3. Parse the Generated SVG

The generated .tmp/workflow-raw.svg contains all the positioning data. Parse it to extract:

3a. Get ViewBox

grep -o 'viewBox="[^"]*"' .tmp/workflow-raw.svg

3b. Extract Node Data

Use a script or manual inspection to extract node information. Each node in the mermaid SVG has:

• A <g> element with class containing the node ID (e.g., flowchart-HUMAN-0)
• A transform attribute with the position
• A <rect> or <polygon> for the shape
• Text content in <span> or <foreignObject>

Example extraction with grep/sed:

# List all node groups with their transforms
grep -E '<g[^>]*class="[^"]*node[^"]*"' .tmp/workflow-raw.svg

3c. Extract Path Data

Paths are <path> elements with class flowchart-link. Extract the d attributes:

# Extract all path d attributes
grep -o 'd="M[^"]*"' .tmp/workflow-raw.svg | head -40

3d. Extract Edge Labels

Edge labels are in <g class="edgeLabel"> elements:

grep -A5 'edgeLabel' .tmp/workflow-raw.svg

4. Identify Node Types from Mermaid Source

Read the class definitions from the mermaid source in docs/agents.md:

class HUMAN human;
class IA_AGENT,RE,AR,TP_AGENT,QE,DEV,TW,CR,UAT_AGENT,RM,RETRO_AGENT agent;
class WE metaagent;
class IA,FS,US,ADR,TP,CODE,DOCS,CRR,REL,PR,WD,UAT,RETRO artifact;

Map each node ID to its SVG class:

Node ID	Mermaid Class	SVG Class
HUMAN	human	node-human
WE	metaagent	node-metaagent
RE, AR, QE, TP_AGENT, DEV, TW, CR, UAT_AGENT, RM, RETRO_AGENT, IA_AGENT	agent	node-agent
FS, IA, WD, ADR, TP, US, CODE, DOCS, CRR, UAT, REL, PR, RETRO	artifact	node-artifact

5. Identify Path Types from Mermaid Source

Read the connection definitions to classify paths:

Connection Syntax	Path Type	Example
==>	path-thick	HUMAN ==> RE
-->	path-solid	RE --> FS --> AR
-- "label" -->	path-solid	CRR -- "Approved" --> UAT_AGENT
-. or -.- or -. "label" .->	path-dashed	CRR -. "Rework" .-> DEV

The dashed paths are feedback loops: "Rework" and "Rendering Issues".

6. Build the Blueprint SVG

Create website/ai-workflow.svg using the template structure. The key transformation steps:

1. Copy viewBox from the mermaid-generated SVG
2. Add defs section with grid pattern and arrow markers
3. Add style section with blueprint CSS classes
4. Add background with dark blue fill and grid overlay
5. Copy all paths with their exact d attributes, applying the correct class:
   • First 3 paths (from HUMAN): path-thick
   • Paths with dashed style in source: path-dashed
   • All others: path-solid
6. Copy all nodes with their exact transforms, applying the correct class based on node type
7. Add edge labels at their extracted positions

7. Node Text Formatting

When copying node text, apply these transformations:

• Remove <b> tags
• For HUMAN node: Use 👤 MAINTAINER (all caps)
• For agents: Use the agent name as-is
• For artifacts: Keep the emoji prefix (📄, 📐, ✓, 📋, 💻, 📚, ✅, 🧪, 🚀, 🔀, 📝, 🔍, ⚙️)

8. Verify the Result

1. Start local server: python -m http.server 3000
2. Open http://127.0.0.1:3000/website/ai-workflow.html
3. Check:
   • All nodes visible with correct styling
   • All paths connect correctly
   • Grid overlay visible
   • Glow effects applied
   • Text readable
4. Run verification: scripts/website-verify.sh --all

SVG Template

<svg xmlns="http://www.w3.org/2000/svg" viewBox="{{VIEWBOX}}" role="graphics-document document" aria-roledescription="flowchart-v2">
  <defs>
    <!-- Blueprint grid pattern -->
    <pattern id="grid-blueprint" width="20" height="20" patternUnits="userSpaceOnUse">
      <path d="M 20 0 L 0 0 0 20" fill="none" stroke="rgba(255,255,255,0.1)" stroke-width="0.5"/>
    </pattern>
    
    <!-- Arrow markers -->
    <marker id="arrow-solid" markerWidth="4" markerHeight="4" refX="3.5" refY="2" orient="auto">
      <path d="M0,0 L0,4 L4,2 z" fill="#00ffff"/>
    </marker>
    <marker id="arrow-dashed" markerWidth="4" markerHeight="4" refX="3.5" refY="2" orient="auto">
      <path d="M0,0 L0,4 L4,2 z" fill="#ff6b6b"/>
    </marker>
    <marker id="arrow-thick" markerWidth="4" markerHeight="4" refX="3.5" refY="2" orient="auto">
      <path d="M0,0 L0,4 L4,2 z" fill="#00ffff"/>
    </marker>
  </defs>
  
  <style>
    /* Human/Maintainer node */
    .node-human rect { fill: none; stroke: #ffffff; stroke-width: 2; stroke-dasharray: 4,2; }
    .node-human text { fill: #00ffff; font-family: monospace; font-size: 13px; font-weight: 600; }
    .node-human { filter: drop-shadow(0 0 4px rgba(0,255,255,0.6)); }
    
    /* Agent nodes */
    .node-agent rect { fill: none; stroke: #00ffff; stroke-width: 2; }
    .node-agent text { fill: #ffffff; font-family: monospace; font-size: 13px; font-weight: 600; }
    .node-agent { filter: drop-shadow(0 0 4px rgba(0,255,255,0.6)); }
    
    /* Meta-agent nodes */
    .node-metaagent rect { fill: none; stroke: #34d399; stroke-width: 2; }
    .node-metaagent text { fill: #34d399; font-family: monospace; font-size: 13px; font-weight: 600; }
    .node-metaagent { filter: drop-shadow(0 0 4px rgba(52,211,153,0.6)); }
    
    /* Artifact nodes */
    .node-artifact rect { fill: rgba(0,255,255,0.1); stroke: #ffffff; stroke-width: 2; stroke-dasharray: 2,2; }
    .node-artifact text { fill: #00ffff; font-family: monospace; font-size: 13px; font-weight: 600; }
    .node-artifact { filter: drop-shadow(0 0 4px rgba(0,255,255,0.6)); }
    
    /* Paths */
    .path-solid { fill: none; stroke: #00ffff; stroke-width: 2; filter: drop-shadow(0 0 2px rgba(0,255,255,0.4)); }
    .path-thick { fill: none; stroke: #00ffff; stroke-width: 2; filter: drop-shadow(0 0 2px rgba(0,255,255,0.4)); }
    .path-dashed { fill: none; stroke: #ff6b6b; stroke-width: 2; stroke-dasharray: 6,3; filter: drop-shadow(0 0 2px rgba(255,107,107,0.4)); }
    
    /* Edge labels */
    .edge-label { fill: rgba(0,255,255,0.8); font-family: monospace; font-size: 10px; font-weight: 500; }
    .edge-label-bg { fill: #0d1b2a; }
  </style>
  
  <!-- Background with grid -->
  <rect x="{{X}}" y="{{Y}}" width="{{WIDTH}}" height="{{HEIGHT}}" fill="#0d1b2a"/>
  <rect x="{{X}}" y="{{Y}}" width="{{WIDTH}}" height="{{HEIGHT}}" fill="url(#grid-blueprint)"/>
  
  <!-- PATHS (render first, behind nodes) -->
  <!-- Thick paths from HUMAN -->
  <path class="path-thick" marker-end="url(#arrow-thick)" d="{{PATH_D}}"/>
  
  <!-- Regular solid paths -->
  <path class="path-solid" marker-end="url(#arrow-solid)" d="{{PATH_D}}"/>
  
  <!-- Dashed paths (feedback loops) -->
  <path class="path-dashed" marker-end="url(#arrow-dashed)" d="{{PATH_D}}"/>
  
  <!-- Edge labels -->
  <g transform="translate({{X}}, {{Y}})">
    <rect class="edge-label-bg" x="-{{W/2}}" y="-10" width="{{W}}" height="20" rx="3"/>
    <text class="edge-label" text-anchor="middle" dy="4">{{LABEL_TEXT}}</text>
  </g>
  
  <!-- NODES -->
  <!-- Human -->
  <g class="node-human" transform="translate({{X}}, {{Y}})">
    <rect x="-{{W/2}}" y="-{{H/2}}" width="{{W}}" height="{{H}}" rx="2" ry="2"/>
    <text text-anchor="middle" dy="5">👤 MAINTAINER</text>
  </g>
  
  <!-- Agent -->
  <g class="node-agent" transform="translate({{X}}, {{Y}})">
    <rect x="-{{W/2}}" y="-{{H/2}}" width="{{W}}" height="{{H}}" rx="2" ry="2"/>
    <text text-anchor="middle" dy="5">{{AGENT_NAME}}</text>
  </g>
  
  <!-- Meta-agent -->
  <g class="node-metaagent" transform="translate({{X}}, {{Y}})">
    <rect x="-{{W/2}}" y="-{{H/2}}" width="{{W}}" height="{{H}}" rx="2" ry="2"/>
    <text text-anchor="middle" dy="5">{{AGENT_NAME}}</text>
  </g>
  
  <!-- Artifact -->
  <g class="node-artifact" transform="translate({{X}}, {{Y}})">
    <rect x="-{{W/2}}" y="-{{H/2}}" width="{{W}}" height="{{H}}" rx="2" ry="2"/>
    <text text-anchor="middle" dy="5">{{ARTIFACT_NAME}}</text>
  </g>
</svg>

Updating ai-workflow.html

Ensure website/ai-workflow.html references the SVG:

<section class="workflow-diagram">
  <object data="ai-workflow.svg" type="image/svg+xml" 
          style="width: 100%; height: auto; max-height: 80vh;">
    <p>Workflow diagram - <a href="ai-workflow.svg">View SVG</a></p>
  </object>
</section>

Prerequisites

• mermaid-cli: Install via npm install -g @mermaid-js/mermaid-cli or use npx/Docker
• Local server: Python (python -m http.server) or similar for verification

Golden Example

The current website/ai-workflow.svg was generated from the mermaid diagram at commit on main branch. Key metrics:

• ViewBox: -8 -8 686.43359375 2087.03125
• Nodes: 26 total (1 human, 11 agents, 1 meta-agent, 13 artifacts)
• Paths: 32 total (3 thick from HUMAN, 27 solid, 2 dashed feedback loops)
• Edge Labels: 5 (Rework, Approved (UAT needed), Approved (no UAT), Rendering Issues, Approved)

Troubleshooting

Paths don't align with nodes

• Ensure you're using the exact d attribute from mermaid output, not recalculating
• Check that node transforms use the same coordinate system

Text is cut off

• Mermaid may use <foreignObject> for text; extract inner text content
• Adjust rect width if needed based on text measurement

Glow not visible

• Check that CSS filter properties are applied to the <g> element, not child elements
• Some browsers may need vendor prefixes for filters

Colors look wrong

• Verify the background color is #0d1b2a
• Check that the grid pattern uses white (rgba(255,255,255,0.1)), not cyan

References

• Blueprint design source: website/prototypes/diagram-designs-svg.html (Design 7)
• Mermaid source: docs/agents.md (search for ```mermaid)
• Node class mappings: docs/agents.md (search for classDef and class)