From 64883fdfa10708278ce88cfa65bb2eecb9b2bc4f Mon Sep 17 00:00:00 2001 From: Brian Love Date: Sun, 7 Jun 2026 15:25:39 -0700 Subject: [PATCH 1/2] docs(spec): voice pass beyond getting-started design Co-Authored-By: Claude Opus 4.8 (1M context) --- .../2026-06-07-docs-voice-beyond-gs-design.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-07-docs-voice-beyond-gs-design.md diff --git a/docs/superpowers/specs/2026-06-07-docs-voice-beyond-gs-design.md b/docs/superpowers/specs/2026-06-07-docs-voice-beyond-gs-design.md new file mode 100644 index 00000000..623c65d3 --- /dev/null +++ b/docs/superpowers/specs/2026-06-07-docs-voice-beyond-gs-design.md @@ -0,0 +1,112 @@ +# Docs Voice Pass — Beyond Getting-Started — Design + +**Date:** 2026-06-07 +**Status:** Draft for review +**Scope:** Apply Brian's technical-register voice pass to the remaining docs prose — guides, concepts, reference, components, and api `.mdx` pages across all 7 libraries (~78 pages, ~14,800 lines). Getting-started was already voice-passed (#583, #585). Ships as one per-lib PR each (7 PRs). Same surgical, prose-only approach proven on the getting-started batches. + +## Goal + +Finish the voice pass so the whole docs prose surface reads in Brian's technical +register — without changing any technical content. This reuses the rubric and +guardrails approved + proven in the getting-started passes; it's the same design +applied to the rest of the docs. + +## Surface (~78 pages, all `.mdx` beyond getting-started) + +Per lib (guides / concepts / reference / components / api `.mdx`; excludes +`getting-started/*` [done] and generated `api/api-docs.json` [JSON, not prose]): + +| Lib | Pages | +|---|---| +| langgraph | 18 (guides 9, concepts 5, api 4) | +| chat | 30 (guides 9, concepts 2, components 14, api 5) | +| render | 11 (guides 5, concepts 1, a2ui 4 [chat-owned, already reviewed], api 5 — voice only) | +| ag-ui | 7 (guides 5, concepts 1, reference 1) | +| a2ui | 5 (guides 3, reference 2) | +| telemetry | 4 (guides 3, reference 1) | +| licensing | 3 (guides 2, reference 1) | + +## Voice rubric (technical register — unchanged from the getting-started passes) + +Apply surgically; don't churn prose that's already in-voice. + +- Title-as-lede (keep existing H1). Contractions ("it's", "you'll", "let's"). + One thought per line; short paragraphs. +- Guides (tutorial/how-to): "Let's" lead-ins where a step intro reads flatly; + ensure a short next-steps close exists where natural (reuse links already + present; verify routes in `docs-config.ts` — don't invent). +- Flag opinions ("For me", "In my experience") + a tradeoff only where the page + already recommends something. Don't invent opinions. +- Trim corporate stiffness/filler; concrete verbs. +- **Excluded:** no emojis, no anecdotes, no hype ("blazing", "game-changing", + "powerful", "seamless", "effortless"), no lecturing ("obviously"). + +## Hard guardrails (non-negotiable — same as the getting-started passes) + +1. Never change anything inside a fenced ``` code block, nor any inline `code`, + command, API name, type, version, or link/href. +2. Never change heading text (`#`/`##`/`###`) — `rehype-slug` anchors + the TOC + depend on it. H1 titles stay (they map to nav/breadcrumb/anchors). +3. Preserve all MDX components (`Callout`, `Steps`/`Step`, `Tabs`/`Tab`, + `CodeGroup`, `Card`/`CardGroup`) and their props — including every + ``. Use only supported `Callout` types (`tip`/`info`/`warning`/`danger`). +4. YAGNI — leave already-in-voice passages alone. +5. No technical corrections folded in. If a real technical error appears, leave + it and report it for a separate follow-up. (The technical review program just + completed; these pages are accuracy-fixed.) + +## Special handling — reference / api / component pages (YAGNI HARD) + +`reference/*`, `api/*`, and `chat/components/*` pages are table/signature/- +reference-heavy with thin narrative. Voice ONLY genuine prose (the page intro, +explanatory paragraphs between code/tables). **Never** touch: +- input/output/parameter/event tables or their rows, +- signatures, code fences, inline API tokens, +- component selectors/props, ``. + +Many of these pages will change little or nothing. That is expected and correct — +a near-empty diff on a reference page is a success, not a gap. + +## Implementation shape — 7 per-lib PRs + +One PR per lib. Within a PR, implementer work is grouped by section (e.g. +langgraph: guides / concepts / api) so no single agent edits too much at once. +Each section group is gated by: + +1. **Prose-only diff guard:** `git diff … | grep -E "^[+-]\s*(#{1,6} |\`\`\`|.*` line changed. +2. **Voice review:** an independent subagent confirms each page reads in the + technical register (no emojis/hype/anecdotes/lecturing) and the guardrails held. +3. **Render check:** each edited page returns HTTP 200; headings identical to `main`. + +Each PR branch is cut from up-to-date `origin/main` (the stale-source guard from +the ag-ui/licensing reviews), pushed, auto-merged on green, and monitored. + +## Order + +Biggest / highest-traffic first: **langgraph → chat → render → ag-ui → a2ui → +telemetry → licensing.** Per-lib PRs merge independently; clean libs/pages just +produce small diffs. + +## Testing & verification + +- Per edited page: the heading/fence/`` guard prints "none changed"; + headings byte-identical to `main` (rehype-slug anchors + TOC preserved); HTTP 200. +- Voice review per section group confirms register. +- No e2e change needed (routes already exist; docs e2e covers rendering). + +## Out of scope + +- `getting-started/*` (already voice-passed). +- Generated `api/api-docs.json` (JSON, not prose). +- Any code/heading/anchor/link/MDX-prop/table change (the guardrails). +- Technical corrections (the accuracy program is done; flag any new error separately). +- The `chat/a2ui/*` content already covered — voice only, no structural change. + +## Self-review notes + +- **Placeholder scan:** none — the rubric, guardrails, and per-lib page counts are concrete. +- **Internal consistency:** the per-lib PR structure matches the implementation shape + order; the YAGNI-hard reference handling is stated in its own section and echoed in out-of-scope; guardrails match the proven getting-started passes. +- **Scope:** large but decomposed into 7 independent per-lib PRs; each is a working, reviewable unit. Brainstormed once; executed lib-by-lib. +- **Ambiguity:** "everything" = all prose `.mdx` beyond getting-started, but reference/api/component pages get YAGNI-hard treatment (prose-only, often near-empty diffs). From 1f2846c398a7d736580e8e6c9646c274af0e0dfd Mon Sep 17 00:00:00 2001 From: Brian Love Date: Sun, 7 Jun 2026 15:38:29 -0700 Subject: [PATCH 2/2] docs(plan): voice pass beyond getting-started implementation plan Co-Authored-By: Claude Opus 4.8 (1M context) --- .../plans/2026-06-07-docs-voice-beyond-gs.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-07-docs-voice-beyond-gs.md diff --git a/docs/superpowers/plans/2026-06-07-docs-voice-beyond-gs.md b/docs/superpowers/plans/2026-06-07-docs-voice-beyond-gs.md new file mode 100644 index 00000000..22a43a25 --- /dev/null +++ b/docs/superpowers/plans/2026-06-07-docs-voice-beyond-gs.md @@ -0,0 +1,152 @@ +# Docs Voice Pass — Beyond Getting-Started Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Apply Brian's technical-register voice pass to the remaining docs prose (guides/concepts/reference/components/api `.mdx` across all 7 libs, ~78 pages), prose-only, shipped as one per-lib PR each (7 PRs). + +**Architecture:** Per-lib PRs. Within each PR, implementer work is grouped by section so no agent edits too much at once; each group is gated by a prose-only diff guard → voice review → render-200. Reference/api/component pages get YAGNI-hard treatment (prose-only; tables/signatures/props untouched; near-empty diffs are correct). Reuses the rubric + guardrails proven on the getting-started passes (#583, #585). + +**Tech Stack:** MDX docs (Next.js App Router), `git diff` heading/fence guard as the accuracy gate, independent voice-review subagent, dev-server/curl for render checks. `docs/gtm/voice.md` = the register. + +**Reference spec:** `docs/superpowers/specs/2026-06-07-docs-voice-beyond-gs-design.md` + +--- + +## Voice rubric (apply surgically — don't churn in-voice prose) +- Title-as-lede (keep existing H1); contractions; one thought per line; short paragraphs. +- Guides: "Let's" lead-ins where a step intro reads flatly; a brief next-steps close where natural (reuse existing links; verify routes in `docs-config.ts`). +- Flag opinions ("For me", "In my experience") + a tradeoff — only where the page already recommends something. Don't invent opinions. +- Trim corporate stiffness/filler; concrete verbs. +- NO emojis, anecdotes, hype, or lecturing. + +## Hard guardrails (NON-NEGOTIABLE) +1. Never change anything inside a fenced ``` code block, nor any inline `code`, command, API name, type, version, or link/href. +2. Never change heading text (`#`/`##`/`###`) — rehype-slug anchors + TOC depend on it. H1 titles stay exactly. +3. Preserve all MDX components + props, incl. every ``. Use only supported `Callout` types (`tip`/`info`/`warning`/`danger` — never `note`). +4. YAGNI — leave already-in-voice passages alone. +5. NO technical corrections folded in. Flag any real error for a separate follow-up. + +## Reference/api/component pages — YAGNI HARD +For `reference/*`, `api/*`, `chat/components/*`: voice ONLY the page intro + explanatory prose between code/tables. NEVER touch tables/rows, signatures, code, inline API tokens, selectors/props, ``. A near-empty or empty diff on these pages is a SUCCESS. + +## Shared per-section gate (run after each section's edits, before committing) + +```bash +cd /Users/blove/repos/angular-agent-framework +# $FILES = the edited .mdx paths for this section +for p in $FILES; do + echo "== $p ==" + echo "headings changed:"; git --no-pager diff "$p" | grep -E "^[+-]\s*#{1,6} " || echo " (none — good)" + echo "fences changed:"; git --no-pager diff "$p" | grep -E "^[+-]\s*\`\`\`" || echo " (none — good)" + echo "Step titles changed:"; git --no-pager diff "$p" | grep -E "^[+-].*`/component change. + +Then dispatch an independent **voice-review subagent** for the section: confirm each page reads in Brian's technical register (contractions, one-thought-per-line; guides have "Let's" + next-steps where natural), no emojis/hype/anecdotes/lecturing, and the guardrails held. Loop until clean. + +--- + +## Per-PR procedure (applies to every lib Task below) + +Each lib Task follows the SAME shape: + +- [ ] **Step A — branch:** `git fetch origin main`; create `claude/voice--docs` off `origin/main` (stale-source guard). +- [ ] **Step B — read + edit by section:** dispatch implementer subagent(s), one per section group (the Task lists the groups). The implementer reads each page + `docs/gtm/voice.md`, applies the rubric surgically, and respects the guardrails + YAGNI-hard rule for reference/api/component pages. +- [ ] **Step C — section gate:** run the shared per-section gate (heading/fence/``/note guard) on the edited files; fix violations. +- [ ] **Step D — voice review:** independent voice-review subagent per section group; loop until clean. +- [ ] **Step E — commit per section** (`docs(): voice pass on
`), grouped for clean history. +- [ ] **Step F — render check:** serve website on :3000; each edited route returns 200; `diff` headings of each edited page vs `origin/main` shows identical heading lines. +- [ ] **Step G — PR + auto-merge:** push, open PR (`docs(): voice pass on guides/concepts/reference`), enable squash auto-merge; monitor (`gh pr update-branch` if BEHIND). + +--- + +## Task 1 — langgraph voice PR (18 pages) + +**Branch:** `claude/voice-langgraph-docs`. +**Section groups (implementer per group):** +- **guides (9):** `lifecycle, streaming, subgraphs, time-travel, persistence, deployment, memory, interrupts, testing` — `apps/website/content/docs/langgraph/guides/*.mdx`. Tutorial/how-to register. +- **concepts (5):** `agent-contract, langgraph-basics, angular-signals, state-management, agent-architecture` — prose-dense; highest voice value; apply rubric to explanatory prose, leave code/diagrams. +- **api (4):** `inject-agent, provide-agent, fetch-stream-transport, mock-stream-transport` — YAGNI HARD (intros only; leave signatures/tables). + +Run Steps A–G. Render routes: all 18 under `/docs/langgraph/{guides,concepts,api}/`. + +## Task 2 — chat voice PR (30 pages) + +**Branch:** `claude/voice-chat-docs`. +**Section groups:** +- **guides (9):** `layout-modes, theming, markdown, generative-ui, custom-catalogs, streaming, configuration, writing-an-adapter, lifecycle`. +- **concepts (2):** `primitives-vs-compositions, message-model`. +- **components A (7):** `chat, chat-popup, chat-sidebar, chat-message-list, chat-trace, chat-input, chat-reasoning` — YAGNI HARD (intro prose only; never the input/output tables, selectors, slots). +- **components B (7):** `chat-interrupt-panel, chat-tool-calls, chat-tool-call-template, chat-tool-call-card, chat-subagent-card, chat-debug, chat-select` — YAGNI HARD. +- **api (5):** `provide-chat, chat-config, mock-agent, content-classifier, parse-tree-store` — YAGNI HARD. +- (Skip `getting-started/changelog.mdx`; the `chat/a2ui/*` pages voice only if narrative — YAGNI HARD.) + +Run Steps A–G. + +## Task 3 — render voice PR (11 pages) + +**Branch:** `claude/voice-render-docs`. +**Section groups:** +- **guides (5):** `registry, state-store, specs, events, lifecycle`. +- **concepts (1):** `json-render-vs-a2ui`. +- **api (5):** `render-spec-component, define-angular-registry, views, signal-state-store, provide-render` — YAGNI HARD. + +Run Steps A–G. + +## Task 4 — ag-ui voice PR (7 pages) + +**Branch:** `claude/voice-ag-ui-docs`. +**Section groups:** +- **guides (5):** `fake-agent, citations, interrupts, testing, troubleshooting`. +- **concepts (1):** `architecture`. +- **reference (1):** `event-mapping` — YAGNI HARD (intro prose only; never the event→signal table). + +Run Steps A–G. + +## Task 5 — a2ui voice PR (5 pages) + +**Branch:** `claude/voice-a2ui-docs`. +**Section groups:** +- **guides (3):** `message-protocol, data-model, adapters-and-validation`. +- **reference (2):** `schema, parser-resolver-guards` — YAGNI HARD (intro prose only; never the type/schema blocks or tables). + +Run Steps A–G. + +## Task 6 — telemetry voice PR (4 pages) + +**Branch:** `claude/voice-telemetry-docs`. +**Section groups:** +- **guides (3):** `browser, node, privacy-and-opt-out`. +- **reference (1):** `events` — YAGNI HARD. + +Run Steps A–G. + +## Task 7 — licensing voice PR (3 pages) + +**Branch:** `claude/voice-licensing-docs`. +**Section groups:** +- **guides (2):** `setup, ci-and-offline`. +- **reference (1):** `api` — YAGNI HARD. + +Run Steps A–G. + +## Task 8 — Land planning artifacts + close out + +- [ ] **Step 1:** After all 7 lib PRs are merged, land the spec + plan to main via a small doc-only PR from `claude/docs-voice-beyond-gs` (rebased on up-to-date main), enable auto-merge. +- [ ] **Step 2:** Confirm all PRs merged (monitor; `gh pr update-branch` any BEHIND; serialize); sync local main; delete merged branches. +- [ ] **Step 3:** Spawn a follow-up for any real technical error a voice-review surfaced (do NOT fold corrections into voice PRs). + +--- + +## Manual verification (per lib PR, before merge) +- [ ] Heading/fence/``/note guard prints "(none — good)" for every edited file; headings byte-identical to `origin/main`. +- [ ] Voice review confirms the technical register; reference/api/component pages show prose-only (often near-empty) diffs. +- [ ] All edited routes render HTTP 200. + +## Self-Review (completed during planning) + +- **Spec coverage:** all 78 pages across 7 libs covered by per-lib Tasks 1–7 with section groups matching the spec's page counts (langgraph 18, chat 30, render 11, ag-ui 7, a2ui 5, telemetry 4, licensing 3) ✓; rubric + guardrails carried verbatim from the proven passes ✓; YAGNI-hard reference/api/component handling stated in the plan header + each relevant group ✓; per-section gate (heading/fence/``/note) + voice review + render-200 ✓; per-lib PRs with stale-source guard + auto-merge + monitor ✓; planning-artifact landing + follow-up spawning (Task 8) ✓; order (langgraph→chat→render→ag-ui→a2ui→telemetry→licensing) matches the spec. +- **Placeholder scan:** No TBD/TODO. Voice edits are author-judgment (a voice pass) — bounded by the rubric, the off-limits guardrails, the automated heading/fence/``/note guard, and the independent voice review; commands have expected output ("(none — good)"). +- **Consistency:** the shared per-section gate + per-PR procedure (Steps A–G) are defined once and referenced by every lib Task; section group page lists match the spec; the supported-Callout-type guard (`note` 500'd a page in the langgraph review) is in the gate; `claude/docs-voice-beyond-gs` holds the spec/plan, with per-lib `claude/voice--docs` branches off `origin/main`.