dsh-maestro-diagram — Maestro Diagram Studio (Host-only)
Hybrid skill + plugin for SA-grade diagrams: GitHub-native Mermaid (single source of truth) + editorial HTML+SVG (self-contained, no JS) + deterministic verify/drift (tool calls > LLM).
- Skill:
maestro-skills/skills/diagram-studio/SKILL.md (rank 350) — teaches the agent when/how to draw, selects among 5 Mermaid types, enforces editorial discipline (density 4/10, accent 1-2), and decides audience (Team vs Client).
- Plugin:
packages/dsh-maestro-diagram (this package, Host-only, rootDir: src/host, inject: ['sessions','tools']) — exposes mermaid_verify and mermaid_drift as reversible ctx.tools.register effects. No Client bundle on v1.
Inspired by cathrynlavery/diagram-design (MIT, 39 editorial types, tokens paper/ink/accent) + diagram-drift + dsh-mermaid. Default output stays GitHub Mermaid (per "render được trên github là ok"); HTML editorial is an explicit export: html when audience: client.
Installation
# As DSH plugin (Host-only, no restart of skill provider needed, but Host needs reload for tools)
dsh plugin add @ddtcorex/dsh-maestro-diagram
# Or via the thin meta-bundle (opt-in until proven, not in meta v2 yet)
dsh plugin add @ddtcorex/dsh-maestro-meta
For skill-only use (no Host tools): git pull + pnpm --dir maestro-skills run build — then node maestro-skills/skills/diagram-studio/scripts/verify-mermaid.mjs <file>.
Tools
mermaid_verify
input: string (Mermaid source or file content when isPath=true)
isPath: boolean? (if true, input is treated as file path, extracts ```mermaid blocks)
strict: boolean? (if true, warns on anti-patterns: shadow, graph legacy, rounded-2xl)
→ { ok: boolean, errors: {line,col,msg}[], warnings: {msg}[] }
Deterministic mermaid.parse() + optional mermaid-cli validate. Never throws — returns isError shape for the agent to fix.
mermaid_drift
diagramPath: string (e.g. docs/architecture.md)
codeRoots: string[]? (default ["packages/*","govard","maestro-skills"])
→ { missingInCode: string[], staleEdges: {from,to}[], missingInDiagram: string[], summary: string }
Parses Mermaid nodes/edges vs scans codeRoots (package.json names, govard/internal/*, skills). Inspired by diagram-drift — flags missingInCode / staleEdges / missingInDiagram before PR.
Supported Cases (all verified — see SKILL.md § Supported Cases)
5 diagram types (mapped from 39 editorial types):
flowchart TB/LR — Components + connections (architecture) — docs/architecture.md §1.1sequenceDiagram — Messages over time (turn lifecycle) — docs/specs/2026-08-27-harness-turn-flow-sequence.mdclassDiagram — Classes + ops (ReviewProvider <|-- GitLabProvider)erDiagram — Entities + fields (PROJECT ||--o{ MEMORY)stateDiagram / stateDiagram-v2 — States + guards ([*] --> queued)
All share tokens paper #f5f5f5 / ink #2d3142 / accent #eb6c36 / muted #8a94a6 / link #4a90e2 from references/style-guide.md (classDef focal/muted, no shadow, rx:6).
2 audiences (controls 4 elements per HTML):
- Team / Internal (
team|internal|engineering or "cho team") → HTML has both: inline SVG + <details><summary>Mermaid source</summary><pre> collapsed + Editorial tokens card + About footer with verify/drift. Example: harness-architecture.html 16K (1 svg,1 pre), harness-turn-flow-sequence.html 31K.
- Client / External (
client|pitch|deck or "cho khách") → HTML has only SVG, no <pre>, no tokens card, footer reduced to Generated via diagram-studio — 2026-08-27. Example: ...-client.html 12K/30K (1 svg,0 pre), PNG 124K/65K.
3 outputs:
- GitHub-native Mermaid in
docs/architecture.md / docs/specs/*-design.md (always show source)
- Editorial HTML
docs/diagrams/<slug>.html (self-contained inline SVG/CSS, no JS) — Team vs Client per table
- Deck PDF
docs/diagrams/maestro-harness-deck.pdf (A4 landscape, 3 pages) — always Client rules, PNG only
3 verification cases:
- Parse ok → 5/5 PASS
- Parse fail (empty,
A-->) → ok:false, line:2
- Anti-pattern strict (
shadow:true) → warnings:1
- Drift
missingInCode 0 / missing file throws ENOENT
2 live case studies on this harness:
- Architecture flowchart (10 plugins + meta) —
harness-architecture.html 16K → ...-client.html 12K — PNG 238K→124K — Deck p1
- Turn flow sequence (6 participants) —
harness-turn-flow-sequence.html 31K (svg 28K via mermaid-cli 11.16.0) → ...-client.html 30K — PNG 100K→65K + ...-rendered.png 20K — Deck p2
All above are live-verified: packages/dsh-maestro-diagram 8/8, maestro-workspace -r verify 13 packages Done, chrome headless 980×1400 screenshots, pdfinfo Pages:3.
Usage (agent)
- Load
diagram-studio skill — it selects flowchart vs sequenceDiagram vs classDiagram vs erDiagram vs stateDiagram by semantic pattern.
- State
type, size (85%/100%), what will be cut due to budget (density 4/10) and wait for redirect (confirm-before-drawing).
- Write Mermaid to
docs/specs/*-design.md (or docs/architecture.md §1.1), call mermaid_verify — fix until ok:true.
- If
audience: client, also render editorial HTML: mermaid-cli -i <src>.mmd -o <slug>.svg → embed inline SVG into docs/diagrams/<slug>.html per audience table, then chrome --screenshot → PNG and --print-to-pdf → deck. Hide source/tokens/footer for client.
- Before PR, run
mermaid_drift --diagram docs/architecture.md --roots packages/*,govard,maestro-skills — fix missingInCode by patching doc or code.
CLI fallback (no plugin): node maestro-skills/skills/diagram-studio/scripts/verify-mermaid.mjs docs/architecture.md
Build & Verify
pnpm --dir packages/dsh-maestro-diagram run build # must create lib/index.js flat (rootDir: src/host)
pnpm --dir packages/dsh-maestro-diagram run test # 8/8 (5 verify + 3 drift)
pnpm --dir packages/dsh-maestro-diagram run verify # tsc --noEmit
pnpm --dir maestro-skills run build # skill provider
pnpm --dir maestro-workspace -r verify # 13 packages Done
lib/index.js flat is required — test -f lib/index.js must be 0 (not lib/host/index.js), otherwise dsh web boot fails ERR_MODULE_NOT_FOUND. Dry-boot on ephemeral port before any real restart.
Publishing
This package is public (private:false, workspace:^ deps). Publish with pnpm publish --access public only — never npm publish (would leave workspace: in tarball). See maestro-skills/README.md for skill distribution and docs/specs/2026-08-27-diagram-studio-design.md for design.
License
MIT — see LICENSE. Editorial tokens/style-guide trimmed from cathrynlavery/diagram-design (MIT) with attribution in maestro-skills/skills/diagram-studio/references/diagram-design-learnings.md.
