Go to file
Z User 30cbaeb8f6 Switch plan.json output to the native H3 ref2va prompt format
Each scene prompt is now the six native reference sections —
subject_definitions / summary [reference generation] / retention_analysis /
detailed_description (1-2 style sentences then [Shot 1]) /
overall_soundscape / non_diegetic_music — one line per element, headers on
their own line. The full head-to-toe look (nude-not-bare) lives in
subject_definitions and is restated compressed in the [Shot 1] body; both
cast members are defined per scene against the wired subject references.
verify_plan_rules.py auto-detects the format per shot and validates the
ref2va contract (canonical order, directive, definitions, retention,
style prefix, thin floor), so legacy t2va plans keep passing. Both system
prompts, the assembler prompt and SKILL.md carry the new skeleton,
worked examples and self-checks; example_output/README.md marks the old
run as the t2va craft reference.
2026-10-30 19:28:36 +00:00
example_output Switch plan.json output to the native H3 ref2va prompt format 2026-10-30 19:28:36 +00:00
h3-plan-gate Switch plan.json output to the native H3 ref2va prompt format 2026-10-30 19:28:36 +00:00
README.md User-approved scene guide is a mandatory workflow step 2026-10-29 19:28:18 +00:00

mmprompt

h3-plan-gate — MiniMax H3 plan-JSON agent workflow + validator

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, 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 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

File Role
SKILL.md Agent Skills entry point — this whole folder is a skill. Cline: copy it to .cline/skills/h3-plan-gate/ (workspace) or ~/.cline/skills/ (global); any Agent-Skills-compatible agent (Claude Code, Cursor, OpenCode, Codex) can load it too
h3_scene_agent_system_prompt.md Stage 1 + 3 system prompts: PROMPT A (scene-guide planner) and PROMPT B (one-scene-per-turn writer with a _handoff chain) — Stage 2 is the human approval between them
h3_plan_assembler_system_prompt.md Stage 4 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 4 merger — verifies the continuity across the chain and 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): 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

Agent workflow (story in, plan.json out)

The loop the user runs: story + scene count → scene guide → approval → one scene at a time → continuity verified → plan.json.

Stage 1 — Scene guide. Put PROMPT A (from h3_scene_agent_system_prompt.md) in the system field, the story idea (and how many scenes) in the user field. Save the reply as outline.json. It freezes scene count, ids, durations, beats, verbatim dialogue distribution, and the style_and_cast block so later turns cannot drift.

Stage 2 — Approval (human in the loop, never skipped). Show the user the guide in plain language — one line per scene plus cast and style — and wait. They approve it or ask for changes; apply every change to outline.json and show the changed rows again. Stage 3 starts only after an explicit approval — the guide is the contract the scenes are composed against.

Stage 3 — One scene per turn (~10 s scenes from the approved guide). Put PROMPT B in the system field and paste this turn template as the user message:

STORY: <the full story idea>
STYLE AND CAST: <paste the "style_and_cast" object from the outline>
OUTLINE: <paste the "scenes" array from the outline>
WRITE SCENE: 2
PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is scene 1.>

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 full scene composition, and a truthful _handoff object for the next turn. Optional gate after each turn:

.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json

(All command blocks below use the Windows venv form; on macOS/Linux replace .venv\Scripts\python.exe with python3.)

Stage 4 — Continuity verified, assembly (deterministic, preferred):

.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json

The merge IS the continuity check: it validates every fragment in the _handoff chain (each scene opens inside the previous scene's real end_state, soundscapes continue, ids, durations, and dialogue match the approved guide), then validates the merged plan — only clean JSON is written. Do not edit fragment prose by hand during assembly; if you want a scene changed, re-run its Stage 3 turn and re-merge. Use the LLM assembler prompt only in a pure-chat setup with no script execution, and diff its output against the fragments if you do (small models transcribe long strings unreliably; build_plan.py is byte-exact by construction).

Example: story idea → final output

The complete run of the shipped example (h3_agent_workflow_examples/) — the same files your agent should produce for any story.

1. Give Cline the story idea. With the skill installed, the whole request is:

Use the h3-plan-gate skill. Story: a courier delivers a package to a greenhouse in the
rain, three shots. When he reaches the table he says exactly: Package for the greenhouse,
right on time.

2. The agent runs the smoke test — proving the toolchain before writing anything:

.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py
.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, 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:

{
  "title": "greenhouse_courier",
  "defaults": { "duration_seconds": 15, "steps": 20 },
  "style_and_cast": {
    "subjects": ["<Subject 1> — an adult bicycle courier; mustard-yellow waterproof jacket, dark teal trousers, charcoal helmet, olive messenger bag"],
    "style": "Photorealistic overcast rainy daylight, soft grey palette, stable landscape tracking shots at eye level",
    "soundscape_seed": "steady light rain drumming on glass roofing, low distant traffic hum"
  },
  "scenes": [
    { "index": 1, "id": "greenhouse_arrival", "duration_seconds": 15,
      "beat": "He wheels his silver bicycle through the greenhouse entrance out of the rain and crosses the interior threshold mid-stride.",
      "dialogue": [] },
    { "index": 2, "id": "greenhouse_aisle", "duration_seconds": 15,
      "beat": "He pushes the bike down the central aisle toward the potting table and slows it to a crawl, one hand reaching for the bag flap.",
      "dialogue": [] },
    { "index": 3, "id": "greenhouse_delivery", "duration_seconds": 15,
      "beat": "He sets the kraft parcel on the wooden potting table and speaks his line as the delivery completes.",
      "dialogue": ["Package for the greenhouse, right on time."] }
  ]
}

4. The agent shows the guide — the user approves or changes it. Before any scene is written, the agent presents the guide in plain language and waits:

The guide for "greenhouse_courier" — 3 scenes, photoreal overcast rain:
  1. greenhouse_arrival   15s — he wheels the bike in out of the rain and crosses the
     threshold mid-stride. No dialogue.
  2. greenhouse_aisle     15s — he pushes the bike down the central aisle and slows to
     a crawl, one hand reaching for the bag flap. No dialogue.
  3. greenhouse_delivery  15s — he sets the parcel on the potting table and speaks as
     the delivery completes. Line: "Package for the greenhouse, right on time."
Cast: <Subject 1> the bicycle courier — mustard jacket, teal trousers, helmet, bag.
Approve, or tell me what to change.
Approved — go.

Any change request ("make scene 2 shorter", "he checks a pocket watch in scene 1") is applied to outline.json first and the changed rows shown again — scenes are composed only from the approved guide.

5. 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:

.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_02.json --index 2 --total 3 --prev scene_01.json
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_03.json --index 3 --total 3 --prev scene_02.json

Each fragment carries the three-line H3 prompt and a truthful _handoff. Scene 3 (description elided — the real file carries the full blocking, camera work, wardrobe behavior, and lighting detail):

{
  "id": "greenhouse_delivery",
  "duration_seconds": 15,
  "prompt": [
    "integrated_multimodal_description: [Shot 1] Continue the same forward stride … He stands silently with mouth closed, then speaks. <d>[English] Package for the greenhouse, right on time.</d> He falls silently with mouth closed … End on the calm wide composition as the delivery completes.",
    "overall_soundscape: the same rain on glass and wet paving continues, tires creak to a stop, the kraft paper parcel thuds softly on the wooden potting table.",
    "non_diegetic_music: N/A"
  ],
  "_handoff": { "end_state": "…", "soundscape": "…", "dialogue_used": ["Package for the greenhouse, right on time."] }
}

6. The agent verifies the continuity and puts it all together at the end — merging every scene into one plan JSON, never writing plan JSON by hand:

.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

Output:

outline: outline.json (3 scenes)
fragment 1/3 … fragment 2/3 … fragment 3/3 …
Merged plan:
  shot 1 id='greenhouse_arrival' raw=362 delivered=362 steps=20
  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

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).

7. 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 it, and re-merges — refreshing plan.json in one command.

Validating

.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

Smoke test with the shipped examples:

.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
# expect: PLAN OK with "total delivered: 1042 frames = 43.42s"

Wiring the result

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

  • build_plan.py and verify_plan_rules.py: Python 3 stdlib only — no venv packages needed; the .venv\Scripts\python.exe form just matches a typical Windows project layout, and plain python / python3 works anywhere.
  • count_prompt_tokens.py: needs tiktoken.
  • LLM settings: temperature 0.3–0.7; enable response_format: {"type": "json_object"} or grammar-constrained JSON if the server supports it. Each scene turn is ≈5k tokens, so ctx 16384 is comfortable; 128k runs the whole workflow many times over.