mmprompt/h3-plan-gate/SKILL.md
Z User 54a8271072 Multi-clip videos as the primary deliverable: per-scene clip export
build_plan.py --clips [DIR] (default clips/) now exports one validated
single-shot plan JSON per scene (clip_01.json, ...) alongside the merged
plan. Each clip renders through plan_json_input as its own video at FULL
duration (no chain overlap trim), then the clips are stitched in order;
the mid-motion open/close craft rules make the cuts read as one take.
plan.json stays as the optional single continuous-take render.

SKILL.md Step 3/4 rewritten (merge exports clips + plan; deliver =
render-per-clip then stitch), README intro/example/wiring/validating
updated to multi-clip-first with real clip output shown. Verified from a
simulated project root: export green, every clip re-checks PLAN OK.
2026-10-29 18:40:18 +00:00

9.0 KiB
Executable File
Raw Blame History

name description
h3-plan-gate Turn a story idea into a validated plan_json_input JSON for the MiniMax H3 Production Plan node (ComfyUI-MiniMaxH3-Context-Loop). Use when the user wants to plan scenes/shots for H3 video generation, write or extend a scene plan, regenerate one scene, or validate an existing H3 plan JSON. The skill lives in the h3-plan-gate folder of the project; all commands run from the project root with the project's Python.

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.

Paths and Python (read first — these exact forms prevent most errors)

  • Work from the project root: the folder that contains h3-plan-gate/. Every path below is relative to it. Do not cd into h3-plan-gate, and do not cd out of the project root.
  • Write generated files into the project root: outline.json, scene_01.json, scene_02.json, … , plan.json.
  • Python command: on Windows run .venv\Scripts\python.exe; if the project has no .venv, use python instead. (macOS/Linux: .venv/bin/python or python.) The scripts need only the Python standard library — nothing to install.
  • Start every task by running the smoke test under "Before you start". If it fails because h3-plan-gate is missing files, stop and tell the user the folder is incomplete.

Before you start (smoke test)

.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 the second command to print PLAN OK with 1042 delivered frames = 43.42s.

Step 1 — Outline

Read h3-plan-gate/h3_scene_agent_system_prompt.md (PROMPT A and its WORKED EXAMPLE are the quality bar). From the user's story idea, write outline.json in exactly this shape:

{
  "title": "short_snake_case_name",
  "defaults": { "duration_seconds": 10, "steps": 20 },
  "style_and_cast": {
    "subjects": ["<Subject 1> — who they are; wardrobe head to toe; build; hair"],
    "style": "one consistent look: photoreal or otherwise, lighting, palette, camera feel",
    "soundscape_seed": "the base ambient sound carried across all scenes"
  },
  "scenes": [
    { "index": 1, "id": "scene_one_name", "duration_seconds": 10,
      "beat": "one sentence: what happens AND where the scene ends",
      "dialogue": [] }
  ]
}

3–12 scenes unless the user names a count (hard max 128). Ids unique lowercase snake_case, never renamed later. Durations whole seconds 2–15, prefer 5–15. Copy the user's quoted 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

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.

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

(--total is the scene count from the outline; --prev chains the previous file.)

Each fragment is exactly this shape:

{
  "id": "from the outline row",
  "duration_seconds": 15,
  "prompt": [
    "integrated_multimodal_description: [Shot 1] ...",
    "overall_soundscape: ...",
    "non_diegetic_music: N/A"
  ],
  "_handoff": { "end_state": "...", "soundscape": "...", "dialogue_used": [] }
}

Step 3 — Merge, export clips, check

Never write the plan JSON by hand and never edit fragment prose during the merge. Run:

.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 --check plan.json

The merger strips _handoff, injects "prompt_prefix": [""] and defaults, validates everything, and writes two deliverables:

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

Report the delivered frames/seconds it prints.

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.

Craft rules for every fragment (violations fail the validator)

  • Raw JSON only: first char {, last char }, no markdown fences, no prose, double quotes, no trailing commas, no raw line break inside a string.
  • The prompt array has EXACTLY three lines in this order; every scene is its own single H3 generation, so the bracket number is always [Shot 1]: 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.
  • 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.
  • Never compress a change into a stated outcome: a line like "<Subject 1> is now an 18 year old man" is FORBIDDEN. Show every transformation (age, wardrobe, weather, lighting, location, size) as a continuous on-screen progression while motion and camera keep flowing.
  • Soundscape: one or two dense clauses matching the picture, continuing the previous audio bed ("the same rain on glass continues"); diegetic music always named with its in-scene source; non_diegetic_music: N/A unless the user asked for a score; sung/spoken words are dialogue and never live in the soundscape line.
  • Dialogue: silence is the default. Spoken words come only from the outline row or the story, reproduced word for word inside case-sensitive <d>[English] words</d> (one space after the marker; other real languages allowed), inside the description line only, with a "silently with mouth {position}" cue before and after every span. Mirror each span in _handoff.dialogue_used (words only, no marker); empty array when silent.
  • _handoff must be truthful: end_state describes the real final frame (2–3 sentences: pose, motion in progress, camera state); soundscape copies the overall_soundscape line character for character.
  • Keys are exactly id, duration_seconds, prompt, _handoff; add steps or seed only when the user explicitly asked. Every duration 2–15 s.

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.

Short stories (2–4 scenes)

You may use the single-pass prompt instead — read h3-plan-gate/h3_plan_json_system_prompt.md, have its rules govern one turn that writes the whole plan, then run --check on the file. Use the 3-step workflow for long stories, per-scene iteration, or when the user wants to revise single scenes.

If you cannot run Python

Fall back to h3-plan-gate/h3_plan_assembler_system_prompt.md for the merge, copy fragment text verbatim, and say plainly that the result skipped script validation.