@playcraft/cli 0.0.44 → 0.0.47

package/project-template/.claude/agents/refs/implementation-plan-guide.md

@@ -0,0 +1,316 @@
+# Implementation Plan Guide — 开发执行计划
+
+> **用途**：Orchestrator 在 `planning` 阶段 spawn plan-writer subagent 时注入的执行指南。
+> Subagent 基于设计文档、layout contract、atom-tree 和 storyboard 参考，输出 **Developer 可直接执行的实践计划**：`docs/implementation-plan.md`。
+>
+> **Stage**: This subagent runs during the `planning` stage (after atom-tree is ready), not at the start of `development`. Developer enters `development` with a ready execution blueprint.
+>
+> **不是做什么**：
+>
+> - 不是完整工程设计文档
+> - 不是代码草图文档
+> - 不是 file tree / interface / pseudo-code 说明书
+>
+> **产出终点**：`docs/implementation-plan.md` 写入完成，并可被 Developer 直接按顺序执行。
+
+## 输入（subagent 自行读取）
+
+| 文件                        | 关注内容                                                                                                                      |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `docs/design-brief.md`      | 核心玩法循环、规则、胜负条件、Experience Flow、首关保证意图                                                                   |
+| `docs/DESIGN.md`            | 玩家体验契约、反馈重点、阶段节奏、可读性要求                                                                                  |
+| `docs/layout-spec.md`       | zone 布局、assetMapping、atlasPath/frameId、契约路径                                                                          |
+| `docs/atom-tree.json`       | `meta.selectedAtoms`（selected skill refs）、`skillsMatch.matches`、`skillsMatch.mediaGroups`                                 |
+| `docs/atom-tree.md`         | `Acceptance Criteria`、`Selected Gameplay Trunk`、`Gameplay Assembly Link`、`Selected Skill Notes`、`Role Resolution`、`Gaps` |
+| `docs/style-exploration.md` | MC 面板与 UI 目标参考                                                                                                         |
+
+**优先级**：`design-brief` 核心玩法 > `DESIGN` 体验约束 > `layout-spec` 契约路径 > `atom-tree` 借鉴与覆盖提示 > MC 视觉参考
+
+**重要边界**：
+
+- `atom-tree` 是 **借鉴/引用输入**，不是后续制作流程的主轴
+- 可以引用 selected atom / skillRef / mediaGroups 帮助规划，但不要把整个计划写成 atom 镜像
+- 计划的主轴必须是 **面向玩家结果和验收的 Feature**；实践分层只用于思考覆盖面与实现边界，不作为输出章节或拆分主轴
+- `DESIGN.md` / `design-brief.md` 中已经明确写过的体验叙述，不要在 plan 中大段复述；plan 只保留会影响实现取舍、验收或 Feature 拆分的关键信息
+- 输出优先遵循本 guide 定义的章节和字段；template 是初始化骨架，不是更高优先级规范
+- 允许在不破坏主结构的前提下补充少量高价值说明，但不要新增压过主结构的大章节
+
+---
+
+## Step 1 — 提炼 Feature 主线
+
+先把计划的主线从"玩法承诺"收敛成"少量可执行的 Feature"。
+
+每个一级 Feature 应同时满足：
+
+- 玩家可感知
+- 可以独立验收
+- 依赖关系清晰
+- 可以作为一次实现 / 集成单位
+
+### 可用思考维度（仅供收敛，不单独输出为章节）
+
+| 维度               | 用途                     | 典型内容                                         |
+| ------------------ | ------------------------ | ------------------------------------------------ |
+| `Data`             | 静态配置与棋盘/关卡/常量 | board preset, tile catalog, level config         |
+| `Runtime Data`     | 运行时状态与状态机       | scene state, selected item, timers, result state |
+| `Gameplay Feature` | 核心玩法闭环             | 规则判定、操作响应、胜负推进                     |
+| `Panel`            | 面板/场景/阶段容器       | Hook, Tutorial, Gameplay, EndCard, CTA           |
+| `Visual Feature`   | 玩家能感知到的反馈与表现 | hint、glow、VFX、audio trigger、readability cues |
+
+这些维度用于帮助判断：
+
+- 某个 Feature 覆盖了哪些实现面
+- 是否遗漏了关键边界
+- 哪些 Feature 会共享 runtime boundary
+- 哪些地方会直接影响"首关必胜"
+
+**不要**把这些维度直接抄成 plan 的一级章节，也不要因为某个维度或 skill hit 很多就继续拆更多 feature。
+
+输出时必须让 Developer 一眼看到：
+
+- 先实现哪几个 Feature
+- 哪些 Feature 依赖哪些基础
+- 哪些可以并行
+- 哪些直接影响"首关必胜"
+
+---
+
+## Step 2 — 提炼复用输入，但不要被其绑架
+
+### 2.1 读取可借鉴输入
+
+从 `atom-tree.json` / `atom-tree.md` 里提炼：
+
+- 哪些 selected `skillRef` 明显能借鉴
+- 哪些 `mediaGroups` 可以直接 link
+- 哪些 `Acceptance Criteria` 必须在计划里兑现
+- `Gameplay Assembly Link` 暗示了哪些 trunk-adjacent references 值得先读
+
+### 2.2 Feature 关键实现输入
+
+计划中保留一张 **Feature 关键实现输入表**，用于告诉 Developer 执行每个 Feature 时应该优先阅读哪些 atom / skill / media reference，以及为什么它们和该 Feature 的实现直接相关。
+
+| Feature                  | Must-read Atoms / Skills                                      | Why It Matters                       | Adaptation Notes                              |
+| ------------------------ | ------------------------------------------------------------- | ------------------------------------ | --------------------------------------------- |
+| {例如：Board Foundation} | `phaser.aicomponent`, `grid_board_layout.aicomponent`         | 引擎入口和棋盘几何会直接决定实现起点 | 复用生命周期和布局算法，改写棋盘 mask / style |
+| {例如：Core Interaction} | `path_elimination_rules.aigameplay`, `path_input.aicomponent` | 点击、阻挡、消除、胜负判定是核心闭环 | 复用规则合同，适配本项目边界和反馈            |
+| {例如：Custom End Flow}  | —                                                             | 无直接可复用 atom                    | From-scratch，并说明现有输入缺口              |
+
+规则：
+
+- 不要求每个 Feature 都硬绑 atom，但如果某个 selected `skillRef` / `mediaGroup` / trunk-adjacent reference 对实现有直接帮助，必须在计划中承认它
+- 不设置固定数量上限；每个 Feature 应列出实现该 Feature 时 **必须先读或明显能省事** 的关键 atom / skill，数量由 Feature 复杂度决定
+- 不为了覆盖完整而罗列无执行价值的 atom；每个条目必须说明它影响哪个实现点、是直接复用、改写、借鉴模式，还是明确不用
+- L0 / From-scratch 项应简述为什么现有输入不够，避免 Developer 误以为遗漏了可复用内容
+- 这张表是 Developer 的阅读顺序提示；Feature 详细清单中的 `Key Implementation Inputs` 负责说明具体 Feature 内怎么用
+
+### 2.3 风险项
+
+**风险项的定义边界**：只收"当前无法确定答案"的开放问题，不收"已有方案但要提醒一下"的实现细节。
+
+判断标准：如果你已经知道怎么做了，就不是风险，放到对应 Feature 的 `Acceptance` 或 `Implementation Locus` 里。
+
+典型的真正风险：
+
+- 算法正确性无法在 Phase 1 验证（需要真实数据才能确认）
+- 首关必胜的容错边界不确定（依赖 playtesting 才能定）
+- 某个交互效果需要 TA / Artist 配合才能判断可行性
+
+**不是风险的内容（不要放进风险表）**：
+
+- 资产占位处理方式（这是已知流程，见下方说明）
+- 音频实现方式（Phase 1 只挂事件钩子，已有规范）
+- 任何"已经想好怎么做了"的实现细节
+
+### 2.4 资产占位策略（plan-writer 必读）
+
+build 环原则：**能用占位图就用占位图；不能用占位图的才代码绘制。不考虑视觉表现力，只保证玩法可玩、程序正常执行。**
+
+| 情况                                       | build 环处理方式                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------------------- |
+| ref-flow 已 link（mediaGroups 有匹配）     | Tier 1：直接绑定合约路径                                                        |
+| 无匹配，且 `assetMapping` 期望静态图片文件 | Tier 2：`npm run placeholder:gen` 生成到合约路径                                |
+| Preloader 已 load 的 MP3 缺失              | Tier 2：`npm run placeholder:gen-audio`（先读 `playable-placeholder` skill）    |
+| 动态数字 / 计时文本 / 无图片合约路径       | Tier 3：最小化代码绘制（`fillText` / DOM / `Graphics`），developer-log 记录原因 |
+| 音频                                       | Tier 3：只在正确时机 `emit` 命名事件，不实现播放                                |
+
+**禁止写法**：
+
+- 用 Phaser `Graphics` / canvas 色块**代替**本该生成的占位图文件（有 `assetMapping` 路径时必须先 Tier 2）
+- AI 生成图片、手绘占位图、build 环视觉打磨
+- Web Audio 合成占位音
+
+ring 4（TA 交付后）：TA 把真实文件放到合约路径，代码零改动。
+
+---
+
+## Step 3 — 组织 Feature，不要写成架构白皮书
+
+### Feature 组织原则
+
+- 按 **用户可感知能力** 组织
+- 不按"先写什么文件"组织
+- 不按纯技术 Phase 编号组织
+- 不按 layer 或 skill 命中数扩增一级 feature
+- 不写完整接口 / file tree / pseudo-code
+
+### 推荐 Feature 形态
+
+```text
+Board / Foundation Setup
+Core Interaction Loop
+Tutorial + First-level Success Control
+Feedback + Readability
+End Flow + CTA
+```
+
+如果某个游戏确实需要不同命名，也要保持同样的原则：**面向玩家结果、可独立验收、依赖清楚**。
+
+### Feature 依赖图
+
+输出 ASCII 图，表达：
+
+- 哪些 shared foundation 先行
+- 哪些 Feature 依赖 Runtime Data / scene flow
+- 哪些反馈表现挂在已有 gameplay 事件上
+- 哪些直接影响首关必胜
+
+---
+
+## Step 4 — 写入 `docs/implementation-plan.md`
+
+初始化时直接参考 [templates/plan.template.md](../../../templates/plan.template.md)。
+
+### 强制结构
+
+1. 核心玩法概述
+2. Feature 关键实现输入
+3. Feature 依赖图
+4. Feature 详细清单
+5. 首关保证策略
+6. 风险与开放问题
+
+### 默认写法
+
+- 以 6 个主章节为正文骨架
+- **Feature 详细清单** 应该是全文主体，信息密度最高
+- `核心玩法概述` 只做实现上下文，不复写 `DESIGN.md` 的完整体验文案；玩法循环最多 1 段，关键规则控制在 3-5 条
+- 允许在章节内部补少量辅助说明，但不要再扩成新的主线章节
+- 除非任务显式要求，否则不要额外加入 `Architecture`、`Implementation Order`、`Asset Pipeline`、`Scene Flow`、`File/Module Structure` 这类大章节
+- 如果确实需要补充实现顺序，请压缩到依赖图说明或 Feature 条目里，不要覆盖主结构
+
+### 每个 Feature 必须包含的字段
+
+```markdown
+### Feature: {名称}
+
+- **Outcome**: {玩家实际会看到/做到什么，合并原 Goal + Player-visible Outcome，避免重复设计复述}
+- **Depends On**: {无 / Feature X / Feature Y}
+- **Key Implementation Inputs**: {skillRef / atom / mediaGroup} L{0-4} — {在本 Feature 的实际参考价值；可多项，按阅读优先级排列}
+- **Implementation Focus**: {实现重点和边界，语义级即可，如 GameScene state / board preset / tutorial panel}
+- **Acceptance**: {2-4 条可验证完成标准}
+- **First-Level Success Impact**: {对首关必胜的影响，没有就写 none}
+```
+
+`Layers Touched` 只作为 plan-writer 自检维度，不再作为 Feature 必填输出字段。
+
+### Skill Support / Key Implementation Inputs 怎么写
+
+**目的**：让 Developer 在执行到这个 Feature 时，知道"哪些 atom / skill / media reference 值得先读"，而不是从零开始自己想。这不是展示覆盖率，而是执行入口：告诉 Developer 读了能省多少事、参考什么、需要怎么改。
+
+**格式**：`{skillRef 或 atom 名称} L{0-4} — {一句话说明在本 Feature 的实际参考价值}`
+
+**级别含义**（对应 `skill-value-layers.md` 复用级别）：
+
+| 级别 | 含义                    | Developer 期望行为                       |
+| ---- | ----------------------- | ---------------------------------------- |
+| L4   | 有完整可用实现          | 先读 SKILL.md Code 段，理解后适配参数    |
+| L3   | 核心算法/架构可复用     | 读 SKILL.md 提取核心逻辑，在此基础上改写 |
+| L2   | 设计模式/思路有参考价值 | 扫一眼借鉴思路，自己实现                 |
+| L1   | 仅配置/参数有参考       | 快速看下默认值和边界条件                 |
+| L0   | 无参考 / From-scratch   | 不需要读 Skill                           |
+
+**示例**：
+
+```markdown
+- **Key Implementation Inputs**:
+  - `layered-stack-board-phaser` L4 — 入场动画算法 + AABB 遮挡检测完整实现可直接适配
+  - `responsive_2d_layout.aicomponent` L3 — 720x1280 安全区和缩放策略可复用，需替换本项目 zone
+  - `match-pop.aicomponent` L2 — 粒子爆发效果思路可参考，但需改为双牌同时消除
+- **Key Implementation Inputs**: none (L0) — 自定义状态机，无现有 Skill 覆盖
+```
+
+**约束**：
+
+- 不设置每个 Feature 的固定 Skill Support 数量上限；数量由 Feature 实现需要决定
+- 只列 Developer 在实现该 Feature 时应该优先打开阅读的关键输入，避免把 `atom-tree` 全量镜像到 plan
+- Skill Support / Key Inputs 必须说"在本 Feature 能帮什么"，不能只写"这个 Skill 存在"
+- 同一个 atom 可出现在多个 Feature 中，但每次都要说明它在该 Feature 下的不同作用
+- L0 的 Feature 可以省略 Key Inputs 行或写 `none`
+
+**禁止**：
+
+- TypeScript `interface`
+- 伪代码算法
+- 完整 scene/file 树
+- `src/...` 级别的 file allocation 清单
+- "Feature 1/2/3 = 技术施工阶段"式线性工程流水账
+
+### Implementation Locus 怎么写
+
+允许：
+
+- `board preset data`
+- `gameplay runtime state`
+- `tutorial overlay panel`
+- `result transition flow`
+- `selection feedback pipeline`
+
+不允许：
+
+- `src/game/board/FreeTileDetector.ts`
+- `interface Tile`
+- `function isTileFree(tile, board)`
+
+---
+
+## Step 5 — 写入 Delivery Checklist
+
+在 `docs/implementation-plan.md` 的 `## 8. Delivery Checklist` 节，从 `DESIGN.md` 和 `layout-spec.md` 提取**可在代码/运行时验证的具体约束**，每项一行。
+
+**格式**：`- [ ] {具体约束} — source: {来源文件}`
+
+**提取原则**：
+
+- 只提取"做错了玩家会直接感知到"的约束，不是所有设计细节
+- 每项必须是可验证的（能在浏览器/代码里确认 pass/fail），不是"做好 UI"这类模糊描述
+- 典型来源：layout zone 边界、UI 可见性时机、交互可达性、关键资产接入要求
+- 数量控制在 5-10 项，覆盖最高风险点即可
+
+**重要**：这个节不是给 Developer 开发时看的，是给 `validate-workflow-stop` hook 在 Developer 自报完成时做验证用的。plan-writer 必须写，Developer 不需要主动查阅。
+
+---
+
+## 完成条件
+
+| #   | 检查项                 | 标准                                                                                                       |
+| --- | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
+| 1   | 计划定位正确           | 是执行计划，不是工程设计白皮书                                                                             |
+| 2   | 主轴正确               | 以 Feature 执行为主，不按 layer / skill 命中数拆分                                                         |
+| 3   | Skill Support 覆盖充分 | Feature 的关键实现输入已覆盖相关 selected skillRef / atom / media reference，且说明了在该 Feature 中的用途 |
+| 4   | From-scratch 可解释    | L0 Feature 没有现有 Skill 覆盖时有理由                                                                     |
+| 5   | Feature 可执行         | 每个 Feature 都有 Outcome / Depends / Acceptance / Implementation Focus                                    |
+| 6   | 首关必胜闭环           | 有专门策略，并映射到相关 Feature                                                                           |
+| 7   | 无代码污染             | 无接口、伪代码、file tree、源码路径清单                                                                    |
+| 8   | Developer 可直接执行   | Developer 无需再次推导计划结构                                                                             |
+
+---
+
+## 注意事项
+
+- **计划服务开发执行，不服务炫技说明**
+- **玩法完整性优先于架构漂亮**
+- **复用输入要承认，但不要被 atom-tree 绑成后续制作流程**
+- **允许写 Implementation Locus，不允许写代码结构**
+- **允许写执行顺序，但应从属于主结构，不要写成新的大章节**