# w2h Skill — Steal+Adapt Plan (Sessions 17+) **Author:** Claude (Opus 4.7) for Ular Kimsanov **Drafted:** 2026-06-11 **Worktree:** `/Users/ularkimsanov/Desktop/hyperframes-w2h-v3` **Branch:** `feat/w2h-restructure-v3` --- ## The verify-first rule (NEW — applies to EVERY phase, EVERY task) Before starting ANY phase or task within a phase, I MUST: 1. **Read every related file in our worktree end-to-end** — the file I'm about to touch + every file it imports/references + every consumer downstream that would be affected. 2. **Read every upstream source I'm porting from end-to-end** — full file, not a snippet. `git show origin/feat/product-launch-v2:` for plv2 imports; `git show 995dbb4f:` for SFX-branch imports. 3. **Map the integration explicitly** — write down (in chat or in TodoWrite) which existing files will change, what their downstream consumers are, what the rollback looks like if it goes wrong. 4. **Only then start typing**. This rule exists because Sessions 13/15 made architectural changes (FRAME.md → no DESIGN.md) without re-reading enough downstream context, and the result was a session of wasted work + a revert. Verify-first prevents that pattern. **No exception. No "this one's small."** Especially when stealing patterns from plv2 — that codebase was written for a different identity and copying without reading the surrounding context produces subtle drift. --- ## Locked decisions (user-confirmed 2026-06-11) 1. **Music command shape:** `hyperframes music` (Option A — parallel command, cleaner UX). 2. **Bundled SFX deletion:** YES — `skills/website-to-hyperframes/assets/sfx/*` (20 mp3s + manifest.json + CREDITS.md) gets removed as part of the SFX-branch merge. The runtime-catalog flow replaces them. 3. **Branch audit before starting:** quick scan for any `feat/music-*` / `feat/*-audio-*` branches that might already exist. If nothing else relevant, proceed to PHASE 0a. --- ## Identity preservation (the non-negotiable spine) Everything below is filtered through this. If a steal violates this, it's adapt-not-copy or skip. Our `website-to-hyperframes` skill is: 1. **URL-in / video-out, capture-first** — start from a real website; the video draws from REAL captured assets (colors, fonts, components, photos, SVGs). No "pick a preset" upfront. 2. **Brand-fidelity over genre purity** — accepts ANY video type from the same URL (social ad, product tour, brand reel, launch teaser, feature announcement). Not launch-biased. 3. **VIDEO, not webpage rebuilt in divs** (Step -1) — cinematic grammar: framing, depth, camera, scale. 4. **Linear 7-step flow** with autonomous-mode exception, cell-experiment-tested (33+ real runs). 5. **Creative Tension Principle** answered FROM the captured assets, not from a lookup table. `product-launch-video` (plv2) is a RELATED-BUT-DIFFERENT skill (launch-narrative oriented, preset-based). We mine its quality patterns; we do NOT adopt its identity. --- ## Plan summary (sequenced, ~12-15 hr total) | Phase | What | Cost | Identity risk | |---|---|---|---| | **0** | Merge `feat/sfx-audio-search` (commit `995dbb4f`) + add music parity | ~2-3 hr | none — pure capability addition | | **A** | Universal quality gates: `derive-context-pack` + `check-compositions` + `validate` | ~3-4 hr | none | | **B** | Worker prompt rigor: absorb `hyperframes-scene` + `hyperframes-finalize` into our refs | ~2-3 hr | none | | **C** | `prep.mjs` full upgrade from stub | ~3-4 hr | low | | **D** | Story craft adapt: hook taxonomy + named-pause + 75%-exit + OPTIONAL archetypes | ~2-3 hr | medium (kept primary narrative-arc, archetypes are secondary) | | **E** | Deferred / skip (presets, phases, build-design, audio.mjs, etc.) | n/a | see § E | **Checkpoint pauses:** after Phase 0, A, B (identity-adjacent), and D. User reviews before next phase. --- ## PHASE 0 — Merge `feat/sfx-audio-search` + music parity **Why first:** the branch REMOVES `assets/sfx/*` (20 mp3s + manifest.json) and switches the skill to runtime catalog search. Doing this before Phase A means our new scripts (PHASE A) don't get written against soon-to-vanish bundled-SFX assumptions. ### 0a — Manual file-by-file merge of commit `995dbb4f` The cherry-pick can't auto-merge because we modified the same files in sessions 13/16. Applying manually: **Clean adds (no conflict — apply verbatim):** - `packages/cli/src/commands/sfx.ts` (dispatcher) - `packages/cli/src/commands/sfx/{add,analyze,analyze.test,auth,catalog-manifest,catalog-manifest.test,inspect,list,search,state}.ts` (10 files) - `skills/hyperframes/references/sound-effects.md` (183 lines, the new reference doc) - `packages/cli/src/cloud/_gen/{client,types}.ts` (regenerated cloud client — `AudioContentType = "music" | "sound_effects"` now exposed) - `packages/cli/src/cli.ts` (register sfx subcommand — light edit) - `packages/cli/src/help.ts` (add sfx help-group entry) - `skills/hyperframes/SKILL.md` (mention SFX in description) - `skills/hyperframes/references/beat-direction.md` (link sound-effects.md) - `skills/hyperframes/references/techniques.md` (light updates — w2h-side conflict possible from our M3 work; merge by hand) - `skills/hyperframes/references/video-composition.md` (light update) **Deletes:** - `skills/website-to-hyperframes/assets/sfx/*` — all 20 mp3 files + CREDITS.md + manifest.json. The manifest swap I did earlier today (97 lines of agent-facing descriptions) becomes moot — descriptions live in the HeyGen catalog now. **Real conflicts (resolve thoughtfully — read commit's intent + our state):** - `skills/website-to-hyperframes/references/step-3-storyboard.md` — commit replaces "use bundled SFX from `sfx/`" with "search the catalog when the storyboard names a beat that needs SFX." Our session-13/16 edits to this file (FRAME.md revert prose + file tree) need to coexist with the new SFX flow. - `skills/website-to-hyperframes/references/step-5-build.md` — commit replaces the `## 1. Copy SFX to project` section with `## 1. Search + add SFX from catalog`. Our session-13/16 edits (landmines + assembler section + dispatch prompt template) need to coexist. ### 0b — Music parity The cloud API already exposes `AudioContentType = "music" | "sound_effects"`. Options: - **Option A (cleaner):** add a new `hyperframes music` command — parallel CLI to `sfx`, reuses analysis/auth/state modules. - **Option B (lighter):** add a `--type music` flag to `hyperframes sfx`. Smaller diff. Confusing UX (user expects music to be its own thing). **Recommendation: A.** Music's discovery flow is different from SFX (bed-style, longer, ducks under VO) and deserves its own command surface. The implementation reuses 90% of the SFX command code. ### 0c — `references/background-music.md` (new, ~80 lines) - When music helps (brand reels, atmospheric pieces) vs hurts (most product demos) - Volume hierarchy: BGM 0.4–0.6 under VO 1.0; pure-music 0.7–0.9 - Duck-on-narration rule (drop BGM 6-10 dB when VO is active) - Motif rule for music (one bed per scene, not stacked) - Search prompts that work (semantic, by feel: "moody ambient", "upbeat lo-fi", "tense synth pad") ### 0d — Smoke verification - `npx tsx packages/cli/src/cli.ts sfx list` — works, shows catalog families - `npx tsx packages/cli/src/cli.ts sfx search "whoosh"` — works (prompts for free key if missing) - `npx tsx packages/cli/src/cli.ts music search "ambient pad"` — works - 88+ tests still pass - `bun test packages/cli/src/commands/sfx/*.test.ts` — runs the bundled tests **Pause for user review** before Phase A. --- ## PHASE A — Universal quality gates ### A1 — `derive-context-pack.mjs` + `lib/capture-meta.mjs` (~30 min) - Port `scripts/derive-context-pack.mjs` (266 LOC) verbatim into `skills/website-to-hyperframes/scripts/` - Port `scripts/lib/capture-meta.mjs` (39 LOC) verbatim - Adapt: rename `context_pack.md` output to live at `capture/context_pack.md`; reference `capture/extracted/*` paths consistently - Wire into `step-0-capture.md` as a Step 0.5 (auto-runs after `capture` completes) - Wire into beat dispatch packet — workers read `capture/context_pack.md` instead of 5 separate JSON files ### A2 — `check-compositions.mjs` (~1 hr) - Port `scripts/check-compositions.mjs` (503 LOC) - Adapt selectors for our beat naming: `b-*` (we use this) vs plv2's `s-*` - Drop any plv2-specific wrapper-ancestor checks that don't apply - Wire into `preflight-finalize.mjs` (already exists, ported in Session 7) as a NEW gate before lint - Smoke against cell-A airbnb fixture ### A3 — `validate.mjs` (~1 hr) - Port `scripts/validate.mjs` (717 LOC) — dispatcher with `narrator` + `section` subcommands - Adapt schemas: - plv2's `narrator_scripts.json` → our `SCRIPT.md` (markdown, not JSON — schema = "must have hook line + 3-7 beats + CTA closer") - plv2's `section_plan.md` → our `STORYBOARD.md` (validate beat count matches estimated duration / total ≤ 60s for social / etc.) - Wire into Step 3 (post-storyboard) and Step 4 (post-script) as self-validation loops ### A4 — Smoke + verification - All 4 new scripts pass `node --check` - 88+ tests still pass - Run `check-compositions` against an existing cell-A fixture, verify it surfaces realistic issues **Pause for user review** before Phase B. --- ## PHASE B — Worker prompt rigor ### B1 — Absorb `hyperframes-scene.md` into `beat-builder-guide.md` (~1.5 hr) Read plv2's `agents/hyperframes-scene.md` (436 LOC). Extract patterns and merge with our existing `beat-builder-guide.md` (375 LOC): - **Pre-write cheat sheet** — our 6 items; plv2's 4 are sharper. Merge to 5-7 best. - **14 numbered constraints** — our `## Rules` block has ~15 rules; plv2 has 14 numbered. Reconcile: keep ours' identity (continuity-heavy w2h) but adopt plv2's: - GSAP transform alias whitelist (`xPx/yPx/sx/sy/rot`) - CSS-baked vs GSAP transform mutual-exclusion rule - Macro-camera scale-headroom (`maxScale = 0.88 * W / r.width`) - Primary-handoff-before-enter rule - **Tier-A shared-element bridge protocol** — w2h doesn't have multi-act bridges in the plv2 sense; SKIP wholesale. But the underlying *element-handoff* protocol (when a logo or card carries between beats) is useful — adapt. - **Skip:** the "scene wall-off" framing. w2h is continuity-heavy — workers CAN read sibling beat files. Our current rule stays. ### B2 — Absorb `hyperframes-finalize.md` Step 3.5 into `step-6-validate.md` (~1 hr) Read plv2's `agents/hyperframes-finalize.md` (251 LOC). Extract: - **Step 3.5 — Mandatory Visual Inspection Checklist** (5 categories): illegibility / out-of-bounds / competing-primaries / cramped-frame / seam-jank. Direct port — these failure modes are universal across video genres. - **Brief-digest fast-path** — `preflight_clean===true` → skip detailed read. Adopt — saves time when gates clean. - **Edit-ready `edit_old`/`edit_new` triage** rule — adopt. Mechanically apply, don't re-derive. - **The framing line** quoted verbatim: *"the eye is fragile (rate-limit prone, end-of-pipeline, subjective), so a structured pass over five concrete failure categories matters more than freeform 'does it look right.'"* ### B3 — Verification - Both reference files re-parse cleanly - 88+ tests still pass - Word-count check: didn't bloat by more than 30% **Pause for user review** before Phase C — this is identity-adjacent (worker contract changes; user should eyeball). --- ## PHASE C — `prep.mjs` full upgrade ### C1 — Read plv2's `prep.mjs` (1010 LOC) end-to-end + diff against our 280-LOC stub (~30 min) ### C2 — Port the upgrade (~2-3 hr) **Take:** - Anchor-walk through STORYBOARD.md (replaces our regex extraction) - Per-beat `start_s` / `estimatedDuration_s` / `duration_s` derivation - Transitions[] inference from storyboard prose - Asset / font / SFX copy into `public/` (we may need to adapt — we currently use `capture/assets/` not `public/`) - `font_face_css` aggregation (already in our stub but plv2's is more robust) - `voice` auto-detection (already in our stub) **Drop:** - cap=2 grouping (plv2-specific; we're single-group continuity-heavy) - Tier-A bridge logic (plv2-specific) - Multi-act dispatch packet ingestion (plv2-specific) ### C3 — Smoke against cell-A airbnb fixture (~30 min) - Replace existing stub - Confirm group_spec.json shape is unchanged from downstream consumer perspective (captions.mjs / assemble-index.mjs / preflight-finalize.mjs all still work) --- ## PHASE D — Story craft adapt-not-copy ### D1 — Universal extracts into `step-3-storyboard.md` (~1.5 hr) Add — these are genre-universal: - **Named hook types** (10): shocking-statistic / imagine / direct-address / pain-validation / visceral-metaphor / rhetorical-question / category-announcement / visual-spectacle / question-invitation / trend-positioning. Each with one-line "when to use" + example. - **"Stillness Before Climax"** named beat (0.3-0.75s pause between major action and confirmation). - **"Exit = 75% of Entry"** named rule (with reasoning: entry is deliberate; departure is swift but not abrupt). - **"Multiplicative breathing > yoyo"** rule (with the `scale = final * (1 + Math.sin(t*freq)*amp)` form). ### D2 — Optional archetypes (~1 hr) Add as a SECONDARY section in `step-3-storyboard.md`. NOT primary. Wording: *"If the user explicitly wants a launch-style or persuasion-heavy reel, these archetypes give the storyboard a named structural spine. For general videos (social ads, brand reels, demos, tours), the narrative-arc options above (Problem→Solution / Reveal / Demonstration / Vibe / Comparison) are the primary frame."* - **PAS** (Problem-Agitate-Solution) — when product solves a clear pain - **Future-Pacing** — when the brand sells aspirational outcome - **Demo-Loop** — when the product itself is the hook - **BAB** (Before-After-Bridge) — transformation story - **Feature-Benefit-Cascade** — when product has 3-5 distinct features ### D3 — SKIP - Plv2's persuasion-family framing (Pain/Authority/Social/Cognitive/Hedonic) — wrong identity layer; pulls us toward sales-copy. Our Step -1 says "viral hook" not "sales pitch." --- ## PHASE E — Deferred / skip with explicit reasoning | Item | Decision | Why | |---|---|---| | **19 style-presets** | DEFER | Philosophical question — capture-first vs preset-first is an identity question. Revisit AFTER Phases 0/A/B/C/D land. Possible future role: presets as FALLBACK when capture is thin (brochure-only sites), not the default path. | | **`audio.mjs` + `wait-bgm.mjs`** | DEFER | Detached BGM only matters when we generate music. Music search (PHASE 0b) covers the user's need for now. Revisit if music GENERATION is on the table. | | **`transitions.mjs` + `lib/transition-registry.mjs`** | DEFER | Our assembler handles transitions via `shader_transitions` field. Plv2's injection system is for THEIR `section_plan.md` flow. Not blocking. | | **`build-design.mjs`** (2941 LOC) + **`emit-chunks.mjs`** | SKIP | Tied to preset-scoring system. Adopt only if we change identity to preset-first. | | **`phases/` architecture** | SKIP | Linear 7-step flow is OUR pattern, just stabilized. Restructure risk doesn't pay off. | | **`site_dna` register** | DEFER | Depends on build-design. Useful concept but presupposes the preset system. | | **`check-bridge` subcommand** of transitions.mjs | DEFER | Plv2 uses for multi-act handoffs; we're single-act/continuity-heavy. Revisit if we add bridge-style transitions. | --- ## Sequence + checkpoints ``` PHASE 0 (sfx + music) → pause for user review PHASE A (quality gates) → pause for user review PHASE B (worker prompts) → pause for user review (identity-adjacent) PHASE C (prep.mjs) → continue PHASE D (story craft) → pause for user review (final) → ready for fresh-session real-URL test ``` After PHASE D, the worktree is at a state worth committing + pushing. We'll do that as a clean commit chain (probably 4-5 logical commits, one per phase + one for capture-layer work from earlier sessions). --- ## Open questions for the user BEFORE starting PHASE 0 1. **Music command shape** — `hyperframes music search` (parallel command, Option A) OR `hyperframes sfx search --type music` (single command with flag, Option B)? Recommend A. 2. **SFX file deletion** — are you OK with `skills/website-to-hyperframes/assets/sfx/` going away entirely? The branch's intent is clear (runtime catalog), but I want to confirm before deleting bundled assets. 3. **Order** — start PHASE 0 immediately on confirmation, OR audit any other related branches first (e.g. is there a `feat/music-...` or similar branch I should know about)? Confirm and I start PHASE 0a.