charts-flow
Purpose
Generate and maintain Mermaid architecture diagrams for SDD documents. Diagrams
live in separate diagrams/ files next to their parent document — keeping the
parent lean to render — and stay traceable back to that parent through a stable
diagram ID and a back-reference link.
This is the single diagram skill for the plugin: all Mermaid generation,
validation, and SVG rendering lives here.
When to Use
Use charts-flow when:
- Adding an architecture diagram (flowchart, sequence, class, state, component,
or deployment) to a BRD, PRD, ADR, SPEC, or IPLAN.
- Migrating an existing inline
mermaid block into a separate diagram file.
- A parent document renders slowly because of complex inline diagrams, or a
diagram needs to be reused across documents.
Do not use it for simple tables/lists (use markdown), tiny diagrams that
render fine inline, or non-architecture charts (Gantt, pie) that fall outside
the SDD diagram contract.
Behavior
Create a new diagram
- Derive the parent document ID from its filename (e.g.
PRD-01) and locate
its folder.
- Create
diagrams/ beside the parent if absent, and write
{PARENT-ID}-diag_{description}.md containing a Document Control block
(parent link, diagram type, dates), an overview, the mermaid block, and a
References section linking back to the parent.
- Render an SVG (
mmdc CLI if available, otherwise Mermaid Live), validate the
syntax, and embed the SVG preview in the parent inside a collapsible
<details> block with a link to the diagram file.
Migrate inline diagrams
- Scan the parent for
mermaid blocks, move each into its own diagram file
(numbering multiples), then replace the original block with the SVG preview
plus a reference link, preserving document flow.
Supported types: flowchart/graph, sequence, class, state, component, and
deployment. Each diagram file follows the same Document Control + References
structure so cross-references resolve in both directions.
Diagram contract (per layer): diagrams attach to the layers that own visual
models — BRD (C4 L1 + DFD L1), PRD (C4 L2 + DFD L2 + key sequence), ADR
(decision sequences), SPEC (C4 L3 + DFD L3). Use the @diagram: tags the layer
template specifies and follow ${CLAUDE_PLUGIN_ROOT}/framework/governance/DIAGRAM_STANDARDS.md.
Quality gates: diagram file in the correct diagrams/ folder; name matches
{PARENT-ID}-diag_{description}.md; Document Control with parent back-link;
valid Mermaid syntax; SVG embedded; all cross-references resolve; SVG < 1 MB.
Related Resources
- Diagram standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/DIAGRAM_STANDARDS.md
- ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
- Layer templates that own diagrams:
${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml,
${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/PRD-TEMPLATE.yaml,
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml,
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
- Roadmap visuals:
../adr-roadmap/SKILL.md
- Mermaid: https://mermaid.js.org/ · https://mermaid.live
1---2name: charts-flow3description: Create and manage Mermaid architecture diagrams as separate, traceable files linked to their parent SDD documents. Use when adding or migrating diagrams for BRD, PRD, ADR, SPEC, or IPLAN documents.4---5
6# charts-flow
7
8## Purpose
9
10Generate and maintain Mermaid architecture diagrams for SDD documents. Diagrams
11live in separate `diagrams/` files next to their parent document — keeping the
12parent lean to render — and stay traceable back to that parent through a stable
13diagram ID and a back-reference link.
14
15This is the single diagram skill for the plugin: all Mermaid generation,
16validation, and SVG rendering lives here.
17
18## When to Use
19
20Use `charts-flow` when:
21
22- Adding an architecture diagram (flowchart, sequence, class, state, component,
23 or deployment) to a BRD, PRD, ADR, SPEC, or IPLAN.
24- Migrating an existing inline `mermaid` block into a separate diagram file.
25- A parent document renders slowly because of complex inline diagrams, or a
26 diagram needs to be reused across documents.
27
28Do **not** use it for simple tables/lists (use markdown), tiny diagrams that
29render fine inline, or non-architecture charts (Gantt, pie) that fall outside
30the SDD diagram contract.
31
32## Behavior
33
34**Create a new diagram**
35
361. Derive the parent document ID from its filename (e.g. `PRD-01`) and locate
37 its folder.
382. Create `diagrams/` beside the parent if absent, and write
39 `{PARENT-ID}-diag_{description}.md` containing a Document Control block
40 (parent link, diagram type, dates), an overview, the `mermaid` block, and a
41 References section linking back to the parent.
423. Render an SVG (`mmdc` CLI if available, otherwise Mermaid Live), validate the
43 syntax, and embed the SVG preview in the parent inside a collapsible
44 `<details>` block with a link to the diagram file.
45
46**Migrate inline diagrams**
47
48- Scan the parent for `mermaid` blocks, move each into its own diagram file
49 (numbering multiples), then replace the original block with the SVG preview
50 plus a reference link, preserving document flow.
51
52**Supported types**: flowchart/graph, sequence, class, state, component, and
53deployment. Each diagram file follows the same Document Control + References
54structure so cross-references resolve in both directions.
55
56**Diagram contract (per layer)**: diagrams attach to the layers that own visual
57models — BRD (C4 L1 + DFD L1), PRD (C4 L2 + DFD L2 + key sequence), ADR
58(decision sequences), SPEC (C4 L3 + DFD L3). Use the `@diagram:` tags the layer
59template specifies and follow `${CLAUDE_PLUGIN_ROOT}/framework/governance/DIAGRAM_STANDARDS.md`.
60
61**Quality gates**: diagram file in the correct `diagrams/` folder; name matches
62`{PARENT-ID}-diag_{description}.md`; Document Control with parent back-link;
63valid Mermaid syntax; SVG embedded; all cross-references resolve; SVG < 1 MB.
64
65## Related Resources
66
67- Diagram standards: `${CLAUDE_PLUGIN_ROOT}/framework/governance/DIAGRAM_STANDARDS.md`
68- ID & tag standards: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
69- Layer templates that own diagrams:
70 `${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml`,
71 `${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/PRD-TEMPLATE.yaml`,
72 `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml`,
73 `${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml`
74- Roadmap visuals: `../adr-roadmap/SKILL.md`
75- Mermaid: <https://mermaid.js.org/> · <https://mermaid.live>
vladm3105