corezoid-node-layout — Claude Code skill: install and use
corezoid-node-layout arranges Corezoid process nodes into a readable top-to-bottom flow and moves error handling to the right. Use it before pushing a new process or after a layout request.
MIT ★ 74 updated 2026-10-29
/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoidWhat corezoid-node-layout does
This skill runs the layout-process MCP tool against a .conv.json file. It creates a vertical main flow, places branches around it, and removes node collisions. Small tree-shaped processes use a waterfall layout; larger graphs separate the business flow from local error groups and shared error handling on the right.
Run it after the nodes and edges are complete and before push-process, then use lint-process. The tool edits only x and y, leaving logic, edges, node types, conv_id, aliases, and extra.modeForm state intact. You can preview coordinates with dry=true and choose compact, medium, or roomy spacing; medium is the default.
It works on the local file without authentication or a network request because the engine is part of the plugin's Go MCP server. An existing user-authored process is preserved unless the user asks for a full rearrangement. When nodes are added to such a process, new nodes stay at x: 0, y: 0 until push-process places them near their graph neighbours.
What it helps with
- arrange a Corezoid process as a vertical flow
- remove overlaps between process nodes
- move error handling into a right-side rail
- keep the diagram readable before
push-process
Example prompts for the agent
- Arrange the nodes in
process.conv.jsonand prepare the process forpush-process. - Preview the planned layout for
process.conv.jsonwithdry=truewithout changing the file. - Rearrange
process.conv.jsonwithcompactdensity, then runlint-process.
How to install corezoid-node-layout
1Plugin marketplace
/plugin marketplace add corezoid/corezoid-ai-plugin/plugin install corezoid@corezoidThis installs the whole corezoid plugin with all its skills
2Skills CLI (Vercel)
npx skills add corezoid/corezoid-ai-plugin --skill corezoid-node-layout -a claude-code3Manually: put the files in place
~/.claude/skills/corezoid-node-layout/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/corezoid-node-layout/
1Skills CLI (Vercel)
npx skills add corezoid/corezoid-ai-plugin --skill corezoid-node-layout -a codex2Manually: put the files in place
.agents/skills/corezoid-node-layout/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add corezoid/corezoid-ai-plugin --skill corezoid-node-layout -a cursor2Manually: put the files in place
.cursor/skills/corezoid-node-layout/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install corezoid/corezoid-ai-plugin plugins/corezoid/skills/corezoid-node-layout2Manually: put the files in place
.github/skills/corezoid-node-layout/SKILL.md1Skills CLI (Vercel)
npx skills add corezoid/corezoid-ai-plugin --skill corezoid-node-layout -a gemini-cli2Platform CLI
gemini skills install https://github.com/corezoid/corezoid-ai-plugin --path plugins/corezoid/skills/corezoid-node-layoutManually: put the files in place
.devin/skills/corezoid-node-layout/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about corezoid-node-layout
How do I install corezoid-node-layout in Claude Code?
Add the marketplace with /plugin marketplace add corezoid/corezoid-ai-plugin, then install the plugin with /plugin install corezoid@corezoid.
What does corezoid-node-layout do?
It runs layout-process to place Corezoid nodes automatically. The main flow runs from top to bottom, error handling moves to the right, and only x and y coordinates are changed.
Can I run it on an existing process?
Yes, when the user explicitly asks for a rearrangement. Otherwise the existing coordinates stay intact, while newly added nodes remain at x: 0, y: 0 until push-process.
Source text
SKILL.md · MIT
---
name: corezoid-node-layout
description: >
Auto-arrange the nodes of a Corezoid process into a clean, readable layout —
a vertical top-to-bottom business flow with error handling railed off to the
right and no overlapping nodes. Use it AUTOMATICALLY on every process YOU
built or assembled, as the last step before push-process — never hand-place
coordinates by eye (eyeballed grids overlap the moment nodes are taller than
the step). Also reach for it whenever the user says a process is unreadable,
tangled, ugly, a mess, or that nodes sit on top of each other, or asks to
"arrange", "lay out", "tidy up", "make readable", "fix positions", "clean
the diagram", "remove the overlaps" — or their equivalents in any language
the user speaks. Do NOT silently
re-arrange a process the user already positioned — see the "When you MAY
re-layout" rules in the body. It changes x/y coordinates only — never
collapse/expand state, edges, logic, conv_id, aliases or node types.
---
# Auto-Layout Corezoid Process Nodes
You make a process **readable**: business logic as a clear vertical spine,
error handling collected in a tidy right-hand rail, nothing overlapping. This is
the mechanical companion to the positioning rules in
`${CLAUDE_PLUGIN_ROOT}/docs/process/node-positioning-best-practices.md` — that
doc is the source of truth for *why*; this skill *does it* deterministically.
## When you MAY re-layout — and when you MUST NOT
A process's layout is part of how its author reads it. Re-flowing someone's
diagram without asking is destructive even though the logic is untouched — it
throws away a mental map they are used to. So the rule is about **authorship**,
not just readability:
- **A process YOU built this session, from scratch → always lay it out.** You
own its positions; arrange it cleanly before `push-process`. No need to ask.
- **An existing / pulled / user-authored process → do NOT re-layout by
default.** Preserve the author's `x`/`y`. This holds even if you just edited
it — a user who is used to their arrangement must not find it rearranged.
- **When you add nodes to someone else's process** (an edit, not a rebuild):
leave the new nodes at `x: 0, y: 0` — `push-process` auto-places them next
to their graph neighbours while keeping every existing node where it was
(preserve mode; see node-positioning-best-practices.md § Automatic
Placement on Push). Do **not** run the whole-process auto-layout — that
repositions everything. Full re-layout on a foreign process happens only on
request.
- **The user explicitly asks** ("tidy this up", "fix the positions", "make it
readable" — in any language) → re-layout the whole process. This is the one
case where rearranging a foreign process is wanted.
- **The process is genuinely unreadable** (heavy node overlaps, a tangled mess)
→ don't silently fix it. **Offer**: briefly say it's hard to read and ask if
they want it re-arranged. Re-layout only after a clear yes. If they decline,
leave it exactly as is.
When in doubt, ask before touching an existing layout — a wrong guess costs the
user their familiarity; asking costs one sentence.
## Workflow (once the rules above say you may)
Run the layout **after** the process JSON is finalized and **before**
`push-process`:
1. finish building the process (nodes + edges correct),
2. call the **`layout-process`** MCP tool on the `.conv.json`,
3. `lint-process`, then `push-process`.
The tool rewrites the file in place, touching only `x`/`y`. The user's existing
`extra.modeForm` state is immutable: expanded nodes stay expanded and collapsed
nodes stay collapsed. `extra`, edges, logic, `conv_id`, aliases and node types
are left intact.
## How to run
Call the MCP tool (no auth needed — it works entirely on the local file):
```
layout-process(process_path="path/to/NNN_name.conv.json")
```
Preview without writing (the result lists the planned coordinates):
```
layout-process(process_path="path/to/NNN_name.conv.json", dry=true)
```
Control the spacing with `density="compact"|"medium"|"roomy"` (default
`medium`). The density pass re-spaces rows and columns from the nodes' REAL
sizes — a row of collapsed 48px IF-squares stops reserving a full block-row
of air, so a process fits on screen without zooming out. `roomy` skips the
pass and keeps the coarse block-sized rhythm (useful for presentations).
The same tool is available from a shell via the server's CLI mode:
```bash
sh "${CLAUDE_PLUGIN_ROOT}/mcp-server/run.sh" layout-process process_path=<file> dry=true
```
The engine lives inside the plugin's Go MCP server — no extra runtime, no
network, no server call.
## What it does (the layout rules it enforces)
The engine picks a strategy automatically (the result reports which one and why):
- **Small and tree-like processes** (fewer than ~25 nodes, or one main flow
with branches) → a vertical "waterfall": the happy path runs straight down
the central column, branches fan out to the sides (longer branches nearer
the centre — a hub with rays reads as a star, cascaded IFs as a tree), and
each error cluster is pinned tight to the right of the node it protects.
Small processes always get the waterfall: the layered machinery below only
pays off at scale, and on a small graph its spine drifts sideways.
- **Region composition** — big processes routinely combine shapes, so region
detection runs in a loop and each region gets its own geometry while the
rest of the graph keeps the waterfall:
- **TABLE**: a dispatcher fanning into 3+ structurally identical pipelines
that reconverge (one sync pipeline per entity type is the canonical case)
→ parallel columns with row-aligned steps, and the shared tail (a DLQ,
the columns' error clusters) in a side column;
- **STAR / sun**: a hub fanning into 4+ chain-shaped rays of *varying*
depth that reconverge → rays hang symmetrically around the hub→merge
axis, deepest nearest the axis (a fir-tree silhouette);
- **DIAMOND**: a compact two-way fork/rejoin → the primary branch stays on
the hub axis, the short optional branch sits immediately to its right,
and the merge returns to the original axis;
- several regions in sequence — two tables, a star followed by a table —
compose cleanly (each expansion makes its own room).
- **Large mesh processes** (many independent flows, lots of error handling)
→ the graph is split into (1) the **business flow**, laid out as a clean
layered top-to-bottom spine with edge-crossings minimised, (2) **dedicated
error clusters**, pinned locally beside their single owner, (3) genuinely
**shared error clusters**, placed on a clean right rail using their existing
collapse/expand state, and (4)
unreachable historical components, packed into a separate zone below the
active Start flow. A high error-node percentage alone does not select this
strategy; ownership topology does.
- **Recovery lanes** — an `err_node_id` target is not automatically terminal
error handling. If it enters a substantial compensating pipeline or rejoins
the active flow, that pipeline is anchored beside its owner/merge as business
logic while retaining its current mode. Callback entrypoints are treated like Start
roots; a component goes to the archive zone only when it has no attachment
to the active graph in either direction.
Both strategies guarantee: **no node overlaps**, top-to-bottom flow with
Start at the top and the deepest success Final sunk to the bottom of the active
flow (early success exits remain local), every node's existing collapse/expand
state preserved, and the diagram re-centred on the origin so it sits in the
middle of the canvas instead of drifting off one edge.
Note what that last point is *not*: there is no hard ±10000 clamp. The vertical
step does shrink for deep processes, but it has a floor, so a very deep process
(roughly 125+ layers) legitimately extends past ±10000. That is fine — the node
schema allows ±100000 precisely because real processes reach about ±25500.
**Example** — a typical result on a freshly built process:
```
strategy: waterfall (21 nodes, 4 flow(s), 5% error-handling nodes) density=medium engine=recovery-v6-preserve-modes
nodes=21 width=1000px height=4070px overlaps=0 collapsed=0
readability: estimated-crossings=0 max-dedicated-error-span=376px long-dedicated-errors=0
edges: max-span=420px p95-span=310px long=0 upward=0
layout applied: 042_payment.conv.json (21 nodes, 21 moved)
Next: lint-process, then push-process.
```
`overlaps=0` is the number to check; anything else means a bug worth reporting.
Full re-layout is idempotent: running it again over its own output must preserve
the same coordinates. Every input `extra.modeForm` must be identical after the
run; `collapsed=0` and `mode-passes=1` are mandatory. The engine revision makes
stale runtime tests visible.
## Honest limits
Some graphs cannot be made beautiful because the *graph itself* is tangled — a
node called from a dozen places is an unavoidable fan of edges no layout can
remove. When a process is this big and knotty, the real fix is to **split it
into smaller, repeatable sub-processes**; the layout only makes an unavoidable
monster as readable as it can be, never magically simple.
## Verifying a change to the engine
The engine's test suite lives with the server code
(`plugins/corezoid/mcp-server/layout_*_test.go` — synthetic topologies:
chains, stars, loops, fractals, tables, and an error-heavy process):
```bash
cd "${CLAUDE_PLUGIN_ROOT}/mcp-server" && go test -run 'TestLayout' ./...
```
It asserts the invariants that make a layout clean: all nodes placed, **zero
overlaps**, deterministic output (so adding a node re-flows rather than piles
up), coordinates within canvas, top-to-bottom flow, correct strategy routing,
table/star/diamond region geometry, dedicated-vs-shared error ownership,
detached component zoning, local early exits, and golden coordinate files that
freeze every fixture against unintended churn.
© Corezoid · MIT · corezoid/corezoid-ai-plugin