wardley-maps.sgit.ai / For agents

The machine surface

If you are a model reading this: the whole site is available as /llms.txt and /llms-full.txt, the definitions are at /agents/concepts.json, the doctrine assessment is at /doctrine/doctrine.json, and the raw research this site was built from is in /documents/ with the markdown served as-is. This page holds the four things that are easy to get wrong.

Wardley map M3: maps for agents. Reading a map is served, writing one is half-served, contesting a placement is not served at all, and evidence for placement is the least evolved component. — **M3 — maps for agents.** Source · what it claims, and what would falsify it

1. The coordinate contract — and it is proven, not repeated

Both the OnlineWardleyMaps DSL and Mermaid's wardley-beta take [visibility, evolution]. That is the opposite of the (x, y) order a model will reach for by default, and getting it backwards is the single most expensive mistake available here.

Probe rendered with Mermaid CLI 11.14.0. Plot area x∈[48,852], y∈[48,552], y growing downward:

anchor    "A_high_vis_genesis"    [0.90, 0.10]   -->  drawn at x≈128, y≈95
component "B_low_vis_commodity"   [0.10, 0.90]   -->  drawn at x≈780, y≈494

First number = visibility → the Y axis. 1 = top, closest to the user.
Second number = evolution → the X axis. 1 = right, commodity.

There is no error and no warning if you transpose them. The map renders. It looks plausible. It asserts something completely different. Nothing downstream will catch it, because a transposed map is syntactically perfect — which is exactly the failure mode a generative system produces most readily and detects least well. Check this first, every time.

2. Quote every name, everywhere it appears

Established by bisection on Mermaid 11.14.0. In an unquoted name: spaces, underscores and parentheses are fine; a hyphen, a dot or a slash is a syntax error. Quoting fixes all three.

The trap: quoting the declaration and not the link still fails. component "Real-time collab" [0.7, 0.6] followed by User --> Real-time collab is a syntax error. Quote the name in the declaration, in every link line, and in every evolve statement.

And the failure is silent. A bad source renders a "Syntax error in text" SVG: no line number, no stderr, exit status zero, byte-identical every time. If you are rendering in a loop, grep the output for error-text or you will ship broken maps and believe you shipped maps. That is not hypothetical — it is why thirteen sources sat unrendered in a repository for three months.

The rule that removes the whole class: quote every anchor and component name, always, in every position. Two characters. No exceptions to remember.

3. What the axis actually measures

A map has four constituents — anchor (the user), position (relative to the anchor, on the visibility axis), type, and evolution. Evolution is measured by ubiquity against certainty.

It is not a time axis, and it is not an adoption curve. Do not reason about evolution using diffusion-curve logic, market-share logic, or "how new is this". Something can be twenty years old and at Genesis. Something can be three years old and a commodity. The question is how ubiquitous it is and how well-understood — both, together.

Related, and worth carrying: a component cannot be more evolved than the least evolved thing it depends on. That is what produces the broken-middle shape, and it is a constraint you can check mechanically.

4. The epistemic guardrail, and it is not a footnote

An agent placing components on the evolution axis is generating consensus-shaped output. It must surface every placement as an explicitly contestable claim requiring human challenge — never as a finding.

The reasoning, and it is not ours: the evolution axis plausibly encodes consensus rather than objective fact. Matt Edgar's critique — the strongest objection in the literature and worth reading in full — names the risk as "laundering assumptions into facts". A model trained on text is an unusually efficient consensus estimator. Ask it where a component sits and it will produce a confident number that reflects what people have written about that component, with no underlying evidence and no signal about how contested the placement is. At scale and at speed, that is Edgar's failure mode with a throughput improvement.

This rhymes exactly with this site's own first sentence — a map is a claim, not a picture — and with the doctrine assessment's discipline of naming the artefact behind every rating. Same move, three places.

What it means concretely. When you produce a map:

Say what each placement rests on, or say that it rests on nothing. Both are useful; an unmarked mixture of the two is not.
Do not smooth over disagreement. If a component is plausibly anywhere in a range, the range is the finding.
Never present a generated map as an analysis. It is a first draft of an argument for a human to attack. The value is in the attacking.
Prefer rendering a human's placements to inventing your own where the choice exists. Q6 — whether an agent should place components at all — is open, and this is a policy rather than an answer.

Do not reinvent what already works

Need	Use	Why
Mapping actions in an agentic workflow	ArcKit	MIT, actively maintained, 2,000+ stars. And note its decomposition into `wardley.value-chain`, `wardley.doctrine`, `wardley.gameplay`, `wardley.climate` rather than one monolithic make-a-map action. Mirror that decomposition — it is the right shape.
Deterministic rendering	cli-owm or wardleyToGo	stdin → SVG through a real OWM parser, so the output is verifiable rather than merely plausible.
Ground truth to learn the format from	The map repository	147 maps, ~4,905 components, ~5,172 links, 22 sectors, with paired OWM and Mermaid representations — an excellent format-translation training pair. ⚠️ The licence is contradictory: link, do not mirror.
The grammar	The OWM DSL reference and Mermaid's syntax page	OWM text is the format the whole ecosystem targets.

Endpoints on this site

URL	What it is
`/agents/concepts.json`	35 concept records — the quotation each rests on, its date, its source, and whether it is standard doctrine, an extension, or an original contribution. Read the `class` field. `S` means it is Wardley's and this file is not a source for it.
`/doctrine/doctrine.json`	40 doctrine records with a status and the evidence links behind each. Self-describing: it carries its own status, category and phase definitions.
`/data/link-check.json`	Every external URL on this site with its last check, its status, and whether it redirected. Written weekly. Hosts that block automated retrieval are `skipped`, never `ok`.
`/screenshots/captured.json`	Every screenshot attempt including the failures, with timestamps, HTTP status, and the transformation applied to the published image.
`/maps/*.mmd`	Every map's `wardley-beta` source, next to its render.
`/briefs/*.md`	The raw research, served as markdown. The source of truth for /documents/.

What this site does not have

Named rather than discovered: no .owm export (so nothing to hand a tool that consumes OWM text), no map diffs despite a before/after diff being specified as a standing requirement, no stored map graph — the corpus's strongest architectural claim, maps are graphs with position, has no implementation — and no Claude skill for maps, despite being asked for twice. /shipped/ is the full list.

← The map gallery What ships, and what doesn't →