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 -o captures/ +\`\`\` + +If the built CLI isn't available, fall back to: +\`\`\`bash +npx tsx packages/cli/src/cli.ts capture -o captures/ +\`\`\` + +Wait for it to complete. Print the summary: how many screenshots, assets, sections, and fonts were extracted. + +## Step 2: Read and summarize + +Read each file below. After reading each one, write a 1-2 sentence summary of what you learned. These summaries are your working memory — the raw file content may be cleared from context later. + +### Must read (do not skip) + +1. **`screenshots/full-page.png`** — View this image. Describe the site's visual mood, layout style, and dominant colors in 2-3 sentences. + +2. **`extracted/tokens.json`** — Note the top 5-7 colors (they're in HEX), all font families, number of sections, and number of headings/CTAs. + +3. **`extracted/visible-text.txt`** — Note the site's headline, tagline, key selling points, and any notable statistics or social proof. + +4. **`extracted/asset-descriptions.md`** — Read this one-line-per-file summary of all downloaded assets. Note which assets are most visually striking or useful for video (hero images, logos, product screenshots). + +### Read if they exist + +5. **`extracted/animations.json`** — Note if the site uses scroll-triggered animations, marquees, canvas/WebGL, or named CSS animations. These inform what motions to recreate. + +6. **`extracted/lottie-manifest.json`** — If present, view each preview image at `assets/lottie/previews/` to see what the animations look like. Note which ones could be embedded in the video. + +7. **`extracted/video-manifest.json`** — If present, view each preview at `assets/videos/previews/` to see what each video shows. Note which could be used as B-roll or hero footage. + +8. **`extracted/shaders.json`** — If present, note what WebGL effects the site uses (this tells you the site's creators invested in visual impact here). + +### On-demand (read only when building scenes) + +9. **Individual images in `assets/`** — Don't view every image now. Use `asset-descriptions.md` as your index. View specific images when you need them for a scene. + +10. **`extracted/assets-catalog.json`** — Don't read the full JSON. Use it to find remote URLs when you need a specific asset that wasn't downloaded. + +### For rich captures (30+ images) + +If `asset-descriptions.md` lists more than 30 assets, launch a sub-agent to view all images and SVGs: + +> "Read every image in assets/ and every SVG in assets/svgs/. For each, write one line: filename — what it shows, dominant colors, approximate size. Return the complete catalog." + +Use the sub-agent's catalog as your asset reference for the rest of the workflow. + +## Gate + +Print your site summary before proceeding to Phase 2: + +- **Site:** [name] +- **Colors:** [top 3-5 HEX values with roles] +- **Fonts:** [font families] +- **Sections:** [count] sections, [count] headings, [count] CTAs +- **Key assets:** [list 3-5 most useful assets for video] +- **Vibe:** [one sentence describing the visual identity] +``` + +- [ ] **Step 2: Commit** + +```bash +git add skills/website-to-hyperframes/references/phase-1-understand.md +git commit -m "feat(skill): add Phase 1 understand reference" +``` + +--- + +### Task 9: Write Phase 2 — Design Reference + +**Files:** +- Create: `skills/website-to-hyperframes/references/phase-2-design.md` + +- [ ] **Step 1: Write phase-2-design.md** + +This file contains the full DESIGN.md schema with all 10 sections, rules, and the Notion example. It should be approximately 150 lines. + +Content structure: +1. **Introduction** — What DESIGN.md is, why it matters (3 lines) +2. **The 10 Required Sections** — Each with a description of what to write: + - Overview (3-4 sentences, factual) + - Style Prompt (single self-contained paragraph — MOST IMPORTANT — emphasized with bold and explanation that "an AI should be able to read ONLY this paragraph and generate consistent on-brand visuals") + - Colors (HEX values from tokens.json, semantic roles) + - Typography (every font family with weights, sizing hierarchy) + - Elevation (depth strategy: borders vs shadows vs flat) + - Components (name every UI component you see in the screenshot — be specific: "Bento Grid" not "Cards") + - Motion (animation style, easing, speed, signature patterns from animations.json) + - Do's and Don'ts (3-5 rules each, derived from what the site does and doesn't do) + - What NOT to Do (explicit anti-patterns — "No gradients", "Never use rounded corners", etc.) + - Assets (map every file in assets/ and URL in assets-catalog.json to WHERE it appears and WHAT it shows) +3. **Rules** — Use exact HEX values, be factual not poetic, name components specifically +4. **Complete Example** — The Notion DESIGN.md example from the current SKILL.md (lines 84-143) — include it in full +5. **Word guidance** — Aim for thorough coverage, approximately 2000-3000 words. The Style Prompt and What NOT to Do sections are the most important — don't skimp on them. + +- [ ] **Step 2: Commit** + +```bash +git add skills/website-to-hyperframes/references/phase-2-design.md +git commit -m "feat(skill): add Phase 2 design reference with full DESIGN.md schema" +``` + +--- + +### Task 10: Write Phase 3 — Creative Direction Reference + +**Files:** +- Create: `skills/website-to-hyperframes/references/phase-3-direct.md` + +- [ ] **Step 1: Write phase-3-direct.md** + +Content structure (~120 lines): + +1. **You are a Creative Director** — Set the role. Unlimited creative freedom. Design a video that stops the scroll, holds attention, drives action. +2. **Choose your visual style** — Read `visual-styles.md` (from the hyperframes/ skill, 8 named presets). Pick one as your style anchor. State it explicitly. +3. **Choose your shader transition** — Energy-to-shader mapping table (inline, 5 rows). State your choice: "I will use [shader] because [reason]." Default is Cross-Warp Morph (already in the scaffold). +4. **Motion vocabulary** — The verbs table (SLAMS, CASCADE, FLOATS etc.) — inline, not referenced. +5. **Write the narration script FIRST** — 2.5 words/sec pacing. Opening line is everything. Use contractions, write like a human. Save as `narration-script.txt`. +6. **Generate TTS** — HeyGen preferred, ElevenLabs alternative, Kokoro offline fallback. Audition 2-3 voices with the first sentence. Reference `tts-integration.md` for details. +7. **Transcribe for timestamps** — `npx hyperframes transcribe narration.wav` → `transcript.json` with word-level timing. +8. **Plan scenes around narration** — Each sentence/phrase maps to a scene. Narration IS the timeline. Print the scene plan table. +9. **Opening 2 seconds** — If you start with a logo fading in on a solid background, you've already lost. Start with: a number that shocks, a visual that moves immediately, a question that provokes, or an asset doing something unexpected. + +No "Red Flags" tables. No negative priming. All directives are positive. + +- [ ] **Step 2: Commit** + +```bash +git add skills/website-to-hyperframes/references/phase-3-direct.md +git commit -m "feat(skill): add Phase 3 creative direction reference" +``` + +--- + +### Task 11: Write Phase 4 — Build Reference + +**Files:** +- Create: `skills/website-to-hyperframes/references/phase-4-build.md` + +- [ ] **Step 1: Write phase-4-build.md** + +Content structure (~150 lines): + +1. **You are a Senior HyperFrames Engineer** — Set the role. Execute the creative director's plan at 200% quality. +2. **The scaffold is pre-wired** — The `index.html` already has Cross-Warp Morph shader transitions. To use a different shader: replace the FRAG_SHADER string, swap noise lib if needed. +3. **How to wire transitions** — One complete inline example showing GSAP timeline calling `beginTrans`/`endTrans` between two scenes with `trans.progress` 0→1. Include exact code. +4. **Asset plan per scene** — Before writing ANY HTML, list every file from `assets/` and URL from `assets-catalog.json` you'll embed per scene. If a scene uses zero captured assets, explain why. +5. **Scene composition rules:** + - Use EXACT colors from DESIGN.md (HEX values) + - Use EXACT fonts via @font-face with URLs from assets catalog + - Real SVG logos from `assets/svgs/` + - Reference assets with `../assets/` paths (compositions are one level deep) + - Remote URLs from `assets-catalog.json` work directly (`crossorigin="anonymous"`) +6. **Wire the audio** — `narration.wav` as `