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:
parent
eb1b626648
commit
dc8d9fab81
30
README.md
30
README.md
@ -319,18 +319,20 @@ output).
|
||||
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)
|
||||
### Installing the skill (any agent harness, any working folder)
|
||||
|
||||
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.
|
||||
Copy the whole `h3-plan-gate/` folder into the harness's skills directory — Windows:
|
||||
`%userprofile%\.agent\skills\h3-plan-gate\`; macOS/Linux: `~/.agent/skills/h3-plan-gate/`.
|
||||
The folder is self-locating: `SKILL.md` resolves its own scripts, prompt files and worked
|
||||
examples from wherever it is installed (SKILL_DIR), while all generated files
|
||||
(`outline.json`, `scene_*.json`, `plan.json`) are written to the working folder. Updating
|
||||
the skill = `git pull` in a clone, then re-copy the folder.
|
||||
|
||||
The `.clinerules/` and `.cline/skills/` folders in this repo are only for working inside a
|
||||
clone of the repo itself (workspace-level rules and the `/h3-plan` slash workflow). They
|
||||
are not needed once the skill is installed globally — just ask for a plan in plain chat.
|
||||
|
||||
Local models in Cline: provider **OpenAI Compatible**, Base URL `http://localhost:8080/v1`
|
||||
(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.
|
||||
|
||||
@ -3,8 +3,9 @@ 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. The skill lives in the h3-plan-gate folder of the
|
||||
project; all commands run from the project root with the project's Python.
|
||||
or validate an existing H3 plan JSON. The scripts and prompt files live next to this
|
||||
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
|
||||
@ -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)
|
||||
|
||||
- Work from the **project root**: the folder that contains `h3-plan-gate/`. Every path below
|
||||
is relative to it. Do not cd into `h3-plan-gate`, and do not cd out of the project root.
|
||||
- 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; 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.
|
||||
- **SKILL_DIR** is the folder this SKILL.md was loaded from — the skill's install folder
|
||||
(default on Windows: `%userprofile%\.agent\skills\h3-plan-gate`; macOS/Linux:
|
||||
`~/.agent/skills/h3-plan-gate`). The scripts, prompt files and worked examples all live
|
||||
in SKILL_DIR, not in the working folder. Every command below uses the Windows default
|
||||
install path; substitute your real SKILL_DIR if it differs.
|
||||
- Work in the user's **working folder** (the folder open in the editor). Write generated
|
||||
files there: `outline.json`, `scene_01.json`, `scene_02.json`, … , `plan.json`. Never
|
||||
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
|
||||
`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
|
||||
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
|
||||
@ -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
|
||||
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
|
||||
`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
|
||||
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
|
||||
@ -61,8 +66,8 @@ never compose a scene from a guide the user has not approved.
|
||||
## Before you start (smoke test)
|
||||
|
||||
```sh
|
||||
.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
|
||||
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py"
|
||||
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
|
||||
@ -71,7 +76,7 @@ Expect the suite to pass and the second command to print
|
||||
## Step 1 — Build the scene guide (outline)
|
||||
|
||||
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
|
||||
~36 KB file. Then write `outline.json` — the guide for every scene — in exactly this
|
||||
shape:
|
||||
@ -137,7 +142,7 @@ through the guide first — never straight into a scene file.
|
||||
## Step 3 — Compose the scenes one at a time
|
||||
|
||||
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,
|
||||
worked example, self-check; ~3.6k tokens as a section, versus ~11k for the whole file).
|
||||
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.
|
||||
|
||||
```sh
|
||||
.venv\Scripts\python.exe 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_01.json --index 1 --total 5
|
||||
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.)
|
||||
@ -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:
|
||||
|
||||
```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
|
||||
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check 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
|
||||
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\build_plan.py" --check plan.json
|
||||
```
|
||||
|
||||
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)
|
||||
|
||||
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
|
||||
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
|
||||
@ -374,5 +379,5 @@ per-scene iteration, or when the user wants to revise single scenes or the guide
|
||||
|
||||
## 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user