diff --git a/.amplifier/AGENTS.md b/.amplifier/AGENTS.md index e674748..13104d1 100644 --- a/.amplifier/AGENTS.md +++ b/.amplifier/AGENTS.md @@ -79,6 +79,53 @@ It almost always does. - **Voice profile:** .amplifier/VOICE.md - **Design specs:** .design/AESTHETIC-GUIDE.md, .design/specs/ +### Visualization Pass Is Mandatory Before Publishing + +Every post gets a visualization pass. The question is not "does this post need +a diagram?" The question is "what would illustrate this better than prose?" + +**For every section of a post, ask:** + +1. Am I reaching for a bullet list? A diagram might replace it entirely. + Bullet lists are a Claude default. Ken's real writing uses prose or visuals, + not lists. If you have 3+ items that relate spatially or sequentially, draw + them instead of listing them. + +2. Am I describing a system, flow, or architecture? Draw it. Code an inline + SVG following the diagram design spec, or use a `` component. + +3. Am I comparing two things? A two-column visual or a before/after diagram + beats a paragraph explaining the contrast. + +4. Am I showing a progression or timeline? A flow diagram with labeled steps + beats a numbered list every time. + +5. Would a concept illustration anchor the section? Even a simple symbolic + SVG (like the masterclass philosophy cards: hub-and-spoke, concentric + circles, crossed-out icons) gives the reader a visual anchor. + +**What the visualization pass produces:** +- A list of sections that would benefit from diagrams +- For each: what type (architecture, flow, comparison, concept) and a brief + description of what the SVG should show +- Generate the SVGs inline using the diagram design spec (when it exists) + or flag them for the author to describe + +**The rule:** If a post has 1000+ words and zero visuals, that's a warning. +Not every post needs diagrams, but every post should have been *considered* +for them. The consideration is mandatory. The diagrams are not. + +**How visuals are made:** +- Claude hand-codes SVGs using primitives (``, ``, ``, + ``) following the diagram design spec constraints +- Use the warm palette from DESIGN.md (paper background, brown-black ink, + terracotta accent) +- Diagrams break wider than prose (840px vs 720px) using the code-block + breakout pattern +- For interactive architecture graphs: DOT source + d3-graphviz runtime +- For concept art / visual targets: use image generation, then code SVG + approximations toward the target + ## Content Pipeline ``` @@ -94,7 +141,10 @@ Mechanical lint: ./scripts/lint-voice.sh LLM judge: voice-check (8 dimensions) | v -Fix failures, re-check +Visualization pass: what would illustrate this better than prose? + | + v +Fix failures, add diagrams, re-check | v Rebuild preview: rebuild /tmp/blog-dist, serve on :4321