plantuml

name: plantuml description: Create PlantUML diagrams (especially swimlane business workflows). Use to look up official syntax, generate .puml, then format/validate and render to PNG.

PlantUML Skill (for Codex)

Goals

• Generate correct PlantUML.
• For business workflows, model roles (swimlanes) × steps without breaking the flow.
• Prefer modern styling: !theme + <style> first; use skinparam only when needed.

Workflow (must follow)

1. Confirm intent quickly: diagram type, purpose, roles/lanes, scope, exceptions/branches, parallelism.
2. Search official docs with python scripts/search_docs.py "<query>".
   • If docs cache is missing, fetch it first: python scripts/fetch_docs.py (cache is local-only; not committed).
3. Output a complete, renderable diagram (@startuml … @enduml) in a puml code block.
4. Sanity-check readability: avoid crossings, reduce width, consistent naming, add legend/notes if helpful.

Doc search (query examples)

• "Swimlanes |Swimlane| alias"
• "partition group activity diagram beta"
• "fork split activity diagram beta"
• "!theme %get_all_theme"
• "style <style> activityDiagram"

Business workflow conventions (swimlanes)

• Use Activity Diagram (beta) for swimlanes.
• Role = lane, step = action, decision = if/else, retry = repeat, parallel = fork/split.
• Split large flows into phases with partition / group.

Format / validate / render (PNG)

This skill includes a helper script that uses the official PlantUML CLI via Docker (no public server; no local Java required):

• Recommended: python scripts/plantuml_server.py build path/to/diagram.puml (format → validate → png)
• Individual commands:
  • python scripts/plantuml_server.py format path/to/diagram.puml
  • python scripts/plantuml_server.py validate path/to/diagram.puml --out path/to/diagram.validation.txt
  • python scripts/plantuml_server.py render path/to/diagram.puml --format png --out path/to/diagram.png

Docker image can be overridden via PLANTUML_DOCKER_IMAGE.

If your repo uses mise + uv, you can wrap these with tasks (e.g. mise run plantuml-build ...) for reproducible runs.

Output rules

• Always output fully renderable PlantUML.
• Add title and legend/note when it reduces reader confusion.