guangminju/mellos-mapping/mellos-mapping

Mellos Mapping — the map discipline

Eight MCP tools (mmap_declare, mmap_update, mmap_remove, mmap_view, mmap_setup, mmap_open, mmap_read, mmap_batch) maintain a Mellos map: a layered dependency map of the system under construction, persisted in .mellos/map.json (default page) plus .mellos/pages/<slug>.json (named pages) and rendered live in a terminal split pane, a desktop Markdown file panel, or an interactive local web viewer beside the conversation. To learn whether a map already exists — and under which page slugs — call mmap_view: every response ends with a pages: line naming the pages this project has and which one you are looking at. Never probe the default file to decide: it is absent whenever all work lives on named pages.

With current servers, prefer mmap_read {resource: "pages"}: it returns page summaries, saved context and revisions. A new conversation or compaction is not a new effort. Resume the matching page, read relevant nodes by ID/filter and request detail/evidence only when needed. Use the IDs returned by mmap_read, not display labels. Declare only missing structure. Keep context.summary and context.next current so another conversation can continue without rebuilding. Pass expectedRevision on writes; reread on CONFLICT. mmap_batch applies mixed changes atomically to one page. mmap_read changes checks linked source hashes; record sources[].sha256 only after verification. Older servers can fall back to mmap_view discovery and the saved JSON for precise IDs.

The map is a ledger, not a judge: the tools only refuse structural corruption; when to declare, start, or complete nodes is YOUR discipline, spelled out here. Report honestly — an unflattering map is doing its job.

When to open a map

The USER chooses how eager mapping is — once, for themselves, not once per project. Where the host runs a session adapter, the answer is already in this session's context, stated before the conversation begins, so there is nothing to probe: Claude Code runs the plugin's SessionStart hook, and omp (Oh My Pi) and pi load the same paragraph through the plugin's host adapters (dist/omp-extension.mjs and dist/pi-extension.mjs, declared in package.json#omp.extensions and package.json#pi.extensions, read from the same store). In hosts without one (Codex CLI, a bare MCP client) call mmap_setup with no arguments before the first map decision of the session; the reply names both scopes and which one governs.

• always — map every structured task: workflows, designs, architecture,

technical dependencies. Small effort, small map — but a map.

• complex — map only medium or complex tasks: several interacting modules,

a new subsystem, layered refactoring — roughly an hour of work or more. Skip trivial edits; a map of one node is noise. When unsure, ask.

• on-request — open a map only when the user explicitly asks.

Under always and complex, the recorded policy is STANDING CONSENT: on a task it covers, declare the ghost design and open the pane yourself, without asking first. Re-asking for permission the user has already given is the failure mode this policy exists to remove.

If the policy is not set anywhere, ask the USER to choose — present the three options, never pick for them — then persist the answer with mmap_setup {policy, scope: "user"}. That is asked ONCE EVER: the choice is saved in the user's own .mellos/config.json and applies to every project. A project that genuinely needs to differ takes mmap_setup {policy, scope: "project"}, which overrides the user choice there; /mmap setup reruns the question for either scope. Until they answer, act as complex. Two things always outrank the policy: an explicit user request for a map wins under any policy, and a map that is already open keeps getting honest updates whatever the policy says.

Caught mid-implementation without a map on work that deserves one? Stop and declare it with honest statuses (written-but-unverified is in-progress, not done). If the mmap tools are missing from the session, explain that mapping is unavailable and continue the user's implementation. In Codex, look for tools by their mmap_* suffix: a host may add a server namespace. Installing or repairing the plugin includes running node <plugin root>/scripts/codex-register.mjs, then starting a new conversation. Existing installation authorization covers this registration; ordinary implementation work alone does not authorize changing host config. The plugin root is two directories above this skill's directory. See <plugin root>/docs/codex.md for Codex packaging and installation details.

Automatic desktop terminal in a browser

In ChatGPT desktop Codex mode, prefer mmap_open {surface: "web-terminal", page} when no other surface was chosen. Pass its hostOpen object to open_in_codex in the current conversation: right placement, browser target, returned URL. The page starts the existing mmap terminal automatically, with independent font size. No manual paste or Computer Use is needed. An older schema can use node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug>. Respect manually pinned pages and report queued opening honestly. Native Claude Code terminal placement remains the default for terminal hosts.

Desktop document panel

When the current host exposes a file side panel (for example Codex desktop's open_in_codex) and the user requests a document or no browser panel is available, use the Markdown surface. This replaces the terminal-placement instructions in step 2 below.

1. Call mmap_open {surface: "markdown", page: "<effort-slug>"}. This generates

local Markdown with a colored SVG map and enables automatic preview updates after successful map mutations in this project. It starts no terminal or web server. Keep the JSON maps as the source; generated documents are not inputs.

1. Pass the returned absolute markdown: path to the host's file-opening tool,

in the current conversation's right panel. With open_in_codex, use placement: "right" and target: {type: "file", path: "<returned path>"}. Do not set another conversation id unless the user asked for that placement.

1. A generated file is not evidence that the user sees it. Report queued

opening as queued, and do not claim a live viewer or automatic UI refresh. If the preview stays stale, regenerate with mmap_open and reopen the same file. Avoid reopening after every write when the viewer already refreshes.

1. preview: STALE means the map mutation succeeded but export failed. Fix

the export problem and regenerate; do not repeat the map mutation. A terminal pane: report does not describe the desktop file panel.

If this conversation still has the previous MCP schema after a local upgrade, use node "<plugin root>/dist/preview.mjs" "<project directory>" --page <slug> to generate the same files. Until a new conversation loads the updated server, rerun this command after map writes. Use the actual installed runtime path from docs/codex.md when the skill cache differs from the runtime install.

The document contains a static vector image, module details, evidence and links to existing child pages. Image nodes do not support dragging, hover details, animated spinners or double-click navigation. Desktop rendering and refresh behavior belong to the host, not the plugin.

Optional interactive web panel

Keep the user's chosen surface. Markdown/SVG remains available with its existing workflow; adding the web viewer never disables or replaces it. When the user asks for a web map or live interaction, call mmap_open {surface: "web", page: "<effort-slug>"}. Pass the returned web: URL to the host's browser-opening tool. In Codex use open_in_codex with placement: "right" and target: {type: "browser", url: "<returned URL>"} in the current conversation. Report queued opening honestly; a running local service does not prove visibility.

The viewer reads the same project maps and refreshes automatically, including writes from older MCP clients. It supports zoom/pan, hover and pinned details, dependency highlighting, search/status filters, page selection, child-map navigation, groups, lanes, light/dark themes and confirmed page deletion. Manual page selection disables auto-follow; do not override a pinned page. Web page deletion also refreshes enabled Markdown previews.

If this conversation has an older schema, run node "<plugin root>/dist/web.mjs" "<project directory>" --page <slug> and open the JSON response's url. It reuses a local service for that project; no public hosting or dependency download is required. Close an unused service with the same command plus --stop instead of --page <slug>. It also exits after five minutes without browser requests. Reopen with the tool/CLI after that, or after a plugin update. A web: configured report describes a runtime record, not a confirmed open desktop panel. See docs/codex.md for transport and lifecycle details.

The working loop