| 1 | # Template Architecture: Brand / Style / Layout / Deck |
| 2 | |
| 3 | [English](./templates-architecture.md) | [Chinese](./zh/templates-architecture.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | > This is the **architecture alignment document**. It defines the four template kinds at the data-model layer, the field sets of each `design_spec.md`, and the multi-path fusion + conflict resolution rules. Audience: contributors and AI workflows; answers "what should / shouldn't a template directory contain; how do they combine when multiple are supplied". |
| 8 | > |
| 9 | > For user-facing usage (how to trigger, how to pick), see [`templates-guide.md`](./templates-guide.md); not repeated here. |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## 1. The four kinds |
| 14 | |
| 15 | | Kind | Library workspace root | What it writes | What it does NOT write | Originating workflow | |
| 16 | |---|---|---|---|---| |
| 17 | | **Brand** | `templates/brands/<id>/` | Identity segment only: color / typography / logo / voice / icon style | No canvas, page structure, SVG roster | `workflows/create-template/create-brand.md` | |
| 18 | | **Style** | `templates/styles/<id>/` | Portable direction/method: communication method, page-role vocabulary, evidence/data expression, visual defaults, image/icon direction, advisory review focus | No identity truth, application contract, canvas, page structure, or SVG roster | `workflows/create-template/create-style.md` | |
| 19 | | **Layout** | `templates/layouts/<id>/` | Brand-neutral structure segment only: canvas / page structure / semantic text roles / page types / SVG roster | No brand identity and no recurring communication application | `workflows/create-template/create-layout.md` | |
| 20 | | **Deck** | `templates/decks/<id>/` | A recurring presentation family: descriptive application context + integrated identity + structure | — | `workflows/create-template/create-deck.md` | |
| 21 | |
| 22 | Every newly created Layout/Deck SVG is a complete preview with root Master/Layout key and picker names, direct atomic Master/Layout elements, and top-level semantic slot groups. A normal slot has positive design-zone bounds and exactly one compatible carrier; composite `object` regions use explicit proxy binding, and zero-slot Layouts are valid. These specialized markers are authoritative; minimal `data-pptx-role` hints are added only for structural page-frame behavior they cannot express. Create Template derives `standard` / `fidelity` / `mirror` internally from the natural-language intent and source evidence. Authored strategies create new SVGs and structure; mirror materializes validated source facts. Strategist later derives strict/adaptive exporter behavior from the actual prototypes and current content. None of these implementation values is a required user choice. A legacy-flat Brand/Layout/Deck directory with `design_spec.md` at its root remains readable only when it satisfies the current kind contract; Style has no legacy-flat form. Semantic-legacy packages must be replaced by a newly created template workspace; they are never upgraded in place. |
| 23 | |
| 24 | The four are **parallel reusable-rule bundles**, not PowerPoint package-object types. In library scope, the physical directory and the frontmatter `kind` field correspond one-to-one: |
| 25 | |
| 26 | The fused project-level `design_spec.md` retains the existing capability label: `deck` when both identity and structure are present, `layout` when structure is present without identity, `brand` when identity is present without structure, and `style` only when direction/method is the sole reusable segment. Style combined with another kind does not change that kind label. For a project-local Brand + Layout composition, `kind: deck` means “both capabilities are installed”; it does not promote that composition into a reusable library Deck or invent application context. The current project's Stage-1 communication contract supplies that context. Strategist derives the template application plan internally; the confirmation page exposes no template mode controls. |
| 27 | |
| 28 | ```yaml |
| 29 | # templates/brands/anthropic/templates/design_spec.md |
| 30 | --- |
| 31 | kind: brand |
| 32 | ... |
| 33 | --- |
| 34 | |
| 35 | # templates/styles/consulting_analytical/templates/design_spec.md |
| 36 | --- |
| 37 | kind: style |
| 38 | ... |
| 39 | --- |
| 40 | |
| 41 | # templates/layouts/presentation_core/templates/design_spec.md |
| 42 | --- |
| 43 | kind: layout |
| 44 | native_structure_mode: structured |
| 45 | ... |
| 46 | --- |
| 47 | |
| 48 | # templates/decks/中国电信/templates/design_spec.md |
| 49 | --- |
| 50 | kind: deck |
| 51 | native_structure_mode: structured |
| 52 | ... |
| 53 | --- |
| 54 | ``` |
| 55 | |
| 56 | ### Native PowerPoint objects are compilation targets |
| 57 | |
| 58 | Project template kinds do not map one-to-one to PresentationML objects: |
| 59 | |
| 60 | | Project contract | Native projection | |
| 61 | |---|---| |
| 62 | | **Brand** | Theme colors/fonts/effects plus logo and other fixed identity-asset rules | |
| 63 | | **Style** | No reusable package structure; confirmed method and visual defaults guide flat Slide-local authoring | |
| 64 | | **Layout** | Master/Layout/Placeholder topology, reusable geometry, semantic text roles, and spatial slot behavior | |
| 65 | | **Deck** | The Brand and Layout projections plus descriptive recurring-application context and actual prototypes | |
| 66 | |
| 67 | A Slide Master may contain both structural geometry and brand visuals. Source |
| 68 | ownership remains separated—Layout owns topology, placement, semantic text |
| 69 | roles, and spatial behavior; Brand owns identity values and assets. Under |
| 70 | downstream `layout` scope, export resolves final placeholder formatting from |
| 71 | those rules plus the confirmed reading mode/type scale; `mirror` preserves |
| 72 | literal source formatting and text topology. Export then compiles the |
| 73 | applicable rules into the same native Master/Layout graph. Theme is therefore |
| 74 | an implementation projection of resolved identity—whether supplied by Brand, |
| 75 | Deck, or the current project—not another template kind. Style fallback colors |
| 76 | and fonts are proposal seeds, not Theme identity truth. |
| 77 | |
| 78 | ### Output scope is separate from kind |
| 79 | |
| 80 | `create-template` confirms where a workspace is placed. This execution choice does not add another kind and does not add a PPTX structure mode: |
| 81 | |
| 82 | | Scope | Workspace root | Core workspace | Discovery | |
| 83 | |---|---|---|---| |
| 84 | | `library` (default) | `skills/ppt-master/templates/<kind>/<id>/` | Required `templates/`; optional `images/`, `icons/`, and on-demand `exports/` | Register in the matching global index | |
| 85 | | `project` | `projects/<name>/` | The same routing contract | No global index update | |
| 86 | |
| 87 | Both roots have the same core shape: |
| 88 | |
| 89 | ```text |
| 90 | <template_workspace>/ |
| 91 | ├── templates/ |
| 92 | │ ├── design_spec.md |
| 93 | │ └── *.svg |
| 94 | ├── images/ # optional; SVG href uses ../images/<name> |
| 95 | ├── icons/ |
| 96 | │ └── imported/ # optional; canonical imported vector assets |
| 97 | └── exports/ # optional; requested review or required multi-Master evidence |
| 98 | └── <id>_template_preview.pptx |
| 99 | ``` |
| 100 | |
| 101 | Empty optional directories are omitted; do not add placeholder files. A preview |
| 102 | PPTX is derived review evidence, not a source template asset. It is generated |
| 103 | on request and is mandatory for a multi-Master package gate. Step 3 records the |
| 104 | workspace root as candidate input without reading its content. After Stage 1 |
| 105 | selects it, the apply stage consumes `templates/` plus any existing `images/` |
| 106 | and `icons/`; it ignores `exports/`. Library `exports/` directories are |
| 107 | Git-ignored. |
| 108 | |
| 109 | Imported vectors use `data-icon="imported/<name>"` and have one canonical file |
| 110 | at `icons/imported/<name>.svg`. Workspace-aware validation and export resolve |
| 111 | that root path directly; `templates/icons/` is not part of the package shape. |
| 112 | |
| 113 | PPTX import uses a two-level metadata model. The temporary lossless SVG keeps native-shape metadata, hidden carriers, and preview evidence as immutable payload backing; `svg_authoring_view.py` creates the editable authoring IR bundle, whose lightweight SVGs carry document-local source refs and whose manifest stores only paths and initial hashes. Authored modes use project-canonical SVG and compact authored-preset groups only for exact registered preset matches. Mirror materializes templates from the IR and reuses converter-supported payload only for unchanged Slide-local/slot refs; fixed structural layers remain direct atoms, unsupported or edited objects keep their SVG fallback, and final templates contain no IR-only refs. Export compiles only the declared SVG structure and never infers ownership. |
| 114 | |
| 115 | Both scopes retain their selected `kind` in portable frontmatter. `output_scope` and `target_project` stay in the workflow brief and are not persisted into `design_spec.md`. |
| 116 | |
| 117 | Before any final write, resolve the selected workspace root, require an empty `templates/` root, and check all planned image and icon destination filenames for conflicts. Check a preview-PPTX destination when review was requested or the confirmed roster contains multiple Masters. Project scope additionally requires an initialized target project. Fail before writing anything; never merge or overwrite. |
| 118 | |
| 119 | ### Segment partition |
| 120 | |
| 121 | To make multi-path fusion override cleanly, every field belongs to a named segment. **Default fusion granularity is whole-segment replacement**: |
| 122 | |
| 123 | | Segment | Sections it contains | Override owner | |
| 124 | |---|---|---| |
| 125 | | **Identity** | Color Scheme / Typography / Logo / Voice & Tone / Icon Style | brand | |
| 126 | | **Direction / method** | Communication Method / Page Role Vocabulary / Evidence & Data Expression / Visual System Defaults / Image & Icon Direction / Review Focus | style; defaults remain subordinate to user-confirmed choices and owning identity/structure segments | |
| 127 | | **Structure** | Portable canvas/page-type metadata, structure-owned Signature rules, SVG Page Roster, and the SVG Master/Layout/slot contract | layout | |
| 128 | | **Application** | Template Overview: recurring situations, audiences/outcomes, delivery assumptions, and representative narrative/page roles | deck only; brand / layout don't write this | |
| 129 | |
| 130 | ### Why Deck is its own kind |
| 131 | |
| 132 | A Deck encodes a **recurring presentation family**, not merely a pre-combined |
| 133 | Brand and Layout. It describes the communication situations the template |
| 134 | serves, the audience outcomes it supports, and representative narrative/page |
| 135 | roles. Identity and structure are integrated around that context, while the |
| 136 | current Strategist decides which prototypes and content to use. |
| 137 | |
| 138 | `standard` / `fidelity` author a new complete system from confirmed evidence; |
| 139 | mirror maps validated source identities and parentage one-to-one into a new |
| 140 | workspace. Mirror preserves source facts but does not prove that the source is |
| 141 | a reusable Deck: creation still has to identify the stable application rules. |
| 142 | A source that yields only identity becomes Brand; reusable method and visual |
| 143 | direction without prototypes becomes Style; a brand-neutral reusable structure |
| 144 | becomes Layout; a branded structural system or scenario-bearing content grammar |
| 145 | becomes Deck. |
| 146 | |
| 147 | This also constrains creation mode: Layout mirror is valid only when the source |
| 148 | contract is already brand-neutral and application-neutral. Removing brand |
| 149 | paint, fonts, logos, fixed identity objects, or reusable application rules is |
| 150 | authorship, so a source outside that boundary must either use `standard` / |
| 151 | `fidelity` to create a new Layout or retain those facts as Deck mirror. |
| 152 | |
| 153 | --- |
| 154 | |
| 155 | ## 2. `design_spec.md` schema per kind |
| 156 | |
| 157 | The schema only specifies the **required** fields. "Don't write what isn't necessary" — if a field isn't listed here, don't add it. |
| 158 | |
| 159 | ### Brand schema |
| 160 | |
| 161 | **Frontmatter** |
| 162 | |
| 163 | ```yaml |
| 164 | --- |
| 165 | brand_id: <slug> |
| 166 | kind: brand |
| 167 | summary: <one-line use cases, including primary color> |
| 168 | primary_color: "<HEX>" |
| 169 | --- |
| 170 | ``` |
| 171 | |
| 172 | **Body sections** (full identity segment) |
| 173 | |
| 174 | | § | Title | Required fields | |
| 175 | |---|---|---| |
| 176 | | I | Brand Overview | Brand Name / Use Cases / Tone | |
| 177 | | II | Color Scheme | role / HEX / provenance (`fact` official truth \| `approx` derived) / notes | |
| 178 | | III | Typography | role / family / weight | |
| 179 | | IV | Logo | file / form / usage + clearspace and lockup rules | |
| 180 | | V | Voice & Tone | formality / person / emoji / abbreviation policy | |
| 181 | | VI | Icon Style | preference (stroke / filled / duotone …) + recommended libraries | |
| 182 | |
| 183 | **Forbidden**: canvas viewBox, page types, SVG roster — those are layout's responsibility. |
| 184 | |
| 185 | ### Style schema |
| 186 | |
| 187 | **Frontmatter** |
| 188 | |
| 189 | ```yaml |
| 190 | --- |
| 191 | style_id: <slug> |
| 192 | kind: style |
| 193 | summary: <one-line portable method and visual direction> |
| 194 | keywords: [tag1, tag2, tag3] |
| 195 | --- |
| 196 | ``` |
| 197 | |
| 198 | **Body sections** (direction/method segment) |
| 199 | |
| 200 | | § | Title | Required content | |
| 201 | |---|---|---| |
| 202 | | I | Style Overview | Name, broad best fit, reusable intent, and sources; no bound audience/outcome | |
| 203 | | II | Communication Method | Preferred mode seed, argument flow, page-message discipline, and evidence discipline | |
| 204 | | III | Page Role Vocabulary | Open roles with communication jobs, evidence obligations, and composition tendencies; no order/count | |
| 205 | | IV | Evidence & Data Expression | Claim/evidence rules, fact/assumption/implication/recommendation distinction, chart/table/source guidance | |
| 206 | | V | Visual System Defaults | Visual-style seed, composition, density, decoration, rhythm, and optional fallback palette/type defaults | |
| 207 | | VI | Image & Icon Direction | Rendering, usage, and treatment guidance without an inventory or page mapping | |
| 208 | | VII | Review Focus | Extra checks used only when the user separately enables visual review | |
| 209 | |
| 210 | Style writes no SVG and never owns official Brand identity, Deck application, |
| 211 | canvas, page count/order, Master/Layout/placeholder structure, or page-specific |
| 212 | resources. Its palette and typography values are overrideable fallbacks: |
| 213 | user-confirmed choices and Brand/Deck identity values take precedence. Review |
| 214 | Focus cannot activate visual review. `kind: style` identifies this reusable |
| 215 | package; it is distinct from the final Stage-2 `visual_style` choice and from the |
| 216 | internal `template_reuse_scope: style` flat-export value. |
| 217 | |
| 218 | ### Layout schema |
| 219 | |
| 220 | **Frontmatter** |
| 221 | |
| 222 | ```yaml |
| 223 | --- |
| 224 | layout_id: <slug> |
| 225 | kind: layout |
| 226 | category: general | scenario | government | special |
| 227 | native_structure_mode: structured |
| 228 | summary: <one-line use cases> |
| 229 | keywords: [tag1, tag2, tag3] |
| 230 | canvas_format: <ppt169 | ppt43 | a4 | ...> |
| 231 | canvas_width: <pixels> |
| 232 | canvas_height: <pixels> |
| 233 | canvas_viewbox: "0 0 <width> <height>" |
| 234 | source_canvas_width: <pixels> # when a PPTX/SVG source canvas is known |
| 235 | source_canvas_height: <pixels> |
| 236 | source_viewbox: "0 0 <width> <height>" |
| 237 | replication_mode: standard | fidelity | mirror |
| 238 | page_count: <N> |
| 239 | page_types: [<cover, toc, chapter, content, ending, ...>] |
| 240 | --- |
| 241 | ``` |
| 242 | |
| 243 | **Body sections** (package-specific structure segment) |
| 244 | |
| 245 | | § | Title | Required fields | |
| 246 | |---|---|---| |
| 247 | | IV | Signature Design Elements | Layout-specific grid, zones, image behavior, density rhythm, neutral framing, semantic text roles, alignment/wrapping/capacity behavior, and slot conventions | |
| 248 | | V | Page Roster | Every SVG file, Layout key, picker name, intended content, and slot behavior | |
| 249 | |
| 250 | `Placeholder Overrides` is conditional and appears only when the layout changes |
| 251 | the canonical authoring vocabulary. The frontmatter `summary` carries concise |
| 252 | selection context. Layouts omit the deck-only Template Overview. |
| 253 | |
| 254 | `category: scenario` is discovery fit only. A Layout may be optimized for a |
| 255 | content shape or delivery setting, but it must not prescribe the communication |
| 256 | objective, audience outcome, required narrative sequence, fixed boilerplate, |
| 257 | or example content. If those rules are reusable, create a Deck instead. |
| 258 | |
| 259 | **Forbidden**: Color Scheme, brand typeface/weight identity, final resolved type scale, brand logo, brand voice & tone, Icon Style, or official-truth color (`provenance: fact`). A Layout may retain semantic text roles, alignment, wrapping, and capacity because those are structural; neutral SVG paint/font/size values are review scaffolding only. Final color and typography are resolved in the Strategist confirmation stage or supplied by another template kind. |
| 260 | |
| 261 | ### Deck schema |
| 262 | |
| 263 | **Frontmatter** |
| 264 | |
| 265 | ```yaml |
| 266 | --- |
| 267 | deck_id: <slug> |
| 268 | kind: deck |
| 269 | category: brand | general | scenario | government | special |
| 270 | native_structure_mode: structured |
| 271 | summary: <one-line recurring presentation family and intended outcome> |
| 272 | keywords: [tag1, tag2, tag3] |
| 273 | canvas_format: <ppt169 | ...> |
| 274 | canvas_width: <pixels> |
| 275 | canvas_height: <pixels> |
| 276 | canvas_viewbox: "0 0 <width> <height>" |
| 277 | source_canvas_width: <pixels> # when a PPTX/SVG source canvas is known |
| 278 | source_canvas_height: <pixels> |
| 279 | source_viewbox: "0 0 <width> <height>" |
| 280 | replication_mode: standard | fidelity | mirror |
| 281 | page_count: <N> |
| 282 | primary_color: "<HEX>" |
| 283 | --- |
| 284 | ``` |
| 285 | |
| 286 | **Body sections** (application + integrated identity/structure) |
| 287 | |
| 288 | | § | Title | Segment | |
| 289 | |---|---|---| |
| 290 | | I | Template Overview | Application | |
| 291 | | II | Color Scheme | Identity | |
| 292 | | III | Typography | Identity; omit only when the shared default stack is used | |
| 293 | | IV | Signature Design Elements | Template-specific identity motifs and reusable structural grammar | |
| 294 | | V | Page Roster | Structure | |
| 295 | | VI | Assets | Identity/supporting assets; omit when none | |
| 296 | | VII | Placeholder Overrides | Structure vocabulary; omit when none | |
| 297 | |
| 298 | Template Overview identifies the recurring presentation family, intended |
| 299 | audiences and outcomes, delivery/reading assumptions, and representative |
| 300 | narrative or page roles. Page Roster factually describes each prototype's |
| 301 | Master/Layout/slot contract, visual character, intended role, and capacity. It |
| 302 | must not assign required/optional/repeatable or fixed/replaceable/example-only |
| 303 | policy; Strategist derives those decisions for the current content. |
| 304 | |
| 305 | Portable canvas fields, `page_count`, and the explicit SVG roster carry the |
| 306 | rest of the structure contract. General spacing, font-ratio, SVG, and |
| 307 | placeholder rules remain centralized and are not copied into each deck spec. |
| 308 | Omitted conditional sections mean “shared default or no asset”, not “another |
| 309 | kind owns this segment”. |
| 310 | |
| 311 | --- |
| 312 | |
| 313 | ## 3. The four index files |
| 314 | |
| 315 | Each index maps one-to-one with its physical directory; fields are trimmed to what Strategist actually needs to pick, following the compact "meta + summary" pattern used by [`charts_index.json`](../skills/ppt-master/templates/charts/charts_index.json) while preserving structured metadata that helps selection. |
| 316 | |
| 317 | These indexes cover library scope only. A project-root workspace is intentionally absent from all four indexes and remains usable through its explicit `projects/<name>/` path. Because both scopes use the same workspace shape, moving or copying the complete core workspace between them does not require asset-path rewriting; only library registration changes. |
| 318 | |
| 319 | ### `templates/brands/brands_index.json` |
| 320 | |
| 321 | ```json |
| 322 | { |
| 323 | "<brand_id>": { |
| 324 | "summary": "Anthropic brand identity — AI/LLM tech talks, developer conferences", |
| 325 | "primary_color": "#D97757" |
| 326 | } |
| 327 | } |
| 328 | ``` |
| 329 | |
| 330 | - Keep `primary_color` — Strategist needs the dominant color at first glance when picking a brand |
| 331 | - Drop `keywords` — summary already carries the English equivalents; AI matches via natural language (same approach as the charts library) |
| 332 | |
| 333 | ### `templates/styles/styles_index.json` |
| 334 | |
| 335 | ```json |
| 336 | { |
| 337 | "<style_id>": { |
| 338 | "summary": "Answer-first, evidence-led decision-document defaults without page prototypes or brand identity", |
| 339 | "keywords": ["consulting", "decision-support", "evidence"] |
| 340 | } |
| 341 | } |
| 342 | ``` |
| 343 | |
| 344 | - Keep `keywords` because method/direction discovery is semantic and has no structural roster to summarize |
| 345 | - Do not add canvas, page count, or primary color; Style owns neither structure nor identity truth |
| 346 | |
| 347 | ### `templates/layouts/layouts_index.json` |
| 348 | |
| 349 | ```json |
| 350 | { |
| 351 | "<layout_id>": { |
| 352 | "summary": "Standard academic defense layout — cover/toc/chapter/content/ending", |
| 353 | "canvas_format": "ppt169", |
| 354 | "page_count": 5, |
| 355 | "page_types": ["cover", "toc", "chapter", "content", "ending"] |
| 356 | } |
| 357 | } |
| 358 | ``` |
| 359 | |
| 360 | - Add `canvas_format` / `page_count` / `page_types` — Strategist needs to judge "can this skeleton hold my deck?" quickly |
| 361 | - No `primary_color` — layouts have no identity |
| 362 | |
| 363 | ### `templates/decks/decks_index.json` |
| 364 | |
| 365 | ```json |
| 366 | { |
| 367 | "<deck_id>": { |
| 368 | "summary": "China Telecom government-enterprise briefing for explaining a plan and aligning next actions", |
| 369 | "canvas_format": "ppt169", |
| 370 | "page_count": 5, |
| 371 | "primary_color": "#XXXXXX" |
| 372 | } |
| 373 | } |
| 374 | ``` |
| 375 | |
| 376 | - Includes `primary_color` (decks carry identity) + structural metadata |
| 377 | - `summary` leads with the recurring presentation family and outcome, not merely visual tone |
| 378 | - The detailed application contract stays in Template Overview; this compact index does not duplicate it |
| 379 | |
| 380 | --- |
| 381 | |
| 382 | ## 4. Multi-path fusion and conflict resolution |
| 383 | |
| 384 | ### Segment ownership (implicit dispatch) |
| 385 | |
| 386 | When Stage 1 confirms registered and/or specified workspace roots, the |
| 387 | post-confirmation apply stage parses every root's real `kind`, resolves each |
| 388 | template segment independently, and writes one |
| 389 | `<project>/templates/design_spec.md`. `library` / `explicit` records discovery |
| 390 | provenance only and never changes ownership: |
| 391 | |
| 392 | | Segment | Starting owner | |
| 393 | |---|---| |
| 394 | | Identity | Brand, otherwise Deck, otherwise unresolved until final Stage 2; Style supplies fallback candidates only | |
| 395 | | Direction / method | Style, otherwise unresolved until final Stage 2; actual Deck prototypes and Signature facts inform compatibility only | |
| 396 | | Structure | Compatible Layout, otherwise Deck, otherwise unresolved/free design until final Stage 2 | |
| 397 | | Reusable application context | Deck only; retained for final Stage-2 comparison, never used as the current project's application contract | |
| 398 | |
| 399 | Current user instructions and final confirmation override every starting |
| 400 | owner. Brand identity remains authoritative over Style palette/type fallbacks. |
| 401 | Style alone, or Style with Brand, uses flat page authoring. Style with a Layout |
| 402 | or Deck follows the selected structural source. A Style never upgrades or |
| 403 | downgrades structure by itself. |
| 404 | |
| 405 | Before applying a Layout override to a Deck, compare the Deck's reusable |
| 406 | application roles against the Layout's page roles, slot types, and capacity. |
| 407 | Before combining Style with Layout/Deck, verify that its communication method |
| 408 | and composition expectations can be realized by that reusable context and |
| 409 | structure. On mismatch, surface the conflicting template segments; do not |
| 410 | silently mix fields or retain a promise that the selected structure cannot |
| 411 | satisfy. Current-project fit begins only in final Stage 2 after Stage 1 is confirmed. |
| 412 | |
| 413 | ### Whole-segment replacement (default granularity) |
| 414 | |
| 415 | Fusion defaults to **whole-segment integer replacement** — e.g. on deck + brand, the entire Color Scheme / Typography / Logo / Voice / Icon Style five sections come from brand. **No implicit field-level mixing** (you will never get "primary from brand, secondary from deck"). |
| 416 | |
| 417 | Field-level micro-adjustment goes through the existing Strategist confirmation stage path — the user says in chat "use the anthropic brand but change primary to #FF0000", and Strategist adjusts fields e/g. Step 3 fusion does not add field-level syntax. |
| 418 | |
| 419 | ### Same-kind multiple paths = git-style conflict resolution |
| 420 | |
| 421 | User supplies `brands/anthropic` + `brands/google` (or any same-kind permutation): |
| 422 | |
| 423 | ``` |
| 424 | AI: You supplied two brands. Detected segment-level conflicts: |
| 425 | - Color Scheme (Anthropic orange-red vs Google multi-color) |
| 426 | - Typography (Styrene/AnthropicSans vs GoogleSans/Roboto) |
| 427 | - Logo (Anthropic mark vs Google mark) |
| 428 | - Voice & Tone (restrained vs friendly) |
| 429 | - Icon Style (stroke vs filled) |
| 430 | |
| 431 | (a) all from Anthropic / (b) all from Google / (c) pick per segment? |
| 432 | ``` |
| 433 | |
| 434 | Rules: |
| 435 | - No implicit ordering — every cross-source segment difference is reported as a conflict |
| 436 | - Only when the user picks `(c)` does AI walk through each segment |
| 437 | - Field-level conflict resolution is out of scope — segment-level only |
| 438 | - `style × 2`, `layout × 2`, `deck × 2`, `brand × 2` handled the same way |
| 439 | - Max two of any one kind (more than that — ask the user to converge in chat first) |
| 440 | |
| 441 | The Default template page already narrows this space: Brand/Style/Layout/Deck each have |
| 442 | one registered single-select dropdown, and one additional specified-root |
| 443 | dropdown may contribute a second workspace of its parsed kind. The server |
| 444 | enforces those limits; chat-based composition retains the general maximum of |
| 445 | two per kind. |
| 446 | |
| 447 | ### Provenance |
| 448 | |
| 449 | When fusion happens (any multi-path case), the resulting `<project>/templates/design_spec.md` carries a provenance block immediately under its H1: |
| 450 | |
| 451 | ```markdown |
| 452 | > **Fused from:** |
| 453 | > - deck: `templates/decks/中国电信/` (base) |
| 454 | > - brand: `templates/brands/anthropic/` (identity override) |
| 455 | > - style: `templates/styles/consulting_analytical/` (direction/method) |
| 456 | > - layout: `templates/layouts/presentation_core/` (structure override) |
| 457 | > - conflicts resolved: Color Scheme from anthropic (user picked a) |
| 458 | ``` |
| 459 | |
| 460 | This lets both AI and humans trace which segment came from where. |
| 461 | |
| 462 | --- |
| 463 | |
| 464 | ## 5. Relationship with Generate PPTX Stage 1 |
| 465 | |
| 466 | Default Generate [Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-candidate-preparation) |
| 467 | only prepares candidate input. Stage 1 presents the communication contract and |
| 468 | the switchable free-design/template choice together. Ordinary requests start in |
| 469 | free design with detailed controls collapsed; explicit template intent or any |
| 470 | exact root starts in template mode. Exactly one supplied root is preselected, |
| 471 | while multiple roots remain unselected candidates. A bare template/brand name |
| 472 | or style phrase never resolves to or preselects a workspace. For every selected |
| 473 | workspace, the post-confirmation apply stage resolves |
| 474 | `<workspace>/templates/design_spec.md`; for directory-shape compatibility, it |
| 475 | also accepts a legacy-flat Brand/Layout/Deck root containing |
| 476 | `<workspace>/design_spec.md` when the package satisfies its current kind |
| 477 | contract. Layout/Deck additionally require current structured SVGs; Style has |
| 478 | no flat form. Packages using legacy semantics such as |
| 479 | `native_structure_mode: template`, missing Master identity, direct atomic |
| 480 | placeholders, or distillation-era markers are rejected; `create-template` must |
| 481 | produce a new workspace before generation continues. The `kind` field decides |
| 482 | **how AI handles the selected path**: |
| 483 | |
| 484 | | User path's `kind` | Step 3 action (per-kind branch) | |
| 485 | |---|---| |
| 486 | | `kind: brand` | Map workspace `templates/` plus existing `images/` and `icons/` to the matching project peers; ignore `exports/` | |
| 487 | | `kind: style` | Install the spec-only direction/method workspace; require no SVG roster and keep generated pages flat | |
| 488 | | `kind: layout` | Map workspace `templates/` plus existing `images/` and `icons/` to the matching project peers; ignore `exports/` | |
| 489 | | `kind: deck` | Map workspace `templates/` plus existing `images/` and `icons/` to the matching project peers; ignore `exports/` | |
| 490 | | Multi-path | Fuse one `design_spec.md` per the table above, then merge the existing portable roots after resolving collisions | |
| 491 | | Same-kind multiple | Run the "git-style conflict resolution" prompt above to determine the merge | |
| 492 | |
| 493 | Bitmaps share the workspace `images/` pool and template SVGs reference them through `../images/`. If the explicit input root is already the target project's root, the apply stage consumes the workspace in place: do not copy it onto itself and do not move its assets again. Otherwise, the complete core workspace is portable: it may be copied from a project root to a library root, from the library to a project, or reused from another workspace without changing its internal structure. Registration is the only scope-specific step. |
| 494 | |
| 495 | ### Strategist confirmation stage behavior per kind |
| 496 | |
| 497 | Installing a template does not narrow away the communication question. Stage 1 confirms the same open communication contract together with, but independently from, the template choice. The communication recommendation uses only the current request, source facts, conversation constraints, and project initialization; even template canvas is excluded. Only after Stage 1 closes and any selection is installed does final Stage 2 inspect that state and confirm the complete solution and production plan. Brand supplies identity constraints while structure stays free; Style supplies method and visual-default seeds while remaining flat; Layout exposes structural capability; Deck contributes descriptive reusable application context for comparison, not the current project's contract. For Style-only use, Strategist does not look for prototypes and deterministically records `template_reuse_scope: style` with flat structure. For Layout/Deck, it inspects the actual prototypes and current content, then authors one page/prototype plan and records `mirror`, `layout`, or `style` only as internal exporter values. A mirror-authored workspace therefore enables literal reuse but never forces it. Confirm UI exposes Free design / Use templates and candidate selectors, but not internal reuse/adherence fields. Planning semantics live in `references/strategist.md` and `references/strategist-template.md`; `templates/schemas/spec_lock.schema.json` owns the machine structure. |
| 498 | |
| 499 | --- |
| 500 | |
| 501 | ## 6. Relationship with routes and child workflows |
| 502 | |
| 503 | | Route or child workflow | Produces | |
| 504 | |---|---| |
| 505 | | `workflows/create-template.md` | Fixed Create Template entry and shared scope, confirmation, preflight, structured-authoring, registration, completion, and handoff contract; dispatches exactly one child workflow | |
| 506 | | `workflows/create-template/create-brand.md` | Identity-only Brand workspace; no SVG roster and empty optional directories are omitted | |
| 507 | | `workflows/create-template/create-style.md` | Direction/method-only Style workspace; no SVG roster, identity truth, application contract, native structure, or preview PPTX | |
| 508 | | `workflows/create-template/create-layout.md` | Brand-neutral structural Layout workspace with a structured SVG roster | |
| 509 | | `workflows/create-template/create-deck.md` | Recurring application contract with integrated identity/structure and a structured SVG roster; selected when the reusable artifact is branded or scenario-bearing, not merely because the source is a complete PPTX | |
| 510 | |
| 511 | In library scope, the frontmatter `kind` field determines which workspace parent is used under `templates/brands/` / `templates/styles/` / `templates/layouts/` / `templates/decks/`. Project scope keeps the same kind semantics at the project workspace root. A complete workspace may move between scopes without reshaping; add or remove only the library index registration. |
| 512 | |
| 513 | --- |
| 514 | |
| 515 | ## 7. Non-goals (rejection list paired with this framing) |
| 516 | |
| 517 | - **No field-level override syntax in the fusion layer** — field-level adjustment uses the existing Strategist confirmation stage path |
| 518 | - **No batch conflict resolution for three or more of the same kind** — ask the user to narrow it down in chat first |
| 519 | - **No bilingual name mapping table** — templates are named in their brand / scenario's native language (Chinese templates use Chinese names; English templates use snake_case); no forced unification |
| 520 | - **No output-scope structure fork or CLI flag** — output scope is a `create-template` brief decision; both layout/deck scopes declare `native_structure_mode: structured`, while Brand/Style remain roster-free |
| 521 | - **No Theme kind** — Theme projects resolved identity from Brand, Deck, or the current project; Style fallback values are not identity truth |
| 522 | - **No automatic visual review from Style** — Review Focus supplements an already-enabled review pass and never triggers it |
| 523 | - **No automatic promotion of Brand + Layout into a reusable library Deck** — the composition may route as a project-local deck-capability bundle, while a reusable Deck still requires an application contract |
| 524 |