ADR Graph-Easy Architect Skill

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

Ensure graph-easy is installed and functional before rendering diagrams.

Full setup instructions: Preflight Setup

Quick verify:

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

DSL Quick Reference

Full syntax with examples, node styling, edge styles, and emoji rules: DSL Syntax Reference

Essential Syntax

[Node]                          # Node
[A] -> [B]                      # Edge
[A] -- label --> [B]            # Labeled edge
[A] <-> [B]                     # Bidirectional
( Group: [Node A] [Node B] )    # Group/container
[id] { label: "Display"; }     # Custom label

Flow Direction (MANDATORY)

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

Graph Label (MANDATORY: EVERY diagram MUST have emoji + title)

WARNING: This is the most commonly forgotten requirement. Diagrams without labels are invalid.

Correct:

graph { label: "🔄 Database Migration"; flow: south; }
[Old DB] -> [New DB]

Anti-Pattern (INVALID):

graph { flow: south; }
[Old DB] -> [New DB]

Missing label: with emoji. The preflight validator will BLOCK any ADR containing diagrams without graph { label: "emoji ..."; }.

Emoji Selection (for graph labels ONLY - never inside nodes)

| Diagram Type | Emoji | Diagram Type | Emoji | | ------------------ | ----- | ---------------- | ----- | | Migration/Change | 🔄 | Architecture | 🏗️ | | Deployment/Release | 🚀 | Network/API | 🌐 | | Data Flow | 📊 | Storage/Database | 💾 | | Security/Auth | 🔐 | Monitoring | 📡 | | Error/Failure | ⚠️ | Hook/Event | 🪝 | | Decision/Branch | 🔀 | Before/After | ⏮️/⏭️ |

Node & Edge Styling Summary

| Style | Syntax | Use For | | --------------- | --------------------- | --------------------- | | Rounded corners | { shape: rounded; } | Start/end nodes | | Double border | { border: double; } | Critical/emphasis | | Bold border | { border: bold; } | Important nodes | | Dotted border | { border: dotted; } | Optional/skippable | | Solid arrow | -> | Main/happy path | | Dotted arrow | ..> | Conditional/alternate | | Bold arrow | ==> | Emphasized/critical | | Labeled edge | -- label --> | Annotated connections |

Character Safety

Graphical emojis INSIDE nodes: NEVER (breaks box alignment)
Unicode symbols inside nodes (checkmark, cross, warning): OK (single-width)
ASCII markers inside nodes ([x] [+] [!]): ALWAYS safe
Graphical emojis in graph { label: }: OK

Full symbol reference: Monospace-Safe Symbols

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]

More patterns by ADR type: Diagram Examples

Rendering

Command (MANDATORY: Always use boxart)

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

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

Validation Workflow

# 1. Write DSL to heredoc
# 2. Render with boxart
# 3. Review output
# 4. Iterate if needed
# 5. Copy final ASCII to ADR

Embedding in ADR

Every rendered diagram MUST include a collapsible <details> block with graph-easy source. Full format guide and GFM syntax rules: ADR Embedding Guide

Required format:

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

<details>
<summary>graph-easy source</summary>

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

</details>

The <details> block is MANDATORY - never embed a diagram without its source.

Mandatory Checklist (Before Rendering)

Graph-Level (MUST have)

[ ] graph { label: "🚀 Title"; } - semantic emoji + title (MOST FORGOTTEN - check first!)
[ ] graph { flow: south; } or graph { flow: east; } - explicit direction
[ ] Command uses --as=boxart - NEVER --as=ascii

Embedding (MUST have - non-negotiable)

[ ] <details> block with source - EVERY diagram MUST have collapsible source code block
[ ] Format: rendered diagram in ``` block, followed by <details><summary>graph-easy source</summary> with source
[ ] Never commit a diagram without its reproducible source

Node Styling (Visual hierarchy)

[ ] Start/end nodes: { shape: rounded; } - entry/exit points
[ ] Critical/important nodes: { border: double; } or { border: bold; }
[ ] Optional/skippable nodes: { border: dotted; }
[ ] Long labels use \n for multiline - max ~15 chars per line

Edge Styling (Semantic meaning)

[ ] Main/happy path: -> solid arrow
[ ] Conditional/alternate: ..> dotted arrow
[ ] Emphasized/critical: ==> bold arrow
[ ] Edge labels are SHORT (1-3 words): -- YES -->, -- error -->

Character Safety (Alignment)

[ ] NO graphical emojis inside nodes (break alignment)
[ ] Unicode symbols OK inside nodes (single-width)
[ ] ASCII markers ALWAYS safe ([x] [+] [!] [OK])
[ ] Graphical emojis ONLY in graph { label: "..."; } title

Structure (Organization)

[ ] Groups ( Name: ... ) used for logical clustering when 4+ related nodes
[ ] Node IDs short, labels descriptive: [db] { label: "PostgreSQL"; }
[ ] No more than 7-10 nodes per diagram (split if larger)

Success Criteria

Correctness

Parses without error - graph-easy accepts the DSL
Renders cleanly - no misaligned boxes or broken lines
Matches content - all key elements from description represented
Source preserved (MANDATORY) - EVERY diagram has <details> block with source

Aesthetics

Uses boxart - clean Unicode lines, not ASCII +--+
Visual hierarchy - start/end rounded, important bold/double, optional dotted
Consistent styling - same border style = same semantic meaning throughout
Readable labels - multiline with \n, no truncation
Clear flow - direction matches natural reading (top-down or left-right)

Comprehensiveness

Semantic emoji in title - emoji chosen to match diagram purpose
Legend if needed - multiline title with \n for complex diagrams
Edge semantics - solid=normal, dotted=conditional, bold=critical
Logical grouping - related nodes in ( Group: ... ) containers

Troubleshooting

| Issue | Cause | Solution | | ------------------- | ------------------------ | -------------------------------------------------------------------------------- | | command not found | graph-easy not installed | Run preflight check | | Misaligned boxes | Used --as=ascii | Always use --as=boxart | | Box border broken | Graphical emoji in node | Remove emojis from nodes, use ASCII markers | | Nodes overlap | Too complex | Split into multiple diagrams (max 7-10 nodes) | | Edge labels cut off | Label too long | Shorten to 1-3 words | | No title showing | Wrong syntax | Use graph { label: "Title"; flow: south; } | | Weird layout | No flow direction | Add graph { flow: south; } or flow: east | | Parse error | Special chars in node | Escape or simplify node names |

Agent Skills: ADR Graph-Easy Architect

Install this agent skill to your local

Skill Files