The golden loop
How an AI agent drives Marrow — the six-step loop, and why looking at the picture is a required step.
Marrow has no GUI. That isn't a gap waiting to be filled — it's the design. The editor is a conversation: a user describes a network, an agent authors and validates the YAML, and the user reviews a picture. The reasoning is in ADR-0002.
This page is written for the agent.
The loop
The Autonomous Golden Loop
The required 5-step feedback cycle for AI agents authoring topologies
Identify devices, core/dist/access hierarchy, zones, and the narrative story.
Write input/*.yaml. Query verified vendor icon catalog; never guess.
Run validate --json. Fix all errors autonomously before continuing.
Render PNG and review image directly. Catch layout flaws invisible to syntax linter.
Compile single HTML or site bundle. Zero errors guaranteed.
Understand
From whatever the user gives you — a description, device configs, lab notes, discovery output — identify:
- the devices,
- the hierarchy (core / distribution / access),
- the zones or sites,
- the links and their ports,
- the story the diagram should tell.
That last one determines everything else. A diagram answering "where does traffic go?" is a different file from one answering "what's in each building?". Ask only what you genuinely can't infer.
Author
Write input/<name>.yaml. Search for icons first —
npm run marrow -- icons search <keyword> — and never invent an id.
Declare meaning explicitly: tier, zone, ha_pair_with. The engine infers
nothing from names.
Validate
npm run marrow -- validate input/<name>.yamlFix every error before continuing. Errors carry the exact line, a fix hint, and did-you-mean suggestions — use them rather than guessing. Read the warnings too; they're usually right.
See
npm run marrow -- snapshot input/<name>.yaml -o /tmp/x.pngThen open the image and look at it. This step is not optional and it is not
a formality. validate proves the file is well-formed; it says nothing about
whether the diagram is good. Overlapping meaning, a wrong hero, a zone that
swallows the picture, a story that doesn't land — all invisible to the
validator, all obvious in a PNG.
Fix what you see by changing the YAML, never the output.
Preview (optional)
npm run marrow -- serve inputGive the user a live URL. Edits hot-reload. Add --host 0.0.0.0 if they need to
reach it from another machine on their network — and tell them it's
unauthenticated.
Build
npm run marrow -- build input/<name>.yamlSingle file, or a folder site for large networks.
Never tell the user something is ready until validation passes with zero errors and you have looked at the result.
Why "look at it" keeps earning its place
The failure mode of an agent driving a diagram tool is confident nonsense: a file that validates perfectly and produces a picture nobody can read. The snapshot step is the only feedback channel that catches:
- a hero device that isn't the point of the diagram,
- one zone containing 400 devices and three others containing two,
- a hub-and-spoke intent that fell through to layered because one spoke links to another,
- labels that collide, or a diagram that's mostly empty space.
Each of those is a YAML fix, and each is invisible without eyes on the render.
Reading the layout the engine chose
The chosen archetype appears in the diagram's sidebar under About → Layout. If it isn't what you intended, the structure you declared isn't what you meant. The exact selection rules are in How layout is chosen.
Quick diagnosis:
| You got | Likely because |
|---|---|
flat when you wanted tiered | One device is missing tier: |
flat when you wanted hub-spoke | A spoke connects to another spoke |
tiered when you wanted zoned | Fewer than two zones actually contain devices |
zoned when you wanted tiered | You declared two or more zones — zoned outranks tiered |
Next
- Rules for agents — the non-negotiables, in one place.
- Claude Code skill — the packaged workflow.
- Authoring topologies — the judgment calls.