| 1 | --- |
| 2 | description: Deterministic selection among PPT Master's four top-level artifact routes. |
| 3 | --- |
| 4 | |
| 5 | # Routing Rules |
| 6 | |
| 7 | Route selection authority for PPT Master. Select exactly one top-level route, then activate only the child workflows, profiles, and stages owned by that route. |
| 8 | |
| 9 | **Hard rule**: If this file conflicts with a route summary elsewhere in the |
| 10 | Skill package or in a repository-level user-facing document, this file wins for |
| 11 | route selection. After selection, the active runtime authority owns execution. |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## 1. Routing Discipline |
| 16 | |
| 17 | | Rule | Behavior | |
| 18 | |---|---| |
| 19 | | One artifact lifecycle | Every request enters Generate PPTX, Create Template, Fill Native PPTX, or Enhance Native PPTX | |
| 20 | | Supporting documents are not top-level routes | Create Template child workflows, generation profiles, stages, and governance documents refine the selected route; never offer them as competing top-level routes | |
| 21 | | Missing prerequisite | State the missing prerequisite and stop that route; do not invent an alternative | |
| 22 | | Ambiguous existing-deck request | Ask one discriminator question only when needed: regenerate visible slides, fill native slide shells with new content, or preserve slides and add native behavior? | |
| 23 | | Explicit user override | Honor explicit route instructions only when the route preconditions are satisfied | |
| 24 | |
| 25 | **Forbidden — route-choice menus**: Do not present multiple implementation paths when the request already matches one row in §2. Ordinary design choices remain at the selected route's existing confirmation gate. |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## 2. Top-Level Route Matrix |
| 30 | |
| 31 | | Route | Request shape | Authority | Preconditions | Mutation model | Output contract | |
| 32 | |---|---|---|---|---|---| |
| 33 | | Generate PPTX | Create, reconstruct, or visually regenerate a presentation/video from sources or a topic; templates remain optional | Image to PPTX: [`image-to-pptx`](./profiles/image-to-pptx.md), always Quick; Beautify: [`beautify-pptx`](./profiles/beautify-pptx.md), Default or Quick; ordinary [`generate-pptx`](./generate-pptx.md) / [`quick-generate`](./profiles/quick-generate.md) | Facts exist or research can gather them; Image to PPTX also requires Codex and an ordered page-frame roster | Author SVG pages and export a new PPTX | Default: spec/lock/SVG/PPTX; Quick: optional source/resource artifacts, no spec/lock, SVG/PPTX; either may derive narrated PPTX/MP4 | |
| 34 | | Create Template | Create a reusable brand/style/layout/deck template from one or more PPTX/SVG files, images/PDFs, direct or file-based text, documents/websites, brand assets, or a mixed reference bundle | [`create-template`](./create-template.md) | A reusable-template request exists; reference material is optional, and project scope additionally requires an initialized target project | Author a new portable workspace; never modify any reference file in place | Workspace with required `templates/`, optional `images/` / `icons/`, and optional review `exports/` | |
| 35 | | Fill Native PPTX | Use a raw PPTX's native slide shells and replace/fill content | [`template-fill-pptx`](./template-fill-pptx.md) | Source PPTX plus new material/topic | Clone and patch PPTX through OOXML; no SVG pipeline | New filled PPTX in project `exports/` | |
| 36 | | Enhance Native PPTX | Keep a finished PPTX's visible slides stable while adding notes, audio, timings, or transitions | [`native-enhance-pptx`](./native-enhance-pptx.md) | Finished source PPTX exists | Append/update scoped OOXML parts; no slide regeneration | New enhanced PPTX in project `exports/` | |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## 3. Generate PPTX Profiles and Stages |
| 41 | |
| 42 | | Request condition | Generate-route behavior | |
| 43 | |---|---| |
| 44 | | One or more raster files represent page frames that must be reconstructed into a layered editable PPTX | Activate the Codex-supported [`image-to-pptx`](./profiles/image-to-pptx.md); normalize the represented frame roster and activate `quick-generate` directly without requiring a separate Quick request | |
| 45 | | Existing PPTX must preserve wording, page count, and page order 1:1 | Activate [`beautify-pptx`](./profiles/beautify-pptx.md); it selects `quick-generate` when that profile's explicit trigger also matches, otherwise `generate-pptx` | |
| 46 | | The effective delivery purpose is recorded, self-running, or video-directed | Inside the already selected Default or explicit Quick runtime, load [`video-design`](../references/video-design.md) before whole-solution/page planning. This is a conditional design reference, not a profile or fifth route; notes, animation, audio, and optional native MP4 remain owned by their existing stages | |
| 47 | | Explicit quick/fast, skip-strategy, or direct SVG-to-PPTX intent without an active fidelity profile | Load [`quick-generate`](./profiles/quick-generate.md) directly without loading `generate-pptx.md`: prepare sources/resources as needed, let the current agent decide without interaction, directly apply at most one exact workspace root per kind supplied for this run, otherwise use free design, omit Strategist/Confirm UI/spec/lock, hand-author SVG, run the lockless final checker, and export the final PPTX | |
| 48 | | Topic only, or supplied sources leave planning-critical factual gaps | Run [`topic-research`](./stages/topic-research.md) inside the selected Generate profile's source preparation: immediately for topic-only input, or after conversion and reading for source-backed input; research only the identified gaps | |
| 49 | | Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through the selected Generate authority's source intake; continue Default unless explicit Quick intent selected that runtime | |
| 50 | | Default Generate reaches planning | Step 3 prepares template candidates without interaction. Stage 1 then confirms the communication contract and free-design/template choice together; only a confirmed non-free choice runs [`apply-template-workspace`](./stages/apply-template-workspace.md) before Stage 2 | |
| 51 | | Explicit current brand/style/layout/deck workspace root outside Image to PPTX | Default Generate preserves the exact path as a Stage-1 template candidate; Quick Generate validates and installs it directly without Steps 3–4 or Confirm UI. Classify it as `library` only when its normalized root exactly matches a registered index entry; otherwise retain `explicit`. Consume the workspace root, never only its inner `templates/` directory | |
| 52 | | Split-mode project resumes in a fresh chat | Run [`resume-execute`](./stages/resume-execute.md) inside the active Generate route | |
| 53 | | Existing generated project needs a deck-wide `colors.*` or universal `typography.font_family` substitution | Stay in Generate; load [`update_spec.py`](../scripts/docs/update_spec.md), honor its supported-key boundary, then rerun the final quality gate and Step 7 export | |
| 54 | | User explicitly requests spec refinement | Run [`refine-spec`](./stages/refine-spec.md) after Design Spec Gate 1 and before lock Gate 2 | |
| 55 | | Data charts exist | Run [`verify-charts`](./stages/verify-charts.md) before export | |
| 56 | | User explicitly requests visual review | Run [`visual-review`](./stages/visual-review.md) before post-processing | |
| 57 | | User requests preview, selection, or annotation application outside Image to PPTX | Use the default Generate pipeline and run [`live-preview`](./stages/live-preview.md) at the stage defined there; explicit Quick + preview intent falls back to default rather than dropping preview. Image to PPTX remains Quick-only and uses its mandatory canonical-frame recomposition comparison instead of this interactive stage | |
| 58 | | User requests page transitions, auto-advance, or deck-wide animation settings without page-specific motion planning or an existing `animations.json` | Load [`animations`](../references/animations.md) and apply its export-level contract | |
| 59 | | `<project_path>/animations.json` already exists, the user explicitly requests per-slide/object-level animation control, or the effective Custom Animations outcome in `design_spec.md §I` is enabled | Run [`customize-animations`](./stages/customize-animations.md) after the final SVG quality gate and any enabled speaker-note pass, before Generate Step 7. A §IX `Motion suggestion` informs an active pass but never triggers it alone | |
| 60 | | Generate PPTX receives an explicit narration request or has effective Narration Audio enabled in `design_spec.md §I`; Enhance Native PPTX has a confirmed `audio.enabled: true` module | Run [`generate-audio`](./stages/generate-audio.md) after the owning route's notes/export readiness; Generate audio implies effective Speaker Notes enabled | |
| 61 | |
| 62 | **Hard rule — fidelity profiles, not fifth routes**: Image to PPTX and Beautify |
| 63 | change different source/page invariants and are mutually exclusive. Image to |
| 64 | PPTX always activates Quick; Beautify uses Quick only on explicit Quick intent |
| 65 | and otherwise uses Default. Neither defines a separate artifact lifecycle or |
| 66 | loads both runtimes. |
| 67 | |
| 68 | **Hard rule — direct-generation profile, not a fifth route**: `quick-generate` |
| 69 | stays inside Generate PPTX but owns an explicit SVG → PPTX short circuit. Page |
| 70 | count alone never activates or blocks it. Conversion, bounded research, and |
| 71 | project-local resources remain available. Package capabilities may be requested |
| 72 | or agent-selected. Quick may consume exact Brand/Style/Layout/Deck workspaces as |
| 73 | flat authoring inputs, with at most one contribution per kind. All four kinds |
| 74 | may combine; Layout takes structural precedence over Deck. A multi-kind project |
| 75 | root contributes all of its specs atomically; |
| 76 | compiling reusable Master/Layout/placeholder structure still requires the |
| 77 | default lock-backed Generate pipeline. Once selected, Quick |
| 78 | is the complete runtime procedure and never loads `generate-pptx.md`; Default |
| 79 | never loads `quick-generate.md`. Image to PPTX is the narrow profile-owned |
| 80 | Quick activation; Beautify may select either runtime, but never both. |
| 81 | |
| 82 | --- |
| 83 | |
| 84 | ## 4. Template and Master/Layout Boundary |
| 85 | |
| 86 | **Hard rule — no direct structure grafting**: An existing PPTX or SVG is never upgraded in place by adding Master/Layout/placeholder structure. If reusable native structure is required: |
| 87 | |
| 88 | 1. Run [`create-template`](./create-template.md) to produce a separate validated workspace. |
| 89 | 2. Pass that workspace root to [`generate-pptx`](./generate-pptx.md) as a Stage-1 template candidate. |
| 90 | 3. Author new structured SVG pages whose Master/Layout contract exists from their first generated draft. |
| 91 | 4. Export a new PPTX from those pages. |
| 92 | |
| 93 | When a PPTX already contains native Master/Layout parts, `create-template` mirror may read and preserve those existing package facts in the new workspace. It does not infer missing historical intent. An incomplete or legacy SVG package may guide `standard` / `fidelity` visually, but it is not mutated into a structured template and cannot claim source-topology recovery. |
| 94 | |
| 95 | **Hard rule — no automatic structure upgrade**: Free-design, brand-only, and style-only generation remains `pptx_structure.mode: flat`. Repeated Slide-local objects never trigger `structured`, Master/Layout promotion, placeholder inference, or deduplication. The minimal Master plus Blank Layout emitted by flat export is package scaffolding, not an inferred reusable design master. |
| 96 | |
| 97 | | Input | Route behavior | |
| 98 | |---|---| |
| 99 | | One or more images containing page frames + explicit final-deck reconstruction intent | Generate PPTX with the Codex-supported, Quick-only [`image-to-pptx`](./profiles/image-to-pptx.md); normalize page frames first and do not infer reusable native structure from pixels | |
| 100 | | Raw PPTX called a template + new content | Fill Native PPTX unless the user explicitly asks for a reusable template workspace | |
| 101 | | Any supported reference bundle or direct-text brief + reusable template request | Create Template | |
| 102 | | Current template workspace root + content | [`generate-pptx`](./generate-pptx.md) Stage-1 template choice | |
| 103 | | Legacy-flat Brand/Layout/Deck root satisfying its current kind contract; Layout/Deck also require current structured SVGs | [`apply-template-workspace`](./stages/apply-template-workspace.md) compatibility reader; Style has no flat form | |
| 104 | | Semantic-legacy or incomplete structured package | Create a new workspace through Create Template; do not migrate in place | |
| 105 | | Request to add a master directly to an existing PPTX/SVG | Unsupported; explain the Create Template → Generate PPTX lifecycle | |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## 5. Create Template Child Workflows |
| 110 | |
| 111 | | Selected kind | Behavior | |
| 112 | |---|---| |
| 113 | | `brand` | Dispatch to [`create-brand`](./create-template/create-brand.md); write identity only and no SVG roster | |
| 114 | | `style` | Dispatch to [`create-style`](./create-template/create-style.md); write reusable communication method and design direction only, with no SVG roster or native structure | |
| 115 | | `layout` | Dispatch to [`create-layout`](./create-template/create-layout.md); author brand-neutral, application-neutral structure and an SVG roster | |
| 116 | | `deck` | Dispatch to [`create-deck`](./create-template/create-deck.md); author descriptive recurring-application context with integrated identity, structure, and an SVG roster | |
| 117 | |
| 118 | Create Template remains the fixed route name and owns the shared contract. These four documents are mutually exclusive child workflows, not additional top-level routes. |
| 119 | |
| 120 | **Hard rule — classify reusable rules, not source completeness**: A complete |
| 121 | PPTX does not automatically select Deck. Use Brand when only identity is |
| 122 | stable; use Style when reusable communication method and design direction |
| 123 | should travel without identity truth, page prototypes, or native |
| 124 | structure; use Layout when structure is brand-neutral and the communication |
| 125 | application stays downstream-defined; use Deck when structure carries identity |
| 126 | or reusable scenario/content semantics. |
| 127 | |
| 128 | --- |
| 129 | |
| 130 | ## 6. Native and Shared Post-Processing Boundary |
| 131 | |
| 132 | | Artifact state | Narration route | |
| 133 | |---|---| |
| 134 | | Main-generated project with notes and exported deck | Shared [`generate-audio`](./stages/generate-audio.md) stage | |
| 135 | | Arbitrary finished PPTX that must preserve visible slides | Enhance Native PPTX; its narration module invokes the same shared audio-stage rules | |
| 136 | |
| 137 | Object animation for generated SVG projects uses the animation stage. Native PPTX routes preserve existing object-animation fingerprints and do not silently claim an animation-editing capability. |
| 138 | |
| 139 | --- |
| 140 | |
| 141 | ## 7. Template Selection Boundary |
| 142 | |
| 143 | | User input | Behavior | |
| 144 | |---|---| |
| 145 | | Default Generate | Step 3 prepares candidates only; Stage 1 confirms one communication contract plus either free design or template use in the same interaction | |
| 146 | | Explicit current workspace root exposing at least one `templates/` Design Spec | Preserve it as a Stage-1 candidate and initialize template mode; preselect that specific candidate only when it is the sole supplied root. An exact registered-root match may be displayed as `library` | |
| 147 | | No exact workspace root and no explicit template intent | Initialize Stage 1 to free design; the user may switch to template mode and select an indexed workspace | |
| 148 | | Explicit template intent or any exact workspace root | Initialize Stage 1 to template mode; exactly one root may be preselected, while multiple roots remain unselected candidates | |
| 149 | | Bare template/brand name or style label without an explicit template-use request | Do not resolve it to a local path or preselect a template; treat it as a style brief. An explicit request to use templates still initializes template mode, but leaves the specific candidate for the user to choose | |
| 150 | | “What templates exist?” in chat | List indexed workspace paths; Stage 1 still requires an explicit free-design/template choice | |
| 151 | |
| 152 | The default UI and chat discovery read only these indexes. Never scan the |
| 153 | corresponding directories to construct or supplement the catalog: |
| 154 | |
| 155 | | Kind | Discovery index | |
| 156 | |---|---| |
| 157 | | Brand | [`brands_index.json`](../templates/brands/brands_index.json) | |
| 158 | | Style | [`styles_index.json`](../templates/styles/styles_index.json) | |
| 159 | | Layout | [`layouts_index.json`](../templates/layouts/layouts_index.json) | |
| 160 | | Deck | [`decks_index.json`](../templates/decks/decks_index.json) | |
| 161 | |
| 162 | **Hard rule — one Stage-1 confirmation, delayed template reading**: Author the |
| 163 | communication recommendation without reading candidate workspaces. Stage 1 |
| 164 | confirms that contract and the template/free-design choice together. Only then |
| 165 | validate/install selected roots and complete the handoff. Stage 2 waits for that |
| 166 | handoff, reads only the installed project-local state, and decides how to apply |
| 167 | it; it never reselects a template. |
| 168 | |
| 169 | **Forbidden — fuzzy resolution**: Never resolve a bare name to a local template |
| 170 | directory on the user's behalf. A library choice comes from an index-derived |
| 171 | root; an unregistered workspace requires an explicit root, including the exact |
| 172 | validated workspace handed off by Create Template in the current conversation. |
| 173 |