| 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 installation + segment-ownership 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 | Each installed spec keeps its own `kind` and id; there is no merged project spec and no combined capability label. The routing consequence is derived while reading: structure comes from an installed Layout or Deck, identity from an installed Brand or Deck, direction from an installed Style. A project-local Brand + Layout pair therefore has both capabilities installed without being promoted into a reusable library Deck or inventing 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-decision/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 Design Spec and every real destination. Library scope requires an empty `templates/` root. Project scope requires an initialized project and rejects a bare spec, a same-kind spec, or invalid qualified naming; distinct kinds may coexist. Adding Deck beside Layout preserves the Layout roster, while adding Layout beside Deck uses isolated validation and an atomic structural replacement. Both scopes reject unrelated asset and preview collisions before writing. Never leave partial output. |
| 118 | |
| 119 | ### Segment partition |
| 120 | |
| 121 | To make multi-path ownership resolve cleanly, every field belongs to a named segment. **A resolved segment is applied whole**: |
| 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 of these four indexes maps one-to-one with its physical directory, and its fields are trimmed to what Strategist needs to select a reusable workspace. Visualization uses a separate boundary: planning reads the objective [`chart-vocabulary.md`](../skills/ppt-master/templates/charts/chart-vocabulary.md) and [`table-vocabulary.md`](../skills/ppt-master/templates/tables/table-vocabulary.md), while [`charts_index.json`](../skills/ppt-master/templates/charts/charts_index.json) and [`tables_index.json`](../skills/ppt-master/templates/tables/tables_index.json) remain machine registries. Qualitative Structure has no index because Executor generates it from page relationships. |
| 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 installation and segment ownership |
| 383 | |
| 384 | ### Installation copies; it never merges |
| 385 | |
| 386 | When Stage 1 confirms registered and/or specified workspace roots, the |
| 387 | post-confirmation apply stage parses every root's real `kind` and installs each |
| 388 | selected workspace as **its own** project-local file: |
| 389 | |
| 390 | ``` |
| 391 | <project>/templates/design_spec.brand.mckinsey.md |
| 392 | <project>/templates/design_spec.style.consulting-decision.md |
| 393 | <project>/templates/design_spec.layout.presentation_core.md |
| 394 | ``` |
| 395 | |
| 396 | The body of each file is copied unchanged; only one provenance line is |
| 397 | prepended under its H1: |
| 398 | |
| 399 | ```markdown |
| 400 | > **Installed from**: `skills/ppt-master/templates/brands/mckinsey/` (library) |
| 401 | ``` |
| 402 | |
| 403 | There is no merged project spec and no combined capability label. A bare |
| 404 | `<project>/templates/design_spec.md` is the older single-kind shape: that |
| 405 | project is itself one workspace and is never consumed as an installed template. |
| 406 | Current project-scope Create Template writes the kind-qualified name instead, so |
| 407 | the two shapes never share one directory — mixing them is rejected rather than |
| 408 | silently resolved. |
| 409 | |
| 410 | `library` / `explicit` records discovery provenance only and never changes |
| 411 | ownership. |
| 412 | |
| 413 | ### Segment ownership is resolved while reading |
| 414 | |
| 415 | The consuming role — Default final Stage 2, or Quick's agent before authoring — |
| 416 | reads every installed spec and resolves these segments in context: |
| 417 | |
| 418 | | Segment | Starting owner | |
| 419 | |---|---| |
| 420 | | Identity | Brand, otherwise Deck, otherwise unresolved until final Stage 2; Style supplies fallback candidates only | |
| 421 | | Direction / method | Style, otherwise unresolved until final Stage 2; actual Deck prototypes and Signature facts inform compatibility only | |
| 422 | | Structure | Layout when present, otherwise Deck, otherwise unresolved/free design until final Stage 2 | |
| 423 | | Reusable application context | Deck only; retained for final Stage-2 comparison, never used as the current project's application contract | |
| 424 | |
| 425 | Current user instructions and final confirmation override every starting |
| 426 | owner. Brand identity remains authoritative over Style palette/type fallbacks. |
| 427 | Style alone, or Style with Brand, uses flat page authoring. Style with a Layout |
| 428 | or Deck follows the selected structural source. A Style never upgrades or |
| 429 | downgrades structure by itself. |
| 430 | |
| 431 | **An owned segment governs visual weight, not only values.** When a segment |
| 432 | owner declares that a value should dominate, recede, or stay rare, that |
| 433 | instruction carries the same authority as the value itself — a Style's |
| 434 | whitespace or composition tendency never demotes a Brand's declared dominant |
| 435 | color into an incidental accent. |
| 436 | |
| 437 | Before combining Style with Layout/Deck, verify that its communication method |
| 438 | and composition expectations can be realized by that reusable context and |
| 439 | structure. On mismatch, surface the conflicting template segments; do not |
| 440 | silently mix fields or retain a promise that the selected structure cannot |
| 441 | satisfy. Current-project fit begins only in final Stage 2 after Stage 1 is confirmed. |
| 442 | |
| 443 | ### Whole-segment application (default granularity) |
| 444 | |
| 445 | A resolved segment is applied **whole** — e.g. on deck + brand, the entire |
| 446 | Color Scheme / Typography / Logo / Voice / Icon Style set comes from brand. |
| 447 | **No implicit field-level mixing** (you will never get "primary from brand, |
| 448 | secondary from deck"). |
| 449 | |
| 450 | Field-level micro-adjustment goes through the existing Strategist confirmation |
| 451 | stage path — the user says in chat "use the anthropic brand but change primary |
| 452 | to #FF0000", and Strategist adjusts fields e/g. Installation adds no |
| 453 | field-level syntax. |
| 454 | |
| 455 | ### Selection conflicts |
| 456 | |
| 457 | The complete selection contains at most one contribution per kind. Layout and |
| 458 | Deck may coexist; Layout owns structure. A specified multi-kind root is atomic |
| 459 | and may coexist only with registered roots of non-overlapping kinds. Default rejects conflicts in the |
| 460 | Stage-1 selector and server receipt; Quick requires a narrower exact-root set |
| 461 | in chat. Installation never averages same-kind specs or chooses by path order. |
| 462 | |
| 463 | ### Traceability |
| 464 | |
| 465 | Because nothing is merged, the installed set is self-describing: the file name |
| 466 | carries kind and id, the provenance line carries the source root, and the |
| 467 | remaining body is unchanged. Tracing which segment came from where is a |
| 468 | directory listing, not a merge reconstruction. |
| 469 | |
| 470 | --- |
| 471 | |
| 472 | ## 5. Relationship with Generate PPTX Stage 1 |
| 473 | |
| 474 | Default Generate [Step 3](../skills/ppt-master/workflows/generate-pptx.md#step-3-template-candidate-preparation) |
| 475 | only prepares candidate input. Stage 1 presents the communication contract and |
| 476 | the switchable free-design/template choice together. Ordinary requests start in |
| 477 | free design with detailed controls collapsed; explicit template intent or any |
| 478 | exact root starts in template mode. Exactly one supplied root is preselected, |
| 479 | while multiple roots remain unselected candidates. A bare template/brand name |
| 480 | or style phrase never resolves to or preselects a workspace. For every selected |
| 481 | root, the post-confirmation apply stage resolves either one library bare spec or |
| 482 | all project-qualified specs; for directory-shape compatibility, it also accepts |
| 483 | a legacy-flat Brand/Layout/Deck root containing |
| 484 | `<workspace>/design_spec.md` when the package satisfies its current kind |
| 485 | contract. Layout/Deck additionally require current structured SVGs; Style has |
| 486 | no flat form. Packages using legacy semantics such as |
| 487 | `native_structure_mode: template`, missing Master identity, direct atomic |
| 488 | placeholders, or distillation-era markers are rejected; `create-template` must |
| 489 | produce a new workspace before generation continues. The `kind` field decides |
| 490 | **how AI handles the selected path**: |
| 491 | |
| 492 | | User path's `kind` | Step 3 action (per-kind branch) | |
| 493 | |---|---| |
| 494 | | `kind: brand` | Install the qualified identity spec and root-owned assets; structure remains free unless the set also contains Layout or Deck | |
| 495 | | `kind: style` | Install the qualified direction/method spec; require no Style-owned roster or assets and keep generated pages flat unless the set contains Layout or Deck | |
| 496 | | `kind: layout` | Install the qualified structure spec plus its root's SVG roster and assets; it takes structural precedence over Deck | |
| 497 | | `kind: deck` | Install the qualified application/identity/structure spec and assets; install its SVG roster only when no Layout is selected | |
| 498 | | Multi-kind root | Preserve every qualified spec and map shared assets once; keep exactly the effective Layout-or-Deck roster | |
| 499 | | Selection conflict | Reject duplicate kinds before installation | |
| 500 | |
| 501 | 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, a project root is directly reusable by another project. Moving one contribution into the library keeps its spec body but changes placement from a qualified project filename to the bare spec inside a single-kind library workspace, followed by registration. |
| 502 | |
| 503 | ### Strategist confirmation stage behavior per kind |
| 504 | |
| 505 | 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. It otherwise inspects the effective prototypes—Layout when present, otherwise Deck—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. |
| 506 | |
| 507 | --- |
| 508 | |
| 509 | ## 6. Relationship with routes and child workflows |
| 510 | |
| 511 | | Route or child workflow | Produces | |
| 512 | |---|---| |
| 513 | | `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 | |
| 514 | | `workflows/create-template/create-brand.md` | Identity-only Brand workspace; no SVG roster and empty optional directories are omitted | |
| 515 | | `workflows/create-template/create-style.md` | Direction/method-only Style workspace; no SVG roster, identity truth, application contract, native structure, or preview PPTX | |
| 516 | | `workflows/create-template/create-layout.md` | Brand-neutral structural Layout workspace with a structured SVG roster | |
| 517 | | `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 | |
| 518 | |
| 519 | **One schema, two landing points.** Templates are a single contract that lands at two layers, and the only difference is what names the Design Spec: |
| 520 | |
| 521 | | Layer | Container | Design Spec | |
| 522 | |---|---|---| |
| 523 | | Skill library | `templates/<kind_dir>/<template_id>/` already names the kind and id | `templates/design_spec.md` | |
| 524 | | Project | one flat `templates/` shared across kinds | `templates/design_spec.<kind>.<id>.md` | |
| 525 | |
| 526 | The container disambiguates, and the filename carries only what the container cannot. A project root therefore holds at most one spec per kind while all four kinds may coexist, and each filename kind/id must match frontmatter `kind` and the matching `<kind>_id`; the bare and qualified shapes never mix in one directory. One `templates/` carries one active SVG roster: Layout when present, otherwise Deck. Deck's other segments remain installed when its structural roster is shadowed. Because the schema itself does not change with the layer, a project spec needs no field added to enter the library and none removed to leave it, and an installed spec is indistinguishable from one authored in place. |
| 527 | |
| 528 | Selection follows the same principle: the unit is the workspace **root**, not the kind. A root contributes every kind it exposes, so pointing at a project that holds a Brand plus a Style applies both. Browsing the library by kind is only a way to find a root — `library` and `explicit` record how a root was discovered, never what it owns. |
| 529 | |
| 530 | 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. Project-to-project reuse preserves the complete root. Moving one contribution into or out of the single-kind library preserves its spec schema and assets but changes the spec filename placement and index registration. |
| 531 | |
| 532 | --- |
| 533 | |
| 534 | ## 7. Non-goals (rejection list paired with this framing) |
| 535 | |
| 536 | - **No field-level override syntax in the installation layer** — field-level adjustment uses the existing Strategist confirmation stage path |
| 537 | - **No duplicate-kind selection** — narrow the chosen roots before installation; Layout plus Deck is resolved by structural precedence |
| 538 | - **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 |
| 539 | - **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 |
| 540 | - **No Theme kind** — Theme projects resolved identity from Brand, Deck, or the current project; Style fallback values are not identity truth |
| 541 | - **No automatic visual review from Style** — Review Focus supplements an already-enabled review pass and never triggers it |
| 542 | - **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 |
| 543 |