diff --git a/.cline/skills/h3-plan-gate/SKILL.md b/.cline/skills/h3-plan-gate/SKILL.md new file mode 100644 index 0000000..c133fcf --- /dev/null +++ b/.cline/skills/h3-plan-gate/SKILL.md @@ -0,0 +1,23 @@ +--- +name: h3-plan-gate +description: 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. +--- + +# H3 Plan Gate + +This is a stub so the skill registers with the agent harness. The real procedure lives at +`h3-plan-gate/SKILL.md` in the project root (~22 KB, fits one read). Read it now and +follow it top to bottom for the user's request. + +Hard rules that apply throughout (also in `.clinerules/`): + +- Run `h3-plan-gate/verify_plan_rules.py` and `h3-plan-gate/build_plan.py` — never read + them (Cline truncates reads over ~48,000 characters). +- Never read back one-line JSON (`build_plan.py` output, `plan_oneline.json`) — Cline + cuts lines at 2,000 characters; copy or submit them with commands. +- If a write is rejected over 6,000 characters, split it with the `@@CONTINUE@@` marker + pattern (see the rules section of `h3-plan-gate/SKILL.md`). Never write part 2 with + write_to_file — it overwrites part 1. diff --git a/.clinerules/h3-plan-gate.md b/.clinerules/h3-plan-gate.md new file mode 100644 index 0000000..97ea6e6 --- /dev/null +++ b/.clinerules/h3-plan-gate.md @@ -0,0 +1,25 @@ +# H3 plan gate — standing rules while this repo is open + +When the user asks for H3 chain video plans, scene plans, or MiniMax H3 Production Plan +JSON: read `h3-plan-gate/SKILL.md` (fits one read) and follow it top to bottom. These +rules hold on every task regardless: + +- Run `verify_plan_rules.py` and `build_plan.py` — never read them. Cline cuts reads at + ~48,000 characters, and the ~62 KB validator arrives truncated no matter what. +- Never read one-line JSON files (`build_plan.py` output, `plan_oneline.json`). Cline + cuts any line at 2,000 characters, so they always look broken — that is expected. + Copy, move, or submit them with commands; to inspect plan structure read the + pretty-printed `h3_agent_workflow_examples/plan.json`. +- A truncation notice is Cline's cap, not repo corruption. Never "fix" a truncated file; + re-read it in smaller ranges instead. +- If a write is rejected ("Editor input too large ... the recommended limit of 6000"), + split it: write part 1 ending with the bare marker line `@@CONTINUE@@`, then + replace_in_file with SEARCH `@@CONTINUE@@` and REPLACE the remainder. Never write + part 2 with write_to_file — it overwrites part 1. +- If command output arrives truncated (`[... output truncated ...]`), stop reading the + big output and re-run per file: + `.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py --check ` + (output under 1 KB). Use `python` if there is no `.venv`, `py -3` if `python` is not + on PATH. +- The two big prompt files under `h3-plan-gate/` are read in the bounded line ranges + cited in SKILL.md Steps 1 and 3 — never whole when context is tight. diff --git a/.clinerules/workflows/h3-plan.md b/.clinerules/workflows/h3-plan.md new file mode 100644 index 0000000..be6e290 --- /dev/null +++ b/.clinerules/workflows/h3-plan.md @@ -0,0 +1,15 @@ +Run the H3 plan gate skill end to end for this request: $ARGUMENTS + +Follow `h3-plan-gate/SKILL.md` from top to bottom: + +1. Run the smoke test ("Before you start"). If it fails, stop and report — do not improvise. +2. Step 1 — write `outline.json` from the story. +3. Step 2 — STOP and ask the user to approve or edit the guide (ask_followup_question). + Never continue past this point without explicit approval. +4. Step 3 — compose and validate one scene at a time, in story order. +5. Step 4 — build `plan.json` with `build_plan.py`; report the frames/seconds it prints. +6. Step 5 — give the user the delivery instructions exactly as SKILL.md and the script + print them. + +Delivery is the user's hand paste into the ComfyUI node — never paste or modify the node +yourself. Mind the standing `.clinerules` for Cline's read/write caps. diff --git a/README.md b/README.md index 0769cb5..4b14a32 100755 --- a/README.md +++ b/README.md @@ -318,3 +318,19 @@ output). - 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. + +### Running the skill inside Cline (VS Code + llama.cpp) + +1. Clone this repo and open the **repo root** as the workspace — Cline loads `.clinerules/` + and `.cline/skills/` from the workspace root only. +2. Provider: **OpenAI Compatible**, Base URL `http://localhost:8080/v1` (your + `llama-server`), any Model ID, context 32768 or more (`-c 131072` is comfortable). +3. Ask for a plan normally (`.clinerules` routes the agent to `h3-plan-gate/SKILL.md`), or + type `/h3-plan` with the story and scene count — the workflow in + `.clinerules/workflows/h3-plan.md` runs the skill end to end, including the + outline-approval pause. +4. `.cline/skills/h3-plan-gate/` is a stub that registers the skill with Cline's skill + system; the real procedure stays in `h3-plan-gate/SKILL.md` (single source of truth). +5. Approvals: enable auto-approve for reading files and executing commands (local model, + nothing to spend), or approve each call — the skill pauses by itself at the + outline-approval step either way. diff --git a/h3-plan-gate/SKILL.md b/h3-plan-gate/SKILL.md index 2509657..ca7a256 100755 --- a/h3-plan-gate/SKILL.md +++ b/h3-plan-gate/SKILL.md @@ -25,8 +25,9 @@ never compose a scene from a guide the user has not approved. - Write generated files into the project root: `outline.json`, `scene_01.json`, `scene_02.json`, … , `plan.json`. - Python command: on Windows run `.venv\Scripts\python.exe`; if the project has no `.venv`, - use `python` instead. (macOS/Linux: `.venv/bin/python` or `python`.) The scripts need - only the Python standard library — nothing to install. + use `python` instead; if `python` is not on PATH (or opens the Microsoft Store), use + `py -3`. (macOS/Linux: `.venv/bin/python` or `python`.) The scripts need only the Python + standard library — nothing to install. - Start every task by running the smoke test under "Before you start". If it fails because `h3-plan-gate` is missing files, stop and tell the user the folder is incomplete. - **Never read `verify_plan_rules.py` or `build_plan.py`** — run them and work from their @@ -41,6 +42,18 @@ never compose a scene from a guide the user has not approved. 2,000 and the file looks broken. That is expected. Submit, copy, or move them with a command; to inspect plan structure, read the pretty-printed `plan.json` in the same examples folder instead. +- Cline's editor rejects writes over 6,000 characters ("Editor input too large ... the + recommended limit of 6000"). outline.json and the example scenes fit, but a rich scene + or a single-pass whole plan often does not. NEVER write part 2 with write_to_file — it + replaces the whole file and part 1 is lost. Split instead: write the first part ending + with the bare marker line `@@CONTINUE@@`, then replace_in_file with SEARCH + `@@CONTINUE@@` and REPLACE the remaining content (repeat the marker for very large + plans). The finished file must not contain the marker. +- Cline also cuts command output at 8,000 characters. The full embedded suite prints + ~7.6 KB when it passes — right at the edge — and a failing run prints more. If suite + output arrives truncated (`[... output truncated ...]`) or the suite fails, ignore the + cut output and work per file: run `--check ` (its output is under 1 KB) and fix + one file at a time. - The two big prompt files are read in the **bounded line ranges** given in Step 1 and Step 3 — never whole. If any read still arrives truncated, split it: read lines 1–230, then 231 onward, and continue from where the last chunk ended. @@ -134,7 +147,8 @@ it, fix it until it passes, and only then move to the next scene. Since you wrot previous file yourself, open it and reuse its `_handoff` as the opening state of the next scene. Rewrite a scene as many times as it takes for every element to be present and concrete — the validator has no word band, only a thin-scene floor, so never pad -and never summarize. +and never summarize. If Cline rejects a scene write with 'Editor input too large', +split it with the marker pattern from the rules above. ```sh .venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 5 @@ -352,7 +366,10 @@ You may use the single-pass prompt instead — read `h3-plan-gate/h3_plan_json_system_prompt.md` (501 lines: the copyable system prompt is the text fence spanning lines 30–428; on a limited-context agent read lines 1–230 then 231–501 instead of the whole file), have its rules govern one turn that writes -the whole plan, then run `--check` on the file. Use the full workflow for long stories, +the whole plan, then run `--check` on the file. The one-turn whole-plan write usually +exceeds Cline's 6,000-character editor cap — deliver it with the split pattern from +the rules section (part 1 ending in the `@@CONTINUE@@` marker, then replace the marker +with the remainder). Use the full workflow for long stories, per-scene iteration, or when the user wants to revise single scenes or the guide. ## If you cannot run Python