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.
This commit is contained in:
Z User 2026-10-29 17:31:19 +00:00
parent bd50b1ba51
commit 63a4469315

View File

@ -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: <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
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.