diagram-authoringlisted

# diagram-authoring — Mermaid over ASCII The single source of truth for **how this plugin draws diagrams**. The plugin writes markdown artifacts (`/board plan` docs, epic/issue bodies, handoffs, status updates, `KNOWLEDGE.md`, README, blog entries). Their destinations — GitHub markdown and Claude Code / claude.ai artifacts — render **Mermaid** natively, so a proper diagram-as-code block costs nothing extra and reads far better than ASCII. ## Core rule When you are about to put a diagram into any plugin-produced markdown artifact, emit a fenced **Mermaid** block. **Never hand-draw ASCII art for a graph** (boxes of `+--+`, `│`, `└──▶`). ASCII diagrams wrap badly, don't diff, and don't scale. ```` ```mermaid flowchart LR A[Issue picked] --> B[Work branch] B --> C[PR + review gate] C --> D[Merge → Done] ``` ```` ## Decision table — diagram type → Mermaid syntax | You are showing… | Use | Header keyword | |---|---|---| | A flow / pipeline / decision path | flowchart | `flowchart TD` / `LR` | | Messages between actors over time | sequence | `sequenceDiagram` | | States and transitions | state machine | `stateDiagram-v2` | | Entities and their relations | ER model | `erDiagram` | | A schedule / timeline | gantt | `gantt` | | A tree / hierarchy | flowchart (top-down) | `flowchart TD` | Pick the type that matches the thing being documented — a flow is not a sequence, a hierarchy is not an ER model. ## Escalation — when Mermaid is not enough Reach for **D2 (Terrastruct)*