Scene composition is the gate, not word counts

The skill exists so the LLM writes/rewrites each scene one at a time
with full attention on making it a complete scene composition — not so
it can hit a word target.

Prompts: the word-budget craft bullets are replaced by an 8-element
composition checklist (subject anchor, style anchor, continuity anchor,
blocking, camera, performance, physical texture, exit state) in both the
scene-writer PROMPT B (new SCENE COMPOSITION section) and the single-pass
prompt. Chase the elements, never a number; padding is as much a failure
as a thin one-liner.

Validator: hard word bands (<10s: 150-200, >=10s: 200-300) removed from
plan and fragment checks. Replaced by a thin-scene floor (100/120 words)
that only trips lazy output, plus a new continuity-anchor check — chained
fragments must open inside the previous end_state. No target band, no
upper limit; output lines say so.

SKILL.md/README: goal, Step 2, craft rules, table rows, and example
outputs updated to match. Suite, --check, chained fragment checks all
green.
This commit is contained in:
Z User 2026-10-29 19:13:27 +00:00
parent 83cc5145bf
commit f5575fa678
5 changed files with 128 additions and 66 deletions

View File

@ -11,11 +11,14 @@ H3 context loop into one continuous multi-clip video, so pasting one `plan.json`
queuing once is all the rendering takes.
Instead of asking the LLM to emit that whole JSON in one turn, the gate is agent-shaped:
one outline turn, then **the LLM writes each scene one at a time** — a single turn fully
focused on that scene's action, camera, audio, and continuity — and the scripts **put it
all together at the end** into the same plan JSON the single-pass prompt would have
produced, validated before it ever reaches the node. Long stories stop drifting, and any
single scene can be regenerated without touching the rest.
one outline turn, then **the LLM writes each scene one at a time** — a single turn that
exists purely to compose that scene from every element a good scene needs (subject,
style, continuity, blocking, camera, performance, texture, sound, exit state) — and the
scripts **put it all together at the end** into the same plan JSON the single-pass
prompt would have produced, validated before it ever reaches the node. The point is
compositional attention, not word counts: the validator checks structure and trips only
a thin-scene floor, so any scene can be rewritten until its elements are right, then
re-merged without touching the rest.
### Files
@ -26,7 +29,7 @@ single scene can be regenerated without touching the rest.
| `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts |
| `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories |
| `build_plan.py` | Deterministic Stage 3 merger — puts all the scenes together at the end: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing `plan.json` |
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments) with an embedded test suite |
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments): structure, handoff truth, continuity, thin-scene floor — no word band — with an embedded test suite |
| `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) |
| `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` |
@ -51,7 +54,7 @@ PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is
Save each reply as `scene_NN.json` (zero-padded). Each fragment carries the native H3
three-line prompt (`integrated_multimodal_description: [Shot 1] …` / `overall_soundscape: …`
/ `non_diegetic_music: …`), the duration-tiered word budget, and a truthful `_handoff`
/ `non_diegetic_music: …`), the full scene composition, and a truthful `_handoff`
object for the next turn. Optional gate after each turn:
```sh
@ -123,8 +126,9 @@ durations, and dialogue so later scenes cannot drift:
}
```
**4. The agent writes each scene one at a time** — one file per turn, fully focused on
that scene, validating it before moving to the next:
**4. The agent composes each scene one at a time** — one file per turn, each turn
given over to making that one scene a complete composition, validating it before
moving to the next:
```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3
@ -133,8 +137,8 @@ that scene, validating it before moving to the next:
```
Each fragment carries the three-line H3 prompt and a truthful `_handoff`. Scene 3
(description elided — the real file carries ~237 words of action, camera, wardrobe, and
lighting detail):
(description elided — the real file carries the full blocking, camera work, wardrobe
behavior, and lighting detail):
```json
{
@ -167,6 +171,8 @@ Merged plan:
shot 2 id='greenhouse_aisle' raw=362 delivered=340 steps=20
shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20
total delivered: 1042 frames = 43.42s
H3 section structure: all shots have the 3 sections in canonical order
description lengths: ['221w @ 15s', '219w @ 15s', '237w @ 15s'] | composition elements are the gate - no word band
wrote plan.json - paste its full contents into plan_json_input
```
@ -197,7 +203,7 @@ Smoke test with the shipped examples:
```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
# expect: PLAN OK — 1042 delivered frames = 43.42s
# expect: PLAN OK with "total delivered: 1042 frames = 43.42s"
```
### Wiring the result

View File

@ -10,8 +10,9 @@ description: Turn a story idea into a validated plan_json_input JSON for the Min
# H3 Plan Gate — agent procedure
Goal: produce `plan.json`, the JSON pasted into the Production Plan node's `plan_json_input`,
by writing an outline and then one scene file at a time — each turn fully focused on that
one scene — validating every file with the bundled scripts, and putting all the scenes
by writing an outline and then one scene file at a time — each turn exists so that ONE
scene can be composed from every element of a good scene composition, never to fill a
word count — validating every file with the bundled scripts, and putting all the scenes
together at the end with `build_plan.py`. Never deliver a plan that did not pass `--check`.
## Paths and Python (read first — these exact forms prevent most errors)
@ -34,7 +35,7 @@ together at the end with `build_plan.py`. Never deliver a plan that did not pass
```
Expect the suite to pass and the second command to print
`PLAN OK` with `1042 delivered frames = 43.42s`.
`PLAN OK` with `total delivered: 1042 frames = 43.42s`.
## Step 1 — Outline
@ -63,12 +64,16 @@ never renamed later. Durations whole seconds 2–15, prefer 5–15. Copy the use
speech EXACTLY into the right scene's `dialogue` array; if the story has no quoted speech,
every `dialogue` array stays `[]`. Only the last scene's beat may come to rest.
## Step 2 — Scenes, one file at a time
## Step 2 — Compose the scenes one at a time
Before writing scene 1, read the PROMPT B section of the same file. Then, in story order:
write ONE scene file, validate it, fix it until it passes, and only then move to the next
scene. Since you wrote the previous file yourself, open it and reuse its `_handoff` as the
opening state of the next scene.
Before writing scene 1, read the PROMPT B section of the same file — its SCENE
COMPOSITION checklist (subject anchor, style anchor, continuity anchor, blocking,
camera, performance, physical texture, exit state) is what each turn is for. Then, in
story order: compose ONE scene file, validate it, fix it until it passes, and only then
move to the next scene. Since you wrote the previous file yourself, open it and reuse
its `_handoff` as the opening state of the next scene. Rewrite a scene as many times
as it takes for every element to be present and concrete — the validator has no word
band, only a thin-scene floor, so never pad and never summarize.
```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 5
@ -128,10 +133,13 @@ and sampler latent or the video can come out square.
`integrated_multimodal_description:` / `overall_soundscape:` / `non_diegetic_music:`.
- The description line is self-sufficient: re-state `<Subject 1>`, the full wardrobe, and
the visual style in EVERY scene — nothing is shared between scenes or from a prefix.
- Word budget for the description line: scenes under 10 s aim for ~175 words (never below
150); scenes of 10 s or longer carry 200–300. Spend them on blocking, camera path and
speed, expression beats, body mechanics, wardrobe behavior, weather on skin and fabric,
lighting, and the exact mid-action end point.
- Scene composition, not word count: the description line must carry every element —
subject anchor (`<Subject 1>` and wardrobe restated), style anchor, continuity anchor
(opens inside the previous end_state), blocking, one camera idea, performance beats,
physical texture (wardrobe behavior, weather on skin and fabric, lighting), and a
concrete mid-action exit state. Never pad to a length and never hand in a thin
one-liner — a scene with every element is long enough on its own. The validator only
trips a thin-scene floor (about 100 words); there is no target band.
- Open by continuing the previous `_handoff` end_state ("Continue the same stride",
"without resetting the motion", "keep the incoming camera direction"); scene 1 sets the
opening. End mid-action except the final scene. No camera cuts inside a scene.

View File

@ -121,14 +121,23 @@ Shots are flat. A shot never contains a nested object.
2. Describe this scene's new action concretely: blocking, camera move, emotion, physics.
3. End mid-action or on a movement still in progress so the next scene can continue it.
Only the final scene may resolve and come to rest.
- The integrated_multimodal_description line must fill the scene's duration. Keep it
within 150-300 words, tiered by scene length: scenes under 10 seconds aim for about
175 words; scenes of 10 seconds or longer carry 200 to 300 words. Spend the words on
concrete detail: full blocking (who moves where, which hand does what), camera path
and speed, facial-expression beats, body mechanics, wardrobe behavior, weather and
surfaces on skin and fabric, lighting on faces, and the exact mid-action point where
the scene ends. Thin one-line scenes are a failure; vague summary sentences are
filler.
- Compose every scene from the same eight elements, and never chase a word count —
chase the elements. A description that genuinely carries them comes out long enough
on its own; padding to a number is as much a failure as a thin one-liner:
1. SUBJECT ANCHOR — <Subject 1> restated: identity, wardrobe head to toe, hair, build.
2. STYLE ANCHOR — the one consistent look: medium, lighting quality, palette.
3. CONTINUITY ANCHOR — open inside the previous scene's end state (scene 1 sets the
opening) and name what carries over: the stride, the camera direction, the light,
the weather.
4. BLOCKING — the new action as concrete staging: who moves where, which hand does
what, at what pace, handling which object.
5. CAMERA — one clear camera idea per scene: shot size, height, path, speed, and what
it holds in frame. No cuts inside a scene.
6. PERFORMANCE — facial-expression beats and body mechanics timed to the action.
7. PHYSICAL TEXTURE — wardrobe behavior, weather and surfaces on skin and fabric,
weight, momentum, lighting on faces.
8. EXIT STATE — the exact mid-action point where the scene ends (only the final scene
may come to rest), concrete enough that the next scene opens from it.
- Never compress a change into a stated outcome. A line like "<Subject 1> is now an 18
year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in
the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening,
@ -278,10 +287,11 @@ Correct reply:
7. Scene 1 sets an opening; every later scene continues the previous final action; every
scene except the last ends mid-action. Every description line is self-sufficient: it
re-states who <Subject 1> is, wardrobe, and visual style, because the prefix is empty.
8. Every integrated_multimodal_description line stays within its duration's word
budget — under 10 s: about 175 words (never below 150); 10 s or longer: 200-300 —
and no change anywhere is stated as a bare outcome like "is now"; every
transformation is shown as a continuous on-screen progression.
8. Every description line carries every element of a scene composition — subject,
style, continuity, blocking, camera, performance, texture, exit state — and no
change anywhere is stated as a bare outcome like "is now"; every transformation is
shown as a continuous on-screen progression. Length is a side effect of the
elements, never a target.
9. Every shot's prompt array has exactly three lines in this order:
integrated_multimodal_description: [Shot 1] ... / overall_soundscape: ... /
non_diegetic_music: ...

View File

@ -6,7 +6,7 @@ same contract as the single-pass prompt, split into an agent workflow.
**Verified against:** commit `43afeff` — `chain_nodes.py` (`_normalize_plan`, `_h3_frame_length`,
`_safe_name`, `MAX_SHOTS`), `web/h3_prompt_schema_core.mjs` (`H3_BASE_SECTIONS`), and the same
dialogue/word-budget rules as `h3_plan_json_system_prompt.md`.
dialogue and scene-composition rules as `h3_plan_json_system_prompt.md`.
---
@ -29,10 +29,12 @@ PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is
```
**Why this split works better for long stories:** each turn only carries one scene's
crafting load; the outline freezes ids, durations, dialogue distribution, and cast so
sequential turns cannot drift; and the `_handoff` chain gives every scene a truthful
starting state. You can also hand-edit `outline.json` between Stage 1 and Stage 2 —
the scene agents will follow the edited skeleton.
compositional load — every element of one good scene gets the model's full attention
instead of competing with a word count across ten scenes; the outline freezes ids,
durations, dialogue distribution, and cast so sequential turns cannot drift; and the
`_handoff` chain gives every scene a truthful starting state. You can also hand-edit
`outline.json` between Stage 1 and Stage 2 — the scene agents will follow the edited
skeleton.
**Assembly (Stage 3):** the reliable path is the deterministic merger —
`python scripts/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json`.
@ -211,15 +213,34 @@ identity and style from the story alone; without a handoff you are scene 1.
- End your description mid-action, on a movement still in progress, so the next scene
can continue it. Only the final outline scene may resolve and come to rest.
# SCENE COMPOSITION (why you write one scene per turn)
Your whole turn exists so this ONE scene can be composed with full attention. Build the
integrated_multimodal_description line from every element below; a scene missing an
element is a failed scene. Do not chase a word count — chase the elements. A
description that genuinely carries them comes out long enough on its own; padding to
a number is as much a failure as a thin one-liner.
1. SUBJECT ANCHOR — <Subject 1> restated: identity, wardrobe head to toe, hair,
build. Nothing is shared between scenes or from a prefix.
2. STYLE ANCHOR — the one consistent look: medium, lighting quality, palette.
3. CONTINUITY ANCHOR — open inside the previous end_state (scene 1 instead
establishes place, light, and the first action). Name what carries over: the
stride, the camera direction, the light, the weather.
4. BLOCKING — the new action as concrete staging: who moves where, which hand
does what, at what pace, handling which object.
5. CAMERA — one clear camera idea: shot size, height, path, speed, and what it
holds in frame. No cuts inside the scene.
6. PERFORMANCE — facial-expression beats and body mechanics timed to the action.
7. PHYSICAL TEXTURE — wardrobe behavior, weather and surfaces on skin and fabric,
weight, momentum, lighting on faces.
8. EXIT STATE — the exact mid-action point where the scene ends (only the final
outline scene may come to rest), concrete enough that the next scene opens
from it.
The sound picture is its own element and lives in the overall_soundscape line (AUDIO
below); dialogue lives inside the description line (DIALOGUE below).
# PROMPT CRAFT
- The integrated_multimodal_description line must fill the scene's duration. Keep it
within 150-300 words, tiered by scene length: scenes under 10 seconds aim for about
175 words; scenes of 10 seconds or longer carry 200 to 300 words. Spend the words on
concrete detail: full blocking (who moves where, which hand does what), camera path
and speed, facial-expression beats, body mechanics, wardrobe behavior, weather and
surfaces on skin and fabric, lighting on faces, and the exact mid-action point where
the scene ends. Thin one-line scenes are a failure; vague summary sentences are
filler.
- Never compress a change into a stated outcome. A line like "<Subject 1> is now an 18
year old man" is FORBIDDEN. Show the change as a continuous on-screen progression in
the same take — for an age change: wrinkles smoothing, jaw and cheekbones softening,
@ -372,10 +393,11 @@ Correct reply:
and the visual style.
5. The description opens by continuing the PREVIOUS HANDOFF's end_state (scene 1 sets
the opening instead) and ends mid-action — except the final outline scene.
6. The description line stays within its duration's word budget — under 10 s: about 175
words (never below 150); 10 s or longer: 200-300 — and no change anywhere is stated
as a bare outcome like "is now"; every transformation is shown as a continuous
on-screen progression.
6. The description line carries every element of a scene composition — subject anchor,
style anchor, continuity anchor, blocking, camera, performance, physical texture,
exit state — and no change anywhere is stated as a bare outcome like "is now";
every transformation is shown as a continuous on-screen progression. Length is a
side effect of the elements, never a target.
7. overall_soundscape continues the previous soundscape ("the same ... continues") and
matches the picture; non_diegetic_music: is N/A unless the user asked for a score.
8. There is no <d> span anywhere unless this scene's outline row or the story gave
@ -417,5 +439,5 @@ Correct reply:
workflow for long stories, per-scene iteration, or regenerating single scenes.
- **Validation without assembly:** `python scripts/verify_plan_rules.py fragment
scene_02.json --index 2 --prev scene_01.json` checks one fragment against all rules
(structure, word budget, handoff truthfulness, soundscape continuity, dialogue
mirror).
(structure, composition floor, handoff truthfulness, soundscape and description
continuity, dialogue mirror).

View File

@ -27,6 +27,13 @@ DIALOGUE_SPAN_RE = re.compile(r"<d>(.*?)</d>")
MARKER_RE = re.compile(r"^\[[^\]]+\]\s*")
CONTINUITY_RE = re.compile(r"\b(same\b|continu|still\b)", re.I)
# The gate is a composition gate, not a word counter: there is no target band and
# no upper limit. The floor only trips on lazy output that could not possibly carry
# the elements of a scene composition (subject, wardrobe, style, continuity,
# blocking, camera, performance, texture, sound, exit state).
THIN_FLOOR_SHORT = 100 # description words, scenes under 10 s
THIN_FLOOR_LONG = 120 # description words, scenes of 10 s or longer
def load_json_text(text, label=""):
"""json.loads tolerant of a surrounding markdown fence (LLM output)."""
@ -180,9 +187,11 @@ def check_h3_sections(plan):
f"shot {idx}: description line must re-state <Subject 1> (prefix is empty)"
dur = float(shot.get("duration_seconds",
plan.get("defaults", {}).get("duration_seconds", 15)))
lo, hi = (200, 300) if dur >= 10 else (150, 200)
assert lo <= wc <= hi, \
f"shot {idx}: {wc} words outside {lo}-{hi} budget for a {dur:g}s scene"
floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT
assert wc >= floor, \
(f"shot {idx}: description is only {wc} words - too thin to carry the "
f"elements of a scene composition (subject, wardrobe, style, continuity, "
f"blocking, camera, performance, texture, sound, exit state)")
assert " is now " not in lines[0].lower(), \
f"shot {idx}: change stated as bare outcome instead of shown progression"
assert "<d>" not in lines[1] and "</d>" not in lines[1], \
@ -191,10 +200,11 @@ def check_h3_sections(plan):
assert re.search(r"silently with mouth", lines[0]), \
f"shot {idx}: dialogue span lacks a mouth-state cue"
print(" H3 section structure: all shots have the 3 sections in canonical order")
print(" description word budget:",
print(" description lengths:",
[(f"{len(s['prompt'][0].split())}w @ "
f"{s.get('duration_seconds', plan.get('defaults', {}).get('duration_seconds', 15))}s")
for s in plan["shots"]], "| <10s: 150-200, >=10s: 200-300")
for s in plan["shots"]],
"| composition elements are the gate - no word band")
return True
@ -253,10 +263,12 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
raise ValueError(f"{where}: line 3 must start with 'non_diegetic_music:'")
wc = len(desc.split())
lo, hi = (200, 300) if dur >= 10 else (150, 200)
if not lo <= wc <= hi:
raise ValueError(f"{where}: description is {wc} words, outside {lo}-{hi} "
f"for a {dur:g}s scene")
floor = THIN_FLOOR_LONG if dur >= 10 else THIN_FLOOR_SHORT
if wc < floor:
raise ValueError(f"{where}: description is only {wc} words - too thin to carry "
f"the elements of a scene composition (subject, wardrobe, "
f"style, continuity, blocking, camera, performance, texture, "
f"sound, exit state)")
if "<Subject 1>" not in desc:
raise ValueError(f"{where}: description must re-state <Subject 1> (prefix is empty)")
if " is now " in desc.lower():
@ -295,6 +307,10 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
if prev_line and not CONTINUITY_RE.search(ssc):
raise ValueError(f"{where}: soundscape does not continue the previous audio "
f"bed (say 'the same ... continues')")
if prev_line and not CONTINUITY_RE.search(desc):
raise ValueError(f"{where}: description does not open inside the previous "
f"end_state (use a continuity cue: 'Continue the same ...', "
f"'without resetting the motion')")
if expect is not None:
if expect.get("id") not in (None, shot_id):
raise ValueError(f"{where}: outline says id {expect.get('id')!r}, "
@ -314,7 +330,7 @@ def validate_fragment(obj, index=1, total=None, prev_handoff=None, expect=None):
raise ValueError(f"{where}: seed out of range")
print(f" {where} id={shot_id!r} dur={dur:g}s raw={raw_frames} frames "
f"words={wc} (band {lo}-{hi}) handoff ok"
f"words={wc} handoff ok"
+ (f" dialogue={len(spans)}" if spans else ""))
return handoff
@ -411,7 +427,7 @@ def run_fragment_suite():
cases = [
("missing _handoff", {k: v for k, v in NURSE_OK.items() if k != "_handoff"}, {}),
("duration outside 2-15", _short_fragment(duration_seconds=20), {}),
("description far under word budget",
("description too thin to compose the scene",
_short_fragment(prompt=["integrated_multimodal_description: [Shot 1] "
"<Subject 1> walks on. End mid-stride.",
NURSE_OK["prompt"][1], "non_diegetic_music: N/A"]), {}),