Open technical standard proposal · May 2026

Diagram Driven Development for verifiable agentic systems.

Mermaid Diagram Driven Development (MDD) treats Mermaid as the first auditable abstraction above source material, then compiles it into typed artifacts that agents can traverse deterministically.

Read the white paper View CLI workflow

mdd-engine compile graphs/auth.mmd --out build/auth.ir.json
mdd-engine verify build/auth.ir.json --tla --z3 --lean
mdd-engine bundle build/auth.ir.json --out dist/auth.mddbundle
mdd next dist/auth.mddbundle --state TokenExpired

LLMs give states meaning.

Mermaid makes meaning visible.

MDD-IR makes meaning typed.

mdd keeps agents inside the verified design space.

Source-backed graph abstraction

A pipeline that separates semantics from proof.

MDD reframes autonomous development as a chain of reviewable graph extraction, typed compilation, deterministic checking, proof-carrying bundles, and bounded runtime traversal.

Extract

LLMs identify candidate states, events, actors, ambiguity, and finite domains from source documents, code, issues, and tests.

Audit

Mermaid diagrams provide a compact, diffable, human-reviewable graph surface with provenance back to the original material.

Check

MDD-IR projects into TLA+, Z3, Lean4 obligations, test plans, and portable bundles for downstream agent runtimes.

Reference architecture

Heavy verification once. Lightweight traversal everywhere.

Full verification may require LLMs, Java/TLA+, Apalache, Z3, Lean4, and model-checking runs. Mermaid Engine splits that work from the deterministic agent runtime.

Source docs / code / issuesInput

↓

Mermaid audit graphHuman review

↓

Typed MDD-IRCanonical graph

↓

Verified .mddbundlePortable artifact

↓

mdd runtime traversalAgent guardrail

CLI tools

Two commands: one compiler, one runtime.

Heavyweight

mdd-engine

Ingests source material, compiles Mermaid into MDD-IR, runs verification backends, and emits proof-carrying bundles.

mdd-engine verify build/auth.ir.json --tla --z3 --lean

Lightweight

mdd

Reads prebuilt .mddbundle directories and gives agents deterministic state and transition traversal without the full verifier stack.

mdd next dist/auth.mddbundle --state TokenExpired

What MDD is — and is not

Design-level verification, not magical implementation proof.

Auditable

Every graph element should preserve explicit, inferred, hypothesis, or human-confirmed provenance.

Typed

MDD-IR separates Mermaid syntax from semantic domains, guards, invariants, and backend projections.

Bounded

The goal is to expose design bugs in the smallest dangerous state space, then guide tests and runtime behavior.