Mellos Mapping

The working loop

1. Resume first, then fill gaps. Read existing pages and the matching effort's records. For a new effort, declare its intended design with mmap_declare: title, layer bands (rank 0 = most primitive, at the bottom), every planned node, and the edges. Everything starts planned — the user can veto the ghost design before any code exists.
2. Put the map on screen — that is YOUR job, not the user's. Use the desktop document flow above when applicable. For terminal hosts, at the first map decision in a session, ensure the requested placement with mmap_open even if a project viewer is already reported. Use no page for this initial placement check so an existing pane pinned by the user keeps its view; subsequent opens name the effort's page as usual. A project-wide viewer report alone does not prove this session has its right split. Every declare, update, remove and view answers with a pane: line telling you who is actually looking. Read it and act on it:
   • pane: CLOSED — nobody is. Call mmap_open {page: "<slug>"} at once, without asking first: a recorded mapping policy IS the user's standing consent to see the map. Confirm it is live only after the tool succeeds. If automatic opening already failed, relay the reason and copyable command once; retry only after the environment changes or the user asks.
   • pane: open on this page — they are watching this land. Carry on.
   • pane: open on <other>, auto-follow on — the pane follows the page last written, so your next write brings the audience along by itself.
   • pane: open on <other>, auto-follow OFF — the user pinned that page by hand. Your changes are real and NOT on their screen: say so, and retarget with mmap_open {page} only if they want it moved. A pane with follow off is a deliberate choice — don't fight it. Default open means a right split beside THIS conversation. A live viewer in another window is not proof of that placement. If opening reports that the source tab is inactive or Windows refused focus, relay it and ask the user to activate this conversation's terminal tab before retrying. Do not retry with window: true unless the user chose a separate window. Always pass the page your effort lives on. Without it a fresh pane opens on whichever page was written last, which after a gap is rarely the one under discussion — and declaring on a named page makes YOU responsible for the audience, rather than telling the user which tab to click. mmap_open {window: true} puts the map in its own window instead of splitting the conversation's, for users who want it separate. It never CLOSES a pane: that is the user's (the q key, or mmap in any terminal of the project, which toggles) — so a pane that vanishes is them, not a fault. On Linux/macOS, the same tool automatically opens tmux, using the inherited session/pane or the single attached session when TMUX is missing. Multiple attached sessions require MELLOS_MAPPING_TMUX_TARGET; custom sockets use MELLOS_MAPPING_TMUX_SOCKET in the MCP server environment. window: true requests a new tmux window. Do not guess between attached sessions. Under omp (Oh My Pi) nothing about this changes: the same tool runs the same launcher, splitting the Windows Terminal window hosting the omp session (tmux split on Linux/macOS) and reusing the pane already bound to it. omp has no pane of its own inside its TUI, so the split IS the map's home there — never claim a map is visible when the tool reported it could not open one. Where the tool cannot help — a client without it, or a machine without Windows Terminal or an attached tmux session — relay the launcher's complete quoted watcher command for a visible terminal, or use: node <plugin root>/dist/watch.mjs --file <project>/.mellos/map.json --page <slug> in a second terminal or tmux split (this skill file lives under <plugin root>/skills/mellos-mapping/). mmap_view shows the map inline anywhere.
3. Work bottom-up. Set a node in-progress before implementing it, and prefer finishing its lower dependencies first. Independent same-band siblings need no artificial queue — building them together (several spinners at once) is honest reporting, not a violation. If you deliberately build above an unfinished dependency, say why in conversation.
4. done requires evidence. Mark done only when verification actually passed, with what passed in evidence (e.g. vitest: 23 passed). No evidence, no done.
5. Regression spreads upward. If later work breaks a done node, set it regressed (breakage in evidence) BEFORE fixing. Then walk every node that uses it, directly or transitively: their done was proven against a foundation that no longer holds. Default them to regressed too; keep one green only with a stated reason (its own verification re-ran green, or it never touches the broken behavior). After the fix, restore each node only as its own verification passes again.
6. Revise the ghost honestly. The design is a hypothesis, and everything it declared can be revised. When a node splits, a primitive appears, or a band was wrong, fix the map in the same turn you change the plan: mmap_update moves a node to another band (layer), renames or re-ranks a band, relabels a group or a lane, and clears any optional field with null (never an empty string); it also edits title, kind and edge labels. mmap_declare grows the map; mmap_remove drops edges, nodes, groups, lanes and bands you have emptied. A map that no longer matches your intent is the one failure mode this system cannot survive.
7. Clean up a finished effort. Pages accumulate — one effort, one page — so when an effort is over and its map has served its purpose, offer to remove it: mmap_remove {pages: ["slug"]} deletes those page files for good. Only with the user behind it, never on your own initiative, and never a page someone might still be reading. (In the pane the user can do it themselves: x twice, or the × on the active tab.)

Modeling guidance

• Nodes are units of buildable, verifiable work (a module, a contract, a renderer) — not tasks like "write tests" and not files.
• Declare groups when one band grows crowded (groups in mmap_declare, group on members): labeled subsystems within that band, worth declaring once a single band holds roughly five or more nodes — the far zoom renders groups, and a crowded band without them degrades into anonymous glyphs. A group must be a strict subset of its band: a group holding the whole band merely renames it. A map spread thin across many bands needs no groups at all. Group status is derived from members — never invent it.
• Every node carries detail: one to three sentences on responsibility, contract, and the key decision. Update it when the design shifts — a stale detail is a small lie on the map.
• Push state to the top. Lower layers take values in, give values out; mutable state concentrates in the topmost orchestrator, which owns it explicitly and hands it down as parameters. Stateless layers are cheap to maintain: testable with values alone, rewritable without ceremony. A lower node whose detail must describe state it keeps between calls is a design smell — restructure before building on it.
• Layers encode dependency direction, nothing else. If A needs sibling B, either B is really lower-layer or A and B are one node — restructure rather than force an edge.
• Edges mean "uses" — the upper node genuinely calls, composes, or reads the lower one. No aspirational edges.
• Ids are stable kebab-case slugs; labels are short display names (CJK fine), renameable without breaking edges.
• One effort = one page. A genuinely separate effort (parallel session, unrelated subsystem) gets its own page via the page parameter — don't mix efforts or overwrite a finished map.
• Sub-maps: dive, don't cram. When a node's internals genuinely deserve their own picture, declare a separate page and set submap: <page-slug> on the node — the pane badges it ⊞; double-click dives in, Backspace climbs back. Your judgment: most nodes need no sub-map; create one only when the child map would carry a handful of nodes of its own.

Diagram kinds

The default kind is dev — the living progress ledger described above. mmap_declare also accepts documentation kinds, rendered neutrally (no ghosts, no spinners, no progress counts). Use them when the user asks for a picture of a system rather than a picture of work; one diagram = one page.

• architecture — layered components; also module dependencies, call graphs.
• dataflow — pipeline stages as layers, sources at rank 0; label edges with the data that flows.
• behavior-tree — leaves (actions) at rank 0, root on top; node kind selector | sequence | parallel | decorator | condition | action renders as a glyph. Also fits mind maps and WBS.
• sequence — the classic call/return diagram. rank = time step, rank 0 = earliest; the pane draws sequence pages TOP-DOWN (earliest step on top, under the participant headers). Declare participants as lanes; every call AND every return is its own event node in the ACTING participant's lane, so a round trip zigzags into the callee's lane and back out. Label each edge with the message.
• State machines are out of scope: transitions cycle, and edges here only point downward. Say so rather than forcing one in.

Edge labels and node kinds work on dev maps too.

Standing state

At any moment the pane should answer at a glance: what is designed, what is built and verified, what is in progress RIGHT NOW, and whether any foundation is cracked. If a glance would mislead on any of these, fix the map first.