/RichFormat

name: RichFormat
metadata:
  short-description: "Draws assistant replies in the terminal with flow diagrams, charts, coloured labels, callouts, and diffs through a Claude Code plugin."
version: 1.0.5
evals:
  deterministic:
    - command: "cd skills/RichFormat && claude plugin test ."
      falsifier: "an engine test fails: a flow fence split across flushes is not held and then drawn as boxes, a VERIFY mark is not green or the closer lacks the LifeOS rule, the disabled option changes the display, compose adds the flow section in a headless session or omits it in an interactive one, or a table answer draws no framed grid"
    - command: "cd skills/RichFormat && claude plugin validate --json . && bun ./tests/hooked-events.check.ts"
      falsifier: "the manifest does not validate, or the mod hooks any event besides prompt.compose and classic.MessageDisplay"
description: The rich-answer rendering mod, a Claude Code function-hooks plugin that draws assistant replies in the terminal with boxed flow diagrams, bar charts, sparklines, trees and timelines, coloured section labels, insight and caution callout bars, red and green diffs, and green and red VERIFY marks, leaving the stored text untouched. USE WHEN rich format, RichFormat, flow diagram not drawn, chart not drawn, bar chart, sparkline, tree chart, timeline chart, diff not coloured, VERIFY marks plain, labels not coloured, turn off rich drawing, answer rendering, render mod, is the render mod loaded. NOT FOR the system prompt's marker rules (edit the Format Rules there), the status band, statusline or hook-fed lines (LifeOSHooks), or generated images and diagrams (Art).

RichFormat

**Contents:** Ideal State · Anti-criteria · Intent Routing · What it draws · The LifeOS rule · Tool contracts · Data & Config · Gotchas · Examples

A function-hooks plugin that makes assistant replies faster to read in the terminal. Claude Code loads it from this folder in every interactive session. It hooks two events and nothing else:

• `prompt.compose` adds one section to the system prompt that teaches the drawable conventions, in interactive terminal sessions only (Anti-criteria).
• `classic.MessageDisplay` receives each batch of finished lines while an answer streams and returns the text the terminal shows in their place, with ANSI colour. That text is the answer's first and only copy. A drawable fence is held until it closes, then drawn whole (`hooks/stream.ts`).

Ideal State

• Every construct in What it draws that parses is drawn, never left as plain markdown: a `flow` fence as boxed nodes, a `diff` fence as numbered red and green lines, a fully marked VERIFY run as green and red marks, and a label line in its colour (the engine and pure-logic suites hold each).
• The stored message never changes. The model, the transcript file and ctrl+o all see plain markdown.
• On any doubt the lines show as written: a fence that does not parse, a fence still open at the message's last flush, a thrown error, or the option switched off.
• Every answer prints exactly once, at any length, under the full statusline.

Anti-criteria

• The mod never hooks any event besides `prompt.compose` and `classic.MessageDisplay`; no `ui.render` hook on AssistantMessage comes back, even one that passes the answer straight through.
• A finished answer is never repainted; this mod shapes first draws only.
• The prompt section is never added outside an interactive terminal session, so iMessage bridges, `-p` runs, teammates and SDK sessions never learn a convention they cannot draw.
• A list is never split between two renderers: a 💡 line inside a list or table, a ✓ bullet outside VERIFY, a VERIFY run with any unmarked or nested bullet, and anything inside another code fence stay plain.
• A double-printed answer is never fixed by turning the statusline off.

Intent Routing

No intents: the plugin runs on its own. Reference files:

| File | Read when | |------|-----------| | `Setup.md` | first-time setup, or filling in the optional USER `Config.md` and `PREFERENCES.md` |

What it draws

| Written in the reply | Drawn as | |---|---| | A fenced `flow` block, one `a -> b -> c` chain per line | Rows of boxed nodes joined by `▶`, wrapped to the terminal width | | A fenced `bar` block of `label: value` lines | A horizontal bar chart, cyan bars, values as written (`hooks/charts.ts`) | | A fenced `spark` block, one series of numbers per line | A one-line trend with its min, max and last | | A fenced `tree` block holding an indented outline | A hierarchy drawn with `├─`, `│` and `└─` | | A fenced `timeline` block of `when: what` lines | Events on a vertical rail with a `●` per event | | A fenced `diff` block holding one valid unified-diff hunk | Old and new line numbers, removals red, additions green | | `🔧 CHANGE:`, `✅ VERIFY:`, `❓ OPEN:` label lines | Bold blue, green and yellow labels | | A standalone line starting with 💡 or ⚠️ | A cyan or amber bar before the line | | A VERIFY run whose bullets all start `- ✓` or `- ✗` | Green and red marks | | A markdown table (header, delimiter row, body), held until it ends | A rounded box grid: frame grey, header bold soft blue, numeric columns right-aligned, ✓ ✗ ⚠ cells toned, cell markdown escaped (`hooks/table.ts`) | | `#`/`##` and `###` headings, a lone `**Mini header**`, a 🎯 line | Bold accent blue, bold soft blue, bold soft blue, bold; markers removed (`hooks/enrich.ts`) | | `- ` items and `1. ` items | An accent `•` (nested: grey `◦`) and an accent number (yellow in OPEN), wrapped with a hanging indent | | `---` (or `* * *`), `> quote` | A grey `─` rule the content width; a grey `▎` bar | | A fenced `workflow` block holding one line, `wf_<id> <plain summary>` | That run's brief card from the bridge (below); the stored text stays the one summary line (`hooks/workflow.ts`) | | A `🗣️ Name:` closer line outside a code fence | The LifeOS rule on its own line just above it: `━━ ◆ LifeOS ━━━ <isa slug> <done>/<total> ━━`, name b