nereid

Collaborate in Nereid Mermaid sessions via MCP using AST-first, probe-refine workflows for sequence diagrams, flowcharts, xrefs, routes, and walkthroughs. Use when exploring or editing diagrams with a

SKILL.md

GitHub

Nereid MCP Collaboration

Collaborate on Mermaid-backed diagrams in a live, shared TUI/MCP session. Keep context small, edits structured, and attention explicit.

Collaboration Contract

Assume co-presence by default:

  • The user can see diagram updates in real time.
  • The user can see where the agent is focused.
  • The agent should steer attention visually, then speak briefly.

Drive collaboration with this state model:

  • attention_human_read: read the human cursor/attention in TUI.
  • attention_agent_read: read the agent spotlight object.
  • attention_agent_set: move the agent spotlight to one object.
  • attention_agent_clear: clear the agent spotlight.
  • follow_ai_read / follow_ai_set: read or toggle whether TUI follows agent spotlight.
  • selection_read / selection_update: shared working-set selection (multi-object).

Treat these as separate concerns:

  • Human attention: what the person is looking at.
  • Agent attention: what the agent wants to emphasize now.
  • Selection: short-term working set for batch reasoning/edits.
  • Follow-AI: whether the TUI camera/cursor tracks agent spotlight.

Core Principles

  • Treat AST as source of truth; rendered text and Mermaid text are projections.
  • Session files (nereid-session.meta.json, diagrams/*.mmd, walkthroughs/*.wt.json) are app-managed snapshots and can be rewritten frequently while Nereid runs.
  • Use canonical ObjectRef everywhere: d:<diagram_id>/<category...>/<object_id>. Supported category pairs are seq/participant, seq/message, seq/block, seq/section, flow/node, flow/edge, class/class, class/relation, er/entity, er/relationship, gantt/section, gantt/task, and gantt/lane.
  • Prefer small reads first (diagram_stat, diagram_get_slice, diagram_diff, walkthrough_diff).
  • Use typed query tools (seq_*, flow_*, xref_*, route_find) before large snapshots.
  • Gate edits with base_rev and keep ops minimal.
  • Record evidence as refs (xrefs and walkthrough nodes) so reasoning is resumable.
  • Keep dangling xrefs visible as TODO artifacts unless asked to clean them.

Diagram Kind Boundaries

Kind Mermaid header Canonical object categories Mutation path
Sequence sequenceDiagram seq/participant, seq/message, seq/block, seq/section structured seq_* ops or Mermaid replace
Flowchart flowchart / graph flow/node, flow/edge structured flow_* ops or Mermaid replace
Class classDiagram class/class, class/relation Mermaid replace
ER erDiagram er/entity, er/relationship Mermaid replace
Gantt gantt gantt/section, gantt/task, gantt/lane Mermaid replace

Creation, raw Mermaid reads, text rendering, xrefs, selection, and attention work for all five kinds. diagram_get_ast and object_read return kind-specific fields, including class members, typed ER cardinalities, and Gantt sections, starts, durations, and dependencies. Typed mutation ops and dedicated query helpers remain sequence/flow-specific, so edit class, ER, and Gantt diagrams with Mermaid replace. gantt/lane refs identify rendered time headers; prefer task or section refs for structural probing.

Execution Discipline

  • Use MCP tools as the only source of truth.
  • Do not inspect src/, tests/, docs/, or data/ to answer runtime collaboration questions.
  • Make the first relevant MCP call immediately after reading the user prompt.
  • Prefer direct MCP execution over schema/code exploration.
  • If payload shape is unclear, call the tool once and adapt from validation errors.
  • Use shell/file probing only when the user explicitly asks for file-level inspection or storage debugging.

Tool Groups

  • Diagram lifecycle and target: diagram_list, diagram_open, diagram_delete, diagram_current, diagram_create_from_mermaid
  • Diagram reads: diagram_stat, diagram_get_slice, diagram_diff, diagram_read, diagram_get_ast, diagram_render_text
  • Diagram mutation: diagram_propose_ops, diagram_apply_ops, diagram_replace_from_mermaid
  • Walkthrough lifecycle and target: walkthrough_list, walkthrough_open, walkthrough_current
  • Walkthrough reads: walkthrough_stat, walkthrough_diff, walkthrough_read, walkthrough_get_node, walkthrough_render_text
  • Walkthrough mutation: walkthrough_apply_ops
  • Collaboration state: attention_human_read, attention_agent_read, attention_agent_set, attention_agent_clear, follow_ai_read, follow_ai_set, selection_read, selection_update, view_read_state
  • Cross-diagram mapping: xref_list, xref_neighbors, xref_add, xref_remove
  • Object inspection: object_read
  • Query helpers (route): route_find
  • Query helpers (sequence): seq_messages, seq_search, seq_trace
  • Query helpers (flow): flow_reachable, flow_paths, flow_cycles, flow_unreachable, flow_dead_ends, flow_degrees

Default Operating Loop

  1. Resolve target:
    • diagram_current -> diagram_list -> diagram_open.
    • walkthrough_current -> walkthrough_list -> walkthrough_open.
    • if no diagram exists yet, bootstrap with diagram_create_from_mermaid.
  2. Read live collab state:
    • attention_human_read, attention_agent_read, follow_ai_read, selection_read.
  3. Probe local context:
    • diagram_stat, diagram_get_slice, then one or two typed queries.
  4. Steer visual attention:
    • attention_agent_set to the object currently being discussed.
    • keep chat short while attention marker carries micro-guidance.
  5. Propose and apply minimal edits:
    • diagram_propose_ops -> diagram_apply_ops.
    • walkthrough_apply_ops for walkthrough refinement.
  6. Refresh with deltas:
    • diagram_diff / walkthrough_diff (avoid full re-read unless needed).

Live Co-Presence Rules

  • Use spotlight-first communication: set attention_agent_set before explaining a local change.
  • Move spotlight when changing topic; clear it when complete.
  • Keep narration compact when user is actively watching the diagram.
  • Skip spotlight changes for quick query-only answers unless orientation is needed.
  • Use selection_update for temporary multi-object working sets, not as a focus proxy.
  • For create/switch-only requests, stop after diagram_create_from_mermaid (and optional attention_agent_set); avoid extra diagram_stat, diagram_render_text, or flow_* probes unless the user asks for inspection/debugging.

Tool Contracts (Input/Output)

diagram_create_from_mermaid

Input:

{
  "mermaid": "flowchart TD\n  A --> B",
  "diagram_id": "d-my-flow",
  "name": "My Flow",
  "make_active": true
}

Output:

{
  "diagram": {
    "diagram_id": "d-my-flow",
    "name": "My Flow",
    "kind": "flowchart",
    "rev": 0
  },
  "active_diagram_id": "d-my-flow"
}

diagram_delete

Input:

{
  "diagram_id": "d-my-flow"
}

Output:

{
  "deleted_diagram_id": "d-my-flow",
  "active_diagram_id": "d-next"
}

diagram_get_slice

Input:

{
  "diagram_id": "d-flow",
  "center_ref": "d:d-flow/flow/node/n:a",
  "radius": 1,
  "depth": 1,
  "filters": {
    "include_categories": ["flow/node", "flow/edge"],
    "exclude_categories": []
  }
}

Output:

{
  "objects": ["d:d-flow/flow/node/n:a", "d:d-flow/flow/node/n:b"],
  "edges": ["d:d-flow/flow/edge/e:ab"]
}

diagram_apply_ops

Input:

{
  "diagram_id": "d-seq",
  "base_rev": 3,
  "ops": []
}

Output:

{
  "new_rev": 4,
  "applied": 1,
  "delta": { "added": [], "removed": [], "updated": [] }
}

walkthrough_apply_ops

Input:

{
  "walkthrough_id": "w:1",
  "base_rev": 0,
  "ops": []
}

Output:

{
  "new_rev": 1,
  "applied": 1,
  "delta": { "added": [], "removed": [], "updated": [] }
}

object_read

Input:

{ "object_ref": "d:d-seq/seq/block/b:0000" }

Output:

{
  "objects": [
    {
      "object_ref": "d:d-seq/seq/block/b:0000",
      "object": {
        "type": "seq_block",
        "kind": "alt",
        "header": "guard",
        "section_ids": ["sec:0000:00", "sec:0000:01"],
        "child_block_ids": []
      }
    },
    {
      "object_ref": "d:d-seq/seq/section/sec:0000:00",
      "object": {
        "type": "seq_section",
        "kind": "main",
        "header": "ok",
        "message_ids": ["m:0000"]
      }
    }
  ],
  "context": {}
}

attention_human_read

Input:

{}

Output:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention_agent_read

Input:

{}

Output:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention_agent_set

Input:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize"
}

Output:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention_agent_clear

Input:

{}

Output:

{
  "cleared": 1
}

follow_ai_read

Input:

{}

Output:

{
  "enabled": true
}

follow_ai_set

Input:

{
  "enabled": true
}

Output:

{
  "enabled": true
}

selection_update

Input:

{
  "object_refs": [
    "d:d-auth-flow/flow/node/n:start",
    "d:d-auth-flow/flow/node/n:authorize"
  ],
  "mode": "replace"
}

Output:

{
  "applied": [
    "d:d-auth-flow/flow/node/n:authorize",
    "d:d-auth-flow/flow/node/n:start"
  ],
  "ignored": []
}

Probe-and-Refine on Charts

Use a shallow, typed exploration loop:

  1. Anchor on one object (attention_human_read or explicit object_ref).
  2. Pull local structure with diagram_get_slice.
  3. Ask one typed question (seq_*, flow_*, xref_*, route_find).
  4. Shift agent spotlight to next object if needed.
  5. Repeat until ambiguity is resolved.

Escalate to global reads (diagram_read, diagram_get_ast, diagram_render_text) only when local probes are insufficient.

Mutation Discipline

  • Use diagram_propose_ops before diagram_apply_ops for non-trivial edits.
  • Keep op batches minimal and scoped to one local intent.
  • Use stable IDs for all new objects.
  • Re-read diagram_stat or diagram_diff after apply to confirm resulting rev/state.

Sequence structure ops

Prefer structured ops over rewriting Mermaid when editing alt / opt / loop / par:

Op type Purpose
seq_add_block Create block + main section (kind: alt/opt/loop/par)
seq_update_block Patch block header
seq_remove_block Remove block tree; messages remain
seq_add_section Add else (under alt) or and (under par)
seq_update_section Patch section header
seq_remove_section Remove empty non-main section
seq_set_message_section Attach/move/detach message membership (section_id: null detaches)
seq_add_message Optional section_id to place message on create

Rules agents must follow:

  • Batch create block + sections + messages with contiguous order_key order in one diagram_apply_ops.
  • Messages in a section must be contiguous in global message order; empty sections are invalid.
  • Nested blocks need parent_block_id and must sit inside one parent section’s message range.
  • After structural edits, confirm with diagram_get_ast or object_read on seq/block / seq/section refs (and diagram_read for Mermaid with blocks).

Example batch (add alt/else with two messages):

{
  "diagram_id": "d-seq",
  "base_rev": 0,
  "ops": [
    {
      "type": "seq_add_block",
      "block_id": "b:cache",
      "kind": "alt",
      "header": "cache",
      "main_section_id": "sec:cache:main"
    },
    {
      "type": "seq_add_section",
      "section_id": "sec:cache:else",
      "block_id": "b:cache",
      "kind": "else",
      "header": "miss"
    },
    {
      "type": "seq_add_message",
      "message_id": "m:hit",
      "from_participant_id": "p:A",
      "to_participant_id": "p:B",
      "kind": "sync",
      "text": "hit",
      "order_key": 1000,
      "section_id": "sec:cache:main"
    },
    {
      "type": "seq_add_message",
      "message_id": "m:miss",
      "from_participant_id": "p:A",
      "to_participant_id": "p:B",
      "kind": "sync",
      "text": "miss",
      "order_key": 2000,
      "section_id": "sec:cache:else"
    }
  ]
}

Walkthrough and Evidence Artifacts

Build walkthroughs as resumable breadcrumbs:

  • Add concise nodes with evidence refs (refs).
  • Keep node titles short; put detail in body_md.
  • Link nodes incrementally as understanding grows.
  • Update walkthroughs after edits instead of re-deriving from scratch.

Use xrefs to preserve cross-diagram semantics:

  • xref_add for implementation/expansion links.
  • xref_list and xref_neighbors for map and traversal.
  • Surface dangling xrefs explicitly for follow-up.

Conflict Recovery

When mutation fails due to stale base_rev:

  1. call diagram_diff or walkthrough_diff from last known rev,
  2. rebase ops on current_rev,
  3. retry with updated base_rev.

If diff history window is exhausted, fetch a fresh snapshot (diagram_read or walkthrough_read) and resume delta-first flow.

Bulk Mermaid replace

Use diagram_replace_from_mermaid when a bulk rewrite is easier than structure ops:

{
  "diagram_id": "d-seq",
  "base_rev": 3,
  "mermaid": "sequenceDiagram\n  A->>B: Hello\n"
}

Behavior:

  • Kind must match the existing diagram (sequence stays sequence).
  • Stable ids are reconciled from the previous AST (messages by fingerprint, blocks/sections by structure fingerprint, participants by name, flow nodes/edges similarly).
  • Response includes identity.preserved / identity.dropped / identity.newly_allocated and dangling_xref_ids.
  • Prefer structure ops for local alt/else/loop edits; use replace for full-source rewrites that should keep identity when content fingerprints still match.
  • Renaming message text typically allocates a new message id and may dangle xrefs that pointed at the old id.

Reporting Discipline

Report only what the user needs:

  • include target (diagram_id/walkthrough_id) and revision movement (base_rev -> new_rev),
  • include concise deltas and key refs,
  • avoid full AST/text dumps unless requested,
  • in live sessions, avoid narrating every micro-step already visible in TUI.

MCP Playbook Companion

Use references/mcp-playbooks.md for extra payload templates. Keep this file as the primary protocol and behavior contract.