diagram

name	diagram
description	Generate architecture diagrams for ADRs. Emits Mermaid source (.mmd) for flowchart, state, er, and sequence types and Structurizr DSL (.dsl) for c4. Source and .svg output are stored side-by-side in docs/adr/diagrams/. Invokable standalone or auto-triggered from brains:brains phase-1 step 8.
argument-hint	"<description>" [--type <flowchart|state|c4|er|sequence>] [--kroki-cloud]
allowed-tools	["Read","Write","Edit","Bash"]

Invocation

/brains:diagram "<description>" [--type <type>]

--type values: flowchart, state, c4, er, sequence. If omitted, infer from description: states/lifecycle/transitions → state | system context/containers/actors → c4 | entities/relationships → er | named participants + message exchanges → sequence | default → flowchart

Source-Language-per-Type

--type	Source language	File extension	Comment / marker prefix
flowchart	Mermaid	.mmd	%%
state	Mermaid	.mmd	%%
c4	Structurizr DSL	.dsl	#
er	Mermaid	.mmd	%%
sequence	Mermaid	.mmd	%%

Routing Table

Load the per-type reference lazily (only when generating that type):

--type	Load
flowchart	skills/diagram/references/flowchart.md
state	skills/diagram/references/state.md
c4	skills/diagram/references/structurizr.md
er	skills/diagram/references/er.md
sequence	skills/diagram/references/sequence.md

Always load on any diagram generation: skills/diagram/references/renderer-conventions.md and skills/diagram/references/storage-conventions.md

Generation Steps

1. Load per-type reference + storage/renderer conventions.
2. Generate source in the language prescribed by the Source-Language-per-Type table above (Mermaid for flowchart/state/er/sequence; Structurizr DSL for c4). The first line MUST be the auto-trigger marker — see Self-Correction section.
3. Sanitize ADR stem: strip any path separators (/, \, ..) from the stem. The output path MUST resolve under docs/adr/diagrams/ only.
4. Detect renderer per renderer-conventions.md; produce SVG if possible. The POST path depends on source language (/mermaid/svg or /structurizr/svg).
5. Write the source file first (.mmd or .dsl). Render to SVG from the source file using the detected renderer. If renderer succeeded, write .svg.
6. Write or update ADR ## Diagram section per storage-conventions.md format.

Flags

Flag	Scope	Behavior
--type <type>	Standalone	Set diagram type; skips heuristic inference. This is the primary flag for standalone /brains:diagram calls.
--max-diagrams N	Auto-trigger	Allow up to N diagrams (1-5, default 1) per distinct heuristic.
--no-diagram	Auto-trigger	Suppress all diagram generation.
--diagram <type>	Auto-trigger	Force a specific type, overriding heuristics and --max-diagrams. Passed by /brains:brains step 8; dispatched internally as --type <type> to this skill. NOT a user flag for standalone calls — use --type instead.
--kroki-cloud	Both	Opt-in to kroki.io cloud; requires explicit interactive consent. DISALLOWED in auto-trigger mode — source-only fallback is used instead.

--type vs --diagram: --type is for standalone /brains:diagram calls. --diagram is a /brains:brains pipeline override that is passed down as --type; do not use it in standalone calls.

--max-diagrams active v0.5 priority order when N > 1: state > ER > flowchart > C4 > sequence

Self-Correction and Regeneration

Retry loop: On renderer syntax error, append the error to generation context and retry once (exactly one retry). On second failure, write the type-specific placeholder below.

Placeholder (second failure):

Mermaid (flowchart, state, er, sequence):

%% auto-generated by brains:diagram — remove this line to protect manual edits
flowchart TD
  A["Diagram placeholder — manual revision required\nSee: docs/adr/diagrams/<stem>-<type>.mmd"]

Structurizr (c4): single-node workspace with note softwareSystem pointing to the .dsl file.

Omit SVG for placeholders. Add to ADR: <!-- diagram generation failed after one retry; edit docs/adr/diagrams/<stem>-<type>.<ext> manually -->.

Ordered overwrite (sequential, not atomic): Write the source file (.mmd or .dsl) first, then render SVG from it and write .svg. On .svg write failure due to parse/generation error: delete any pre-existing .svg (stale artifact). On transient I/O failure: preserve the pre-existing .svg (last-known-good).

Auto-trigger marker: First line of every generated source file MUST be exactly (no leading whitespace, no BOM), matching the comment prefix for the language:

• Mermaid (.mmd): %% auto-generated by brains:diagram — remove this line to protect manual edits
• Structurizr (.dsl): # auto-generated by brains:diagram — remove this line to protect manual edits

Option-5 regeneration: Enumerate docs/adr/diagrams/ for the current ADR stem:

• <adr-stem>-flowchart.mmd, <adr-stem>-state.mmd, <adr-stem>-er.mmd, <adr-stem>-sequence.mmd — Mermaid types.
• <adr-stem>-c4.dsl — Structurizr.

Anchored, no globs. If the first line of the source file exactly matches the marker for its language: regenerate. Otherwise: skip, log one-line note.