@playcraft/cli 0.0.43 → 0.0.46

package/project-template/.claude/agents/refs/framework-game-feel-juice.md

@@ -0,0 +1,266 @@
+# Game Feel & Game Juice 框架
+
+## 原始来源
+
+### 理论基石
+
+- **书籍**：Steve Swink (2008). _Game Feel: A Game Designer's Guide to Virtual Sensation_. Morgan Kaufmann.
+  - 详细解读：https://www.gamejuice.co.uk/articles/swink-6-components-game-feel
+
+### 经典演讲
+
+- **Juice it or Lose it** (2012) — Martin Jonasson & Petri Purho，Nordic Game Indie Night
+  - 解读：https://www.gamejuice.co.uk/articles/juice-it-or-lose-it-lessons
+- **The Art of Screenshake** (2013) — Jan Willem Nijman (Vlambeer), INDIGO Classes
+  - 中文解读：https://blog.chosenconcept.dev/tw/posts/2022/11/0012-the-art-of-screenshake/
+
+### 综合参考
+
+- Making Games 'Juicy'：https://abagames.github.io/joys-of-small-game-development-en/make_game_juicy.html
+- Game Feel 资源汇总：https://marcosecchi.github.io/resources/pages/gamedesign_game-feel.html
+
+---
+
+## 一、什么是 Game Feel？
+
+Game Feel（游戏手感）是指**玩家在操控游戏时感受到的无形触感**——为什么同样是"跳跃"，《超级马里奥》的跳跃就是比其他游戏"更舒服"？Game Feel 就是对这种差异的系统性解释。
+
+Steve Swink 在 2008 年的同名著作中首次将 Game Feel 系统化为 **6 个组件**，为"什么让游戏玩起来感觉好"提供了可分析、可诊断的结构框架。
+
+> **Game Feel 不是一个配方，而是一把测量工具和一套诊断语言。**
+
+---
+
+## 二、Steve Swink 的 6 个 Game Feel 组件
+
+### 组件 1：Real-Time Control（实时控制）
+
+**定义**：玩家必须能**直接**操控虚拟对象，且输入获得**即时**响应。
+
+**关键阈值**：
+
+- **100ms**：超过此延迟，大脑不再认为这是"直接控制"，而像是在"下达命令等执行"
+- **一致性 > 速度**：不稳定的 80ms 延迟比稳定的 100ms 感觉更糟
+
+**常见问题及修复**：
+| 问题 | 原因 | 修复方式 |
+|------|------|---------|
+| 操控迟钝 | 输入延迟过高 | 减少帧延迟，优化输入管线 |
+| 动作"卡住" | 必须等动画播完才能响应 | 输入缓存、动画取消、设置可打断帧 |
+| 感觉不灵敏 | 帧率不稳定 | 固定物理步长，与渲染帧率解耦 |
+
+### 组件 2：Simulated Space（空间模拟）
+
+**定义**：游戏世界必须遵循**内部一致**的物理规则（重量、动量、碰撞、重力）。
+
+物理可以夸张，**但必须可预测**。
+
+**核心原则**：
+
+- 不可预测的物理让人愤怒——不是因为"不真实"，而是因为"无法建立心理模型"
+- 模拟必须延伸到玩家能互动的所有事物
+
+**经典案例**：
+
+- **《蔚蓝》(Celeste)**：物理完全不真实（空中冲刺违反物理定律），但内部绝对一致，玩家能精准预测落点
+- **反例**：角色有时被击退 3 格有时 5 格，没有可见原因 → 玩家困惑
+
+### 组件 3：Polish（润色）
+
+**定义**：游戏性非严格必需、但能让体验更丰富的修饰层——粒子、屏幕震动、音效、动画细节、拖尾等。
+
+这就是大众常说的 **"Juice"**。
+
+**⚠️ 关键顺序**：
+
+> **润色排在第三位，不是第一位。** 它是**放大器**——放大已经感觉良好的空间模拟。如果底层模拟很弱，润色只会让弱点更刺眼。
+
+**一致性要求**：
+
+- 特效必须形成一种"语言"——屏幕震动在不同语境下不能意思矛盾
+- 润色层应是有统一语法的系统，而非随意堆砌
+
+### 组件 4：Metaphor（隐喻）
+
+**定义**：虚拟对象与玩家**现实物理理解**之间的连接。
+
+玩家带着一生的物理体验来玩游戏。当虚拟互动与真实物理感觉共鸣时，会产生近乎潜意识的"正确感"。
+
+**示例**：
+| 隐喻匹配 | 效果 |
+|---------|------|
+| 重物落地→低沉轰鸣+屏幕微震 | ✅ 符合物理直觉，感觉"对" |
+| 爆头→清脆尖锐声+短衰减 | ✅ 高冲击碰撞的真实声学特征 |
+| 仙女魔杖→榴弹发射器声效 | ❌ 隐喻破裂，反馈与世界矛盾 |
+
+### 组件 5：Juiciness（多汁性）
+
+**定义**：**最小输入产生最大输出**的特质。游戏对每个动作给予不成比例的丰厚反馈。
+
+**核心理念**：让玩家每一个微小操作都感到"有力量、有效果"。
+
+**⚠️ 需要层级**：
+
+- 每次操作都全屏爆炸 → 反而削弱了真正重大事件的冲击力
+- 正确做法：**小动作小奖励，大动作大奖励**，建立清晰的反馈层级
+
+**玩具测试**（源自马里奥 64 团队）：
+
+> 在没有关卡、没有敌人的空房间里，光是跑、跳、操作，是否就已经令人满足？如果是，你就拥有了 Juiciness。
+
+### 组件 6：Mastery（学习与精通）
+
+**定义**：随着玩家内化操控、开始流畅行动，手感随时间**不断加深**的掌控感。
+
+**深度 vs 天花板**：
+
+- 操控系统必须足够深，让精通能持续产生新能力
+- 操控太浅 → 很快触及天花板 → 玩家失去兴趣
+- 精通创造**心流**——这是长期留存的核心
+
+> **对 Playable Ad 的特殊考量**：15 秒内无法实现深度精通，但可以设计"可感知的操控深度"——让玩家觉得"如果我再玩一会儿，我能做得更好"，这正是转化的驱动力。
+
+---
+
+## 三、Game Feel 诊断工具
+
+当游戏"感觉不对"时，按组件逐一排查：
+
+| 症状                  | 对应组件   | 诊断方向                               |
+| --------------------- | ---------- | -------------------------------------- |
+| 操控迟钝、无响应      | ① 实时控制 | 查输入延迟、动画打断帧、响应时机       |
+| 移动不可预测、轻飘    | ② 空间模拟 | 查物理一致性、重力曲线、动量传递       |
+| 有特效但仍觉无力      | ③ 润色     | 查反馈通道是否同步、反馈语言是否一致   |
+| 技术正确但情感平淡    | ④ 隐喻     | 查反馈是否匹配世界逻辑和玩家物理直觉   |
+| 动作缺乏震撼力        | ⑤ 多汁性   | 查反馈的规模和种类与动作重要性是否匹配 |
+| 老手停止进步/失去兴趣 | ⑥ 精通     | 控制系统有天花板，阻碍了技巧表达       |
+
+**组件间的依赖关系**：
+
+```
+① 实时控制 ← 基础。没有它，⑥精通不可能
+② 空间模拟 ← ③润色的基座。模拟弱则润色制造混乱
+④ 隐喻    ← 绑定整个系统。没有它，所有反馈情感空洞
+```
+
+---
+
+## 四、Game Juice 实操清单
+
+Juice 是 Game Feel 中"润色"和"多汁性"组件的具体实现手段。以下综合了 **Juice it or Lose it** 演讲和 **The Art of Screenshake** 演讲中的所有技术：
+
+### 4.1 视觉反馈
+
+| #   | 技术                             | 描述                      | 示例                  |
+| --- | -------------------------------- | ------------------------- | --------------------- |
+| 1   | **Squash & Stretch（挤压拉伸）** | 物体弹跳/碰撞时的形变动画 | 球落地时压扁再弹起    |
+| 2   | **Screen Shake（屏幕震动）**     | 碰撞/消除时的短暂画面抖动 | 消除方块时轻震 0.1 秒 |
+| 3   | **Particles（粒子特效）**        | 碰撞/消除时喷射的粒子     | 方块消除时碎片飞溅    |
+| 4   | **Flash/Blink（闪白/闪烁）**     | 受击/激活时的短暂颜色变化 | 敌人被打中闪白 1 帧   |
+| 5   | **Color Change（颜色变化）**     | 根据状态变化调整颜色      | HP 低时角色变红       |
+| 6   | **Trail（拖尾）**                | 移动物体留下的轨迹        | 子弹拖出光轨          |
+| 7   | **Muzzle Flash（枪口焰）**       | 发射/释放时的源头特效     | 射击时枪口闪火        |
+| 8   | **Impact VFX（命中特效）**       | 击中目标时的视觉标记      | 命中时溅射火花        |
+| 9   | **Permanence（永久痕迹）**       | 保留战斗/操作的视觉痕迹   | 地上留有碎片          |
+
+### 4.2 动画与运动
+
+| #   | 技术                                   | 描述                  | 示例                     |
+| --- | -------------------------------------- | --------------------- | ------------------------ |
+| 10  | **Tweening/Easing（缓动）**            | 所有运动使用缓动曲线  | 方块落下用 easeOutBounce |
+| 11  | **Anticipation（预备动作）**           | 大动作前的蓄力姿势    | 跳跃前先蹲下             |
+| 12  | **Follow-through（随动）**             | 动作完成后的惯性延续  | 挥剑后手臂的回摆         |
+| 13  | **Knockback（击退）**                  | 碰撞后的位移反应      | 敌人被击中后弹飞         |
+| 14  | **Recoil（后坐力）**                   | 施力者自身的反作用    | 射击时枪向上弹跳         |
+| 15  | **Bigger Projectiles（更大的投射物）** | 弹药/投射物比实际更大 | 子弹放大到清晰可见       |
+
+### 4.3 时间操控
+
+| #   | 技术                                  | 描述                   | 示例                   |
+| --- | ------------------------------------- | ---------------------- | ---------------------- |
+| 16  | **Hit Stop/Freeze Frame（打击暂停）** | 命中瞬间的极短暂冻结   | 打击时停顿 2-3 帧      |
+| 17  | **Slow Motion（慢动作）**             | 关键时刻降低时间流速   | 最后一击进入 0.3x 慢放 |
+| 18  | **Speed Up（加速）**                  | 常规行为加速以保持节奏 | 子弹速度翻倍           |
+
+### 4.4 镜头
+
+| #   | 技术                            | 描述                   | 示例                         |
+| --- | ------------------------------- | ---------------------- | ---------------------------- |
+| 19  | **Camera Lerp（镜头平滑跟随）** | 镜头像弹簧一样柔和追踪 | 角色移动时镜头延迟 0.1s 跟随 |
+| 20  | **Camera Kick（镜头推动）**     | 有方向性的镜头偏移     | 射击时镜头向射击反方向微推   |
+| 21  | **Zoom（缩放）**                | 关键时刻拉近/推远      | 大规模消除时镜头微微拉远     |
+
+### 4.5 音效
+
+| #   | 技术                            | 描述                   | 示例                        |
+| --- | ------------------------------- | ---------------------- | --------------------------- |
+| 22  | **Impact SFX（打击音效）**      | 碰撞/消除时的声音      | 清脆的"啪"声                |
+| 23  | **Pitch Variation（音高变化）** | 连续操作的音高递增     | 连续消除从低音到高音        |
+| 24  | **Layered SFX（分层音效）**     | 多个声音叠加成丰满效果 | 爆炸 = 低频轰+中频碎+高频嘶 |
+| 25  | **BGM Reactive（音乐响应）**    | 背景音乐响应游戏事件   | 连击时 BGM 加鼓点           |
+
+### 4.6 情感反馈
+
+| #   | 技术                             | 描述                    | 示例                           |
+| --- | -------------------------------- | ----------------------- | ------------------------------ |
+| 26  | **Floating Text（飘字）**        | 动作结果的数字/文字弹出 | "+100" 向上飘出                |
+| 27  | **Celebration（庆祝演出）**      | 达成成就时的夸张表演    | 全消时烟花+欢呼声              |
+| 28  | **Expressions（表情）**          | 角色/物体显示情感反应   | 被选中的方块"瞪大眼睛"         |
+| 29  | **Combo Escalation（连击升级）** | 连续成功的反馈逐级增强  | Normal → Great → Amazing → MAX |
+
+---
+
+## 五、Juice 实施优先级
+
+根据 "Juice it or Lose it" 的核心建议：
+
+### 第一步：音效（成本最低、见效最快）
+
+一个好的打击/消除音效就能让操作感提升 50%。
+
+### 第二步：缓动动画
+
+将所有 `linear` 运动替换为 `easeOut` / `easeInOut`，瞬间提升品质感。
+
+### 第三步：层层叠加
+
+依次加入粒子 → 屏幕震动 → 慢动作 → 颜色变化……
+
+### 核心法则
+
+> **"More is more. Add more juice, then add more."**（多就是多。加更多 Juice，然后再加更多。）
+
+但要记住 Steve Swink 的警告：
+
+> **Juice 是放大器，不是遮瑕膏。** 底层 Game Feel（实时控制+空间模拟）必须先到位。
+
+---
+
+## 六、累积效应
+
+Juice 技术单独使用效果有限，但**累积叠加**产生质变：
+
+```
+裸机制                          → 🫤 能玩但乏味
++ 音效                          → 😐 稍好
++ 音效 + 粒子                    → 🙂 开始有感觉
++ 音效 + 粒子 + 屏幕震动          → 😀 体验明显提升
++ 音效 + 粒子 + 屏幕震动 + 慢动作  → 😆 开始上瘾
++ 以上全部 + 连击升级 + 飘字       → 🤩 停不下来
+```
+
+**整体远大于部分之和。**
+
+---
+
+## 七、参考资源汇总
+
+| 类型    | 名称                          | 链接                                                                                                     |
+| ------- | ----------------------------- | -------------------------------------------------------------------------------------------------------- |
+| 📕 书籍 | Game Feel (Steve Swink, 2008) | [Taylor & Francis](https://www.taylorfrancis.com/books/mono/10.1201/9781482267334/game-feel-steve-swink) |
+| 🎤 演讲 | Juice it or Lose it (2012)    | [GameJuice 解读](https://www.gamejuice.co.uk/articles/juice-it-or-lose-it-lessons)                       |
+| 🎤 演讲 | The Art of Screenshake (2013) | [中文解读](https://blog.chosenconcept.dev/tw/posts/2022/11/0012-the-art-of-screenshake/)                 |
+| 📝 文章 | 6 Components of Game Feel     | [GameJuice](https://www.gamejuice.co.uk/articles/swink-6-components-game-feel)                           |
+| 📝 文章 | Making Games 'Juicy'          | [abagames](https://abagames.github.io/joys-of-small-game-development-en/make_game_juicy.html)            |
+| 🔗 汇总 | Game Feel Resources           | [marcosecchi](https://marcosecchi.github.io/resources/pages/gamedesign_game-feel.html)                   |
+| 🎮 案例 | Celeste & Forgiveness         | Celeste 如何用宽容度提升 Game Feel                                                                       |

package/project-template/.claude/agents/refs/framework-mda.md

@@ -0,0 +1,147 @@
+# MDA 框架 — Mechanics, Dynamics, Aesthetics
+
+## 原始来源
+
+- **论文**：Hunicke, R., LeBlanc, M., & Zubek, R. (2004). _MDA: A Formal Approach to Game Design and Game Research_. AAAI Workshop – Technical Report.
+- **原文 PDF**：https://www.researchgate.net/publication/228884866_MDA_A_Formal_Approach_to_Game_Design_and_Game_Research
+- **Semantic Scholar**：https://www.semanticscholar.org/paper/MDA-%3A-A-Formal-Approach-to-Game-Design-and-Game-Hunicke-Leblanc/2b134e5c46eec50f69c702c0b4aa29687d5d8fba
+- **解读**：https://educationalgamedesign.com/mechanics-dynamics-and-aesthetics-mda-framework-by-hunicke-leblanc-and-zubek.html
+
+---
+
+## 一、核心思想
+
+MDA 框架将游戏拆解为三个相互关联的层次，提供了一种**形式化的语言**来分析和设计游戏。其最核心的洞察是：
+
+> **设计者自下而上（规则 → 行为 → 情感），玩家自上而下（情感 → 行为 → 规则）。**
+
+设计者编写规则（Mechanics），规则在运行时产生动态行为（Dynamics），动态行为引发玩家的情感体验（Aesthetics）。但玩家的感知方向正好相反——他们首先感受到"好不好玩"（Aesthetics），然后才注意到行为模式和底层规则。
+
+```
+设计者视角：  Mechanics  →  Dynamics  →  Aesthetics
+                 ↑ 你直接控制    ↑ 你间接影响    ↑ 你的最终目标
+
+玩家视角：    Aesthetics  →  Dynamics  →  Mechanics
+                 ↑ 首先感受到     ↑ 然后注意到    ↑ 最后才理解
+```
+
+---
+
+## 二、三层详解
+
+### 层次 1：Mechanics（机制）
+
+**定义**：游戏的组件、规则、算法和数据结构。
+
+这是设计者能**直接控制**的部分。包括：
+
+- 玩家可以执行的**动作/动词**（点击、滑动、放置、交换……）
+- 游戏运行的**规则和算法**（匹配判定、分数计算、消除逻辑……）
+- 底层的**数据结构**（棋盘矩阵、牌组列表、状态机……）
+
+**示例**（三消游戏）：
+| 机制要素 | 具体内容 |
+|---------|---------|
+| 动作 | 交换两个相邻方块 |
+| 匹配规则 | ≥3 个同色方块连成一线即消除 |
+| 重力 | 消除后上方方块下落填补空位 |
+| 分数算法 | 基础分 × 连击倍率 |
+
+### 层次 2：Dynamics（动态）
+
+**定义**：当机制被执行、玩家开始游戏后**涌现**的运行时行为。
+
+这是设计者只能**间接影响**的部分。Dynamics 是 Mechanics 的"运行时行为"——你设计了规则，但规则在实际游戏中会产生你未必预料到的交互模式和策略。
+
+**示例**（三消游戏）：
+| 动态行为 | 来源机制 |
+|---------|---------|
+| 连锁消除（一次消除引发新的匹配） | 重力 + 匹配规则的组合 |
+| 玩家优先寻找大规模消除而非小匹配 | 分数算法的倍率激励 |
+| 在有限步数下出现的紧迫感 | 步数限制 + 分数目标 |
+| 特殊方块的策略性保留 | 特殊方块生成规则 + 其清除范围 |
+
+### 层次 3：Aesthetics（美学/情感）
+
+**定义**：游戏旨在引发的**情感体验**。
+
+这是设计者的**最终目标**——让玩家"感觉好"。MDA 框架给出了一个经典的 **8 种乐趣分类法**，不是说游戏必须包含所有类型，而是帮助设计者明确自己的游戏主要瞄准哪几种情感。
+
+---
+
+## 三、8 种乐趣分类（Aesthetics Taxonomy）
+
+| #   | 类型     | 英文       | 关键词               | 描述                                                                     |
+| --- | -------- | ---------- | -------------------- | ------------------------------------------------------------------------ |
+| 1   | **感官** | Sensation  | 视听冲击、特效满足   | 通过视觉、听觉等感官刺激获得的愉悦。华丽的特效、悦耳的音效、流畅的动画。 |
+| 2   | **幻想** | Fantasy    | 代入、扮演、想象     | 让玩家代入一个虚构角色或世界，体验日常不可能的事情。                     |
+| 3   | **叙事** | Narrative  | 故事推进、情节展开   | 通过故事的展开和发展，给玩家"追剧"般的参与感。                           |
+| 4   | **挑战** | Challenge  | 克服困难、成就感     | 面对障碍、克服困难后获得的成就感。难度曲线和技巧门槛是关键。             |
+| 5   | **社交** | Fellowship | 合作、竞争、社区     | 与他人互动、合作或竞争带来的社交愉悦。                                   |
+| 6   | **探索** | Discovery  | 发现、惊喜、揭秘     | 发现新区域、新道具、隐藏内容时的惊喜和好奇心满足。                       |
+| 7   | **表达** | Expression | 自我展现、创造       | 玩家通过游戏系统表达自我的自由度（如捏脸、建筑、选择路线）。             |
+| 8   | **消遣** | Submission | 放空、无脑、消磨时间 | "关掉脑子"的轻松愉悦，让玩家放松地消磨时间。                             |
+
+---
+
+## 四、在 Playable Ad 中的适用度评估
+
+Playable Ad 的典型场景是 **15-30 秒**、**单人**、**即点即玩**、**以转化为目标**。基于这些约束：
+
+| 乐趣类型               | 适用度     | 原因                                             |
+| ---------------------- | ---------- | ------------------------------------------------ |
+| **Sensation（感官）**  | ⭐⭐⭐⭐⭐ | 核心。视听反馈是 15 秒内让玩家"爽"的最快途径。   |
+| **Challenge（挑战）**  | ⭐⭐⭐⭐⭐ | 核心。"差一点就赢了"的挫折感是转化的最大驱动力。 |
+| **Submission（消遣）** | ⭐⭐⭐⭐   | 非常适合休闲消除类。"无脑但上瘾"的循环。         |
+| **Discovery（探索）**  | ⭐⭐⭐     | 适合翻转、解谜类。发现匹配/路径的"啊哈"时刻。    |
+| **Fantasy（幻想）**    | ⭐⭐       | 时间太短难以建立深度代入，但简单的主题包装可以。 |
+| **Expression（表达）** | ⭐⭐       | 时间太短难以展开，但简单的选择（如选角色）可以。 |
+| **Narrative（叙事）**  | ⭐         | 几乎不适用。15 秒无法讲好一个故事。              |
+| **Fellowship（社交）** | ⭐         | 几乎不适用。Playable Ad 是单人体验。             |
+
+### 设计启发问题
+
+在 Brainstorm 阶段，可以用以下问题引导设计方向：
+
+1. **"这个游戏主要打哪 2-3 种乐趣？"** — 确定主攻方向
+2. **"玩家在第 5 秒会感受到什么情感？"** — 确保开头有足够的 hook
+3. **"15 秒内能体验到至少一次完整的情感循环吗？"** — 确保时长内有完整体验
+4. **"失败时玩家会觉得'差一点就行了'还是'完全没懂'？"** — 诊断挑战性设计是否到位
+
+---
+
+## 五、MDA 的设计方法论
+
+### 从 Aesthetics 出发倒推设计
+
+MDA 框架最有价值的用法不是从 M 推到 A，而是**从 A 反推到 M**：
+
+```
+1. 确定目标情感（Aesthetics）
+   → "我希望玩家感到满足感 + 轻度挑战"
+
+2. 设想需要的动态行为（Dynamics）
+   → "连锁消除带来满足感，有限步数带来挑战"
+
+3. 设计支撑这些行为的规则（Mechanics）
+   → "重力填充 + 匹配规则产生连锁；步数限制产生紧迫"
+```
+
+### 用 MDA 诊断问题
+
+当游戏"感觉不对"时，MDA 提供了诊断路径：
+
+| 症状                   | 可能的问题层    | 诊断方向                                            |
+| ---------------------- | --------------- | --------------------------------------------------- |
+| "好看但无聊"           | Aesthetics 缺失 | 你瞄准了什么情感？Sensation 有了但 Challenge 没有？ |
+| "有策略深度但没人想玩" | Dynamics 问题   | 涌现行为是否有趣？玩家能发现策略吗？                |
+| "概念好但执行差"       | Mechanics 问题  | 规则是否能产生你想要的 Dynamics？                   |
+
+---
+
+## 六、参考资源
+
+- 📄 **原始论文** (2004)：[ResearchGate](https://www.researchgate.net/publication/228884866_MDA_A_Formal_Approach_to_Game_Design_and_Game_Research)
+- 📖 **知乎中文翻译**：[MDA 框架详解](https://zhuanlan.zhihu.com/p/402577913)
+- 🎓 **教育版解读**：[Educational Game Design](https://educationalgamedesign.com/mechanics-dynamics-and-aesthetics-mda-framework-by-hunicke-leblanc-and-zubek.html)
+- 🛠️ **设计工具箱**：[Game Design Toolkit - MDA Framework](https://tkdev.dss.cloud/gamedesign/toolkit/mda-framework/)

package/project-template/.claude/agents/refs/game-designer-gameplay-sufficiency.md

@@ -0,0 +1,123 @@
+# Gameplay Sufficiency Self-Check
+
+> **When to read**: Game Designer reads this at Step 2, after brainstorm is complete and the living brief is structurally complete. This is a **blocking gate** — do not proceed to Five-Axis Evaluation (Step 3) until all angles pass.
+>
+> **Pattern**: Modeled on Flow B's "玩法核心充分性 Review" — 8 angles covering MDA, Game Feel, visual readability, and Playable Ad flow completeness.
+
+---
+
+## Purpose
+
+Verify that the design-brief contains enough gameplay depth to support module selection, five-axis evaluation, and downstream production. This check prevents the common failure mode of "proceeding with a technically complete but experientially shallow brief."
+
+**Why before Five-Axis**: Five-Axis evaluation and Style Direction must serve the core gameplay. If the gameplay itself is underspecified, five-axis choices become disconnected from player experience.
+
+---
+
+## 8-Angle Review Table
+
+For each angle, answer the core question. If the answer is unclear or only partially addressed in design-brief → mark ❌ and return to Step 1 brainstorm for targeted clarification.
+
+| #   | Angle                  | Core Question                                                                            | ✅ Pass Signal                                                                                             | ❌ Fail Signal                                                                       |
+| --- | ---------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| 1   | **MDA / Mechanics**    | Core rules, player operations, legal/illegal actions — are they explicit?                | Can state: "player does X → system checks Y → result Z" with no ambiguity                                  | Only describes features/functions, never states rules                                |
+| 2   | **MDA / Dynamics**     | What strategy, rhythm, risk, or feedback loop emerges from consecutive play?             | Can describe: "after 3-5 operations, player experiences {tension/flow/escalation} because {mechanism}"     | Single operation is clear but no loop or decision pressure described                 |
+| 3   | **MDA / Aesthetics**   | Which 2-3 emotion types does this game primarily deliver?                                | Specific emotions named with source (e.g., "Sensation from cascade VFX + Challenge from near-win")         | Only "fun" / "exciting" / "engaging" without identifying emotion source              |
+| 4   | **Game Feel / Juice**  | Is the input → response → satisfaction chain planned?                                    | Each core interaction has: what feedback (visual + audio), when it fires, how it escalates on combo/streak | "Click something → something happens" — no feedback specifics                        |
+| 5   | **Visual Readability** | Can player instantly distinguish: clickable / unclickable / target / risk / progress?    | Design-brief describes HOW each gameplay state is visually communicated to the player                      | Only describes art style or tech stack, not how visuals serve gameplay understanding |
+| 6   | **Level Progression**  | Do levels serve gameplay teaching and challenge escalation, or are they just data files? | Each level/stage has stated intent: "level 1 teaches X, level 2 tests Y, level 3 introduces Z"             | Only lists level count or says "difficulty increases" without per-level purpose      |
+| 7   | **Playable Ad Flow**   | Does Hook → Tutorial → Gameplay → EndCard form a 15-30s emotional closed loop?           | All four stages named with emotional beat, timing, and transition triggers                                 | Only describes the gameplay loop, no ad-specific rhythm (hook, CTA, sequel feeling)  |
+| 8   | **Data Derivation**    | Are data structures derived FROM gameplay rules, or do they drive/constrain gameplay?    | Rules/player-experience described first; data representation follows naturally                             | JSON schema / config format / solver algorithm appears before "how to play"          |
+
+---
+
+## Output Format
+
+Write self-check results in internal notes or briefly in design-brief appendix:
+
+```markdown
+### Gameplay Sufficiency Self-Check
+
+| Angle              | Result | Notes                                                                                                       |
+| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------- |
+| MDA / Mechanics    | ✅     | Tap to unscrew → color-match to hole → gravity release when all screws removed                              |
+| MDA / Dynamics     | ✅     | Buffer management creates "which screw to remove first" strategy                                            |
+| MDA / Aesthetics   | ✅     | Sensation (satisfying unscrew SFX + gravity cascade) + Challenge (buffer full = lose)                       |
+| Game Feel / Juice  | ❌     | Success cascade feedback not specified — need to define what happens on multi-release                       |
+| Visual Readability | ✅     | Color = screw-hole match affordance; glow = removable; grey = blocked                                       |
+| Level Progression  | ✅     | L1: single color; L2: two colors; L3: introduce blocking order                                              |
+| Playable Ad Flow   | ✅     | Hook: show stuck board → Tutorial: guided first screw → Gameplay: 3-level cascade → EndCard: "more puzzles" |
+| Data Derivation    | ✅     | Rules defined first; level JSON is just instantiation of rule parameters                                    |
+
+**Result**: 7/8 pass. ❌ Game Feel → return to Step 1 for targeted clarification on cascade feedback design.
+```
+
+---
+
+## Decision
+
+- **All 8 ✅** → Proceed to Step 3 (Five-Axis Evaluation)
+- **Any ❌** → Return to Step 1 with specific angle as the brainstorm target. Ask user only about the gap (not re-do entire brainstorm).
+
+---
+
+## Reference Frameworks (Condensed for Playable Ads)
+
+### MDA — 8 Aesthetics Taxonomy (Playable Ad Relevance)
+
+| #   | Type           | Relevance  | Role in Playable Ads                                              |
+| --- | -------------- | ---------- | ----------------------------------------------------------------- |
+| 1   | **Sensation**  | ⭐⭐⭐⭐⭐ | Core — visual juice + audio feedback is the baseline for every ad |
+| 2   | **Challenge**  | ⭐⭐⭐⭐⭐ | Core — "one more try" / near-win is the #1 conversion driver      |
+| 3   | **Submission** | ⭐⭐⭐⭐   | Casual/relaxing ads — low-pressure flow, "mindless but addictive" |
+| 4   | **Discovery**  | ⭐⭐⭐     | Puzzle/reveal ads — "aha, that's how it works!" moment            |
+| 5   | **Fantasy**    | ⭐⭐       | Theme wrapping only — 15s too short for deep immersion            |
+| 6   | **Expression** | ⭐⭐       | Dress-up/customization ads — niche                                |
+| 7   | **Narrative**  | ⭐         | Almost never fits in 30s                                          |
+| 8   | **Fellowship** | ⭐         | Playable ads are single-player                                    |
+
+**Design questions:**
+
+1. "Which 2-3 aesthetics does this game primarily deliver?"
+2. "What does the player feel at second 5? At second 15? At second 25?"
+3. "Can the player experience one complete emotional cycle in 15-30s?"
+
+### 5-Component Filter (Quick Scoring)
+
+Evaluate each core mechanic against 5 components:
+
+| Component        | Core Question                    | ⭐⭐⭐ (Excellent)             | ❌ (Fail)               |
+| ---------------- | -------------------------------- | ------------------------------ | ----------------------- |
+| **Clarity**      | Can player understand in 3s?     | Zero-tutorial comprehension    | 5s+ still confused      |
+| **Motivation**   | Why does player want to act?     | Can't stop, intrinsic drive    | "Why should I do this?" |
+| **Response**     | Feedback within 100ms?           | Multi-channel instant feedback | Action → silence        |
+| **Satisfaction** | Does success feel "juicy"?       | Want "one more time"           | Success feels empty     |
+| **Fit**          | Mechanic matches theme/audience? | Inseparable from the game      | Feels "bolted on"       |
+
+**Minimum bar for Playable Ads**: All 5 components ≥ ⭐⭐. Any ❌ = redesign needed.
+
+### Game Feel — 6-Component Diagnostic
+
+When something "feels off" but can't be named, check:
+
+| Component         | Symptom                              | Fix Direction                                                                   |
+| ----------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
+| Real-Time Control | Sluggish, unresponsive               | Reduce input delay; enable animation interrupts                                 |
+| Simulated Space   | Floaty, unpredictable movement       | Make physics internally consistent (can be unrealistic but MUST be predictable) |
+| Polish (Juice)    | Technically correct but lifeless     | Add particles, screen shake, squash/stretch, sound layers                       |
+| Metaphor          | Feedback feels "wrong" for the world | Align audio/visual feedback with what real-world physics would suggest          |
+| Juiciness         | Actions feel powerless               | Amplify output-to-input ratio; small tap → big response                         |
+| Mastery           | Gets boring fast                     | Ensure control depth allows skill expression over time                          |
+
+**Playable Ad note**: In 15-30s, focus on components 1-5. Component 6 (Mastery) manifests as "perceived depth" — player should feel "I could get better at this" which drives install.
+
+---
+
+## Common Failure Patterns
+
+| Pattern                  | Example                                                                         | How to Fix                                                                              |
+| ------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Feature-list design**  | "Has scoring, timer, 3 levels, power-ups" — no rules/emotions                   | Ask: "When player does X, what happens and how does it FEEL?"                           |
+| **Tech-first design**    | "Uses physics engine with rigid bodies and constraints" — no player perspective | Ask: "What does the PLAYER see and do? Forget the implementation."                      |
+| **Single-moment design** | "Player taps tiles to match" — no loop/escalation/arc                           | Ask: "After the 5th successful match, what's different? What pressure builds?"          |
+| **Borrowed assumption**  | "It's like Candy Crush" without specifying which aspects                        | Ask: "WHICH aspects of Candy Crush? Swap mechanic? Cascade? Level goals? Visual juice?" |

package/project-template/.claude/agents/refs/game-designer-legacy-fallback.md

@@ -0,0 +1,15 @@
+# Game Designer Legacy Fallback
+
+Use this reference only when `dispatchPacket` is null and `sliceState` is empty.
+
+This preserves the older growth-ring clarify path for existing projects. It is not part of slice-axis dispatch.
+
+Legacy behavior:
+
+- Read `npm run state:get -- --json` and follow the disclosed current action.
+- Produce the design document requested by the legacy orchestrator path.
+- Keep early work focused on core gameplay, player action, feedback, progress, and first success.
+- Do not implement runtime code or mark downstream work complete.
+- Write handoff context through `npm run state:set`.
+
+When `sliceState` exists, return to the main Game Designer role contract.

package/project-template/.claude/agents/refs/game-designer-workflow-detail.md

@@ -0,0 +1,69 @@
+# Game Designer Workflow Detail
+
+> Design execution workflow for `growth-rings-v1` clarify loops.
+>
+> **Slice-axis (primary)**: seed or deepen `sliceState` per §0 in `game-designer.md`. Ring numbers are outer budget only.
+>
+> Ring 1 is a playable seed pass, not a full game design pass. Ring 2 deepens **periphery slices**, not a full layout/production package.
+
+## Ring 1 Scope (slice-axis)
+
+Ring 1 clarify produces `docs/design-brief.md` (discovery), concise `docs/DESIGN.md`, and a minimal developer `sliceState` queue (1–3 slices).
+
+Do not create or read `docs/layout-spec.md`, full `docs/implementation-plan.md`, `docs/style-exploration.md`, MC (Master Composite, 主合成图), ASR (Asset State Reference, 资产状态参考表), or production logs in Ring 1.
+
+## Ring 1 Steps (slice-axis)
+
+1. Run `npm run state:get -- --json dispatchPacket sliceState`.
+2. Progressive discovery → `docs/design-brief.md`.
+3. Lock playable seed → `docs/DESIGN.md`.
+4. Seed `sliceState` (1–3 developer slices) + optional `meta.activatedSlices[]`.
+5. STOP with handoffContext via `state:set`.
+
+## Ring 2 Scope (slice-axis deepening)
+
+Ring 2 clarify **extends the slice queue** with 2–4 developer **periphery** slices (HUD, flow skeleton, tutorial hints, peripheral feedback — one slice = one verifiable outcome).
+
+| Do                                                    | Do not                           |
+| ----------------------------------------------------- | -------------------------------- |
+| Append `design-brief.md` with periphery discovery     | Invoke Artist / TA               |
+| Replace/extend `sliceState` with 2–4 developer slices | Lock production `assetMapping`   |
+| Optional `layout-spec.md` — zones/screen intent only  | Full atom graph expansion        |
+| Optional `implementation-plan.md` explain view        | `style-exploration` / CTA polish |
+| Patch `atom-tree.meta.activatedSlices[]`              | Full feature backlog             |
+
+Legacy fallback (empty `sliceState`): ring 2 may still require layout-spec + atom-tree per `DESIGNER_REQUIRED_DOCS_BY_RING[2]` — orchestrator discloses via `state:get`.
+
+## Ring 1 STOP Context (legacy — empty sliceState)
+
+Use this pattern only when no `sliceState` is seeded:
+
+```bash
+npm run state:set -- \
+  subagent_stop=true \
+  waiting_for=orchestrator \
+  last_completed_by=game-designer \
+  contextRole=game-designer \
+  contextSummary="Playable seed locked: <player action> -> <feedback> -> first win" \
+  contextNextRole=ref-flow \
+  contextArtifactRefs=docs/DESIGN.md \
+  contextCoreAction="<player action>" \
+  contextSemanticPlaceholders="player;target;feedback;reward" \
+  contextMustKnow="Use DESIGN.md as playable seed only; select engine + compact gameplay trunk; do not build full product tree" \
+  contextRequiredFiles="docs/DESIGN.md" \
+  next_orchestrator_action="Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection, then scaffold and invoke @developer"
+```
+
+## Later Rings (legacy deepening notes)
+
+Ring 3 clarify defines Hook / CTA (Call To Action, 行动号召) intent and style constraints for storyboard / Artist work. It does not produce production assets.
+
+Ring 4 clarify is spec-gap arbitration only. Answer routed contract ambiguity, then STOP with updated `handoffContext`; do not produce assets, code, or implementation plans.
+
+## Anti-Patterns
+
+- Treating Ring 1 `DESIGN.md` as a full player-experience contract.
+- Ring 2 "big bag" clarify: layout-spec + full plan + atom graph in one STOP instead of slice queue.
+- Asking many speculative style or progression questions before the playable seed exists.
+- Encoding atom selection, implementation status, asset paths, or production progress in `DESIGN.md`.
+- Using documents as handoff memory. The next agent reads `state:get` context first; documents are artifact refs for traceability.