| 1 | --- |
| 2 | description: Generate-PPTX runbook for validating and installing selected Brand, Style, Layout, and Deck workspaces as separate project-local specs. |
| 3 | --- |
| 4 | |
| 5 | # Apply Template Workspace Stage |
| 6 | |
| 7 | > Run from [`generate-pptx.md`](../generate-pptx.md) Step 4 only after Stage 1 confirms at least one exact template workspace. [`quick-generate`](../profiles/quick-generate.md) enters only for exact roots or a current Create Template handoff. Never load for free design, bare names, or style descriptions. This stage applies the completed Stage-1 selection; it never chooses a workspace or changes the communication contract. |
| 8 | |
| 9 | ## 1. Gate and Normalize Inputs |
| 10 | |
| 11 | 🚧 **GATE**: Either Default Stage 1 confirmed a non-free template selection, or |
| 12 | Quick received exact roots directly from the |
| 13 | user/current Create Template handoff. In Quick, that explicit input is the complete selection authority: do |
| 14 | not launch Confirm UI or create `template_options.json`, |
| 15 | `template_selection.json`, or `template_handoff.json`. Every selected input must |
| 16 | resolve to one of these current contracts: |
| 17 | |
| 18 | | Input shape | Spec and SVG source | Asset source | |
| 19 | |---|---|---| |
| 20 | | Current workspace root | `<root>/templates/design_spec.md`, or one `design_spec.<kind>.<id>.md` per kind, plus `<root>/templates/` | Existing `<root>/images/` and `<root>/icons/` | |
| 21 | | Compatible legacy-flat Brand/Layout/Deck root | `<root>/design_spec.md`; Layout/Deck also require current-contract SVGs under `<root>/` | Package-local files | |
| 22 | | Current Create Template handoff | Its exact validated library or project workspace root | Existing portable sibling `images/` and `icons/`; already installed only when the root is the target project | |
| 23 | |
| 24 | Spec naming and kind declaration follow [`templates/README.md`](../../templates/README.md); a root exposing several kind-qualified specs contributes all of them. Do not accept only another project's inner `templates/` directory because that omits sibling assets. |
| 25 | |
| 26 | **Selection-source classification**: |
| 27 | |
| 28 | | Source label | Resolution rule | |
| 29 | |---|---| |
| 30 | | `library` | The normalized root exactly equals `templates/<kind_dir>/<id>/` derived from an entry in that kind's `*_index.json` | |
| 31 | | `explicit` | The user or Create Template supplied an exact workspace root that is not registered at that canonical index-derived root | |
| 32 | |
| 33 | Read library choices only from `brands_index.json`, `styles_index.json`, |
| 34 | `layouts_index.json`, and `decks_index.json`. Never scan kind directories or |
| 35 | promote an unregistered directory into the UI catalog. An explicit root remains |
| 36 | valid without index membership; exact equality with a registered root may be |
| 37 | reported as `library`. The label changes discovery provenance only, never schema |
| 38 | validation, segment precedence, or installation behavior. |
| 39 | |
| 40 | **Selection cardinality**: Select at most one root per kind; all four kinds may |
| 41 | coexist. A multi-kind explicit root contributes all its specs atomically and |
| 42 | may combine only with non-overlapping kinds. Default permits one explicit root |
| 43 | beside registered choices; Quick applies the same kind constraint. Reject |
| 44 | duplicate kinds before validation. |
| 45 | |
| 46 | **Hard rule — raw source boundary**: A raw PPTX is not a template workspace. Raw PPTX plus new content uses [`template-fill-pptx`](../template-fill-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first; its validated workspace-root handoff becomes a Stage-1 candidate and is preselected only when it is the sole supplied root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project. |
| 47 | |
| 48 | **Compatibility gate**: Reject semantic-legacy or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved. A legacy-flat Brand/Layout/Deck directory is readable only when it satisfies its current kind contract; Layout/Deck also require a current structured SVG contract. Style has no legacy-flat form. |
| 49 | |
| 50 | ## 2. Read the Matching Schema |
| 51 | |
| 52 | Read [`templates/README.md`](../../templates/README.md), then only the README for each supplied kind: |
| 53 | |
| 54 | | Kind | Schema | Owned segment | |
| 55 | |---|---|---| |
| 56 | | `brand` | [`templates/brands/README.md`](../../templates/brands/README.md) | Identity: color, typography, logo, voice/tone, icon style | |
| 57 | | `style` | [`templates/styles/README.md`](../../templates/styles/README.md) | Direction/method: reusable communication method, visual language, composition, and information-expression defaults | |
| 58 | | `layout` | [`templates/layouts/README.md`](../../templates/layouts/README.md) | Structure: canvas, page structure, semantic text roles, page types, SVG roster | |
| 59 | | `deck` | [`templates/decks/README.md`](../../templates/decks/README.md) | Application plus integrated identity and structure | |
| 60 | |
| 61 | A Layout created with `mirror` remains eligible only when its source contract is brand-neutral and application-neutral. Keep a branded or application-bearing source as a Deck, or re-author it as Layout through `standard` / `fidelity`; do not remove those semantics through mirror. |
| 62 | |
| 63 | Before mapping any current workspace, run its shared package validator from the |
| 64 | workspace root. This is the same schema authority used during creation and |
| 65 | registration: Brand/Style are roster-free, the active structure validates its |
| 66 | roster, and a shadowed Deck still validates its declared contract: |
| 67 | |
| 68 | ```bash |
| 69 | python3 skills/ppt-master/scripts/svg_quality_checker.py "<workspace_root>/templates" --template-mode |
| 70 | ``` |
| 71 | |
| 72 | Any error blocks installation. A compatible legacy-flat root uses its own root |
| 73 | as the checker target. |
| 74 | |
| 75 | ## 3. Structured Preflight |
| 76 | |
| 77 | Before copying a Deck or Layout workspace, inspect every SVG root and slot. Brand and Style workspaces are roster-free and skip this structured preflight: |
| 78 | |
| 79 | - Every page declares root Master/Layout keys and PowerPoint picker names. |
| 80 | - Master/Layout visuals are direct atoms, not generic layer `<g>` wrappers. |
| 81 | - Every non-composite slot is a top-level `<g>` with positive bounds and exactly one compatible carrier. |
| 82 | - A composite region uses an explicit `object` proxy; a zero-slot Layout is valid. |
| 83 | - The complete SVG contract is current. Reject a legacy semantic contract instead of repairing it in the target project. |
| 84 | |
| 85 | ## 4. Install Each Distinct Root Once |
| 86 | |
| 87 | Validate each normalized root once. Resolve the effective structural owner as |
| 88 | Layout when selected, otherwise Deck; install only its SVG/non-bitmap |
| 89 | structural payload, but install every selected spec. A library or |
| 90 | compatible legacy-flat root contributes one bare `design_spec.md`; install it |
| 91 | as `design_spec.<kind>.<id>.md`, where `<id>` comes from the matching |
| 92 | frontmatter id field. A current project root may contribute several qualified |
| 93 | specs; preserve each validated qualified filename. Never merge spec bodies, |
| 94 | and never copy one multi-kind root's shared SVG or asset pool once per kind. |
| 95 | |
| 96 | | Installed file | Meaning | |
| 97 | |---|---| |
| 98 | | `templates/design_spec.<kind>.<id>.md` | A template contribution installed into or authored in this project | |
| 99 | | `templates/design_spec.md` | Library or compatible legacy-flat source shape only; never valid beside qualified project specs | |
| 100 | |
| 101 | For every copied spec, prepend exactly one provenance line under its H1, then |
| 102 | leave the rest of the document untouched. An in-place root is not rewritten: |
| 103 | |
| 104 | ```markdown |
| 105 | > **Installed from**: `skills/ppt-master/templates/brands/mckinsey/` (library) |
| 106 | ``` |
| 107 | |
| 108 | **Root mapping**: |
| 109 | |
| 110 | - Copy every selected spec from the root to its resolved qualified destination. |
| 111 | - If the root contributes the effective structural owner, copy its declared |
| 112 | SVG roster and other non-bitmap structural files once. Do not copy a Deck |
| 113 | roster when Layout is selected; its structure is shadowed by design. |
| 114 | - Copy the root's real package-owned `images/` and `icons/` files once. A |
| 115 | Style-only root has none; reject a Style-only library package carrying asset |
| 116 | or review payloads. |
| 117 | - Ignore `exports/`; it contains review artifacts, not portable inputs. |
| 118 | |
| 119 | After that root-level copy, kinds have these downstream effects: |
| 120 | |
| 121 | | Kind | Consumption behavior | |
| 122 | |---|---| |
| 123 | | `brand` | Identity is constrained; structure remains free unless the selected set also includes Layout or Deck. | |
| 124 | | `style` | Expose reusable direction/method without identity truth, page prototypes, or native structure. Default Style-only and Style + Brand derive `template_reuse_scope: style` and stay flat; Style + Layout/Deck follows the selected structure plan. Quick always realizes the resolved combination as flat pages. A Style workspace never activates visual review. | |
| 125 | | `layout` | Expose the actual reusable structure and take structural precedence over Deck; Default Strategist later inspects these prototypes, while Quick's current agent uses them for immediate flat authoring decisions in active context. | |
| 126 | | `deck` | Expose descriptive application context and identity. It also supplies structure and the actual prototype roster only when no Layout is selected. | |
| 127 | |
| 128 | For a compatible legacy-flat package, route SVG/spec/non-bitmaps to project `templates/`, bitmaps to project `images/`, and declared icons to project `icons/`. Do not infer legacy Master/Layout semantics from the flat directory shape. |
| 129 | |
| 130 | **Atomic install preflight**: |
| 131 | |
| 132 | 1. Resolve every source and destination path. |
| 133 | 2. Enumerate the union mapping across all distinct roots and across |
| 134 | `templates/`, `images/`, and `icons/`; map a source file at most once. |
| 135 | 3. Reject every destination collision and every duplicate-kind selection |
| 136 | before writing. Resolve Layout-over-Deck structural precedence before |
| 137 | constructing the destination map, so the shadowed Deck roster never enters |
| 138 | that map. |
| 139 | 4. Write the accepted mapping once; never use recursive copy as an implicit conflict policy. |
| 140 | |
| 141 | Consume an input equal to the target project in place, mapping only other |
| 142 | roots. If a selected Layout supersedes its in-place Deck roster, stage the |
| 143 | accepted mapping and replace that roster atomically. Never mix rosters or write |
| 144 | piecemeal. Ignore `exports/`; empty optional roots remain absent. |
| 145 | |
| 146 | **Hard rule — project-local consumer boundary**: After installation, |
| 147 | Default template-aware Strategist work in final Stage 2, Quick's current |
| 148 | agent before direct authoring, and every later role read only |
| 149 | `<project_path>/templates/` and the project-local `images/` / `icons/` pools. The original library or external root |
| 150 | is installation input, not a later prompt source. If source and target are the |
| 151 | same project root, that in-place root already satisfies this boundary. |
| 152 | |
| 153 | Template SVGs are authoring prototypes, not export-time overlays. The generated page remains complete in `svg_output/`; `page_layouts` selects the complete prototype and its explicit structure contract for authoring. |
| 154 | Quick instead realizes the selected prototypes into complete flat, Slide-local |
| 155 | SVGs and never writes `page_layouts` or Master/Layout/placeholder metadata. |
| 156 | |
| 157 | |
| 158 | ## 5. Segment Precedence Is Resolved While Reading |
| 159 | |
| 160 | Installation copies specs; it never merges them. The consuming role — Default |
| 161 | final Stage 2 through [`strategist-template.md`](../../references/strategist-template.md), |
| 162 | or Quick's current agent before authoring — reads **every** installed |
| 163 | `design_spec.<kind>.<id>.md` and resolves the segments below in context. Asset |
| 164 | collisions are still rejected at install time (§4); segment conflicts are a |
| 165 | reading decision, not a write-time one. |
| 166 | |
| 167 | Never reinterpret, predict, or revise the confirmed Stage-1 communication |
| 168 | contract here. Default obtains any additional material conflict decision |
| 169 | through the active chat channel after Stage 1; this does not reopen template |
| 170 | selection. Quick follows explicit conflict instructions; an unresolved material |
| 171 | compatibility conflict is a hard prerequisite handled in chat, never by |
| 172 | launching Confirm UI or by using path order. |
| 173 | |
| 174 | ### 5.1 Different Kinds |
| 175 | |
| 176 | Resolve four whole template segments. This table names the starting owner; |
| 177 | current user instructions and the consuming plan still govern project use: |
| 178 | |
| 179 | | Segment | Starting owner | |
| 180 | |---|---| |
| 181 | | Identity | Brand, otherwise Deck, otherwise unresolved until the consuming plan (Default final Stage 2 or Quick active context). Style color/type/icon/image values are direction candidates, never identity truth. | |
| 182 | | Structure | Layout when present, otherwise Deck, otherwise unresolved/free design until the consuming plan. Style owns no canvas, prototype, Master/Layout, slot, or page mapping. | |
| 183 | | Reusable application context | Deck only when present. Preserve it for the consuming comparison; it never becomes the current project's application contract. | |
| 184 | | Direction / method | Style when present, otherwise unresolved until the consuming plan. Actual Deck prototypes and Signature facts may inform compatibility, but Deck does not own the Style-only method segment. | |
| 185 | |
| 186 | Apply each selected segment wholesale; do not mix its fields implicitly. Brand or Deck identity overrides any identity-adjacent defaults carried by Style. A Style direction may adapt to that resolved identity, but cannot relabel its candidates as official brand facts. |
| 187 | |
| 188 | **Hard rule — an owned segment governs visual weight, not only values**: when a |
| 189 | segment owner declares how a value should dominate, recede, or stay rare, that |
| 190 | instruction carries the same authority as the value itself. A Style's |
| 191 | composition or whitespace tendency never demotes a Brand's declared dominant |
| 192 | color to an incidental accent. |
| 193 | |
| 194 | Before Style overlays Layout or Deck guidance, verify that its method fits the |
| 195 | selected structure and, for Deck, serves its reusable context. On mismatch, |
| 196 | require omitting Style or choosing a compatible Style/structure; never silently |
| 197 | weaken a segment. Default final Stage 2 separately checks the result against the |
| 198 | confirmed project contract; Quick checks it against the current request/content |
| 199 | before authoring. |
| 200 | |
| 201 | Field-level micro-adjustments such as a primary-color override are not a workspace selection. Default carries them into the normal final Stage-2 confirmation fields; Quick treats explicit adjustments as direct active-context authoring constraints. |
| 202 | |
| 203 | ### 5.2 Selection Conflicts |
| 204 | |
| 205 | Duplicate kinds are selection errors. Layout plus Deck is valid: Layout owns |
| 206 | structure; Deck keeps its other segments. Default returns duplicates to Stage |
| 207 | 1; Quick asks for narrower roots. Never split a multi-kind root, average |
| 208 | same-kind specs, or choose by path order. |
| 209 | |
| 210 | ### 5.3 Installed Set |
| 211 | |
| 212 | Each installed file keeps its own frontmatter `kind` and `<id>` from its source |
| 213 | workspace; nothing is relabelled. There is no combined capability label and no |
| 214 | merged spec: the installed set is exactly what was selected, and the routing |
| 215 | consequence is derived while reading — structure comes from Layout when |
| 216 | present, otherwise Deck; identity comes from Brand or Deck; direction comes |
| 217 | from Style. A project-local Brand + Layout pair does not become a reusable library |
| 218 | Deck; its application remains current-project context. |
| 219 | |
| 220 | **Completion receipt**: Report `roots=<unique normalized roots>; sources=<library|explicit per root>; kinds=<all contributed kinds per root>; segments=identity:<owner>,structure:<owner>,application_context:<owner>,direction:<owner>; active_roster=<layout|deck|none>:<source root>; install=<in-place|copied>; installed_specs=<comma-separated design_spec.<kind>.<id>.md>`. |
| 221 | |
| 222 | ## ✅ Template Workspace Applied |
| 223 | |
| 224 | - [x] Every selected input was an index-derived library root or an exact explicit/Create Template root satisfying a listed workspace contract |
| 225 | - [x] Every kind schema passed preflight; structured SVG checks ran only for Layout/Deck inputs |
| 226 | - [x] Duplicate kinds and all destination collisions were rejected before one atomic install; Layout-over-Deck precedence selected exactly one active structural roster |
| 227 | - [x] `<project_path>/templates/` and any portable sibling assets are complete and are the only downstream template source |
| 228 | - [ ] **Next**: Default completes the template-selection handoff and continues [`generate-pptx.md`](../generate-pptx.md) Step 4 Stage 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2 |
| 229 |