mmprompt/h3-plan-gate/SKILL.md
Z User b9b0e41469 Add SKILL.md: Agent Skills entry point for the h3-plan-gate folder
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.
2026-10-29 17:55:52 +00:00

149 lines
7.3 KiB
Markdown
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. 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
1. **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, 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; no quoted speech
anywhere means every array stays `[]`. Only the last scene's beat may come to rest.
2. **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:
```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": [] }
}
```
After each fragment, validate it and fix until it passes:
```sh
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
```
3. **Merge.** Never write the plan JSON by hand and never edit fragment prose during the
merge. Run:
```sh
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.json
```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, 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.
4. **Deliver.** Tell the user to paste the full contents of `plan.json` into the Plan
node's forced STRING input `plan_json_input`. Resolution, context length, audio mode,
and `base_seed` stay 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 `prompt` array 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 `_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.
## 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:
```sh
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
```