Skill is install-location independent: SKILL_DIR concept (loaded-from folder) replaces project-root assumption; all command forms use %USERPROFILE%\.agent\skills\h3-plan-gate; generated files go to the working folder; README install section rewritten for global skills dirs (.clinerules/.cline kept as repo-workspace extras)

This commit is contained in:
Z User 2026-10-31 00:49:45 +00:00
parent eb1b626648
commit dc8d9fab81
2 changed files with 43 additions and 36 deletions

View File

@ -319,18 +319,20 @@ output).
grammar-constrained JSON if the server supports it. Each scene turn is ≈5k tokens, so 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. ctx 16384 is comfortable; 128k runs the whole workflow many times over.
### Running the skill inside Cline (VS Code + llama.cpp) ### Installing the skill (any agent harness, any working folder)
1. Clone this repo and open the **repo root** as the workspace — Cline loads `.clinerules/` Copy the whole `h3-plan-gate/` folder into the harness's skills directory — Windows:
and `.cline/skills/` from the workspace root only. `%userprofile%\.agent\skills\h3-plan-gate\`; macOS/Linux: `~/.agent/skills/h3-plan-gate/`.
2. Provider: **OpenAI Compatible**, Base URL `http://localhost:8080/v1` (your The folder is self-locating: `SKILL.md` resolves its own scripts, prompt files and worked
`llama-server`), any Model ID, context 32768 or more (`-c 131072` is comfortable). examples from wherever it is installed (SKILL_DIR), while all generated files
3. Ask for a plan normally (`.clinerules` routes the agent to `h3-plan-gate/SKILL.md`), or (`outline.json`, `scene_*.json`, `plan.json`) are written to the working folder. Updating
type `/h3-plan` with the story and scene count — the workflow in the skill = `git pull` in a clone, then re-copy the folder.
`.clinerules/workflows/h3-plan.md` runs the skill end to end, including the
outline-approval pause. The `.clinerules/` and `.cline/skills/` folders in this repo are only for working inside a
4. `.cline/skills/h3-plan-gate/` is a stub that registers the skill with Cline's skill clone of the repo itself (workspace-level rules and the `/h3-plan` slash workflow). They
system; the real procedure stays in `h3-plan-gate/SKILL.md` (single source of truth). are not needed once the skill is installed globally — just ask for a plan in plain chat.
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 Local models in Cline: provider **OpenAI Compatible**, Base URL `http://localhost:8080/v1`
outline-approval step either way. (your `llama-server`), any Model ID, context 32768 or more (`-c 131072` is comfortable).
Enable auto-approve for reading files and executing commands (local model, nothing to
spend) — the skill still pauses by itself at the outline-approval step.

View File

@ -3,8 +3,9 @@ name: h3-plan-gate
description: Turn a story idea into a validated plan_json_input JSON for the MiniMax H3 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 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, scenes/shots for H3 video generation, write or extend a scene plan, regenerate one scene,
or validate an existing H3 plan JSON. The skill lives in the h3-plan-gate folder of the or validate an existing H3 plan JSON. The scripts and prompt files live next to this
project; all commands run from the project root with the project's Python. SKILL.md (the skill's install folder); run them from the user's working folder, where
all generated files are written.
--- ---
# H3 Plan Gate — agent procedure # H3 Plan Gate — agent procedure
@ -20,16 +21,20 @@ never compose a scene from a guide the user has not approved.
## Paths and Python (read first — these exact forms prevent most errors) ## Paths and Python (read first — these exact forms prevent most errors)
- Work from the **project root**: the folder that contains `h3-plan-gate/`. Every path below - **SKILL_DIR** is the folder this SKILL.md was loaded from — the skill's install folder
is relative to it. Do not cd into `h3-plan-gate`, and do not cd out of the project root. (default on Windows: `%userprofile%\.agent\skills\h3-plan-gate`; macOS/Linux:
- Write generated files into the project root: `outline.json`, `scene_01.json`, `~/.agent/skills/h3-plan-gate`). The scripts, prompt files and worked examples all live
`scene_02.json`, … , `plan.json`. in SKILL_DIR, not in the working folder. Every command below uses the Windows default
- Python command: on Windows run `.venv\Scripts\python.exe`; if the project has no `.venv`, install path; substitute your real SKILL_DIR if it differs.
use `python` instead; if `python` is not on PATH (or opens the Microsoft Store), use - Work in the user's **working folder** (the folder open in the editor). Write generated
`py -3`. (macOS/Linux: `.venv/bin/python` or `python`.) The scripts need only the Python files there: `outline.json`, `scene_01.json`, `scene_02.json`, … , `plan.json`. Never
standard library — nothing to install. write generated files into SKILL_DIR.
- Python command: Windows `py -3` (or `python`); macOS/Linux `python3`. If the working
folder has a `.venv`, its interpreter works too (`.venv\Scripts\python.exe` /
`.venv/bin/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 - 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. SKILL_DIR is missing files, stop and tell the user the skill folder is incomplete.
- **Never read `verify_plan_rules.py` or `build_plan.py`** — run them and work from their - **Never read `verify_plan_rules.py` or `build_plan.py`** — run them and work from their
printed output. Cline's read_file is capped by hard-coded budgets that do NOT grow with printed output. Cline's read_file is capped by hard-coded budgets that do NOT grow with
the model's context window: about 48,000 characters per read, 2,000 lines per read, and the model's context window: about 48,000 characters per read, 2,000 lines per read, and
@ -37,7 +42,7 @@ never compose a scene from a guide the user has not approved.
The ~62 KB validator arrives cut no matter how large `llama-server -c` is. A truncation The ~62 KB validator arrives cut no matter how large `llama-server -c` is. A truncation
notice is Cline's read cap, not repo corruption — do not "fix" truncated files. notice is Cline's read cap, not repo corruption — do not "fix" truncated files.
- **Never read back one-line JSON files** — `build_plan.py`'s output plan and - **Never read back one-line JSON files** — `build_plan.py`'s output plan and
`h3_agent_workflow_examples/plan_oneline.json` are one-line JSON (the shipped example is SKILL_DIR's `h3_agent_workflow_examples/plan_oneline.json` are one-line JSON (the shipped example is
a single 5,807-character line), so a read always ends in `[line truncated]` at character a single 5,807-character line), so a read always ends in `[line truncated]` at character
2,000 and the file looks broken. That is expected. Submit, copy, or move them with a 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 command; to inspect plan structure, read the pretty-printed `plan.json` in the same
@ -61,8 +66,8 @@ never compose a scene from a guide the user has not approved.
## Before you start (smoke test) ## Before you start (smoke test)
```sh ```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py py -3 "%USERPROFILE%\.agent\skills\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 py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\build_plan.py" --check "%USERPROFILE%\.agent\skills\h3-plan-gate\h3_agent_workflow_examples\plan.json"
``` ```
Expect the suite to pass and the second command to print Expect the suite to pass and the second command to print
@ -71,7 +76,7 @@ Expect the suite to pass and the second command to print
## Step 1 — Build the scene guide (outline) ## Step 1 — Build the scene guide (outline)
The user gives you a story and how many scenes they want. Read **lines 53–156** of The user gives you a story and how many scenes they want. Read **lines 53–156** of
`h3-plan-gate/h3_scene_agent_system_prompt.md` — the PROMPT A section (its ROLE, OUTPUT SKILL_DIR's `h3_scene_agent_system_prompt.md` — the PROMPT A section (its ROLE, OUTPUT
SHAPE, FIELD RULES, WORKED EXAMPLE and SELF-CHECK are the quality bar); never the whole SHAPE, FIELD RULES, WORKED EXAMPLE and SELF-CHECK are the quality bar); never the whole
~36 KB file. Then write `outline.json` — the guide for every scene — in exactly this ~36 KB file. Then write `outline.json` — the guide for every scene — in exactly this
shape: shape:
@ -137,7 +142,7 @@ through the guide first — never straight into a scene file.
## Step 3 — Compose the scenes one at a time ## Step 3 — Compose the scenes one at a time
Work only from the approved guide. Before writing scene 1, read **lines 157–568** of Work only from the approved guide. Before writing scene 1, read **lines 157–568** of
`h3-plan-gate/h3_scene_agent_system_prompt.md` — the PROMPT B section (role, output SKILL_DIR's `h3_scene_agent_system_prompt.md` — the PROMPT B section (role, output
shape, turn template, SCENE COMPOSITION checklist, craft, audio, dialogue, timing, shape, turn template, SCENE COMPOSITION checklist, craft, audio, dialogue, timing,
worked example, self-check; ~3.6k tokens as a section, versus ~11k for the whole file). worked example, self-check; ~3.6k tokens as a section, versus ~11k for the whole file).
Its SCENE COMPOSITION checklist (subject anchor, Its SCENE COMPOSITION checklist (subject anchor,
@ -151,8 +156,8 @@ and never summarize. If Cline rejects a scene write with 'Editor input too large
split it with the marker pattern from the rules above. split it with the marker pattern from the rules above.
```sh ```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 5 py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_01.json --index 1 --total 5
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --total 5 --prev scene_01.json py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_02.json --index 2 --total 5 --prev scene_01.json
``` ```
(`--total` is the scene count from the outline; `--prev` chains the previous file.) (`--total` is the scene count from the outline; `--prev` chains the previous file.)
@ -195,8 +200,8 @@ it write the ONE plan JSON. Never write the plan JSON by hand and never edit fra
prose during the merge. Run: prose during the merge. Run:
```sh ```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json py -3 "%USERPROFILE%\.agent\skills\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 py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\build_plan.py" --check plan.json
``` ```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates
@ -363,7 +368,7 @@ and sampler latent or the video can come out square.
## Short stories (2–4 scenes) ## Short stories (2–4 scenes)
You may use the single-pass prompt instead — read 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 SKILL_DIR's `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 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 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. The one-turn whole-plan write usually the whole plan, then run `--check` on the file. The one-turn whole-plan write usually
@ -374,5 +379,5 @@ per-scene iteration, or when the user wants to revise single scenes or the guide
## If you cannot run Python ## If you cannot run Python
Fall back to `h3-plan-gate/h3_plan_assembler_system_prompt.md` for the merge, copy fragment Fall back to SKILL_DIR's `h3_plan_assembler_system_prompt.md` for the merge, copy fragment
text verbatim, and say plainly that the result skipped script validation. text verbatim, and say plainly that the result skipped script validation.