Monodraw LLM

Monodraw LLM

Generate Monodraw v5 object graphs with editable frames, containers, text, shadows, borders, connectors, free endpoints, and line-pinned labels. Emit both native .monopic and inspectable .monojson files.

Request to command

Hand the task back if what is wanted is a chart or plot (dataviz), a diagram drawn inside a web artifact or page (artifact-diagramming), or a UI mockup or wireframe (design). The only thing this skill produces is a Monodraw document.

Resolve the directory containing this SKILL.md as SKILL_DIR. Claude Code exposes it as ${CLAUDE_SKILL_DIR}; in Codex, use the discovered skill path. Then use the bundled wrapper:

CLI="$SKILL_DIR/scripts/monodraw-llm"

The wrapper runs the source checkout it sits inside, otherwise an installed monodraw-llm on PATH. With neither it exits 127 and prints the python3 -m pip install -e . instruction. Do that and retry; do not fall back to hand-writing .monopic bytes.

Convert an ASCII sketch to editable Monodraw

When the user asks for an ASCII diagram and a Monodraw export, use this two-stage workflow:

1. Draft or refine the text diagram in the conversation. If the user already supplied one, use it as the design contract.
2. Map every box to a node or group; map nested boundaries to parent/child groups.
3. Map arrows and lines to edges, including direction, attachment sides, labels, dashed styles, and deliberately free endpoints.
4. Preserve horizontal/vertical ordering and whitespace relationships with explicit position, width, and height values when layout fidelity matters.
5. For a label that must move with its connector, add a line_positions entry plus a node or annotation with a matching pin. An edge label alone creates an editable but absolutely positioned midpoint label.
6. Generate, validate, and open or render the result when Monodraw is available.

Do not paste the full ASCII drawing into one Monodraw text frame. The goal is a diagram made from separate editable native objects. The LLM performs the semantic translation; the CLI performs deterministic serialization.

Create a new editable diagram

1. Read references/spec.md before writing a non-trivial spec.
2. Use concise multiline labels and stable semantic IDs.
3. Represent visual boundaries as groups; represent components as nodes.
4. Attach edges to frame sides. Use free points only when a connector deliberately ends in open space.
5. Use explicit positions for screenshot fidelity. Use ranks/automatic layout for a new architecture.
6. Generate and validate:

"$CLI" generate diagram.json -o diagram.monopic
"$CLI" validate diagram.monopic
open -a Monodraw diagram.monopic

The generate command writes the .monopic plus a readable .monojson sibling unless --monopic-only is passed.

Use assets/multi-region-checkout.json as the primary complex authored example. It exercises nested regions, service and data tiers, shadows, routed incident paths, and pinned labels. For a 1:1 example, extract any existing .monopic and preserve the resulting explicit geometry and z-order.

Recreate an existing document 1:1

Extract a source spec instead of manually reverse-engineering its internal IDs:

"$CLI" extract-spec source.monopic -o source.spec.json
"$CLI" generate source.spec.json -o recreated.monopic
monodraw -u -w source.monopic > original.txt
monodraw -u -w recreated.monopic > recreated.txt
diff -u original.txt recreated.txt

Preserve these fields when editing an extracted spec:

• position, width, and height for exact geometry.
• Separate name and label values when both exist.
• z_order, which Monodraw interprets front-to-back.
• line_positions and frame pin records for labels that follow connectors.
• Explicit connector sides, arrows, free points, line style, and origin.

Do not claim 1:1 fidelity from structural validation alone. Require no renderer diff, or use screenshots when the installed renderer is unavailable.

Run corpus regression

Use Monodraw's renderer as the authoritative visual oracle:

"$CLI" regress path/to/files -o regression-output

The output contains, per case, the extracted spec, fresh v5 files, original/generated Unicode renders, and a unified diff. It also writes report.json and report.md.

Pass --open-failures only when visual inspection is useful; avoid opening every passing document.

Inspect and convert

"$CLI" inspect diagram.monopic
"$CLI" unpack diagram.monopic diagram.monojson
"$CLI" pack diagram.monojson diagram.monopic
"$CLI" validate diagram.monopic diagram.monojson

Use --force with pack only after deliberately accepting validation errors.

Preserve native editability

• Emit type-20 frames and type-5 connectors, not a raster image or one flattened text block.
• Keep connector endpoints attached to frame side records so dragging/resizing remains useful.
• Use type-24 line positions for pinned labels so labels move with their connectors.
• Place outer containers last in default z_order; otherwise they mask their contents.
• Retain the .monojson sibling as the reviewable source when practical.
• Re-open the final .monopic in Monodraw after any format-level change.

Load references selectively

• Read references/spec.md to author or modify diagram specs.
• Read references/format.md when diagnosing serialization, object references, legacy v3 behavior, z-order, or pinned-label problems.