Diagram-First
A skill that makes diagrams the default agent artifact whenever the content has order, connection, state, or proportion.
The judgment call is isolated to one stage; everything downstream (rendering, linting, gating, assembly) is deterministic code.
Extract to assemble
One strong-model stage emits a schema-validated spec; a small model reads the result cold; four stages are plain code.
Problem / outcome
Problem
Agents default to prose even when a plan, recap, or system is easier to understand as a diagram.
Outcome
A Claude Code plugin that makes diagrams the agent's default output for plans, recaps, and system documentation. A router skill decides when structure should be shown instead of described; a forked builder agent, deterministic Python renderers, and a saved workflow execute the heavy lifting off the main thread.
- A schema-validated intermediate representation shrinks the strong-model surface to one stage, rendering the spec into diagram syntax is a template function, so the output is syntactically valid by construction, and half the design-review rubric collapses into graph lint.
- Every artifact ships with an honest verification grade, enforced by a headless-browser gate that renders each diagram at the pinned renderer version before anything goes out.
- The only stage that needs a strong model, its sole job is emitting a schema-validated intermediate representation, not drawing anything.
Stage detail
The only stage that needs a strong model; its sole job is emitting a schema-validated intermediate representation, not drawing anything.
A template function over the validated spec, so output is syntactically valid by construction.
A headless browser opens the artifact, renders every diagram at the pinned version, and blocks anything that fails. Parse-valid is not render-valid.
A small model states what each diagram claims without having seen the reasoning that produced it, catching drift between intent and output.
Capability matrix
A router skill decides when to show structure; a forked builder agent does the heavy lifting.
Saved workflow plus forked builder keep diagram work off the main thread.
A schema-validated intermediate representation shrinks the strong-model surface to one stage.
Deterministic Python renderers turn a schema-validated IR into diagram syntax.
Diagrams become the default agent artifact for plans, recaps, and system docs.
A headless-browser gate renders each diagram at the pinned renderer version before ship.
Diagram-First turns structure into diagrams or charts so patterns stay inspectable.
Diagram-first ships with render-verified grades so broken tabs cannot leave silently.
README
I built a Claude Code plugin that makes diagrams the agent's default output for plans, recaps, and system documentation. A router skill decides when structure should be shown instead of described; a forked builder agent, deterministic Python renderers, and a saved workflow do the heavy lifting off the main thread. A schema-validated intermediate representation shrinks the strong-model surface to one stage. Rendering the spec into diagram syntax is a template function, so the output is syntactically valid by construction. Every artifact ships with an honest verification grade, enforced by a headless-browser gate that renders each diagram at the pinned renderer version. The write-up covers the trigger stack and the rendering failure that forced the verification gate. Clear Diagrams and Terragram automate related design-first workflows from repo evidence.