| 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
- Load per-type reference + storage/renderer conventions.
- 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.
- Sanitize ADR stem: strip any path separators (
/, \, ..) from the stem. The output path MUST resolve under docs/adr/diagrams/ only.
- Detect renderer per renderer-conventions.md; produce SVG if possible. The POST path depends on source language (
/mermaid/svg or /structurizr/svg).
- Write the source file first (
.mmd or .dsl). Render to SVG from the source file using the detected renderer. If renderer succeeded, write .svg.
- 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.