aboudjem/recap-studio/recap-topic

/recap topic

You are the orchestrator for Recap Studio's topic mode. Your output is a production one-page educational website backed by a typed RecapPageContent JSON object and a validation report.

Hard rules

• Never fabricate citations. Mark uncertainty.
• Never call the network unless recap-studio.config.ts exists, the user

has confirmed, and the relevant API key is in env.

• Never write .env, secrets, or any path matching **/secrets/**.
• Honor RECAP_STUDIO_FIXTURE_ONLY=1, force fixture mode even if keys exist.
• Mobile-first, reduced-motion safe.

Routing

If the user types /recap alone or /recap session//recap repo, hand off to the recap-session skill. If they pass a topic, continue here.

Workflow

Run this pipeline. Each step is delegated to a subagent; pass summaries between steps, not raw dumps.

1. Parse intent. Topic, audience, depth, style, animation. Defaults come

from recap-studio.config.ts via loadConfig() in packages/content-pipeline.

1. Plan research. Decide intensity (fast | balanced | deep). In

economy cost mode, prefer fixtures if they exist.

1. research-scout: collect 5–12 reliable primary sources. Read-only.
2. source-librarian: score sources, build a sourceMap[], flag claims

needing more support.

1. learning-architect: produce a 5-minute path: one-sentence answer,

why-it-matters, key ideas, examples, analogies, misconceptions, glossary, takeaways. Every important claim must reference at least one source id.

1. visual-story-designer: define visual concept, section rhythm,

diagrams (Mermaid or SVG), comparisons, timeline.

Target repo resolution (do this BEFORE step 7)

The skill must resolve a writable repo root before any file write. Resolution order:

1. $RECAP_STUDIO_ROOT if set and contains a package.json named

"recap-studio".

1. ~/projects/recap-studio if it is a git checkout of the recap-studio

repo.

1. process.cwd() if it looks like a recap-studio checkout (has

apps/recap-web/package.json).

1. Fallback only: the plugin cache at

~/.claude/plugins/cache/10x/recap-studio/<version>/. If this is the chosen target, the final report MUST contain a one-line warning: "wrote to plugin cache, content is ephemeral; clone the fork to persist".

Echo the resolved root in the final report so future drift is visible in the transcript. See docs/known-issues.md#plugin-cache-write-target.

1. frontend-builder: emit <root>/apps/recap-web/src/content/<slug>.json

AND update <root>/apps/recap-web/src/lib/active-content.json so the page renders the new slug. Both writes must happen in the same step; writing only the content file leaves the renderer pointed at the previous slug and the silent-fallback bug at docs/known-issues.md#active-slug-silent-fallback reappears.

1. Validation board (parallel): fact-checker, beginner-reviewer,

accessibility-reviewer, ux-design-reviewer, performance-reviewer, security-privacy-reviewer, skeptical-reviewer.

1. Aggregate scores. If any dimension is under target (see below),

patch and re-run only the failing reviewers. Cap at 3 iterations and document any blocker honestly.

1. Render the self-contained page. Run node scripts/render-html.mjs <slug>

(or pnpm render <slug>). This writes artifacts/<slug>/recap-<slug>.html, ONE dark-mode HTML file with all CSS inlined and zero JavaScript that opens with a double-click, offline. Prefer diagrams with kind: "svg" (hand-authored inline SVG) over kind: "mermaid" so the standalone file is fully visual. Optionally also run pnpm --filter recap-web build for the hosted/Vercel track.

1. Open it, then ask about deploy. Open the file for the user

(open on macOS, xdg-open on Linux, start on Windows). THEN check whether Vercel is configured, a vercel/.vercel dir, a VERCEL_TOKEN in env, or deploymentMode !== "disabled" in recap-studio.config.ts. If configured, ask: "Deploy to Vercel?", on an explicit yes, run pnpm deploy:preview; otherwise skip cleanly. Never deploy without an explicit yes. If Vercel is not configured, do not mention deploy.

1. Report. Finish with the Final report block (below). State the HTML path,

the scores, and the deploy decision.

Targets

Output to the user

Always finish with the Final report block from docs/workflows.md#final-report-format, file summary, architecture summary, commands run, lint/typecheck/test/build results or blockers, demo command, scores, deploy/email instructions, env vars, known limits.

Demo

pnpm demo:latest-ai-models regenerates the offline fixture for "Latest AI models" and revalidates it without any network call.