Realign: one plan JSON, written one scene at a time

The deliverable is the single merged plan.json — the same shape the
single-pass system prompt emits — and the multi-clip video is what the
node itself produces from it: each shot renders as its own clip, chained
through the H3 context loop into one continuous video. Removed the
--clips per-scene export (external stitching is NOT the design).

Workflow restated everywhere: outline turn -> the LLM writes each scene
one at a time (one focused turn per scene) -> build_plan.py puts it all
together at the end into plan.json -> paste once, queue once.

build_plan.py: --clips option and export block removed; docstring now
describes the node-side chaining. README: intro/example/validating/
wiring rewritten around the single deliverable. SKILL.md: goal, Step 3
(Put it all together at the end), Step 4 (the node makes the multi-clip
video), and the revising loop updated. Suite + --check green.
This commit is contained in:
Z User 2026-10-29 19:00:11 +00:00
parent 54a8271072
commit 83cc5145bf
11 changed files with 69 additions and 104 deletions

View File

@ -5,12 +5,17 @@
Prompt set and tooling that turn a story idea into the `plan_json_input` JSON for the
**Production Plan** node (`MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)`) in
[ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop),
verified against commit `43afeff`. The workflow is agent-shaped: one outline turn, one turn
per scene, then a validated merge — so long stories are written scene by scene and single
scenes can be regenerated without touching the rest. The merge exports **one render-ready
JSON per scene** (`clips/clip_NN.json`) for making **multi-clip videos** — each scene is
rendered as its own clip and stitched in an editor — plus an optional merged `plan.json`
for a single continuous chain take.
verified against commit `43afeff`. The deliverable is always **one plan JSON with one shot
per scene** — the node renders every shot as its own clip and chains the clips through the
H3 context loop into one continuous multi-clip video, so pasting one `plan.json` and
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.
### Files
@ -20,7 +25,7 @@ for a single continuous chain take.
| `h3_scene_agent_system_prompt.md` | Stage 1 + 2 system prompts: **PROMPT A** (outline planner) and **PROMPT B** (one-scene-per-turn writer with a `_handoff` chain) |
| `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: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing; `--clips` exports one single-scene plan JSON per scene for multi-clip rendering |
| `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 |
| `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` |
@ -89,7 +94,8 @@ right on time.
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
```
Expect the suite to pass and `PLAN OK — 1042 delivered frames = 43.42s`.
Expect the suite to pass and, from the second command, `PLAN OK` with
`total delivered: 1042 frames = 43.42s`.
**3. The agent writes `outline.json`** — the skeleton that freezes cast, style, ids,
durations, and dialogue so later scenes cannot drift:
@ -117,7 +123,8 @@ durations, and dialogue so later scenes cannot drift:
}
```
**4. The agent writes the scenes one file at a time**, validating each before moving on:
**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:
```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3
@ -142,10 +149,11 @@ lighting detail):
}
```
**5. The agent merges, exports the clips, and checks** — never writing plan JSON by hand:
**5. The agent puts it all together at the end** — merging every scene into one plan
JSON, never writing plan JSON by hand:
```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
```
@ -160,38 +168,22 @@ Merged plan:
shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20
total delivered: 1042 frames = 43.42s
wrote plan.json - paste its full contents into plan_json_input
clip 1/3 -> clips/clip_01.json (id=greenhouse_arrival)
shot 1 id='greenhouse_arrival' raw=362 delivered=362 steps=20
total delivered: 362 frames = 15.08s
…
clip 3/3 -> clips/clip_03.json (id=greenhouse_delivery)
shot 1 id='greenhouse_delivery' raw=362 delivered=362 steps=20
total delivered: 362 frames = 15.08s
…
wrote 3 single-scene clip plans -> clips/ - render each clip_NN.json through
plan_json_input as its own video, then stitch the clips in order
```
Two deliverables: **`clips/clip_01.json`, `clip_02.json`, `clip_03.json`** — one
single-scene plan per clip, the input for a multi-clip video — and the merged
`plan.json` for an optional single continuous take (full file:
`h3_agent_workflow_examples/plan.json`).
The deliverable is the single `plan.json` — `"prompt_prefix": [""]`, `defaults`, and
three self-sufficient shots: exactly the shape the single-pass system prompt emits (full
file: `h3_agent_workflow_examples/plan.json`).
**6. Render the multi-clip video (the main use).** For each clip in order: paste the full
contents of `clips/clip_NN.json` into the Production Plan node's `plan_json_input`, queue
one render, save the output — then stitch the clips in order in any editor. Every clip
renders at its FULL duration (three 15-second scenes = 45 seconds of footage; the chain
overlap trim does not apply to independent clips), and because every description opens
mid-motion and ends mid-action, the cuts read as one continuous take.
*Alternative — one continuous take:* paste `plan.json` instead and the node renders the
whole story as a single chain video (1042 delivered frames ≈ 43.4 s at 24 fps — every
scene after the first loses ~1 second to overlap trimming).
**6. Render the multi-clip video.** Paste the full contents of `plan.json` into the
Production Plan node's forced STRING input `plan_json_input` and queue **once**. The node
renders each shot as its own clip and chains the clips through the H3 context loop —
scene 2 continues from scene 1's final frames, scene 3 from scene 2's — producing ONE
continuous multi-clip video: 1042 delivered frames ≈ 43.4 s at 24 fps (every scene after
the first loses ~1 second to the fixed overlap trim that stitches the clips together).
Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything else": it
rewrites only `scene_02.json`, re-validates, and re-merges — refreshing both the clip and
the merged plan.
rewrites only `scene_02.json`, re-validates it, and re-merges — refreshing `plan.json`
in one command.
### Validating
@ -199,7 +191,6 @@ the merged plan.
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py plan plan.json # node-rule replica on a final plan
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check clips/clip_01.json # clips validate the same way
```
Smoke test with the shipped examples:
@ -211,14 +202,14 @@ Smoke test with the shipped examples:
### Wiring the result
For a **multi-clip video**, render one clip at a time: paste the full contents of
`clips/clip_NN.json` into the Plan node's forced STRING input **`plan_json_input`** (a
non-empty connected value overrides the visual editor's plan for that run), queue, save,
next clip — then stitch in order. For a **single continuous take**, paste `plan.json`
instead and render once. Resolution, context length, audio mode, and `base_seed` stay on
the node's own widgets (the JSON cannot set them; default canvas is 960×544 — set
width/height widgets and wire the width/height outputs into the conditioning node and
sampler latent to avoid square output).
Paste the full contents of `plan.json` into the Plan node's forced STRING input
**`plan_json_input`** (a non-empty connected value overrides the visual editor's plan for
that run) and queue once — the node's context loop turns the multi-shot plan into one
multi-clip video by itself; no per-scene renders, no editor stitching. Resolution,
context length, audio mode, and `base_seed` stay on the node's own widgets (the JSON
cannot set them; default canvas is 960×544 — set width/height widgets and wire the
width/height outputs into the conditioning node and sampler latent to avoid square
output).
### Requirements

View File

@ -10,9 +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, validating every file with the
bundled scripts, and merging with `build_plan.py`. Never deliver a plan that did not pass
`--check`.
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
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)
@ -92,39 +92,32 @@ Each fragment is exactly this shape:
}
```
## Step 3 — Merge, export clips, check
## Step 3 — Put it all together at the end
Never write the plan JSON by hand and never edit fragment prose during the merge. Run:
Once every scene file passes, merge them into the ONE plan JSON. Never write the plan
JSON by hand and never edit fragment prose during the merge. Run:
```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates
everything, and writes two deliverables:
everything, and writes the single deliverable: `plan.json` — `"prompt_prefix": [""]`,
`defaults`, and one self-sufficient shot per scene, exactly the shape the single-pass
system prompt emits. Report the delivered frames/seconds it prints.
- `clips/clip_01.json`, `clip_02.json`, … — one single-scene plan per clip. **This is the
main output: the goal is a multi-clip video**, one rendered clip per scene.
- `plan.json` — all shots in one chain plan (optional: a single continuous take instead).
## Step 4 — Deliver (the node makes the multi-clip video)
Report the delivered frames/seconds it prints.
The user pastes the full contents of `plan.json` into the Plan node's `plan_json_input`
and queues ONCE. The node renders each shot as its own clip and chains the clips through
the H3 context loop — scene 2 continues from scene 1's final frames, scene 3 from scene
2's — producing one continuous multi-clip video. Every scene after the first loses about
1 second to the fixed overlap trim that stitches the clips together.
## Step 4 — Deliver (multi-clip is the default goal)
**Multi-clip video (main use):** the user renders each scene as its own video — paste the
full contents of `clips/clip_01.json` into the Plan node's `plan_json_input`, queue one
render, save the output, then repeat with `clip_02.json`, `clip_03.json`, … — and stitches
the clips in order in any editor. Each clip renders at its FULL duration (no chain overlap
trimming), and because every description opens mid-motion and ends mid-action, the cuts
read as one continuous take.
**Continuous take (optional):** pasting `plan.json` instead renders the whole story in one
chain run; every scene after the first then loses about 1 second to overlap trimming.
Either way: resolution, context length, audio mode, and `base_seed` stay on the node's
widgets — the JSON cannot set them; the width/height outputs must be wired into the
conditioning node and sampler latent or the video can come out square.
Resolution, context length, audio mode, and `base_seed` stay on the node's widgets — the
JSON cannot set them; the width/height outputs must be wired into the conditioning node
and sampler latent or the video can come out square.
## Craft rules for every fragment (violations fail the validator)
@ -164,8 +157,8 @@ conditioning node and sampler latent or the video can come out square.
## Revising one scene
Rewrite that `scene_NN.json` (keep its id and duration from the outline), re-validate it
with the fragment command, then re-run the Step 3 merge so `clips/clip_NN.json` and
`plan.json` refresh together. Never patch `plan.json` or a clip file directly.
with the fragment command, then re-run the Step 3 merge so `plan.json` refreshes. Never
patch `plan.json` directly.
## Short stories (2–4 scenes)

View File

@ -1,22 +1,21 @@
#!/usr/bin/env python3
"""Merge MiniMax H3 scene-agent fragments into the final plan JSON for plan_json_input.
Stage 3 of the agent workflow (outline -> one scene per turn -> assembly).
Deterministic and byte-exact: fragment prompt strings are copied, never rewritten.
Every fragment and the merged plan are validated with the same rules the node uses
(replicated in verify_plan_rules.py) before anything is written.
Stage 3 of the agent workflow (outline -> one scene per turn -> put it all together
at the end). Deterministic and byte-exact: fragment prompt strings are copied, never
rewritten. Every fragment and the merged plan are validated with the same rules the
node uses (replicated in verify_plan_rules.py) before anything is written.
The merged plan carries one shot per scene. The node renders each shot as its own
clip and chains the clips through the H3 context loop into one continuous video —
this one plan JSON is the whole multi-clip deliverable; paste it into plan_json_input
once and queue once.
Usage:
python build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips
python build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
python build_plan.py scene_01.json scene_02.json -o plan.json [--duration 10] [--steps 20]
python build_plan.py --check plan.json # validate an existing plan file
--clips [DIR] (default dir: clips) additionally writes one single-shot plan JSON per
scene (clip_01.json, clip_02.json, ...) for MULTI-CLIP rendering: render each clip
through plan_json_input as its own video, then stitch the clips in an editor. Each
clip plays at its full duration (no chain overlap trimming). The merged plan (-o /
stdout) remains the single continuous-take render.
The outline file (from the scene agent's PROMPT A) is optional; it is auto-detected by
its "scenes" key. When present, fragment ids, durations, and dialogue are checked
against it in order. Fenced markdown JSON (```json ... ```) also parses.
@ -72,9 +71,6 @@ def main():
help="defaults.steps when no outline is given")
ap.add_argument("--check", metavar="PLAN", default=None,
help="validate an existing plan JSON and exit")
ap.add_argument("--clips", nargs="?", const="clips", default=None, metavar="DIR",
help="also write one single-shot plan JSON per scene here "
"(multi-clip rendering; default dir: clips)")
args = ap.parse_args()
if args.check:
@ -145,21 +141,6 @@ def main():
else:
print("\n" + out_text)
if args.clips:
os.makedirs(args.clips, exist_ok=True)
for i, shot in enumerate(final_shots, 1):
clip = {"prompt_prefix": [""], "defaults": dict(defaults), "shots": [shot]}
print(f"\nclip {i}/{n} -> {args.clips}/clip_{i:02d}.json "
f"(id={shot.get('id')})")
vpr.validate_plan(clip)
vpr.check_h3_sections(clip)
with open(os.path.join(args.clips, f"clip_{i:02d}.json"), "w",
encoding="utf-8") as fh:
fh.write(json.dumps(clip, indent=2, ensure_ascii=False) + "\n")
print(f"\nwrote {n} single-scene clip plans -> {args.clips}/ - render each "
f"clip_NN.json through plan_json_input as its own video, then stitch "
f"the clips in order (each clip plays at its full duration)")
if __name__ == "__main__":
main()

0
h3-plan-gate/count_prompt_tokens.py Normal file → Executable file
View File

0
h3-plan-gate/h3_agent_workflow_examples/outline.json Normal file → Executable file
View File

0
h3-plan-gate/h3_agent_workflow_examples/plan.json Normal file → Executable file
View File

0
h3-plan-gate/h3_agent_workflow_examples/scene_01.json Normal file → Executable file
View File

0
h3-plan-gate/h3_agent_workflow_examples/scene_02.json Normal file → Executable file
View File

0
h3-plan-gate/h3_agent_workflow_examples/scene_03.json Normal file → Executable file
View File

0
h3-plan-gate/h3_plan_assembler_system_prompt.md Normal file → Executable file
View File

0
h3-plan-gate/h3_scene_agent_system_prompt.md Normal file → Executable file
View File