The h3-plan-gate directory is now a drop-in skill for Cline (.cline/skills/ or ~/.cline/skills/) and any Agent-Skills-compatible agent. SKILL.md carries the full agent procedure (outline -> one fragment per turn with per-turn validation -> build_plan.py merge -> delivery notes) plus the condensed craft rules; the prompt .md files remain the deep reference and worked examples stay bundled. README files table updated.
7.3 KiB
| 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. Runs a 3-stage agent workflow (outline → one scene fragment per turn → deterministic merge) and validates every artifact with the bundled node-rule replica before anything is delivered. |
H3 Plan Gate
You are producing the plan_json_input JSON for the "Production Plan" node
(MiniMax H3 Context Loop Plan / MiniMax H3 Plan (Modern)) in
ComfyUI-MiniMaxH3-Context-Loop. You write the JSONs yourself following the shapes below;
the bundled scripts validate and merge them. Never deliver a plan that did not pass
build_plan.py --check.
<skill_dir> below means the folder containing this SKILL.md. Run every command from your
workspace folder, calling the scripts by path. Write generated files into the workspace:
outline.json, scene_01.json, scene_02.json, … (zero-padded), plan.json.
Procedure
-
Outline. Read the PROMPT A section of
<skill_dir>/h3_scene_agent_system_prompt.md(its WORKED EXAMPLE is the quality bar). From the user's story idea, writeoutline.jsonin 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
dialoguearray; no quoted speech anywhere means every array stays[]. Only the last scene's beat may come to rest. -
Scenes, one per turn. Before writing scene 1, read the PROMPT B section of the same file. Then write ONE fragment file per scene in story order, in 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": [] } }After each fragment, validate it and fix until it passes:
python3 <skill_dir>/verify_plan_rules.py fragment scene_01.json --index 1 --total <N> python3 <skill_dir>/verify_plan_rules.py fragment scene_02.json --index 2 --total <N> --prev scene_01.json -
Merge. Never write the plan JSON by hand and never edit fragment prose during the merge. Run:
python3 <skill_dir>/build_plan.py outline.json scene_01.json scene_02.json -o plan.json python3 <skill_dir>/build_plan.py --check plan.jsonThe merger strips
_handoff, injects"prompt_prefix": [""]anddefaults, and validates everything. Report the delivered frames/seconds it prints. To change a scene, rewrite that one fragment (step 2) and re-merge — never patch the merged plan. -
Deliver. Tell the user to paste the full contents of
plan.jsoninto the Plan node's forced STRING inputplan_json_input. Resolution, context length, audio mode, andbase_seedstay on the node's widgets (the JSON cannot set them; connect the width/height outputs to the conditioning node and sampler latent or the output 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
promptarray has EXACTLY three lines in this order, each scene rendered as 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: it re-states
<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
_handoffend_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/Aunless 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. _handoffmust be truthful:end_statedescribes the real final frame (2–3 sentences: pose, motion in progress, camera state);soundscapecopies the overall_soundscape line character for character.- Keys are exactly
id,duration_seconds,prompt,_handoff; addstepsorseedonly when the user explicitly asked. Every duration 2–15 s.
Short stories
For 2–4 scene stories you may use the single-pass prompt instead
(<skill_dir>/h3_plan_json_system_prompt.md — one turn produces the whole plan), then run
build_plan.py --check on it. Use the 3-stage workflow for long stories, per-scene
iteration, or when the user wants to revise single scenes.
No script execution available
If you cannot run Python, fall back to the LLM assembler prompt
(<skill_dir>/h3_plan_assembler_system_prompt.md) for the merge and copy fragments
verbatim — and say plainly that the output skipped script validation.
Smoke test
After setup changes, prove the tooling works:
python3 <skill_dir>/verify_plan_rules.py
python3 <skill_dir>/build_plan.py --check <skill_dir>/h3_agent_workflow_examples/plan.json
# expect: PLAN OK — 1042 delivered frames = 43.42s