From a570adb5d92a757964cfaa0cd4de8f5455b2d7d0 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 15:01:29 -0700 Subject: [PATCH 1/2] docs(skills): clarify who runs the multi-scene dispatch pipeline The parallel fan-out in Phase 1 and Phase 2b requires the Agent/Task tool, which in Claude Code is only available to the top-level conversation agent. Dispatched subagents cannot spawn further subagents, so they can't drive the parallel pipeline. Add guidance in SKILL.md and references/multi-scene.md: - Top-level agent: run the full parallel pipeline - Nested subagent: author fragments sequentially, still run through the assembler and lint gates, note the constraint in the final report This surfaced in eval runs where the skill was invoked from a nested general-purpose subagent and the multi-scene dispatch silently fell back to serial authoring with no indication to the caller. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/SKILL.md | 2 ++ skills/hyperframes/references/multi-scene.md | 11 +++++++++++ 2 files changed, 13 insertions(+) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 7b80d80d1..412689364 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -43,6 +43,8 @@ For small edits (fix a color, adjust timing, add one element), skip straight to 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. +**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: 1. **Eval gate:** Validate each scene AS it arrives (format first, then content). Do NOT batch. Do NOT assemble until every scene has a `.eval.md` with PASS. diff --git a/skills/hyperframes/references/multi-scene.md b/skills/hyperframes/references/multi-scene.md index 80a9ca2b7..0b74d9ca2 100644 --- a/skills/hyperframes/references/multi-scene.md +++ b/skills/hyperframes/references/multi-scene.md @@ -2,6 +2,15 @@ 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. +## 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 Every scene file (`.hyperframes/scenes/sceneN.html`) must be a **fragment**, not a standalone document. The assembler splits on markers and injects verbatim — non-compliant files break assembly. @@ -74,6 +83,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): From fb5c4c35aff1d3332f7b126bbf184994182ae515 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 16 Apr 2026 16:02:34 -0700 Subject: [PATCH 2/2] feat(skills): lower multi-scene threshold from 4 to 2 scenes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Single-pass authoring under-decorates when a composition has more than one scene. The eval run showed p1 branch (3 scenes, single-pass with expansion) regressing vs main on background-layer density — the authoring agent followed the expansion's scene-element list literally and omitted the house-style atmosphere stack (ghost type, radial glow, framing rules). Giving each scene its own subagent via the multi-scene pipeline keeps per-scene density and decoration consistent, because each fragment agent reads house-style.md and applies "2–5 decoratives per scene" to its one scene without competing for context. The threshold is now "2 or more scenes". Single-pass is reserved for true one-scene compositions (title cards, standalone overlays). Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/hyperframes/SKILL.md | 6 +++--- skills/hyperframes/references/multi-scene.md | 4 +++- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 412689364..390504fbc 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -39,9 +39,9 @@ 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. @@ -345,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 0b74d9ca2..3d6dced06 100644 --- a/skills/hyperframes/references/multi-scene.md +++ b/skills/hyperframes/references/multi-scene.md @@ -1,6 +1,8 @@ # 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