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 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 **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), [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 verified against commit `43afeff`. The deliverable is always **one plan JSON with one shot
per scene, then a validated merge — so long stories are written scene by scene and single per scene** — the node renders every shot as its own clip and chains the clips through the
scenes can be regenerated without touching the rest. The merge exports **one render-ready H3 context loop into one continuous multi-clip video, so pasting one `plan.json` and
JSON per scene** (`clips/clip_NN.json`) for making **multi-clip videos** — each scene is queuing once is all the rendering takes.
rendered as its own clip and stitched in an editor — plus an optional merged `plan.json`
for a single continuous chain take. 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 ### 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_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_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 | | `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 | | `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`) | | `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` | | `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 .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, **3. The agent writes `outline.json`** — the skeleton that freezes cast, style, ids,
durations, and dialogue so later scenes cannot drift: 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 ```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3 .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 ```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 .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 shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20
total delivered: 1042 frames = 43.42s total delivered: 1042 frames = 43.42s
wrote plan.json - paste its full contents into plan_json_input 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 The deliverable is the single `plan.json` — `"prompt_prefix": [""]`, `defaults`, and
single-scene plan per clip, the input for a multi-clip video — and the merged three self-sufficient shots: exactly the shape the single-pass system prompt emits (full
`plan.json` for an optional single continuous take (full file: file: `h3_agent_workflow_examples/plan.json`).
`h3_agent_workflow_examples/plan.json`).
**6. Render the multi-clip video (the main use).** For each clip in order: paste the full **6. Render the multi-clip video.** Paste the full contents of `plan.json` into the
contents of `clips/clip_NN.json` into the Production Plan node's `plan_json_input`, queue Production Plan node's forced STRING input `plan_json_input` and queue **once**. The node
one render, save the output — then stitch the clips in order in any editor. Every clip renders each shot as its own clip and chains the clips through the H3 context loop —
renders at its FULL duration (three 15-second scenes = 45 seconds of footage; the chain scene 2 continues from scene 1's final frames, scene 3 from scene 2's — producing ONE
overlap trim does not apply to independent clips), and because every description opens continuous multi-clip video: 1042 delivered frames ≈ 43.4 s at 24 fps (every scene after
mid-motion and ends mid-action, the cuts read as one continuous take. the first loses ~1 second to the fixed overlap trim that stitches the clips together).
*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).
Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything else": it 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 rewrites only `scene_02.json`, re-validates it, and re-merges — refreshing `plan.json`
the merged plan. in one command.
### Validating ### 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 # 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/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 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: Smoke test with the shipped examples:
@ -211,14 +202,14 @@ Smoke test with the shipped examples:
### Wiring the result ### Wiring the result
For a **multi-clip video**, render one clip at a time: paste the full contents of Paste the full contents of `plan.json` into the Plan node's forced STRING input
`clips/clip_NN.json` into the Plan node's forced STRING input **`plan_json_input`** (a **`plan_json_input`** (a non-empty connected value overrides the visual editor's plan for
non-empty connected value overrides the visual editor's plan for that run), queue, save, that run) and queue once — the node's context loop turns the multi-shot plan into one
next clip — then stitch in order. For a **single continuous take**, paste `plan.json` multi-clip video by itself; no per-scene renders, no editor stitching. Resolution,
instead and render once. Resolution, context length, audio mode, and `base_seed` stay on context length, audio mode, and `base_seed` stay on the node's own widgets (the JSON
the node's own widgets (the JSON cannot set them; default canvas is 960×544 — set cannot set them; default canvas is 960×544 — set width/height widgets and wire the
width/height widgets and wire the width/height outputs into the conditioning node and width/height outputs into the conditioning node and sampler latent to avoid square
sampler latent to avoid square output). output).
### Requirements ### 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 # H3 Plan Gate — agent procedure
Goal: produce `plan.json`, the JSON pasted into the Production Plan node's `plan_json_input`, 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 by writing an outline and then one scene file at a time — each turn fully focused on that
bundled scripts, and merging with `build_plan.py`. Never deliver a plan that did not pass one scene — validating every file with the bundled scripts, and putting all the scenes
`--check`. 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) ## 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 ```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 .venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
``` ```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates 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 ## Step 4 — Deliver (the node makes the multi-clip video)
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).
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) 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
**Multi-clip video (main use):** the user renders each scene as its own video — paste the and sampler latent or the video can come out square.
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.
## Craft rules for every fragment (violations fail the validator) ## 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 ## Revising one scene
Rewrite that `scene_NN.json` (keep its id and duration from the outline), re-validate it 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 with the fragment command, then re-run the Step 3 merge so `plan.json` refreshes. Never
`plan.json` refresh together. Never patch `plan.json` or a clip file directly. patch `plan.json` directly.
## Short stories (2–4 scenes) ## Short stories (2–4 scenes)

View File

@ -1,22 +1,21 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
"""Merge MiniMax H3 scene-agent fragments into the final plan JSON for plan_json_input. """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). Stage 3 of the agent workflow (outline -> one scene per turn -> put it all together
Deterministic and byte-exact: fragment prompt strings are copied, never rewritten. at the end). Deterministic and byte-exact: fragment prompt strings are copied, never
Every fragment and the merged plan are validated with the same rules the node uses rewritten. Every fragment and the merged plan are validated with the same rules the
(replicated in verify_plan_rules.py) before anything is written. 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: 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 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 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 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 its "scenes" key. When present, fragment ids, durations, and dialogue are checked
against it in order. Fenced markdown JSON (```json ... ```) also parses. against it in order. Fenced markdown JSON (```json ... ```) also parses.
@ -72,9 +71,6 @@ def main():
help="defaults.steps when no outline is given") help="defaults.steps when no outline is given")
ap.add_argument("--check", metavar="PLAN", default=None, ap.add_argument("--check", metavar="PLAN", default=None,
help="validate an existing plan JSON and exit") 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() args = ap.parse_args()
if args.check: if args.check:
@ -145,21 +141,6 @@ def main():
else: else:
print("\n" + out_text) 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__": if __name__ == "__main__":
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