From a34a6687b7e95318b8c54c135dd08f90f37d3ae0 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 16:06:46 -0700 Subject: [PATCH 1/4] feat(skills): require design.md first via visual-style skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make design.md a prerequisite for every composition, not an optional picker step. Step 0a is now "Design system" and must complete before prompt expansion (Step 0b), because expansion output is supposed to cite design.md's palette, typography, and motion energy — expanding first produces generic breakdowns the downstream agents then ignore. Resolution order for design.md: 1. Existing design.md in project root → use as-is 2. Invoke /visual-style skill in Create mode → save output to design.md 3. references/design-picker.md (fallback if user prefers pre-built) 4. house-style.md defaults (only with explicit "skip design") Also expand prompt-expansion.md's scene-breakdown spec to require 2–5 decoratives per scene drawn from house-style's list, each using design.md's palette values. Spells out that "single ambient motion" means one looping motion applied to these decoratives, not one element total — this was the p1 regression root cause in the eval run. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/SKILL.md | 29 +++++++++++++------ .../references/prompt-expansion.md | 28 ++++++++++-------- 2 files changed, 36 insertions(+), 21 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 390504fbc..c729a559a 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -9,23 +9,34 @@ HTML is the source of truth for video. A composition is an HTML file with `data- ## Approach -### Step 0a: Prompt expansion +### Step 0a: Design system (always required, first) -If the user's prompt lacks scene-by-scene structure, expand it into a full production prompt first. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. Present the expanded prompt to the user for approval before proceeding. +Run this BEFORE prompt expansion. Design direction shapes expansion output (atmosphere layers, motion energy, typography), so expanding first produces generic breakdowns that later ignore the palette. -### Step 0b: Design system +Every composition MUST have a `design.md` in the project root before construction. It is the source of truth for colors, typography, motion, spacing, and mood — every later step (expansion output, scene subagents, assembler) reads it. -Check for a `design.md` in the project root. If one exists, read it — it defines colors, typography, motion, and mood for all compositions in this project. +**Resolution order:** -If none exists, **ask the user:** +1. **Exists** — if `design.md` is already in the project root, read it and proceed to Step 1. +2. **Build one via the `visual-style` skill** — invoke the `/visual-style` skill (Skill tool, `skill: "visual-style"`) in "Create" mode. Ask the user the batched vibe questions the skill prescribes (mood, palette, typography, energy), then have it emit a full design spec. Save the result to `design.md` in the project root. +3. **Interactive picker (fallback)** — if the user prefers pre-built options instead of a guided build, read [references/design-picker.md](references/design-picker.md) and serve the picker. +4. **House-style defaults (last resort)** — only if the user explicitly says "skip design" or this is a tiny edit to an existing composition without a design.md. In that case, follow [house-style.md](./house-style.md) and write its palette + typography into `design.md` so downstream steps have a file to read. -> "Want to pick a visual style before we build? (yes = design picker, no = use defaults)" - -If yes → read [references/design-picker.md](references/design-picker.md) for the full picker workflow. If no → follow [house-style.md](./house-style.md) defaults. +Do NOT begin prompt expansion or scene authoring without a `design.md`. Design direction affects expansion output (atmosphere layers, motion energy, typography choices) — expansion before design produces generic scene breakdowns that later ignore the palette. ### Using design.md during construction -If a `design.md` exists (from Step 0b or provided by the user), it is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. +`design.md` is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. + +**Passing design.md downstream:** + +- **Prompt expansion** — include the palette, typography, and mood/energy from design.md in the expanded prompt's style block. Every scene breakdown should reference the palette and note which decorative motifs belong. +- **Scene subagents** — each subagent receives the full `design.md` (or a tight summary of its values). Fragment authors apply only these values; house-style decoratives are added WITHIN the design.md's palette constraints. +- **Assembler** — reads design.md to populate any global CSS variables in the scaffold. + +### Step 0b: Prompt expansion + +If the user's prompt lacks scene-by-scene structure, expand it into a full production prompt. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. The expanded prompt must cite design.md's palette, typography, and mood — not repeat them as generic defaults. Present the expanded prompt to the user for approval before proceeding. ### Step 1: Plan diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index ece0bc2b3..8aab52241 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -1,6 +1,10 @@ # Prompt Expansion -Expand a sparse user prompt into a full production prompt before proceeding with design and construction. +Expand a sparse user prompt into a full production prompt. Runs AFTER `design.md` is established (Step 0a) — the expansion consumes design.md and produces output that cites its palette, typography, and motion energy. + +## Prerequisites + +- `design.md` exists in the project root. If not, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. ## When to expand @@ -14,18 +18,18 @@ A prompt needs expansion if it lacks: scene-by-scene structure, specific visual Expand into a full production prompt with these sections: -1. **Title + style block** — genre, visual style, format, color direction, typography direction, mood, audio feel -2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style +1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values. +2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases). 3. **Scene-by-scene breakdown** — for each scene: - Time range and title - - Specific visual elements (not generic — "alien claw slides across wall" not "scary things happen") - - Text/typography that appears with animation style - - Background, midground, foreground layer descriptions + - **Background layer (REQUIRED, 2-5 decoratives)** — pick from house-style's decorative list (radial glow / oversized ghost type / accent hairline rules / grid patterns / thematic decoratives) AND confirm each uses design.md's palette values. "Single ambient motion per scene" means one LOOPING MOTION applied to these decoratives, not one element total. + - **Midground (content)** — specific visual elements (not generic — "alien claw slides across wall" not "scary things happen") + - **Foreground (text + accents)** — text/typography with animation style - Transition to next scene as a specific morph (what object becomes what) -4. **Recurring motifs** — visual threads that appear across multiple scenes -5. **Transition rules** — every scene-to-scene connection described as object morphing -6. **Pacing curve** — where energy builds, peaks, and releases -7. **Negative prompt** — what to avoid +4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography. +5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level. +6. **Pacing curve** — where energy builds, peaks, and releases. +7. **Negative prompt** — what to avoid. Always include: "no colors outside design.md palette, no fonts outside design.md typography pair". ## Output @@ -35,6 +39,6 @@ Tell the user: > "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md` > -> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed to the design picker." +> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed." -Only move to the design system step after the user approves or says to continue. +Only move to construction after the user approves or says to continue. From e0619625547b845ff0f17089f1b5d0169534c857 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 16:32:27 -0700 Subject: [PATCH 2/4] docs(skills): move decorative rule to single source in house-style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prompt-expansion.md was re-stating house-style rules in its scene breakdown and negative-prompt sections. That's duplication — if house-style changes, expansion drifts. Fix: - Prerequisites now tell the expansion step to read house-style.md and design.md before generating. The expansion generates output that conforms to those rules; it doesn't re-state them. - Scene breakdown template names the three layer slots (background/midground/foreground) without re-stating the decorative-count rule or palette-compliance rule. - Negative-prompt no longer hard-codes palette/font rules — those live in design.md and house-style.md where they belong. - The "single ambient motion doesn't mean single element" clarification moves to house-style.md where the base rule lives, so any reader sees it next to the rule it clarifies. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/house-style.md | 2 ++ .../hyperframes/references/prompt-expansion.md | 17 +++++++++++------ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md index 6d5161552..fa7235067 100644 --- a/skills/hyperframes/house-style.md +++ b/skills/hyperframes/house-style.md @@ -44,6 +44,8 @@ Ideas (mix and match, 2-5 per scene): All decoratives should have slow ambient GSAP animation — breathing, drift, pulse. Static decoratives feel dead. +**Decorative count vs motion count.** The "2-5 per scene" count refers to decorative _elements_. If a project's `design.md` says "single ambient motion per scene", it means one looping motion applied to these decoratives (a shared breath/drift/pulse) — not one element total. A scene with 4 decoratives sharing one breathing motion is correct; a scene with 1 decorative is under-dressed. + ## Motion See [references/motion-principles.md](references/motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries. diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index 8aab52241..a8ed8a945 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -4,7 +4,12 @@ Expand a sparse user prompt into a full production prompt. Runs AFTER `design.md ## Prerequisites -- `design.md` exists in the project root. If not, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. +Read before generating: + +- `design.md` — palette, typography, energy, mood. The expansion quotes these values; it does not invent any. +- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion does NOT re-state those rules; it writes output that conforms to them. + +If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. ## When to expand @@ -20,16 +25,16 @@ Expand into a full production prompt with these sections: 1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values. 2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases). -3. **Scene-by-scene breakdown** — for each scene: +3. **Scene-by-scene breakdown** — for each scene, three layers: - Time range and title - - **Background layer (REQUIRED, 2-5 decoratives)** — pick from house-style's decorative list (radial glow / oversized ghost type / accent hairline rules / grid patterns / thematic decoratives) AND confirm each uses design.md's palette values. "Single ambient motion per scene" means one LOOPING MOTION applied to these decoratives, not one element total. - - **Midground (content)** — specific visual elements (not generic — "alien claw slides across wall" not "scary things happen") - - **Foreground (text + accents)** — text/typography with animation style + - Background layer — list the decoratives (per the prerequisite rules) + - Midground — the specific content elements (not generic: "alien claw slides across wall" not "scary things happen") + - Foreground — text and typography with their animation style - Transition to next scene as a specific morph (what object becomes what) 4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography. 5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level. 6. **Pacing curve** — where energy builds, peaks, and releases. -7. **Negative prompt** — what to avoid. Always include: "no colors outside design.md palette, no fonts outside design.md typography pair". +7. **Negative prompt** — what to avoid for this specific composition. ## Output From b3780f97a402f03e0e3dd9109d455fa42f189f28 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 16:53:26 -0700 Subject: [PATCH 3/4] feat(skills): always run prompt expansion, not gated on sparseness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expansion is not about lengthening a short prompt — it's about grounding the user's intent against design.md and house-style.md and producing a consistent intermediate that every downstream agent reads the same way. Even a fully-detailed user prompt benefits: - Color words ("warm", "cinematic") → resolved to design.md hex values - Decorative layers the user forgot → added explicitly per house-style - Vague transitions → specified as morph operations with duration/ease tied to design.md energy - Per-scene timing → verified to sum to stated total The eval showed p5 (fully-expanded brief) skipping this step and missing the benefit. When expansion runs on an already-expanded prompt, it's mostly pass-through, but it still binds the prompt to design.md and house-style — which is the contract downstream steps depend on. Single-scene compositions and trivial edits are the only exceptions. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/SKILL.md | 6 +++++- .../hyperframes/references/prompt-expansion.md | 17 ++++++++++++----- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index c729a559a..85e6bbcf3 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -36,7 +36,11 @@ Do NOT begin prompt expansion or scene authoring without a `design.md`. Design d ### Step 0b: Prompt expansion -If the user's prompt lacks scene-by-scene structure, expand it into a full production prompt. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. The expanded prompt must cite design.md's palette, typography, and mood — not repeat them as generic defaults. Present the expanded prompt to the user for approval before proceeding. +Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against `design.md` and `house-style.md` and produces a consistent intermediate that every downstream agent — scene subagents, assembler, lint — reads the same way. + +Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. The expanded prompt quotes design.md's palette hex values, typography pair, and motion energy verbatim — it does not re-state generic defaults. Present the expanded prompt to the user for approval before proceeding. + +If the user's prompt is already scene-by-scene, the expansion is mostly pass-through, but it still binds the prompt to design.md and house-style — which is the contract the downstream steps depend on. ### Step 1: Plan diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index a8ed8a945..87f5c87fc 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -1,6 +1,8 @@ # Prompt Expansion -Expand a sparse user prompt into a full production prompt. Runs AFTER `design.md` is established (Step 0a) — the expansion consumes design.md and produces output that cites its palette, typography, and motion energy. +Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way. + +Runs AFTER `design.md` is established (Step 0a). The expansion consumes design.md and produces output that cites its palette, typography, and motion energy verbatim. ## Prerequisites @@ -11,13 +13,18 @@ Read before generating: If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore. -## When to expand +## Why always run it + +A detailed user prompt can still be ambiguous or under-specified in ways only the expansion step surfaces: -A prompt needs expansion if it lacks: scene-by-scene structure, specific visual elements per scene, transition descriptions, or timing. +- The user's color words ("warm", "cinematic") get resolved to design.md's exact hex values. +- Decorative layers that the user forgot to mention get added explicitly, per house-style. +- Transitions vaguely described ("cut", "crossfade") get specified as morph operations with duration and ease tied to design.md's energy. +- Per-scene timing gets verified to sum to the stated total. -**Sparse:** "make me a trailer about a killer alien on a spaceship" or "coconut water promo, tropical, 45 seconds" +If the user's prompt is already scene-by-scene, the expansion is shorter and largely pass-through, but it still binds the prompt to design.md and house-style — which is the contract the scene subagents and assembler depend on. -**Already expanded:** Has numbered scenes with timing, specific elements, transition rules, and animation direction — skip this step. +**Do not skip.** Single-scene compositions and trivial edits are the only exceptions. ## What to generate From fc45778805409698809902144e0de9f1d9d7ab75 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 17:44:58 -0700 Subject: [PATCH 4/4] feat(skills): expansion is never pass-through, always enriches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The p2 eval (sparse prompt, 6 scenes) was dense and alive because expansion had to invent atmosphere and micro-details to fill in the 1-sentence input. The scene subagents then built from that rich spec. p3/p5/p6 (detailed prompts) produced muted output because the expansion was framed as "largely pass-through" for already-detailed inputs. Scene subagents got a thin brief and built thin output. Make expansion always enrich, never pass-through: - Every user prompt is a *seed*, not a spec. Expansion takes what the user wrote and adds atmosphere, ambient motion, micro-details. User's content stays; expansion builds on top. - Scene-by-scene breakdown now enumerates 5 required fields per scene: background (2-5 decoratives with ambient motion), midground, foreground, micro-details (2-3 per scene: registration marks, tick indicators, monospace labels, background data streams, grid patterns), transition morph. - Framing note: the quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. If expansion front-loads the richness, every scene subagent builds from a rich brief; every scene comes out alive. Addresses user feedback after the eval review: "the only significant difference I see is in p2" — because p2 was the only case where expansion had to enrich. Making enrichment mandatory everywhere. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../references/prompt-expansion.md | 31 ++++++++++++------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md index 87f5c87fc..c33b27f77 100644 --- a/skills/hyperframes/references/prompt-expansion.md +++ b/skills/hyperframes/references/prompt-expansion.md @@ -15,16 +15,22 @@ If `design.md` doesn't exist yet, run Step 0a (Design system) first. Expansion w ## Why always run it -A detailed user prompt can still be ambiguous or under-specified in ways only the expansion step surfaces: +**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly. -- The user's color words ("warm", "cinematic") get resolved to design.md's exact hex values. -- Decorative layers that the user forgot to mention get added explicitly, per house-style. -- Transitions vaguely described ("cut", "crossfade") get specified as morph operations with duration and ease tied to design.md's energy. -- Per-scene timing gets verified to sum to the stated total. +Even a detailed 7-scene brief lacks things only the expansion adds: -If the user's prompt is already scene-by-scene, the expansion is shorter and largely pass-through, but it still binds the prompt to design.md and house-style — which is the contract the scene subagents and assembler depend on. +- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them. +- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead. +- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request. +- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target. +- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands. +- **Exact hex values, typography parameters, ease choices** from design.md — no vagueness left for the scene subagent to guess. -**Do not skip.** Single-scene compositions and trivial edits are the only exceptions. +Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive. + +The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one. + +**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions. ## What to generate @@ -32,12 +38,13 @@ Expand into a full production prompt with these sections: 1. **Title + style block** — cite design.md's palette (bg/fg/accent hex values), typography pairing, energy level, and mood. Do NOT invent a palette — quote the design.md values. 2. **Global animation rules** — parallax layers, micro-motion requirements, kinetic typography, pacing rules, transition style. Align energy with design.md (calm → slow eases, high energy → snappy eases). -3. **Scene-by-scene breakdown** — for each scene, three layers: +3. **Scene-by-scene breakdown** — for each scene, enumerate: - Time range and title - - Background layer — list the decoratives (per the prerequisite rules) - - Midground — the specific content elements (not generic: "alien claw slides across wall" not "scary things happen") - - Foreground — text and typography with their animation style - - Transition to next scene as a specific morph (what object becomes what) + - **Background layer** — list the 2–5 decoratives (from house-style's list) with exact positioning, opacity values from design.md, and the ambient motion each uses (breath, drift, pulse, orbit). This is almost always richer than what the user's prompt specified — the user rarely lists atmosphere, you add it. + - **Midground** — content elements (not generic: "alien claw slides across wall" not "scary things happen"). Keep everything the user specified; add what's missing. + - **Foreground** — text, typography, animation style per text element. Type sizes and weights quoted from design.md. + - **Micro-details** — registration marks, tick indicators, monospace coord/meta labels, typographic accents, background data streams, grid patterns. These are what make a scene feel real. The user's prompt never lists them; expansion adds at least 2–3 per scene. + - **Transition out** — specific morph (what object becomes what, duration, ease), not just "cut" or "crossfade" 4. **Recurring motifs** — visual threads that appear across multiple scenes, always drawn from design.md's palette and typography. 5. **Transition rules** — every scene-to-scene connection described as object morphing. Transition duration/ease should match design.md's energy level. 6. **Pacing curve** — where energy builds, peaks, and releases.