@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/.claude/agents/refs/developer-phase1-flow.md

@@ -0,0 +1,404 @@
+# Developer Flow — `loop: build`
+
+> **触发条件**：`npm run state:get -- --json` 披露 `iteration` 1..4 + `loop: build`。只读取其中披露的 `currentRingRequiredFiles`。
+> 本文件由**单一 `developer` 角色**执行。
+
+---
+
+## 目标
+
+按照当前 Ring 披露的任务面实现游戏：Ring 1 只完成最小可验证 playable spine、`HOOK` 启动、`window.__playable` 生命周期和首关可胜；它可以是一个动作链路，不应扩张成完整游戏雏形。Ring 2+ 才根据 `state:get` 披露的计划、布局和视觉材料扩展体验。目标始终是达到真实的 `devStatus: ready` + `devUrl`。
+
+**核心原则**：
+
+1. **先 read / load，再写代码**。
+2. **有现成代码也必须先读**——已有实现、scaffold 文件、半成品代码都属于当前项目现实，不能当成不存在。
+3. **Feature 不是背景信息，而是验收 checklist**——实现结束前必须逐项 review。
+4. **流程不是填表，而是少返工策略**——Skill 读取、scaffold 采用、placeholder 物化和最小闭环装配，都是为了先建立可靠的工程判断，避免后面重写、绕开或猜测。
+
+**资产策略（build 环）**：**能用占位图就用占位图** — 目标是玩法可玩、程序正常执行，不考虑视觉表现力。
+
+严格按三档执行 — **(1)** plan/ref-flow 已 link 的 Skill 资产直接用；**(2)** 合约路径需要静态图片的 → `npm run placeholder:gen`；已 load 的 MP3 路径 → `npm run placeholder:gen-audio`；**(3)** 占位文件不可行的（动态数字、计时文本、纯事件钩子）→ 最小化代码绘制，并在 `developer-log` 记录原因。先读 **`skills/playable-placeholder/SKILL.md`**。详见 [`developer-impl-cookbook.md` § Asset Placeholder Strategy](./developer-impl-cookbook.md#asset-placeholder-strategy-phase-1)。
+
+---
+
+## 入场状态认知（先读这里）
+
+在开始任何工作之前，先建立对当前项目状态的正确认知：
+
+**你进来时项目已经是这个状态：**
+
+- 当 `state:get` 披露 `docs/atom-tree.json` 时，`meta.selectedAtoms` 对应 skill 文件可能已在 `.claude/skills/<skillRef>/` 下；如果缺失，按当前 Ring 命令补齐，不要提前读取未披露材料。
+- `game/` 目录下可能已有 scaffold 文件或半成品代码，这些是当前项目现实的一部分，不是草稿
+- 你的工作起点是**读懂当前项目现实**，而不是从零开始铺代码
+
+**scaffold 的正确定位：**
+
+- scaffold 的产出是一个**可运行的项目骨架**，目标是在这个骨架上按 feature 适配，而不是把 scaffold 文件当成草稿重写
+- scaffold 必须由已披露的 `docs/atom-tree.json` 的 `meta.engineDecision.adapter` 选择；不要把 Ring 1 快路径理解为固定 Phaser 模板。不同 engine root（Phaser / Three.js）有不同初始化逻辑，但都必须暴露同一个 `window.__playable` 运行时契约。
+- **Ring 1 scaffold 前置链（legacy：仅在 `state:get` 披露且无 active slice 时执行，不静默覆盖）**：
+
+```bash
+# First inspect the disclosed action surface.
+npm run state:get -- --json
+# Must already be produced by the temporary ref-flow atom-selection subagent:
+# docs/atom-tree.json
+playcraft remix init-template --from-atom-tree
+npm install
+npm run verify:contract
+npm run verify:lifecycle
+npm run verify:firstwin
+npm run verify:placeholders
+```
+
+- scaffold 文件是已经落地到项目里的 **Skill implementation asset**：先判断它承载了哪个 Skill decision，再决定如何适配；不要把它当成可以随手覆盖的生成初稿
+- scaffold 是一个**选择性动作**，只在读完 skill ref 和当前项目代码之后，判断确实需要骨架支撑时才执行
+- **先读 skill ref，再决定是否 scaffold**；不是先 scaffold 再理解工程
+
+---
+
+## Step 0：上游摄入（必须）
+
+在任何 `game/` 编辑之前，读取这些文档，并填写 **`logs/developer-log.md` § Upstream Intake**。
+
+| 文档 / 命令                           | 读取条件       | 需要从中获取的内容                                                           |
+| ------------------------------------- | -------------- | ---------------------------------------------------------------------------- |
+| `npm run state:get -- --json`         | 每次必读       | 当前 action、允许/禁止任务、当前必读文件、当前 verifiers、下一步命令         |
+| `npm run state:get -- --json`         | 每次必读       | 当前 `iteration` / `loop`、handoff、`devStatus`、`devBlockers`、当前停在哪里 |
+| `docs/DESIGN.md`                      | Ring 1+ 披露时 | Ring 1 玩法唯一来源：核心循环 / 规则 / 首关必赢策略 / `HOOK` 入口            |
+| `docs/atom-tree.json`                 | build 披露时   | 已选 `meta.selectedAtoms` skill refs；engine decision                        |
+| `docs/scaffold-manifest.md`（如存在） | build 披露时   | scaffold 已复制的文件 → skill atom 来源映射                                  |
+| `docs/implementation-plan.md`         | Ring 2+ 披露时 | Feature 列表 + 依赖图 + 首关策略 + Skill Support                             |
+| `docs/layout-spec.md`                 | Ring 2+ 披露时 | Zones、elementIds、assetMapping 路径、Atlas 分组                             |
+| `docs/style-exploration.md`           | Ring 3+ 披露时 | MC 面板 — UI（User Interface，用户界面）布局 + 视觉风格参考                  |
+
+> **Ring 1 禁止**读取 design-brief / layout-spec / implementation-plan — Ring 1 不产出这些，玩法以 DESIGN.md 为唯一来源，强读会膨胀上下文且无必要。
+
+> **要求**：不要只打勾，要在 `developer-log` 写一句“读到了什么、它会怎样影响实现”。
+
+## Step 2.4：场景模块拆分（Ring 1 硬约束）
+
+> **目标**：避免单文件 500+ 行导致 Write 截断重试与上下文膨胀（test4 曾用 `cat >>` 追加 6 次，浪费 6 轮往返）。
+
+- 按职责拆分 `game/`：`gameplay/`（纯逻辑）、`scenes/`（Phaser 场景壳）、`config/`（关卡/布局常量）
+- 单文件 **必须 ≤ 350 行**；超过则**必须**拆为子模块（board 渲染 / 输入 / HUD / endcard 分离）— 不可把整场景写进一个 `GameScene.ts`
+- 优先 **小步 Write / Edit** 分模块写入；**禁止** `cat >` / `cat >>` heredoc 拼接大文件
+- 若 Write 工具报 `InputValidationError`，拆文件而非改用 Bash heredoc
+
+## Step 1：Disclosure Quick-Check + Feature Checklist 建立
+
+在写代码前，先做两个动作。
+
+### 1) Disclosure Quick-Check
+
+确认：
+
+- `state:get` 的 `currentAction` 与 JSON 状态中的当前 `iteration` / `loop` 一致
+- 本轮只读取 `currentRingRequiredFiles`；`deferredFiles` 只能作为未披露材料记录，不能变成当前实现输入
+- Ring 1 的缺口只围绕核心玩法、`HOOK`、`autoPlay()`、`ENDCARD`、首关可胜判断
+- Ring 2+ 才检查 `layout-spec.md` / `implementation-plan.md` 是否能映射到当前项目结构
+
+如果发现缺口：
+
+- 记录到 `developer-log`，并用 `npm run state:set -- devBlockers=...` 写入 blocker
+- 路由给正确上游（Game Designer / Artist / TA）
+- **不要**靠臆测直接盲写替代逻辑
+
+### 2) Feature Checklist 建立
+
+把当前 Ring 披露的交付项转成真正的 checklist，写入 `logs/developer-log.md`：
+
+- feature 名称
+- 来源（plan / design / layout / Skill）
+- 依赖项
+- 关联代码入口
+- 完成标准
+- 本地验证方式
+
+Ring 1 checklist 至少包括：
+
+- `currentPhase` 初始为 `HOOK`
+- 核心玩法 loop 可执行
+- `autoPlay()` 通过玩家可用动作推进到 `ENDCARD`
+- 首关必赢策略已落地
+- `verify:contract` / `verify:lifecycle` / `verify:firstwin` / `verify:placeholders` 可通过
+
+Ring 2+ 才把 `docs/implementation-plan.md` 中本轮需要交付的 feature 和 `§ 8 Delivery Checklist` 并入 checklist。
+
+> **要求**：后续 ready 判断基于这个 checklist，而不是"感觉差不多做完了"。
+
+## Step 2：上下文组装和项目整备（必须）
+
+在任何实质性实现之前，先完成 **project context + linked atom skill context + selective scaffold decision + placeholder materialization + Skill-to-Prototype Assembly**，并把结果写进 `logs/developer-log.md` § `Skill Preflight`、§ `Read / Load Log` 与 § `Skill-to-Prototype Assembly (Project Assembly Checkpoint)`。
+
+**本阶段目标**：把 selected Skills 转成当前项目里的最小可运行玩法骨架。它不是额外流程记录，而是为了避免三类返工：误读 Skill ref 后重写对象模型、把 scaffold 文件当草稿覆盖、feature 写到后期才发现核心状态流不通。
+
+**完成前不要开始写 feature 逻辑。** 如果你觉得这一步浪费时间，通常说明你还没有从 Skill 中抽出可运行的最小闭环；此时直接写 feature 更容易返工。
+
+> **前提**：只在 `state:get` 披露 `docs/atom-tree.json` 后读取 selected atom refs。Developer 的职责是读取这些 linked atom refs，并判断是否需要 scaffold。
+
+### 2.1 先读当前项目现实
+
+读取并记录：
+
+- 入口文件
+- 当前 scene / state / config / gameplay 相关文件
+- 任何将被改动的已有文件
+- 任何已经 scaffold 到项目里的相关代码
+- 当前磁盘上的 linked assets
+- atlas / frame / contract path 绑定方式
+
+**要求**：不能因为已有文件存在，就把它当作黑盒直接覆盖；也不能因为 scaffold 代码已经在项目里，就跳过来源理解。
+
+### 2.2 Load linked atom skill refs
+
+基于当前 Ring checklist 读取相关 linked atom skill。Ring 1 以 `docs/DESIGN.md` 和 `docs/atom-tree.json` 为输入；Ring 2+ 才加入 `docs/implementation-plan.md` 与更深 reading guide。这里的目标不是把 `ref/` 当文件桶全量扫一遍，而是先理解 Skill package 的意图、对象模型和可继承判断，再选择真正相关的 recipe / `ref/` / source。
+
+1. 优先读项目本地 `.claude/skills/<skillRef>/SKILL.md`
+2. 再按 `SKILL.md`、`docs/atom-tree.md` 的 `readFirst` / `devReadOrder` 读取相关 `ref/` 或 source code
+3. 若本地 link 缺失，才使用 `playcraft skills read <skillRef>` fallback
+4. 对每个 relevant atom 在 `developer-log.md` 记录：
+   - `skillRef`
+   - 关联 Feature
+   - 已读入口（SKILL.md / ref / source / CLI fallback）
+   - 本轮采用方式：`read-only` / `scaffold-candidate` / `skip-with-reason`
+
+**偏航识别**：如果你正在反复使用类似 `glob ref/**/*` 的方式找信息，通常说明你把 Skill refs 当成了散装文件目录。先回到 `.claude/skills/<skillRef>/SKILL.md` 和 atom-tree reading guide，确认 Skill root、对象模型、关键 ref，再读取具体文件。
+
+**要求**：selected atom skill 是实现参考，不是可选灵感；即使代码已经复制进工程，也必须回读对应 Skill 的 recipe / `ref/` / source。
+
+### 2.3 Selective scaffold decision
+
+只有在读完项目代码和 linked atom refs 后，才判断是否需要 scaffold。
+
+**第一步：检查 `docs/scaffold-manifest.md` 是否存在。**
+
+- **存在**：说明本项目已经跑过 scaffold。必须先读 `docs/scaffold-manifest.md`，了解已有骨架的文件列表和 atom 来源，再判断是否需要补充 scaffold（通常不需要再跑）。不能因为"想重新生成"就重复执行。
+- **不存在**：说明还没有骨架，按下方判断条件决定是否首次执行 scaffold。
+
+**必须在 `logs/developer-log.md` § Skill Preflight 中明确记录决策**：每个 relevant atom 标注 `scaffold-candidate` 或 `skip-with-reason`，并在该 section 末尾写一句总结性决策说明（如 "本轮 scaffold: none, because ..." 或 "本轮 scaffold: atomX, atomY, because ..."）。**没有决策记录，不能进入 Step 3 实现。**
+
+**scaffold 之后的目标状态**：你会得到一个可运行的项目骨架。你的工作是在这个骨架上按 feature checklist 逐项适配，而不是把 scaffold 文件当成草稿重写。scaffold 文件和你自己写的代码地位相同，都必须先读懂再改。
+
+**替换前先判断文件身份**：如果你准备从零重写某个 scaffold / existing file，先写清它承载的 Skill decision 是什么，以及项目约束是否真的推翻了这个 decision。多数情况下应该适配 scaffold 边界，而不是绕开它重写同类模块。
+
+允许 scaffold 的典型情况：
+
+- 当前项目缺少共享入口代码或运行时骨架
+- 某个 Feature 明确需要 Skill 的 L3/L4 代码结构
+- 手写会明显增加集成风险，而 scaffold 后可以更快适配现有工程
+
+不应 scaffold 的情况：
+
+- 只是想
+- 只是想“看看会生成什么”
+- 某个 atom 只提供设计思路 / 参数参考 / 视觉参考
+- 当前 Feature 只需要读取 ref 后自行实现
+- 一次性把所有 shortlisted atoms 都铺进项目，导致后续理解成本失控
+
+执行格式（**两种 scaffold，勿混用**）：
+
+```bash
+# 引擎 scaffold — ring 1 build 前由 orchestrator 执行（一次性 game/ 骨架）
+playcraft remix init-template --from-atom-tree
+
+# atom scaffold — build 环内按需复制 Skill 实现代码
+playcraft skills scaffold \
+  --engine <engine>          # from meta.engineDecision.adapter
+  --atoms "<atom1>,<atom2>,<atom3>"  # 只填本轮确认需要 scaffold 的 selectedAtomRef
+```
+
+### 2.4 Post-scaffold focused readback
+
+如果执行了 scaffold：
+
+- **必须读取 `docs/scaffold-manifest.md`**
+- 只聚焦读取本轮 scaffold 相关的 landed files
+- 回读对应 Skill 的 `SKILL.md` / `ref/` / source，确认 copied code 的来源与适配边界
+- 对实际会绑定到 Feature 的 contract assets 做必要的 `playcraft image info` / `playcraft audio info`
+
+**判断原则**：
+
+- **scaffold 不替代读 Skill ref**
+- **先读 ref，再决定 scaffold；不是先 scaffold 再理解工程**
+- **静态资源检查按 contract path / Feature 绑定驱动，不按磁盘库存全量扫**
+- **read / load / scaffold decision 是实现输入，不是可选附加项**
+
+### 2.5 Skill-to-Prototype Assembly (Project Assembly Checkpoint)
+
+在进入 Step 3 之前，必须完成一次 **Skill-to-Prototype Assembly**。目标不是产出最终美术，也不是补一段流程记录，而是把本轮采用的 Skill decision 转成当前项目里的最小可运行玩法骨架，让后续 feature 实现有稳定的对象模型、资源路径和状态流。
+
+这里的**最小闭环**必须由本轮采用的 Skill / ref 定义，而不是默认套用完整广告体验流程。某些 Skill 的最小闭环可能只有“生成局面 → 玩家操作 → 状态反馈 → 结算一次核心规则”；它不一定包含 Hook、Tutorial、EndCard 或 CTA。
+
+先回答三个工程问题：
+
+1. **What skill decisions am I inheriting?**
+   - 例如对象模型、规则归属、状态流、交互边界、资源组织方式。
+2. **What project-specific changes are required?**
+   - 例如当前玩法尺寸、素材 contract path、首关要求、UI 状态、平台运行时约束。
+3. **What is the smallest playable spine before feature expansion?**
+   - 例如加载局面、渲染核心对象、执行一次玩家操作、通过规则层反馈结果、完成一次结算。
+
+必须完成：
+
+1. **Scaffold adoption map**
+   - 如果存在 `docs/scaffold-manifest.md`，列出本轮会基于哪些 landed files 继续适配。
+   - 如果某个 scaffold 文件与 Feature 相关但不采用，必须记录 `ignore-with-reason`；不能绕开它重新手写同类模块。
+   - 对每个将改动或替换的 scaffold 文件，先说明它承载的 Skill decision，以及项目适配点。
+2. **Placeholder materialization**（先读 **`skills/playable-placeholder/SKILL.md`**，按 skill 5 步流程）
+   - Ring 1 只列出核心玩法所需的占位资源；Ring 2+ 再基于 `layout-spec.md` `assetMapping`、Feature 所需 UI / VFX（Visual Effects，视觉特效）列出全部视觉 + 音频合约路径。
+   - 已有文件：`playcraft image info` / `playcraft audio info` 验证。
+   - 缺失**静态图片**：`cp templates/gen-placeholders.template.mjs` → 填 `PLACEHOLDERS` → `node ta-workspace/scripts/gen-placeholders.mjs`。
+   - 缺失且 Preloader **已 load** 的 **MP3**：`cp templates/gen-placeholder-audio.template.mjs` → 填 `PLACEHOLDER_AUDIO` → `node ta-workspace/scripts/gen-placeholder-audio.mjs`。
+   - 不能用占位文件的（动态数字、纯事件钩子）：Tier 3 + developer-log 一行原因。
+   - 代码只引用本地 contract path；禁止 `Graphics` 色块代替 Tier 2 图片路径。
+3. **Minimal prototype wiring baseline**
+   - 建立 Feature → Skill/ref → scaffold/source file → asset contract path 的映射。
+   - 明确 Skill / ref 定义的最小闭环步骤，并确认每一步都有本地资源路径、代码入口和状态流转设计。
+   - Ring 1 必须具备 `HOOK` → player-reachable gameplay actions → `ENDCARD` 的轻量生命周期。Tutorial、CTA（Call to Action，行动召唤）fallback、完整广告节奏属于后续披露项；不要在 Ring 1 把它们当 blocker。
+   - 若某个必要资源没有 spec 尺寸或 contract path，记录 blocker 并 route upstream，不要用随意路径继续实现。
+
+**进入 Step 3 的条件**：`logs/developer-log.md` § `Skill-to-Prototype Assembly (Project Assembly Checkpoint)` 已记录继承的 Skill decisions、项目适配点、最小 playable spine、scaffold 采用、placeholder 生成结果、资源验证结果、Feature 映射、Skill/ref 最小闭环定义和剩余 blocker。否则不能开始 feature 逻辑实现。
+
+## Step 3：Per-Feature 确认与执行（不是盲拆 batch）
+
+基于 Feature Checklist 按依赖顺序逐个 feature 推进。可以按功能域分组，但每次落代码前都必须先完成该 feature 的确认，不要为了拆 batch 而拆 batch，也不要把实现建立在“之后再补读”的假设上。
+
+**核心纪律：每个 `game/` 代码变更都必须可追溯到当前正在执行的 Feature Checklist 项。** 如果你发现自己在写代码但说不上来是哪个 feature 需要的，停下来：先确认是不是漏读了已有实现、漏了上游约束、漏了 Skill/ref，还是 checklist 不够细。
+
+每个 feature 必须按以下顺序执行：
+
+1. **Feature intake**
+   - 对应当前 Ring checklist 哪一项
+   - 对应 Skill / ref 中的哪个玩法规则、交互模式或代码模式
+   - 是否受当前披露文件约束；Ring 1 只看 `DESIGN.md` / `atom-tree.json`，Ring 2+ 才看 `layout-spec.md` / `implementation-plan.md`
+2. **Implementation target confirmation**
+   - 会改哪些现有文件、scaffold 文件或新增哪些必要文件
+   - 这些文件是否都已经读过
+   - 是否有可复用的 Skill/ref/source 代码路径，不能绕开已有可用结构重新手写同类模块
+3. **Execution**
+   - 基于现有架构、scaffold 和 Skill/ref 模式落代码
+   - 只实现当前 feature 所需范围，不顺手重写无关模块
+4. **Feature-local validation**
+   - 至少检查该 feature 的主要交互、状态变更、资源绑定和失败边界是否成立
+   - 如果该 feature 是最小闭环的一部分，要确认它在 Skill/ref 闭环中的输入和输出是否接上
+5. **Checklist update**
+   - 更新为 `done / partial / blocked`
+   - 记录验证结果、假设和风险
+   - 如果未完成，明确是 spec-gap、资源缺口、已有代码理解问题，还是实现阻塞
+
+### 实现时的工作方式
+
+- 优先改对当前 feature 真正相关的代码，不要盲目重写整个模块
+- 如果已有实现与你的目标冲突，先判断是边界没兼容、理解偏差、还是更深层结构问题
+- 不要用“多加一个 if / else”掩盖没看懂的结构问题
+- 如果问题来自更深层系统边界，记录根因，不要只修表面
+
+## Step 4：Feature Checklist Review（验收必须项）
+
+实现完成后，必须做一次**以 feature 为中心**的 review，而不是只做泛泛的 dev smoke check。
+
+对 checklist 中每一项逐条确认：
+
+- [ ] 该 feature 的代码是否真的落地
+- [ ] 相关已有代码是否被正确理解和复用，而不是被绕开盲写
+- [ ] 相关 Skill / ref 是否真正被读过并起到作用
+- [ ] feature 的完成标准是否满足
+- [ ] feature 的边界条件是否至少被检查过核心路径
+- [ ] 若未完成，是否明确标记为 `partial` 或 `blocked`
+
+### Review 输出要求
+
+在 `logs/developer-log.md` 中写清：
+
+- 每个 feature 的状态：`done / partial / blocked`
+- 对应验证结果
+- 未完成原因
+- 是否还存在需要上游处理的问题
+
+> **没有完成 checklist review，就不能进入 ready 判断。**
+
+## Step 5：Dev 自检与 Ready 判断
+
+在 checklist review 完成后，运行：
+
+```bash
+npm run typecheck
+```
+
+Ring 1 build STOP 前还必须运行 objective self-gate（**脚本自带 dev server，禁止为跑 verify 而手动 `npm run dev`**）：
+
+```bash
+npm run verify:contract
+npm run verify:lifecycle
+npm run verify:firstwin
+npm run verify:placeholders
+```
+
+将 `verify:contract` / `verify:lifecycle` / `verify:firstwin` / `verify:placeholders` 的 pass/OK 结果写入 `developer-log` § Dev self-check。
+
+build 收尾：启动**一个**常驻 dev server 用于 Ring Gate 试玩，记录真实 URL 到 `devUrl`，**Ring Gate 前不要 pkill**：
+
+```bash
+npm run dev
+# 从终端输出读取 Local: http://127.0.0.1:PORT/ → 通过状态层写入 devUrl
+```
+
+至少验证：
+
+- [ ] Ring 1 主要状态可达（HOOK → Gameplay actions → ENDCARD）
+- [ ] 核心玩法循环正常（操作 + 响应 + 状态变更）
+- [ ] 首关保障玩家成功
+- [ ] 胜负条件正确触发
+- [ ] Ring 3+ 才检查 CTA 触发（mraid / FbPlayableAd / ExitApi / `window.open` 回退）
+- [ ] 无 Error-level console 错误
+- [ ] `devUrl` 已记录到 `developer-log` 和 `npm run state:get -- --json`
+
+### Ready 判断规则
+
+只有同时满足以下条件，才能设置 `devStatus: ready`：
+
+- Feature Checklist 没有未解释的空项
+- 所有 `blocked` 项都已经显式进入 `devBlockers` 或 routed upstream
+- 本地运行结果与日志描述一致
+- 当前项目现实下已经达到可交 Reviewer 的状态
+
+否则：
+
+- 可继续实现 → 继续回到 Step 3
+- 存在上游阻塞 → 设置 `devStatus: blocked_upstream`
+- 存在开发内阻塞但未就绪 → 保持非 ready 状态并明确记录
+
+## Step 6：STOP
+
+- 若 ready：设置 `devStatus: ready` + `devUrl`
+- 更新 handoff：ring 1 → `next_orchestrator_action: "npm run ring:gate -- --iteration 1"`；ring 2+ → `next_orchestrator_action: "Invoke @reviewer gameplay_conformance"`
+- 确认 `developer-log` 已能说明当前状态：上游摄入、Skill Preflight 证据、Read / Load 事实、Feature Checklist / Review 结果、Dev self-check，以及任何需要解释的 blocker
+- 追加 `--- PLAYCRAFT_STOP ---`（`role: developer`）
+
+---
+
+## Ring 4 production integration（TA Wave 2 之后 — mandatory）
+
+After `@technical-artist` STOP with `next_orchestrator_action: Invoke @developer (Ring 4 production integration)`:
+
+1. Read `logs/ta-log.md` Handoff + Production manifest — wire **every** delivered asset at `assetMapping` paths.
+2. Update `TILE_KEYS` / loaders so all new tiles (e.g. 6-color board) are referenced — run `npm run verify:asset-code-sync`.
+3. Remove or disable placeholder-only paths; ensure `bg_*` is a clean plate layer (z below tiles/HUD).
+4. Self-check: `npm run verify:ui` + `npm run dev` with `?debug=1`.
+5. STOP: `devStatus: ready` → `next_orchestrator_action: "Invoke @reviewer ui_diff"`.
+
+**Do not** route to `@reviewer ui_diff` until integration is complete — TA deliverables alone are insufficient.
+
+---
+
+## Rework（`ui_review` 之后）
+
+**ring 4 verify ui_diff 修复**不走完整 build flow。那时由 [`../developer.md`](../developer.md) 按 routed Action Items 执行 scoped fixes，并 handoff `Invoke @reviewer ui_diff`。
+
+---
+
+## 共享参考
+
+- 实现模式：[`developer-impl-cookbook.md`](./developer-impl-cookbook.md)
+- Dev 交接详情：[`developer-dev-handoff.md`](./developer-dev-handoff.md)

package/project-templates/threejs/.claude/agents/refs/framework-5-component-filter.md

@@ -0,0 +1,252 @@
+# 5-Component Filter 框架 — 机制好玩度快速检验
+
+## 原始来源
+
+- **出处**：https://mcpmarket.com/zh/tools/skills/game-design-framework
+- **性质**：这是一个 Claude Code Skill 中提出的实战框架，并非学术论文。它综合了多个游戏设计理论（MDA、Game Feel 等），形成了一套**快速可操作**的机制评估工具。
+- **关联理论**：
+  - Steve Swink 的 Game Feel 6 组件（Response 对应"实时控制"，Satisfaction 对应"多汁性"）
+  - MDA 框架的 Aesthetics 层（Motivation 对应"目标情感"，Fit 对应"整体一致性"）
+  - Nielsen 的可用性启发式（Clarity 对应"系统可见性"和"匹配现实世界"）
+
+---
+
+## 一、核心思想
+
+5-Component Filter 是一个**快速评估清单**，用于在设计和迭代阶段检验每一个游戏机制是否"好玩"。
+
+它的核心问题是：
+
+> **"这个机制通过了以下 5 项检查吗？如果任一项不通过，它就不会好玩。"**
+
+---
+
+## 二、5 个组件详解
+
+### 组件 1：Clarity（清晰度）
+
+> **核心问题：玩家在 3 秒内能看懂怎么玩吗？**
+
+| 维度             | 检查点                                                |
+| ---------------- | ----------------------------------------------------- |
+| **视觉可见性**   | 可操作对象是否视觉突出？能否一眼分辨什么能点/不能点？ |
+| **动作可猜测性** | 不看教程，玩家能猜到该做什么吗？                      |
+| **反馈明确性**   | 操作后发生了什么——成功还是失败——是否立刻清晰？        |
+| **状态可读性**   | 当前游戏状态（分数、剩余步数、进度）是否随时可读？    |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 零教程可上手，3 秒内理解玩法 |
+| ⭐⭐ | 需要 1 次提示或试错后理解 |
+| ⭐ | 需要文字教程或多次试错 |
+| ❌ | 5 秒后仍不知道该做什么 |
+
+**Playable Ad 中的硬约束**：
+
+> 在 Playable Ad 中，Clarity 是**生死线**。玩家不会花超过 3 秒去"学"一个广告。如果不能即刻理解，就会关闭。
+
+**常见修复手段**：
+
+- 手指引导动画（指示首次操作）
+- 高亮可操作区域
+- 第一步设计为"不可能失败"
+- 减少首屏信息量
+
+---
+
+### 组件 2：Motivation（动机）
+
+> **核心问题：玩家为什么想做这个动作？**
+
+| 维度           | 检查点                               |
+| -------------- | ------------------------------------ |
+| **目标可见性** | 玩家是否知道自己在朝什么目标努力？   |
+| **进度感**     | 每次操作后是否感到"离目标更近了"？   |
+| **奖励预期**   | 玩家是否期待下一个动作会带来好结果？ |
+| **紧迫感**     | 是否有时间/步数/空间等约束驱动行动？ |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 玩家主动想做、停不下来 |
+| ⭐⭐ | 知道该做什么但没有强烈冲动 |
+| ⭐ | 被动执行，缺乏内在驱动力 |
+| ❌ | "为什么我要做这个？" |
+
+**设计策略**：
+
+| 策略         | 机制示例                               | 适用场景   |
+| ------------ | -------------------------------------- | ---------- |
+| **可见目标** | 进度条、目标分数、"消除 30 个红色方块" | 所有类型   |
+| **短期奖励** | 每次匹配后的分数弹出、金币收集动画     | 休闲消除   |
+| **紧迫感**   | 倒计时、步数限制、上升的障碍           | 增加挑战感 |
+| **好奇心**   | 翻转显示隐藏图案、解锁新内容预览       | 探索发现类 |
+| **差一点感** | 失败时显示"还差 2 个就赢了！"          | 转化驱动   |
+
+---
+
+### 组件 3：Response（响应性）
+
+> **核心问题：操作后 100ms 内有反馈吗？**
+
+| 维度       | 检查点                               |
+| ---------- | ------------------------------------ |
+| **即时性** | 触摸/点击后有即时视觉+听觉反馈吗？   |
+| **多通道** | 反馈是否同时涵盖视觉+听觉（+触觉）？ |
+| **比例性** | 反馈强度是否与动作重要性成正比？     |
+| **一致性** | 相同操作的反馈是否每次都一致？       |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 每次操作都有多通道即时反馈，爽快利落 |
+| ⭐⭐ | 有反馈但单通道或有延迟感 |
+| ⭐ | 部分操作无反馈或反馈不一致 |
+| ❌ | 操作后没有任何可感知的变化 |
+
+**这与 Steve Swink 的 Game Feel 直接对应**：
+
+- 100ms 阈值 → 来自 Swink 的"实时控制"组件
+- 多通道反馈 → 来自 Swink 的"润色"组件
+- 比例性 → 来自 Swink 的"多汁性"组件
+
+**快速检查表**：
+
+```
+□ 点击有按下缩放效果？
+□ 松手有弹起动画？
+□ 匹配成功有消除动画？
+□ 消除有音效？
+□ 连击有升级反馈？
+□ 失败有挫败感反馈（但不惩罚）？
+□ 每一帧都有东西在动？
+```
+
+---
+
+### 组件 4：Satisfaction（满足感）
+
+> **核心问题：每次成功操作有"爽"的感觉吗？**
+
+| 维度           | 检查点                                         |
+| -------------- | ---------------------------------------------- |
+| **"啊哈"时刻** | 操作结果是否超出玩家预期？（如意外的连锁消除） |
+| **感官奖励**   | 成功是否伴随视觉+听觉的"爆发"？                |
+| **成长曲线**   | 随着游戏进行，满足感是否在升级？               |
+| **对比度**     | 成功与未成功之间的反馈差距是否足够大？         |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 每次成功都想"再来一次"，有近乎上瘾的满足感 |
+| ⭐⭐ | 成功有正反馈但缺乏"wow"时刻 |
+| ⭐ | 成功与失败的感觉差距不大 |
+| ❌ | 成功了也没什么特别感觉 |
+
+**满足感的层级设计**（对应 Juice 的"连击升级"）：
+
+```
+Level 1（单次匹配）  → 小粒子 + 轻音效
+Level 2（连击 ×2）   → 更多粒子 + 音高上升 + 飘字
+Level 3（连击 ×3）   → 屏幕震动 + 大粒子 + 连击文字
+Level 4（超级连击）   → 全屏特效 + 慢动作 + 欢呼声
+```
+
+> **关键洞察**：满足感 = Response（响应性）× Surprise（惊喜度）。同样的响应如果每次都完全一样，会逐渐麻木。适度的随机性和升级机制维持满足感。
+
+---
+
+### 组件 5：Fit（契合度）
+
+> **核心问题：这个机制与整体风格搭吗？**
+
+| 维度               | 检查点                                 |
+| ------------------ | -------------------------------------- |
+| **与主题一致**     | 机制是否与游戏的视觉主题和世界观匹配？ |
+| **与其他机制协同** | 这个机制是否与其他机制产生有趣的交互？ |
+| **与目标受众匹配** | 机制的复杂度是否适合目标玩家？         |
+| **与平台特性适配** | 机制是否利用了平台的特有输入方式？     |
+
+**评分标准**：
+| 等级 | 描述 |
+|------|------|
+| ⭐⭐⭐ | 机制与整体风格浑然一体、不可分割 |
+| ⭐⭐ | 机制与整体搭配，但有可改进空间 |
+| ⭐ | 机制感觉像是"外挂"上去的 |
+| ❌ | 明显与游戏整体格格不入 |
+
+**Fit 的检查维度扩展**：
+
+| 契合维度   | 好的例子                   | 坏的例子                 |
+| ---------- | -------------------------- | ------------------------ |
+| 主题契合   | 果冻消除游戏用"弹弹弹"动画 | 中世纪骑士游戏用霓虹粒子 |
+| 节奏契合   | 休闲消除的慢节奏配柔和配乐 | 放松游戏用高速闪烁特效   |
+| 复杂度契合 | 休闲广告用单指操作         | 休闲广告用 5 步组合操作  |
+| 平台契合   | 移动端用滑动/点击          | 移动端用双指旋转缩放     |
+
+---
+
+## 三、5-Component Filter 的使用方法
+
+### 方法 1：单机制评估卡
+
+评估一个具体的游戏机制（如"滑动交换两个相邻方块"）：
+
+```
+机制名称: [交换消除]
+┌──────────────┬────────┬─────────────────────────┐
+│ Component    │ Score  │ Notes                   │
+├──────────────┼────────┼─────────────────────────┤
+│ Clarity      │ ⭐⭐⭐  │ 滑动方向=交换方向，直觉  │
+│ Motivation   │ ⭐⭐⭐  │ 可见的目标分数+步数限制  │
+│ Response     │ ⭐⭐    │ 缺少消除音效，需补充     │
+│ Satisfaction │ ⭐⭐    │ 连锁反馈不够强烈         │
+│ Fit          │ ⭐⭐⭐  │ 与糖果主题完美搭配       │
+└──────────────┴────────┴─────────────────────────┘
+最低分: Response (⭐⭐) & Satisfaction (⭐⭐)
+优先改进: 添加消除音效 + 增强连锁视觉反馈
+```
+
+### 方法 2：多机制对比
+
+在 Brainstorm 阶段比较多个候选机制：
+
+```
+          Clarity  Motivation  Response  Satisfaction  Fit   Total
+方案A-滑动交换  ⭐⭐⭐     ⭐⭐⭐       ⭐⭐       ⭐⭐        ⭐⭐⭐   13
+方案B-点击选取  ⭐⭐      ⭐⭐        ⭐⭐⭐      ⭐⭐        ⭐⭐    11
+方案C-拖拽放置  ⭐⭐      ⭐⭐⭐       ⭐⭐       ⭐⭐⭐       ⭐⭐    12
+```
+
+### 方法 3：迭代检查点
+
+在开发过程中定期使用，特别是：
+
+1. **Brainstorm 后**：评估概念是否有基本的好玩潜力
+2. **原型完成后**：第一次可玩版本的快速健检
+3. **Juice 添加后**：确认 Juice 是否真的提升了各项分数
+4. **最终交付前**：确保没有组件被遗漏
+
+---
+
+## 四、快速诊断表
+
+当 QA 或玩家说"不好玩"但说不清原因时，用此表逐项排查：
+
+| 玩家的模糊反馈          | 最可能的缺失组件 | 优先修复方向                       |
+| ----------------------- | ---------------- | ---------------------------------- |
+| "不知道该干什么"        | Clarity          | 加引导动画、高亮可操作区           |
+| "没意思" / "为什么要玩" | Motivation       | 加可见目标、紧迫感、奖励预览       |
+| "操作没感觉" / "卡卡的" | Response         | 加即时反馈、音效、缓动动画         |
+| "赢了也没什么感觉"      | Satisfaction     | 加连击反馈、胜利演出、对比度       |
+| "感觉怪怪的" / "不搭"   | Fit              | 检查主题一致性、节奏匹配、平台适配 |
+
+---
+
+## 五、参考资源
+
+- 🔗 **框架来源**：[Game Design & Mechanics Framework (MCP Market)](https://mcpmarket.com/zh/tools/skills/game-design-framework)
+- 📕 **Clarity 理论基础**：Jakob Nielsen 的 [10 Usability Heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/)
+- 📕 **Response 理论基础**：Steve Swink 的 [Game Feel (2008)](https://www.taylorfrancis.com/books/mono/10.1201/9781482267334/game-feel-steve-swink)
+- 📕 **Motivation 理论基础**：MDA 框架的 [Aesthetics Taxonomy](https://www.researchgate.net/publication/228884866_MDA_A_Formal_Approach_to_Game_Design_and_Game_Research)