ADR Graph-Easy Architect

Create comprehensive ASCII architecture diagrams for Architecture Decision Records (ADRs) using graph-easy. Pure text output with automatic layout - no image rendering required.

When to Use This Skill Writing new ADR that involves architectural changes ADR describes migration, integration, or system changes User asks for visual representation of a decision Existing ADR diagram needs review or update Preflight Check

Run these checks in order. Each layer depends on the previous.

Layer 1: Package Manager /usr/bin/env bash << 'SETUP_EOF'

Detect OS and set package manager

case "$(uname -s)" in Darwin) PM="brew" ;; Linux) PM="apt" ;; *) echo "ERROR: Unsupported OS (require macOS or Linux)"; exit 1 ;; esac command -v $PM &>/dev/null || { echo "ERROR: $PM not installed"; exit 1; } echo "✓ Package manager: $PM" SETUP_EOF

Layer 2: Perl + cpanminus (mise-first approach)

Prefer mise for unified tool management

if command -v mise &>/dev/null; then # Install Perl via mise mise which perl &>/dev/null || mise install perl # Install cpanminus under mise perl mise exec perl -- cpanm --version &>/dev/null 2>&1 || { echo "Installing cpanminus under mise perl..." mise exec perl -- curl -L https://cpanmin.us | mise exec perl -- perl - App::cpanminus } echo "✓ cpanminus installed (via mise perl)" else # Fallback: Install cpanminus via system package manager command -v cpanm &>/dev/null || { echo "Installing cpanminus via $PM..." case "$PM" in brew) brew install cpanminus ;; apt) sudo apt install -y cpanminus ;; esac } echo "✓ cpanminus installed" fi

Layer 3: Graph::Easy Perl module

Check if Graph::Easy is installed (mise-first)

if command -v mise &>/dev/null; then mise exec perl -- perl -MGraph::Easy -e1 2>/dev/null || { echo "Installing Graph::Easy via mise perl cpanm..." mise exec perl -- cpanm Graph::Easy } echo "✓ Graph::Easy installed (via mise perl)" else perl -MGraph::Easy -e1 2>/dev/null || { echo "Installing Graph::Easy via cpanm..." cpanm Graph::Easy } echo "✓ Graph::Easy installed" fi

Layer 4: Verify graph-easy is in PATH

Verify graph-easy is accessible and functional

command -v graph-easy &>/dev/null || { echo "ERROR: graph-easy not found in PATH" exit 1 }

Test actual functionality (--version exits with code 2, unreliable)

echo "[Test] -> [OK]" | graph-easy &>/dev/null && echo "✓ graph-easy ready"

All-in-One Preflight Script /usr/bin/env bash << 'PREFLIGHT_EOF'

Copy-paste this entire block to ensure graph-easy is ready (macOS + Linux)

Prefers mise for unified cross-platform tool management

Check for mise first (recommended)

if command -v mise &>/dev/null; then echo "Using mise for Perl management..." mise which perl &>/dev/null || mise install perl mise exec perl -- cpanm --version &>/dev/null 2>&1 || \ mise exec perl -- curl -L https://cpanmin.us | mise exec perl -- perl - App::cpanminus mise exec perl -- perl -MGraph::Easy -e1 2>/dev/null || mise exec perl -- cpanm Graph::Easy else # Fallback: system package manager echo "💡 Tip: Install mise for unified tool management: curl https://mise.run | sh" case "$(uname -s)" in Darwin) PM="brew" ;; Linux) PM="apt" ;; *) echo "ERROR: Unsupported OS"; exit 1 ;; esac command -v $PM &>/dev/null || { echo "ERROR: $PM not installed"; exit 1; } command -v cpanm &>/dev/null || { [ "$PM" = "apt" ] && sudo apt install -y cpanminus || brew install cpanminus; } perl -MGraph::Easy -e1 2>/dev/null || cpanm Graph::Easy fi

Verify graph-easy is in PATH and functional

command -v graph-easy &>/dev/null || { echo "ERROR: graph-easy not in PATH after installation" exit 1 }

Test actual functionality (--version exits with code 2, unreliable)

echo "[Test] -> [OK]" | graph-easy &>/dev/null && echo "✓ graph-easy ready" PREFLIGHT_EOF

Part 1: DSL Syntax Basic Elements

Nodes (square brackets)

[Node Name]

Edges (arrows)

[A] -> [B]

Labeled edges

[A] -- label --> [B]

Bidirectional

[A] <-> [B]

Chain

[A] -> [B] -> [C]

Groups (Containers)

Named group with dashed border

( Group Name: [Node A] [Node B] )

Nested connections

( Before: [Old System] ) ( After: [New System] ) [Before] -> [After]

Node Labels

Custom label (different from ID)

[db] { label: "PostgreSQL Database"; }

ASCII markers for visual distinction INSIDE boxes

(emojis break box alignment - use ASCII markers instead)

[deleted] { label: "[x] Old Component"; } [added] { label: "[+] New Component"; } [warning] { label: "[!] Deprecated"; } [success] { label: "[OK] Passed"; }

Character rules for nodes:

Graphical emojis (🚀 💡 ✅ ❌) - NEVER (double-width breaks box alignment) Unicode symbols (✓ ✗ ⚠ → ←) - OK (single-width, safe) ASCII markers ([x] [+] [!] :) ) - ALWAYS safe (monospace)

Use graph { label: "..."; } for graphical emojis in title/legend.

Example: Emoji breaks alignment (DON'T DO THIS)

BAD - emoji inside node

[rocket] { label: "🚀 Launch"; }

Renders broken:

┌────────────┐ │ 🚀 Launch │ <-- box edge misaligned due to double-width emoji └────────────┘

Example: ASCII marker preserves alignment (DO THIS)

GOOD - ASCII marker inside node

[rocket] { label: "[>] Launch"; }

Renders correctly:

┌────────────┐ │ [>] Launch │ └────────────┘

Example: Emoji safe in graph title (OK)

OK - emoji in graph label (outside boxes)

graph { label: "🚀 Deployment Pipeline"; flow: east; } [Build] -> [Test] -> [Deploy]

Renders correctly (emoji in title, not in boxes):

    🚀 Deployment Pipeline

┌───────┐ ┌──────┐ ┌────────┐ │ Build │ --> │ Test │ --> │ Deploy │ └───────┘ └──────┘ └────────┘

Flow Direction (MANDATORY: Always specify)

MANDATORY: Always specify flow direction explicitly

graph { flow: south; } # Top-to-bottom (architecture, decisions) graph { flow: east; } # Left-to-right (pipelines, sequences)

Never rely on default flow - explicit is clearer.

Graph Title and Legend (Outside Boxes - Emojis Safe Here)

Emojis break alignment INSIDE boxes but are SAFE in graph titles/legends.

Emoji Selection Guide - Choose emoji that matches diagram purpose:

Diagram Type Emoji Example Title Migration/Change 🔄 "🔄 Database Migration" Deployment/Release 🚀 "🚀 Deployment Pipeline" Data Flow 📊 "📊 Data Ingestion Flow" Security/Auth 🔐 "🔐 Authentication Flow" Error/Failure ⚠️ "⚠️ Error Handling" Decision/Branch 🔀 "🔀 Routing Decision" Architecture 🏗️ "🏗️ System Architecture" Network/API 🌐 "🌐 API Integration" Storage/Database 💾 "💾 Storage Layer" Monitoring/Observability 📡 "📡 Monitoring Stack" Hook/Event 🪝 "🪝 Hook Flow" Before/After comparison ⏮️/⏭️ "⏮️ Before" / "⏭️ After"

Title with semantic emoji

graph { label: "🚀 Deployment Pipeline"; flow: east; }

Title with legend (multiline using \n)

graph { label: "🪝 Hook Flow\n──────────\n✓ Allow ✗ Deny ⚠ Warn"; flow: south; }

Rendered:

Hook Flow ────────── ✓ Allow ✗ Deny ⚠ Warn

╭───────╮ │ Start │ ╰───────╯

Rule: Emojis ONLY in graph { label: "..."; } - NEVER inside [ node ]

Node Styling (Best Practices)

Rounded corners for start/end nodes

[ Start ] { shape: rounded; } [ End ] { shape: rounded; }

Double border for emphasis

[ Critical Step ] { border: double; }

Bold border for important nodes

[ Key Decision ] { border: bold; }

Dotted border for optional/skippable

[ Optional ] { border: dotted; }

Multiline labels with \n

[ Hook Input\n(stdin JSON) ]

Rendered examples:

╭─────────╮ ┌─────────┐ │ Rounded │ │ Default │ ╰─────────╯ └─────────┘

╔═════════╗ ┏━━━━━━━━━┓ ║ Double ║ ┃ Bold ┃ ╚═════════╝ ┗━━━━━━━━━┛

Note: Dotted borders ({ border: dotted; }) use ⋮ characters that render inconsistently on GitHub. Use sparingly.

Edge Styles [ A ] -> [ B ] # Solid arrow (default) [ A ] ..> [ B ] # Dotted arrow [ A ] ==> [ B ] # Bold/double arrow [ A ] - -> [ B ] # Dashed arrow [ A ] -- label --> [ B ] # Labeled edge

Part 2: Common Diagram Patterns Migration (Before → After) graph { flow: south; } [Before] -- migrate --> [After]

Multi-Component System graph { flow: south; } [A] -> [B] -> [C] [B] -> [D]

Pipeline (Left-to-Right) graph { flow: east; } [Input] -> [Process] -> [Output]

Decision with Options graph { flow: south; } [Decision] -> [Option A] [Decision] -> [Option B]

Grouped Components ( Group: [Component 1] [Component 2] ) [External] -> [Component 1]

Bidirectional Flow [Client] <-> [Server] [Server] -> [Database]

Part 3: Rendering Command (MANDATORY: Always use boxart)

MANDATORY: Always use --as=boxart for clean output

graph-easy --as=boxart << 'EOF' graph { flow: south; } [A] -> [B] -> [C] EOF

Never use --as=ascii - it produces ugly +--+ boxes instead of clean ┌──┐ lines.

Output Modes Mode Command Usage boxart --as=boxart MANDATORY - clean Unicode lines ascii --as=ascii NEVER USE - ugly output, legacy only Validation Workflow

1. Write DSL to heredoc

2. Render with boxart

graph-easy --as=boxart << 'EOF' [Your] -> [Diagram] -> [Here] EOF

3. Review output

4. Iterate if needed

5. Copy final ASCII to ADR

Part 4: Embedding in ADR Markdown Format (MANDATORY: Always Include Source)

CRITICAL: Every rendered diagram MUST be followed by a collapsible

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Before  │ ──> │  After   │ ──> │ Database │
└──────────┘     └──────────┘     └──────────┘

graph { flow: east; }
[Before] -> [After] -> [Database]