stream_weaver 0.3.0

data/docs/visual-skills/blog/blog-series-outline.md

@@ -0,0 +1,39 @@
+# Blog Series: StreamWeaver Visual Skills
+
+## Post 1: Token Efficiency — "From 30K Tokens to 3K"
+**Angle:** The design system belongs in the framework, not the conversation.
+- visual-explainer reads ~30K tokens of CSS patterns EVERY invocation → 0 with StreamWeaver
+- 80-85% reduction isn't incremental — it's architectural
+- **The Ruby angle:** Ruby's DSL capabilities make this natural. `mermaid "graph TD\n..."` vs generating 200 lines of HTML+JS. The language's expressiveness IS the token efficiency.
+- **The attitude of Ruby:** Convention over configuration, developer happiness, "make programmers happy" — these principles produce concise DSLs that are inherently token-efficient. Ruby was optimized for human readability; turns out that's also LLM readability.
+- Compare: Python Streamlit (close but more verbose), JS/TS (pi-design-deck's approach — more boilerplate)
+
+## Post 2: Claude Code as Collaborative Architect
+**Angle:** What AI-assisted engineering actually looks like at scale.
+- Parallel subagent analysis while main thread does non-overlapping work (GSD research, blog outlines, progress tracking, lessons learned)
+- Quality of analysis: 45 Gherkin scenarios from reading TypeScript source, token cost estimates, architecture recommendations — all emerged without being explicitly prompted
+- The "ultrathink" instruction: asking for thoroughness yields thoroughness
+- Not "AI writes code" but "AI does the research, analysis, and grunt work so the human can make better decisions faster"
+- The human's role: specifying the process, predicting outcomes (1/3 overlap → confirmed at 37%), setting quality bars, choosing what to vet
+
+## Post 3: The Engineering Process That GenAI Rewards
+**Angle:** Specification depth is the new 10x multiplier.
+- Most people: "build me a design deck" → 1-shot, mediocre result, tech debt from day 1
+- This approach: clone references → deep analysis → overlap matrix → unified specs → reviewed design → subagent implementation
+- **The code reuse prediction:** Hypothesized ~1/3 overlap, confirmed at 37%. Most engineers can't predict this because they don't analyze before building. GenAI makes analysis cheap enough to always do it.
+- **DRY at the architecture level:** Not just "don't copy-paste functions" but "don't build 50 components when 37% are shared infrastructure." The component inventory (9 shared, 10 deck, 19 explainer, 12 enhanced) exists because we analyzed first.
+- **Why this matters for long-lived projects:** StreamWeaver isn't a weekend hack. Shared Mermaid rendering, theme system, code highlighting — these compound. Every future skill gets them for free. The upfront analysis cost (3 subagents, ~370K tokens) pays for itself on the second skill.
+- **The uncomfortable truth:** Most people won't do this. Not because they can't, but because they don't value the analysis phase. GenAI amplifies whatever process you bring — if your process is "just build it," you get fast garbage. If your process is "understand, then build," you get fast quality.
+
+## Post 4: The Repeatable Process (Skill Extraction)
+**Angle:** If it worked once, encode it.
+- The full process: clone → parallel analysis (shared template) → overlap matrix → unified Gherkin → OO design → multi-model review → GSD-style subagent implementation
+- Why each step exists (lessons learned)
+- The skill template for `/port-from-reference`
+- Meta-lesson: the process of creating the process is itself the valuable artifact
+- Connection to SDRD: this IS spike-driven discovery — we're building to learn what the architecture should be
+
+## Cross-Cutting Themes
+- **Forrest's Law in action:** Zero friction (DSL is trivial to use) + substantial perks (80% token savings, visual quality, shared infrastructure)
+- **SDRD validated:** We didn't over-plan. We analyzed reference implementations, discovered the real requirements, and are designing from evidence — not imagination.
+- **GEA-compatible:** The parallel subagent pattern works because it's file-tracked. 20 sessions could contribute to this without stepping on each other.

data/docs/visual-skills/blog/token-efficiency.md

@@ -0,0 +1,73 @@
+# Blog Post Draft: Why a DSL Beats Raw HTML for AI Agent UIs
+
+## Working Title
+"From 10,000 Tokens to 200: Why StreamWeaver's DSL Is the Future of Agent-to-Browser Communication"
+
+## Thesis
+Every coding agent that needs visual output is reinventing the same wheel: generate
+HTML/CSS/JS, serve it, open browser. This is expensive (tokens), fragile (CSS bugs),
+and duplicated across every project. A reactive DSL solves all three.
+
+## Outline
+
+### 1. The Problem: ASCII Art Has Hit Its Wall
+- Terminal agents default to box-drawing characters for diagrams
+- Tables wrap and break beyond 3 columns
+- Design decisions need visual comparison, not text descriptions
+- Two excellent projects prove the demand: pi-design-deck, visual-explainer
+
+### 2. The Current Solution: Generate HTML Every Time
+- Agent generates full HTML documents with inline CSS/JS
+- pi-design-deck: ~2000-token JSON slide definitions + agent generates options
+- visual-explainer: agent generates entire HTML pages from reference patterns
+- Every interaction regenerates substantial markup
+- Token cost analysis: [INSERT NUMBERS FROM ANALYSIS]
+
+### 3. The DSL Alternative: Describe Intent, Not Markup
+- StreamWeaver example: design deck in ~50 lines of Ruby DSL
+- vs. the equivalent: hundreds of lines of generated HTML/CSS/JS
+- The DSL is the protocol — agent sends structured data, DSL renders it
+- Re-rendering is free (server-side, no token cost)
+
+### 4. Token Efficiency Math
+- Raw HTML approach: [X] tokens per design deck interaction
+- DSL approach: [Y] tokens per design deck interaction
+- Reduction: [Z]%
+- At scale (20 interactions/session): savings compound
+
+### 5. Beyond Efficiency: The Toolkit Advantage
+- pi-design-deck is one tool. visual-explainer is another. Each standalone.
+- StreamWeaver unifies: Mermaid, code highlighting, themes, slides, tables
+  are shared components used by BOTH use cases
+- New skills get these for free — no re-implementation
+- Community can build on the foundation
+
+### 6. The Architecture
+- Agent sends compact DSL commands or structured data
+- StreamWeaver server renders reactive HTML (Puma + Pushable)
+- Browser stays open, state persists across interactions
+- AlpineJS handles client-side reactivity
+- SSE for live updates (generate-more, progress tracking)
+
+### 7. What This Means for the Ecosystem
+- Skills become smaller (less prompt engineering for HTML generation)
+- Works with Pi, Claude Code, Codex (any agent that can POST JSON)
+- Open source Ruby gem — not locked to one agent platform
+- The Streamlit parallel: just as Streamlit democratized data app UIs,
+  StreamWeaver democratizes agent UIs
+
+### 8. Show Don't Tell
+- Side-by-side: pi-design-deck JSON → StreamWeaver equivalent
+- Side-by-side: visual-explainer HTML generation → StreamWeaver equivalent
+- Token counts for each
+
+## Key Quotes to Develop
+- "TUI isn't always the best way, but this is a token-efficient way"
+- "If you can describe it in 10 lines of DSL, why generate 200 lines of HTML?"
+- "The best agent UI framework is the one where adding a new visualization
+  costs zero tokens — because the component already exists"
+
+## Target Audience
+- AI coding agent builders (Pi, Claude Code, Codex ecosystem)
+- Ruby developers interested in AI tooling
+- People frustrated with ASCII art in their terminals