From 63a44693150ee127c0ce4cc475d2022cfb47ee4a Mon Sep 17 00:00:00 2001 From: Z User Date: Thu, 29 Oct 2026 17:31:19 +0000 Subject: [PATCH] README: agent usage guide for the h3-plan-gate workflow 3-stage agent workflow (outline -> one scene per turn -> validated merge), per-turn fragment gate, validation commands, smoke test with the shipped examples, plan_json_input wiring notes, and requirements. --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/README.md b/README.md index 07aa441..c99656a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,95 @@ # 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 workflow is agent-shaped: one outline turn, one turn +per scene, then a validated merge — so long stories are written scene by scene and single +scenes can be regenerated without touching the rest. + +### Files + +| File | Role | +|---|---| +| `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: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing | +| `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: +STYLE AND CAST: +OUTLINE: +WRITE SCENE: 2 +PREVIOUS HANDOFF: +``` + +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 +python3 h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json +``` + +**Stage 3 — Assembly (deterministic, preferred):** + +```sh +python3 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). + +### Validating + +```sh +python3 h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite +python3 h3-plan-gate/verify_plan_rules.py plan plan.json # node-rule replica on a final plan +python3 h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report +``` + +Smoke test with the shipped examples: + +```sh +python3 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 and +receives identical normalization/validation. 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. +- `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.