feat(skills): require design.md first via visual-style skill#549
feat(skills): require design.md first via visual-style skill#549vanceingalls wants to merge 4 commits intomainfrom
Conversation
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
This stack of pull requests is managed by Graphite. Learn more about stacking. |
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Staff review
TL;DR: Intent is right (design-first → expand → build is the correct pipeline order), and references/prompt-expansion.md is well-built. But this PR ships a second design gate next to the existing <HARD-GATE> "Visual Identity Gate" already in SKILL.md (lines 56–73 on main) — different filename casing, different resolution order, no reconciliation. Plus a broken file reference, an undeclared external skill dependency, and significant prose duplication.
Blocking
1. Two competing design gates in one file. After this PR, SKILL.md contains both the new "Step 0a" (design.md lowercase, 4-path resolution) and the existing <HARD-GATE> "Visual Identity Gate" (DESIGN.md uppercase, different 4-path resolution). They conflict on:
- Filename casing —
design.mdvsDESIGN.md. On Linux (where the renderer runs) these are different files; on macOS they collide unpredictably. Existing projects withDESIGN.mdwon't satisfy Step 0a's path 1. - Bootstrap source — new gate uses external
/visual-styleskill +references/design-picker.md+house-style.md; old gate uses in-repovisual-styles.mdpresets + 3-question fallback. - Hardness — old one is wrapped in
<HARD-GATE>, new one is just a step.
Pick one. If new replaces old, delete the <HARD-GATE> block in this PR. Align casing — DESIGN.md (uppercase) is already established.
2. Broken reference. SKILL.md:22 (new) links to references/design-picker.md for path 3. That file is not in the diff and not in the tree. Path 3 is unreachable.
3. Undeclared external dependency. Step 0a path 2 invokes /visual-style, which lives at /home/ubuntu/.agents/skills/visual-style/ — a separately-installed skill. OSS users installing via npx skills add heygen-com/hyperframes won't have it. No graceful fallback.
4. Filename + schema mismatch with the dependency. /visual-style natively produces visual-style.md (structured YAML: style_prompt_full, colors[], typography, etc.). The PR says save it as design.md — but never defines a design.md schema. Downstream subagents are told to "use only the values it defines" without knowing what fields are guaranteed. references/prompt-expansion.md:35 even references "ease choices from design.md" — visual-style.md doesn't carry easings. Either define the schema or the contract is fictional.
Significant
5. Duplicated prose. "Design direction shapes/affects expansion output (atmosphere layers, motion energy, typography)..." appears twice almost verbatim (SKILL.md:14 and :25). Drop one.
6. SKILL.md is the hot path. This file loads on every hyperframes invocation. The PR adds ~30 lines. Per skill-creator principles: keep SKILL.md to essentials, push detail into references/. The "Using design.md during construction" subsection (passing-design-downstream bullets) belongs in a reference file.
7. SKILL.md and prompt-expansion.md contradict each other on pass-through.
SKILL.md:43(new): "If the user's prompt is already scene-by-scene, the expansion is mostly pass-through..."references/prompt-expansion.md:24: "Do not skip. Do not pass through."
The reference is more correct (the rest of prompt-expansion.md argues forcefully against pass-through). Fix the SKILL.md sentence.
8. PR template is empty + no test plan. No "What/Why/How/Test plan." For a workflow change that gates every composition, please document at minimum:
- Run on a project with existing
DESIGN.md(uppercase) — confirms migration path. - Run on a fresh project with no design context — confirms
/visual-styleinvocation path. - "Small edit" run — confirms escape hatch fires.
- "Skip design" run — confirms last-resort path writes a usable file.
Smaller things
- Step numbering:
0a/0b/1is the visible scar of accreted edits. Renumber. house-style.mddecorative-count addition is a useful clarification but reads as a band-aid mid-section. Promote to a real subheader.prompt-expansion.mdwrites to.hyperframes/expanded-prompt.md— confirm nothing in the CLI/registry treats.hyperframes/as generated artifact directory that lint/build could clobber.- Behavioral cost on iteration: even with the "tiny edit" exception, the gate triggers on every fresh invocation. Consider an explicit shortcut:
existing design + single-element change → skip expansion entirely.
What this PR gets right
- Diagnosis is correct: ordering design → expansion → scenes is the right architecture; expanding before grounding produces generic breakdowns.
references/prompt-expansion.mdis well-structured: clear prerequisites, "why always run", per-section output spec, output destination, user handoff message. Good progressive disclosure.- Decorative-vs-motion clarification in
house-style.mdresolves a real ambiguity ("4 decoratives sharing one breathing motion is correct; 1 decorative is under-dressed" — concrete and memorable).
Recommended path
Block on (1)–(4). Reissue with: one gate not two, schema for design.md, explicit /visual-style dependency note + OSS fallback, the missing design-picker.md (or remove path 3), de-duplicated prose, real PR description and test plan. The reference file and house-style.md clarification can ship as-is.
2 participants
What
Brief description of the change.
Why
Why is this change needed?
How
How was this implemented? Any notable design decisions?
Test plan
How was this tested?