PlantUML import
PlantUML import turns bounded PlantUML source into a new diagram artifact in the repository's design system. The workflow extracts the source meaning first, redraws it for a chosen use, and checks that the command, reference, extractor, example, and safety rules remain in sync.
Import boundary
PlantUML import accepts .puml, .plantuml, and .pu files, plus Markdown files with fenced plantuml or puml blocks. It is a redraw rather than a render, so the result keeps diagram meaning but does not inherit PlantUML positions or visual skin.
Source formats
The import route supports two PlantUML diagram kinds: sequence diagrams and UML class diagrams. Sequence input provides lifelines, messages, control fragments, notes, and activation spans. Class input provides classifiers, members, stereotypes, relationships, and cardinality.
References: commands/import-plantuml.md• L12-16 skills/…/import-plantuml.md• L3-9 skills/…/import-plantuml.md• L25
Trust boundary
The extractor treats source text and its labels as untrusted diagram data. It does not render PlantUML or execute PlantUML, Graphviz, includes, macros, URLs, or label content; external includes and similar executable input fail closed instead of being fetched or expanded.
References: skills/…/plantuml_extract.py• L2-18 skills/…/import-plantuml.md• L21-25 skills/…/import-plantuml.md• L101-107
Import command
The /diagram-design:import-plantuml command is the user-facing entry point. It locates the installed diagram-design skill, extracts the source before drawing, and stops when extraction reports an error.
Command choices
The command uses these defaults and choices:
| Choice | Default | Purpose |
|---|---|---|
| Format | html | Select the self-contained artifact form. |
| Size | doc-inline | Fit the artifact to its destination. |
| Detail | balanced | Control how much source content the redraw carries. |
| Audience | mixed | Set wording for the intended readers. |
| Variant | light | Select the editorial visual template. |
| Diagram | First block | Select one source block, or use all for separate outputs. |
| Type | Inferred | Choose a visual type from the extracted kind, unless forced. |
| Output | Beside the source | Set a different output base path when needed. |
The format may be html, svg, png, or html+png. The size and detail choices must fit the source within the available diagram budget.
References: commands/import-plantuml.md• L1-3 commands/import-plantuml.md• L18-37 skills/…/import-plantuml.md• L36-51
Command sequence
When an engineer runs the command, the workflow follows this order:
- Identify the source file and the requested output choices.
- Run skills/…/plantuml_extract.py before drawing.
- Select a block when the source has more than one diagram.
- Choose the visual type and apply the requested detail and audience.
- Redraw the content in the repository's design system.
- Run the visual checks and report the artifact paths and fidelity ledger.
The command asks for a source when no file is provided. It reports extractor errors verbatim and does not continue with a partial diagram.
References: commands/import-plantuml.md• L39-51 prompts/import-plantuml.md• L6-14 skills/…/import-plantuml.md• L53-74
Extraction model
The extraction helper creates a normalized intermediate representation, or IR, that separates source meaning from the final layout. Its digest gives the redraw stage a bounded view of nodes, edges, fragments, analysis hints, and discarded source styling.
Diagram kinds
The helper identifies sequence and class content before the redraw stage chooses a target visual type. It preserves order and control structure for sequences. It preserves member data, relationship kinds, navigability, and cardinality for classes.
The helper also records hubs, entry points, terminals, unconnected nodes, and budget flags. These signals help the redraw focus the story without inventing new source content.
References: skills/…/plantuml_extract.py• L11-18 skills/…/import-plantuml.md• L25-27 skills/…/import-plantuml.md• L53-59
Block selection
One PlantUML file can contain several @startuml blocks. Markdown can contain several fenced blocks. The helper exposes them as separate diagrams with an index, kind, and node and edge counts.
The default selects the first block. A numeric --diagram selects one block. --diagram all processes every block as a separate output. An unselected bad block is reported in the summary without blocking other selectable blocks, while a selected bad block stops with its exact error.
References: skills/…/import-plantuml.md• L29-34 skills/…/import-plantuml.md• L92-99 skills/…/plantuml_extract.py• L2054-2066
Digest output
The default digest is a compact review surface. It shows the selected diagram kind, source layout status, node and edge counts, likely types, budget status, discarded source skin, fragments, activations, notes, and bounded node and edge tables. --json adds the full IR for cases that need complete member, fragment, activation, or note data.
PlantUML has no source coordinates, so the redraw starts from a blank destination view rather than copying positions. The digest's discarded ledger makes styling and refused includes visible for the later fidelity report.
References: skills/…/plantuml_extract.py• L1868-1905 skills/…/plantuml_extract.py• L1965-2021 skills/…/plantuml_extract.py• L2025-2051
Redraw workflow
The redraw stage converts the extracted meaning into an editorial artifact for a destination, not into a PlantUML rendering. It keeps the source story within the selected format, size, detail level, and audience.
Semantic preservation
The redraw keeps the relationships that explain the source: sequence order, activation spans, combined fragments, class members, relationship kind, cardinality, and navigability. It may merge, collapse, or drop content when the requested detail level requires it, but each such change belongs in the fidelity ledger.
Source colors, fonts, sprites, themes, and skin parameters do not constrain the new design. The redraw applies the repository's style rules and does not add components only to fill space.
References: skills/…/import-plantuml.md• L53-67 skills/…/import-plantuml.md• L69-74 commands/import-plantuml.md• L45-49
Worked artifact
The worked artifact at skills/…/example-import-plantuml.html shows a token-refresh sequence redrawn at html, doc-inline, balanced, and mixed settings. It demonstrates how lifelines, message order, an alternate branch, activation bars, and a plain-text note become a self-contained diagram without carrying over PlantUML skin.
References: skills/…/import-plantuml.md• L78-90 skills/…/example-import-plantuml.html• L20-25
Verification path
Verification checks the whole import contract instead of checking only one rendered image. It combines extractor behavior, adversarial input handling, command and prompt wiring, reference consistency, the worked artifact, and mobile containment.
Import gates
The primary gate is scripts/verify-plantuml-import.py. It runs the real extractor as a subprocess and checks sequence and class fixtures, multi-block behavior, trust-boundary failures, resource limits, named errors, documentation links, output presets, and the worked artifact.
The regression driver scripts/test-verify-plantuml-import.py copies the repository to a temporary tree and confirms that the verifier rejects stale command names, broken reference links, wrong supported-kind text, off-preset examples, missing mobile scrollers, and missing fixtures.
References: scripts/verify-plantuml-import.py• L1-7 scripts/verify-plantuml-import.py• L110-125 scripts/verify-plantuml-import.py• L1317-1415 scripts/test-verify-plantuml-import.py• L22-143
Verification command
Run the PlantUML import checks together:
python3 scripts/verify-plantuml-import.py && python3 scripts/test-verify-plantuml-import.py
The repository treats this pair as the PlantUML import path check. It covers sequence and class input, adversarial source, caps, and documentation synchronization.
References: CONTRIBUTING.md• L53-57 scripts/test-verify-plantuml-import.py• L33-46
Workflow relationships
PlantUML import is one source-specific route in the wider diagram import and export flow. Use the diagram import and export workflows page for the shared model, then compare source-specific behavior with Mermaid import, draw.io import, Excalidraw import, and diagram export.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the command flags, prompt defaults, reference behavior, and output-spec presets aligned.
- Keep the extractor's supported-kind message aligned with the reference and verifier expectations.
- Keep block selection behavior aligned across the extractor, command, digest, and multi-block guidance.
- Keep the discarded-content and fidelity-ledger rules aligned with the redraw guidance and worked artifact.
- Keep the verifier's fixture set and documentation wiring checks aligned with the current import contract.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| PlantUML, Graphviz, or an include is executed | Untrusted source crosses the import trust boundary | Use the bounded extractor and stop on include not inlined. |
| An unsupported kind such as activity or state is supplied | The source is redrawn as the wrong diagram type | Report the supported-kinds error and do not approximate it. |
| A selected block is malformed or exceeds a cap | The import could silently lose source meaning | Report the extractor error verbatim and stop. |
| Multiple blocks are merged without an explicit request | Separate diagrams can lose their own type and scope | Select a block or use --diagram all; do not merge by default. |
| Source styling is carried into the output | PlantUML skin becomes a false layout or brand constraint | Redraw with the repository style and record discarded styling. |
Key files
| File | Why to read it |
|---|---|
| commands/import-plantuml.md | Defines the user-facing command, defaults, flags, and required behavior. |
| prompts/import-plantuml.md | Defines the prompt route and skill discovery for Pi. |
| skills/…/import-plantuml.md | Provides the source-of-truth workflow for extraction, redraw, multi-block input, trust, and fidelity. |
| skills/…/plantuml_extract.py | Produces the normalized PlantUML IR and digest used by the redraw stage. |
| scripts/verify-plantuml-import.py | Runs structural, adversarial, wiring, and artifact checks for the import path. |
| scripts/test-verify-plantuml-import.py | Verifies that the PlantUML verifier detects common contract regressions. |
| skills/…/example-import-plantuml.html | Shows the expected PlantUML redraw output and destination containment. |
scripts/fixtures/sample-sequence.puml | Shows the sequence input used to verify order, branches, activations, and notes. |
scripts/fixtures/sample-class.puml | Shows the class input used to verify members, inheritance, composition, and cardinality. |