| name | adr-graph-easy-architect |
| description | ASCII architecture diagrams for ADRs via graph-easy. TRIGGERS - ADR diagram, architecture diagram, ASCII diagram. |
| allowed-tools | Bash, Read, Write, Edit |
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.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
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
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)
Embedding (MUST have - non-negotiable)
Node Styling (Visual hierarchy)
Edge Styling (Semantic meaning)
Character Safety (Alignment)
Structure (Organization)
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 |
Resources
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
