diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 7b80d80d1..390504fbc 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -39,9 +39,11 @@ Before writing HTML, think at a high level: For small edits (fix a color, adjust timing, add one element), skip straight to the rules. -### Multi-scene builds (4+ scenes) +### Multi-scene builds (2+ scenes) -For compositions with 4 or more scenes, use the parallel subagent pipeline instead of a single pass. Read [references/multi-scene.md](references/multi-scene.md) for the full process. +For compositions with 2 or more scenes, use the parallel subagent pipeline instead of a single pass. Read [references/multi-scene.md](references/multi-scene.md) for the full process. The only single-pass builds are true one-scene compositions (title cards, single overlays, simple standalone scenes). + +**Who runs this pipeline:** The parallel dispatch MUST run from the top-level conversation agent (the one that received the user's `/hyperframes` invocation). That agent has the `Agent`/`Task` tool and can fan out. Dispatched subagents typically cannot spawn their own subagents, so if YOU are a nested subagent reading this skill, you cannot do the parallel fan-out — author fragments sequentially inline instead and still run through the assembler. Do not silently skip the pipeline; note the constraint and proceed serially. **BLOCKING GATES — these are NOT optional. Skipping any gate produces broken compositions.** The full details (eval steps, assembler usage, scaffold markers) are in [references/multi-scene.md](references/multi-scene.md). Summary: @@ -343,7 +345,7 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi - **[references/prompt-expansion.md](references/prompt-expansion.md)** — Expand sparse user prompts into full scene-by-scene production prompts. Read when the user gives a brief description instead of a detailed breakdown. - **[references/design-picker.md](references/design-picker.md)** — Create a design.md via visual picker. Read when no design.md exists and the user wants to create one. -- **[references/multi-scene.md](references/multi-scene.md)** — Multi-scene subagent pipeline: scaffold → parallel scene builds → streaming evaluation → assembly. Read for 4+ scene compositions. +- **[references/multi-scene.md](references/multi-scene.md)** — Multi-scene subagent pipeline: scaffold → parallel scene builds → streaming evaluation → assembly. Read for any composition with 2 or more scenes. ### Composition authoring diff --git a/skills/hyperframes/references/multi-scene.md b/skills/hyperframes/references/multi-scene.md index 80a9ca2b7..3d6dced06 100644 --- a/skills/hyperframes/references/multi-scene.md +++ b/skills/hyperframes/references/multi-scene.md @@ -1,6 +1,17 @@ # Multi-Scene Build Pipeline -For compositions with 4 or more scenes, build in phases instead of one pass. A single pass produces shallow results — detail drops as context fills with boilerplate. +For compositions with 2 or more scenes, build in phases instead of one pass. A single pass produces shallow results — detail drops as context fills with boilerplate, and the authoring agent tends to under-decorate later scenes. Giving each scene its own subagent keeps per-scene density and decoration consistent. + +Single-pass is reserved for true one-scene compositions: title cards, standalone overlays, single-clip animations. + +## Who runs this pipeline + +The parallel dispatch in Phase 1 and Phase 2b requires the `Agent`/`Task` tool. In Claude Code, only the **top-level conversation agent** (the one that received the user's `/hyperframes` invocation) has this tool. Dispatched subagents typically do not. + +- **If you're the top-level agent:** run the full pipeline. Fan out scene subagents and evaluator subagents in parallel. +- **If you're a nested subagent** (you were dispatched with a `/hyperframes` task): you cannot fan out further. Author all scene fragments sequentially yourself, strictly following the Scene Fragment Spec below, then run the assembler and lint gates. Do not silently skip the pipeline — note in your final report that parallel dispatch was unavailable and you built serially. + +The assembler, scaffold markers, fragment spec, and gates are the same either way; only the dispatch shape changes. ## Scene Fragment Spec @@ -74,6 +85,8 @@ No parsing, no stripping, no guessing. The scaffold and scene subagents have no dependency on each other — dispatch them all at the same time. Scene subagents don't read the scaffold; they only need the fragment spec, design.md, and their scene prompt section. Assembly waits for both to finish. +**Nested-subagent fallback:** If you don't have the dispatch tool (see "Who runs this pipeline" above), write the scaffold first, then write each scene fragment yourself one after another. Skip Phase 2b streaming evaluation — the assembler's format validation (Phase 3) is your gate instead. Note the constraint in your final report. + ### Scaffold Build the HTML skeleton yourself (or in a subagent):