diff --git a/README.md b/README.md index 7127efc..4f182e1 100755 --- a/README.md +++ b/README.md @@ -25,24 +25,32 @@ re-merged without touching the rest. | 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_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 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 | -| `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 | | `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) +### Agent workflow (story in, plan.json out) -**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. +The loop the user runs: **story + scene count → scene guide → approval → one scene at a +time → continuity verified → plan.json**. -**Stage 2 — One scene per turn.** Put PROMPT B in the system field and paste this turn -template as the user message: +**Stage 1 — Scene guide.** Put PROMPT A (from `h3_scene_agent_system_prompt.md`) in the +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 STORY: @@ -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 `.venv\Scripts\python.exe` with `python3`.) -**Stage 3 — Assembly (deterministic, preferred):** +**Stage 4 — Continuity verified, 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 +The merge IS the continuity check: it validates every fragment in the `_handoff` chain +(each scene opens inside the previous scene's real end_state, soundscapes continue, ids, +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 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). @@ -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: 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 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 -JSON, never writing plan JSON by hand: +**6. The agent verifies the continuity and 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 @@ -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 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 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 diff --git a/h3-plan-gate/SKILL.md b/h3-plan-gate/SKILL.md index 757470e..25534c8 100755 --- a/h3-plan-gate/SKILL.md +++ b/h3-plan-gate/SKILL.md @@ -10,10 +10,13 @@ description: Turn a story idea into a validated plan_json_input JSON for the Min # H3 Plan Gate — agent procedure 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 -scene can be composed from every element of a good scene composition, never to fill a -word count — validating every file with the bundled scripts, and putting all the scenes -together at the end with `build_plan.py`. Never deliver a plan that did not pass `--check`. +in five moves: the user gives a story and a scene count → you build a scene guide +(`outline.json`) and show it for **approval** → with the approved guide you compose the +scenes one at a time (about 10 seconds each), each turn existing so that ONE scene can +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) @@ -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 `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 -quality bar). From the user's story idea, write `outline.json` in exactly this shape: +The user gives you a story and how many scenes they want. Read +`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 { @@ -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, -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. +never renamed later. Durations whole seconds 2–15 — about 10 seconds unless the user says +otherwise. 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. -## 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 -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. +Show the user the finished guide in plain language — one line per scene: number, id, +duration, what happens and where it ends, any dialogue — plus the cast and style block. +Then STOP and wait for their reply. The user approves it or asks for changes; apply +every change to `outline.json` (scene count, ids, durations, beats, dialogue, cast, +style) and, if anything changed, show the changed rows again. Start Step 3 only after +an explicit approval. The approved guide is the contract: scenes are composed from it, +ids and durations are never silently altered, and new story ideas from the user go +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 .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 -JSON by hand and never edit fragment prose during the merge. Run: +Once every scene file passes, the merge is the continuity check: `build_plan.py` +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 .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 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` 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` 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 -with the fragment command, then re-run the Step 3 merge so `plan.json` refreshes. Never -patch `plan.json` directly. +- Guide-level change (durations, beats, dialogue, scene count): update `outline.json` + first, show the changed rows, then rewrite only the affected scenes against it. +- 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) 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. +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 or the guide. ## If you cannot run Python diff --git a/h3-plan-gate/h3_plan_assembler_system_prompt.md b/h3-plan-gate/h3_plan_assembler_system_prompt.md index cf37b7b..aef15e4 100755 --- a/h3-plan-gate/h3_plan_assembler_system_prompt.md +++ b/h3-plan-gate/h3_plan_assembler_system_prompt.md @@ -3,8 +3,9 @@ **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). -This is **Stage 3** of the agent workflow started in `h3_scene_agent_system_prompt.md` -(outline → one scene per turn → assembly). +This is **Stage 4** of the agent workflow started in `h3_scene_agent_system_prompt.md` +(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 — `python scripts/build_plan.py outline.json scene_01.json scene_02.json ... -o plan.json`. diff --git a/h3-plan-gate/h3_scene_agent_system_prompt.md b/h3-plan-gate/h3_scene_agent_system_prompt.md index 614b69b..870fc2b 100755 --- a/h3-plan-gate/h3_scene_agent_system_prompt.md +++ b/h3-plan-gate/h3_scene_agent_system_prompt.md @@ -14,11 +14,17 @@ dialogue and scene-composition rules as `h3_plan_json_system_prompt.md`. | Stage | System prompt | User message | Output | |---|---|---|---| -| 1. Outline | PROMPT A below | the story idea | 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`, … | -| 3. Assembly | `h3_plan_assembler_system_prompt.md` **or** `scripts/build_plan.py` | all fragments | final plan JSON → `plan_json_input` | +| 1. Scene guide | PROMPT A below | the story idea + scene count | outline JSON — save as `outline.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. 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 STORY: @@ -30,13 +36,13 @@ PREVIOUS HANDOFF: