@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/templates/artist-log.template.md

@@ -0,0 +1,182 @@
+# Artist Log
+
+## Delivery Summary
+
+- **Planned outputs**: {{planned_outputs}}
+- **Completed outputs**: {{completed_outputs}}
+- **Skipped / reused**: {{skipped_or_reused}}
+- **Blocked items**: {{blocked_items}}
+
+## Per-Output Record
+
+### {{output_name}} — {{purpose_or_contract_id}}
+
+- **Category**: {{MC / ASR / BGM / SFX / digit_strip / supplementary_reference}}
+- **Method**: {{AI generation / reuse / manual}}
+- **Model**: {{model_name_if_generated}}
+- **Prompt**: {{full_generation_prompt}}
+- **Output path**: {{file_path}}
+- **Dimensions/Size**: {{WxH, file_size}}
+- **Post-processing**: {{resize/crop/compress steps if any}}
+- **Recipe Record**:
+  | Field | Value |
+  |-------|-------|
+  | Prompt | {{full_generation_prompt}} |
+  | Model | {{model_name}} |
+  | Seed | {{seed_if_applicable}} |
+  | Reference Image | {{reference_image_path_or_none}} |
+  | Aspect Ratio | {{aspect_ratio}} |
+  | Style Constraint | {{style_keywords}} |
+  | Generation Time | {{seconds}} |
+- **Consistency check**: {{how this output relates to the rest of the visual/audio direction}}
+- **Style Intent Notes** (供 TA 补全时参考):
+  - 主色调：{{dominant color and why}}
+  - 光影方向：{{light source direction and quality}}
+  - 边缘处理：{{hard/soft/outline style}}
+  - 质感特征：{{matte/glossy/textured}}
+  - 与整体概念图的关系：{{how this element fits the full mockup}}
+- **Anti-Pattern Notes** (明确告诉 TA 不要做什么):
+  - 不要：{{specific style choice to avoid}}
+  - 不要：{{another anti-pattern}}
+- **Reference Usage Guide** (告诉 TA 这个样本怎么用):
+  - 适用元素类型：{{which element types this sample can guide}}
+  - 不适用元素类型：{{which types should NOT use this reference}}
+  - 需要额外注意的属性：{{e.g., "UI 元素需要更高对比度，不能直接用 tile 的柔和处理"}}
+
+<!--
+Repeat this section for each meaningful output.
+Fill in details as you complete each one.
+-->
+
+## Image Production Preflight (ring 3 build — ASR)
+
+> **Mandatory before MC/ASR generation and before ring 3 verify STOP.** Read all three Skills; record key decisions.
+
+| Skill / Check               | 已读 | 关键决策摘要                                             |
+| --------------------------- | ---- | -------------------------------------------------------- |
+| playcraft-storyboard        | ☐    | MC 45:16 · model whitelist · Panel 1 all element types   |
+| playcraft-asset-state-sheet | ☐    | ASR grid · isolated cells · sheet #808080 · cell chroma  |
+| playcraft-image-generation  | ☐    | §3 chroma matrix · §3.1 ASR branch · no remove-bg on ASR |
+
+<!--
+  MUST be filled before generating ASR (Step 4) and before ring 3 verify STOP.
+  Hook validate-workflow-stop enforces this section when iteration >= 3 and loop is build or verify.
+-->
+
+## ASR Coverage Matrix (designer-handoff-v2 — 100% contract rows)
+
+> UI: `assets/images/reference/ui_state_sheet_{{option}}.png`  
+> Element: `assets/images/reference/element_state_sheet_{{option}}.png`
+
+### Sheet grid metadata (供 TA crop 计算)
+
+| Sheet                                  | Total rows    | Total cols | Cell W×H (px) | Cell padding (px) | Origin            |
+| -------------------------------------- | ------------- | ---------- | ------------- | ----------------- | ----------------- |
+| `ui_state_sheet_{{option}}.png`        | 2             | 4          | 800×800       | 80                | top-left (R1, C1) |
+| `element_state_sheet_{{option}}.png`   | 2             | 4          | 800×800       | 80                | top-left (R1, C1) |
+| `element_state_sheet_{{option}}_2.png` | (if overflow) |            |               |                   |                   |
+
+<!--
+Grid coordinates use 1-based indexing, row-major.
+Cell W×H = visible cell area (without padding). Padding = margin between cells AND outer margin.
+Pixel coordinates of cell (R, C):
+  x = (C - 1) × (cellW + padding) + padding
+  y = (R - 1) × (cellH + padding) + padding
+TA uses these for `playcraft image crop --x ... --y ... --width cellW --height cellH`.
+-->
+
+### Coverage
+
+| Contract id                      | elementType | Type   | CoverageLayer                 | ASR sheet    | Grid (row,col) | State(s)    | TA extends? |
+| -------------------------------- | ----------- | ------ | ----------------------------- | ------------ | -------------- | ----------- | ----------- |
+| {{element_id_from_assetMapping}} | {{type}}    | visual | on-asr / mc-crop / ta-extends | ui / element | {{R1C1}}       | {{default}} | {{yes/no}}  |
+| {{static_text_id}}               | —           | text   | mc-crop or on-asr             | ui / MC-crop | —              | baked       | {{yes/no}}  |
+
+<!--
+One row per layout-spec assetMapping elementId and per static text id.
+CoverageLayer:
+  on-asr     — physical slot on ASR PNG; Grid required
+  mc-crop    — MC Panel 1 only; ASR sheet = MC-crop
+  ta-extends — variant/extra states; TA extends? = yes + Style Intent note
+
+Type rule: each distinct elementType must have ≥1 row with on-asr OR mc-crop.
+Grid syntax: R{row}C{col}, e.g. R1C2, 1-based, row-major.
+
+This table is for TA crop/reference understanding and for downstream precedent notes.
+Do not mirror it into `atom-tree.json` as execution fields in the simplified manifest model.
+-->
+
+## Palette Locked (from MC option {{option}})
+
+| Role          | Hex         | Notes |
+| ------------- | ----------- | ----- |
+| bg_primary    | {{#______}} |       |
+| accent        | {{#______}} |       |
+| cta           | {{#______}} |       |
+| {{element_1}} | {{#______}} |       |
+
+**Delta vs layout-spec Color Palette**: {{match | Game Designer update: one line}}
+
+## Skill Preflight (Phase 2)
+
+> **Mandatory before audio/digit production.** Read relevant Skills + check mediaGroups.
+
+| Skill / Check              | 已读 | 关键决策摘要                                  |
+| -------------------------- | ---- | --------------------------------------------- |
+| playcraft-audio-generation | ☐    | {{BGM mood, SFX prompt pattern, loop config}} |
+| playcraft-text-rendering   | ☐    | {{digit strip chroma strategy, font style}}   |
+| playcraft-image-generation | ☐    | {{background decision for digit strip}}       |
+| mediaGroups (.aiaudio)     | ☐    | {{linked: X, skipped: Y, reason: Z}}          |
+
+<!--
+  MUST be filled before generating any audio or digit strip in Phase 2.
+  mediaGroups: list each .aiaudio match disposition (linked/skipped + reason).
+-->
+
+## mediaGroups Reuse (Phase 2)
+
+> **Mandatory before any audio generation.** Filter `atom-tree.json` → `meta.skillsMatch.mediaGroups` by `extension`; Artist is responsible for **`.aiaudio` only** (TA handles `.aiimage` / `.aisprite`).
+
+| mediaGroup atomId | extension | Matches Artist atom? | Disposition   | Reason (if skipped)                | Output path (if linked) |
+| ----------------- | --------- | -------------------- | ------------- | ---------------------------------- | ----------------------- |
+| {{mg_atomId}}     | .aiaudio  | {{atom_id / —}}      | linked / skip | {{mood mismatch / wrong loop / —}} | {{path / —}}            |
+
+<!--
+  Artist scope (this table):
+    .aiaudio — BGM / SFX bundles → link or skip (with reason)
+
+  Out of Artist scope (do NOT fill rows for these — TA owns them):
+    .aiimage  — single-shot image atoms
+    .aisprite — sprite-sheet atoms (multi-frame)
+    .aigameplay / .aiconfig — Developer reads via skillRef
+
+  Filter command:
+    cat docs/atom-tree.json | jq '.meta.skillsMatch.mediaGroups[] | select(.extension == ".aiaudio")'
+
+  Disposition rules:
+    linked → playcraft skills link → verify mood matches MC → status: done
+    skip   → quality / mood / loop mismatch → document reason → generate from scratch
+-->
+
+## Style Consistency Self-Check
+
+- [ ] All visual assets share the same art style?
+- [ ] Color temperature consistent with layout-spec palette?
+- [ ] Audio mood matches visual atmosphere?
+- [ ] File naming matches asset-mapping exactly?
+- [ ] All assets within size budget?
+
+## Size Budget Tracking
+
+| Asset          | Budget       | Actual          | Status      |
+| -------------- | ------------ | --------------- | ----------- |
+| {{asset_name}} | {{max_size}} | {{actual_size}} | {{ok/over}} |
+
+<!--
+Total project budget: <= 5MB
+Individual budgets:
+- Background: < 500KB
+- Tile/icon: < 100KB
+- BGM: < 300KB
+- SFX: < 50KB
+-->

package/project-templates/phaser/templates/atom-tree.template.json

@@ -0,0 +1,133 @@
+{
+  "meta": {
+    "atomTreeSchemaVersion": 1,
+    "title": "",
+    "idea": "",
+    "gate": 1,
+    "engineDecision": {
+      "mode": "unset",
+      "engine": null,
+      "engineAtom": null,
+      "adapter": null,
+      "reason": "Run playcraft skills init-atom-tree after intent is known.",
+      "runtimeContract": "window.__playable"
+    },
+    "skillsMatch": {
+      "engine": null,
+      "engineSource": "none",
+      "intent": [],
+      "items": [],
+      "mediaGroups": []
+    },
+    "selectedAtoms": [],
+    "compactSelectionNoMatchReason": "",
+    "activatedSlices": [],
+    "sliceQueueNote": "Slice-axis: run playcraft skills match before seeding sliceState. Write meta.skillsMatch snapshot + a few meta.selectedAtoms (compact refs, not full graph). Each developer slice must cite skillRefs/skillUse or fromScratchReason. activatedSlices lists sliceIds driving dispatch — Ring 1: 1–3; Ring 2: 2–4 periphery ids.",
+    "selectionRevisions": [
+      {
+        "version": "1.0",
+        "date": "1970-01-01",
+        "changes": "Initial unset skeleton from template",
+        "author": "template"
+      }
+    ],
+    "rings": {
+      "1": {
+        "goal": "first playable loop",
+        "requiredPaths": ["engine"],
+        "verifiers": ["contract", "lifecycle", "firstLevelWin", "placeholders"],
+        "acceptanceKeys": ["contract", "lifecycle", "firstLevelWin", "placeholders"]
+      },
+      "2": {
+        "goal": "gameplay + periphery",
+        "requiredPaths": ["engine"],
+        "verifiers": [
+          "contract",
+          "lifecycle",
+          "firstLevelWin",
+          "oneClickEndcard",
+          "verifyUi",
+          "fullPlaythrough",
+          "placeholders"
+        ],
+        "acceptanceKeys": [
+          "contract",
+          "lifecycle",
+          "firstLevelWin",
+          "oneClickEndcard",
+          "verifyUi",
+          "fullPlaythrough",
+          "placeholders"
+        ]
+      },
+      "3": {
+        "goal": "playable ad hook/CTA",
+        "requiredPaths": ["engine"],
+        "verifiers": [
+          "contract",
+          "lifecycle",
+          "firstLevelWin",
+          "oneClickEndcard",
+          "verifyUi",
+          "fullPlaythrough",
+          "hookCta",
+          "placeholders"
+        ],
+        "acceptanceKeys": [
+          "contract",
+          "lifecycle",
+          "firstLevelWin",
+          "oneClickEndcard",
+          "verifyUi",
+          "fullPlaythrough",
+          "hookCta",
+          "placeholders"
+        ]
+      },
+      "4": {
+        "goal": "production + architecture",
+        "requiredPaths": ["engine"],
+        "verifiers": [
+          "contract",
+          "lifecycle",
+          "firstLevelWin",
+          "oneClickEndcard",
+          "verifyUi",
+          "fullPlaythrough",
+          "hookCta",
+          "uiDiff",
+          "visualDiff",
+          "bgClean",
+          "tileConsistency",
+          "textOverlap",
+          "assetBudget",
+          "assetCodeSync",
+          "atomConformance",
+          "fusion"
+        ],
+        "acceptanceKeys": [
+          "contract",
+          "lifecycle",
+          "firstLevelWin",
+          "oneClickEndcard",
+          "verifyUi",
+          "fullPlaythrough",
+          "hookCta",
+          "uiDiff",
+          "visualDiff",
+          "bgClean",
+          "tileConsistency",
+          "textOverlap",
+          "assetBudget",
+          "assetCodeSync",
+          "atomConformance",
+          "fusion"
+        ]
+      }
+    }
+  },
+  "engine": { "atom": null },
+  "globals": {},
+  "scenes": [],
+  "review": {}
+}

package/project-templates/phaser/templates/design-brief.template.md

@@ -0,0 +1,92 @@
+# {Game Name} — Progressive Discovery Brief
+
+<!--
+  Living discovery log — NOT a substitute for docs/DESIGN.md (the playable seed contract).
+
+  Ring 1 (slice-axis):
+  - Record how core action / feedback / progress / constraints were discovered.
+  - Feed the minimal slice queue; do NOT write layout, style, CTA polish, or production plans here.
+
+  Rings 2–4:
+  - Deepen periphery, layout intent, Hook/CTA, style direction as those rings disclose.
+  - Ring 2 (slice-axis): append periphery discovery → 2–4 developer slices; not a feature backlog.
+
+  Update rules:
+  - Create at the start of clarify; append after each brainstorm round.
+  - Preserve source tags; do not polish away evidence.
+
+  Source tags: [USER] [WEB] [SKILL] [AGENT] [ASSUMPTION][confidence: high/medium/low]
+
+  Forbidden here:
+  - Gate / handoff / workflow state
+  - implementation plans, API names, file paths
+  - MC / ASR production notes (Artist/TA logs)
+-->
+
+**Created**: {YYYY-MM-DD}
+**Last Updated**: {YYYY-MM-DD HH:mm}
+**Purpose**: Progressive discovery → slice queue + DESIGN seed
+
+---
+
+## Discovery Status
+
+### Clear enough to slice
+
+- Core action: {one line} [{SOURCE}]
+- Immediate feedback: {one line} [{SOURCE}]
+- Progress signal (3–5 actions): {one line} [{SOURCE}]
+- First-win constraint: {one line} [{SOURCE}]
+
+### Still open
+
+- {ambiguous point to clarify next} [{SOURCE}]
+
+---
+
+## Discovery Feed
+
+Append-only evidence (newest first or chronological — pick one and stay consistent).
+
+- {YYYY-MM-DD HH:mm} [USER] {what the user confirmed}
+- {YYYY-MM-DD HH:mm} [AGENT] {synthesis or hypothesis}
+- {YYYY-MM-DD HH:mm} [ASSUMPTION][confidence: medium] {inference not yet confirmed}
+
+---
+
+## Brainstorm Log
+
+### Round 1
+
+- Asked: {question and why it mattered for core action / feedback}
+- Answer: [USER] {response}
+- Impact: {what changed in DESIGN.md or slice queue intent}
+
+---
+
+## Core Discovery (Ring 1 scope)
+
+> Full Hook / Tutorial / Gameplay / End Card packaging is **Ring 2+**. Ring 1 only needs enough to seed verifiable developer slices.
+
+### Player action chain
+
+- First action: {…} [{SOURCE}]
+- System response within ~100ms: {…} [{SOURCE}]
+- Progress after 3–5 actions: {…} [{SOURCE}]
+
+### Constraints
+
+- Engine hint basis: {phaser / threejs + why} [{SOURCE}]
+- Semantic placeholders: {player; target; feedback; reward; …} [{SOURCE}]
+- Out of scope for Ring 1: layout zones, style direction, CTA copy, asset production
+
+---
+
+## Quality check (Ring 1)
+
+- [ ] Core action is explicit, not implied
+- [ ] Feedback timing is stated
+- [ ] Progress signal is countable (3–5 steps)
+- [ ] First-win guarantee is described
+- [ ] Important claims have source tags
+- [ ] This file reads like discovery in progress, not a post-hoc essay

package/project-templates/phaser/templates/design-lens-checklist.reference.md

@@ -0,0 +1,117 @@
+# Design Lens Checklist
+
+> **Used by**: Reviewer Agent — after the five-dimension evaluation (mechanic / dimension / interaction / narrative / emotional arc),
+> apply these 8 design lenses for a quality audit of the design-brief.
+>
+> **Source**: Jesse Schell's _The Art of Game Design_ core lenses, streamlined and adapted for playable ads.
+>
+> Each lens is a set of concrete questions — not a score, but forced thinking.
+> If 2+ lenses have "❌ No" answers, Reviewer should flag specific design-brief items for Game Designer revision.
+
+---
+
+## Lens 1 — The Essential Experience
+
+> "Is every mechanic serving that one core feeling?"
+
+- [ ] What feeling should the user carry away when the ad ends? (fill in: \_\_\_)
+- [ ] Does the design-brief's Emotional Arc clearly describe this feeling?
+- [ ] Is every design decision in Hook / Gameplay / EndCard reinforcing this core feeling?
+- [ ] Is any design element "consuming time" without serving the core feeling?
+
+---
+
+## Lens 2 — The Toy
+
+> "Is the basic interaction inherently satisfying, even without goals?"
+
+- [ ] Does the base operation (eliminate/tap/drag) come with inherently pleasing instant feedback (visual + audio)?
+- [ ] During the first interaction (Tutorial), does the user feel satisfied by the action itself, not just the goal?
+- [ ] Does the element design (size, animation, sound) make users want to tap/interact more?
+- [ ] If all game rules and win/lose conditions were removed, leaving only interaction feedback — is it still fun?
+
+---
+
+## Lens 3 — Curiosity
+
+> "Is the user continuously drawn to find out what's next?"
+
+- [ ] Does the Hook successfully open a cognitive gap ("What is this? What happens next?")?
+- [ ] At Tutorial end, does the user want to know "what does it feel like one level harder?"
+- [ ] During Gameplay, are there continuous small surprises (new mechanic / effects / near-win) to sustain curiosity?
+- [ ] Does the EndCard leave "there's more to explore" suspense (cognitive gap NOT closed)?
+
+---
+
+## Lens 4 — The Hook
+
+> "What makes the user start and stay for 30s? Is the reason consistent?"
+
+- [ ] Do the first 3s have a strong enough stimulus to stop the user from scrolling?
+- [ ] Is this stimulus related to the product/game's core value (not pure clickbait)?
+- [ ] From Hook → Tutorial → Gameplay, is the main thread (core conflict or goal) consistent?
+- [ ] After completing Tutorial, does the user understand "why do I want to win?"
+
+---
+
+## Lens 5 — Skill
+
+> "Does a zero-skill user succeed on first try? Is the flow zone reasonable?"
+
+- [ ] Does the Tutorial design guarantee zero-skill users succeed on the very first interaction?
+- [ ] Is the difficulty of the first 3 interactions at the flow zone lower bound (success rate ≥ 95%)?
+- [ ] Is the difficulty ramp reasonable (no more than 1 new challenge per 5s)?
+- [ ] Is the Near-Win difficulty designed as "solvable, not unsolvable"? (avoid frustration)
+
+---
+
+## Lens 6 — The Near Win
+
+> "Is a near-win moment deliberately designed? Does the scenario have a solution?"
+
+- [ ] Does the design-brief's Gameplay stage explicitly describe the Near-Win design (which step / what scenario)?
+- [ ] Does the Near-Win scenario have a clear solution (player can see the "just one more step" path)?
+- [ ] Is the Near-Win duration appropriate (≤ 5s, to avoid turning into frustration)?
+- [ ] After Near-Win resolution, is there sufficient emotional peak reinforcement (effects / audio / animation)?
+
+---
+
+## Lens 7 — Emotion
+
+> "Does each mechanic trigger the intended emotion? Aligned with the overall arc?"
+
+- [ ] Does the selected Emotional Arc (Competence / Challenge / Curiosity / Relaxation / Urgency) match the User Motivation Job (JTBD)?
+- [ ] Is the emotion triggered by the Hook consistent with the arc's starting point?
+- [ ] Do Gameplay emotions form a complete arc (starting point → peak → landing), not a flat line?
+- [ ] Is the EndCard emotion a combination of "satisfaction + incompleteness", not an abrupt ending?
+- [ ] Does any mechanic trigger unintended negative emotions (frustration / confusion / boredom)?
+
+---
+
+## Lens 8 — The Memorable Moment
+
+> "What will the user remember 10 minutes later?"
+
+- [ ] Is there 1 sufficiently unique visual/mechanic moment in the 30s experience that the user can describe 10 minutes later?
+- [ ] Does this memorable moment occur at the emotional peak (typically Near-Win or EndCard)?
+- [ ] Is this memorable moment related to the promoted product's core value (user can associate memory with install motivation)?
+- [ ] Does the design avoid "too many highlights so nothing is remembered" (focus on 1-2 peak moments)?
+
+---
+
+## Summary
+
+| Lens                   | Pass ✅ | Needs Work ❌ | Key Issue |
+| ---------------------- | ------- | ------------- | --------- |
+| 1 Essential Experience |         |               |           |
+| 2 The Toy              |         |               |           |
+| 3 Curiosity            |         |               |           |
+| 4 The Hook             |         |               |           |
+| 5 Skill                |         |               |           |
+| 6 The Near Win         |         |               |           |
+| 7 Emotion              |         |               |           |
+| 8 Memorable Moment     |         |               |           |
+
+**Reviewer Conclusion**: {{overall_assessment}}
+
+<!-- If any ❌: list specific design-brief items that Game Designer should revise -->

package/project-templates/phaser/templates/design-methodology.md

@@ -0,0 +1,99 @@
+# Design Methodology Foundations
+
+> **When to read**: Game Designer reads this before Step 4 (Five-Axis Evaluation) to ground decisions in theory.
+> Artist and Reviewer may also reference this for context on emotional intent.
+
+---
+
+## A. MDA Framework (Mechanics-Dynamics-Aesthetics)
+
+Core insight: **designers build upward from mechanics; players experience downward from emotion** — opposite starting points.
+
+```
+Game Designer's perspective (build direction):  Mechanics → Dynamics → Aesthetics
+Player's perspective (experience direction): Aesthetics ← Dynamics ← Mechanics
+```
+
+8 Aesthetics emotion types (starred = most relevant to playable ads):
+
+| Relevance | Aesthetic      | Role in Playable Ads                                              |
+| --------- | -------------- | ----------------------------------------------------------------- |
+| ★★★★★     | **Sensation**  | Visual juice + audio feedback — the baseline for every ad         |
+| ★★★★★     | **Challenge**  | Theoretical basis for Near-Win design; drives "one more try"      |
+| ★★★★      | **Submission** | Healing/relaxing emotion in casual ads; low-pressure flow         |
+| ★★★       | **Discovery**  | The "aha, that's how it works!" moment; core of the Curiosity Arc |
+| ★★        | Fellowship     | Social proof in ad context (rarely applicable in 30s)             |
+| ★★        | Fantasy        | World-building for RPG/adventure ads (requires L2+ narrative)     |
+| ★         | Narrative      | Story-driven ads — almost never fits in 30s                       |
+| ★         | Expression     | Dress-up/customization ads — niche                                |
+
+**Key principle**: A tiny change in mechanics → amplified by dynamics → dramatic shift in aesthetics. Example: changing the match threshold from 3 to 2 completely transforms the rhythm and sense of achievement.
+
+---
+
+## B. JTBD — Jobs-to-be-Done (User Motivation Framework)
+
+Users don't "play a game" — they **hire** the game to do a psychological job. The same game targeting different motivation types requires completely different Hook strategies:
+
+| Motivation Type             | Signal Words                                | Hook Emotion Strategy                                 | Default Arc    |
+| --------------------------- | ------------------------------------------- | ----------------------------------------------------- | -------------- |
+| **Stress Relief**           | "casual", "relaxing", "zen", "mindless"     | Show smooth, satisfying elimination flow              | Relaxation Arc |
+| **Challenge / Mastery**     | "hard", "strategic", "brain teaser"         | Show high-difficulty board + near-win tension         | Challenge Arc  |
+| **Collection / Growth**     | "collect", "upgrade", "rewards", "evolve"   | Show reward cascade / evolution moment                | Competence Arc |
+| **Creativity / Expression** | "customize", "dress up", "design", "create" | Show rich personalization options + beautiful results | Curiosity Arc  |
+| **Immersion / Escape**      | "story", "world", "RPG", "adventure"        | Show grand scene entry + immersion hook               | Curiosity Arc  |
+
+**Default rule**: If the prompt has no clear motivation signal → assume **Stress Relief** (broadest audience coverage).
+
+---
+
+## C. Three Key Emotional Mechanisms
+
+These are the non-negotiable tools in your emotional design toolkit:
+
+### 1. Near-Win
+
+Deliberately design a "one step away from success" situation — the peak emotion trigger.
+
+**Critical constraint**: Near-Win **must have a solution**. A visible path to victory creates excitement; a dead end creates frustration. The difference between "thrilling" and "rage-quit" is whether the player can see the way out.
+
+### 2. Emotional Breather
+
+The Tutorial phase's low-pressure onboarding is a **mandatory buffer zone** — it cannot be compressed or skipped.
+
+**Flow theory basis**: Place zero-skill new users at the bottom of the flow channel. The first interaction must succeed at 100% — no exceptions. This is the entry ramp to flow state; skip it and you lose the user.
+
+### 3. Curiosity Gap Closure
+
+The End Card **does not close the gap** — the user installs to "continue this story", not to "buy a product."
+
+**CTA is a sequel entrance, not an ad cutoff.** "Continue playing" > "Download now". The cognitive gap opened in the Hook should remain partially open at the End Card — closure happens after install.
+
+---
+
+## D. Hook-Body-CTA Advertising Framework
+
+Standard ad creative structure, mapped to playable ad stages:
+
+| Ad Stage | Playable Ad Stage   | Duration | Job                                                            |
+| -------- | ------------------- | -------- | -------------------------------------------------------------- |
+| **Hook** | Hook                | 0-3s     | Stop the scroll — create immediate emotional stimulus          |
+| **Body** | Tutorial + Gameplay | 3-25s    | Deliver the core experience — build and peak the emotional arc |
+| **CTA**  | End Card            | 25-30s   | Convert emotion to action — sequel feeling, not sales pitch    |
+
+**Key insight**: The Hook's emotion must be **consistent** with the Body and CTA. If the Hook creates curiosity but the Body delivers relaxation, the experience fractures. The Emotional Arc must be a single throughline across all three stages.
+
+---
+
+## E. Design Lenses (Quick Reference)
+
+Jesse Schell's 8 most relevant lenses for playable ads (full checklist in `templates/design-lens-checklist.reference.md`):
+
+1. **Essential Experience** — Is every mechanic serving the core feeling?
+2. **The Toy** — Is the basic interaction inherently satisfying, even without goals?
+3. **Curiosity** — Is the user continuously drawn to find out what's next?
+4. **The Hook** — Is the reason to start and stay consistent throughout?
+5. **Skill** — Does a zero-skill user succeed on first try? Is the flow zone reasonable?
+6. **Near-Win** — Is a near-win moment deliberately designed? Does it have a solution?
+7. **Emotion** — Does each mechanic trigger the intended emotion? Aligned with the arc?
+8. **Memorable Moment** — What will the user remember 10 minutes later?

package/project-templates/phaser/templates/design.template.md

@@ -0,0 +1,50 @@
+# {Game Name} — Ring 1 Playable Seed
+
+<!--
+  Ring 1 only. This is the single Game Designer contract for a semantic
+  placeholder playable demo. It defines the smallest player-reachable action
+  chain; later rings disclose layout, Hook/CTA (Call To Action, 行动号召),
+  MC (Master Composite, 主合成图), ASR (Asset State Reference, 资产状态参考表),
+  and production assets.
+-->
+
+**Date**: {YYYY-MM-DD}
+**Engine Hint**: {phaser / threejs + one-line reason}
+
+---
+
+## Player Action
+
+{What the player can do first: tap / drag / aim / choose. Name the visible target and why the action is obvious.}
+
+## Immediate Feedback
+
+{What changes within 100ms after the first input: motion, state, sound placeholder, count, reveal, or response.}
+
+## Progress Signal
+
+{How 3-5 actions show progress toward success: meter fills, targets clear, path opens, stack shrinks, character advances, etc.}
+
+## First Win
+
+{How the first level guarantees success: constrained setup, guided target, no failure timer, locked failure path, or simplified rule.}
+
+## Semantic Placeholders
+
+| Placeholder | Meaning in Ring 1                            | Required? |
+| ----------- | -------------------------------------------- | --------- |
+| player      | {player avatar / cursor / controlled object} | yes       |
+| target      | {thing the player acts on}                   | yes       |
+| feedback    | {visual/audio/state response placeholder}    | yes       |
+| reward      | {first win / payoff placeholder}             | yes       |
+| blocker     | {optional blocker / pressure source, or n/a} | optional  |
+
+## Runtime Seed
+
+- **Start phase**: `HOOK` (teaching beat only — not production ad hook packaging)
+- **Playable spine (Ring 1)**: HOOK → player-reachable actions → first win. **ENDCARD/CTA sections belong in Ring 3+** — do not add `## ENDCARD` or `## CTA` headings here.
+- **autoPlay() rule**: uses the same reachable actions a player can perform; it must not jump directly to ENDCARD.
+
+## Open Assumptions
+
+{Only list assumptions that materially affect Ring 1. Use "none" if clear.}