mmprompt/h3-plan-gate/SKILL.md
Z User fa764ec933 Full look every scene; 'nude' for uncovered body parts, never 'bare'
H3 needs every aspect of the look restated per scene, and uncovered
skin is steered by the skin-state word 'nude' (tank-top with nude
arms), not 'bare'. Added to both prompts' subject anchor + craft
rules + self-checks and SKILL.md; the validator prints a non-blocking
note when a description line uses 'bare'.
2026-10-29 23:18:56 +00:00

12 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, in five moves: the user gives a story and a scene count → you build a scene guide (outline.json) and show it for approval → with the approved guide you compose the scenes one at a time (about 10 seconds each), each turn existing so that ONE scene can be composed from every element of a good scene composition, never to fill a word count → the scripts verify the continuity across the whole chain → build_plan.py puts all the scenes together at the end. Never deliver a plan that did not pass --check, and never compose a scene from a guide the user has not approved.

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 total delivered: 1042 frames = 43.42s.

Step 1 — Build the scene guide (outline)

The user gives you a story and how many scenes they want. Read h3-plan-gate/h3_scene_agent_system_prompt.md (PROMPT A and its WORKED EXAMPLE are the quality bar) and write outline.json — the guide for every scene — 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 — about 10 seconds unless the user says otherwise. 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 — Present the guide for approval (do not skip)

Show the user the finished guide in plain language — one line per scene: number, id, duration, what happens and where it ends, any dialogue — plus the cast and style block. Then STOP and wait for their reply. The user approves it or asks for changes; apply every change to outline.json (scene count, ids, durations, beats, dialogue, cast, style) and, if anything changed, show the changed rows again. Start Step 3 only after an explicit approval. The approved guide is the contract: scenes are composed from it, ids and durations are never silently altered, and new story ideas from the user go through the guide first — never straight into a scene file.

Step 3 — Compose the scenes one at a time

Work only from the approved guide. Before writing scene 1, read the PROMPT B section of h3_scene_agent_system_prompt.md — 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.

.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 4 — Verify the continuity, put it all together at the end

Once every scene file passes, the merge is the continuity check: build_plan.py re-walks the whole _handoff chain — every scene after the first must open inside the previous scene's real end_state, every soundscape must continue the previous audio bed, every id, duration, and spoken line must match the approved guide — and only then does it write the ONE plan JSON. 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
.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 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.

Step 5 — Deliver (the node makes the multi-clip video)

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.

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> and the full look in EVERY scene — identity, hair, build, every garment head to toe, footwear, and the visual style — nothing is shared between scenes or from a prefix. Name every body part the clothing leaves uncovered and call uncovered skin "nude", never "bare" ("a man wearing a white tank-top with nude arms").
  • 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.
  • Decompose every action into body mechanics: never a single outcome verb ("picks up the ball") — write the ordered joint-level sequence ("bends his knees, grabs the ball with his left hand, then stands back up"), naming the hand or limb for each step. H3 plays back only what is stated; a compressed verb leaves gaps the model fills by guessing, and guessed motion drifts off intent.
  • 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 after approval

  • Guide-level change (durations, beats, dialogue, scene count): update outline.json first, show the changed rows, then rewrite only the affected scenes against it.
  • One scene reads badly: rewrite that scene_NN.json (keep its id and duration from the guide), re-validate it with the fragment command, then re-run the Step 4 merge so plan.json refreshes. Never patch plan.json 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 full workflow for long stories, per-scene iteration, or when the user wants to revise single scenes or the guide.

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.