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
|
||||
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`.
|
||||
|
||||
`<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`.
|
||||
## 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 `<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:
|
||||
## Before you start (smoke test)
|
||||
|
||||
```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
|
||||
{
|
||||
@ -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
|
||||
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.
|
||||
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.
|
||||
|
||||
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 2 — Scenes, one file at a time
|
||||
|
||||
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
|
||||
{
|
||||
@ -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
|
||||
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
|
||||
.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
|
||||
```
|
||||
|
||||
3. **Merge.** Never write the plan JSON by hand and never edit fragment prose during the
|
||||
merge. Run:
|
||||
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, and validates
|
||||
everything. Report the delivered frames/seconds it prints.
|
||||
|
||||
```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
|
||||
```
|
||||
## Step 4 — Deliver
|
||||
|
||||
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).
|
||||
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 `<Subject 1>`, 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 `<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,
|
||||
@ -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
|
||||
(`<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.
|
||||
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
|
||||
(`<skill_dir>/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 <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
|
||||
```
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user