Deprecate the terminal (Mermaid→ASCII) surface; make termchart viewer-first#230
Merged
Conversation
…-first The agent-compat journey tests showed coding agents anchor on Mermaid types (flowchart/erDiagram) for viewer tasks because termchart presents as a Mermaid-terminal tool — the 'termchart' terminal skill mis-activates and the CLI --help tagline leads with 'Mermaid → ASCII for terminals'. Refocus on the viewer: - Remove the agent-facing terminal surface: delete the 'termchart' terminal skill and the /termchart:diagram command (the bits that mis-activate). Demote 'mermaid' to a last-resort fallback in the diagram-recipes decision guide. - Reframe viewer-first: plugin.json + marketplace.json (drop the 'terminal fallback' line, reorder keywords, bump plugin 0.14.0 -> 0.15.0); README/AGENTS/cli README lead with the viewer and mark terminal sections deprecated. - Soft-deprecate the CLI render (kept working for backward compat): viewer-first --help tagline, render/lint + flags moved under 'Deprecated', and a one-line stderr deprecation notice on the render/lint path (stdout output unchanged). - Core unchanged: 'mermaid' stays a valid viewer push type (mermaidErrors/validate). Tests: cli 257 pass; render/lint still work + emit the notice; push --type mermaid still accepted; plugin exposes only diagram-recipes/inbox-watch/scheduled-boards + diagram-remote/schedule-board.
… + 'flow is JSON not mermaid') Agent-compat eval showed agents pick the right --type but then bail to mermaid because the JSON shapes live in separate files (flow.md etc.) they don't open, and Claude has a strong 'flowchart = graph TB' prior. Put a 'Start here' block at the top of the skill with the exact copy-pasteable JSON for flow/component/vegalite/panes and an explicit 'content is JSON, never Mermaid graph syntax' rule. With this (and the guide reaching the agent), Claude haiku/sonnet + Gemini one-shot 5/5 journey activation with no error-correction hint.
…agram-recipes Eval finding: agents pick skills by NAME, and tasks say 'termchart' — so Claude Code never auto-activated the 'diagram-recipes' skill from a scenario prompt (skill-only, no context files) and flew blind (1/5). A lean skill NAMED 'termchart' (the name that matches user intent) that carries the pick-type + exact-JSON one-shot block and points to diagram-recipes for depth fixes it WITHOUT renaming/removing diagram-recipes or touching any AGENTS.md/CLAUDE.md. Measured skill-only via npx skills, no context files: Claude Haiku 5/5 (activates the skill on all 5), Gemini 5/5, Claude Sonnet passing. Replaces the now-deleted terminal 'termchart' skill; diagram-recipes stays the deep library.
ivanmkc
pushed a commit
that referenced
this pull request
Jul 5, 2026
…terminal-render section (#230)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The agent-compat journey tests found coding agents (Claude/Gemini) misuse termchart because it
presents as a Mermaid-terminal tool: given "show this on the viewer", Claude activates the
termchartterminal skill ("render Mermaid → ASCII") and anchors on Mermaid types(
flowchart,erDiagram) — the wrong vocabulary for a rich viewer push (journey activationstayed ~1/5). The Mermaid framing pervades termchart (the CLI
--helptagline is literally"deterministic Mermaid → ASCII/Unicode for terminals"). Decision: deprecate the terminal
surface and focus on the viewer.
What
Remove the agent-facing terminal surface (the parts that mis-activate)
termchartterminal skill (plugin/skills/termchart/) and the/termchart:diagramcommand (
plugin/commands/diagram.md).mermaidto a last-resort fallback in thediagram-recipesdecision guide; sequencediagrams now recommend rich
flow(manual lifelines) with mermaid as a noted fallback.Reframe viewer-first
plugin.json+marketplace.json: drop the "Mermaid→ASCII is the terminal fallback" line,reorder keywords viewer-first, bump plugin 0.14.0 → 0.15.0.
README.md,AGENTS.md,packages/cli/README.md: lead with the viewer; terminal sectionsmarked deprecated (kept as reference).
Soft-deprecate the CLI render (kept working — no breaking change)
cli.ts: viewer-first--helptagline;termchart <file>/lint+ render flags moved undera "Deprecated" heading; a one-line stderr deprecation notice on the render/lint path
(stdout render output unchanged).
render.ts/lint.ts+ tests untouched.packages/cli/package.json: softened description + viewer-first keywords (no npm version bump).Core unchanged —
mermaidstays a valid viewer push type (rendered in-browser); this onlydeprecates the terminal ASCII renderer.
Verification
termchart --help→ "push rich diagrams to a live viewer"; render/lint under "Deprecated".printf 'graph LR\n A-->B' | termchart→ still renders and prints the deprecation noticeto stderr; stdout output unchanged.
push --type mermaidstill accepted.diagram-recipes/inbox-watch/scheduled-boardsskills +/termchart:diagram-remote//termchart:schedule-boardcommands.Follow-up (separate): re-run the agent-compat journey suite with the terminal skill gone to
confirm agents now activate
diagram-recipesand journey activation rises.