Go to file
Z User b308dd77e1 SKILL.md: rewrite for project-root layout and Windows venv
The <skill_dir> placeholder and python3 commands confused the LLM and fail
on Windows. Now: all commands are concrete and relative to the project root
(the folder containing h3-plan-gate/), invoked as
.venv\\Scripts\\python.exe (Windows venv layout) with python/.venv/bin/python
as fallbacks; python3 removed entirely. Added a start-of-task smoke test,
explicit file-output locations, one-file-at-a-time scene loop with immediate
fragment validation, and a revise-one-scene loop. All command paths verified
from a simulated project root (suite, --check, merge, fragment --prev all
green).
2026-10-29 18:27:44 +00:00
h3-plan-gate SKILL.md: rewrite for project-root layout and Windows venv 2026-10-29 18:27:44 +00:00
README.md Add SKILL.md: Agent Skills entry point for the h3-plan-gate folder 2026-10-29 17:55:52 +00:00

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:

python3 h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --prev scene_01.json

Stage 3 — Assembly (deterministic, preferred):

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

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:

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.