AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
docs(rules): add prompt-layers — what belongs in a prompt file and where it lives
hugohe3af2fdfab9b8f
diff --git a/AGENTS.md b/AGENTS.mdindex dfa9be24..4fc84303 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -42,6 +42,7 @@ PPT Master turns source material into natively editable DrawingML PPTX. Generate## Required Conventions- **Repo-wide style rules** — when editing prompt files under [`skills/ppt-master/references/`](skills/ppt-master/references/), Python under [`skills/ppt-master/scripts/`](skills/ppt-master/scripts/), or any other code/prose in the repo, follow the matching style rule in [`docs/rules/`](docs/rules/).+- **Prompt content layers** — follow [`docs/rules/prompt-layers.md`](docs/rules/prompt-layers.md): a prompt file holds craft (design judgment) and the minimal contract the model writes; enforced grammar, importer behavior, and restated procedure live in [`scripts/docs/`](skills/ppt-master/scripts/docs/), one owner per rule with pointers elsewhere.- **Prompt decision ownership** — follow [`docs/rules/prompt-style.md`](docs/rules/prompt-style.md) §4.1. Default Strategist prepares project-local resources and Executor realizes them; Quick's current agent decides and prepares before SVG authoring. This is not downstream acquisition. Every project icon is prepared material; `icons.inventory` indexes the default plan's curated bundled pool, not page usage or an execution whitelist. Sounds follow [`animations.md`](skills/ppt-master/references/animations.md) §2.2.- **Markdown language consistency** — follow [`docs/rules/language.md`](docs/rules/language.md): one language per file, mirroring the siblings in that directory; a non-English string may appear in an English file only as quoted content (user trigger text, sample values, rendered labels, proper nouns), never as the wording of a rule; never hard-code which language the model replies in. Chat replies are unaffected.diff --git a/docs/rules/README.md b/docs/rules/README.mdindex 7d6d94f3..ab918b45 100644--- a/docs/rules/README.md+++ b/docs/rules/README.md@@ -5,6 +5,7 @@ Conventions and style guides for contributors and AI agents working in this repo| Rule | Scope ||---|---|| [`prompt-style.md`](./prompt-style.md) | Style guide for files under `skills/ppt-master/references/` — voice, sectioning, table-first, forbidden patterns |+| [`prompt-layers.md`](./prompt-layers.md) | What belongs in a prompt file — craft vs minimal contract vs tool documentation, where each lives, and how to move content out without losing a rule || [`code-style.md`](./code-style.md) | Style guide for Python under `skills/ppt-master/scripts/` — file headers, imports, CLI entry points, error handling, no-tests rule || [`language.md`](./language.md) | Language rule for agent-facing Markdown and `docs/` — one language per file, non-English as content but never as a rule, no hard-coded output language |diff --git a/docs/rules/prompt-layers.md b/docs/rules/prompt-layers.mdnew file mode 100644index 00000000..c1fbf78c--- /dev/null+++ b/docs/rules/prompt-layers.md@@ -0,0 +1,55 @@+# Prompt Content Layers++> Which content belongs in a prompt file at all, and where each kind lives. Applies to every file the runtime loads: `skills/ppt-master/references/`, `skills/ppt-master/workflows/`, `skills/ppt-master/templates/*.md`, `SKILL.md`, and `AGENTS.md`. [`prompt-style.md`](prompt-style.md) governs how those files are written; this rule governs what goes into them.++The prompt files are read by a model before it plans a deck and hand-writes SVG slides. Everything in them competes for the model's attention with the design decisions it is about to make. A paragraph earns its place only by being one of the first two kinds below.++---++## 1. The three kinds++| Kind | Test | Lives in | Example |+|---|---|---|---|+| **Craft** — design judgment | Changing it changes what the page looks like or says | The prompt file of the phase that makes the decision, once | The Visual Job Router, the elevation table and one-light-source default, overlay recipes, the contour-before-encoding gate, the communication-contract table, the cover and closing rules |+| **Contract** — minimal form | The one canonical form the model must write, plus a boundary the tools cannot enforce | Beside the craft that uses it, as one example and one line | One XML example per effect; "a gradient stroke needs a path with both width and height"; "never put `filter` and `clip-path` on the same `<image>`" |+| **Tool documentation** — converter and importer behavior | The checker or exporter already enforces it, or it describes import/normalization/`--strict` behavior, or it restates a procedure another phase owns | `skills/ppt-master/scripts/docs/`, never a prompt file | Accepted-but-warned spellings, DrawingML numeric ranges, crop-transport quantization, closed transform/path grammars, server lifecycle, sidecar schemas |++**Hard rule — enforced grammar is not prose**: a rule that `svg_quality_checker.py` or `svg_to_pptx` preflight already rejects needs nothing in the prompt beyond its canonical form. The failing check teaches the boundary at the moment it matters, with the exact message; a paragraph read before authoring cannot compete with that.++**Hard rule — a selection cue stays with the craft**: when a contract paragraph also says *when to choose* one construction over another ("a thin circle with a preset dash stays a native ellipse line; the shorthand is for thick rings"), that sentence is craft. Keep it in the prompt file even when the rest of the paragraph moves. Moving a whole paragraph by its heading is how selection cues get lost.++---++## 2. Where each kind lives++| Location | Holds | Loaded by |+|---|---|---|+| `references/<role>*.md`, `workflows/**.md` | Craft and contract, one owner per rule, organized by the phase that decides it (Plan: Strategist and the Generate Steps 1–5 / Quick §2; Do·Check·Act: Executor and Steps 6–7 / Quick §3–4 — see [`SKILL.md`](../../skills/ppt-master/SKILL.md) Phase Frame) | The runtime load sets in `scripts/prompt_audit_manifest.json` |+| `scripts/docs/<topic>.md` | Tool documentation. A contract reference that mirrors a prompt file keeps that file's section numbers (`svg-contract.md` §1.1–§2.2 mirror `shared-standards-core.md`, Part II §6.2–§6.10 mirror `svg-effects.md`) so a pointer resolves in either direction | Nobody during generation; `coverage.exempt` in the manifest with a reason |+| `templates/*_reference.md`, `templates/schemas/*.json` | Artifact grammar the model authors against (`design_spec.md`, `spec_lock.md`) | Read at authoring time by the owning Step |++**Hard rule — one owner, pointers elsewhere**: a rule is stated in full in exactly one file. Every other file that needs it carries a pointer naming the file and section, not a paraphrase. A paraphrase is a second owner: it drifts, contradicts the original after the next edit, and doubles the tokens. The cross-file duplicate check in `prompt_audit.py` catches verbatim copies only; paraphrases are caught by reading.++**Hard rule — everyday capabilities stay in the core**: effects, native shapes and their preset vocabulary, relationship grammar, and topology assembly are read before the first page by both Default and Quick. Only a capability most decks never touch (formula, hyperlink, chart/table branches, structured templates, video, animation, web-image attribution) loads on its own observable trigger, and the always-read core still names it in one routing row. Demoting an everyday capability to a trigger does not shrink the run — nearly every deck fires the trigger — and it reintroduces the failure where a capability not in context is never used.++---++## 3. Moving content out of a prompt file++Run this procedure paragraph by paragraph; do not classify by section heading.++1. **Verify enforcement.** `grep` `scripts/svg_quality/` and `scripts/svg_to_pptx/` for the rule's tokens. Enforced → the whole paragraph moves to `scripts/docs/`. Unenforced but export-affecting → one line stays. Unenforced and not export-affecting → it was never a contract; decide whether it is craft or noise.+2. **Extract the selection cue** before moving the rest (§1 above).+3. **Keep the canonical form**: one example, the generated spelling, nothing about accepted alternatives.+4. **Sweep references** after removing or renumbering a section: `grep -rn "<file>.*§<n>"` across `skills/` and `docs/`. A pointer to a section that no longer exists is a silent loss.+5. **Update the manifest**: move the file between load sets if its role changed, add a `coverage.exempt` entry with a reason for a new tool document, lower the file budget to the new size (budgets are fixed upper bounds; 1000-token increments for large files), and refresh or remove any `schema_grammars` projection whose paragraph you edited.+6. **Run `python3 skills/ppt-master/scripts/prompt_audit.py`** and record the per-file and per-load-set numbers in the commit message.+7. **Review for strength and reach** ([`prompt-style.md`](prompt-style.md) §13): a `Hard rule` that vanished from both the prompt and the tool document, a positive capability statement that no loaded file carries any more, and a Quick-only gap (Quick loads no Strategist module) are the three regressions this kind of edit produces.++---++## 4. What this rule does not permit++- Deleting craft to hit a token target. The ceiling in [`prompt-style.md`](prompt-style.md) §4.1 is met by moving the other two kinds, never by thinning design judgment.+- Turning a `Hard rule` into a pointer to a tool document when no tool enforces it.+- Restating a moved rule "briefly" in the file it left. Brief restatements are the mechanism that produced the bloat.diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.mdindex 71551f01..f6a21152 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -122,19 +122,10 @@ across a role file plus a shared technical file produced richer pages than a4,000-line, 12-file mandatory bundle; the larger bundle flattened expressionwhile passing every structural gate. Treat that as the working ceiling. When acore grows past it, shrink it by removing what is not authoring guidance —-never by demoting an everyday capability to a trigger. Every paragraph in a-prompt file is one of three kinds, and only the first two belong there:--| Kind | Test | Where it lives |-|---|---|---|-| Design judgment | Changes what the page looks like or says | The phase file that makes that decision, once |-| Minimal contract | The one canonical form the model must write, plus a boundary the tools cannot enforce | Beside the capability it governs, as one form and one line |-| Tool documentation | Spellings the checker already rejects, import/export normalization, `--strict` behavior, converter internals, restated procedure from another phase | `scripts/docs/`, or the single owning phase file — never a second prompt file |--A rule that `svg_quality_checker.py` or exporter preflight already enforces-needs no prose beyond its canonical form: the failing check teaches it at the-moment it matters. Verify enforcement with the checker source before moving a-rule out; an unenforced rule that affects export keeps one line.+never by demoting an everyday capability to a trigger. What may stay in a+prompt file at all — craft, minimal contract, or tool documentation — and the+procedure for moving content out are owned by+[`prompt-layers.md`](prompt-layers.md).Default Strategist's planning bundle covers resource/preparation and high-levelexpression options without local authoring parameters, because those choices are