mmprompt/h3-plan-gate/SKILL.md
Z User b9b0e41469 Add SKILL.md: Agent Skills entry point for the h3-plan-gate folder
The h3-plan-gate directory is now a drop-in skill for Cline (.cline/skills/
or ~/.cline/skills/) and any Agent-Skills-compatible agent. SKILL.md carries
the full agent procedure (outline -> one fragment per turn with per-turn
validation -> build_plan.py merge -> delivery notes) plus the condensed
craft rules; the prompt .md files remain the deep reference and worked
examples stay bundled. README files table updated.
2026-10-29 17:55:52 +00:00

7.3 KiB
Raw Blame History

name description
h3-plan-gate Turn a story idea into a validated plan_json_input JSON for the MiniMax H3 Production Plan node (ComfyUI-MiniMaxH3-Context-Loop). Use when the user wants to plan scenes/shots for H3 video generation, write or extend a scene plan, regenerate one scene, or validate an existing H3 plan JSON. Runs a 3-stage agent workflow (outline → one scene fragment per turn → deterministic merge) and validates every artifact with the bundled node-rule replica before anything is delivered.

H3 Plan Gate

You are producing the plan_json_input JSON for the "Production Plan" node (MiniMax H3 Context Loop Plan / MiniMax H3 Plan (Modern)) in ComfyUI-MiniMaxH3-Context-Loop. You write the JSONs yourself following the shapes below; the bundled scripts validate and merge them. Never deliver a plan that did not pass build_plan.py --check.

<skill_dir> below means the folder containing this SKILL.md. Run every command from your workspace folder, calling the scripts by path. Write generated files into the workspace: outline.json, scene_01.json, scene_02.json, … (zero-padded), plan.json.

Procedure

  1. Outline. Read the PROMPT A section of <skill_dir>/h3_scene_agent_system_prompt.md (its WORKED EXAMPLE is the quality bar). From the user's story idea, write outline.json in exactly this shape:

    {
      "title": "short_snake_case_name",
      "defaults": { "duration_seconds": 10, "steps": 20 },
      "style_and_cast": {
        "subjects": ["<Subject 1> — who they are; wardrobe head to toe; build; hair"],
        "style": "one consistent look: photoreal or otherwise, lighting, palette, camera feel",
        "soundscape_seed": "the base ambient sound carried across all scenes"
      },
      "scenes": [
        { "index": 1, "id": "scene_one_name", "duration_seconds": 10,
          "beat": "one sentence: what happens AND where the scene ends",
          "dialogue": [] }
      ]
    }
    

    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; no quoted speech anywhere means every array stays []. Only the last scene's beat may come to rest.

  2. Scenes, one per turn. Before writing scene 1, read the PROMPT B section of the same file. Then write ONE fragment file per scene in story order, in exactly this shape:

    {
      "id": "from the outline row",
      "duration_seconds": 15,
      "prompt": [
        "integrated_multimodal_description: [Shot 1] ...",
        "overall_soundscape: ...",
        "non_diegetic_music: N/A"
      ],
      "_handoff": { "end_state": "...", "soundscape": "...", "dialogue_used": [] }
    }
    

    After each fragment, validate it and fix until it passes:

    python3 <skill_dir>/verify_plan_rules.py fragment scene_01.json --index 1 --total <N>
    python3 <skill_dir>/verify_plan_rules.py fragment scene_02.json --index 2 --total <N> --prev scene_01.json
    
  3. Merge. Never write the plan JSON by hand and never edit fragment prose during the merge. Run:

    python3 <skill_dir>/build_plan.py outline.json scene_01.json scene_02.json -o plan.json
    python3 <skill_dir>/build_plan.py --check plan.json
    

    The merger strips _handoff, injects "prompt_prefix": [""] and defaults, and validates everything. Report the delivered frames/seconds it prints. To change a scene, rewrite that one fragment (step 2) and re-merge — never patch the merged plan.

  4. Deliver. Tell the user to paste the full contents of plan.json into the Plan node's forced STRING input plan_json_input. Resolution, context length, audio mode, and base_seed stay on the node's widgets (the JSON cannot set them; connect the width/height outputs to the conditioning node and sampler latent or the output can come out square).

Craft rules for every fragment (violations fail the validator)

  • Raw JSON only: first char {, last char }, no markdown fences, no prose, double quotes, no trailing commas, no raw line break inside a string.
  • The prompt array has EXACTLY three lines in this order, each scene rendered as its own single H3 generation, so the bracket number is always [Shot 1]: integrated_multimodal_description: / overall_soundscape: / non_diegetic_music:.
  • The description line is self-sufficient: it re-states <Subject 1>, the full wardrobe, and the visual style in EVERY scene — nothing is shared between scenes or from a prefix.
  • Word budget for the description line: scenes under 10 s aim for ~175 words (never below 150); scenes of 10 s or longer carry 200–300. Spend them on blocking, camera path and speed, expression beats, body mechanics, wardrobe behavior, weather on skin and fabric, lighting, and the exact mid-action end point.
  • Open by continuing the previous _handoff end_state ("Continue the same stride", "without resetting the motion", "keep the incoming camera direction"); scene 1 sets the opening. End mid-action except the final scene. No camera cuts inside a scene.
  • Never compress a change into a stated outcome: a line like "<Subject 1> is now an 18 year old man" is FORBIDDEN. Show every transformation (age, wardrobe, weather, lighting, location, size) as a continuous on-screen progression while motion and camera keep flowing.
  • Soundscape: one or two dense clauses matching the picture, continuing the previous audio bed ("the same rain on glass continues"); diegetic music always named with its in-scene source; non_diegetic_music: N/A unless the user asked for a score; sung/spoken words are dialogue and never live in the soundscape line.
  • Dialogue: silence is the default. Spoken words come only from the outline row or the story, reproduced word for word inside case-sensitive <d>[English] words</d> (one space after the marker; other real languages allowed), inside the description line only, with a "silently with mouth {position}" cue before and after every span. Mirror each span in _handoff.dialogue_used (words only, no marker); empty array when silent.
  • _handoff must be truthful: end_state describes the real final frame (2–3 sentences: pose, motion in progress, camera state); soundscape copies the overall_soundscape line character for character.
  • Keys are exactly id, duration_seconds, prompt, _handoff; add steps or seed only when the user explicitly asked. Every duration 2–15 s.

Short stories

For 2–4 scene stories you may use the single-pass prompt instead (<skill_dir>/h3_plan_json_system_prompt.md — one turn produces the whole plan), then run build_plan.py --check on it. Use the 3-stage workflow for long stories, per-scene iteration, or when the user wants to revise single scenes.

No script execution available

If you cannot run Python, fall back to the LLM assembler prompt (<skill_dir>/h3_plan_assembler_system_prompt.md) for the merge and copy fragments verbatim — and say plainly that the output skipped script validation.

Smoke test

After setup changes, prove the tooling works:

python3 <skill_dir>/verify_plan_rules.py
python3 <skill_dir>/build_plan.py --check <skill_dir>/h3_agent_workflow_examples/plan.json
# expect: PLAN OK — 1042 delivered frames = 43.42s