diagram

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.