draw.io diagrams

You build the diagram by writing a small Node script that uses the drawio-ai engine. The engine places every box and routes every arrow. You only declare what is inside what.

Follow the steps in order. Do not skip a step. Each step names the exact file to read — read only that file, nothing else in the kit.

Step 0 — Check the CLI

command -v drawio-ai >/dev/null 2>&1 && drawio-ai root || echo "MISSING"

If it prints MISSING: stop. Tell the user to install it, then try again:

npm i -g drawio-ai-kit

Never run npm i -g yourself.

Step 1 — Understand the request

You need these 4 facts. Take them from the user's message first.

Rules for asking:

• Ask one short message with all missing questions together. Offer choices, e.g. "Which cloud: AWS, Azure, or GCP?"
• If the user said "just do it" or the request is already clear, do not ask. Pick the common choice and tell the user what you assumed at the end.
• The source is a Terraform/Terramate repo? Follow workflows/from-iac.md before Step 2.

Step 2 — Pick the domain reference

Read exactly one row's files from this skill folder:

Then also read:

• references/api.md — the whole engine API on one page (every domain). Never open engine source code.
• references/principles.md — layout rules: dense grids, flow direction, no overlaps (cloud domains; skip for BPMN).

Optional, only if you are unsure which layout fits: references/diagram-types.md. Colors and creators: references/style-guide.md.

Step 3 — Build, check, fix

Follow workflows/build.md. Short version:

1. drawio-ai search "a, b, c" — look up all icons in one call (comma or space separated, e.g. "k8s pg es"). Use only names it returns.
2. drawio-ai scaffold <template>.mjs -o <out-dir>/build.mjs --name <name>.drawio — copy the closest template. <out-dir> = the folder of the output path from Step 1; the .drawio lands there.
3. Edit the tree in build.mjs. No x/y numbers.
4. drawio-ai run <out-dir>/build.mjs — it builds, prints VALIDATE: {…}, and renders a PNG with an issues list.
5. Fix all errors/warnings/advice/issues in one edit. Run again. Repeat until all are empty (max 5 runs).
6. Look at the PNG once. Fix what you see. Done. (No draw.io desktop app → no PNG: skip this step.)

Can your harness run a subagent that has shell + image reading? You may hand Step 3 to it with workflows/delegate.md. Otherwise do Step 3 yourself.

Step 4 — Deliver

Check every box before you answer:

• Built with the layout engine (group/frame/grid + icon/box + renderTree). No x/y numbers.
• Every icon name came from drawio-ai search. No icon recolored.
• drawio-ai validate <file>.drawio → "ok":true with empty errors, warnings, advice.
• You looked at the rendered PNG — or, if RENDER-SKIPPED was printed, you told the user no PNG was made.
• The file is in the user's project — never inside the kit folder (drawio-ai root).

Reply with: the .drawio path, the .png path (if any), one sentence on what the diagram shows, and any assumptions you made.

Never

• Never write files into the kit folder (drawio-ai root).
• Never invent icon names or style strings. Search for them.
• Never hand-write draw.io XML or x/y coordinates.
• Never read the engine's source (dist/, src/). references/api.md has everything.
• Never import by file path. Scripts use import { ... } from "drawio-ai-kit" and run with drawio-ai run build.mjs.