adr-graph-easy-architect_skill

Overview

This skill generates clean, reproducible ASCII architecture diagrams for Architecture Decision Records (ADRs) using graph-easy. It produces Unicode boxart output suitable for embedding in Markdown and enforces a workflow that keeps diagram source with the rendered output for future edits and audits.

How this skill works

You describe system nodes, groups, and edges using a small DSL and render it with graph-easy using the mandatory --as=boxart option. The skill validates flow direction, encourages monospace-safe markers, and outputs the box-drawing ASCII plus a collapsible details block containing the original graph-easy source for reproducibility.

When to use it

• Writing a new ADR that needs a visual representation of architecture or decisions
• Documenting migrations, integrations, or system redesigns in an ADR
• Updating or reviewing an existing ADR diagram for accuracy
• Creating lightweight diagrams that must remain editable in plain text
• Exporting architecture diagrams to include inline in Markdown with source

Best practices

• Always specify graph { flow: ... } explicitly (east or south) to avoid layout surprises
• Use --as=boxart when rendering; never use ascii mode
• Keep emojis out of node labels; use monospace-safe ASCII markers like [+] or [x]
• Include a collapsible <details> block immediately after the rendered diagram with the original graph-easy source
• Prefer simple node IDs with custom label fields for display text to keep IDs stable

Example use cases

• Generate a before/after migration diagram to include in an ADR with source in a <details> block
• Document a CI/CD pipeline left-to-right using flow: east and render as boxart
• Show a decision with multiple options and annotate edges with labels for pros/cons
• Group components into containers to show subsystem boundaries in an ADR
• Quickly iterate diagrams by editing the graph-easy source and re-rendering with --as=boxart