| 1 | --- |
| 2 | description: Default Generate PPTX authority for source intake, planning, SVG authoring, quality gates, and native PPTX export. |
| 3 | --- |
| 4 | |
| 5 | # Generate PPTX Route |
| 6 | |
| 7 | > Load only after [`routing.md`](./routing.md) selects Default Generate or its |
| 8 | > Beautify profile. This file owns that runtime's Step 1–7 sequence, gates, role |
| 9 | > switching, and mandatory commands. Explicit Quick loads its own profile instead. |
| 10 | |
| 11 | **Default Core Pipeline**: `Initial Materials → [Fact Research] → Create Project → Template Candidate Preparation → Stage-1 Communication + Template Confirmation → [Template Installation] → Stage-2 Solution → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export` |
| 12 | |
| 13 | **Generate-specific execution discipline**: |
| 14 | |
| 15 | - The current main agent hand-writes every SVG page; never delegate page generation or run a Python, Node, or shell generator over `svg_output/`. |
| 16 | - Initial SVG cadence: P01 → first-page gate → uninterrupted remaining pages → final gate. Grouped batches and mid-run checker calls are forbidden. |
| 17 | - `preset_shape_svg.py` and `shape_boolean_svg.py` may provide only their documented stdout fragment(s) after the main agent chooses the object's role, operands, paint, and z-order; neither helper chooses layout or writes a page. |
| 18 | - Gate checklists are internal verification, not user-facing output. On success, continue automatically and emit at most one compact status line when useful; on failure, report only the blocking items and required recovery. |
| 19 | |
| 20 | **Profile boundary**: Explicit Quick is selected before runtime authority |
| 21 | loading and never enters this file. Beautify enters this file only when its |
| 22 | request does not explicitly select Quick. |
| 23 | |
| 24 | ### SVG Page-Design Boundary |
| 25 | |
| 26 | | Scope | Contract | |
| 27 | |---|---| |
| 28 | | Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. | |
| 29 | | Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. | |
| 30 | | Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. They never replace native SVG geometry, text, styles, grouping, or asset references. | |
| 31 | | `svg_final/` | Mandatory derived, self-contained SVG visual preview in the default pipeline. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. Quick-generate skips it. | |
| 32 | | SVG-to-PPTX export | The only supported generated-PPTX route reads `svg_output/` and maps its content through the project converter to DrawingML/native objects. It compiles only the selected route's explicit structure contract: `flat` keeps represented content Slide-local, while `structured` may place explicitly scoped content in Master/Layout/Slide parts. It MUST NOT infer structure, upgrade `flat`, or invent new visible page content. | |
| 33 | | Native PPTX routes and presentation-behavior stages | Remain outside SVG page-design closure. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. | |
| 34 | |
| 35 | **MUST — page-design closure**: For an SVG-authoring route, inspect the final page SVG to determine what the exported slide looks like. Do not reinterpret “SVG is the page-design language” as “SVG is the complete PPTX package description language.” |
| 36 | |
| 37 | ## Cross-Cutting Authorities |
| 38 | |
| 39 | | Concern | Authority | Contract | |
| 40 | |---|---|---| |
| 41 | | Main pipeline sequencing | This file | Owns Step 1–7 order, gates, role switching, and mandatory commands | |
| 42 | | Artifact ownership | [`artifact-ownership.md`](../references/artifact-ownership.md) | Owns fact channels, source/derived artifact boundaries, and regeneration rules | |
| 43 | | Failure recovery | [`failure-recovery.md`](./governance/failure-recovery.md) | Owns stop/continue policy and resume pointers | |
| 44 | | Confirm UI details | [`confirm_ui.md`](../scripts/docs/confirm_ui.md) | Owns the JSON schema, launcher behavior, staged-result contract, port strategy, and chat fallback details | |
| 45 | | Confirmed template application | [`apply-template-workspace.md`](./stages/apply-template-workspace.md) | Owns validation, installation, and fusion after Stage 1 confirms library or explicit workspace roots; skip for confirmed free design | |
| 46 | |
| 47 | ## Workflow |
| 48 | |
| 49 | ### Step 1: Source Content Processing |
| 50 | |
| 51 | 🚧 **GATE**: The user has provided a topic / desired outcome and any available initial material. |
| 52 | |
| 53 | > **Topic-only**: run [`topic-research`](stages/topic-research.md) immediately, then use its factual supplement as source content. |
| 54 | |
| 55 | When the user provides non-Markdown content, convert immediately through the |
| 56 | unified dispatcher. It preserves the backend converters' existing behavior, |
| 57 | routes by source type, and writes the standard Markdown plus conversion profile. |
| 58 | |
| 59 | | User Provides | Action | |
| 60 | |---------------|--------| |
| 61 | | PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` | |
| 62 | | CSV / TSV | Read directly as plain-text table source | |
| 63 | | Markdown | Read directly | |
| 64 | |
| 65 | For PPTX sources, Step 1 converts the deck to Markdown content; after Step 2 |
| 66 | `import-sources`, standard PPTX intake is also written to `<project>/analysis/`. |
| 67 | Use `source_to_md.py -t <type>` only when extension detection is ambiguous. |
| 68 | Default local conversion writes Markdown/profile outputs beside each source file. |
| 69 | Use `-o` only when a specific output file/directory is required; with multiple |
| 70 | inputs or directory inputs, `-o` is an output directory. Backend converter details are documented in |
| 71 | [`scripts/docs/conversion.md`](../scripts/docs/conversion.md). |
| 72 | |
| 73 | After reading direct and converted content, assess factual sufficiency: |
| 74 | |
| 75 | | Material state | Action | |
| 76 | |---|---| |
| 77 | | Requested outcome is supported | Continue Step 2 | |
| 78 | | Required externally verifiable claims remain unsupported | Run [`topic-research`](stages/topic-research.md) for those gaps only | |
| 79 | | Closed corpus / source-only / no external enrichment | Stay within supplied material | |
| 80 | |
| 81 | **Sufficiency test**: research only to avoid inventing, omitting, or leaving unsupported a factual claim the requested outcome requires; file presence or length is irrelevant. It gathers facts only. Step 5 acquires Strategist-selected images after final confirmation. |
| 82 | |
| 83 | > **Office vector assets (EMF/WMF) from DOCX/PPTX sources**: |
| 84 | > Source conversion extracts embedded Office vector images (.emf/.wmf) |
| 85 | > alongside bitmap images when the source format exposes them. After `import-sources`, these land in `images/` |
| 86 | > together with `image_manifest.json` and are first-class assets in §VIII Image Resource List. |
| 87 | > |
| 88 | > **Do NOT convert EMF/WMF to PNG.** The PPT Master pipeline preserves them as external |
| 89 | > references (`finalize_svg.py` skips them) and `svg_to_pptx.py` embeds them as |
| 90 | > PPTX-native media via `image/x-emf` / `image/x-wmf` MIME — PowerPoint renders them at full vector fidelity. |
| 91 | > Converting via LibreOffice/Inkscape introduces CJK font substitution drift and |
| 92 | > rasterization loss; the original EMF/WMF is always higher fidelity than the converted PNG. |
| 93 | > |
| 94 | > Browser-based live preview cannot render EMF (will show blank) — this is expected; |
| 95 | > the PPTX output is the source of truth. |
| 96 | |
| 97 | **✅ Checkpoint — Confirm source content and any factual supplement are ready, proceed to Step 2.** |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | ### Step 2: Project Initialization |
| 102 | |
| 103 | 🚧 **GATE**: Step 1 complete; source content is ready (Markdown file, user-provided text, or requirements described in conversation are all valid). |
| 104 | |
| 105 | ```bash |
| 106 | python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format> |
| 107 | ``` |
| 108 | |
| 109 | Project initialization creates `<project_path>/validation/workflow.log` and |
| 110 | records the initialization milestone. After the project exists, run each |
| 111 | project-scoped Python tool normally. The shared CLI bootstrap automatically |
| 112 | records its command envelope and a bounded set of material outcome lines in |
| 113 | that log; no wrapper command is required. Full console output is not copied. |
| 114 | Detached Confirm UI and live-preview processes retain their detailed output in |
| 115 | their existing component logs. |
| 116 | |
| 117 | When a Python helper serves the active deck but neither its arguments nor its |
| 118 | working directory identifies the project, provide the routing signal on that |
| 119 | same command — still one Python process: |
| 120 | |
| 121 | ```bash |
| 122 | PPT_MASTER_PROJECT_PATH="<project_path>" python3 ${SKILL_DIR}/scripts/<helper>.py <args...> |
| 123 | ``` |
| 124 | |
| 125 | When an important audit detail has no owning command output — for example a |
| 126 | material stage handoff or rework reason, a user-approved exception, or a manual |
| 127 | recovery choice — the active role may append one concise note: |
| 128 | |
| 129 | ```bash |
| 130 | python3 ${SKILL_DIR}/scripts/workflow_log.py <project_path> "<material audit detail>" |
| 131 | ``` |
| 132 | |
| 133 | Notes are selective and non-authoritative. Do not duplicate artifact contents, |
| 134 | routine page progress, or chain-of-thought; current artifacts and gate results |
| 135 | still determine stage and readiness. The transcript is cold audit evidence: |
| 136 | never read it during normal generation; open it only when the user explicitly |
| 137 | asks to review the run. |
| 138 | |
| 139 | Format options must be named with concrete dimensions. Default: `ppt169` = `1280x720`, `viewBox="0 0 1280 720"`. Other examples: `ppt43` = `1024x768`, `story` = `1080x1920`, `banner` = `1920x1080`. For the full format list, see `references/canvas-formats.md`. |
| 140 | |
| 141 | Import source content (choose based on the situation): |
| 142 | |
| 143 | | Situation | Action | |
| 144 | |-----------|--------| |
| 145 | | Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...>` | |
| 146 | | User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly | |
| 147 | |
| 148 | For PPTX sources, `import-sources` automatically runs the standard intake enrichment: |
| 149 | |
| 150 | ```bash |
| 151 | python3 ${SKILL_DIR}/scripts/pptx_intake.py <project_path>/sources/<source.pptx> -o <project_path>/analysis |
| 152 | ``` |
| 153 | |
| 154 | For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, observed usage) and `<stem>.slide_library.json` (text slots, geometry, native tables, native chart caches, SmartArt nodes/connections), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; the beautify profile and Fill Native PPTX route decide separately which fields become locked constraints. |
| 155 | |
| 156 | Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify profile and Fill Native PPTX route remain single-deck (1:1 to one chosen source deck) and read that deck's `<stem>.*` artifacts. |
| 157 | |
| 158 | **Source ownership boundary**: Use the automatic import mode shown above. Only inputs already under the repository's `projects/` tree move into the target project's `sources/`; every other local path is copied and remains untouched, even if `--move` is supplied. Use `--copy` when a projects-local input must also remain in place. If Step 1 wrote Markdown beside the original sources, pass that source path/directory once. If Step 1 used `-o` to write Markdown elsewhere, pass both the original source path(s)/directory and the Markdown output path(s)/directory. Intermediate artifacts (e.g., `_files/`) are handled automatically. |
| 159 | |
| 160 | Direct supported bitmap inputs follow both boundaries: the original is archived under `sources/`, and a collision-safe basename is copied into `images/` for analysis and §VIII planning. SVG/EMF/WMF remain source assets unless they arrive through a converter companion manifest that supplies their display metadata. This does not classify an asset's role; Strategist still decides whether it is used. |
| 161 | |
| 162 | **✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.** |
| 163 | |
| 164 | --- |
| 165 | |
| 166 | ### Step 3: Template Candidate Preparation |
| 167 | |
| 168 | **Scope**: Every Default Generate run. This is internal preparation only: do not |
| 169 | open a page, ask a question, wait for a receipt, select a workspace, read a |
| 170 | template spec/prototype, or install anything. Quick resolves exact supplied |
| 171 | roots or free design inside its profile and skips this Step. |
| 172 | |
| 173 | Prepare the candidate boundary that Stage 1 will confirm. Registered candidates |
| 174 | come from exactly these discovery sources: |
| 175 | |
| 176 | - `templates/brands/brands_index.json` |
| 177 | - `templates/styles/styles_index.json` |
| 178 | - `templates/layouts/layouts_index.json` |
| 179 | - `templates/decks/decks_index.json` |
| 180 | |
| 181 | Derive each library root as `templates/<kind_dir>/<id>/` from its index entry. |
| 182 | Never scan kind directories, infer unregistered entries, or resolve a bare name, |
| 183 | brand mention, or style phrase to a path. Preserve every exact root supplied for |
| 184 | this run. A registered-root equality match remains `library`; every other exact |
| 185 | root remains `explicit`. Candidate provenance never changes later validation, |
| 186 | fusion, or precedence. |
| 187 | |
| 188 | Resolve the confirmation surface under |
| 189 | [`confirm_ui.md`](../scripts/docs/confirm_ui.md). In the UI branch, run |
| 190 | `--reset-template-selection`, then write |
| 191 | `<project_path>/confirm_ui/template_options.json` with schema version `1`, |
| 192 | `phase: "template"`, the UI language, and all supplied exact roots as absolute |
| 193 | `explicit_workspace_roots`; use an empty array when none were supplied. Also |
| 194 | write required `default_mode`: `templates` when the user explicitly asks to use |
| 195 | or browse templates or supplies any exact root, otherwise `free_design`. The |
| 196 | server reads the four indexes itself. Do not launch it yet. In chat/delegated |
| 197 | confirmation, retain the same candidate boundary in context and create no UI |
| 198 | artifact. |
| 199 | |
| 200 | Stage 1 initializes from `default_mode`, but the user can switch modes. Template |
| 201 | mode alone expands the candidates and must eventually select at least one |
| 202 | workspace. Exactly one supplied root may be preselected as an editable default; |
| 203 | multiple supplied roots remain unselected candidates. `free_design` selects none. |
| 204 | |
| 205 | **Raw PPTX boundary**: A raw PPTX remains valid source material, but it is not a |
| 206 | template workspace candidate. Raw PPTX plus new content uses |
| 207 | [`template-fill-pptx`](./template-fill-pptx.md). To create a reusable workspace, |
| 208 | run [`create-template`](./create-template.md), then return with the generated |
| 209 | root. Never add Master/Layout/placeholder structure directly to an existing |
| 210 | PPTX or SVG project. |
| 211 | |
| 212 | **✅ Checkpoint**: Candidate input is ready for the combined Stage-1 |
| 213 | confirmation. No template has been selected, read, validated, fused, or |
| 214 | installed. Proceed to Step 4 without a user-visible stop. |
| 215 | |
| 216 | --- |
| 217 | |
| 218 | ### Step 4: Strategist Phase (MANDATORY in the default pipeline) |
| 219 | |
| 220 | 🚧 **GATE**: Source preparation and Step-3 candidate preparation are |
| 221 | complete. No template content has entered planning context and no template has |
| 222 | been installed. Stage 1 has not started before this point. |
| 223 | |
| 224 | **Hard rule — Stage 1 is template-independent**: Author every Stage-1 |
| 225 | communication recommendation from the user's current request, source facts, |
| 226 | conversation constraints, and project-initialization state only. Candidate |
| 227 | paths, index summaries, template specs/prototypes/assets, and template canvas |
| 228 | are not recommendation evidence. Author the communication proposal before any |
| 229 | chat-branch catalog listing. The project initialization canvas remains the |
| 230 | Stage-1 starting value unless the current user/source context changes it. |
| 231 | Template inspection and current-project fit begin only after Stage 1 confirms |
| 232 | both the communication contract and template/free-design choice and any selected |
| 233 | workspace has been installed. |
| 234 | |
| 235 | At Step-4 entry, load the always-required planning context directly in one |
| 236 | batch: the role core, every canonical content-type source file defined below, |
| 237 | and the compact structured analysis facts already present. These inputs are |
| 238 | known required reads; do not route or rediscover them one file at a time. For a |
| 239 | multi-deck `source_profile.json`, read its compact `decks[]` digests in that |
| 240 | batch and open a deck's larger identity/slide-library files only when the |
| 241 | specific need below arises. |
| 242 | |
| 243 | ``` |
| 244 | Read references/strategist.md |
| 245 | ``` |
| 246 | |
| 247 | Then load only the extra role modules triggered by the current plan: |
| 248 | |
| 249 | | Deterministic trigger | Additional Strategist reference | |
| 250 | |---|---| |
| 251 | | Stage 1 is confirmed and its template choice installed a selected Brand/Style/Layout/Deck workspace into this project | `references/strategist-template.md` before Stage 2 | |
| 252 | | The core's proposed Stage 2 `image_usage` contains a source other than `none`, the user supplied an explicit non-`none` image constraint, or formula-worthy content activates formula planning | `references/strategist-image.md` + `references/image-layout-spec.md` + `references/image-layout-patterns.md` before authoring image renderings, production detail, formula resources, or §VIII | |
| 253 | |
| 254 | Core chooses Stage-2 sources. Load it before Stage 2 for non-`none`, or after confirmation if `none` changes; do not backfill candidates. Retain for confirmed non-`none` or formulas; otherwise write no image rows. Only an installed project-local template state loads the template module, and only after Stage 1 is confirmed; a bare template/style name does not. |
| 255 | |
| 256 | > ⚠️ **Mandatory artifact gates**: after final confirmation, author complete `design_spec.md` from `${SKILL_DIR}/templates/design_spec_reference.md`. After Gate 1 and any refinement approval, author `spec_lock.md` from `${SKILL_DIR}/templates/spec_lock_reference.md` plus approved Design Spec/context. Author each new artifact once without placeholders or `scaffold-*` (manual-only). Schema validity does not prove semantic fidelity. |
| 257 | |
| 258 | **Artifact ownership**: fact-channel and source/derived artifact boundaries are defined in [`references/artifact-ownership.md`](../references/artifact-ownership.md). This Step uses those ownership rules; it does not redefine them. |
| 259 | |
| 260 | **`<project_path>/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `<stem>.identity.json` / `<stem>.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Strategist confirmation stage, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table / SmartArt entries per source deck), then open a specific deck's `<stem>.identity.json` / `<stem>.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.) |
| 261 | |
| 262 | **Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the content-type files in `sources/`** — primarily `<stem>.md`, but also any user-supplied content the import archived there: `.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml` (a `metrics.json` or `data.csv` may carry core content — judge by what the file holds). Text, tables, chart data values, and SmartArt node wording come from these (`ppt_to_md` transcribes native charts as Markdown tables and SmartArt nodes as hierarchical bullets). **Do NOT read pipeline sidecars in `sources/` as content**: `*.conversion_profile.json` (conversion audit) and `*_files/image_manifest.json` (asset index) are process metadata — open them only to audit a conversion or resolve assets, never as slide content. Converted-source originals archived in `sources/` (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) are read via their converted `<stem>.md`, not scanned directly in the main pipeline. The `analysis/` chart / table / diagram entries are a **structural digest** for outline decisions (which slides carried charts, tables, or SmartArt; chart types / series names; SmartArt layout and hierarchy) — not a second copy of the content values; do NOT also pull chart values or SmartArt wording from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract while preserving SmartArt unchanged; beautify uses it for native chart / table data and SmartArt relationships while keeping all wording from the Markdown. |
| 263 | |
| 264 | **Confirmation orchestration**: field meaning and recommendation logic belong to the active Strategist modules; [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the JSON schema, server lifecycle, staged-result contract, port behavior, and equivalent chat fallback. |
| 265 | |
| 266 | ⛔ **BLOCKING**: The two-stage Strategist confirmation is the always-on user |
| 267 | gate unless explicitly delegated. Stage 1 confirms the communication contract |
| 268 | and, on the same screen or in the same chat turn, exactly one template mode: |
| 269 | `free_design` or `templates`. Only `templates` expands the four registered-kind |
| 270 | selectors plus supplied exact-root candidates, and it requires at least one |
| 271 | selection. Final Stage 2 confirms the complete deck solution plus production |
| 272 | mechanics only after the Stage-1 choice is installed or its free-design handoff |
| 273 | is complete. An enabled `refine_spec` adds the one conditional chat gate after |
| 274 | Design Spec Gate 1. Author each stage once; submitted values—including blanks or |
| 275 | unusual overrides—are authoritative. |
| 276 | |
| 277 | **Confirmation ownership and surface**: Only the user confirms. Before any |
| 278 | confirmation server command, apply |
| 279 | `confirm_ui.md`'s surface |
| 280 | decision to this run's most recent explicit surface instruction and retain that |
| 281 | branch as the owner specifies. A natural-language request or agreement to |
| 282 | personally confirm in chat, or to avoid the page, selects the chat branch without |
| 283 | a magic keyword; skip UI launch/wait commands and UI-authored result state. |
| 284 | Explicit delegation is a separate higher-priority branch. With no surface |
| 285 | instruction, use the default UI branch. A chat-question tool alone does not |
| 286 | replace that default. The agent may author recommendations, operate the |
| 287 | server, read state, and apply a selected template, but MUST NOT confirm on the |
| 288 | user's behalf, automate submission, synthesize a payload, or write/replace user |
| 289 | result state. Delegation applies only to this run: make the Stage-1 communication |
| 290 | and template decision, install any selection, then derive and show the complete |
| 291 | Stage-2 summary without fabricating UI results. Silence confirms nothing. |
| 292 | |
| 293 | **UI branch files and completion evidence:** |
| 294 | |
| 295 | | Input file (only the active unconfirmed Strategist stage may be overwritten) | Agent writes | Completion evidence | |
| 296 | |---|---|---| |
| 297 | | `confirm_ui/template_options.json` | Candidate schema/language plus supplied exact roots; library entries remain server-owned index data | Stage-1 submission writes user-owned `template_selection.json` with `phase: template`, `status: confirmed` | |
| 298 | | `confirm_ui/recommendations.stage1.json` | Communication contract, `content_divergence`, and canvas only; no template-derived recommendation | The same submission writes `result.json` with `status: stage1-confirmed` | |
| 299 | | `confirm_ui/template_handoff.json` | Only through `--complete-template-selection`, after the Stage-1 selection and free-design closure or successful installation | `status: ready`, bound to the current selection hash; prerequisite for Stage 2 | |
| 300 | | `confirm_ui/recommendations.stage2.json` | `stage: stage2`; complete deck solution plus conditional AI path, formula policy, generation mode, refine-spec, proactive speaker notes, custom animations, and narration audio | `stage: final`, `status: confirmed` | |
| 301 | |
| 302 | If the user rejects the current recommendation before confirming it, regenerate by overwriting that same stage file and have the page refresh; do not create revision-suffixed files. This never authorizes one stage file to carry another stage's payload. |
| 303 | |
| 304 | **UI branch only** — Step 3 wrote `template_options.json` but did not launch or |
| 305 | wait. Create `confirm_ui/recommendations.stage1.json` without reading template |
| 306 | candidate content, then launch the combined Stage-1 page and post |
| 307 | `confirm_ui.md`'s required communication + template-choice summary/fallback: |
| 308 | |
| 309 | ```bash |
| 310 | python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon |
| 311 | python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1 |
| 312 | ``` |
| 313 | |
| 314 | The single Stage-1 submission writes both `result.json` and |
| 315 | `template_selection.json`; neither replaces the other. Read each exactly once. |
| 316 | Require a confirmed communication result and either `free_design` with no roots |
| 317 | or `templates` with at least one server-resolved root. |
| 318 | |
| 319 | 1. For `templates`, load and run |
| 320 | [`apply-template-workspace.md`](./stages/apply-template-workspace.md) against |
| 321 | every confirmed exact root. It validates/fuses them and installs one |
| 322 | project-local state under `templates/` plus any real `images/` and `icons/`. |
| 323 | For `free_design`, skip installation. Then bind the completed state: |
| 324 | |
| 325 | ```bash |
| 326 | python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --complete-template-selection |
| 327 | ``` |
| 328 | |
| 329 | This agent-only command writes `template_handoff.json`; do not hand-author |
| 330 | it. The server requires this handoff before Stage 2. |
| 331 | |
| 332 | 2. Only now inspect installed template state and apply |
| 333 | `strategist-template.md` when active. Derive the complete deck solution and |
| 334 | production defaults, loading the triggered image-planning bundle above. |
| 335 | Create `confirm_ui/recommendations.stage2.json` without changing Stage 1; |
| 336 | declare `stage: "stage2"`, then wait for the final confirmation: |
| 337 | |
| 338 | ```bash |
| 339 | python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only |
| 340 | ``` |
| 341 | |
| 342 | 3. After the final wait returns, read the complete `result.json` exactly once |
| 343 | and retain that object through Design Spec authoring and its fidelity audit. |
| 344 | Proceed only when it carries `stage: final` and `status: confirmed`. Do not |
| 345 | reopen the file during normal lock authoring or downstream execution. On a |
| 346 | non-zero wait, this same single read determines whether the persisted result |
| 347 | succeeded before using the documented chat fallback. A stage-skip result |
| 348 | returns to the missing stage; it is not a browser failure. |
| 349 | |
| 350 | 4. After final confirmation or chat fallback, always release the server: |
| 351 | |
| 352 | ```bash |
| 353 | python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown |
| 354 | ``` |
| 355 | |
| 356 | If the user selects chat any time after the UI server launches, immediately |
| 357 | apply `confirm_ui.md`'s in-run switch procedure. Continue the unresolved current |
| 358 | stage and all remaining stages in chat; do not enter UI interruption recovery |
| 359 | or relaunch the server. |
| 360 | |
| 361 | **Chat branch** — present the template mode and Stage-1 communication contract |
| 362 | together and wait for one explicit response. Show registered candidates only |
| 363 | when the user chooses `templates`; supplied exact roots remain available in that |
| 364 | expanded choice. Initialize free design for an ordinary request and template |
| 365 | mode for explicit template intent or any exact root; with exactly one root it |
| 366 | may also be the preselected candidate, while multiple roots remain unselected. |
| 367 | Do not create UI receipts |
| 368 | or call `--complete-template-selection`. After confirmation, install/fuse any |
| 369 | selected roots (or close free design) and retain that completed state in context |
| 370 | as the Stage-2 gate. Then run final Stage 2 in chat and retain one visible |
| 371 | cumulative summary as the equivalent final state. Under explicit delegation, |
| 372 | make the same Stage-1 decision, install it, derive Stage 2, and present one |
| 373 | complete AI-authored summary. |
| 374 | |
| 375 | ⛔ **GATE — final state → Design Spec → conditional review → lock.** Consume every present final value once into the complete, audited `design_spec.md` under [`strategist.md`](../references/strategist.md) §6.2. Preserve each owning semantic type and all production, typography, image-source, and `image_notes` obligations; acceptance never turns a Reference/Permission into a Literal. Do not reopen `result.json`. |
| 376 | |
| 377 | With `refine_spec: true`, run [`refine-spec`](stages/refine-spec.md) after Gate 1: review that same file in chat, accept arbitrary revisions, touch no lock, and stop until explicit approval. Revisions supersede only affected decisions. Otherwise skip the stop. |
| 378 | |
| 379 | After the review closes, author `spec_lock.md` from the approved Design Spec and context. Preserve identity/refinements, every recurring typography role, reusable routing anchors, and each placed image's source/layout suggestion/crop policy; omit page-local garnish and never write a separate image palette. Apply `strategist-template.md` §3 when active. Unhonorable requirements follow [`failure-recovery.md`](governance/failure-recovery.md). |
| 380 | |
| 381 | **Conditional — split-mode note** (not a separate confirmation): after listing the Strategist confirmation stage details, append one short line (rendered in the user's language, prefixed with 💡) only when the confirmed mode is `split` or upstream-load signals make a fresh execution context materially useful. Judge those signals from recommended page count, source-material bulk, and research material actually retained in this chat. Raw fetches performed by a successful isolated `topic-research` worker do not count; substantial local-fallback fetches or unusually large imported research artifacts do. |
| 382 | |
| 383 | | Signal read | Line content | |
| 384 | |---|---| |
| 385 | | Heavy (long page count / bulky sources / heavy retained research context) | State the applicable heavy signals; recommend switching to [split mode](stages/resume-execute.md) after Step 5 — stop this chat, open a fresh window and input `继续生成 projects/<project_name>` to enter the execution session (SVG generation + export); no response or "continue" = default continuous mode. | |
| 386 | | Explicit `split` selection | Confirm that planning will stop after Step 5 and give the `继续生成 projects/<project_name>` handoff command. | |
| 387 | |
| 388 | For the normal/default `continuous` path, print no split-mode reminder and proceed automatically. Confirm UI still exposes the generation-mode toggle and records it in `result.json`; a chat fallback captures the same choice in its confirmation summary without adding a separate reminder. |
| 389 | |
| 390 | **Mandatory — spec-refinement note** (not another Confirm UI stage): after confirmation details and any split-mode line, append one localized 💡 line offering review of the complete Design Spec before the lock; any part may be revised in chat until explicit approval. Default OFF; only explicit chat opt-in or `refine_spec: true` runs [`refine-spec`](stages/refine-spec.md) after Gate 1. Confirm UI records the toggle; chat fallback prints the same line. |
| 391 | |
| 392 | **Formula policy**: Final Stage 2 confirms `mixed`, `render-all`, or `text-only`. When rendering is required, load the image-planning bundle even if `image_usage` is `none`, then follow [`strategist-image.md`](../references/strategist-image.md)'s formula-resource contract. `text-only` creates no formula image rows. |
| 393 | |
| 394 | **Proactive production decisions**: Final Stage 2 records |
| 395 | `proactive_speaker_notes`, `proactive_custom_animations`, and |
| 396 | `proactive_narration_audio`. They control only what the agent initiates when the |
| 397 | user has not already given an explicit instruction. Resolve each effective |
| 398 | outcome as latest explicit user instruction → final Stage-2 value → workflow |
| 399 | default `true` / `false` / `false`. Final Stage-2 Narration Audio enabled raises a |
| 400 | non-explicitly-disabled Speaker Notes outcome to enabled and names that |
| 401 | dependency in its provenance without rewriting the raw proactive preference. |
| 402 | Persist the resolved effective outcomes plus provenance as the `Speaker Notes`, |
| 403 | `Custom Animations`, and `Narration Audio` rows in `design_spec.md §I`; keep the |
| 404 | raw proactive fields only as confirmation evidence and do not project either |
| 405 | form into `spec_lock.md`. |
| 406 | |
| 407 | **Post-confirmation override**: A later explicit request updates only affected |
| 408 | §I outcomes/provenance and resumes their owning step; do not reopen Confirm UI. |
| 409 | If it disables Speaker Notes while Narration Audio remains enabled, write |
| 410 | neither row and ask one question: disable audio too, or retain its required |
| 411 | notes. Wait, then update both. Before `generate-audio`, create and split notes |
| 412 | when complete per-slide files are absent. |
| 413 | |
| 414 | If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**. It writes `analysis/image_analysis.csv` — the authoritative regenerated image-fact view in the `analysis/` folder, which MUST be read before authoring §VIII: |
| 415 | ```bash |
| 416 | python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images |
| 417 | ``` |
| 418 | |
| 419 | > 🔁 **Image facts are regenerated on change, never maintained as a second store.** `images/` is the live working folder and single source of truth; `analysis/image_analysis.csv` is its regenerated view. Run `analyze_images.py` before the first inventory read, then reuse that CSV while `images/` is unchanged. Re-run after import/acquisition or any user addition, removal, or replacement; an empty folder produces a fresh header-only CSV rather than leaving stale facts. |
| 420 | |
| 421 | > ⚠️ **Image understanding**: Do not bulk-open images. Strategist starts from context, filenames, records, and `image_analysis.csv`; inspect only a specifically ambiguous asset under [`strategist-image.md`](../references/strategist-image.md), then record the result in §VIII. Under [`executor-image.md`](../references/executor-image.md), Executor may inspect one selected `Existing` / `Sourced` asset only to resolve crop, focal placement, or text contrast—never to reselect, replace, or infer provenance. |
| 422 | |
| 423 | **Output**: |
| 424 | - `<project_path>/design_spec.md` — complete human-readable design narrative and durable confirmed production state |
| 425 | - `<project_path>/spec_lock.md` — machine-readable stable execution anchors/routing, authored after conditional review approval |
| 426 | |
| 427 | For a new project, use the reference-first whole-document sequence: |
| 428 | |
| 429 | 1. Read `${SKILL_DIR}/templates/design_spec_reference.md`; create complete I–X `<project_path>/design_spec.md` once from retained confirmation, analysis, and context, without placeholders/examples. |
| 430 | 2. Audit it field by field against retained confirmation; Gate 1 must pass. |
| 431 | 3. If enabled, run [`refine-spec`](stages/refine-spec.md) on that file until explicit approval; touch no lock. |
| 432 | 4. Read `${SKILL_DIR}/templates/spec_lock_reference.md`; create or resynchronize the lock once from approved Design Spec and context. Never reopen `result.json` or make a new design choice. |
| 433 | 5. Compare lock anchors/routing to the Design Spec; run `python3 ${SKILL_DIR}/scripts/project_manager.py validate <project_path>`. |
| 434 | |
| 435 | Final state → initial Design Spec mismatch, approved Design Spec/context → lock mismatch, or an unapplied revision blocks despite schema validity. `validate` does not prove fidelity. Repair from retained confirmation before refinement; during it, preserve unaffected values and apply explicit revisions. After approval, derive the lock from that Design Spec/context. Resume/refine edits existing files, never scaffolds. Fresh recovery alone may reread persisted final evidence once. |
| 436 | |
| 437 | **✅ Internal checkpoint — Phase deliverables complete**: facts read; confirmation consumed once; final Stage-2 production fields resolved (formula policy, generation mode, refine-spec, proactive choices, and conditional AI path); Design Spec passed Gate 1; enabled refinement approved; lock derived from it; split handling resolved; communication and every §IX `Audience move` validated. Do not print this checklist; auto-proceed. |
| 438 | |
| 439 | --- |
| 440 | |
| 441 | ### Step 5: Image Acquisition Phase (Conditional) |
| 442 | |
| 443 | 🚧 **GATE**: Step 4 complete; `<project_path>/design_spec.md` and `<project_path>/spec_lock.md` both exist. If either required artifact is missing, stop before any acquisition or generation and follow [`failure-recovery.md`](governance/failure-recovery.md) §3. Formula rows already have `Acquire Via: formula` and status `Rendered` or `Needs-Manual`. |
| 444 | |
| 445 | > **Trigger**: At least one row in the resource list has `Acquire Via: ai`, `web`, and/or `slice`. A prepared-user-only plan contains `user / Existing` rows and skips this entire step; `formula` and `placeholder` rows also do not trigger acquisition. A permitted but unused image source creates no row and does not trigger acquisition. If §VIII omits a source, asset, or page role that `image_notes` explicitly requires, the Design Spec is incomplete; return to Step 4 Gate 1, repair it from the retained final state, and re-author the affected lock anchors from context. Do not reopen `result.json` during this check. |
| 446 | |
| 447 | **Failure recovery**: stop/continue behavior for AI/web/slice/image-readiness failures is defined in [`workflows/governance/failure-recovery.md`](governance/failure-recovery.md). This Step keeps the acquisition procedure. |
| 448 | |
| 449 | **Always load the common framework**: |
| 450 | |
| 451 | ``` |
| 452 | Read references/image-base.md |
| 453 | ``` |
| 454 | |
| 455 | Then **lazy-load the path-specific reference** for each row that actually needs it: |
| 456 | |
| 457 | | Acquire Via | Load reference (only if any such row exists) | Run | |
| 458 | |---|---|---| |
| 459 | | `ai` | `references/image-generator.md` | write `<project_path>/images/image_prompts.json`, then follow `image-generator.md §7 Path Selection` (`image_gen.py --manifest` is **Path A only**) | |
| 460 | | `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` (≥2 web rows → `--batch images/image_queries.json`) | |
| 461 | | `slice` | `references/image-generator.md` §4.3 | derived — **after** the parent `ai` sheet row is `Generated`, run `python3 ${SKILL_DIR}/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names ... --trim --alpha` (see workflow step 2.5) | |
| 462 | | `user` / `formula` / `placeholder` | (skip) | (skip) | |
| 463 | |
| 464 | A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `web` rows never loads `image-generator.md`. A mixed deck loads both, processes each row through its own path, and writes both `image_prompts.json` and `image_sources.json`. |
| 465 | |
| 466 | > ⚠️ **In-pipeline ai rows MUST use the manifest contract** — even when only 1 ai row exists. Always write `images/image_prompts.json` first and render `image_prompts.md` with `image_gen.py --render-md`. Then execute the confirmed path from `image-generator.md §7`: `image_gen.py --manifest` is **Path A only**; `host-native` is **Path B** and MUST skip `--manifest`; `manual` writes the prompts and stops for external generation. The positional form (`image_gen.py "prompt" ...`) is reserved for **out-of-pipeline one-off testing / single-image fixups** — it skips manifest + sidecar, leaving no audit trail. |
| 467 | |
| 468 | > ⚠️ **web path — batch multiple rows**: when ≥2 rows are `Acquire Via: web`, write all queries into `images/image_queries.json` and run `image_search.py --batch` once (concurrent acquisition, status written back), instead of one CLI call per row. A single web row may use the positional single-query form. See [image-searcher.md](../references/image-searcher.md) §5. |
| 469 | |
| 470 | > **Default — short provider query (may override for a complete entity name or necessary disambiguation)**: keep §VIII `Reference` as the locked subject/focal/crop intent and author a separate concrete `image_queries.json.query`. Search/review never rewrites the Design Spec or lock to fit a candidate. |
| 471 | |
| 472 | > **Default — one sheet for compatible AI spots (may override for different cell shape, detail, quality, or semantics)**: prefer one grid sheet for a same-family set; independent `ai` rows remain valid. When selected, choose a grid matching the planned cells, keep the sheet unplaced, and place/project each `slice` row. Contract: [image-generator.md](../references/image-generator.md) §4.3. |
| 473 | |
| 474 | > ⚠️ **Honor the Design Spec's confirmed image source before running any generation command**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — the production value recorded in `design_spec.md §I` wins. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. Never reopen `result.json` here, and never run `image_gen.py --manifest` when the recorded value is `host-native` or `manual`. Full selection rule: [image-generator.md](../references/image-generator.md) §7 Path Selection. |
| 475 | |
| 476 | Workflow: |
| 477 | |
| 478 | 1. Extract all resource rows from the design spec and group them by `Acquire Via`; rows with `Status: Pending` or `Status: Failed` and `Acquire Via ∈ {ai, web, slice}` must all reach a terminal state before Executor starts |
| 479 | 2. Generate prompts (ai rows) and/or run search (web rows) per [image-base.md](../references/image-base.md) §3 dispatch table |
| 480 | 2.5. **Slice any spot-illustration sheets (only if `slice` rows exist).** For each generated `ai` **sheet** row, run `slice_images.py` (grid + the element `--names` matching the `slice` rows, `--trim --alpha`) so every element file lands in `images/`; mark each `slice` row `Generated`. A sheet still in `Needs-Manual` cannot be sliced — leave its `slice` rows `Needs-Manual` and surface them at the Step 7 readiness gate. Contract: [image-generator.md](../references/image-generator.md) §4.3. |
| 481 | 3. Verify every row reaches a terminal status: `Generated` (ai success / sliced element), `Sourced` (web success), or `Needs-Manual`. `Failed` is not a terminal status: it means the current run did not generate that item, but the item remains retryable. On `auto`, follow the owning fallback chain. On an explicitly confirmed `api` or `host-native` path, retry only that path; if it still fails, mark the row `Needs-Manual` without switching to another automated provider. |
| 482 | 4. Re-derive image facts now that web / AI / sliced files are in the folder — `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` — so `analysis/image_analysis.csv` reflects every acquired image **including the sliced elements** (real measured sizes) before the Executor lays them out. Image facts are regenerated on use, never a stale store (see Step 4's image-facts note). |
| 483 | |
| 484 | **✅ Internal checkpoint — acquisition complete**: verify conditional AI/web sidecars, all required slice outputs, terminal status for every resource row, and a refreshed `image_analysis.csv`. Do not print this checklist. On success, auto-proceed under the compact status rule above. |
| 485 | |
| 486 | **Default — auto-proceed to Step 6.** Only when `design_spec.md §I` records `generation_mode: split`, output the planning-session handoff below and stop this conversation: |
| 487 | |
| 488 | ```markdown |
| 489 | ## ✅ Planning Session Complete |
| 490 | - [x] Spec: `design_spec.md`, `spec_lock.md` |
| 491 | - [x] Resources: `sources/`, `images/`, `templates/` |
| 492 | - [ ] **Next**: open a fresh chat window and input `继续生成 projects/<project_name>` to enter the execution session via the [`resume-execute`](stages/resume-execute.md) stage. |
| 493 | ``` |
| 494 | |
| 495 | > On acquisition failure, follow [image-base.md](../references/image-base.md) §6 without halting. Web rows continue through materially different query/provider/license/URL strategies; after exhaustion, mark `Needs-Manual`, report, and continue. |
| 496 | |
| 497 | --- |
| 498 | |
| 499 | ### Step 6: Executor Phase |
| 500 | |
| 501 | 🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready. |
| 502 | |
| 503 | **Exact page roster**: render `design_spec.md §IX` one-for-one, in order. Any add/drop/merge/split/reorder requires Spec repair/refinement first. |
| 504 | |
| 505 | **Page content**: §IX is preferred wording and semantic authority. Use it when it works; adapt it when presentation benefits while preserving intent, facts, and explicit literal requirements. Read sources only to verify requested evidence; return incomplete blocks to Step 4 instead of enriching them during execution. |
| 506 | |
| 507 | **Planning context**: follow [`executor-base.md`](../references/executor-base.md) §2.1. Reuse the complete Design Spec and lock in an unchanged, uncompacted context. Fresh/resumed/restarted, compacted/summary-only, or externally/unknown changed execution reads both once and reloads triggered inputs. For a local question, consult the retained lock first, then only the owning Design Spec fragment; do not poll files merely to prove validity. |
| 508 | |
| 509 | **Artifact ownership**: `svg_output/` is the author source, `svg_final/` is derived, and image facts come from the regenerated `analysis/image_analysis.csv`; see [`references/artifact-ownership.md`](../references/artifact-ownership.md). |
| 510 | |
| 511 | Read the execution references for this deck's locked `mode` + `visual_style` |
| 512 | (from `spec_lock.md`). Load this fixed required block directly as one batch; |
| 513 | do not route among its files one at a time: |
| 514 | ``` |
| 515 | Read references/executor-base.md # REQUIRED: flat/shared execution core |
| 516 | Read references/shared-standards-core.md # REQUIRED: SVG compatibility + shared aesthetic/leading baseline |
| 517 | Read references/svg-effects.md # REQUIRED: Visual Job Router + effects/construction vocabulary |
| 518 | Read references/native-shape-authoring.md # REQUIRED: native-shape selection and Boolean construction |
| 519 | Read references/semantic-svg.md # REQUIRED: semantic metadata boundary |
| 520 | Read references/modes/<resolved-id>.md # one preset id, or each `mode_references` id |
| 521 | Read references/visual-styles/<resolved-id>.md # one preset id, or each `visual_style_references` id |
| 522 | ``` |
| 523 | |
| 524 | Keep the core's shared visual-quality defaults and `svg-effects.md` §6.1 Visual Job Router active during page authoring; they are not passive compatibility reading. Explicit user/template requirements and the locked style override compatible aesthetic defaults, never technical Required / Forbidden boundaries. |
| 525 | |
| 526 | > Read only the always-on references above plus the conditionally triggered modules below. A preset reads its one locked file. For `mode: custom` or `visual_style: custom`, read every exact file named by the optional `mode_references` / `visual_style_references`, then synthesize those sources under the corresponding behavior. If the reference field is absent, the direction is genuinely novel: read no preset file and follow the behavior directly. Never infer adjacent references or glob `modes/` / `visual-styles/`. |
| 527 | |
| 528 | | Deterministic trigger | Additional references | |
| 529 | |---|---| |
| 530 | | `pptx_structure.mode: structured` | `executor-structured.md` + `pptx-structure-interface.md` | |
| 531 | | Any data chart/table, including mini or inset charts and sparklines | `executor-chart.md` | |
| 532 | | Preset pattern or supported native chart/table | `native-data-interface.md` before drawing | |
| 533 | | `spec_lock.md images` / §VIII has an image/formula row, or the template has bundled images | `executor-image.md` + `image-layout-spec.md` + `image-layout-patterns.md` + `svg-image-embedding.md` | |
| 534 | | At least one placed image has `Status: Sourced` | `executor-web-image.md` after the image branch | |
| 535 | | All SVG pages and SVG quality gates are complete, and the effective Speaker Notes outcome in `design_spec.md §I` is enabled | `executor-notes.md` before generating speaker notes | |
| 536 | |
| 537 | No branch is loaded by analogy. Evaluate these triggers from `spec_lock.md`, §VII/§VIII, the selected style, and the current page plan. |
| 538 | |
| 539 | **Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2. |
| 540 | |
| 541 | **Live Preview Auto-Startup (Mandatory)**: before the first SVG, automatically start the browser editor in live mode and keep it running continuously through Executor + Step 7 export: |
| 542 | ```bash |
| 543 | python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon |
| 544 | ``` |
| 545 | - Start when Executor begins; `svg_output/` may be empty. Default: first free port from `5050`; `--port N`: strict bind. Read the actual URL from output or `<project_path>/live_preview/lock.json`. |
| 546 | - Before the first SVG, report that URL or the launch failure; never claim an unavailable preview. |
| 547 | - Run it as a long-running side process/session; do not wait for it to exit before generating SVG pages. Do not wait for user confirmation after startup. |
| 548 | - **Service must keep running** until one of: (a) the user clicks **Exit preview** in the browser, or (b) the user explicitly asks in chat to stop it. Generation continues even if the user closes the editor. |
| 549 | - **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/stages/live-preview.md`](stages/live-preview.md). |
| 550 | - The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/stages/live-preview.md`](stages/live-preview.md) Notes. |
| 551 | |
| 552 | **Conditional reference reads**: Follow `executor-structured.md` for template Design Spec/prototypes and `executor-chart.md` for chart SVGs. Read each selected full reference once per valid context; reread only after a known change or context invalidation. Flat routes skip template reads. Summaries and sidecars never replace full SVGs. |
| 553 | |
| 554 | > Image facts: trust the latest `analysis/image_analysis.csv` from the Step 4 inventory read or the Step 5 post-acquisition refresh. If `images/` changed since, re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before layout; if the folder is empty, use no image inventory and ignore a stale CSV. |
| 555 | |
| 556 | **Page-context**: use the read-only projector only for the diagnostic/telemetry triggers in Executor §2.1, never as a routine pre-page load. |
| 557 | |
| 558 | > ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents. |
| 559 | > ⚠️ **Generation rhythm**: P01 → first-page gate → uninterrupted remaining pages → final gate. After context invalidation, reload under §2.1 before continuing; do not insert batches or mid-run checker calls. |
| 560 | |
| 561 | **Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/` |
| 562 | |
| 563 | Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Treat §IX `Native shape suggestion` as a candidate, not a command: inspect the actual page construction, then choose the highest-level faithful construction in this order — editable basic primitive, exact Office preset, Merge Shapes Boolean result, and only then a necessary freeform. Apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before materializing an adopted native treatment. Diagram relationships follow the same Shape-first order; do not infer a preset from contour similarity. |
| 564 | |
| 565 | **Motion-ready image composition**: Only when an explicit user motion |
| 566 | instruction, the effective Custom Animations outcome in `design_spec.md §I` is |
| 567 | enabled, or an existing `animations.json` activates custom motion, evaluate §IX `Motion suggestion` |
| 568 | rows. If the adopted motion depends on distinct in-slide image states or |
| 569 | cross-slide image continuity, author those visible states now under |
| 570 | [`executor-image.md`](../references/executor-image.md). Give each independently |
| 571 | revealable or continuing ordinary Slide-local unit a descriptive direct-root |
| 572 | `<g id>`; structured atoms/slots retain their declared boundaries and are |
| 573 | targetable only when that contract permits. Do not defer required visible |
| 574 | content or reshape structure for the later stage. This is SVG preparation, not |
| 575 | early animation authoring: effects, pairing, order, and timing remain in the |
| 576 | conditional custom stage after the final SVG quality gate and any enabled |
| 577 | speaker-note pass. A Motion suggestion alone does not activate preparation or |
| 578 | custom animation. A page-transition-only request requires no extra visible |
| 579 | layer; deterministic Morph still needs the continuing object as a direct-root |
| 580 | group on both pages. |
| 581 | |
| 582 | `template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive uses the current or new Layout key/name already declared by Strategist. If construction proves that fixed atoms or slot topology/bounds must change, stop and return upstream for Strategist to repair the owning plan and lock, validate and read back the affected fragments, then resume; Executor never mutates `spec_lock.md`. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata. |
| 583 | |
| 584 | `template_reuse_scope: style`, Style-only, free-design, and brand-only pages use `pptx_structure.mode: flat`. A Style-only workspace always derives `template_reuse_scope: style`; Style never supplies prototype mappings. When fused with Layout/Deck, Style changes only Direction / method and follows the selected non-Style structure plan. On a flat page, draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content. |
| 585 | |
| 586 | Do not duplicate specialized identity with `data-pptx-role`. Add it only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by `data-pptx-layer`, `data-pptx-placeholder`, or `data-pptx-replace-with`; such an element needs a stable unique `id`. Do not add generic content roles to ordinary titles, body text, cards, KPIs, diagrams, charts, icons, or images. Full contract: [`references/semantic-svg.md`](../references/semantic-svg.md). |
| 587 | |
| 588 | **First-page gate (Mandatory)** — after the **first** SVG page, before drawing page 2: |
| 589 | ```bash |
| 590 | python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page --json |
| 591 | ``` |
| 592 | Run the command unfiltered—do not pipe it through `tail`, `head`, `grep`, or another output truncator. Review the complete P01 issue set from that one run before editing. Select any advisory warnings worth addressing, fix all blocking errors and selected warnings in one consolidated edit pass, then perform one verification rerun. Do not rerun merely to reveal the next issue. If verification still fails, treat its complete output as the next batch and repeat the same review → consolidated edit → single verification cycle; never check between individual fixes. If the terminal output itself is truncated, read only the relevant issue arrays from `validation/svg_quality_first_page_report.json`; do not launch another checker run for discovery. After the gate passes, draw P02 through the final page without checker calls. |
| 593 | |
| 594 | **Mandatory — read P01 as a method sample, then emit the classification before editing**: the gate validates how the remaining pages will be authored, not only this page. |
| 595 | |
| 596 | | Signal | Reading | |
| 597 | |---|---| |
| 598 | | Two or more issues share a category and direction | Method-level bias — resolve it to the authoritative rule before P02; a correction fitted to the observed offset only patches this sample. For text extents that rule is `svg_to_pptx.drawingml.elements.estimate_single_line_text_frame_width(runs)`, with `skills/ppt-master/scripts` on `sys.path` and every run key present — `text`, `font_size`, `font_family`, `font_weight`, `letter_spacing` — since omissions under-measure | |
| 599 | | One isolated issue tied to this page's structure | Page-local — fix and continue | |
| 600 | | A recurring element appears for the first time (page furniture, caption format, section numbering, accent discipline) | It will be copied to every later page — confirm its semantics now | |
| 601 | |
| 602 | Emit one line before the consolidated edit: |
| 603 | |
| 604 | ``` |
| 605 | gate-signal: method=<rule resolved, or none> | page-local=<count> | not-exercised=<list> |
| 606 | ``` |
| 607 | |
| 608 | `not-exercised` names what P01 could not test — a cover typically omits multi-line text, columns, charts, image captions, and data objects. Carry every resolved rule forward as arithmetic; P02 through the final page run without further tool calls. |
| 609 | |
| 610 | **Quality Check Gate (Mandatory)** — only after every planned SVG exists, BEFORE annotation handling and speaker notes: |
| 611 | ```bash |
| 612 | python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json |
| 613 | ``` |
| 614 | - **MUST**: Before this gate, every chart/table whose Design Spec §IX page block says `Native-ready: yes` already has its own draw-time marker plus JSON metadata. Rows marked `no` and incidental microvisuals remain ordinary SVG. For legacy specs only, a matching §VII value may supply the decision when §IX has no field. |
| 615 | - Run the command unfiltered—do not pipe it through `tail`, `head`, `grep`, or another output truncator. One invocation already scans every page and reports the complete issue set. |
| 616 | - On failure, review all `blocking` errors and all advisory warnings from that run before editing. Choose which warnings merit work, fix every blocking error and the selected warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never run the checker between individual fixes or use repeated invocations to discover one next issue at a time. If terminal output is truncated, extract only `categories.blocking.issues` and, when needed, `categories.introduced.issues` from the report written by that same run. |
| 617 | - Every `warning` is advisory and non-blocking: do not return the page for mandatory modification, do not auto-normalize user-authored compatible syntax, and do not require an acknowledgement/disposition line. Recommendation warnings identify the generated-SVG default; fidelity/quality warnings may be reported when material, but the existing input may ship unchanged. If a condition must be corrected before release, the checker must classify it as an `error`, not a `warning`. |
| 618 | - The same rule applies to structured-template warnings (empty/framing-only Layout, bare Master, duplicate layout keys): they may guide an optional template cleanup, but warnings alone never fail the quality gate. Flat `style`, free-design, and brand-only routes still rely on their existing hard errors for invalid structure metadata or incomplete required locks. |
| 619 | - Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations). |
| 620 | - The JSON report is written to `validation/svg_quality_report.json`. `inherited` prototype diagnostics and `source-import` compatibility losses are informational provenance; only changed/new warnings remain `introduced`, and all release-blocking failures remain `blocking`. |
| 621 | - **Hard rule — token-safe report handling**: On a successful checker run, use the exit status and terminal summary as gate evidence. Do not open, `cat`, or otherwise load the complete JSON report into model context. Read it only for failure investigation, an explicit audit request, or a field absent from stdout; extract only the required field(s). |
| 622 | |
| 623 | **Logic Construction Phase (conditional)**: after the SVG quality gate passes, |
| 624 | when the effective Speaker Notes outcome in `design_spec.md §I` is enabled, load |
| 625 | [`executor-notes.md`](../references/executor-notes.md), ground each page's |
| 626 | narration in all information-bearing content in its final SVG, and generate |
| 627 | speaker notes → `<project_path>/notes/total.md`. When the outcome is `disabled`, |
| 628 | do not load the notes branch and do not require or create `notes/total.md`. |
| 629 | |
| 630 | **✅ Internal checkpoint — execution complete**: verify live preview timing, |
| 631 | the P01 method gate, uninterrupted remaining-page generation, consolidated |
| 632 | repair of any complete failure set, exact §IX roster coverage, one-frame prose |
| 633 | wrapping, a final checker result of 0 errors, and `notes/total.md` only when |
| 634 | speaker notes are enabled. Do not print this checklist. Run the applicable |
| 635 | conditional gates below, then proceed to Step 7 under the compact status rule |
| 636 | above. |
| 637 | |
| 638 | > **Chart pages?** If this deck contains data charts, run the [`verify-charts`](stages/verify-charts.md) quality-gate stage before Step 7 to calibrate coordinates. Skip if no chart pages. |
| 639 | |
| 640 | > **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the [`visual-review`](stages/visual-review.md) quality-gate stage before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only. |
| 641 | |
| 642 | > **Motion execution (conditional)?** Visible-layer preparation belongs to the |
| 643 | > main SVG pass above. An existing `<project_path>/animations.json` always runs |
| 644 | > [`customize-animations`](stages/customize-animations.md) to validate and |
| 645 | > resolve preserve/adjust/replace/suppress intent before export. Without a sidecar, run |
| 646 | > the custom stage only for an explicit per-slide/per-object motion request or |
| 647 | > when the effective Custom Animations outcome in `design_spec.md §I` is |
| 648 | > enabled; §IX `Motion suggestion` rows inform that active pass but never |
| 649 | > trigger it alone. A deck-wide request loads |
| 650 | > [`animations.md`](../references/animations.md) and resolves Step 7.3 flags |
| 651 | > without activating the custom stage. Otherwise keep the exporter defaults |
| 652 | > (`fade` page transition, per-element animation `none`) and load no motion |
| 653 | > reference. Strategist owns the communication purpose; Executor owns exact |
| 654 | > native effects, options, order, timing, and whether a non-literal suggestion |
| 655 | > should simplify to `none`. Never add motion for coverage or variation. |
| 656 | |
| 657 | --- |
| 658 | |
| 659 | ### Step 7: Post-processing & Export |
| 660 | |
| 661 | 🚧 **GATE**: Step 6 is complete; `svg_output/` contains every final page, all |
| 662 | required conditional quality gates passed, and the final SVG quality report has |
| 663 | 0 errors. When the effective Speaker Notes outcome in `design_spec.md §I` is |
| 664 | enabled, |
| 665 | `notes/total.md` also exists and covers every page; when it is disabled, notes |
| 666 | artifacts are not gate requirements. |
| 667 | |
| 668 | 🚧 **Image readiness GATE**: When any required resource row is `Needs-Manual`, every expected file and derived slice output MUST exist under `<project_path>/images/` before the first active Step 7 sub-step. If any file is absent, pause and list the exact filenames. After the files arrive, rerun `analyze_images.py`, replace each dashed placeholder in `svg_output/`, reconcile every `no-crop` container to the measured native ratio, then rerun the final SVG quality check so the gate covers the changed sources. |
| 669 | |
| 670 | After the separate readiness gate above has supplied every required manual file, the final SVG quality check closes each usable terminal §VIII row through `spec_lock.md images`, the exact locked file, and a real `<image href>`; it rejects unplanned/wrong-path references and also validates Sourced provenance/license records, image-specific visible credits, and effective per-placement pixel scale under `meet` / `slice` / `none`. |
| 671 | |
| 672 | **Failure recovery**: On a command failure, repair the owning source artifact and resume from that failed sub-step per [`failure-recovery.md`](./governance/failure-recovery.md). Do not restart planning unless its owning source changed. |
| 673 | |
| 674 | **Hard rule — strict serial commands**: Run the following commands one at a time. Do not combine them in one code block or shell invocation. Enter the next sub-step only after the current command exits successfully and its success criterion is true. |
| 675 | |
| 676 | #### Step 7.1 — Split Speaker Notes |
| 677 | |
| 678 | Run this sub-step only when the effective Speaker Notes outcome in |
| 679 | `design_spec.md §I` is enabled: |
| 680 | |
| 681 | ```bash |
| 682 | python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path> |
| 683 | ``` |
| 684 | |
| 685 | **Success criterion**: When enabled, per-slide Markdown files exist under |
| 686 | `<project_path>/notes/` and cover every published slide. When disabled, skip the |
| 687 | command and proceed directly to Step 7.2. |
| 688 | |
| 689 | #### Step 7.2 — Build the Self-Contained SVG Preview |
| 690 | |
| 691 | ```bash |
| 692 | python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path> |
| 693 | ``` |
| 694 | |
| 695 | **Success criterion**: `<project_path>/svg_final/` contains one self-contained preview SVG for every published slide. This mandatory derived preview does not replace `svg_output/` as the native-export source. |
| 696 | |
| 697 | #### Step 7.3 — Export the Native PPTX |
| 698 | |
| 699 | Choose exactly one notes mode: |
| 700 | |
| 701 | | Effective decision | Command | |
| 702 | |---|---| |
| 703 | | Speaker Notes `enabled` | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>` | |
| 704 | | Speaker Notes `disabled` | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --no-notes` | |
| 705 | |
| 706 | For deck-wide motion settings, append the resolved flags from |
| 707 | [`animations.md`](../references/animations.md). When the conditional custom |
| 708 | stage preserves or produces `<project_path>/animations.json`, keep the base command above: |
| 709 | the exporter reads the sidecar automatically. Explicit motion flags override |
| 710 | the corresponding sidecar default/slide fields, while group overrides remain |
| 711 | unless `-a none` hard-disables object motion. Exception: explicit Custom |
| 712 | Animations disable keeps the sidecar and appends `-a none`; final Stage-2 `false` |
| 713 | does neither. Only explicit all-motion disable uses `--no-animations`. |
| 714 | Otherwise do not mix deck-wide flags with a sidecar. With no motion input or |
| 715 | sidecar, preserve `fade` / `none`. |
| 716 | |
| 717 | **Success criterion**: The command exits successfully and produces: |
| 718 | |
| 719 | - `exports/<project_name>_<timestamp>.pptx` |
| 720 | - `validation/<project_name>_<timestamp>.report.json` with `passed` or `passed-with-warnings` package/resource postflight status |
| 721 | - `validation/<project_name>_<timestamp>.trace.json` when bare `--conversion-trace` is enabled; an explicit `--conversion-trace <path>` uses that destination instead |
| 722 | |
| 723 | Before creating the PPTX, the exporter independently requires the current matching `final` quality report; a missing, unreadable, unsupported, non-final, blocking, stale, or unverifiable report exits nonzero. The compact `[POSTFLIGHT]` receipt prints `status`, `quality_gate`, Slide count, warning-category counts, and PPTX/report paths. Disclose material warnings. Do not open or `cat` the complete report on routine success; use targeted field extraction only for failure investigation, an explicit audit request, or information absent from the receipt. A failed report or missing PPTX is not success. Retain its report path for later Generate narration (`deck_motion` handoff). |
| 724 | |
| 725 | ## ✅ Generate PPTX Complete |
| 726 | |
| 727 | - [x] Image readiness gate passed |
| 728 | - [x] Notes split completed when enabled; disabled exports used `--no-notes` |
| 729 | - [x] `svg_final/` preview completed |
| 730 | - [x] Native PPTX published and postflight report written |
| 731 | - [ ] **Next**: Report the exported PPTX path; when the effective Narration Audio outcome in `design_spec.md §I` is enabled, run [`generate-audio`](stages/generate-audio.md), otherwise run a supporting post-export stage only when its explicit trigger is present |
| 732 |