diff --git a/h3-plan-gate/SKILL.md b/h3-plan-gate/SKILL.md old mode 100644 new mode 100755 index 412de20..ca54d17 --- a/h3-plan-gate/SKILL.md +++ b/h3-plan-gate/SKILL.md @@ -3,101 +3,123 @@ 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. + 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 +# H3 Plan Gate — agent procedure -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`. +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, validating every file with the +bundled scripts, and merging with `build_plan.py`. Never deliver a plan that did not pass +`--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`. +## Paths and Python (read first — these exact forms prevent most errors) -## Procedure +- 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. -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: +## Before you start (smoke test) - ```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": [] } - ] - } - ``` +```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 +``` - 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. +Expect the suite to pass and the second command to print +`PLAN OK` with `1042 delivered frames = 43.42s`. -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: +## Step 1 — Outline - ```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": [] } - } - ``` +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: - After each fragment, validate it and fix until it passes: +```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": [] } + ] +} +``` - ```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–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. -3. **Merge.** Never write the plan JSON by hand and never edit fragment prose during the - merge. Run: +## Step 2 — Scenes, one file at a time - ```sh - python3 /build_plan.py outline.json scene_01.json scene_02.json -o plan.json - python3 /build_plan.py --check plan.json - ``` +Before writing scene 1, read the PROMPT B section of the same file. Then, in story order: +write 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. - 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. +```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 +``` -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). +(`--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 — Merge and check + +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`, and validates +everything. Report the delivered frames/seconds it prints. + +## Step 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; 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, each scene rendered as its own - single H3 generation, so the bracket number is always `[Shot 1]`: +- 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: it re-states ``, the full wardrobe, - and the visual style in EVERY scene — nothing is shared between scenes or from a prefix. +- The description line is self-sufficient: re-state ``, 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, @@ -124,25 +146,19 @@ workspace folder, calling the scripts by path. Write generated files into the wo - 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 +## Revising one scene -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. +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. Never patch `plan.json` directly. -## No script execution available +## Short stories (2–4 scenes) -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. +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. -## Smoke test +## If you cannot run Python -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 -``` +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.