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:
parent
b9b0e41469
commit
b308dd77e1
138
h3-plan-gate/SKILL.md
Normal file → Executable file
138
h3-plan-gate/SKILL.md
Normal file → Executable file
@ -3,28 +3,43 @@ 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:
|
```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
|
```json
|
||||||
{
|
{
|
||||||
@ -43,13 +58,26 @@ workspace folder, calling the scripts by path. Write generated files into the wo
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
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:
|
|
||||||
|
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
|
```json
|
||||||
{
|
{
|
||||||
@ -64,40 +92,34 @@ workspace folder, calling the scripts by path. Write generated files into the wo
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
After each fragment, validate it and fix until it passes:
|
## Step 3 — Merge and check
|
||||||
|
|
||||||
|
Never write the plan JSON by hand and never edit fragment prose during the merge. Run:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
python3 <skill_dir>/verify_plan_rules.py fragment scene_01.json --index 1 --total <N>
|
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
|
||||||
python3 <skill_dir>/verify_plan_rules.py fragment scene_02.json --index 2 --total <N> --prev scene_01.json
|
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
|
||||||
```
|
```
|
||||||
|
|
||||||
3. **Merge.** Never write the plan JSON by hand and never edit fragment prose during the
|
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, and validates
|
||||||
merge. Run:
|
everything. Report the delivered frames/seconds it prints.
|
||||||
|
|
||||||
```sh
|
## Step 4 — Deliver
|
||||||
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
|
Tell the user to paste the full contents of `plan.json` into the Plan node's forced STRING
|
||||||
validates everything. Report the delivered frames/seconds it prints. To change a scene,
|
input `plan_json_input`. Resolution, context length, audio mode, and `base_seed` stay on
|
||||||
rewrite that one fragment (step 2) and re-merge — never patch the merged plan.
|
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.
|
||||||
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)
|
## 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
|
|
||||||
```
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user