docs: add skill architecture redesign spec

Comprehensive redesign of website-to-hyperframes skill and capture
pipeline based on code review findings and Claude Code architecture
research. Key changes: remove AI auto-generation, restructure skill
into phases, embed shader boilerplate in scaffold, fix color format.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
ularkim
2026-04-15 14:05:01 -04:00
co-authored by Claude Opus 4.6
parent a67753e433
commit 4ecd8fcaed
13 changed files with 1490 additions and 23 deletions
+70
View File
@@ -0,0 +1,70 @@
# Context for New Session
## The Project
HyperFrames is an open-source video rendering framework: write HTML, render video. The branch `feat/website-capture-design-md` adds a website capture pipeline and skill system for turning URLs into videos.
## What Exists on This Branch
### Capture Pipeline (`packages/cli/src/capture/`)
`npx hyperframes capture <URL>` extracts a website's design system — colors, fonts, assets, animations, Lottie, WebGL shaders — into a structured folder with screenshots, tokens.json, assets/, and extracted data.
### Skills (AI Agent Instructions)
**`skills/website-to-hyperframes/SKILL.md`** — 6-step workflow:
1. Capture the website
2. Read ALL captured data
3. Create DESIGN.md (brand identity doc)
4. Plan the video (Creative Director role)
5. Build compositions (Engineer role)
6. Lint, validate, preview
**`skills/hyperframes/SKILL.md`** — Compose skill for writing HTML video compositions. Has rules for data attributes, GSAP timelines, deterministic rendering.
**Reference files:**
- `references/visual-styles.md` — 8 named visual styles with hex palettes, GSAP easing, shader pairings
- `references/asset-sourcing.md` — How to source brand logos, icons, photos from free APIs
- `references/video-recipes.md` — Scene patterns, 5-layer composition system, transition patterns
- `references/transitions/shader-setup.md` — WebGL boilerplate for 14 GLSL shader transitions
- `references/transitions/shader-transitions.md` — 14 fragment shaders (domain warp, ridged burn, gravitational lens, etc.)
### 28 Existing Captures
`captures/` has linear, perplexity, arc-browser, stripe-website, notion, framer, midjourney, resend, vercel-tour, and more — each with screenshots, tokens, assets, visible text.
## Git State
- Rebased on latest `origin/main` (v0.3.0)
- 6 commits + 10 staged files (not yet committed)
- ~49 unstaged test/template files that are NOT our changes — discard with `git checkout -- packages/producer/tests/ templates/`
## 4 Test Runs Were Completed
Each in a fresh Claude Code session with a single prompt:
1. **Linear capture → 24s launch video**
2. **"Make a 20s video about AI agents replacing jobs"** (no URL, from scratch)
3. **"Make a 20s video showcasing Stripe's payment platform"** (brand-specific)
4. **"Make a 15s Data Drift style video about quantum computing"** (named visual style)
The conversation logs are the 4 most recent JSONL files in:
`/Users/ularkimsanov/.claude/projects/-Users-ularkimsanov-Desktop-hyperframes-3/`
## What To Do
Review the entire skill system, the 4 test conversation logs, and the resulting compositions. Assess:
- What is the skill system doing well?
- What is it doing poorly?
- What specific changes would improve output quality?
- Are there structural issues (not just instruction wording) that need addressing?
Look at the actual HTML compositions produced, the DESIGN.md files, the narration scripts, and the index.html files. Judge the output quality honestly.
## Key Files
- `skills/website-to-hyperframes/SKILL.md`
- `skills/hyperframes/SKILL.md`
- `skills/hyperframes/house-style.md`
- `skills/hyperframes/references/transitions/shader-setup.md`
- `skills/hyperframes/references/transitions/shader-transitions.md`
- `skills/website-to-hyperframes/references/visual-styles.md`
- `skills/website-to-hyperframes/references/video-recipes.md`
- `skills/website-to-hyperframes/references/asset-sourcing.md`
+105
View File
@@ -0,0 +1,105 @@
# Session Handoff — April 13, 2026
## What This Branch Is
`feat/website-capture-design-md` — Website capture pipeline + skill system for turning URLs into HyperFrames videos. Rebased on latest main (v0.3.0, 28 commits ahead). Not yet pushed or PR'd.
## What Was Built (All Working)
### Capture Pipeline (`packages/cli/src/capture/`)
- `npx hyperframes capture <URL>` — extracts design tokens, assets, screenshots, animations, Lottie, shaders, video manifest
- Two-pass strategy: Pass 1 (full JS) captures WebGL/Lottie/animations, Pass 2 (stable HTML) extracts tokens
- Downloads SVGs, images, fonts, favicons with deduplication and batch parallelism
- Generates `CLAUDE.md` per capture with brand summary and example prompts
- Bug fix needed: `assetDownloader.ts` `fetchBuffer()` — added content-type check to reject XML error responses saved as images (staged but not committed)
### Website-to-HyperFrames Skill (`skills/website-to-hyperframes/`)
Full 6-step pipeline: Capture → Read ALL data → Create DESIGN.md → Plan video (Creative Director) → Build compositions (Engineer) → Lint/validate/preview.
### Compose Skill Improvements (`skills/hyperframes/SKILL.md`)
- Added `<HARD-GATE>` Visual Identity Gate — requires DESIGN.md or visual-style.md before ANY HTML writing
- 4-step cascade: existing DESIGN.md → visual-style.md → named style → ask 3 questions
- **TEST RESULT: 4/4 tests created DESIGN.md before HTML. This works.**
### New Reference Files
- `references/visual-styles.md` — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing, shader pairings
- `references/asset-sourcing.md` — How to source brand logos (Simple Icons), company logos (Clearbit), icons (Lucide), photos (Unsplash) with exact curl commands
- `references/video-recipes.md` — 5-layer composition system (L1-L5), shader-first transition pattern, seeded PRNG grain, motion vocabulary
### DESIGN.md Format
Added sections: `## Style Prompt` (standalone AI-readable paragraph), `## Motion`, `## What NOT to Do` (explicit anti-patterns). Tested and working across all captures.
## What Failed — Shader Transitions
### The Problem
HyperFrames has 14 GLSL shader transitions (domain warp, ridged burn, gravitational lens, etc.) that are a massive visual differentiator. But Claude Code never uses them — every test video uses CSS fade-to-black between scenes.
### What We Tried
1. **Session 1:** Added energy→shader table, verbal commitment requirement ("I will use [shader name]"), shader wiring instructions in Step 5. **Result: 1/3 used shaders** (Arc did, Linear and Perplexity didn't).
2. **Session 2:** Added superpowers-style enforcement — `<HARD-GATE>` tags, Red Flags table (6 rationalizations), self-verification checklist (5 checkboxes). **Result: 0/3 used shaders.** Three different failure modes:
- Linear: Named "Cinematic Zoom" but wrote CSS clip-path instead — treated verbal commitment as checkbox
- Stripe: Falsely claimed "shader reference files are not available in the installed skill" — never tried to read them
- Data Drift: Searched for visual-styles.md in wrong directory, gave up, improvised
### Why Instructions Don't Work For This
The shader transition system requires ~200 lines of WebGL boilerplate (texture capture, shader compilation, state machine, GSAP integration). The agent has to:
1. Read shader-setup.md (200+ lines)
2. Read shader-transitions.md (pick a fragment shader)
3. Hold all of that in working memory
4. Write it from scratch into index.html
5. While ALSO managing scenes, narration, captions, fonts, assets, timing
The agent takes the easy path every time: CSS fades (3 lines vs 200).
### What Might Actually Work (Untested)
- **Option A: Inline the shader boilerplate** directly in the SKILL.md as a copy-paste code block instead of referencing a separate file. The agent can't skip code that's right in front of it.
- **Option B: Template file** — `index-template-with-shaders.html` with WebGL pre-wired. Agent fills in scene IDs and picks a fragment shader.
- **Option C: Engine feature** — `data-transition="cinematic-zoom"` as a framework attribute. Engine handles WebGL internally. This is the long-term answer but requires real engineering in `packages/engine`.
### Key Insight From Testing
Instructions work when they're **structurally useful** to the agent (DESIGN.md helps it write better HTML → 4/4 compliance). Instructions fail when they add **extra work** the agent can shortcut (shader WebGL boilerplate → 0/3 compliance).
## Git State
- Branch: `feat/website-capture-design-md`
- Rebased on latest `origin/main` (v0.3.0)
- 6 commits + 10 staged files (not committed)
- Staged files:
- `skills/hyperframes/SKILL.md` (DESIGN.md hard gate + visual-styles.md reference)
- `skills/hyperframes/visual-styles.md` (NEW)
- `skills/website-to-hyperframes/SKILL.md` (shader enforcement — may want to remove the failed enforcement parts)
- `skills/website-to-hyperframes/references/asset-sourcing.md` (NEW)
- `skills/website-to-hyperframes/references/visual-styles.md` (NEW)
- `skills/website-to-hyperframes/references/video-recipes.md` (5-layer system)
- `packages/cli/src/capture/index.ts` (capture pipeline)
- `packages/cli/src/capture/agentPromptGenerator.ts` (capture pipeline)
- `packages/cli/src/capture/assetDownloader.ts` (capture pipeline + content-type fix)
- `docs/superpowers/specs/2026-04-13-preproduction-enforcement-design.md` (design spec)
- ~49 unstaged test/template files — NOT ours, caused by a bug where `npx hyperframes preview` overwrites TRANSCRIPT arrays in test fixtures. Discard with `git checkout -- packages/producer/tests/ templates/`
## Existing Captures Available for Testing
28 captures in `captures/` including: linear, perplexity, arc-browser, stripe-website, notion, framer, midjourney, resend, vercel-tour, and more. Each has screenshots, tokens.json, assets, visible-text.txt.
## Installed Skills & Tools
- Superpowers v5.0.7 (brainstorming, TDD, debugging, code review, etc.)
- GSAP skills (core, timeline, plugins, performance, scrolltrigger, utils)
- HeyGen skills (create-video, visual-style, avatar-video, TTS, etc.)
- Remotion best practices (38 rule files at `.agents/skills/remotion-best-practices/`)
- ElevenLabs MCP (TTS)
- Playwright MCP (browser automation)
## Key Files to Read
- `skills/website-to-hyperframes/SKILL.md` — the main workflow
- `skills/hyperframes/SKILL.md` — compose skill with DESIGN.md gate
- `skills/hyperframes/house-style.md` — motion defaults, anti-defaults table
- `skills/hyperframes/references/transitions/shader-setup.md` — the WebGL boilerplate that agents won't read
- `skills/hyperframes/references/transitions/shader-transitions.md` — 14 fragment shaders
- `.claude/projects/-Users-ularkimsanov-Desktop-hyperframes-3/memory/MEMORY.md` — persistent memory index
## What To Do Next
1. **Commit what works** — DESIGN.md gate, visual styles, asset sourcing, video recipes, capture pipeline. These are proven wins.
2. **Solve shader transitions** — try Option A (inline boilerplate in skill) or Option B (template file). Test with subagents or fresh sessions.
3. **Fix the transcript overwrite bug** — `npx hyperframes preview` is mutating test fixtures and templates.
4. **Test non-capture videos** — the DESIGN.md gate works but named styles (like "Data Drift") fail because the agent can't find visual-styles.md. The file path needs to be more prominent in the compose skill.
@@ -0,0 +1,93 @@
# Phase 1: Pre-Production + Shader Enforcement
**Date:** 2026-04-13
**Status:** Approved
**Scope:** Skill/documentation changes only. Zero engine or CLI code.
## Problem
1. **2/3 test videos skipped shader transitions** despite SKILL.md instructions. The instruction was a suggestion, not an enforced gate. Claude verbally committed to a shader in Step 4 then wrote CSS fades in Step 5.
2. **Non-capture videos have no visual identity.** When there's no website capture, Claude picks generic defaults (blue, gray, Roboto). The compose skill acknowledges `visual-style.md` exists but has no mechanism to require one.
3. **Non-capture videos have no assets.** Without a capture, Claude can only generate CSS shapes and inline SVGs. No photos, no brand logos, no icons.
## Deliverables
### 1. Asset Sourcing Reference (`asset-sourcing.md`)
**File:** `skills/website-to-hyperframes/references/asset-sourcing.md`
Teaches Claude how to find and download free assets from known-good sources:
| Asset type | Source | URL pattern | License |
|-----------|--------|-------------|---------|
| Brand logos (SVG) | Simple Icons | `cdn.jsdelivr.net/npm/simple-icons@latest/icons/{name}.svg` | CC0 |
| Company logos (PNG) | Clearbit | `logo.clearbit.com/{domain}` | Free |
| Icons (SVG) | Lucide | `cdn.jsdelivr.net/npm/lucide-static@latest/icons/{name}.svg` | ISC |
| Photos | Unsplash | `api.unsplash.com/search/photos?query={q}` | Free (attribution) |
Includes: when to source vs skip, curl patterns, naming conventions, manifest format.
Also wired into SKILL.md Reference Files table.
### 2. Universal DESIGN.md Gate in Compose Skill
**File:** `skills/hyperframes-compose/SKILL.md` (the global compose skill)
Add a `<HARD-GATE>` before any HTML writing that enforces:
```
1. DESIGN.md exists? → Use it.
2. visual-style.md exists? → Use it.
3. User named a style? → Generate DESIGN.md from visual-styles.md.
4. None? → Ask 3 questions, generate minimal DESIGN.md.
```
Every composition must trace its palette back to a defined source. No generic defaults.
### 3. Shader Transition Enforcement
**File:** `skills/website-to-hyperframes/SKILL.md`
Three superpowers-inspired enforcement mechanisms:
**A. Red Flags table** (Step 4) — 5 common rationalizations with reality checks:
- "CSS fades are simpler" → Shaders are the default
- "I'll add shaders later" → Later never comes
- "Separate files are cleaner" → Shaders need root index.html
- "Video is short" → Under 10s is the ONLY exception
- "It's complex" → Boilerplate is copy-paste from shader-setup.md
**B. Hard gate** (Step 5) — Before writing index.html, verify:
- Shader named in Step 4
- shader-setup.md read
- Fragment shader code read
**C. Self-verification checklist** (Step 6) — Before claiming done:
- [ ] index.html contains `<canvas id="gl-canvas">`
- [ ] index.html contains `gl.createShader`
- [ ] index.html contains `beginTrans` and `endTrans`
- [ ] Scenes do NOT fade to/from black
## Files Changed
| File | Change type |
|------|------------|
| `skills/website-to-hyperframes/references/asset-sourcing.md` | NEW |
| `skills/website-to-hyperframes/SKILL.md` | EDIT (red flags + hard gate + verification) |
| `skills/hyperframes-compose/SKILL.md` | EDIT (DESIGN.md hard gate) |
## Success Criteria
Re-run 3 test captures. Expect:
- 3/3 use shader transitions (was 1/3)
- 3/3 have DESIGN.md with Style Prompt (was 3/3, maintain)
- Non-capture videos also get DESIGN.md before any HTML
## What This Does NOT Change
- Compose skill HTML rules (data attributes, templates, GSAP)
- Capture pipeline (no code changes)
- Engine or producer (no code changes)
- house-style.md (still the fallback for motion defaults)
@@ -0,0 +1,305 @@
# Skill Architecture Redesign — Website-to-HyperFrames + Compose
**Date:** 2026-04-13
**Status:** Approved
**Goal:** A fresh Claude Code session, given a one-line prompt, produces professional-quality video with shader transitions, real assets, synced narration, and purposeful motion — whether starting from a URL or from scratch.
---
## Problem Statement
The current system produces mediocre output. Root causes identified through comprehensive code review:
1. **Split-brain DESIGN.md schema.** The auto-generator (`designMdGenerator.ts`) produces DESIGN.md missing 3 critical sections (Style Prompt, Motion, What NOT to Do) that the skill depends on. Two different systems disagree on what DESIGN.md contains.
2. **Instruction decay.** The 450-line monolithic SKILL.md causes Lost-in-the-Middle attention collapse. Shader instructions (the biggest visual differentiator) sit in the middle of a long document and are ignored in 100% of existing compositions.
3. **Context overflow.** "Read ALL files, do not skip any" triggers 100+ tool calls. By the time the agent finishes viewing 42 images, the first 10 are compressed out of context.
4. **RGB/HEX mismatch.** Token extractor outputs `rgb()` format but every downstream consumer expects `#HEX`.
5. **Shader transitions require building from scratch.** The agent must read 900+ lines of reference material across 3 files to wire a shader. 0% compliance rate.
6. **No path for "from scratch" videos.** The hyperframes compose skill's Visual Identity Gate handles URL-based captures well but produces a minimal 4-field DESIGN.md for non-URL prompts.
---
## Design
### Part 1: Remove AI Auto-Generation from Capture Pipeline
The capture pipeline becomes a pure data extractor. All intelligence lives in the agent session.
#### Files to delete
- `packages/cli/src/capture/designMdGenerator.ts`
#### Dependencies to remove from `packages/cli/package.json`
- `@anthropic-ai/sdk`
- `@google/genai`
#### Changes to `packages/cli/src/capture/index.ts`
- Remove the AI key check block (lines 822-853). Replace with:
```typescript
progress("design", "DESIGN.md will be created by your AI agent");
```
- Remove `hasDesignMd` variable and its usage in `generateAgentPrompt()` call
- Remove the font paths collection block (lines 787-797) — only needed for the AI generator
#### Changes to `packages/cli/src/capture/agentPromptGenerator.ts`
- Remove `hasDesignMd` parameter from `generateAgentPrompt()` and `buildPrompt()`
- Remove the conditional DESIGN.md row from the table
- Convert colors to HEX in the Brand Summary section (use a simple rgb-to-hex converter)
- The CLAUDE.md it generates should always say "DESIGN.md will be created when you run the workflow"
#### Changes to `packages/cli/src/capture/tokenExtractor.ts`
- Convert all extracted colors from `rgb()`/`rgba()` to `#HEX` format at extraction time
- Add a `rgbToHex()` utility function
#### New: Generate `extracted/asset-descriptions.md` during capture
- After asset download completes in `index.ts`, generate a one-line-per-file summary
- Source data: filename, file size, image dimensions (from buffer), HTML context from `assets-catalog.json`
- Format: `image-0.png — 1920x600, hero section, found in <section> "Financial Infrastructure"`
- For SVGs: `svgs/logo.svg — brand wordmark, 400x100 viewBox, found in <nav>`
- No AI needed — derive from metadata already available
- Add this file to the CLAUDE.md table so agents know to read it
#### New: Improve `index.html` scaffold with shader boilerplate
- The scaffold generated at end of `index.ts` (lines 908-932) currently creates an empty shell
- Replace with a scaffold that includes:
- `<canvas id="gl-canvas">` positioned above scene slots
- Pre-wired WebGL init (getContext, compileShader utility functions)
- The Cross-Warp Morph fragment shader as default (most versatile)
- Scene slot divs with `data-composition-src` pointing to `compositions/scene-N.html`
- `beginTrans()` / `endTrans()` functions wired to GSAP timeline
- Comment markers: `/* AGENT: Replace this shader with your choice from shader-transitions.md */`
- CSS fallback for when WebGL is unavailable
- The scaffold should be a complete, working composition that the agent modifies, not builds from scratch
- Number of scene slots: 4 (the agent adds/removes as needed)
- Include `<audio>` element for narration on its own track
- Include a caption composition slot on a parallel track
---
### Part 2: Restructure website-to-hyperframes Skill
Replace the monolithic SKILL.md with a slim orchestrator + phase-specific references.
#### New file structure
```
skills/website-to-hyperframes/
├── SKILL.md ← ~120 lines, orchestrator only
├── references/
│ ├── phase-1-understand.md ← Read data, write working summary
│ ├── phase-2-design.md ← Write DESIGN.md (full 10-section schema)
│ ├── phase-3-direct.md ← Creative direction + narration + TTS
│ ├── phase-4-build.md ← Build compositions + inline shader example
│ ├── asset-sourcing.md ← Keep as-is
│ ├── video-recipes.md ← Keep, minor trim
│ ├── tts-integration.md ← Keep as-is
│ └── animation-recreation.md ← Keep as-is
```
#### Delete
- `skills/website-to-hyperframes/references/visual-styles.md` (duplicate of canonical `skills/hyperframes/visual-styles.md`)
#### SKILL.md — The Orchestrator (~120 lines)
Structure:
```
# Website to HyperFrames
Quick Start section (what users say, what happens)
## Phase 1: Capture & Understand
- Run capture command
- Read: references/phase-1-understand.md
- GATE: Print site summary (name, colors, fonts, asset count, vibe)
## Phase 2: Write DESIGN.md
- Read: references/phase-2-design.md
- GATE: DESIGN.md exists with all 10 sections
## Phase 3: Creative Direction
- Read: references/phase-3-direct.md
- GATE: narration-script.txt exists, scene plan printed
## Phase 4: Build & Deliver
- Read: /hyperframes-compose skill
- Read: references/phase-4-build.md
- GATE: npx hyperframes lint && npx hyperframes validate pass
## Quick Reference
- Video Types table (filled in with durations, scene counts, narration guidance)
- Format reference (landscape/portrait/square)
- Reference files table
```
Key principles:
- Each phase is ~3-5 lines in the orchestrator, linking to a focused reference
- Gates produce artifacts (files, printed output), not "confirm" instructions
- No "Red Flags" tables — positive directives only
- No `!!!!` or `!!!!!!` — professional tone
- Critical rules stated at top AND bottom (repetition per research)
#### phase-1-understand.md (~80 lines)
The write-down-and-forget pattern:
- For each extracted file, read it and write a 1-2 sentence summary
- The summary is the agent's working memory
- For captures with 30+ images: launch a sub-agent to view all assets and return a compact catalog
- Tiered reading: MUST read (screenshot, tokens, visible-text, asset-descriptions.md), SKIM (assets-catalog), ON-DEMAND (individual images)
- End state: a ~500-word printed summary that persists in context
#### phase-2-design.md (~150 lines)
Full DESIGN.md schema with all 10 sections:
1. Overview (3-4 sentences)
2. Style Prompt (single self-contained paragraph — most important section, emphasized)
3. Colors (HEX values, semantic roles)
4. Typography (families, weights, sizing hierarchy)
5. Elevation (depth strategy)
6. Components (named by what you see)
7. Motion (easing, speed, animation style, signature patterns)
8. Do's and Don'ts
9. What NOT to Do (explicit anti-patterns)
10. Assets (map every file to what it shows and where it appears)
Includes the Notion example from the current SKILL.md (it's excellent — keep it).
Word guidance: aim for thorough coverage, approximately 2000-3000 words.
Rules: use exact HEX values from tokens.json, be factual not poetic, name components specifically.
#### phase-3-direct.md (~120 lines)
Creative direction workflow:
1. Read visual-styles.md (from hyperframes/ skill) — pick a style anchor
2. Choose shader transition FIRST (energy → shader mapping table, inline)
3. Write narration script FIRST (2.5 words/sec pacing, opening line is everything)
4. Generate TTS (HeyGen preferred → ElevenLabs → Kokoro fallback)
5. Transcribe for word-level timestamps
6. Map timestamps to scene plan (narration IS the timeline)
7. Print scene plan table (Scene | Duration | What viewer sees | What viewer feels | Assets | Transition | Narration)
Motion vocabulary table (SLAMS, CASCADE, FLOATS, etc.) — inline, not referenced.
Opening 2 seconds guidance — inline.
#### phase-4-build.md (~150 lines)
Composition building:
1. The index.html scaffold already has shader transitions wired — modify, don't build
2. One complete inline example: Cross-Warp Morph between two scenes with GSAP driving `u_progress`
3. "For other shaders, see `hyperframes/references/transitions/shader-transitions.md`" (link, not inline)
4. Asset plan per scene (list every file/URL you'll embed)
5. Scene composition rules: use real assets, EXACT colors from DESIGN.md, @font-face with captured fonts
6. Wire audio: narration.wav on root track, captions.html on parallel track
7. Scene durations from narration timestamps, not guessing
Key rules repeated at bottom:
- Every element must DO something (mid-scene activity)
- No `repeat: -1`
- Deterministic (no Math.random)
- Timeline registered to `window.__timelines`
---
### Part 3: Update Hyperframes Compose Skill's Visual Identity Gate
#### Current behavior (hyperframes/SKILL.md lines 24-38):
```
Check in this order:
1. DESIGN.md exists? → Read it
2. visual-style.md exists? → Read it
3. User named a style? → Generate MINIMAL DESIGN.md (4 fields)
4. None of the above? → Ask 3 questions, generate MINIMAL DESIGN.md
```
#### New behavior:
Options 1 and 2 stay the same. Options 3 and 4 change:
**Option 3 (user named a style or gave a topic):**
- Read visual-styles.md for the 8 named presets
- If a preset matches, use it as the foundation
- Generate a **full** DESIGN.md with all 10 sections, not 4
- The Style Prompt, Colors, Typography, and Motion come from the preset
- Components, Do's/Don'ts, What NOT to Do are derived from the style's principles
- Save as DESIGN.md in the project directory
**Option 4 (no style, no URL, just a topic like "astronomical discoveries"):**
- Ask 3 questions (keep current: mood, light/dark, brand references)
- But then generate a **full** DESIGN.md with all 10 sections
- Pick the closest visual style preset as a starting point
- Adapt colors, typography, motion to the topic
- The agent should research the topic briefly (web search if available) to inform visual choices
- Save as DESIGN.md in the project directory
The key change: **every path through the gate produces a full DESIGN.md**, not a minimal one. This ensures Prompt B ("astronomical discoveries") gets the same quality foundation as Prompt A ("stripe.com").
Update the gate text to replace the minimal DESIGN.md instruction with a reference to the full schema. The full schema lives in `website-to-hyperframes/references/phase-2-design.md` — the compose skill can reference it: "Generate a full DESIGN.md following the schema in the `/website-to-hyperframes` skill's phase-2-design.md reference."
---
### Part 4: Root CLAUDE.md Updates
- Update the skills table if skill names or descriptions change
- Update the "Rules" section to reference the new phase structure
- Remove any references to the old monolithic SKILL.md workflow
---
## What Stays the Same
- **hyperframes SKILL.md** — structure stays, only Visual Identity Gate options 3-4 updated
- **All hyperframes references** — house-style.md, motion-principles.md, transitions/, fonts.md, captions.md, patterns.md, etc.
- **Capture pipeline logic** — Puppeteer two-pass, animation cataloger, asset downloader, token extractor, Lottie detection, shader extraction, video manifest, section splitter
- **28 existing captures** — keep their DESIGN.md files (agent-written, good quality)
- **Narration-first workflow** — elevated from buried instruction to hard gate
## Not In Scope
- Lint rule for shader presence (future PR)
- Rewriting video-recipes.md beyond minor trim
- Changes to rendering engine, producer, or studio packages
- Re-running captures to regenerate data
- Building sub-agent orchestration framework (document the pattern, agent follows naturally)
- Music/sound effects integration (the compose skill already supports `<audio>` elements — the agent can source royalty-free music and layer it)
---
## Success Criteria
A fresh Claude Code session handles both prompts and produces shocking quality:
**Prompt A (with URL):**
> "Create me a 24-28 second product launch video of my website https://stripe.com"
**Prompt B (from scratch):**
> "Create me a video about the most exciting astronomical discoveries for the past 20 years with visuals, voiceover, music and some sound effects"
**"Shocking good quality" means:**
- Shader transitions between scenes (not CSS fades, not fade-to-black)
- Real brand assets / sourced visuals (not colored rectangles or placeholder text)
- Narration that sounds human, timed to the millisecond
- Every element moves with purpose (5-layer system, mid-scene activity throughout)
- Opening 2 seconds that stop the scroll
- Typography and color that match the brand / topic precisely
- The "What NOT to Do" constraints from DESIGN.md are visibly respected
- A viewer cannot tell this was made from a URL + one sentence
---
## File Change Summary
| Action | File |
|--------|------|
| DELETE | `packages/cli/src/capture/designMdGenerator.ts` |
| EDIT | `packages/cli/src/capture/index.ts` (remove AI key block, add asset descriptions, improve scaffold) |
| EDIT | `packages/cli/src/capture/agentPromptGenerator.ts` (remove hasDesignMd, HEX colors) |
| EDIT | `packages/cli/src/capture/tokenExtractor.ts` (RGB→HEX conversion) |
| EDIT | `packages/cli/package.json` (remove @anthropic-ai/sdk, @google/genai) |
| REWRITE | `skills/website-to-hyperframes/SKILL.md` (slim orchestrator) |
| CREATE | `skills/website-to-hyperframes/references/phase-1-understand.md` |
| CREATE | `skills/website-to-hyperframes/references/phase-2-design.md` |
| CREATE | `skills/website-to-hyperframes/references/phase-3-direct.md` |
| CREATE | `skills/website-to-hyperframes/references/phase-4-build.md` |
| DELETE | `skills/website-to-hyperframes/references/visual-styles.md` (duplicate) |
| EDIT | `skills/hyperframes/SKILL.md` (Visual Identity Gate options 3-4) |
| EDIT | `CLAUDE.md` (update skill references) |