diff --git a/README.md b/README.md index c99656a..a081cef 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ scenes can be regenerated without touching the rest. | File | Role | |---|---| +| `SKILL.md` | Agent Skills entry point — this whole folder is a skill. Cline: copy it to `.cline/skills/h3-plan-gate/` (workspace) or `~/.cline/skills/` (global); any Agent-Skills-compatible agent (Claude Code, Cursor, OpenCode, Codex) can load it too | | `h3_scene_agent_system_prompt.md` | Stage 1 + 2 system prompts: **PROMPT A** (outline planner) and **PROMPT B** (one-scene-per-turn writer with a `_handoff` chain) | | `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts | | `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories | diff --git a/h3-plan-gate/SKILL.md b/h3-plan-gate/SKILL.md new file mode 100644 index 0000000..412de20 --- /dev/null +++ b/h3-plan-gate/SKILL.md @@ -0,0 +1,148 @@ +--- +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`. + +`` 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 `/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": [" — 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 /verify_plan_rules.py fragment scene_01.json --index 1 --total + python3 /verify_plan_rules.py fragment scene_02.json --index 2 --total --prev scene_01.json + ``` + +3. **Merge.** Never write the plan JSON by hand and never edit fragment prose during the + merge. Run: + + ```sh + python3 /build_plan.py outline.json scene_01.json scene_02.json -o plan.json + python3 /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 ``, 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 " 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 `[English] words` (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 +(`/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 +(`/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 /verify_plan_rules.py +python3 /build_plan.py --check /h3_agent_workflow_examples/plan.json +# expect: PLAN OK — 1042 delivered frames = 43.42s +```