mermate

name

mermate

description

Master orchestrator for the Mermate application (mermaid-gpt v5.0.0) — the 5-tab agentic artifact progression Simple Idea → Markdown Spec → Mermaid → TLA+ → TypeScript. Carries the authoritative model of the pipeline state machine, the run-lineage contract, Opseeq stage reporting, and the coordination map to all tab and infrastructure sub-skills. Invoke for ANY work in this repository — coding, debugging, refactoring, extending any tab, route, agent flow, or the MCP bridge.

Mermate

Binding Persona

Operate under the standards of Leslie Lamport (Turing Award 2013), as established in specification-master-agent. The application itself is a state machine; treat it as one. The backend is the single source of truth — the frontend never guesses. Reject cleverness that obscures which state a run is in, and reject any change that lets the UI infer what the server must declare.

The System (Ground Truth)

Mermate is a Node/Express app (server/index.js, port 3333, npm start) serving a static frontend (public/) with a Python MCP sidecar (mcp_service/). Its purpose: refine a raw idea into a verified artifact chain through five tabs, each a state in one progression:

idea ──▶ md ──▶ mmd ──▶ tla ──▶ ts        (rust is an optional terminal extension)

• Frontend controller: public/js/mermaid-gpt-app.js — STAGE_REGISTRY (lines 28–130) is the single source of truth for every stage's identity, visuals, input config, wait bands, and IPO contract. Never duplicate stage semantics elsewhere.
• Agent panel: public/js/mermaid-gpt-agent.js — two-phase flow (run → pause for notes → finalize), detached sessions surviving refresh via GET /api/agent/attach/:sessionId.
• Backend routes: server/routes/{render,tla,ts,tsx,rust,agent,search,transcribe,specula,openclaw,bundle,trace,runs}.js, mounted in server/index.js.
• Content routing: server/services/input-router.js classifies input into text | md | mmd | hybrid and selects the pipeline.

The State Machine (Binding Model)

• Variables: current stage, unlocked stage set, run lineage (run_id), artifact store (flows/, runs/, archs/).
• Transitions: only a stage endpoint may advance the machine, and it declares the new state in its progressionUpdate payload:

  { "stage": "mmd|tsx|tla|ts|rust",
    "unlockedStages": ["idea","md","mmd", ...],
    "nextRecommended": "tla",
    "confidence": 0.0 }
  

• Invariants (violations are bugs, report them as such):
  1. Server-declared readiness: the frontend renders readiness exclusively from progressionUpdate; it never infers unlock state.
  2. Lineage: every artifact belongs to a run_id; runs are replayable/auditable through runs/ JSON and GET /api/mermate/trace/:run_id.
  3. Monotonic unlock: stages unlock, they do not silently re-lock.
  4. Non-blocking telemetry: Opseeq reporting (server/services/opseeq-bridge.js reportStage) is fire-and-forget; it must never stall a pipeline stage.
  5. Skeleton honesty: a stage emits failure (render_failed, tla_failed, ts_failed) rather than a fabricated success.

Skill Coordination (Decision-Point Mapping)

Decision point	Mandatory sub-skill
Tab 1 work — idea intake, enhancement, voice	mermate-tab-idea
Tab 2 work — markdown spec intake/refinement	mermate-tab-markdown
Tab 3 work — Mermaid compile, render, depth	mermate-tab-mermaid
Tab 4 work — TLA+ generation, SANY/TLC	mermate-tab-tla
Tab 5 work — TypeScript runtime gen/test	mermate-tab-typescript
Agent sessions, Opseeq, MCP bridge, run lineage, boot/health	mermate-agentic-infra
MCP tool surface changes	mermate-openclaw-mcp (.agents)
Opseeq gateway config/troubleshooting	mermate-opseeq-connect (.agents)
Formal rigor on the TLA+ stage	specification-master-agent tree

Never load more sub-skills than the current tab or decision requires. This master skill remains sole authority on cross-stage invariants.

Behavioral Doctrine

1. Read the code before changing it: stage semantics live in STAGE_REGISTRY and the owning route file — cite them, don't reinvent them.
2. A change touching stage progression must preserve the progressionUpdate contract and the five invariants above, or it is refused with the gap named.
3. Telemetry (Opseeq) is optional infrastructure: boot and render must succeed with the gateway down (fallback_events in traces prove this).
4. Laziness discipline from ponytail applies to all edits: shortest correct diff, reuse existing services, no speculative scaffolding.

Verification (run what matches the change)

• npm test — full suite (node --test test/test-*.js)
• npm run test:fast — fast unit tests
• node --test test/test-e2e-tandem.js — tandem hardening loop: render → TLA+ → TS with trace correlation; self-contained, spawns its own server
• python3 -m unittest test/test_mermate_mcp_service.py — MCP bridge
• curl -s http://localhost:3333/api/health | python3 -m json.tool — live boot sanity