Rules for agents
The non-negotiables when an agent is driving Marrow.
Short list, all load-bearing. Each one exists because ignoring it produces a specific, recurring failure.
Validate before claiming done
Zero errors, or it isn't ready. Warnings are advisory; errors are not.
Saying "your diagram is ready" over a file that doesn't compile is the single worst thing an agent can do here, because the user finds out later and stops trusting everything else you said.
Search icons; never guess
npm run marrow -- icons search firewallIcon ids are not guessable. affinity/tile/switch-multilayer, not
affinity/tile/l3-switch. Getting it wrong costs a validation round trip that
searching first would have avoided entirely.
Declare meaning; don't rely on inference
tier, zone, ha_pair_with. The engine will not read core-sw-01 and
conclude the device is core. Structure drives layout, and structure only exists
if you declare it.
Look at the result
snapshot then actually open the PNG. See the golden loop.
Never hand-edit generated or vendored trees
output/— regenerated on every build; edits are lost and misleading.icon-packs/**/svg/— vendor artwork, replaced byicons fetch.node_modules/— obviously.
One dev server per port
Check whether something is already listening on 5200 before starting another. A stale server serving an old directory looks exactly like a bug in the tool.
Never write credentials
No SSH passwords, no SNMP community strings, no API keys, no secrets in YAML —
and especially not in a file that will be committed or in a diagram that will be
shared. config: snippets are shown in the inspector of a file that's designed
to be emailed around. Sanitize them.
A built diagram is a shareable artifact. Everything in the YAML — notes, config snippets, management IPs — travels with it. Treat the file as public.
Don't commit unless asked
Authoring and building are not committing. Wait to be asked.
legacy-v1/ is reference only
The archived Python v1. Don't author from it, don't build with it. Use
marrow import to bring old YAML forward.
Delete x-v1-config: on sight
Inert. It records v1's engine × layout matrix, which v2 does not have and never reads. Leaving it in place makes the next reader expect outputs that will never appear.
When the picture is wrong, the description is wrong
There is no layout: key and nothing to drag. Resist the urge to reach for
pin: — it bypasses placement, can create the overlaps that fail the build, and
rots the moment the topology changes. Fix the structure instead.
Use density and scale for compactness, never manual pins
When the user asks for a denser diagram or a presentation-sized visual, declare
density: compact | standard | spacious or scale: <0.4-2.5> in the topology header
or marrow.config.yaml. Never attempt to move nodes closer using pin:.
Store operational facts in custom_fields and sections
When importing device metadata, CMDB attributes, or network operational state:
- Put key-value primitives (serial numbers, models, IOS versions, IPs) in
custom_fields:. - Put tabular data (BGP peers, interface status tables, routing tables) or markdown notes in
sections:. - Do not stuff structured tables into the single-line
note:field or discard them inx-annotations.
Demonstrate visually in documentation; never rely on text or ASCII
When writing technical guides, decision records, or references:
- Render live visual components (such as
and) rather than writing descriptive words like "plain line", "double rail", or "green LED". - Replace ASCII diagrams with real vector schemas, blueprint title blocks, or live component previews.
- Ensure visual meaning is immediately recognizable at a glance without reading prose descriptions.
Use Marrow and its official logo for all branding examples
Always use Marrow and the official Marrow arrowhead logo as the example organization and brand mark across documentation, configs (marrow.config.yaml), and schemas. Never use fictional placeholders like "Acme Networks" or generic globe icons.
Check updates safely; authorize impacting changes
When running, verify skills and toolchain status (npx skills check, toolchain checks):
- Safe patches: Apply non-breaking updates cleanly without disturbing custom configuration or unrelated code.
- Impacting / Breaking updates: If an update changes schema contracts, alters output structures, or impacts existing topologies, stop and alert the user. Detail exactly what will be affected and require explicit user authorization before updating.
Self-heal minor update regressions autonomously
When an update to Marrow or its skills introduces minor issues (e.g. deprecated syntax, renamed attributes, minor layout warnings, missing vendor icon dependencies, or lint errors):
- Do not immediately surrender or stop the workflow for minor breaks.
- Run structured diagnostics (
npm run validate -- <file> --jsonornpm test) to extract precise error codes, line numbers, and suggestions. - Autonomously patch the syntax, update renamed keys, and re-compile packages.
- Confirm zero errors on re-validation before reporting back.
- Only escalate if the issue requires architectural design decisions or changes the underlying topology structure.