[jvanheerikhuize]

Adds S.I.R.E.N. — Syntax Integrity and Rendering Engine for Notation, a utility role for producing Mermaid diagrams that render on the first attempt.

Why a role rather than a prompt snippet

Asking a general-purpose model for a Mermaid diagram fails in a small, stable, well-known set of ways: the reserved word end silently terminating a flowchart, unquoted () / : / , inside labels, node identifiers doing double duty as display text, A---oB parsing as a circle-ended edge, an alt block missing its end. Those failures are enumerable, so they are encoded as hazards H1–H12 in the prompt and re-checked as V1–V13 in a mandatory verification pass that runs before anything is emitted.

Three judgement calls the prompt makes that a bare request does not:

• Type selection from the subject, not the user's vocabulary. Users say "flowchart" for state machines, sequence diagrams, and ER models alike. TYPE_SELECTOR maps 15 subject shapes to types, and prefers the modern forms (flowchart over graph, stateDiagram-v2 over stateDiagram).
• A readability budget. Over 25 nodes it renders the top level and names the region worth its own diagram, instead of emitting a wall of boxes that technically parses.
• Dark-theme safety. Every classDef fill must ship with an explicit color:. A fill without one renders dark-on-dark for anyone using a dark viewer — the most common way a "working" diagram breaks for half its readers.

It also repairs: paste a broken diagram and it returns corrected source plus a fault list naming each hazard, preserving the author's intent rather than redesigning the content.

Design notes

• Category utility, interaction: single-shot, targets: [system-prompt], governance all-low/public — matching A.T.L.A.S., its nearest neighbour (both are stateless single-task renderers, and it's listed as a companion).
• Acronym naming per the library convention (A.T.L.A.S., S.P.R.A.Y., Q.A.V.E. …).
• catalog.yaml needs no role entry — tools/build.py discovers roles from the roles/**/role.md tree. Only module.version moves, 2.0.0-alpha.2 → 2.0.0-alpha.3, a MINOR bump per VERSIONING.md ("new roles").
• Root README gains the catalogue row, the badge count 23 → 24, and the tree line.

Verification

• python3 tools/build.py → built 24 roles; index.yaml and dist/prompts/siren.md regenerated in the same commit, so the CI stale-artifact gate is satisfied.
• scripts/validate-index.sh --check-crisis → OK — all checks passed, including the README metadata-agreement check added in fix: restore role versions lost in the v2 migration, and guard the drift class #6 (the > **Version:** 1.0 | **Category:** Utility header agrees with the frontmatter).
• scripts/test-roles.sh → OK — all role smoke tests passed (4 warning(s)). siren is clean at 21,604 chars, well under the 60,000 budget. The 4 WARNs are the pre-existing crisis-number findings for frank, psy, vita, agora — untouched by this PR and targeted by Phase 2 config templating.
• The worked example embedded in the prompt was validated through a live Mermaid renderer: valid: true, diagramType: flowchart. The role tells the model to quote every label; the example had to actually demonstrate that, so it was worth confirming rather than assuming.

No existing prompt bodies changed.

Noted, not fixed here

roles/utility/atlas/README.md still links to prompt.md and prompt-semanticode.md from its Quick Start and Files table; both were replaced by role.md in the v2 migration. Out of scope for this PR, but it's the template new roles get copied from, so it's worth a follow-up.

🤖 Generated with Claude Code