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(executor): tighten prose, keep all rules and concrete values
hugohe36b2a926ae683
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 07fc73f1..b1cfdd6f 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -6,7 +6,7 @@## 1. Template Adherence Rules-If template files exist in the project's `templates/` directory, the template structure must be followed:+If `templates/` exists in the project, follow the template structure:| Page Type | Corresponding Template | Adherence Rules ||-----------|----------------------|-----------------|@@ -18,43 +18,39 @@ If template files exist in the project's `templates/` directory, the template st### Page-Template Mapping Declaration (Required Output)-Before generating each page, you must explicitly output which template (or "free design") is used:+Before generating each page, output which template is used:```📝 **Template mapping**: `templates/01_cover.svg` (or "None (free design)")🎯 **Adherence rules / layout strategy**: [specific description]```-- **Content pages**: Templates only define header and footer; the content area is freely laid out by the Executor-- **No template**: Generate entirely per the Design Specification & Content Outline+- **Content pages**: template defines only header/footer; content area is free+- **No template**: generate entirely per the Design Spec---## 2. Design Parameter Confirmation (Mandatory Step)-> Before generating the first SVG page, you **must review the key design parameters from the Design Specification & Content Outline** to ensure all subsequent generation strictly follows the spec.--Must output confirmation including: canvas dimensions, body font size, color scheme (primary/secondary/accent HEX values), font plan.--**Why is this step mandatory?** Prevents the "spec says one thing, execution does another" disconnect.+Before the first SVG page, output a confirmation listing: canvas dimensions, body font size, color scheme (primary/secondary/accent HEX), font plan. Prevents spec/execution drift.### 2.1 Per-page spec_lock re-read (Mandatory)-> Long decks + streaming generation = attention drift and context compression. By mid-deck, the Executor has often drifted off the color palette or icon inventory declared in `design_spec.md`. `spec_lock.md` is the short form of those decisions and is the Executor's **canonical execution reference** during generation.+> Long decks drift off the declared palette/icons mid-deck due to context compression. `spec_lock.md` is the canonical execution reference — re-read it per page to bypass model memory.-**Hard rule**: Before generating **each** SVG page, `read_file <project_path>/spec_lock.md`. Use the values from this file — not values you remember from earlier in the conversation. If the context was auto-compacted, `read_file <project_path>/design_spec.md` too (for the current page's §IX brief).+**Hard rule**: Before generating **each** SVG page, `read_file <project_path>/spec_lock.md`. Use only values from this file, not from memory. If context was auto-compacted, also `read_file <project_path>/design_spec.md` for the current page's §IX brief.-**If `spec_lock.md` is missing**: Before generating each page, emit the literal line `warning: spec_lock.md missing — generating without execution lock` and proceed using `design_spec.md` narrative values. Do not silently skip. A missing lock is expected only for legacy projects predating this feature; for new projects the Strategist MUST produce it (see [strategist.md](strategist.md) §6, step 4).+**If `spec_lock.md` is missing**: emit `warning: spec_lock.md missing — generating without execution lock` once, then proceed using `design_spec.md` values. Expected only for legacy projects; new projects MUST have it (see [strategist.md](strategist.md) §6 step 4).**Forbidden — values outside the lock**:-- Color values (fill / stroke / stop-color) MUST come from `colors` in `spec_lock.md`-- Icons MUST come from the `icons.inventory` list; icon library MUST equal `icons.library`-- Font family MUST come from the `typography` block: use the role-specific override (`title_family` / `body_family` / `emphasis_family` / `code_family`) if declared for that role, otherwise fall back to `font_family`.-- Font sizes follow a **ramp anchored on `typography.body`**, not a closed menu. The slots listed in `spec_lock.md typography` (`title` / `subtitle` / `annotation` / any project-specific additions like `cover_title` / `hero_number`) are common anchors — use them directly when they fit. Executor MAY use an intermediate size (e.g., 40px hero number, 13px chart annotation, 72px cover headline) when the role calls for it, **provided** the size's ratio to `body` falls within the corresponding role's band in the design-spec ramp table (see `design_spec_reference.md §IV — Font Size Hierarchy`, also mirrored in `design_spec.md §IV` per project). Sizes outside every ramp band are still forbidden — surface the need and extend the lock instead of inventing one-off values.+- Colors (fill / stroke / stop-color) MUST come from `colors`+- Icons MUST come from `icons.inventory`; library MUST equal `icons.library`+- Font family from `typography`: use role override (`title_family` / `body_family` / `emphasis_family` / `code_family`) if declared, else fall back to `font_family`+- Font sizes follow a **ramp anchored on `typography.body`**, not a closed menu. Use the declared slots when they fit. Intermediate sizes (e.g., 40px hero number, 13px annotation) are allowed if the ratio to `body` falls within the role's band (see `design_spec.md §IV ramp table`). Sizes outside every band require extending the lock first.- Images MUST reference files listed under `images`; no invented filenames-If a page genuinely needs a value not in `spec_lock.md`, stop and surface it — do not silently invent one. Either request the user to extend the lock, or revise the page to stay within it.+If a page needs a value not in `spec_lock.md`, surface it — do not silently invent one.**Per-page layout rhythm — `page_rhythm` section**:@@ -66,44 +62,39 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`| `dense` | Information-heavy. Card grids, multi-column layouts, KPI dashboards, tables, and charts are all permitted. This is the baseline behavior. || `breathing` | Low-density impact page. Avoid **multi-card grid layouts** — do not organize content as multiple parallel rounded containers (3-card row, 4-card KPI grid, 2×2 matrix rendered as cards). Use naked text blocks, dividers, whitespace, or full-bleed imagery as the content structure. Single rounded visual elements (hero image corners, callouts, tags, one emphasis block) are fine — the rule is about grid structure, not about the `rx` attribute. Proportions follow information weight (not a preset ratio). Typical forms: hero quote, single large number with one-line interpretation, full-bleed image with floating caption, section transition. |-**Why this matters**: Without rhythm variation, long decks default to "every page is a card grid" — the AI-generated look. The `page_rhythm` tag is the only lever that survives context compression (since Executor re-reads `spec_lock.md` per page); narrative guidance buried in `design_spec.md` does not.+> Without rhythm variation, every page defaults to card grids (the "AI-generated" look). `page_rhythm` is the only narrative lever that survives context compression.-**Missing `page_rhythm` section** → fall back to `dense` for every page (pre-rhythm behavior). Emit the literal line `warning: spec_lock.md missing page_rhythm — defaulting all pages to dense` once, then proceed.+**Missing `page_rhythm` section** → emit `warning: spec_lock.md missing page_rhythm — defaulting all pages to dense` once, fall back to `dense` for all pages.**Tag not found for current page** → fall back to `dense` silently. Do not invent a tag.-**Rationale**: Tool-result re-reads bypass model memory (which compression can corrupt). Every page gets a fresh ground truth pinned to the most recent turn in context.----## 3. Execution Guidelines-- **Proximity principle**: Place related elements close together to form visual groups; increase spacing between unrelated groups to reinforce logical structure-- **Absolute spec adherence**: Strictly follow the color, layout, canvas format, and typography parameters in the spec-- **Follow template structure**: If templates exist, inherit the template's visual framework-- **Main-agent ownership**: SVG generation must be performed by the current main agent, not delegated to sub-agents, because each page depends on shared upstream context and cross-page visual continuity-- **Generation rhythm**: First lock the global design context, then generate pages sequentially one by one in the same continuous context; grouped page batches (for example, 5 pages at a time) are not allowed+- **Proximity**: group related elements with tight spacing; separate unrelated groups+- **Spec adherence**: follow color, layout, canvas format, and typography in the spec+- **Template structure**: if templates exist, inherit the visual framework+- **Main-agent ownership**: SVG generation must run in the main agent (not sub-agents) — pages share upstream context for cross-page visual continuity+- **Generation rhythm**: lock global design context first, then generate pages sequentially in one continuous context. No batched groups (e.g., 5 at a time).- **Phased batch generation** (recommended):- 1. **Visual Construction Phase**: Generate all SVG pages continuously in sequential page order, ensuring high consistency in design style and layout coordinates (Visual Consistency). During the initial SVG draft, do NOT run `svg_position_calculator.py`; use normal layout judgment to place charts and approximate chart marks.- 2. **Quality Check Gate** (mandatory between phases): first run `python3 scripts/svg_quality_checker.py <project_path>` against `svg_output/`. Any `error` (banned SVG features, viewBox mismatch, spec_lock color / font / size drift, non-PPT-safe font stack, etc.) MUST be fixed on the offending page before entering the Logic Construction Phase — re-generate that page and re-run the check. `warning` entries should be reviewed and fixed when straightforward; otherwise acknowledge and release. After the SVG quality checker passes, run the chart coordinate calibration in §5.1 for pages containing chart types supported by `svg_position_calculator.py`. Do NOT defer these checks to after `finalize_svg.py` — finalize rewrites SVG and some violations get masked.- 3. **Logic Construction Phase**: After SVGs pass the quality gate, batch-generate speaker notes to ensure narrative coherence (Narrative Continuity)-- **Technical specifications**: See [shared-standards.md](shared-standards.md) for SVG technical constraints and PPT compatibility rules-- **Visual depth — through restraint, not abundance**: Layered depth comes from rhythm (flat vs lifted, dense vs spacious), not from applying shadows everywhere. Use shadow on at most 2–3 genuinely floating elements per page (cards on photos, primary CTA, overlays); keep section panels, peer-grid cards, dividers, and body-text containers flat. Reach for typography weight, spacing, accent bars, and subtle background tints **before** adding shadow. See shared-standards.md §6 for full rules including single-light-source and elevation tiers.+ 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Do NOT run `svg_position_calculator.py` during the initial draft — use layout judgment for chart marks.+ 2. **Quality Check Gate** (between phases): run `python3 scripts/svg_quality_checker.py <project_path>` on `svg_output/`. Any `error` (banned features, viewBox mismatch, spec_lock drift, non-PPT-safe font, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. Address `warning`s when straightforward. After passing, run §5.1 chart coordinate calibration for calculator-supported chart types. Do NOT defer to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.+ 3. **Logic Construction Phase**: after SVGs pass, batch-generate speaker notes for narrative continuity.+- **Technical specs**: see [shared-standards.md](shared-standards.md) for SVG/PPT constraints+- **Visual depth — through restraint**: layered depth comes from rhythm (flat vs lifted, dense vs spacious), not from shadows everywhere. Apply shadow to at most 2-3 genuinely floating elements per page (cards on photos, primary CTA, overlays); keep peer-grid cards, dividers, body containers flat. Reach for typography weight, spacing, accent bars, subtle tints **before** shadow. Full rules in shared-standards.md §6.### SVG File Naming Convention-File naming format: `<number>_<page_name>.svg`+Format: `<NN>_<page_name>.svg` (two-digit number from 01; name matches the deck's language and the page title in the Design Spec).-- **Chinese content** → Chinese naming: `01_封面.svg`, `02_目录.svg`, `03_核心优势.svg`-- **English content** → English naming: `01_cover.svg`, `02_agenda.svg`, `03_key_benefits.svg`-- **Number rules**: Two-digit numbers, starting from 01-- **Page name**: Concise and descriptive, matching the page title in the Design Specification & Content Outline+Examples: `01_封面.svg` / `02_目录.svg` / `03_核心优势.svg`; `01_cover.svg` / `02_agenda.svg` / `03_key_benefits.svg`.---## 4. Icon Usage-Strategist chooses the icon approach and approved inventory. Executor only implements the approved choice. Built-in library details and the one-library rule are documented in [`../templates/icons/README.md`](../templates/icons/README.md); this section defines the SVG placeholder syntax.+Strategist chooses the library and inventory; Executor only implements. Library details and one-library rule: [`../templates/icons/README.md`](../templates/icons/README.md). This section defines placeholder syntax.**Built-in icons — Placeholder method (recommended)**:@@ -128,11 +119,11 @@ Strategist chooses the icon approach and approved inventory. Executor only imple<use data-icon="tabler-outline/home" x="100" y="200" width="48" height="48" fill="#005587" stroke-width="3"/>```-> ⚠️ **Icon Color Rule**: For `<use data-icon="...">` tags, ALWAYS use `fill="#HEX"` to set the color. NEVER use `stroke` or `fill="none"` on these placeholders, even for stroke-style libraries.+> ⚠️ **Color**: ALWAYS use `fill="#HEX"` on `<use data-icon="...">`. NEVER use `stroke` or `fill="none"`, even for stroke-style libraries.>-> `stroke-width` on the placeholder (stroke-style libraries only — currently `tabler-outline`): allowed values `1.5` / `2` / `3`. **If `spec_lock.md icons` declares `stroke_width`, every placeholder MUST use that exact value, deck-wide.** If the field is absent (legacy decks), default to `2`. Ignored on non-stroke libraries (`chunk-filled` / `tabler-filled` / `phosphor-duotone` / `simple-icons`). Values outside `{1.5, 2, 3}` are forbidden — heavier weight requires switching library, not thicker strokes.+> **stroke-width** (stroke-style libraries only, currently `tabler-outline`): allowed values `{1.5, 2, 3}`. If `spec_lock.md icons.stroke_width` is declared, all placeholders MUST use that value deck-wide. Default `2` if absent (legacy). Ignored on non-stroke libraries.>-> No need to manually run `embed_icons.py`; `finalize_svg.py` post-processing tool will auto-embed icons.+> Icons are auto-embedded by `finalize_svg.py` — no need to run `embed_icons.py` manually.**Searching for icons** — use terminal, zero token cost:```bash@@ -170,36 +161,35 @@ ls skills/ppt-master/templates/icons/simple-icons/ | grep github> For self-evident names (home, user, file, search, arrow, etc.) — just `grep chunk-filled/` directly without consulting the table.-> ⚠️ **Icon validation rule**: If the Design Specification includes an icon inventory list, Executor may **only** use icons from that approved list. Before using any icon, verify it exists via `ls | grep` search. **Mixing icons from different libraries in the same presentation is FORBIDDEN** — use only the library specified in the Design Spec.+> ⚠️ **Icon validation**: only use icons from the Design Spec's approved inventory. Verify each via `ls | grep` before use. Mixing libraries within one deck is FORBIDDEN.---## 5. Visualization Reference-When the Design Spec includes a **VII. Visualization Reference List**, read the referenced SVG templates from `templates/charts/` before drawing pages that use those visualization types. The path remains `templates/charts/` for backward compatibility.+When the Design Spec includes **VII. Visualization Reference List**, read the referenced templates from `templates/charts/` before drawing those pages.-**Reading is mandatory; copying is not.** On first use of any visualization type listed in section VII, read `templates/charts/<chart_name>.svg` before generating that page. Do not improvise from memory. Use the template as reference for layout, card structure, spacing, and visual logic — apply the project's color scheme, typography, and content; do not replicate verbatim.+**Reading is mandatory; copying is not.** On first use of each visualization type listed in §VII, read `templates/charts/<chart_name>.svg`. Use as reference for layout, structure, spacing, visual logic — apply the project's colors, typography, content. Do not improvise from memory; do not replicate verbatim.-> **Reuse**: no re-read for subsequent pages of the same type.-> **Change**: re-read when the visualization type changes.+> Re-read only when the visualization type changes; reuse for subsequent pages of the same type.**Adaptation rules**:-- **Must preserve**: Visualization type (bar/line/pie/timeline/process/framework etc.) as specified in the Design Spec-- **Must adapt**: Data values, labels, colors (match the project's color scheme), and dimensions to fit the page layout-- **May adjust freely**: Visual composition, axis ranges, grid lines, legend position, spacing, decorative elements — creative freedom is encouraged as long as the chart remains accurate and readable-- **Must NOT**: Change visualization type without Design Spec justification, or omit data points / structural elements specified in the outline+- **Preserve**: visualization type (bar/line/pie/timeline/process/framework…) as specified+- **Adapt**: data, labels, colors (project scheme), dimensions+- **Freely adjust**: composition, axis ranges, grid, legend, spacing, decoration — as long as the chart stays accurate and readable+- **Forbidden**: changing visualization type without spec justification; omitting data points or structural elements from the outline-> Visualization templates: `templates/charts/` (70 types). Index: `templates/charts/charts_index.json`+> Templates: `templates/charts/` (70 types). Index: `templates/charts/charts_index.json`### 5.1 Chart Coordinate Calibration (After SVG Quality Checker)-> For pages containing chart types supported by `svg_position_calculator.py`, run the calculator **after** `svg_quality_checker.py` passes and **before** entering the Logic Construction Phase. The goal is to calibrate the already generated SVG against the actual chart plot area. Do NOT run this calculator during the initial SVG draft, and do NOT apply this requirement to every visualization; it only applies to calculator-supported chart types.+> For chart types supported by `svg_position_calculator.py`, run calibration **after** `svg_quality_checker.py` passes and **before** Logic Construction. Calibrates already-generated SVG against the plot area. Do NOT run during initial draft. Only applies to calculator-supported types.-**Workflow for chart pages after `svg_quality_checker.py` passes:**+**Workflow after `svg_quality_checker.py` passes:**-1. **Confirm the chart type is supported** — run this review only for data chart types exposed by the calculator: `bar`, `pie` / `donut`, `radar`, and `line` / `area` / `scatter`. Area charts do **not** have a separate calculator mode; use `calc line` for the upper boundary points, then close the filled area to the plot area's bottom baseline (`y_max`) in the SVG. Grid layout calculation is optional layout assistance, not a mandatory chart calibration target. Other visualizations (timeline, process, framework diagrams, maps, pictograms, etc.) are governed by normal visual/spec review unless they can be explicitly modeled by one of these data chart modes.+1. **Confirm chart type is supported** — calculator covers: `bar`, `pie`/`donut`, `radar`, `line`/`area`/`scatter`. Area has no separate mode — use `calc line` for the top boundary, then close to `y_max`. Grid layout is optional. Other visualizations (timeline, process, framework, maps, pictograms…) skip this step.-2. **Identify the chart plot area** — read it from the SVG layout or derive it from the existing chart frame. The plot area is the data drawing rectangle only; it excludes title, legend, axis labels, footnotes, and surrounding annotations.+2. **Identify the plot area** — the data drawing rectangle only; excludes title, legend, axis labels, footnotes, annotations.Recommended SVG marker when generating chart pages:```xml@@ -226,15 +216,15 @@ When the Design Spec includes a **VII. Visualization Reference List**, read theM first_x,first_y ... L last_x,last_y L last_x,y_max L first_x,y_max Z```-4. **If coordinates differ** — manually update the SVG attributes from the calculator output, then rerun `svg_quality_checker.py` and repeat this coordinate review. Do NOT use regex or bulk text replacement to rewrite SVG coordinates automatically.+4. **If coordinates differ** — manually update SVG attributes from calculator output, rerun `svg_quality_checker.py`, repeat. Do NOT use regex or bulk replacement.-**Why this matters**: AI models routinely introduce 10–50 px coordinate errors when mentally mapping data values to SVG pixel positions. These errors compound across bars, lines, and arcs, producing charts where data proportions are visually wrong. The calculator eliminates this class of error entirely.+> AI models routinely introduce 10-50 px errors when mapping data to pixel positions. Errors compound across bars/lines/arcs, distorting proportions. The calculator eliminates this class of error.---## 6. Image Handling-Handle images based on their status in the Design Specification's "Image Resource List". Status names and lifecycle are defined in [`svg-image-embedding.md`](svg-image-embedding.md).+Handle images by their status in the Design Spec's Image Resource List. Status enum and lifecycle: [`svg-image-embedding.md`](svg-image-embedding.md).| Status | Source | Handling ||--------|--------|----------|@@ -251,11 +241,11 @@ Handle images based on their status in the Design Specification's "Image Resourc## 7. Font Usage-Font family per role is governed by `spec_lock.md typography` — that file is the source of truth. Read `font_family` as the default, plus any `*_family` override (`title_family` / `body_family` / `emphasis_family` / `code_family` / etc.); roles without an explicit override fall back to `font_family`.+Source of truth: `spec_lock.md typography`. Use `font_family` as default; override per role with `title_family` / `body_family` / `emphasis_family` / `code_family` if declared.-If `spec_lock.md` is absent for any reason, consult the seed combinations and PPT-safe discipline in [`strategist.md`](strategist.md) §g "Typography Plan Confirmation" rather than inventing a stack.+If `spec_lock.md` is absent, consult [`strategist.md`](strategist.md) §g — do not invent a stack.-**Hard rule — never violate**: every `font-family` stack emitted into SVG MUST end with a cross-platform pre-installed family (Microsoft YaHei / SimHei / SimSun / Arial / Calibri / Segoe UI / Times New Roman / Georgia / Consolas / Courier New / Impact / Arial Black). PPTX stores a single `typeface` per run with no runtime fallback — a missing font silently degrades to Calibri on the viewer's machine.+**Hard rule**: every SVG `font-family` stack MUST end with a pre-installed family (Microsoft YaHei / SimHei / SimSun / Arial / Calibri / Segoe UI / Times New Roman / Georgia / Consolas / Courier New / Impact / Arial Black). PPTX has no runtime fallback — missing fonts degrade to Calibri.---@@ -263,11 +253,9 @@ If `spec_lock.md` is absent for any reason, consult the seed combinations and PP### Task 1. Generate Complete Speaker Notes Document-After **all SVG pages are generated and finalized**, enter the "Logic Construction Phase" and generate the complete speaker notes document in `notes/total.md`.+After all SVG pages are finalized, enter Logic Construction Phase and write the full notes to `notes/total.md`. Batch-writing (not per-page) lets transitions plan coherently.-**Why not generate page-by-page?** Batch-writing notes allows planning transitions like a script, ensuring coherent presentation logic.--**Format**: Each page starts with `# <number>_<page_title>`, separated by `---` between pages. Each page includes: script text (2-5 sentences), `Key points: ① ② ③`, `Duration: X minutes`. Except for the first page, each page's text starts with a `[Transition]` phrase.+**Format**: Each page: `# <number>_<page_title>` heading, separated by `---`. Each contains 2-5 sentence script, `Key points: ① ② ③`, `Duration: X minutes`. Every page after the first starts with a `[Transition]` phrase.**Basic stage direction markers** (common to all styles):@@ -278,7 +266,7 @@ After **all SVG pages are generated and finalized**, enter the "Logic Constructi> Each style may extend with additional markers (`[Interactive]`/`[Data]`/`[Scan Room]`/`[Benchmark]` etc.), see `executor-{style}.md`.-**Language consistency rule**: All structural labels and stage direction markers in speaker notes **MUST match the presentation's content language**. When the presentation content is non-English, localize every label — do NOT mix English labels with non-English content.+**Language consistency**: structural labels and stage direction markers MUST match the deck's content language. Localize all labels — do NOT mix English labels with non-English content.| English | 中文 | 日本語 | 한국어 ||---------|------|--------|--------|@@ -294,20 +282,13 @@ After **all SVG pages are generated and finalized**, enter the "Logic Constructi> For languages not listed above, translate each label to the corresponding natural term in that language.-**Requirements**:--- Notes should be conversational and flow naturally-- Highlight each page's core information and presentation key points-- Users can manually edit and override in the `notes/` directory+**Requirements**: conversational tone; highlight each page's core info and key points; users may edit/override in `notes/`.### Task 2. Split Into Per-Page Note Files-Automatically split `notes/total.md` into individual speaker note files in the `notes/` directory.--**File naming convention**:+Auto-split `notes/total.md` into per-page files in `notes/`.-- **Recommended**: Match SVG names (e.g., `01_cover.svg` → `notes/01_cover.md`)-- **Compatible**: Also supports `slide01.md` format (backward compatibility)+**Naming**: match SVG names (`01_cover.svg` → `notes/01_cover.md`); `slide01.md` also supported (legacy).---