diff --git a/README.md b/README.md index 4b14a32..79c7050 100755 --- a/README.md +++ b/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. diff --git a/h3-plan-gate/SKILL.md b/h3-plan-gate/SKILL.md index ca7a256..8b51927 100755 --- a/h3-plan-gate/SKILL.md +++ b/h3-plan-gate/SKILL.md @@ -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.