feat: rich directive components for structured visual blocks

apps/skills/plannotator-setup-goal/SKILL.md

@@ -139,12 +139,27 @@ If the user edits or removes facts in the UI, apply that result directly. If the
 
 Explore the codebase. Discover and validate implementation paths toward each accepted fact. Treat facts with `automatedVerification: true` as requiring concrete automated checks unless you document a blocker. Trace through code, identify files and systems involved, surface risks and unknowns. Refine until you have a confident order of operations.
 
-Write `goals/<slug>/plan.md`:
+Write `goals/<slug>/plan.md` using Plannotator's rich directive syntax for structured sections:
 
-- Solution approach (brief)
-- Ordered steps with the files/systems each touches
-- Verification for each step (concrete commands or checks)
-- Risks or open questions worth flagging
+**Available directives** (rendered as themed visual components in the reviewer):
+
+- `:::stats` — key numbers. Each line: `value | label` or `value | label | color` (success/destructive/warning/primary).
+- `:::milestone [status]` — timeline phase. Status: `done`, `warn`, `blocked`, or omitted. `###` heading = title. Backtick lines = tag chips. Consecutive milestones render as a connected timeline.
+- `:::risks` — risk grid. Each line: `severity | name | mitigation` (HIGH/MED/LOW).
+- `:::cols` — multi-column layout. Split with `:::col` markers. Use `:::cols N` for explicit count.
+- `:::diagram [caption]` — wraps mermaid/graphviz code fences or inline SVG in a captioned panel.
+- `:::note`, `:::tip`, `:::warning`, `:::caution`, `:::important` — callouts.
+
+**Plan structure:**
+
+- `:::stats` strip with scope numbers (files touched, facts covered, steps)
+- `:::milestone` entries for ordered implementation steps, each listing files/systems touched
+- Verification for each step (concrete commands or checks, inside the milestone body or as a task list)
+- `:::risks` grid for anything worth flagging
+- `:::cols` for side-by-side comparisons (before/after, option A vs B) when useful
+- `:::diagram` for architecture or data flow when 3+ components interact
+
+Keep it scannable. One idea per section. Skip directives that don't serve the content — plain prose, headings, code fences, and task lists are always fine.
 
 Gate the plan with Plannotator:
 

apps/skills/plannotator-visual-explainer/SKILL.md

@@ -2,62 +2,124 @@
 name: plannotator-visual-explainer
 disable-model-invocation: true
 description: >
-  Generate self-contained HTML visualizations with Plannotator theming. Use for implementation
-  plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual
-  explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive
-  approach; all other visual content delegates to nicobailon/visual-explainer.
+  Generate visual plans, PR explainers, and technical documents with Plannotator.
+  Use rich directives (:::stats, :::milestone, :::risks, :::cols, :::diagram) for
+  structured layouts in markdown. Fall back to HTML only for PR diffs (Pierre CDN),
+  UI mockups, or complex SVG positioning that directives don't cover.
 ---
 
 # Plannotator Visual Explainer
 
-Three paths depending on content type. Each has its own references and structure.
-
 ## Route by content type
 
-**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.
+**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Uses directives for structure. No HTML references needed.
+
+**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/pr-components.md` for Pierre diff rendering. Directives for summary sections; HTML for diff hunks.
 
-**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.
+**Everything else** (data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.
 
-**Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.
+**HTML escape hatch** → Only when directives don't cover the layout (custom SVG positioning, UI mockups, bespoke grids). Read `references/design-system.md` + `references/svg-patterns.md` at that point, not before.
 
 ## Delivery
 
 Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.
 
-**Plans/proposals** (user should approve/deny):
+**Markdown with directives** (default):
 ```bash
-plannotator annotate <file> --render-html --gate
+plannotator annotate <file.md>
 ```
 
-**Everything else** (informational):
+**Plans/proposals with gate** (user should approve/deny):
+```bash
+plannotator annotate <file.md> --gate
+```
+
+**HTML escape hatch** (only when directives don't suffice):
 ```bash
 plannotator annotate <file> --render-html
 ```
 
 ---
 
-## Plan path
+## Directive path
 
-For implementation plans, design docs, feature specs, migration guides, and proposals.
+Rich directives render structured visual components directly in markdown — no HTML, no CSS tokens, no iframe. They inherit the active Plannotator theme automatically.
 
-**Before generating, read:**
-1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
-2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow
+Available directives:
+
+**`:::stats`** — Summary strip of stat cards
+```
+:::stats
+4 | MRs
+2 | Approved | success
+2 | Blocked | destructive
+:::
+```
+Each line: `value | label` or `value | label | color`. Colors: `success`, `destructive`, `warning`, `primary`.
+
+**`:::milestone [status]`** — Timeline entry
+```
+:::milestone done
+### Deploy to staging
+All checks green.
+`backend-api`
+:::
+```
+Status on opening line: `done` (green), `warn` (yellow), `blocked` (red), or omitted (default). `###` heading = title. Backtick-only lines = tag chips. Consecutive milestones render as a connected vertical timeline.
+
+**`:::risks`** — Risk grid with severity badges
+```
+:::risks
+HIGH | Merge conflicts | Rebase before merging
+MED | Stale pipeline | Retrigger CI
+LOW | Reviewer OOO | Not blocking
+:::
+```
+Each line: `severity | name | mitigation`. HIGH/MED/LOW map to badge colors.
+
+**`:::cols`** — Multi-column layout
+```
+:::cols
+:::col
+Left column content.
+:::col
+Right column content.
+:::
+```
+N columns auto-detected from `:::col` count. Use `:::cols 3` for explicit count. Collapses to single column on narrow viewports.
+
+**`:::diagram [caption]`** — Diagram panel
+````
+:::diagram Request flow through the gateway
+```mermaid
+graph LR
+  A[Browser] --> B[Gateway]
+  B --> C[API]
+```
+:::
+````
+Wraps code fences (mermaid, graphviz) or inline `<svg>` in a bordered, captioned panel. Inline SVG inherits theme CSS variables — use `var(--primary)` etc. instead of hardcoded colors.
+
+---
+
+## Plan path
+
+For implementation plans, design docs, feature specs, migration guides, and proposals. Uses directives — no HTML references to read.
 
 **Document structure (in order, pick what fits):**
 
-1. **Header** — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)
-2. **Summary strip** — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)
-3. **Milestones / timeline** — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.
-4. **Architecture / data flow** — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.
-5. **Mockups** — build UI mockups in HTML/CSS directly, not as descriptions
-6. **Key code** — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.
-7. **Risks & mitigations** — table with severity badges (HIGH/MED/LOW)
-8. **Open questions** — callout cards with decision owner ("Decide with: backend team")
+1. **Header** — `#` title, then a `>` blockquote with the original brief
+2. **Summary strip** — `:::stats` with 3-5 key numbers at a glance
+3. **Milestones / timeline** — consecutive `:::milestone` blocks showing phases. No time estimates — phases show sequence and dependencies, not duration.
+4. **Architecture / data flow** — `:::diagram` wrapping mermaid or inline SVG. Use for 3+ interacting components.
+5. **Side-by-side comparison** — `:::cols` for before/after, option A vs B, or any two-pane layout
+6. **Key code** — fenced code blocks. Only architecturally significant interfaces/schemas.
+7. **Risks & mitigations** — `:::risks` with severity and mitigation per row
+8. **Open questions** — `:::note` or `:::warning` callouts with decision owner
 
 Not every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.
 
-**Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.
+**Adapt to the task:** Backend → lead with data flow diagram. Frontend → lead with columns (mockup vs spec). Refactoring → lead with before/after columns. Infrastructure → lead with architecture diagram.
 
 **Quality bar:** The plan answers "what, why, and how" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.
 
@@ -67,22 +129,17 @@ Not every plan needs every section. Skip what doesn't serve the content. Never i
 
 For PR walkthroughs, diff reviews, code change explainers, and reviewer guides.
 
-**Before generating, read:**
-1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
-2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels
+**Before generating, read:** `references/pr-components.md` — Pierre diff CDN, file cards, before/after panels. Use directives for summary sections (stats, risks, cols); HTML only for diff hunks that need Pierre syntax highlighting.
 
 **Document structure (in order, pick what fits):**
 
-1. **Header** — PR title, meta strip (file count, +/- lines, branch, author)
-2. **TL;DR** — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.
-3. **Why** — motivation and before/after comparison (two-column grid)
-4. **File tour** — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a "why" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.
-5. **Risk map** — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).
-6. **Where to focus** — numbered callout cards. Each names a file/function and describes the concern.
-7. **Test plan** — checkbox-style verification checklist
-8. **Rollout** (if applicable) — phased deployment with feature flags
-
-Use Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.
+1. **Header** — PR title, `:::stats` meta strip (file count, +/- lines)
+2. **TL;DR** — `:::note` callout. 2-3 sentences.
+3. **Why** — `:::cols` with before/after comparison
+4. **File tour** — HTML file cards with Pierre diffs (this is the HTML escape hatch — directives can't render syntax-highlighted diffs)
+5. **Risk map** — `:::risks` showing which files need careful review
+6. **Where to focus** — numbered `:::warning` callouts per concern
+7. **Test plan** — checkbox task list (`- [ ]`)
 
 ---
 

apps/skills/plannotator-visual-explainer/references/design-system.md

@@ -1,5 +1,7 @@
 # Design System Reference
 
+> **Prefer rich directives** for stat strips, milestones, risk grids, column layouts, and diagram panels — they render as themed components directly in markdown without any CSS. See SKILL.md → [Directive path]. Use this design system reference only for HTML escape-hatch layouts (custom SVG positioning, PR diffs, UI mockups) or when you need component patterns not covered by directives.
+
 Plan documents use Plannotator's semantic theme tokens. This makes them theme-aware: standalone files render with bundled defaults; embedded in the Plannotator UI, they inherit whatever theme is active (30+ themes, light and dark variants).
 
 ## Standalone defaults

apps/skills/plannotator-visual-explainer/references/svg-patterns.md

@@ -2,6 +2,8 @@
 
 Building blocks for creating diagrams in implementation plans. All SVGs are inline — no external dependencies. Compose these patterns to build architecture diagrams, data flow visualizations, flowcharts, and charts.
 
+> **For simple diagrams**, use `:::diagram` directives — they wrap mermaid/graphviz code fences or inline `<svg>` in a captioned, themed panel without any HTML boilerplate. Use these SVG patterns only for complex architecture diagrams with precise positioning that need the full HTML escape hatch.
+
 All colors reference Plannotator theme tokens. In SVG, use the CSS custom property values directly via `style` attributes or the corresponding CSS classes.
 
 ## Table of Contents

apps/skills/plannotator-visual-explainer/references/theme-override.md

@@ -1,5 +1,7 @@
 # Plannotator Theme Override
 
+> **Rich directives inherit the active theme automatically** — no `:root` token block, no variable mapping, no override needed. This document is only relevant when generating standalone HTML files via `--render-html` that need to work outside the Plannotator UI.
+
 When visual-explainer's workflow says to pick a palette and font pairing, use these Plannotator tokens instead. Everything else — layout, structure, components, anti-slop rules — stays as visual-explainer prescribes.
 
 ## CSS Custom Properties