Step 7: Validate

Verify diagram file exists and is readable Check Mermaid syntax validity Confirm SVG renders correctly Validate cross-references resolve Mode 2: Migrate Existing Diagrams

Step 1: Scan Parent Document

Search for ```mermaid code blocks Extract each diagram with surrounding context Preserve diagram content and styling

Step 2: Create Diagram Files

For each extracted diagram, follow Steps 1-4 from Mode 1 Auto-generate description from diagram content or context Number multiple diagrams: _diagram_1, _diagram_2, etc.

Step 3: Replace in Parent Document

Remove original ```mermaid blocks Insert SVG + reference link in same location Maintain document flow and readability

Step 4: Validate Migration

Confirm all diagrams extracted Verify no broken references Check visual fidelity (SVG matches original Mermaid) Templates Diagram File Template

{PARENT-ID}-diag:

Document Control

| Item | Details |

|------|---------|

| Diagram ID | {PARENT-ID}-diag |

| Parent Document | {PARENT-ID}: {Parent Title} |

| Diagram Type | {flowchart|sequence|class|state|component|deployment} |

| Status | Active |

| Version | 1.0.0 |

| Created | {YYYY-MM-DD} |

| Last Updated | {YYYY-MM-DD} |

| Maintained By | {Role} |

Overview

{Brief description of what this diagram represents}

{Diagram Title}

```mermaid

Diagram Description

{Detailed explanation of diagram elements, flows, and purpose}

Key Elements

{List or table of important nodes, components, actors, states, or flows}

References Parent Document: {PARENT-ID}: {Parent Title} Related Diagrams: {Links to related diagram files if applicable} Related Documents: {Links to related requirements, ADRs, strategy docs}

Diagram Version: 1.0.0 Created: {YYYY-MM-DD} Maintained By: {Role}

Parent Document Reference Template

```markdown Visual Diagram: {PARENT-ID}-diag: {Diagram Title}

Supported Diagram Types Flowchart / Graph graph TB A[Start] --> B{Decision} B -->|Yes| C[Action 1] B -->|No| D[Action 2]

Use for: Process flows, decision trees, workflows

Sequence Diagram sequenceDiagram Actor->>System: Request System->>Database: Query Database-->>System: Result System-->>Actor: Response

Use for: Agent interactions, API calls, message flows

Class Diagram classDiagram class Agent { +state: State +execute() +validate() } Agent <|-- StrategyAgent

Use for: Object relationships, system components

State Diagram stateDiagram-v2 [] --> SCANNING SCANNING --> ACTIVE ACTIVE --> DEFENSE DEFENSE --> []

Use for: State machines, lifecycle flows

Component Diagram (using flowchart) graph LR subgraph "Level 1" SO[System Orchestrator] end subgraph "Level 2" IS[Item Selection] end SO --> IS

Use for: System architecture, component relationships

Deployment Diagram (using flowchart) graph TB subgraph "Cloud Run" A[Agent Container] end subgraph "Cloud SQL" B[(Database)] end A --> B

Use for: Infrastructure architecture, deployment topology

Tool Usage Check for Mermaid CLI which mmdc

If not installed:

npm install -g @mermaid-js/mermaid-cli

Alternative: Use Puppeteer

npm install -g puppeteer

Generate SVG from Mermaid mmdc -i input.md -o output.svg -b transparent

Parameters:

-i: Input file (Mermaid markdown) -o: Output file (SVG) -b: Background color (transparent recommended) Convert SVG to Base64 base64 -w 0 diagram.svg

macOS:

base64 -i diagram.svg

Quality Gates (Definition of Done) File Created: Diagram file exists in correct diagrams/ subfolder Naming Convention: File name follows {PARENT-ID}-diag_{description}.md pattern Document Control: Metadata section present with parent link back-reference Mermaid Syntax: Diagram syntax validates without errors SVG Generated: SVG file created successfully (if using file method) SVG Embedded: Base64 SVG embedded in parent document Reference Added: Link to diagram file added in parent document Cross-References: All links resolve correctly (bidirectional) Rendering: Diagram displays correctly in GitHub, VS Code, and documentation sites Accessibility: Collapsible