v1.3.0 to v1.4.0

113 added, 76 removed. Audit A to A.

---

name: diagram-generator

description: "Generate a diagram and route to the right engine — draw.io XML (precise, editable, C4, swimlanes) or Excalidraw JSON (hand-drawn, sketch, wireframes). One entry for flowcharts, architecture, ER, sequence, mind maps. Don't use for Mermaid or slides."

license: MIT

effort: high

+ dependencies:

+ - drawio-generator

+ - excalidraw-generator

metadata:

- version: 1.3.0

+ version: 1.4.0

author: "Luong NGUYEN <luongnv89@gmail.com>"

---

# Diagram Generator

- Single entry point for "make me a diagram". This umbrella picks the right engine and hands off to

- it — both produce the same diagram taxonomy (flowchart, architecture, C4, ER, sequence, mind map)

+ Single entry point for "make me a diagram". This umbrella picks one engine and hands the request to

+ it. Both engines cover the same diagram types (flowchart, architecture, C4, ER, sequence, mind map)

through the same four phases (**Understand → Propose → Generate → Validate**); they differ only in

- **output format and aesthetic**.

+ **output format and aesthetic**. The umbrella writes no file itself. Its body stays short to protect

+ the agent's context window; report templates live in `references/`.

## Which engine?

- |---|---|---|---|

+ | Engine | When the user wants... | Output |

+ |---|---|---|

+ | `drawio-generator` | Precise, professional diagrams to edit later in draw.io / diagrams.net / Confluence; official C4 styling; swimlanes; multi-page | kebab-case `.drawio` file (XML) |

+ | `excalidraw-generator` | A hand-drawn, sketchy, whiteboard feel; wireframes; quick collaborative sketches | kebab-case `.excalidraw` file (JSON) |

- Routing rules:

+ Apply the routing rules in order and stop at the first rule that matches:

- - The user names a format or tool ("draw.io", "diagrams.net", "Excalidraw", "whiteboard sketch") → use that engine.

- - The user names an editing target ("I'll tweak it in draw.io", "import to Confluence") → **draw.io**.

- - The user wants a hand-drawn / sketch / wireframe look → **Excalidraw**.

- - No format signal → ask one question: "Precise and editable (draw.io) or hand-drawn sketch (Excalidraw)?" Keep routing blocked until the user answers. Only after explicit delegation such as "just pick", "choose for me", or "use the default", choose **draw.io** for architecture/C4/technical diagrams and **Excalidraw** for wireframes/brainstorms.

- - The user asks for **Mermaid**, a slide deck, or brand/marketing graphics → out of scope; say so (Mermaid is native markdown; use a presentation or design tool for the others).

+ 1. The request asks for **Mermaid**, a slide deck, or brand/marketing graphics → do not route. Write

+ the out-of-scope Final Report (Mermaid is native Markdown; use a presentation or design tool for

+ the others).

+ 2. The request updates an existing file → route by its extension: `.drawio` → `drawio-generator`,

+ `.excalidraw` → `excalidraw-generator`.

+ 3. The request names exactly one tool or editing target ("draw.io", "diagrams.net", "Confluence",

+ "Excalidraw") → route to that engine, even when the aesthetic words point to the other one.

+ 4. The request names both tools → if it asks for both files, follow *Edge Cases → Both formats*;

+ otherwise ask the routing question in rule 6.

+ 5. The request asks for a hand-drawn, sketch, whiteboard, or wireframe look → `excalidraw-generator`.

+ 6. No format signal → ask one question: "Precise and editable (draw.io) or hand-drawn sketch

+ (Excalidraw)?" Wait for the answer. If the user explicitly delegates ("just pick", "choose for

+ me", "use the default"), route architecture, C4, ER, sequence, and swimlane diagrams to

+ `drawio-generator`, and wireframes, brainstorms, and mind maps to `excalidraw-generator`.

+ Anything else that is delegated goes to `drawio-generator`.

+ Silence is not delegation. Ask content questions (entities, relationships, direction) only inside

+ the engine's Phase 1, never in the umbrella.

## Dependency Preflight (mandatory)

- Routing above selects exactly one engine — `drawio-generator` or `excalidraw-generator` — which

- "How to use" then invokes by name. Once routing picks `engine`, and **before** invoking it, verify

- that engine is installed:

+ This skill invokes the two engines declared in frontmatter `dependencies`, but each run needs only

+ the one that routing selects. Run this once, after routing and before the engine starts:

```bash

- engine=drawio-generator # or excalidraw-generator — whichever routing selected

- asm list -p claude --json | grep -q "\"$engine\"" || {

- echo "Missing required skill: $engine" >&2

- echo "Install it: asm install github:luongnv89/skills:skills/diagram-generator/$engine -p claude --yes" >&2

- echo "Verify: asm list -p claude --json | grep '\"$engine\"'" >&2

- echo "No asm yet: npm install -g agent-skill-manager" >&2

- echo "Stop — never substitute the other engine; if it is installed, the user may re-request it explicitly." >&2

- exit 1

- }

+ if command -v asm >/dev/null && asm deps --help >/dev/null 2>&1; then

+ asm deps discover diagram-generator --json || echo "discover failed; acquire still runs" >&2

+ echo "dg_mode=lease"

+ else

+ echo "asm deps unavailable: npm install -g agent-skill-manager@latest" >&2

+ echo "dg_mode=installed"

+ fi

+ printf 'dg_session=%s\n' "diagram-generator-$(date +%s)-$$" # record it; reuse it verbatim

```

- A missing routed engine stops the run before any output is written.

- ## Repo Sync Before Edits (mandatory)

+ 1. With `dg_mode=lease`, run `asm deps acquire <engine> --session <dg_session> --json` for the

+ routed engine only. Record the returned `skillMdPath`.

+ 2. With `dg_mode=installed`, run

+ `test -f "$HOME/.claude/skills/<engine>/SKILL.md" || test -f "$HOME/.agents/skills/<engine>/SKILL.md"`

+ and record the path that exists.

+ 3. If step 1 or 2 fails, print

+ `Missing skill: <engine> — install: asm install github:luongnv89/skills:skills/diagram-generator/<engine> -p claude --yes`,

+ then stop with the missing-engine Final Report. Never substitute the other engine. Never

+ imitate the engine inline.

+ 4. **Release in `finally`.** If any acquire ran, run `asm deps release --session <dg_session> --json`

+ once at every terminal outcome, stops included, after the closing Final Report.

- The selected engine writes the diagram file. When that output path lives inside a git worktree, sync before the write to avoid clobbering remote work:

+ Do not acquire the engine that routing did not select.

- ```bash

- branch="$(git rev-parse --abbrev-ref HEAD)"

- git fetch origin

- git pull --rebase origin "$branch"

- ```

+ ## Repo Sync Before Edits (mandatory)

- If the working tree is dirty: stash → sync → pop. If `origin` is missing or a conflict occurs: **stop and ask the user.** Skip this section only when the output path is outside any git repository (e.g. a scratch directory).

+ The umbrella runs no git command and writes no file. The routed engine runs its own *Repo Sync

+ Before Edits* (scoped to the output file's repository, with its conflict and network-failure rules)

+ before it writes. Do not run a second sync here, and do not skip the engine's sync.

- ## How to use

+ ## Workflow

- Once the engine is chosen, invoke the nested skill by name — the runtime resolves names regardless

- of filesystem path:

+ 1. Apply the routing rules. If rule 1 matches, write the out-of-scope Final Report and stop.

+ 2. If rule 4 or 6 asks the routing question, wait for the answer. If the user has not answered

+ after the question was asked twice (*Edge Cases*), write the unanswered-routing Final Report

+ and stop.

+ 3. Print one line: `Routing to <engine>: <the rule that matched, in the user's words>.`

+ 4. Run the *Dependency Preflight*.

+ 5. Read the recorded `SKILL.md` path and follow that engine's workflow with the user's request

+ unchanged. The engine owns its questions, file naming, Repo Sync, validation, and fix cycles.

+ It also asks for confirmation before it overwrites an existing file; never skip or pre-answer

+ that confirmation.

+ 6. Relay the engine's Final Report as the run's closing output (*Final Report* below).

+ 7. Run the release step of the *Dependency Preflight*.

- - `/drawio-generator` — generate draw.io XML

- - `/excalidraw-generator` — generate Excalidraw JSON

+ ## Final Report

- Each engine owns its full workflow, `references/`, `agents/`, and validation checks. This umbrella

- stays short to protect the agent's context budget; it only routes.

+ Both engines end every run, stops included, with a four-line Final Report (`Result:` COMPLETE |

+ PARTIAL | BLOCKED, `Evidence:`, `Uncertainty:`, `Decision:`). When an engine ran, its Final Report

+ is this skill's closing output. Relay it verbatim: do not restate it, re-grade it, or change its

+ status. If the release step fails, add one line after the closing report, whichever skill wrote it:

+ `Router note: asm deps release failed for session <dg_session>; run asm deps release --session <dg_session> --json.`

- ## Prerequisites

+ When the umbrella stops before any engine runs (out of scope, unanswered routing question, missing

+ engine), it writes its own four-line report with status `BLOCKED`. Templates and fill rules:

+ `references/final-report.md`. Expected output when the routed engine is missing:

- 1. Confirm at least one nested engine is installed and callable.

- 2. Require enough diagram content to identify nodes, relationships, and intended audience; ask for

- missing essentials before routing.

- 3. Check whether the requested output path already exists. Let the selected engine run its own

- confirmation, backup, dry-run, error, and rollback safeguards before any overwrite.

+ ```text

+ Result: BLOCKED. No diagram written: drawio-generator is not installed.

+ Evidence: Routed to drawio-generator (rule 3, "in draw.io"). Preflight dg_mode=lease; asm deps acquire drawio-generator failed.

+ Uncertainty: No engine ran, so no file was generated or validated.

+ Decision: Install drawio-generator with the printed command, then re-run. Excalidraw output is available only if you ask for it.

+ ```

## Example

```text

- Input: "Draw a sketchy onboarding wireframe for mobile."

- Route: excalidraw-generator

- Expected output: one validated .excalidraw JSON artifact

+ Input: "Draw a sketchy onboarding wireframe for mobile."

+ Route: Routing to excalidraw-generator: rule 5, "sketchy wireframe".

+ Closing: excalidraw-generator's Final Report, relayed unchanged, e.g.

+ Result: COMPLETE. Wrote mobile-onboarding-wireframe.excalidraw (...)

```

## Acceptance Criteria

- Verify every routed run:

- - Exactly one engine is selected unless the user explicitly requests both formats.

- - The selected engine matches the requested format, editing target, or aesthetic.

- - The nested workflow reaches its Validate phase and produces its expected output artifact.

- - The artifact passes the engine's structural checks; validation errors are reported, not hidden.

- - Existing files are not overwritten without the selected engine's required confirmation or backup.

- ## Step Completion Reports

- After routing, emit:

- ```text

- ◆ Route Diagram

- Engine available: √ pass

- Route justified: √ pass

- Output validated: √ pass

- Result: PASS | FAIL | PARTIAL

- ```

+ Verify these for every run:

- Use `× fail — reason` when a check fails. Report PASS only after the nested engine's acceptance

- criteria and expected result are verified.

+ - [ ] Routing follows the first matching rule. Exactly one engine runs, unless the user asked for

+ both files.

+ - [ ] The routed engine matches the requested tool, existing file extension, or aesthetic, and the

+ `Routing to` line names the matching rule.

+ - [ ] The preflight acquires or checks only the routed engine. A missing engine stops the run with

+ no file written and no substitution.

+ - [ ] When an engine ran, the closing output is that engine's Final Report, unchanged.

+ - [ ] When the umbrella stopped, its report opens with `Result: BLOCKED` and has `Evidence:`,

+ `Uncertainty:` and `Decision:` lines.

+ - [ ] The closing report passes the four reader checks in `references/final-report.md` (result

+ findable, facts and assumptions separated, claims traceable, next decision clear). Without a

+ human reviewer's answer, human understanding is unconfirmed.

## Edge Cases

- - **User explicitly wants both formats** — generate with one engine first, then offer to regenerate the same diagram in the other.

- - **Ambiguous, no answer to the routing question** — keep routing blocked and ask the question again; silence or timeout is not approval to choose an engine. Apply the routing heuristics only when the user explicitly delegates the choice (for example, "just pick", "choose for me", or "use the default").

- - **Routed engine is unavailable** — the Dependency Preflight stops the run with its install command; the other engine is only an alternative the user may re-request explicitly. Never substitute silently or invent output under the wrong engine.

+ - **Both formats** — run the engine the user named first, or `drawio-generator` when no order was

+ given. After its Final Report, run the other engine on the same content without asking again,

+ because the user already asked for both: acquire it under the same `dg_session`. If the first

+ engine ended `BLOCKED`, ask before running the second. Relay each engine's Final Report in turn.

+ - **Unanswered routing question** — ask it once more. Silence or a timeout is not delegation. If the

+ user still does not answer, write the unanswered-routing Final Report.

+ - **Routed engine unavailable** — the preflight stops the run. Name the other engine as an option

+ the user may request explicitly, and never switch to it on your own.

+ - **Request for an image file** (PNG, SVG) — say that both engines write an editable file that its

+ editor can export to PNG or SVG. If the user accepts that, continue with the routing rules.

+ Otherwise write the out-of-scope Final Report.