Story: PlantUML integration: recipe and codegen scaffold

Table of Contents

This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

Make PlantUML diagrams a first-class citizen of ORE Studio's documentation workflow. A how-to recipe explains how to write and embed a .puml diagram in any org-mode document; a new compass add diagram sub-command scaffolds a .puml file with the standard licence header, @startuml / @enduml delimiters, and the project skin/style preamble so every diagram is consistent from the first line.

2. Status

Field Value
State DONE
Parent sprint Sprint 18
Now Complete.
Waiting on Nothing.
Next None.
Last touched 2026-05-28

3. Acceptance

  • doc/recipes/plantuml/how_do_i_add_a_plantuml_diagram.org exists and explains: install/verify PlantUML, write the .puml source, run plantuml to export the PNG, and embed it in org-mode with an #+attr_html: / #+attr_latex: figure block.
  • compass add diagram <slug> (or equivalent sub-command) scaffolds <slug>.puml with the standard AGPL licence header, @startuml / @enduml, and the shared skin preamble; the generated file matches the convention of existing diagrams in the repo.
  • Existing .puml files are audited; any that lack the standard header are updated.

4. Tasks

Task State Start End Description
Task: Add PlantUML recipe and extend codegen with puml scaffold DONE 2026-05-28 2026-05-28 PlantUML integration: recipe and codegen scaffold

5. Decisions

6. Out of scope

  • Automating PNG regeneration in CI (diagrams are regenerated manually when the source changes).
  • Switching to SVG output — PNG is the current convention.

Emacs 29.3 (Org mode 9.6.15)