SKILL.md: rewrite for project-root layout and Windows venv

The <skill_dir> placeholder and python3 commands confused the LLM and fail
on Windows. Now: all commands are concrete and relative to the project root
(the folder containing h3-plan-gate/), invoked as
.venv\\Scripts\\python.exe (Windows venv layout) with python/.venv/bin/python
as fallbacks; python3 removed entirely. Added a start-of-task smoke test,
explicit file-output locations, one-file-at-a-time scene loop with immediate
fragment validation, and a revise-one-scene loop. All command paths verified
from a simulated project root (suite, --check, merge, fragment --prev all
green).
This commit is contained in:
Z User 2026-10-29 18:27:44 +00:00
parent b9b0e41469
commit b308dd77e1

156
h3-plan-gate/SKILL.md Normal file → Executable file
View File

@ -3,31 +3,46 @@ name: h3-plan-gate
description: Turn a story idea into a validated plan_json_input JSON for the MiniMax H3 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 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, 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 or validate an existing H3 plan JSON. The skill lives in the h3-plan-gate folder of the
fragment per turn → deterministic merge) and validates every artifact with the bundled project; all commands run from the project root with the project's Python.
node-rule replica before anything is delivered.
--- ---
# H3 Plan Gate # H3 Plan Gate — agent procedure
You are producing the `plan_json_input` JSON for the "Production Plan" node Goal: produce `plan.json`, the JSON pasted into the Production Plan node's `plan_json_input`,
(`MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)`) in by writing an outline and then one scene file at a time, validating every file with the
ComfyUI-MiniMaxH3-Context-Loop. You write the JSONs yourself following the shapes below; bundled scripts, and merging with `build_plan.py`. Never deliver a plan that did not pass
the bundled scripts validate and merge them. Never deliver a plan that did not pass `--check`.
`build_plan.py --check`.
`<skill_dir>` below means the folder containing this SKILL.md. Run every command from your ## Paths and Python (read first — these exact forms prevent most errors)
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 - 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 `<skill_dir>/h3_scene_agent_system_prompt.md` ## Before you start (smoke test)
(its WORKED EXAMPLE is the quality bar). From the user's story idea, write `outline.json`
in exactly this shape:
```json ```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 `1042 delivered 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", "title": "short_snake_case_name",
"defaults": { "duration_seconds": 10, "steps": 20 }, "defaults": { "duration_seconds": 10, "steps": 20 },
"style_and_cast": { "style_and_cast": {
@ -40,19 +55,32 @@ workspace folder, calling the scripts by path. Write generated files into the wo
"beat": "one sentence: what happens AND where the scene ends", "beat": "one sentence: what happens AND where the scene ends",
"dialogue": [] } "dialogue": [] }
] ]
} }
``` ```
3–12 scenes unless the user names a count (hard max 128). Ids unique lowercase 3–12 scenes unless the user names a count (hard max 128). Ids unique lowercase snake_case,
snake_case, never renamed later. Durations whole seconds 2–15 (prefer 5–15). Copy the never renamed later. Durations whole seconds 2–15, prefer 5–15. Copy the user's quoted
user's quoted speech EXACTLY into the right scene's `dialogue` array; no quoted speech speech EXACTLY into the right scene's `dialogue` array; if the story has no quoted speech,
anywhere means every array stays `[]`. Only the last scene's beat may come to rest. every `dialogue` 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 ## Step 2 — Scenes, one file at a time
file. Then write ONE fragment file per scene in story order, in exactly this shape:
```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.
```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", "id": "from the outline row",
"duration_seconds": 15, "duration_seconds": 15,
"prompt": [ "prompt": [
@ -61,43 +89,37 @@ workspace folder, calling the scripts by path. Write generated files into the wo
"non_diegetic_music: N/A" "non_diegetic_music: N/A"
], ],
"_handoff": { "end_state": "...", "soundscape": "...", "dialogue_used": [] } "_handoff": { "end_state": "...", "soundscape": "...", "dialogue_used": [] }
} }
``` ```
After each fragment, validate it and fix until it passes: ## Step 3 — Merge and check
```sh Never write the plan JSON by hand and never edit fragment prose during the merge. Run:
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 ```sh
merge. Run: .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
```
```sh The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, and validates
python3 <skill_dir>/build_plan.py outline.json scene_01.json scene_02.json -o plan.json everything. Report the delivered frames/seconds it prints.
python3 <skill_dir>/build_plan.py --check plan.json
```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, and ## Step 4 — Deliver
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 Tell the user to paste the full contents of `plan.json` into the Plan node's forced STRING
node's forced STRING input `plan_json_input`. Resolution, context length, audio mode, input `plan_json_input`. Resolution, context length, audio mode, and `base_seed` stay on
and `base_seed` stay on the node's widgets (the JSON cannot set them; connect the the node's widgets — the JSON cannot set them; the width/height outputs must be wired into
width/height outputs to the conditioning node and sampler latent or the output can come the conditioning node and sampler latent or the video can come out square.
out square).
## Craft rules for every fragment (violations fail the validator) ## Craft rules for every fragment (violations fail the validator)
- Raw JSON only: first char `{`, last char `}`, no markdown fences, no prose, double - Raw JSON only: first char `{`, last char `}`, no markdown fences, no prose, double
quotes, no trailing commas, no raw line break inside a string. 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 - The `prompt` array has EXACTLY three lines in this order; every scene is its own single
single H3 generation, so the bracket number is always `[Shot 1]`: H3 generation, so the bracket number is always `[Shot 1]`:
`integrated_multimodal_description:` / `overall_soundscape:` / `non_diegetic_music:`. `integrated_multimodal_description:` / `overall_soundscape:` / `non_diegetic_music:`.
- The description line is self-sufficient: it re-states `<Subject 1>`, the full wardrobe, - The description line is self-sufficient: re-state `<Subject 1>`, the full wardrobe, and
and the visual style in EVERY scene — nothing is shared between scenes or from a prefix. 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 - 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 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, 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` - Keys are exactly `id`, `duration_seconds`, `prompt`, `_handoff`; add `steps` or `seed`
only when the user explicitly asked. Every duration 2–15 s. 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 Rewrite that `scene_NN.json` (keep its id and duration from the outline), re-validate it
(`<skill_dir>/h3_plan_json_system_prompt.md` — one turn produces the whole plan), then run with the fragment command, then re-run the Step 3 merge. Never patch `plan.json` directly.
`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 ## Short stories (2–4 scenes)
If you cannot run Python, fall back to the LLM assembler prompt You may use the single-pass prompt instead — read
(`<skill_dir>/h3_plan_assembler_system_prompt.md`) for the merge and copy fragments `h3-plan-gate/h3_plan_json_system_prompt.md`, have its rules govern one turn that writes
verbatim — and say plainly that the output skipped script validation. 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: 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.
```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
```