mmprompt/h3-plan-gate/SKILL.md
Z User 28f9b80c83 subject_definitions is a lean identity anchor; the look is woven into detailed_description
Rule 6: subject_definitions never carries the full head-to-toe look or a
nude/bare skin state - it is a lean identity anchor (who the label is, tied
to its reference image). The full look is woven into the [Shot 1] body of
detailed_description according to what is going on in the scene: face, hair,
build as the body moves, each garment where the action touches it, footwear
where steps land, uncovered skin named "nude" where the scene exposes it,
and wardrobe/skin changes stated as part of the action that causes them.

- validator: defs lines reject nude/bare-family skin states and anything
  over 25 words (lean-anchor cap); body re-state message updated; two new
  suite FAIL cases (nude-in-defs, look-dump-in-defs); fixtures rewritten
  to lean defs with the look woven into both [Shot 1] bodies
- all three LLM prompts + SKILL.md: defs role flipped everywhere (template,
  SUBJECT ANCHOR, PROMPT CRAFT, REF2VA spec, worked examples, self-checks);
  outline 'subjects' array now documented as the cast inventory the look is
  spent from
2026-10-30 19:42:00 +00:00

252 lines
14 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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`,
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)
```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 — 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:
```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 — 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. The `subjects` array is the cast inventory: collect the
full head-to-toe look there once — when writing scenes it is spent by weaving it into
each scene's [Shot 1] body, never parked in subject_definitions.
## 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.
```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": [
"subject_definitions:",
"<Subject 1> ...lean identity anchor: who they are, tied to their reference image...",
"summary:",
"[reference generation]",
"retention_analysis:",
"<Subject 1>: fully_preserved",
"detailed_description:",
"...1-2 style sentences from the guide's style...",
"[Shot 1] ...the full scene composition...",
"overall_soundscape:",
"...the sound the scene itself makes...",
"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:
```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 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 carries the six native H3 ref2va sections in canonical order —
`subject_definitions:` / `summary:` / `retention_analysis:` / `detailed_description:` /
`overall_soundscape:` / `non_diegetic_music:` — one line per element, headers on their
own line; `summary` is exactly `[reference generation]`; every scene is its own single
H3 generation, so the bracket number is always `[Shot 1]`.
- The full look is re-stated in EVERY scene, and it lives in the [Shot 1] body —
subject_definitions stays a lean identity anchor (the `<Subject 1>` label and who
they are, tied to their reference image; never a wardrobe list, never a nude/bare
state). Weave the head-to-toe look into the action as the scene exposes it — hair,
build, and face as they move, each garment where the action touches it, footwear
where steps land — nothing is shared between scenes or from a prefix. Name every
body part the clothing leaves uncovered and call uncovered skin "nude", never
"bare", where the scene shows it
("a man wearing a white tank-top with nude arms").
- Scene composition, not word count: the [Shot 1] body must carry every element —
subject anchor (`<Subject 1>` restated, the full look woven in), 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", "crosses her legs") — write the ordered joint-level sequence ("bends his
knees, grabs the ball with his left hand, then stands back up"; "raises her left
leg and places it across her right leg"), naming the hand or limb for each step.
Every movement and motion of every character is this detailed, large or small. H3
plays back only what is stated; a compressed verb leaves gaps the model fills by
guessing, and guessed motion drifts off intent.
- Show common actions, never just mention them: an action named without its steps is
a report, not a render — H3 displays only what the description displays. The common
everyday actions are the worst offenders, and each is written as its ordered
on-screen steps: unbuttoning a shirt (pinch the button, push it through the
buttonhole, pull the plackets apart, work down one at a time), changing a diaper
(undo the waist tabs, fold the panel down, lift the ankles, slide the old one out,
wipe, lay the fresh one under, press each tab closed), turning on a lamp (flip the
switch with one finger, hold still while the bulb flickers and settles), opening a
door (press the lever down, pull the door toward you, step through), buckling a
strap (pull it across, click the tongue home, tug the free end to tighten), handing
over an object (lift it, hold it out, wait for the other hand to close, release).
- Spell out every change and movement step by step — not only the subject's actions.
Camera, lighting, weather, background, wardrobe, and any transformation each get
their own ordered sequence of visible stages ("the camera pushes in one slow step,
then another, until his hands fill the lower frame"); never a summarized change
("the lights dim"). H3 plays back only what is stated; a summarized change or
movement is a gap the model fills by guessing.
- 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 [Shot 1] body 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 soundscape content
line (the element after the `overall_soundscape:` header) 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.