The deliverable is the single merged plan.json — the same shape the single-pass system prompt emits — and the multi-clip video is what the node itself produces from it: each shot renders as its own clip, chained through the H3 context loop into one continuous video. Removed the --clips per-scene export (external stitching is NOT the design). Workflow restated everywhere: outline turn -> the LLM writes each scene one at a time (one focused turn per scene) -> build_plan.py puts it all together at the end into plan.json -> paste once, queue once. build_plan.py: --clips option and export block removed; docstring now describes the node-side chaining. README: intro/example/validating/ wiring rewritten around the single deliverable. SKILL.md: goal, Step 3 (Put it all together at the end), Step 4 (the node makes the multi-clip video), and the revising loop updated. Suite + --check green.
223 lines
11 KiB
Markdown
Executable File
223 lines
11 KiB
Markdown
Executable File
# mmprompt
|
||
|
||
## h3-plan-gate — MiniMax H3 plan-JSON agent workflow + validator
|
||
|
||
Prompt set and tooling that turn a story idea into the `plan_json_input` JSON for the
|
||
**Production Plan** node (`MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)`) in
|
||
[ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop),
|
||
verified against commit `43afeff`. The deliverable is always **one plan JSON with one shot
|
||
per scene** — the node renders every shot as its own clip and chains the clips through the
|
||
H3 context loop into one continuous multi-clip video, so pasting one `plan.json` and
|
||
queuing once is all the rendering takes.
|
||
|
||
Instead of asking the LLM to emit that whole JSON in one turn, the gate is agent-shaped:
|
||
one outline turn, then **the LLM writes each scene one at a time** — a single turn fully
|
||
focused on that scene's action, camera, audio, and continuity — and the scripts **put it
|
||
all together at the end** into the same plan JSON the single-pass prompt would have
|
||
produced, validated before it ever reaches the node. Long stories stop drifting, and any
|
||
single scene can be regenerated without touching the rest.
|
||
|
||
### Files
|
||
|
||
| 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 |
|
||
| `build_plan.py` | Deterministic Stage 3 merger — puts all the scenes together at the end: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing `plan.json` |
|
||
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments) with an embedded test suite |
|
||
| `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) |
|
||
| `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` |
|
||
|
||
### Agent workflow (3 stages)
|
||
|
||
**Stage 1 — Outline.** Put PROMPT A (from `h3_scene_agent_system_prompt.md`) in the system
|
||
field, the story idea in the user field. Save the reply as `outline.json`. It freezes scene
|
||
count, ids, durations, beats, verbatim dialogue distribution, and the `style_and_cast` block
|
||
so later turns cannot drift. You may hand-edit it before Stage 2 — the scene agents follow
|
||
the edited skeleton.
|
||
|
||
**Stage 2 — One scene per turn.** Put PROMPT B in the system field and paste this turn
|
||
template as the user message:
|
||
|
||
```text
|
||
STORY: <the full story idea>
|
||
STYLE AND CAST: <paste the "style_and_cast" object from the outline>
|
||
OUTLINE: <paste the "scenes" array from the outline>
|
||
WRITE SCENE: 2
|
||
PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is scene 1.>
|
||
```
|
||
|
||
Save each reply as `scene_NN.json` (zero-padded). Each fragment carries the native H3
|
||
three-line prompt (`integrated_multimodal_description: [Shot 1] …` / `overall_soundscape: …`
|
||
/ `non_diegetic_music: …`), the duration-tiered word budget, and a truthful `_handoff`
|
||
object for the next turn. Optional gate after each turn:
|
||
|
||
```sh
|
||
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json
|
||
```
|
||
|
||
(All command blocks below use the Windows venv form; on macOS/Linux replace
|
||
`.venv\Scripts\python.exe` with `python3`.)
|
||
|
||
**Stage 3 — Assembly (deterministic, preferred):**
|
||
|
||
```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
|
||
```
|
||
|
||
The merger validates every fragment in the `_handoff` chain (against the outline when
|
||
present), then validates the merged plan — only clean JSON is written. Do **not** edit
|
||
fragment prose by hand during assembly; if you want a scene changed, re-run its Stage 2
|
||
turn and re-merge. Use the LLM assembler prompt only in a pure-chat setup with no script
|
||
execution, and diff its output against the fragments if you do (small models transcribe
|
||
long strings unreliably; `build_plan.py` is byte-exact by construction).
|
||
|
||
## Example: story idea → final output
|
||
|
||
The complete run of the shipped example (`h3_agent_workflow_examples/`) — the same files
|
||
your agent should produce for any story.
|
||
|
||
**1. Give Cline the story idea.** With the skill installed, the whole request is:
|
||
|
||
```text
|
||
Use the h3-plan-gate skill. Story: a courier delivers a package to a greenhouse in the
|
||
rain, three shots. When he reaches the table he says exactly: Package for the greenhouse,
|
||
right on time.
|
||
```
|
||
|
||
**2. The agent runs the smoke test** — proving the toolchain before writing anything:
|
||
|
||
```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, from the second command, `PLAN OK` with
|
||
`total delivered: 1042 frames = 43.42s`.
|
||
|
||
**3. The agent writes `outline.json`** — the skeleton that freezes cast, style, ids,
|
||
durations, and dialogue so later scenes cannot drift:
|
||
|
||
```json
|
||
{
|
||
"title": "greenhouse_courier",
|
||
"defaults": { "duration_seconds": 15, "steps": 20 },
|
||
"style_and_cast": {
|
||
"subjects": ["<Subject 1> — an adult bicycle courier; mustard-yellow waterproof jacket, dark teal trousers, charcoal helmet, olive messenger bag"],
|
||
"style": "Photorealistic overcast rainy daylight, soft grey palette, stable landscape tracking shots at eye level",
|
||
"soundscape_seed": "steady light rain drumming on glass roofing, low distant traffic hum"
|
||
},
|
||
"scenes": [
|
||
{ "index": 1, "id": "greenhouse_arrival", "duration_seconds": 15,
|
||
"beat": "He wheels his silver bicycle through the greenhouse entrance out of the rain and crosses the interior threshold mid-stride.",
|
||
"dialogue": [] },
|
||
{ "index": 2, "id": "greenhouse_aisle", "duration_seconds": 15,
|
||
"beat": "He pushes the bike down the central aisle toward the potting table and slows it to a crawl, one hand reaching for the bag flap.",
|
||
"dialogue": [] },
|
||
{ "index": 3, "id": "greenhouse_delivery", "duration_seconds": 15,
|
||
"beat": "He sets the kraft parcel on the wooden potting table and speaks his line as the delivery completes.",
|
||
"dialogue": ["Package for the greenhouse, right on time."] }
|
||
]
|
||
}
|
||
```
|
||
|
||
**4. The agent writes each scene one at a time** — one file per turn, fully focused on
|
||
that scene, validating it before moving to the next:
|
||
|
||
```sh
|
||
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 3
|
||
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --total 3 --prev scene_01.json
|
||
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_03.json --index 3 --total 3 --prev scene_02.json
|
||
```
|
||
|
||
Each fragment carries the three-line H3 prompt and a truthful `_handoff`. Scene 3
|
||
(description elided — the real file carries ~237 words of action, camera, wardrobe, and
|
||
lighting detail):
|
||
|
||
```json
|
||
{
|
||
"id": "greenhouse_delivery",
|
||
"duration_seconds": 15,
|
||
"prompt": [
|
||
"integrated_multimodal_description: [Shot 1] Continue the same forward stride … He stands silently with mouth closed, then speaks. <d>[English] Package for the greenhouse, right on time.</d> He falls silently with mouth closed … End on the calm wide composition as the delivery completes.",
|
||
"overall_soundscape: the same rain on glass and wet paving continues, tires creak to a stop, the kraft paper parcel thuds softly on the wooden potting table.",
|
||
"non_diegetic_music: N/A"
|
||
],
|
||
"_handoff": { "end_state": "…", "soundscape": "…", "dialogue_used": ["Package for the greenhouse, right on time."] }
|
||
}
|
||
```
|
||
|
||
**5. The agent puts it all together at the end** — merging every scene into one plan
|
||
JSON, never writing plan JSON by hand:
|
||
|
||
```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
|
||
```
|
||
|
||
Output:
|
||
|
||
```text
|
||
outline: outline.json (3 scenes)
|
||
fragment 1/3 … fragment 2/3 … fragment 3/3 …
|
||
Merged plan:
|
||
shot 1 id='greenhouse_arrival' raw=362 delivered=362 steps=20
|
||
shot 2 id='greenhouse_aisle' raw=362 delivered=340 steps=20
|
||
shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20
|
||
total delivered: 1042 frames = 43.42s
|
||
wrote plan.json - paste its full contents into plan_json_input
|
||
```
|
||
|
||
The deliverable is the single `plan.json` — `"prompt_prefix": [""]`, `defaults`, and
|
||
three self-sufficient shots: exactly the shape the single-pass system prompt emits (full
|
||
file: `h3_agent_workflow_examples/plan.json`).
|
||
|
||
**6. Render the multi-clip video.** Paste the full contents of `plan.json` into the
|
||
Production Plan node's forced STRING input `plan_json_input` and queue **once**. The node
|
||
renders each shot as its own clip and chains the clips through the H3 context loop —
|
||
scene 2 continues from scene 1's final frames, scene 3 from scene 2's — producing ONE
|
||
continuous multi-clip video: 1042 delivered frames ≈ 43.4 s at 24 fps (every scene after
|
||
the first loses ~1 second to the fixed overlap trim that stitches the clips together).
|
||
|
||
Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything else": it
|
||
rewrites only `scene_02.json`, re-validates it, and re-merges — refreshing `plan.json`
|
||
in one command.
|
||
|
||
### Validating
|
||
|
||
```sh
|
||
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite
|
||
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py plan plan.json # node-rule replica on a final plan
|
||
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report
|
||
```
|
||
|
||
Smoke test with the shipped examples:
|
||
|
||
```sh
|
||
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
|
||
# expect: PLAN OK — 1042 delivered frames = 43.42s
|
||
```
|
||
|
||
### Wiring the result
|
||
|
||
Paste the full contents of `plan.json` into the Plan node's forced STRING input
|
||
**`plan_json_input`** (a non-empty connected value overrides the visual editor's plan for
|
||
that run) and queue once — the node's context loop turns the multi-shot plan into one
|
||
multi-clip video by itself; no per-scene renders, no editor stitching. Resolution,
|
||
context length, audio mode, and `base_seed` stay on the node's own widgets (the JSON
|
||
cannot set them; default canvas is 960×544 — set width/height widgets and wire the
|
||
width/height outputs into the conditioning node and sampler latent to avoid square
|
||
output).
|
||
|
||
### Requirements
|
||
|
||
- `build_plan.py` and `verify_plan_rules.py`: Python 3 stdlib only — no venv packages
|
||
needed; the `.venv\Scripts\python.exe` form just matches a typical Windows project
|
||
layout, and plain `python` / `python3` works anywhere.
|
||
- `count_prompt_tokens.py`: needs `tiktoken`.
|
||
- LLM settings: temperature 0.3–0.7; enable `response_format: {"type": "json_object"}` or
|
||
grammar-constrained JSON if the server supports it. Each scene turn is ≈5k tokens, so
|
||
ctx 16384 is comfortable; 128k runs the whole workflow many times over.
|