diff --git a/docs/superpowers/plans/2026-04-13-skill-architecture-redesign.md b/docs/superpowers/plans/2026-04-13-skill-architecture-redesign.md new file mode 100644 index 0000000000..9839cfa484 --- /dev/null +++ b/docs/superpowers/plans/2026-04-13-skill-architecture-redesign.md @@ -0,0 +1,998 @@ +# Skill Architecture Redesign — 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:** Restructure the website-to-hyperframes skill from a monolithic 450-line document into a phase-based architecture with pre-wired shader transitions, eliminating the AI auto-generation path and fixing all data quality issues identified in the code review. + +**Architecture:** Remove `designMdGenerator.ts` and AI SDK dependencies. Restructure the skill into a slim orchestrator (SKILL.md) that delegates to 4 phase-specific reference files. Improve the capture pipeline to output HEX colors, asset descriptions, and a shader-ready index.html scaffold. Update the hyperframes compose skill's Visual Identity Gate to produce full DESIGN.md for non-URL prompts. + +**Tech Stack:** TypeScript (capture pipeline), Markdown (skills), WebGL/GLSL (shader scaffold), GSAP (timeline scaffold) + +--- + +## File Map + +| Action | File | Responsibility | +|--------|------|---------------| +| DELETE | `packages/cli/src/capture/designMdGenerator.ts` | AI-powered DESIGN.md generation | +| EDIT | `packages/cli/package.json` | Remove AI SDK deps | +| EDIT | `packages/cli/src/capture/tokenExtractor.ts` | RGB→HEX color conversion | +| EDIT | `packages/cli/src/capture/index.ts` | Remove AI path, add asset descriptions, new scaffold | +| EDIT | `packages/cli/src/capture/agentPromptGenerator.ts` | Remove hasDesignMd, show HEX, add asset-descriptions | +| REWRITE | `skills/website-to-hyperframes/SKILL.md` | Slim phase-based orchestrator | +| CREATE | `skills/website-to-hyperframes/references/phase-1-understand.md` | Data reading + working summary | +| CREATE | `skills/website-to-hyperframes/references/phase-2-design.md` | DESIGN.md writing (full 10-section schema) | +| CREATE | `skills/website-to-hyperframes/references/phase-3-direct.md` | Creative direction + narration + TTS | +| CREATE | `skills/website-to-hyperframes/references/phase-4-build.md` | Composition building + inline shader | +| DELETE | `skills/website-to-hyperframes/references/visual-styles.md` | Duplicate of hyperframes/ canonical | +| EDIT | `skills/hyperframes/SKILL.md` | Visual Identity Gate options 3-4 | +| EDIT | `CLAUDE.md` | Update skill references | + +--- + +### Task 1: Remove AI Auto-Generation — Dependencies and Generator + +**Files:** +- Delete: `packages/cli/src/capture/designMdGenerator.ts` +- Modify: `packages/cli/package.json:28-29` + +- [ ] **Step 1: Delete designMdGenerator.ts** + +```bash +rm packages/cli/src/capture/designMdGenerator.ts +``` + +- [ ] **Step 2: Remove AI SDK dependencies from package.json** + +In `packages/cli/package.json`, remove these two lines: + +``` + "@anthropic-ai/sdk": "^0.82.0", + "@google/genai": "^1.48.0", +``` + +- [ ] **Step 3: Run pnpm install to update lockfile** + +Run: `pnpm install` +Expected: lockfile updates, no errors + +- [ ] **Step 4: Commit** + +```bash +git add packages/cli/src/capture/designMdGenerator.ts packages/cli/package.json pnpm-lock.yaml +git commit -m "refactor(capture): remove AI auto-generation and SDK dependencies" +``` + +--- + +### Task 2: Convert Colors to HEX in Token Extractor + +**Files:** +- Modify: `packages/cli/src/capture/tokenExtractor.ts:52-82` + +- [ ] **Step 1: Add rgbToHex helper inside EXTRACT_SCRIPT** + +Insert after the `addColor` function (after line 57), before the color sampling loop: + +```js + function rgbToHex(color) { + if (!color) return null; + if (color.startsWith('#')) return color.length === 4 + ? '#' + color[1]+color[1] + color[2]+color[2] + color[3]+color[3] + : color; + var m = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/); + if (!m) { + // Handle color() function format: color(srgb 0.84 0.84 0.83) + var cm = color.match(/color\(srgb\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)/); + if (!cm) return color; + m = [null, Math.round(parseFloat(cm[1])*255), Math.round(parseFloat(cm[2])*255), Math.round(parseFloat(cm[3])*255)]; + } + return '#' + ((1<<24) + (parseInt(m[1])<<16) + (parseInt(m[2])<<8) + parseInt(m[3])).toString(16).slice(1).toUpperCase(); + } +``` + +- [ ] **Step 2: Wrap addColor to convert before storing** + +Replace the existing `addColor` function body: + +```js + function addColor(c) { + if (!c || c === "rgba(0, 0, 0, 0)" || c === "transparent" || c === "inherit" || c === "initial") return; + var hex = rgbToHex(c); + if (hex) colorSet[hex] = (colorSet[hex] || 0) + 1; + } +``` + +- [ ] **Step 3: Also convert section backgroundColor to HEX** + +In the sections extraction (around line 144), change: + +```js + if (!sectionBg || sectionBg === "rgba(0, 0, 0, 0)" || sectionBg === "transparent") sectionBg = "#FFFFFF"; + else sectionBg = rgbToHex(sectionBg) || sectionBg; +``` + +- [ ] **Step 4: Also convert heading colors to HEX** + +In the headings extraction (around line 88), change the return to: + +```js + return { level: parseInt(h.tagName[1]), text: (h.textContent || "").trim().slice(0, 200), fontSize: s.fontSize, fontWeight: s.fontWeight, color: rgbToHex(s.color) || s.color }; +``` + +- [ ] **Step 5: Run a quick capture test to verify HEX output** + +Run: `npx tsx packages/cli/src/cli.ts capture https://example.com -o /tmp/test-hex-capture --skip-split` +Expected: `tokens.json` contains `#` prefixed colors, not `rgb()` strings + +- [ ] **Step 6: Commit** + +```bash +git add packages/cli/src/capture/tokenExtractor.ts +git commit -m "fix(capture): convert extracted colors to HEX format" +``` + +--- + +### Task 3: Remove AI Path from index.ts, Add Asset Descriptions + +**Files:** +- Modify: `packages/cli/src/capture/index.ts:787-853,908-935` + +- [ ] **Step 1: Remove font paths collection block (lines 787-797)** + +Delete this entire block — it was only used by designMdGenerator: + +```typescript + // Collect font file paths (used by DESIGN.md generator) + const fontsDir = join(outputDir, "assets", "fonts"); + let fontPaths: string[] = []; + try { + const { readdirSync } = await import("node:fs"); + fontPaths = readdirSync(fontsDir) + .filter((f: string) => /\.(woff2?|ttf|otf)$/i.test(f)) + .map((f: string) => `assets/fonts/${f}`); + } catch { + /* no fonts dir */ + } +``` + +- [ ] **Step 2: Replace AI key block (lines 822-853) with asset descriptions generation** + +Delete the entire `hasAiKey` block. Replace with: + +```typescript + // Generate asset descriptions for the AI agent (no API keys needed) + progress("design", "Generating asset descriptions..."); + try { + const { readdirSync, statSync } = await import("node:fs"); + const lines: string[] = []; + + // Describe downloaded images + const assetsPath = join(outputDir, "assets"); + try { + for (const file of readdirSync(assetsPath)) { + if (file === "svgs" || file === "fonts" || file === "lottie" || file === "videos") continue; + const filePath = join(assetsPath, file); + const stat = statSync(filePath); + if (!stat.isFile()) continue; + const sizeKb = Math.round(stat.size / 1024); + // Find context from cataloged assets + const catalogMatch = catalogedAssets.find( + (a) => a.url && file.includes(a.url.split("/").pop()?.split("?")[0]?.slice(0, 20) || "___"), + ); + const context = catalogMatch?.htmlContext?.slice(0, 80) || ""; + lines.push(`${file} — ${sizeKb}KB${context ? ", " + context : ""}`); + } + } catch { /* no assets dir */ } + + // Describe SVGs + try { + const svgsPath = join(assetsPath, "svgs"); + for (const file of readdirSync(svgsPath)) { + if (!file.endsWith(".svg")) continue; + const svgMatch = tokens.svgs.find( + (s) => s.label && file.includes(s.label.toLowerCase().replace(/[^a-z0-9]/g, "-").slice(0, 15)), + ); + const label = svgMatch?.label || file.replace(".svg", "").replace(/-/g, " "); + const isLogo = svgMatch?.isLogo || file.includes("logo"); + lines.push(`svgs/${file} — ${isLogo ? "logo: " : "icon: "}${label}`); + } + } catch { /* no svgs dir */ } + + // Describe fonts + try { + const fontsPath = join(assetsPath, "fonts"); + for (const file of readdirSync(fontsPath)) { + lines.push(`fonts/${file} — font file`); + } + } catch { /* no fonts dir */ } + + if (lines.length > 0) { + writeFileSync( + join(outputDir, "extracted", "asset-descriptions.md"), + "# Asset Descriptions\n\nOne line per file. Read this instead of opening every image individually.\n\n" + + lines.map((l) => "- " + l).join("\n") + "\n", + "utf-8", + ); + progress("design", `${lines.length} asset descriptions written`); + } + } catch { + /* non-critical */ + } + + progress("design", "DESIGN.md will be created by your AI agent"); +``` + +- [ ] **Step 3: Remove the `hasAiKey` variable reference on line 955** + +Change the `generateAgentPrompt` call. The 6th argument `!!hasAiKey` should become `false`: + +```typescript + generateAgentPrompt( + outputDir, + url, + tokens, + animationCatalog, + !!fullPageScreenshot, + false, // DESIGN.md is always created by the AI agent now + discoveredLotties.length > 0, + existsSync(join(outputDir, "extracted", "shaders.json")), + catalogedAssets, + ); +``` + +- [ ] **Step 4: Commit** + +```bash +git add packages/cli/src/capture/index.ts +git commit -m "refactor(capture): remove AI key path, add asset descriptions generator" +``` + +--- + +### Task 4: Update agentPromptGenerator.ts + +**Files:** +- Modify: `packages/cli/src/capture/agentPromptGenerator.ts` + +- [ ] **Step 1: Remove hasDesignMd parameter** + +Remove `hasDesignMd` from both function signatures. In `generateAgentPrompt` (line 15), remove the 6th parameter. In `buildPrompt` (line 41), remove the 6th parameter. + +- [ ] **Step 2: Remove the conditional DESIGN.md row from the table** + +Remove this line from the template (around line 91): +``` +${hasDesignMd ? "| `DESIGN.md` | AI-generated design system reference |" : ""} +``` + +Replace with a static row: +``` +| `extracted/asset-descriptions.md` | One-line description of every downloaded asset — read this first | +``` + +- [ ] **Step 3: Add a note about DESIGN.md creation** + +After the table, add: + +``` +> **DESIGN.md does not exist yet.** It will be created when you run the `/website-to-hyperframes` workflow. Do not write compositions without it. +``` + +- [ ] **Step 4: Commit** + +```bash +git add packages/cli/src/capture/agentPromptGenerator.ts +git commit -m "refactor(capture): update agent prompt, remove hasDesignMd, add asset descriptions" +``` + +--- + +### Task 5: Rewrite index.html Scaffold with Shader Boilerplate + +**Files:** +- Modify: `packages/cli/src/capture/index.ts:908-935` + +- [ ] **Step 1: Replace the empty scaffold with a shader-ready template** + +Replace the `index.html` write block (lines 908-935) with: + +```typescript + if (!existsSync(indexPath)) { + const hostname = new URL(url).hostname.replace(/^www\./, ""); + writeFileSync( + indexPath, + ` + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +`, + "utf-8", + ); + } +``` + +- [ ] **Step 2: Verify the scaffold is valid HTML** + +Run: `npx tsx packages/cli/src/cli.ts lint /tmp/test-scaffold` (after writing the scaffold to a temp project) +Expected: No structural errors (GSAP loads, timelines registered) + +- [ ] **Step 3: Commit** + +```bash +git add packages/cli/src/capture/index.ts +git commit -m "feat(capture): pre-wire shader transitions in index.html scaffold" +``` + +--- + +### Task 6: Delete Duplicate visual-styles.md + +**Files:** +- Delete: `skills/website-to-hyperframes/references/visual-styles.md` + +- [ ] **Step 1: Delete the duplicate** + +```bash +rm skills/website-to-hyperframes/references/visual-styles.md +``` + +- [ ] **Step 2: Update any references in SKILL.md** + +The current SKILL.md (line 167) references `[visual-styles.md](./references/visual-styles.md)`. This will be replaced when we rewrite SKILL.md in Task 7. No action needed here — just noting the dependency. + +- [ ] **Step 3: Commit** + +```bash +git add skills/website-to-hyperframes/references/visual-styles.md +git commit -m "chore: remove duplicate visual-styles.md (canonical is in hyperframes/)" +``` + +--- + +### Task 7: Rewrite website-to-hyperframes SKILL.md + +**Files:** +- Rewrite: `skills/website-to-hyperframes/SKILL.md` + +- [ ] **Step 1: Write the new slim orchestrator** + +Replace the entire file with: + +```markdown +--- +name: website-to-hyperframes +description: | + Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use. +--- + +# Website to HyperFrames + +Capture a website's identity, then create an on-brand video from it. + +Users say things like: +- "Capture stripe.com and make me a 20-second product demo video" +- "Turn this website into a 15-second social ad for Instagram" +- "Create a 30-second product tour from linear.app" + +The workflow has 4 phases. Each phase produces an artifact that gates the next. + +--- + +## Phase 1: Capture & Understand + +**Read:** [references/phase-1-understand.md](references/phase-1-understand.md) + +Run the capture, then read and summarize the extracted data using the write-down-and-forget method described in the reference. + +**Gate:** Print your site summary before proceeding: +- Site name, top 3-5 colors (HEX), primary font family +- Number of assets, sections, and animations available +- One sentence: what is this site's visual vibe? + +--- + +## Phase 2: Write DESIGN.md + +**Read:** [references/phase-2-design.md](references/phase-2-design.md) + +Write a complete DESIGN.md with all 10 sections. The Style Prompt section is the most important — an AI should be able to read only that paragraph and generate consistent on-brand visuals. + +**Gate:** `DESIGN.md` exists in the project directory with all 10 sections populated. + +--- + +## Phase 3: Creative Direction + +**Read:** [references/phase-3-direct.md](references/phase-3-direct.md) + +Think like a creative director. Choose a visual style, write the narration script, generate TTS audio, and plan every scene around the narration timestamps. + +**Gate:** All three artifacts exist: +1. `narration-script.txt` — the voiceover script +2. `narration.wav` (or .mp3) — generated TTS audio +3. Scene plan printed (Scene | Duration | Visual | Emotion | Assets | Transition | Narration) + +If the user explicitly says "no narration" or "no voiceover": skip script/TTS, plan scenes with visual-only timing. + +--- + +## Phase 4: Build & Deliver + +**Read:** The `/hyperframes-compose` skill (invoke it — every rule matters) +**Read:** [references/phase-4-build.md](references/phase-4-build.md) + +Build the compositions. The `index.html` scaffold already has shader transitions pre-wired (Cross-Warp Morph by default). Modify the shader choice and wire the transition timeline to your scene plan. + +**Gate:** Both commands pass with zero errors: +```bash +npx hyperframes lint +npx hyperframes validate +``` + +Then preview: `npx hyperframes preview` + +--- + +## Quick Reference + +### Video Types + +| Type | Duration | Scenes | Narration | +|------|----------|--------|-----------| +| Social ad (IG/TikTok) | 10-15s | 3-4 | Optional hook sentence | +| Product demo | 30-60s | 5-8 | Full narration | +| Feature announcement | 15-30s | 3-5 | Full narration | +| Brand reel | 20-45s | 4-6 | Optional, music focus | +| Launch teaser | 10-20s | 2-4 | Minimal, high energy | + +### Format + +- **Landscape**: 1920x1080 (default) +- **Portrait**: 1080x1920 (Instagram Stories, TikTok) +- **Square**: 1080x1080 (Instagram feed) + +### Reference Files + +| File | When to read | +|------|-------------| +| [phase-1-understand.md](references/phase-1-understand.md) | Phase 1 — reading captured data | +| [phase-2-design.md](references/phase-2-design.md) | Phase 2 — writing DESIGN.md | +| [phase-3-direct.md](references/phase-3-direct.md) | Phase 3 — creative direction and narration | +| [phase-4-build.md](references/phase-4-build.md) | Phase 4 — building compositions | +| [asset-sourcing.md](references/asset-sourcing.md) | When you need logos, icons, or photos not in the capture | +| [video-recipes.md](references/video-recipes.md) | Scene patterns, 5-layer system, mid-scene activity | +| [tts-integration.md](references/tts-integration.md) | Voice selection, TTS generation options | +| [animation-recreation.md](references/animation-recreation.md) | Converting source animations to GSAP | +``` + +- [ ] **Step 2: Commit** + +```bash +git add skills/website-to-hyperframes/SKILL.md +git commit -m "refactor(skill): rewrite website-to-hyperframes as phase-based orchestrator" +``` + +--- + +### Task 8: Write Phase 1 — Understand Reference + +**Files:** +- Create: `skills/website-to-hyperframes/references/phase-1-understand.md` + +- [ ] **Step 1: Write phase-1-understand.md** + +```markdown +# Phase 1: Capture & Understand + +## Step 1: Run the capture + +\`\`\`bash +npx hyperframes capture