Problem
Agents generating plans and explainers through Plannotator currently write 20-30KB of raw HTML with copy-pasted CSS tokens because the markdown renderer lacks structured visual components. The directive system (:::kind ... :::) already parses arbitrary kinds but only renders a generic Callout for all of them.
This causes token drift (agents regenerate CSS from memory), bloated output, annotation degradation (HTML uses iframe bridge), and theme disconnection (standalone HTML hardcodes light-theme tokens).
Proposal
Extend the directive system with 5 purpose-built React components so agents write concise markdown instead of verbose, inconsistent HTML:
:::stats — summary strip with stat cards (pipe-delimited: value | label | color):::milestone [status] — timeline entry with vertical connector (done/warn/blocked):::risks — risk grid with severity badges (HIGH | name | mitigation):::cols — multi-column layout with :::col children (responsive, N-column):::diagram [caption] — bordered panel for mermaid/graphviz or inline SVG
Parser change
Extend the directive regex to capture optional trailing args on the opening line (:::milestone done → directiveArgs='done'). Backwards compatible — existing directives route to Callout via the default case.
Theme integration
Components use Tailwind classes resolving through existing CSS variable bridge. No :root token declarations needed. Theme tokens flow from the theme-{name} class on <html>.
Annotation compatibility
Each component renders with data-block-id and data-block-type="directive". Existing web-highlighter selection works on all rendered text.
Skill updates
The plannotator-visual-explainer skill is updated to route plans through directives by default. HTML references (design-system.md, svg-patterns.md) are gated behind an explicit escape hatch — agents only read them when directives don't cover the layout. The plannotator-setup-goal skill's plan phase also gains directive awareness.
Implementation
PR: victor-software-house/plannotator#1 (forthcoming)
~780 lines across 15 files. All existing tests pass; 5 new parser tests added.
Problem
Agents generating plans and explainers through Plannotator currently write 20-30KB of raw HTML with copy-pasted CSS tokens because the markdown renderer lacks structured visual components. The directive system (
:::kind ... :::) already parses arbitrary kinds but only renders a generic Callout for all of them.This causes token drift (agents regenerate CSS from memory), bloated output, annotation degradation (HTML uses iframe bridge), and theme disconnection (standalone HTML hardcodes light-theme tokens).
Proposal
Extend the directive system with 5 purpose-built React components so agents write concise markdown instead of verbose, inconsistent HTML:
:::stats— summary strip with stat cards (pipe-delimited:value | label | color):::milestone [status]— timeline entry with vertical connector (done/warn/blocked):::risks— risk grid with severity badges (HIGH | name | mitigation):::cols— multi-column layout with:::colchildren (responsive, N-column):::diagram [caption]— bordered panel for mermaid/graphviz or inline SVGParser change
Extend the directive regex to capture optional trailing args on the opening line (
:::milestone done→directiveArgs='done'). Backwards compatible — existing directives route to Callout via the default case.Theme integration
Components use Tailwind classes resolving through existing CSS variable bridge. No
:roottoken declarations needed. Theme tokens flow from thetheme-{name}class on<html>.Annotation compatibility
Each component renders with
data-block-idanddata-block-type="directive". Existing web-highlighter selection works on all rendered text.Skill updates
The
plannotator-visual-explainerskill is updated to route plans through directives by default. HTML references (design-system.md,svg-patterns.md) are gated behind an explicit escape hatch — agents only read them when directives don't cover the layout. Theplannotator-setup-goalskill's plan phase also gains directive awareness.Implementation
PR: victor-software-house/plannotator#1 (forthcoming)
~780 lines across 15 files. All existing tests pass; 5 new parser tests added.