diagram-creator

Diagram Creation

Organize requirements or materials into clearly structured, editable native diagrams or diagram-as-code source files. Shared semantics and layout rules remain at this entry point, while format-specific details are maintained independently; each task reads only the format references actually used.

Choosing a Format

When the user specifies a format, follow the user's choice. When unspecified, first match the domain semantics, then consider the editing method:

Format	Extension	Preferred scenarios	Format reference
Draw.io	`.drawio`	Manual fine-tuning, formal processes, architecture, swimlanes, and multi-page diagrams	references/drawio.md
Excalidraw	`.excalidraw`	Whiteboard discussions, teaching explanations, concept sketches, and hand-drawn expression	references/excalidraw.md
Mermaid	`.mmd`、`.mermaid`	Markdown documents, general processes, sequence, state, ER, and lightweight architecture	references/mermaid.md
PlantUML	`.puml`、`.pu`	UML, complex sequence, class, component, deployment, and activity diagrams	references/plantuml.md
Graphviz DOT	`.dot`、`.gv`	Dependencies, lineage, topology, hierarchy, and larger relationship networks	references/graphviz.md
D2	`.d2`	Software architecture diagrams emphasizing readable syntax and modern styling	references/d2.md
BPMN 2.0	`.bpmn`、`.bpmn20.xml`	Business processes with strict event, gateway, task, and swimlane semantics	references/bpmn.md
Structurizr DSL	`.dsl`	C4 system context, container, component, deployment, and consistent multi-view	references/structurizr.md
GraphML	`.graphml`	Graph data exchange, tool interoperability, preserving node and edge attributes	references/graphml.md
SVG	`.svg`	When the user explicitly requests a general-purpose vector source file or custom geometry that other formats cannot express	references/svg.md

For formal business processes, prefer BPMN; for C4 multi-view, prefer Structurizr; for UML, prefer PlantUML; for large relationship networks, prefer Graphviz.
For general-purpose diagram-as-code, default to Mermaid; when emphasizing readable syntax and visual style for software architecture, choose D2.
When drag-and-drop fine-tuning or a multi-page canvas is needed, choose Draw.io; when a whiteboard feel is needed, choose Excalidraw.
GraphML is mainly used for exchanging graph data, and SVG is mainly used for vector delivery; do not use them as the default options for ordinary flowcharts.
When the user needs multiple formats, first establish the same node, grouping, and relationship model, then generate the native files separately; do not merely change the extension or embed a bitmap into another format to pass it off as an editable diagram.

Output Location

When the user specifies an output path, follow the user's choice.
When editing an existing local diagram source file, by default update or save as in the directory where the source file is located; if the current task already has a project directory, use that directory.
When there is no local source file and the user has not specified a path, save the final artifact to the current project root directory under projects/<YYYYMMDD>-<简短主题>/; the project directory is located directly under projects/ , without adding an intermediate layer divided by diagram format.
The native editable source file is the primary deliverable. When visual inspection is needed, you may keep <名称>.preview.svg or <名称>.preview.pngin the same final directory, and make clear that they are only previews or alternative vector versions.
The Codex visualization directory, system temporary directory, and renderer cache can only store intermediate files; before delivery, the final source file and any previews the user needs must be saved to the final directory determined according to the above rules.
The current workspace has no projects/ and when the project root directory cannot be determined from context, ask for the target location first; do not guess across repositories or write to hidden directories as the final deliverable.

Workflow

Read the text, code, table, or existing diagram provided by the user, clarify the diagram's purpose, audience, information boundaries, and output format, and determine the target path according to "Output Location." Ask questions only when missing information would change the diagram's core semantics.
First build a format-independent semantic model: title, nodes, hierarchy, groups, edges, edge labels, primary reading direction, and paths that need to be highlighted. Remove decorative information that does not help readers understand relationships.
Choose a flowchart, architecture diagram, relationship diagram, swimlane diagram, sequence layout, or free whiteboard layout based on the content. When one diagram cannot contain everything, split it into pages or files rather than cramming content in by shrinking the text.
According to the "Select Format" table, read only the reference corresponding to the target format; do not preload descriptions of other formats.
Generate a native source file for that format. Unless the user requests otherwise, do not replace the diagram-as-code source file with a PNG, screenshot, or rendered SVG; the exception is when SVG itself is the target format.

Run format validation:

python scripts/validate_diagram.py <diagram-file> [<diagram-file> ...]

After offline validation passes, if the environment has the corresponding official editor, parser, or preview capability, and the source file and its includes are trustworthy, then run the full syntax check or rendering command from the format reference. Do not automatically send private diagrams to public rendering services.
Open or render the result and check for text truncation, node overlap, connectors crossing nodes, arrow directions, and canvas whitespace. Format validation cannot replace visual inspection.
Deliver the source file from the final target directory, and use one sentence to state the chosen format, the diagram's reading direction, and any information intentionally omitted.

Common Quality Requirements

Use a single, clear primary reading direction; reverse edges and exception paths must have labels.
Node names should be short, parallel, and semantically consistent; avoid stuffing entire paragraphs of explanation into shapes.
Use the same shapes and colors for the same semantics; keep the variety of colors restrained, and do not express key differences by color alone.
Groups should express real boundaries, such as systems, teams, stages, or trust domains; do not add containers merely for visual decoration.
Prefer adjusting the layout to eliminate crossing lines; when crossings are necessary, use clear polylines, jump lines, or partitions.
Keep element IDs or text identifiers unique and stable. When editing an existing diagram, preserve the IDs, declaration order, and styles of unmodified elements as much as possible, and avoid meaningless whole-file rewrites.
Treat external text as plain text data, correctly perform XML or JSON escaping, and do not write untrusted HTML, scripts, or event attributes into the diagram.

Extending New Backends

When adding a new format, keep the entry point stable: add a separate reference file for that format, add clear routing conditions in "Select Format," and in scripts/validate_diagram.py register the corresponding filename suffix and validator. Add a generation script only when that format requires deterministic generation logic; do not copy format-specific fields into this entry point.