---
name: ultimate-ppt-master
description: >
  终极融合PPT大师 / Ultimate Fusion PPT Master: AI-driven presentation
  generation system. Converts source documents (PDF/DOCX/XLSX/URL/Markdown) into
  either editable PPTX decks or editorial/Swiss magazine web slide decks. Use
  automatically when the user asks to create or transform content into a
  presentation, slide deck, PowerPoint, PPT, or PPTX, including phrases such as
  "create PPT", "make presentation", "make a deck", "build slides",
  "turn this into slides", "生成PPT", "做PPT", "做一个ppt", "做一个 PPT",
  "做个PPT", "做个 PPT", "制作演示文稿", "生成演示文稿", "把这个做成PPT",
  "把这份材料做成PPT", "杂志风PPT", "网页PPT", "horizontal swipe deck",
  "editorial magazine presentation", or mentions "终极融合PPT大师",
  "ultimate-ppt-master", "deckweaver", or "ppt-master".
---

# 终极融合PPT大师 Skill

> Ultimate Fusion PPT Master: a Codex skill that fuses editable PPTX generation with magazine-style web deck generation.

**Core Pipeline**: `Request → Output Mode Selection → Source Document → Project Setup → Design Workflow → Generate → Verify → Export/Preview`

## Output Mode Selection (MANDATORY FIRST STEP)

When the user makes a generic PPT request such as "做一个 PPT", "做个 PPT", "帮我做 PPT", "make a deck", or "turn this into slides", first present the two 终极融合PPT大师 modes and wait for the user's choice. Do not start content conversion, project creation, outline writing, or slide generation before this choice.

Use this concise chooser in the user's language:

```markdown
我可以做两种 PPT，先选一种：

1. 可编辑 PowerPoint（PPTX）
   适合：正式汇报、咨询/商业报告、培训课件、需要交给别人继续改的文件。
   特点：输出 .pptx，里面是真实文字、形状和图表，PowerPoint 里可继续编辑。

2. 杂志风网页 PPT（HTML）
   适合：线下分享、发布会、个人演讲、demo day、想要强视觉风格的展示。
   特点：输出单个 index.html，横向翻页，电子杂志/电子墨水风格，有 WebGL 背景和动效；不适合多人在 PowerPoint 里继续编辑。

你想做哪一种？如果不确定，我建议正式材料选 1，演讲分享选 2。
```

Selection rules:
- If the user explicitly asks for editable PPTX, PowerPoint, `.pptx`, business/report/consulting/training deck, or "可编辑", choose **Mode 1: Editable PPTX**.
- If the user explicitly asks for magazine style, web PPT, HTML slides, horizontal swipe deck, editorial magazine, e-ink/electronic ink, Swiss Style, 瑞士风, keynote/showcase/demo-day visual deck, choose **Mode 2: Magazine Web Deck**.
- If the user has already selected "1", "PPTX", "可编辑", "2", "网页", "杂志风", or equivalent, proceed with that mode without asking again.
- If the user asks for both modes, complete them as separate deliverables and keep their project folders separate.

> [!CAUTION]
> ## 🚨 Global Execution Discipline (MANDATORY)
>
> **This workflow is a strict serial pipeline. The following rules have the highest priority — violating any one of them constitutes execution failure:**
>
> 1. **SERIAL EXECUTION** — Steps MUST be executed in order; the output of each step is the input for the next. Non-BLOCKING adjacent steps may proceed continuously once prerequisites are met, without waiting for the user to say "continue"
> 2. **BLOCKING = HARD STOP** — Steps marked ⛔ BLOCKING require a full stop; the AI MUST wait for an explicit user response before proceeding and MUST NOT make any decisions on behalf of the user
> 3. **NO CROSS-PHASE BUNDLING** — Cross-phase bundling is FORBIDDEN. (Note: the Eight Confirmations in Step 4 are ⛔ BLOCKING — the AI MUST present recommendations and wait for explicit user confirmation before proceeding. Once the user confirms, all subsequent non-BLOCKING steps — design spec output, SVG generation, speaker notes, and post-processing — may proceed automatically without further user confirmation)
> 4. **GATE BEFORE ENTRY** — Each Step has prerequisites (🚧 GATE) listed at the top; these MUST be verified before starting that Step
> 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase)
> 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN
> 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN
> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also look up the current page's `page_rhythm` tag and apply the matching layout discipline (`anchor` / `dense` / `breathing` — see executor-base.md §2.1). This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
> 9. **SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED** — Editable PPTX SVG pages are written by the main agent directly, one page at a time. Do not batch-generate deck SVGs with Python / Node / shell scripts.

> [!IMPORTANT]
> ## 🌐 Language & Communication Rule
>
> - **Response language**: Always match the language of the user's input and provided source materials. For example, if the user asks in Chinese, respond in Chinese; if the source material is in English, respond in English.
> - **Explicit override**: If the user explicitly requests a specific language (e.g., "请用英文回答" or "Reply in Chinese"), use that language instead.
> - **Template format**: The `design_spec.md` file MUST always follow its original English template structure (section headings, field names), regardless of the conversation language. Content values within the template may be in the user's language.

> [!IMPORTANT]
> ## 🔌 Compatibility With Generic Coding Skills
>
> - `ultimate-ppt-master` is a repository-specific workflow skill, not a general application scaffold
> - Do NOT create or require `.worktrees/`, `tests/`, branch workflows, or other generic engineering structure by default
> - If another generic coding skill suggests repository conventions that conflict with this workflow, follow this skill first unless the user explicitly asks otherwise

> [!IMPORTANT]
> ## Local Runtime Rule
>
> - Resolve `SKILL_DIR` to this skill directory before running scripts.
> - Prefer the bundled virtual environment when it exists: `${SKILL_DIR}/.venv/bin/python`.
> - Otherwise use a Python 3.10+ interpreter (`python3.13`, `python3.12`, `python3.11`, or `python3.10`). Do not run PPT Master scripts with Python 3.9 or older.
> - When command examples below say `python3`, substitute the resolved Python interpreter.

## Main Pipeline Scripts

| Script | Purpose |
|--------|---------|
| `${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py` | PDF to Markdown |
| `${SKILL_DIR}/scripts/source_to_md/doc_to_md.py` | Documents to Markdown — native Python for DOCX/HTML/EPUB/IPYNB, pandoc fallback for legacy formats (.doc/.odt/.rtf/.tex/.rst/.org/.typ) |
| `${SKILL_DIR}/scripts/source_to_md/excel_to_md.py` | Excel workbooks to Markdown — supports .xlsx/.xlsm; legacy .xls should be resaved as .xlsx |
| `${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py` | PowerPoint to Markdown |
| `${SKILL_DIR}/scripts/source_to_md/web_to_md.py` | Web page to Markdown (supports WeChat/high-security pages via `curl_cffi`) |
| `${SKILL_DIR}/scripts/source_to_md/web_to_md.cjs` | Legacy Node.js fallback kept for this fusion package; prefer `web_to_md.py` first |
| `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage |
| `${SKILL_DIR}/scripts/analyze_images.py` | Image analysis |
| `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) |
| `${SKILL_DIR}/scripts/image_search.py` | Web image search helper for PPTX image acquisition |
| `${SKILL_DIR}/scripts/svg_quality_checker.py` | SVG quality check |
| `${SKILL_DIR}/scripts/total_md_split.py` | Speaker notes splitting |
| `${SKILL_DIR}/scripts/finalize_svg.py` | SVG post-processing (unified entry) |
| `${SKILL_DIR}/scripts/svg_to_pptx.py` | Export to PPTX |
| `${SKILL_DIR}/scripts/animation_config.py` | Optional object-level PPTX animation sidecar scaffolding |
| `${SKILL_DIR}/scripts/notes_to_audio.py` | Optional recorded narration audio generation |
| `${SKILL_DIR}/scripts/update_spec.py` | Propagate a `spec_lock.md` color / font_family change across all generated SVGs |
| `${SKILL_DIR}/scripts/visual_review.py` | Optional rubric-based visual review pass for generated SVG pages |

For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.

## Template Index

| Index | Path | Purpose |
|-------|------|---------|
| Layout templates | `${SKILL_DIR}/templates/layouts/layouts_index.json` | Query available page layout templates |
| Scenario preset directions | `${SKILL_DIR}/templates/presets/preset-directions.json` | Seed common deck structures, source requirements, template candidates, and QA checks |
| Brand presets | `${SKILL_DIR}/templates/brands/brands_index.json` | Query available brand identity presets (color / typography / logo / voice) |
| Visualization templates | `${SKILL_DIR}/templates/charts/charts_index.json` | Query available visualization SVG templates (charts, infographics, diagrams, frameworks) |
| Icon library | `${SKILL_DIR}/templates/icons/` | See `${SKILL_DIR}/templates/icons/README.md`; search icons on demand with `ls templates/icons/<library>/ \| grep <keyword>` |
| Magazine Web Style A template | `${SKILL_DIR}/assets/magazine-web/template.html` | Single-file editorial/e-ink web deck seed |
| Magazine Web Style B template | `${SKILL_DIR}/assets/magazine-web/template-swiss.html` | Single-file Swiss Style web deck seed |
| Magazine Web references | `${SKILL_DIR}/references/magazine-web/` | Themes, layouts, components, image prompts, screenshot framing, and QA checklists |

## Standalone Workflows

| Workflow | Path | Purpose |
|----------|------|---------|
| `topic-research` | `workflows/topic-research.md` | Pre-pipeline research when the user supplies only a topic with no source files |
| `create-template` | `workflows/create-template.md` | Standalone template creation workflow |
| `create-brand` | `workflows/create-brand.md` | Standalone brand-only template creation workflow |
| `resume-execute` | `workflows/resume-execute.md` | Resume SVG execution in a fresh chat after Step 1-5 |
| `verify-charts` | `workflows/verify-charts.md` | Chart coordinate calibration before export |
| `customize-animations` | `workflows/customize-animations.md` | Optional object-level PPTX animation customization |
| `generate-audio` | `workflows/generate-audio.md` | Optional recorded narration/audio workflow |
| `live-preview` | `workflows/live-preview.md` | Browser-based live preview and annotation workflow |
| `visual-review` | `workflows/visual-review.md` | Optional per-page visual review pass after SVG generation and before post-processing |

---

## Mode 2: Magazine Web Deck Workflow

Use this workflow only when Output Mode Selection chooses the magazine-style web deck.

### Web Step 1: Clarify the Deck Brief

Choose one visual sub-style before copying a template:

| Style | Use when | Template | References |
|---|---|---|---|
| **A · 电子杂志 × 电子墨水** (default) | the user says magazine, editorial, e-ink, Monocle-like, humanistic, narrative, or does not specify a sub-style | `assets/magazine-web/template.html` | `themes.md`, `layouts.md`, `components.md` |
| **B · 瑞士国际主义 / Swiss Style** | the user says Swiss Style, 瑞士风, Helvetica, grid, information design, data-driven, product/engineering/KPI deck | `assets/magazine-web/template-swiss.html` | `themes-swiss.md`, `layouts-swiss.md`, `swiss-layout-lock.md` |

If the user has not already provided these details, ask concise questions one at a time: sub-style A/B, audience/scenario, talk duration or target page count, source material, image availability/screenshot handling, theme preference, and hard constraints. If enough information is present, proceed with a stated assumption. Preserve Style A as the default so the original magazine/e-ink aesthetic remains unchanged.

If the user needs help with structure, propose a narrative arc:

`Hook → Context → Core → Shift → Takeaway`

### Web Step 2: Create the HTML Deck Folder

Create a folder for the web deck, usually `<project_name>/ppt/`, with an adjacent `images/` directory. Copy the seed template:

```bash
mkdir -p "<project_path>/ppt/images" "<project_path>/ppt/assets"
cp "${SKILL_DIR}/assets/magazine-web/motion.min.js" "<project_path>/ppt/assets/motion.min.js"
```

Style A · editorial/e-ink:

```bash
cp "${SKILL_DIR}/assets/magazine-web/template.html" "<project_path>/ppt/index.html"
```

Style B · Swiss Style:

```bash
cp "${SKILL_DIR}/assets/magazine-web/template-swiss.html" "<project_path>/ppt/index.html"
```

Immediately replace the `<title>` placeholder in `index.html`; grep for `[必填]` and remove all remaining placeholders before delivery.

### Web Step 3: Choose Theme and Layouts

Read only the needed magazine references based on selected style:

- Style A theme choice: `${SKILL_DIR}/references/magazine-web/themes.md`
- Style A layout skeletons and theme rhythm rules: `${SKILL_DIR}/references/magazine-web/layouts.md`
- Style B theme choice: `${SKILL_DIR}/references/magazine-web/themes-swiss.md`
- Style B locked layout skeletons: `${SKILL_DIR}/references/magazine-web/layouts-swiss.md`
- Style B layout lock rules: `${SKILL_DIR}/references/magazine-web/swiss-layout-lock.md`
- Shared component details: `${SKILL_DIR}/references/magazine-web/components.md`
- Screenshot framing: `${SKILL_DIR}/references/magazine-web/screenshot-framing.md` (only when screenshots/UI captures are used)
- Optional generated image prompts: `${SKILL_DIR}/references/magazine-web/image-prompts.md`
- Final QA: `${SKILL_DIR}/references/magazine-web/checklist.md`

Rules:
- For Style A, use one of the five curated themes; for Style B, use one of the Swiss theme presets. Do not invent custom hex colors unless the user explicitly overrides the aesthetic system.
- Do not mix Style A and Style B class systems in one deck. Copy one template and use the matching layout reference only.
- Plan page rhythm before writing slides: every `<section>` must include `light`, `dark`, `hero light`, or `hero dark`.
- Use the layout skeletons instead of writing slides from scratch.
- Before adding slide markup, inspect the `<style>` block in `index.html` and confirm every class used by the chosen skeleton exists.
- Put images under `ppt/images/` and reference them with relative paths like `images/01-cover.jpg`.
- For Style B, every slide should carry a registered `data-layout` value from `swiss-layout-lock.md`, and local images should include `data-image-slot` when the layout defines an image slot.

### Web Step 4: Generate, Preview, and Check

Fill `<main id="deck">` with the selected sections, then run these checks:

```bash
grep -n "\\[必填\\]" "<project_path>/ppt/index.html"
grep -n 'class="slide' "<project_path>/ppt/index.html"
```

For Style B, also run the static Swiss lock validator:

```bash
node "${SKILL_DIR}/scripts/validate-swiss-deck.mjs" "<project_path>/ppt/index.html"
```

Open the file directly in a browser:

```bash
open "<project_path>/ppt/index.html"
```

Use `${SKILL_DIR}/references/magazine-web/checklist.md` for final QA. P0 issues must be fixed before delivery. The output is `index.html`, not a `.pptx`.

---

## Mode 1: Editable PPTX Workflow

### Step 1: Source Content Processing

🚧 **GATE**: User has provided source material (PDF / DOCX / EPUB / URL / Markdown file / text description / conversation content — any form is acceptable).

If the user provides only a topic name or brief requirements with no source files or substantive source content, run `workflows/topic-research.md` first, then return here with the generated Markdown/source materials.

When the user provides non-Markdown content, convert immediately:

| User Provides | Command |
|---------------|---------|
| PDF file | `python3 ${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py <file>` |
| DOCX / Word / Office document | `python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>` |
| XLSX / XLSM / Excel workbook | `python3 ${SKILL_DIR}/scripts/source_to_md/excel_to_md.py <file>` |
| CSV / TSV | Read directly as plain-text table source |
| PPTX / PowerPoint deck | `python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>` |
| EPUB / HTML / LaTeX / RST / other | `python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>` |
| Web link | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` |
| WeChat / high-security site | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` (requires `curl_cffi`; falls back to `node web_to_md.cjs <URL>` only if that package is unavailable) |
| Markdown | Read directly |

> **Office vector assets (EMF/WMF) from DOCX/PPTX sources**: preserve extracted EMF/WMF files as first-class vector assets. Do not convert them to PNG unless the user explicitly accepts rasterization; `finalize_svg.py` skips them and `svg_to_pptx.py` embeds them as native Office media.

**✅ Checkpoint — Confirm source content is ready, proceed to Step 2.**

---

### Step 2: Project Initialization

🚧 **GATE**: Step 1 complete; source content is ready (Markdown file, user-provided text, or requirements described in conversation are all valid).

```bash
python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>
```

Format options: `ppt169` (default), `ppt43`, `xhs`, `story`, etc. For the full format list, see `references/canvas-formats.md`.

Import source content (choose based on the situation):

| Situation | Action |
|-----------|--------|
| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --move` |
| User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |

> ⚠️ **MUST use `--move`**: All source files (original PDF / MD / images) MUST be **moved** (not copied) into `sources/` for archiving.
> - Markdown files generated in Step 1, original PDFs, original MDs — **all** must be moved into the project via `import-sources --move`
> - Intermediate artifacts (e.g., `_files/` directories) are handled automatically by `import-sources`
> - After execution, source files no longer exist at their original location

**✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**

---

### Step 3: Template Option

🚧 **GATE**: Step 2 complete; project directory structure is ready.

**Default path — free design, no question asked.** Proceed directly to Step 4. Do NOT query `layouts_index.json` and do NOT ask the user an A/B template-vs-free-design question. Free design is the standard mode: the AI tailors structure and style to the specific content.

**Template flow is opt-in.** Enter it only when one of these explicit triggers appears in the user's prior messages:

1. User names a specific template (e.g., "用 mckinsey 模板" / "use the academic_defense template")
2. User names a style / brand reference that maps to a template (e.g., "McKinsey 那种" / "Google style" / "学术答辩样式")
3. User explicitly asks what templates exist (e.g., "有哪些模板可以用")

**Scenario preset hint (non-blocking).** If the task clearly matches a common scenario, read `${SKILL_DIR}/templates/presets/preset-directions.json` and use the matching preset to seed the narrative, source requirements, recommended slide roster, candidate charts, and quality checks. This does not force a visual template. Only copy layout/brand template files when the user explicitly requests that template, asks what templates exist and chooses one, or the handoff manifest already contains an explicit preset/template selection.

Only when a trigger fires: read `${SKILL_DIR}/templates/layouts/layouts_index.json`, resolve the match (or list available options for trigger 3), and copy template files to the project directory:

```bash
cp ${SKILL_DIR}/templates/layouts/<template_name>/*.svg <project_path>/templates/
cp ${SKILL_DIR}/templates/layouts/<template_name>/design_spec.md <project_path>/templates/
cp ${SKILL_DIR}/templates/layouts/<template_name>/*.png <project_path>/images/ 2>/dev/null || true
cp ${SKILL_DIR}/templates/layouts/<template_name>/*.jpg <project_path>/images/ 2>/dev/null || true
```

**Soft hint (non-blocking, optional).** Before Step 4, if the user's content is an obvious strong match for an existing template (e.g., clearly an academic defense, a government report, a McKinsey-style consulting deck) AND the user has given no template signal, the AI MAY emit a single-sentence notice and continue without waiting:

> Note: the library has a template `<name>` that matches this scenario closely. Say the word if you want to use it; otherwise I'll continue with free design.

This is a hint, not a question — do NOT block, do NOT require an answer. Skip the hint entirely when the match is weak or ambiguous.

> To create a new global template, read `workflows/create-template.md`

**✅ Checkpoint — Default path proceeds to Step 4 without user interaction. If a template trigger fired, template files are copied before advancing.**

---

### Step 4: Strategist Phase (MANDATORY — cannot be skipped)

🚧 **GATE**: Step 3 complete; default free-design path taken, or (if triggered) template files copied into the project.

First, read the role definition:
```
Read references/strategist.md
```

> ⚠️ **Mandatory gate in `strategist.md`**: Before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and produce the spec following its full I–XI section structure. See `strategist.md` Section 1 for the explicit gate rule.

**Must complete the Eight Confirmations** (full template structure in `templates/design_spec_reference.md`):

⛔ **BLOCKING**: The Eight Confirmations MUST be presented to the user as a bundled set of recommendations, and you MUST **wait for the user to confirm or modify** before outputting the Design Specification & Content Outline. This is the single core confirmation point in the workflow. Once confirmed, all subsequent script execution and slide generation should proceed fully automatically.

1. Canvas format
2. Page count range
3. Target audience
4. Style objective
5. Color scheme
6. Icon usage approach
7. Typography plan
8. Image usage approach

After the eight items, append one short split-mode note in the user's language. For large page counts or bulky sources, recommend switching to `workflows/resume-execute.md` after Step 5 by opening a fresh chat and entering `继续生成 projects/<project_name>`; for normal scale, state that continuous mode is the default and split mode remains available.

If the user has provided images, run the analysis script **before outputting the design spec** (do NOT directly read/open image files — use the script output only):
```bash
python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
```

> ⚠️ **Image handling rule**: The AI must NEVER directly read, open, or view image files (`.jpg`, `.png`, etc.). All image information must come from the `analyze_images.py` script output or the Design Specification's Image Resource List.

**Output**:
- `<project_path>/design_spec.md` — human-readable design narrative
- `<project_path>/spec_lock.md` — machine-readable execution contract (distilled from the decisions in design_spec.md; Executor re-reads this before every page). See `templates/spec_lock_reference.md` for the skeleton.

**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:
```markdown
## ✅ Strategist Phase Complete
- [x] Eight Confirmations completed (user confirmed)
- [x] Design Specification & Content Outline generated
- [x] Execution lock (spec_lock.md) generated
- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase
```

---

### Step 5: Image Acquisition Phase (Conditional)

🚧 **GATE**: Step 4 complete; Design Specification & Content Outline generated and user confirmed.

> **Trigger condition**: at least one Design Spec image row needs `Acquire Via: ai` and/or `Acquire Via: web`. If every row is `user` or `placeholder`, skip directly to Step 6.

Always read the common framework first:

```
Read references/image-base.md
```

Then lazy-load only the needed path-specific reference:

| Acquire Via | Load reference | Run |
|---|---|---|
| `ai` | `references/image-generator.md` | `python3 ${SKILL_DIR}/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json` |
| `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` |
| `user` / `placeholder` | skip | skip |

**✅ Checkpoint — Confirm image generation attempted for every row, proceed to Step 6**:
```markdown
## ✅ Image_Generator Phase Complete
- [x] Prompt document created
- [x] Each image: status is either `Generated` (file present in images/) or `Needs-Manual` (reported to user with filename + reason)
- [x] No row remains `Pending`
```

> On generation failure, do NOT halt — follow the Failure Handling rule in `references/image-generator.md` §4.3: retry once, then mark the row `Needs-Manual`, report to user, and continue to Step 6.

---

### Step 6: Executor Phase

🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready.

Read the role definition based on the selected style:
```
Read references/executor-base.md          # REQUIRED: common guidelines
Read references/shared-standards.md       # REQUIRED: SVG/PPT technical constraints
Read references/executor-general.md       # General flexible style
Read references/executor-consultant.md    # Consulting style
Read references/executor-consultant-top.md # Top consulting style (MBB level)
```

> Only need to read executor-base + shared-standards + one style file.

**Design Parameter Confirmation (Mandatory)**: Before generating the first SVG, the Executor MUST review and output key design parameters from the Design Specification (canvas dimensions, color scheme, font plan, body font size) to ensure spec adherence. See executor-base.md Section 2 for details.

**Live Preview Auto-Startup (Mandatory)**: before generating the first SVG, start the browser editor in live mode and keep it running through Executor + export:
```bash
python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live
```
- Start it immediately when Executor begins; `svg_output/` may still be empty.
- Default URL is `http://localhost:5050`; if the port is occupied, use `--port <other>` and report the actual URL.
- Run it as a long-running side process. Do not wait for it to exit before generating pages.
- Do not read or apply submitted annotations during generation. If the user later asks to apply annotations, use `workflows/live-preview.md` after export.

**Pre-generation Batch Read (Mandatory)**: before the first SVG, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` and every distinct chart SVG referenced in `spec_lock.page_charts` (plus backup chart references). One read per file, up front.

**Per-page spec_lock re-read (Mandatory)**: Before generating **each** SVG page, Executor MUST `read_file <project_path>/spec_lock.md` and use only the colors / fonts / icons / images listed there, plus the per-page `page_rhythm`, `page_layouts`, and `page_charts` lookups. This resists context-compression drift on long decks. See executor-base.md §2.1 for details.

> ⚠️ **Main-agent only rule**: SVG generation in Step 6 MUST remain with the current main agent because page design depends on full upstream context (source content, design spec, template mapping, image decisions, and cross-page consistency). Do NOT delegate any slide SVG generation to sub-agents.
> ⚠️ **Generation rhythm rule**: After confirming the global design parameters, the Executor MUST generate pages sequentially, one page at a time, while staying in the same continuous main-agent context. Do NOT split Step 6 into grouped page batches such as 5 pages per batch.

**Visual Construction Phase**:
- Generate SVG pages sequentially, one page at a time, in one continuous pass → `<project_path>/svg_output/`

**Quality Check Gate (Mandatory)** — after all SVGs are generated and BEFORE speaker notes:
```bash
python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
```
- Any `error` (banned SVG features, viewBox mismatch, spec_lock drift, etc.) MUST be fixed on the offending page before proceeding — go back to Visual Construction, re-generate that page, re-run the check.
- `warning` entries (e.g., low-resolution image, non-PPT-safe font tail) should be reviewed and fixed when straightforward; may be acknowledged and released otherwise.
- Running the checker against `svg_output/` is required — running it only after `finalize_svg.py` is too late (finalize rewrites SVG and some violations get masked).

**Logic Construction Phase**:
- Generate speaker notes → `<project_path>/notes/total.md`

**✅ Checkpoint — Confirm all SVGs and notes are fully generated and quality-checked. Proceed directly to Step 7 post-processing**:
```markdown
## ✅ Executor Phase Complete
- [x] All SVGs generated to svg_output/
- [x] svg_quality_checker.py passed (0 errors)
- [x] Speaker notes generated at notes/total.md
```

> **Chart pages?** If this deck contains data charts, run `workflows/verify-charts.md` before Step 7 to calibrate coordinates. Skip when the deck has no chart pages.

---

### Step 7: Post-processing & Export

🚧 **GATE**: Step 6 complete; all SVGs generated to `svg_output/`; speaker notes `notes/total.md` generated.

🚧 **Image readiness GATE**: if Step 5 left any `Needs-Manual` image rows, every expected file must exist at `project/images/<filename>` before running Step 7.1. If files are missing, pause and report filenames plus required locations.

> ⚠️ The following three sub-steps MUST be **executed individually one at a time**. Each command must complete and be confirmed successful before running the next.
> ❌ **NEVER** put all three commands in a single code block or single shell invocation.

Run the canonical three-command pipeline (same as `references/shared-standards.md` §5):

**Step 7.1** — Split speaker notes:
```bash
python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>
```

**Step 7.2** — SVG post-processing (icon embedding / image crop & embed / text flattening / rounded rect to path):
```bash
python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
```

**Step 7.3** — Export PPTX (embeds speaker notes by default):
```bash
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
# Output: exports/<project_name>_<timestamp>.pptx
#
# Optional SVG snapshot preview:
# python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --svg-snapshot
#
# Optional conversion diagnostics:
# python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --trace-conversion
```

> ❌ **NEVER** use `cp` as a substitute for `finalize_svg.py` — it performs multiple critical processing steps
> ❌ **NEVER** add extra flags like `--only`

**Optional animation flags**: defaults already enable rich entrance animations. Adjust only when the user asks:
- `-t <effect>` page transition; default `fade`
- `-a <effect>` per-element entrance animation; default `mixed`
- `--animation-trigger {on-click,with-previous,after-previous}`
- `--animation-config <path>` optional object-level sidecar, usually created through `workflows/customize-animations.md`
- `--auto-advance <seconds>` kiosk-style auto-play

**Optional recorded narration**: only when the user asks for narration/audio/video export, run `workflows/generate-audio.md`. Do not call `notes_to_audio.py` directly without that workflow, because backend/voice/rate/embed choices must be confirmed once.

> **Post-export annotation window**: if the live preview service is still running and the user submitted annotations, apply them only after export via `workflows/live-preview.md`.

---

## Role Switching Protocol

Before switching roles, you **MUST first read** the corresponding reference file — skipping is FORBIDDEN. Output marker:

```markdown
## [Role Switch: <Role Name>]
📖 Reading role definition: references/<filename>.md
📋 Current task: <brief description>
```

---

## Reference Resources

| Resource | Path |
|----------|------|
| Shared technical constraints | `references/shared-standards.md` |
| Canvas format specification | `references/canvas-formats.md` |
| Image layout specification | `references/image-layout-spec.md` |
| SVG image embedding | `references/svg-image-embedding.md` |
| Icon library | `templates/icons/README.md` |

---

## Notes

- Local preview: `python3 -m http.server -d <project_path>/svg_final 8000`
- **Troubleshooting**: If the user encounters issues during generation (layout overflow, export errors, blank images, etc.), recommend checking `docs/faq.md` — it contains known solutions sourced from real user reports and is continuously updated
