// 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.
This skill should be used when the user asks to "run the brains pipeline", "start the brains workflow", "plan and implement from scratch", "do an ADR", "start with brainstorming", or invokes "/brains:brains". Phase 1 of the BRAINS pipeline: interactive research, question generation, questionnaire, architecture synthesis, and ADR production. Supports --single, --parallel (default), and --debate modes, and an optional --autopilot flag that auto-chains into hands-off map + implement. Chains into /brains:map at the user gate.
This skill should be used when the user asks to "document mode", "edit only docs", "just update the docs", "fast-path a doc change", or invokes "/brains:document". Canonical entry point for BRAINS document mode: an abbreviated spine for document-only changes that skips planning, teammate orchestration, nurture, and secure. Runs an eligibility gate, lightweight research, the full 2-4 question questionnaire, a slim ADR, inline document edits, direct star-chamber council review (replacing nurture+secure), and an inline commit. Supports --single, --parallel (default), and --debate modes for the review phase, plus --autopilot and --lean.
This skill should be activated when a task involves significant complexity — multiple components, cross-cutting concerns, unfamiliar codebases, architectural decisions, or multi-step implementations. It suggests the BRAINS workflow to the user without auto-invoking it.
This skill should be used when the user asks to "set up brains", "configure brains", "install brains dependencies", "set up multi-LLM", "configure star-chamber for brains", "change brains defaults", "set up kroki", "enable diagram rendering", or invokes "/brains:setup". Guides the user through installing dependencies, configuring LLM providers, setting default modes for each BRAINS skill, and optionally starting a local Kroki container for diagram rendering.
This skill should be used when the user asks to "nurture", "review and fix", "improve code quality", "add tests", "fix remaining bugs", "polish the implementation", "check for completeness", or invokes "/brains:nurture". Reviews implementation for completeness, then fixes issues including bugs, missing features, and lack of tests. Supports --single (default), --parallel, and --debate modes for the review phase. When invoked by a phase-3 teammate with --scope phase-N, scopes the review to changes in that plan-phase, commits code and updates .gitignore, reflects any half-complete state in docs, and files follow-up beads tasks for the next phase or cleanup.
This skill should be used when the user asks to "implement the plan", "execute the plan", "start implementation", "build the tasks", "run the teammates", or invokes "/brains:implement". Phase 3 of the BRAINS pipeline: spawns a teammate Claude Code instance per plan-phase via agent-teams (preferred) or tmux (fallback), waits on beads state, handles task failures with two-strike-plus-human-in-loop flow. Supports --single, --parallel (default), and --debate modes for nurture/secure review within each plan-phase, plus an optional --autopilot flag that runs hands-off across phases until a needs-human ticket or direct user intervention stops it. Also supports --resume to pick up after a pause.
| 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"] |
/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
--type | Source language | File extension | Comment / marker prefix |
|---|---|---|---|
flowchart | Mermaid | .mmd | %% |
state | Mermaid | .mmd | %% |
c4 | Structurizr DSL | .dsl | # |
er | Mermaid | .mmd | %% |
sequence | Mermaid | .mmd | %% |
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
flowchart/state/er/sequence; Structurizr DSL for c4). The first line MUST be the auto-trigger marker — see Self-Correction section./, \, ..) from the stem. The output path MUST resolve under docs/adr/diagrams/ only./mermaid/svg or /structurizr/svg)..mmd or .dsl). Render to SVG from the source file using the detected renderer. If renderer succeeded, write .svg.## Diagram section per storage-conventions.md format.| 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. |
--typevs--diagram:--typeis for standalone/brains:diagramcalls.--diagramis a/brains:brainspipeline 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
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:
.mmd): %% auto-generated by brains:diagram — remove this line to protect manual edits.dsl): # auto-generated by brains:diagram — remove this line to protect manual editsOption-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.