mmprompt/README.md
Z User a804088d72 README: end-to-end example from story idea to final output
Walks the shipped greenhouse example through all six steps: the Cline
request, smoke test, outline.json (full JSON), one-file-at-a-time scene
validation, build_plan.py merge with real output (1042 frames = 43.42s),
and rendering via plan_json_input incl. the revise-one-scene loop. All
command blocks aligned to the Windows venv form (.venv\\Scripts\\python.exe)
with one macOS/Linux note, matching SKILL.md.
2026-10-29 18:32:43 +00:00

10 KiB
Executable File
Raw Blame History

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, 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
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: 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:

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:

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

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

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:

.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 PLAN OK — 1042 delivered frames = 43.42s.

3. The agent writes outline.json — the skeleton that freezes cast, style, ids, durations, and dialogue so later scenes cannot drift:

{
  "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 the scenes one file at a time, validating each before moving on:

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

{
  "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 merges and checks — never writing the plan JSON by hand:

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

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

plan.json is the final artifact — "prompt_prefix": [""], "defaults", and three shots with their three-line prompts and durations (full file: h3_agent_workflow_examples/plan.json).

6. Render. Paste the full contents of plan.json into the Production Plan node's plan_json_input (a non-empty connected value overrides the visual editor's plan for that run), set the Plan node's width/height widgets, and wire the width/height outputs into the conditioning node and sampler latent. You get three 15-second scenes — the first plays in full, each later scene loses ~1 second to overlap trimming — 1042 delivered frames ≈ 43.4 s at 24 fps. Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything else": it rewrites only scene_02.json, re-validates, and re-merges.

Validating

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

.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 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 — 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.