The skill exists so the LLM writes/rewrites each scene one at a time with full attention on making it a complete scene composition — not so it can hit a word target. Prompts: the word-budget craft bullets are replaced by an 8-element composition checklist (subject anchor, style anchor, continuity anchor, blocking, camera, performance, physical texture, exit state) in both the scene-writer PROMPT B (new SCENE COMPOSITION section) and the single-pass prompt. Chase the elements, never a number; padding is as much a failure as a thin one-liner. Validator: hard word bands (<10s: 150-200, >=10s: 200-300) removed from plan and fragment checks. Replaced by a thin-scene floor (100/120 words) that only trips lazy output, plus a new continuity-anchor check — chained fragments must open inside the previous end_state. No target band, no upper limit; output lines say so. SKILL.md/README: goal, Step 2, craft rules, table rows, and example outputs updated to match. Suite, --check, chained fragment checks all green.
182 lines
9.4 KiB
Markdown
Executable File
182 lines
9.4 KiB
Markdown
Executable File
---
|
||
name: h3-plan-gate
|
||
description: 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 — each turn exists so that ONE
|
||
scene can be composed from every element of a good scene composition, never to fill a
|
||
word count — validating every file with the bundled scripts, and putting all the scenes
|
||
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)
|
||
|
||
- 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)
|
||
|
||
```sh
|
||
.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 — 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:
|
||
|
||
```json
|
||
{
|
||
"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 — Compose the scenes one at a time
|
||
|
||
Before writing scene 1, read the PROMPT B section of the same file — 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.
|
||
|
||
```sh
|
||
.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:
|
||
|
||
```json
|
||
{
|
||
"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 — Put it all together at the end
|
||
|
||
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
|
||
.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 4 — 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>`, the full wardrobe, and
|
||
the visual style in EVERY scene — nothing is shared between scenes or from a prefix.
|
||
- 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.
|
||
- 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 `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 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.
|