User-approved scene guide is a mandatory workflow step

Encoded the intended user flow end to end: story + scene count ->
scene guide (outline.json) -> USER APPROVAL (hard stop, changes applied
to the guide first) -> scenes composed one at a time (~10s each) from
the approved guide -> continuity verified across the handoff chain ->
final plan.json.

SKILL.md: goal line states the five moves; new Step 2 'Present the
guide for approval (do not skip)' — plain-language presentation, STOP
and wait, approved guide is the contract; Step 3 works only from the
approved guide; Step 4 renamed 'Verify the continuity, put it all
together'; revising section split into guide-level vs single-scene.

README: workflow reframed as 4 stages with Stage 2 = approval (human in
the loop, never skipped); example gains a real guide-presentation +
'Approved — go' exchange between outline and scene writing; steps
renumbered.

Scene-agent prompt: stage table gains the Approval row and a 'Stage 2 is
a hard stop' note; assembler prompt re-labeled Stage 4. Suite + --check
green.
This commit is contained in:
Z User 2026-10-29 19:28:18 +00:00
parent f5575fa678
commit df8df95d39
4 changed files with 124 additions and 60 deletions

View File

@ -25,24 +25,32 @@ re-merged without touching the rest.
| File | Role | | 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 | | `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_scene_agent_system_prompt.md` | Stage 1 + 3 system prompts: **PROMPT A** (scene-guide planner) and **PROMPT B** (one-scene-per-turn writer with a `_handoff` chain) — Stage 2 is the human approval between them |
| `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts | | `h3_plan_assembler_system_prompt.md` | Stage 4 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 | | `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` | | `build_plan.py` | Deterministic Stage 4 merger — verifies the continuity across the chain and 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): structure, handoff truth, continuity, thin-scene floor — no word band — with an embedded test suite | | `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments): structure, handoff truth, continuity, thin-scene floor — no word band — with an embedded test suite |
| `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) | | `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` | | `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` |
### Agent workflow (3 stages) ### Agent workflow (story in, plan.json out)
**Stage 1 — Outline.** Put PROMPT A (from `h3_scene_agent_system_prompt.md`) in the system The loop the user runs: **story + scene count → scene guide → approval → one scene at a
field, the story idea in the user field. Save the reply as `outline.json`. It freezes scene time → continuity verified → plan.json**.
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 **Stage 1 — Scene guide.** Put PROMPT A (from `h3_scene_agent_system_prompt.md`) in the
template as the user message: system field, the story idea (and how many scenes) 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.
**Stage 2 — Approval (human in the loop, never skipped).** Show the user the guide in
plain language — one line per scene plus cast and style — and wait. They approve it or
ask for changes; apply every change to `outline.json` and show the changed rows again.
Stage 3 starts only after an explicit approval — the guide is the contract the scenes
are composed against.
**Stage 3 — One scene per turn (~10 s scenes from the approved guide).** Put PROMPT B in
the system field and paste this turn template as the user message:
```text ```text
STORY: <the full story idea> STORY: <the full story idea>
@ -64,15 +72,17 @@ object for the next turn. Optional gate after each turn:
(All command blocks below use the Windows venv form; on macOS/Linux replace (All command blocks below use the Windows venv form; on macOS/Linux replace
`.venv\Scripts\python.exe` with `python3`.) `.venv\Scripts\python.exe` with `python3`.)
**Stage 3 — Assembly (deterministic, preferred):** **Stage 4 — Continuity verified, assembly (deterministic, preferred):**
```sh ```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 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 The merge IS the continuity check: it validates every fragment in the `_handoff` chain
present), then validates the merged plan — only clean JSON is written. Do **not** edit (each scene opens inside the previous scene's real end_state, soundscapes continue, ids,
fragment prose by hand during assembly; if you want a scene changed, re-run its Stage 2 durations, and dialogue match the approved guide), 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 3
turn and re-merge. Use the LLM assembler prompt only in a pure-chat setup with no script 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 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). long strings unreliably; `build_plan.py` is byte-exact by construction).
@ -126,7 +136,30 @@ durations, and dialogue so later scenes cannot drift:
} }
``` ```
**4. The agent composes each scene one at a time** — one file per turn, each turn **4. The agent shows the guide — the user approves or changes it.** Before any scene is
written, the agent presents the guide in plain language and waits:
```text
The guide for "greenhouse_courier" — 3 scenes, photoreal overcast rain:
1. greenhouse_arrival 15s — he wheels the bike in out of the rain and crosses the
threshold mid-stride. No dialogue.
2. greenhouse_aisle 15s — he pushes the bike down the central aisle and slows to
a crawl, one hand reaching for the bag flap. No dialogue.
3. greenhouse_delivery 15s — he sets the parcel on the potting table and speaks as
the delivery completes. Line: "Package for the greenhouse, right on time."
Cast: <Subject 1> the bicycle courier — mustard jacket, teal trousers, helmet, bag.
Approve, or tell me what to change.
```
```text
Approved — go.
```
Any change request ("make scene 2 shorter", "he checks a pocket watch in scene 1") is
applied to `outline.json` first and the changed rows shown again — scenes are composed
only from the approved guide.
**5. The agent composes each scene one at a time** — one file per turn, each turn
given over to making that one scene a complete composition, validating it before given over to making that one scene a complete composition, validating it before
moving to the next: moving to the next:
@ -153,8 +186,8 @@ behavior, and lighting detail):
} }
``` ```
**5. The agent puts it all together at the end** — merging every scene into one plan **6. The agent verifies the continuity and puts it all together at the end** — merging
JSON, never writing plan JSON by hand: every scene into one plan JSON, never writing plan JSON by hand:
```sh ```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 outline.json scene_01.json scene_02.json scene_03.json -o plan.json
@ -180,7 +213,7 @@ The deliverable is the single `plan.json` — `"prompt_prefix": [""]`, `defaults
three self-sufficient shots: exactly the shape the single-pass system prompt emits (full three self-sufficient shots: exactly the shape the single-pass system prompt emits (full
file: `h3_agent_workflow_examples/plan.json`). file: `h3_agent_workflow_examples/plan.json`).
**6. Render the multi-clip video.** Paste the full contents of `plan.json` into the **7. 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 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 — 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 scene 2 continues from scene 1's final frames, scene 3 from scene 2's — producing ONE

View File

@ -10,10 +10,13 @@ description: Turn a story idea into a validated plan_json_input JSON for the Min
# H3 Plan Gate — agent procedure # H3 Plan Gate — agent procedure
Goal: produce `plan.json`, the JSON pasted into the Production Plan node's `plan_json_input`, 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 — each turn exists so that ONE in five moves: the user gives a story and a scene count → you build a scene guide
scene can be composed from every element of a good scene composition, never to fill a (`outline.json`) and show it for **approval** → with the approved guide you compose the
word count — validating every file with the bundled scripts, and putting all the scenes scenes one at a time (about 10 seconds each), each turn existing so that ONE scene can
together at the end with `build_plan.py`. Never deliver a plan that did not pass `--check`. be composed from every element of a good scene composition, never to fill a word count
→ the scripts verify the continuity across the whole chain → `build_plan.py` puts all
the scenes together at the end. Never deliver a plan that did not pass `--check`, and
never compose a scene from a guide the user has not approved.
## Paths and Python (read first — these exact forms prevent most errors) ## Paths and Python (read first — these exact forms prevent most errors)
@ -37,10 +40,12 @@ together at the end with `build_plan.py`. Never deliver a plan that did not pass
Expect the suite to pass and the second command to print Expect the suite to pass and the second command to print
`PLAN OK` with `total delivered: 1042 frames = 43.42s`. `PLAN OK` with `total delivered: 1042 frames = 43.42s`.
## Step 1 — Outline ## Step 1 — Build the scene guide (outline)
Read `h3-plan-gate/h3_scene_agent_system_prompt.md` (PROMPT A and its WORKED EXAMPLE are the The user gives you a story and how many scenes they want. Read
quality bar). From the user's story idea, write `outline.json` in exactly this shape: `h3-plan-gate/h3_scene_agent_system_prompt.md` (PROMPT A and its WORKED EXAMPLE are the
quality bar) and write `outline.json` — the guide for every scene — in exactly this
shape:
```json ```json
{ {
@ -60,20 +65,33 @@ quality bar). From the user's story idea, write `outline.json` in exactly this s
``` ```
3–12 scenes unless the user names a count (hard max 128). Ids unique lowercase snake_case, 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 never renamed later. Durations whole seconds 2–15 — about 10 seconds unless the user says
speech EXACTLY into the right scene's `dialogue` array; if the story has no quoted speech, otherwise. Copy the user's quoted speech EXACTLY into the right scene's `dialogue` array;
every `dialogue` array stays `[]`. Only the last scene's beat may come to rest. if the story has no quoted speech, every `dialogue` array stays `[]`. Only the last
scene's beat may come to rest.
## Step 2 — Compose the scenes one at a time ## Step 2 — Present the guide for approval (do not skip)
Before writing scene 1, read the PROMPT B section of the same file — its SCENE Show the user the finished guide in plain language — one line per scene: number, id,
COMPOSITION checklist (subject anchor, style anchor, continuity anchor, blocking, duration, what happens and where it ends, any dialogue — plus the cast and style block.
camera, performance, physical texture, exit state) is what each turn is for. Then, in Then STOP and wait for their reply. The user approves it or asks for changes; apply
story order: compose ONE scene file, validate it, fix it until it passes, and only then every change to `outline.json` (scene count, ids, durations, beats, dialogue, cast,
move to the next scene. Since you wrote the previous file yourself, open it and reuse style) and, if anything changed, show the changed rows again. Start Step 3 only after
its `_handoff` as the opening state of the next scene. Rewrite a scene as many times an explicit approval. The approved guide is the contract: scenes are composed from it,
as it takes for every element to be present and concrete — the validator has no word ids and durations are never silently altered, and new story ideas from the user go
band, only a thin-scene floor, so never pad and never summarize. through the guide first — never straight into a scene file.
## Step 3 — Compose the scenes one at a time
Work only from the approved guide. Before writing scene 1, read the PROMPT B section of
`h3_scene_agent_system_prompt.md` — its SCENE COMPOSITION checklist (subject anchor,
style anchor, continuity anchor, blocking, camera, performance, physical texture, exit
state) is what each turn is for. Then, in story order: compose 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. Rewrite a scene as many times as it takes for every element to be present
and concrete — the validator has no word band, only a thin-scene floor, so never pad
and never summarize.
```sh ```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_01.json --index 1 --total 5
@ -97,10 +115,14 @@ Each fragment is exactly this shape:
} }
``` ```
## Step 3 — Put it all together at the end ## Step 4 — Verify the continuity, put it all together at the end
Once every scene file passes, merge them into the ONE plan JSON. Never write the plan Once every scene file passes, the merge is the continuity check: `build_plan.py`
JSON by hand and never edit fragment prose during the merge. Run: re-walks the whole `_handoff` chain — every scene after the first must open inside the
previous scene's real end_state, every soundscape must continue the previous audio bed,
every id, duration, and spoken line must match the approved guide — and only then does
it write the ONE plan JSON. Never write the plan JSON by hand and never edit fragment
prose during the merge. Run:
```sh ```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 outline.json scene_01.json scene_02.json scene_03.json -o plan.json
@ -112,7 +134,7 @@ everything, and writes the single deliverable: `plan.json` — `"prompt_prefix":
`defaults`, and one self-sufficient shot per scene, exactly the shape the single-pass `defaults`, and one self-sufficient shot per scene, exactly the shape the single-pass
system prompt emits. Report the delivered frames/seconds it prints. system prompt emits. Report the delivered frames/seconds it prints.
## Step 4 — Deliver (the node makes the multi-clip video) ## Step 5 — Deliver (the node makes the multi-clip video)
The user pastes the full contents of `plan.json` into the Plan node's `plan_json_input` The user pastes the full contents of `plan.json` into the Plan node's `plan_json_input`
and queues ONCE. The node renders each shot as its own clip and chains the clips through and queues ONCE. The node renders each shot as its own clip and chains the clips through
@ -162,18 +184,20 @@ and sampler latent or the video can come out square.
- 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.
## Revising one scene ## Revising after approval
Rewrite that `scene_NN.json` (keep its id and duration from the outline), re-validate it - Guide-level change (durations, beats, dialogue, scene count): update `outline.json`
with the fragment command, then re-run the Step 3 merge so `plan.json` refreshes. Never first, show the changed rows, then rewrite only the affected scenes against it.
patch `plan.json` directly. - One scene reads badly: rewrite that `scene_NN.json` (keep its id and duration from
the guide), re-validate it with the fragment command, then re-run the Step 4 merge so
`plan.json` refreshes. Never patch `plan.json` directly.
## Short stories (2–4 scenes) ## Short stories (2–4 scenes)
You may use the single-pass prompt instead — read 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 `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, the whole plan, then run `--check` on the file. Use the full workflow for long stories,
per-scene iteration, or when the user wants to revise single scenes. per-scene iteration, or when the user wants to revise single scenes or the guide.
## If you cannot run Python ## If you cannot run Python

View File

@ -3,8 +3,9 @@
**Target node:** `MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)` ("Production Plan") in **Target node:** `MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)` ("Production Plan") in
[ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop). [ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop).
This is **Stage 3** of the agent workflow started in `h3_scene_agent_system_prompt.md` This is **Stage 4** of the agent workflow started in `h3_scene_agent_system_prompt.md`
(outline → one scene per turn → assembly). (scene guide → approval → one scene per turn → assembly, with the merge doubling as the
continuity check).
**Recommended:** assemble with the deterministic merger instead of the LLM — **Recommended:** assemble with the deterministic merger instead of the LLM —
`python scripts/build_plan.py outline.json scene_01.json scene_02.json ... -o plan.json`. `python scripts/build_plan.py outline.json scene_01.json scene_02.json ... -o plan.json`.

View File

@ -14,11 +14,17 @@ dialogue and scene-composition rules as `h3_plan_json_system_prompt.md`.
| Stage | System prompt | User message | Output | | Stage | System prompt | User message | Output |
|---|---|---|---| |---|---|---|---|
| 1. Outline | PROMPT A below | the story idea | outline JSON — save as `outline.json` | | 1. Scene guide | PROMPT A below | the story idea + scene count | outline JSON — save as `outline.json` |
| 2. Scene ×N | PROMPT B below | the turn template below | one fragment JSON per turn — save as `scene_01.json`, `scene_02.json`, … | | 2. Approval | — (you and the user, not the LLM) | show the guide in plain language | user approval, or edits applied to `outline.json` |
| 3. Assembly | `h3_plan_assembler_system_prompt.md` **or** `scripts/build_plan.py` | all fragments | final plan JSON → `plan_json_input` | | 3. Scene ×N | PROMPT B below | the turn template below | one fragment JSON per turn — save as `scene_01.json`, `scene_02.json`, … |
| 4. Assembly | `h3_plan_assembler_system_prompt.md` **or** `scripts/build_plan.py` | all fragments | final plan JSON → `plan_json_input` |
**Turn template for Stage 2** (fill and paste as the user message): **Stage 2 is a hard stop:** never run a Stage 3 turn before the user has explicitly
approved the guide shown to them. Requests for changes are applied to `outline.json`
first and the changed rows shown again; the approved guide is the contract that every
scene turn, and the assembly checks, are run against.
**Turn template for Stage 3** (fill and paste as the user message):
```text ```text
STORY: <the full story idea> STORY: <the full story idea>
@ -30,13 +36,13 @@ PREVIOUS HANDOFF: <paste the previous scene's "_handoff" object — or: This is
**Why this split works better for long stories:** each turn only carries one scene's **Why this split works better for long stories:** each turn only carries one scene's
compositional load — every element of one good scene gets the model's full attention compositional load — every element of one good scene gets the model's full attention
instead of competing with a word count across ten scenes; the outline freezes ids, instead of competing with a word count across ten scenes; the approved outline freezes
durations, dialogue distribution, and cast so sequential turns cannot drift; and the ids, durations, dialogue distribution, and cast so sequential turns cannot drift; and
`_handoff` chain gives every scene a truthful starting state. You can also hand-edit the `_handoff` chain gives every scene a truthful starting state. User edits to the
`outline.json` between Stage 1 and Stage 2 — the scene agents will follow the edited story go through `outline.json` during the approval stage — the scene agents follow the
skeleton. edited skeleton.
**Assembly (Stage 3):** the reliable path is the deterministic merger — **Assembly (Stage 4):** the reliable path is the deterministic merger —
`python scripts/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json`. `python scripts/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json`.
It strips `_handoff`, validates every fragment and the merged plan, and prints the It strips `_handoff`, validates every fragment and the merged plan, and prints the
delivered runtime. Use the assembler LLM prompt only when you cannot run scripts. delivered runtime. Use the assembler LLM prompt only when you cannot run scripts.