@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/skills/playcraft-vfx-animation/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: playcraft-vfx-animation
+description: VFX 特效与动画精灵图选型决策树与核心命令速查。按游戏事件快速选定预设，详细预设目录见 refs/ta-vfx-preset-catalog.md。
+triggers: VFX,特效,动画,animate,animation,use-vfx,精灵动画,sprite animation,爆炸特效,闪光效果,vfx预设,animate预设,bounce,spin,pulse,shake,float,blink,swing,wobble,flip,confetti,sparkle,explosion,starburst,smoke,glow,impact
+---
+
+# PlayCraft VFX 特效与动画精灵图生成指南
+
+## 0. Overview
+
+VFX（视觉特效精灵图）和 animate（运动动画精灵图）是可玩广告视觉品质的关键层。它们属于 TA 工作流的 **Stage B**（精灵图处理阶段），在 Stage A 元素生成完成后执行。
+
+- **VFX**：预制粒子/爆炸/光效精灵表，用于游戏事件反馈（消除、得分、胜利等）
+- **animate**：将静态素材转为循环动画精灵表，用于 idle 状态、UI 引导、装饰运动
+
+**发现可用预设**：
+
+```bash
+playcraft image list-vfx            # 列出所有 VFX 预设（含帧数、体积）
+playcraft image animate --list-presets  # 列出所有 animate 预设
+```
+
+## 1. VFX 选型决策树
+
+按游戏事件选择预设：
+
+```
+需要为哪种游戏事件添加 VFX？
++-- 元素消除/击破 -> explosion_small (8帧, ~30KB)
+|   理由: 中心爆发+碎片扩散, 8帧在视觉冲击与体积间取得平衡
++-- 得分/收集奖励 -> sparkle (6帧, ~15KB)
+|   理由: 轻量粒子迸发, 15KB 可高频触发而不累积体积压力
++-- 关卡完成/大胜利 -> confetti (12帧, ~25KB)
+|   理由: 多彩纸片飘落, 12帧保证庆祝感的持续时长
++-- 连击触发/特殊技能 -> starburst (8帧, ~20KB)
+|   理由: 金色放射线条, 视觉冲击强且不遮挡游戏元素
++-- 元素消失/冲刺残影 -> smoke (8帧, ~20KB)
+|   理由: 烟雾自然消散, 柔和过渡不抢视觉焦点
++-- 元素高亮/选中状态 -> glow (6帧, ~10KB)
+|   理由: 最小体积, 适合持续循环播放(选中状态)
++-- 落地/点击反馈 -> impact_ring (6帧, ~15KB)
+|   理由: 快速扩散环, 6帧短促匹配瞬时反馈的时间尺度
++-- 金币/货币拾取 -> coin_collect (8帧, ~20KB)
+    理由: 专用金色闪光发散, 与通用 sparkle 区分货币语义
+```
+
+## 2. Animate 选型决策树
+
+按运动需求选择预设：
+
+```
+需要什么运动效果？
++-- 引起注意(CTA/重要按钮) -> pulse (缩放脉冲, 周期1.5-2s)
+|   理由: 缩放振荡是最有效的注意力引导, 不依赖位移空间
++-- 持续旋转(加载/转盘/金币) -> spin (X轴缩放模拟Y轴旋转)
+|   理由: 2D压缩模拟3D翻转, 适合圆形/对称元素
++-- 弹跳反馈(点击/收集/idle) -> bounce (Y轴正弦平移)
+|   理由: 最自然的"活着"感, 适用面最广
++-- 错误/警告/受击 -> shake (随机小幅XY偏移)
+|   理由: 随机位移制造紧张感, 强制引导注意力
++-- 悬浮装饰(idle/魔法道具) -> float (轻柔漂浮+微旋转)
+|   理由: 比bounce更轻柔, 加入+-3度旋转增添神秘感
++-- 闪烁提示(光标/倒计时) -> blink (不透明度振荡)
+|   理由: 最简单的"请注意我"动画, 最小视觉干扰
++-- 钟摆装饰(悬挂物/灯笼) -> swing (绕顶部中心摆动)
+|   理由: 物理感强, 专为"挂着"的元素设计
++-- 可爱/卡通idle(果冻/气泡) -> wobble (左右交替小幅旋转)
+|   理由: +-5-10度交替旋转产生弹性感, 适合软体元素
++-- 卡牌翻转/3D旋转 -> flip (需要正面+背面两张素材)
+    理由: 完整正面->过渡->背面翻转; 详见 ta-3d-flip-recipe.md
+```
+
+## 3. Core Commands
+
+### use-vfx 完整示例
+
+```bash
+playcraft image use-vfx \
+  --preset explosion_small \   # 预设名(必填), 从决策树选定
+  --tint "#FF6B35" \           # 颜色叠加(可选), hex格式, 按元素颜色调整
+  --scale 1.2 \                # 缩放(可选, 默认1.0), 范围0.5-3.0
+  --output assets/images/vfx/tile_break.png  # 输出路径(必填)
+```
+
+| 参数       | 类型   | 默认值     | 说明                 |
+| ---------- | ------ | ---------- | -------------------- |
+| `--preset` | string | 必填       | VFX 预设名           |
+| `--output` | string | 必填       | 输出精灵表路径(.png) |
+| `--tint`   | hex    | 预设默认色 | 颜色叠加 `#RRGGBB`   |
+| `--scale`  | number | 1.0        | 整体缩放(0.5-3.0)    |
+
+### animate 完整示例
+
+```bash
+playcraft image animate \
+  --input assets/images/ui/cta_button.png \  # 输入静态素材(必填)
+  --preset pulse \             # 动画预设(默认bounce)
+  --frames 8 \                 # 总帧数(2-64, 默认8)
+  --columns 4 \                # 精灵表列数(默认4)
+  --output assets/images/ui/cta_button_pulse.png  # 输出路径(必填)
+```
+
+| 参数        | 类型   | 默认值 | 说明                    |
+| ----------- | ------ | ------ | ----------------------- |
+| `--input`   | string | 必填   | 输入图片路径            |
+| `--output`  | string | 必填   | 输出精灵表路径(.png)    |
+| `--preset`  | string | bounce | 动画预设名              |
+| `--frames`  | number | 8      | 总帧数(2-64)            |
+| `--columns` | number | 4      | 精灵表列数              |
+| `--back`    | string | 无     | flip 专用: 背面图片路径 |
+
+## 4. Post-Generation Checklist
+
+| 检查项             | 方法                               | 不通过时                     |
+| ------------------ | ---------------------------------- | ---------------------------- |
+| 帧数与预设规格匹配 | 计算精灵表格子数 = 行x列           | 重新生成, 检查 --frames 参数 |
+| 精灵表尺寸合理     | 单帧 <= 256x256, 总图 <= 1024px 宽 | 降低 --scale 或减少帧数      |
+| 文件体积在预算内   | VFX 总计 <= 150KB                  | 减少预设数量或降帧           |
+| 记录到 ta-log.md   | grid 参数(帧数/列数/单帧尺寸)      | 补写, Developer 需要此信息   |
+
+## 5. Detailed Reference
+
+完整预设目录与组合配方见 `refs/ta-vfx-preset-catalog.md`，包含：
+
+- 每个 VFX 预设的完整详解（动画感描述、Tint 建议、Scale 建议、典型错误）
+- 每个 animate 预设的完整详解（参数建议、最佳用途、典型错误）
+- 按游戏类型的 VFX + 动画组合配方（Match-3 / 跑酷 / 卡牌 / 泡泡射击）
+- flip 工作流详情
+- 自定义帧数决策指南与非均匀帧时长技巧
+- 体积预算分配参考

package/project-template/.claude/skills/playcraft-workflow/SKILL.md

@@ -0,0 +1,485 @@
+---
+name: playcraft-workflow
+description: PlayCraft 可玩广告开发工作流与 Skill 体系入口。在开始构建任何游戏项目、选择组件、查找 Skill、生成图片/音频、创建 Remix 时自动触发。解释双层 Skill 体系并引导正确工作流。
+triggers: 构建游戏,开始开发,创建项目,选择组件,选择 skill,查找 skill,生成图片,生成音频,工作流,workflow
+---
+
+# PlayCraft 工作流与 Skill 体系
+
+## 执行模式（首先判断）
+
+在开始任何工作前，先判断当前执行环境：
+
+### Multi-Agent Mode（默认，优先使用）
+
+如果当前环境支持 sub-agent 调用（Claude Code 的 `@agent` 语法可用）：
+
+1. **你是 orchestrator**，不要自己执行任何 Agent 的工作
+2. 按 `CLAUDE.md` 中 Orchestration Protocol 的阶段转换表 spawn sub-agents
+3. 每个 sub-agent 完成后，读取 `docs/project-state.md` 的 **`## Agent handoff`** YAML + Gates 表，再决定下一步
+4. **Orchestrator 会话**优先遵循 `.cursor/rules/playcraft-orchestrator.mdc`；子 Agent 会话不加载 orchestrator rule
+5. **仅 orchestrator** 对用户 `AskUserQuestion` — 子 Agent **禁止**问用户（见 `docs/team/agent-conduct.md`）
+   - `gate_pending` 非 null 且 `waiting_for: user_gate` 时：**只跑 Gate**，不得 invoke 子 Agent
+   - `subagent_stop: true` 时：只执行 `next_orchestrator_action`
+   - Gate #1 / #2a / #2b：`AskUserQuestion`（子 Agent 更新 handoff 后 STOP）
+   - **Gate #1 / #2b 前**：先 invoke `@reviewer design_check`（软性 checklist）
+   - Gate #3：Reviewer `load_check` 通过后展示 **devUrl**（用户只点链；玩法由用户判断）
+   - Gate / handoff 细则：`docs/team/collaboration.md` § Gate Protocol、§ Agent Handoff
+6. `devStatus: ui_ready` → `@reviewer ui_diff`；`ui_rework` → 按 report 修复 → 再 `@reviewer ui_diff`
+7. `devStatus: ready` → `@reviewer load_check` → Gate #3
+8. `devStatus: blocked_upstream` → 按 `devBlockers.routeTo` 调度 TA/Designer → 再 `@developer`
+9. 当前交付终点 = 用户在 Dev URL 验收通过（`done`），**不要求** `playcraft build`
+
+### ⚠️ Orchestrator 调度原则：传 WHAT 不传 HOW
+
+**Orchestrator 不是全知全能的指挥官。** 不要在调度时给子 Agent 写详细步骤——子 Agent 有完整的 `.claude/agents/<role>.md` + `refs/` + 相关 Skills。
+
+**正确的调度方式：**
+
+```
+@technical-artist
+目标：完成 atom-plan.json 中所有 assignTo: TA 的 atoms。
+注意：atom-plan.json → skillsMatch.mediaGroups 有 3 个预制图片资产可复用，优先 link。
+```
+
+**错误的调度方式（越俎代庖）：**
+
+```
+@technical-artist
+1. 先生成 tile_01.png，用绿幕...
+2. 然后 remove-background --tolerance 25...
+3. 接着 resize 到 128x128...
+```
+
+**原则：**
+
+- Orchestrator 只传递 **目标 + 约束 + 关键提醒**（如 mediaGroups 可用）
+- 子 Agent 自己读 `refs/` + Skills 找到正确方法论
+- Orchestrator 在 sub-agent STOP 后 **验证结果**（atom status 是否更新、Context 是否填写）
+
+### Orchestrator STOP 后验证清单
+
+Sub-agent STOP 返回后，Orchestrator 必须验证：
+
+```bash
+# 检查 atom status 是否全部更新
+cat docs/atom-plan.json | jq '[.atoms[] | select(.assignTo == "<agent>") | select(.status == "pending")] | length'
+# 应该 = 0（所有该 agent 的 atom 都已 done / skipped）
+
+# 检查 Context 是否填写
+grep -c "Pending" docs/atom-plan.md
+# 对应 agent 的 Context 区不应包含 "Pending"
+
+# 检查 actualOutput 文件是否存在
+cat docs/atom-plan.json | jq '.atoms[] | select(.assignTo == "<agent>" and .status == "done") | .actualOutput' | xargs -I {} test -f {}
+```
+
+如果验证失败 → 不转入下一阶段，而是要求该 agent 补全。
+
+### Single-Agent Mode（降级模式，当 sub-agent 不可用时）
+
+串行执行所有阶段，但**必须**：
+
+- 每进入一个新阶段时，先完整读取对应 `.claude/agents/<role>.md` 的所有指令
+- 不可跳过任何阶段的必选产出（特别是 TA 的完整素材生产——UI 图、VFX、精灵图都必须生产）
+- 必须执行 Spec Quick-Check：TA 在 production Wave 2 启动后 30s 内；Developer 在 `ui_pass` 启动后 30s 内
+- PM 定稿后运行 `playcraft skills link --from-atom-plan`；Developer 优先读 `.claude/skills/<atomId>/SKILL.md`，仅断链时用 `playcraft skills read`
+
+---
+
+## 双层 Skill 体系
+
+PlayCraft 使用 **两套互补的 Skill 系统**：
+
+| 层                     | 位置                                            | 用途                                             | 发现方式                                                                                                                       |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| **Claude Code Skills** | `.claude/skills/`                               | 平台工具使用指南（图片生成、音频、代码编辑器等） | IDE 自动发现和注入                                                                                                             |
+| **DAG Atom Skills**    | `playcraft skills match` 返回的 `skillDir` 路径 | 游戏积木（玩法规则、组件、图片、音效、配置）     | `playcraft skills match` CLI 推荐；PM 定稿后 `playcraft skills link --from-atom-plan` 软链到 `.claude/skills/` 供 IDE 自动发现 |
+
+**关键规则**：构建任何新游戏项目前，**必须先运行 `playcraft skills match`** 获取完整的推荐积木清单，再动手写代码。
+
+---
+
+## 标准工作流（必须遵守）
+
+```
+① 运行本地 Skill 推荐（必须）
+   playcraft skills match --intent "<关键词,逗号分隔>" --json
+   # 自动推断引擎；若已定：加 --engine <threejs|phaser>
+
+② 评估本地 Skill 覆盖度
+   - 完整覆盖 → 进入步骤 ③
+   - 部分覆盖 → 进入步骤 ③，同时触发 ②-ext
+   - 完全没有 → 触发 ②-ext
+
+② -ext（本地不足时）网络研究补充
+   - 参阅 playcraft-research SKILL，按角色执行定向研究
+   - 研究结论写入 `docs/atom-plan.md` 的对应 Context 区域
+   - 标记候选新 Skill（在 DAG Revisions 中记录）
+
+③ 读取每个代码 Skill 的 SKILL.md（PM 已 link 后优先项目内路径）：
+   cat .claude/skills/<atomId>/SKILL.md
+   # 软链缺失时兜底：playcraft skills read <atomId>
+   - 理解 Recipe；列出将使用的 ref/ 文件
+   - 将关键信息记入 `docs/atom-plan.md` 对应的 Context 区域
+
+④ PM 定稿 `atom-plan.json` 后，软连接 DAG Skill 到项目（IDE 自动发现，强烈推荐）：
+   playcraft skills link --from-atom-plan --prune
+
+⑤ 执行 scaffold 命令，复制 ref 文件到项目（注：package.json/tsconfig.json 使用 merge-json 模式，不覆盖已有配置）
+   playcraft skills scaffold --engine <引擎> --atoms <skill1,skill2> --out ./game
+
+⑥ 按各媒体 Skill 的参数（或网络研究得出的参数）生成图片/音频资产
+   playcraft tools generate-image --prompt "..." --output ta-workspace/xxx.png
+   playcraft tools generate-sfx --prompt "..." --duration 1.5
+   playcraft tools generate-bgm --prompt "..."
+
+⑦ 在已有 ref 文件基础上（或基于研究方案）编写项目代码
+```
+
+**禁止**：
+
+- ❌ 未运行 `skills match` 就开始写引擎/布局/输入/渲染代码
+- ❌ 未读 SKILL.md（项目软链或 CLI 兜底）就跳过 Skill 内容直接从头实现
+- ❌ 对已有 ref 文件重新实现相同功能
+- ❌ 手动猜测 Skill 名称
+- ❌ 本地无 Skill 就直接凭感觉写——先做网络研究，把依据记录在活 DAG 里
+
+---
+
+## Agent 自增强协议（Skill-on-Demand）
+
+> **核心原则**：Skill 是持续可用的资源，不是一次性查询。每个 Agent 在其专属阶段都应独立做角色相关的 Skill 发现。
+
+### 为什么需要多次 Skill 查询
+
+- 每个 Agent 是独立 session，不继承前一个 Agent 的 Skill 搜索结果
+- 每个角色需要的 Skill 类型完全不同
+- 在实现某个具体功能时才知道需要什么，无法在规划阶段完全预见
+
+### 按角色的 Skill 发现模式
+
+**PM（规划阶段）**
+
+```bash
+# 确认玩法类型的已有实现和依赖关系
+playcraft skills match --engine <engine> --intent "<gameplay_type>,<game_mechanic>" --json
+# 浏览所有可用配置封包
+playcraft skills list --category config --json
+```
+
+**Designer（创意样本生产阶段）**
+
+```bash
+# 找视觉资产参考和生成参数（aiimage Skill 包含 manifest.json 里的 generation 字段）
+playcraft skills list --category visual --json
+# 找音频资产参考
+playcraft skills list --category audio --json
+# 按具体元素类型搜索
+playcraft skills match --intent "<element_type>,<art_style>" --json
+```
+
+**Technical Artist（技术生产阶段）**
+
+```bash
+# 找精灵图/图集生产 Skill
+playcraft skills list --category visual --json
+playcraft skills match --intent "<element_type>,sprite,atlas,sheet" --json
+# 找 3D 渲染/翻转精灵图 Skill
+playcraft skills match --intent "3d,sprite,flip,render" --json
+# 找图片处理 Skill
+playcraft skills match --intent "image,processing,pipeline" --json
+# 找验证器（用于合规检查）
+playcraft skills list --category validator --json
+```
+
+**Developer（代码实现阶段）**
+
+```bash
+# 每实现一个 Atom 前，先搜索是否有现成的代码积木
+playcraft skills match --engine <engine> --intent "<feature_name>,<component_type>" --json
+# 找引擎适配层
+playcraft skills list --category engine --json
+# 找布局/UI 组件
+playcraft skills list --category layout --json
+```
+
+**Reviewer（质量验证阶段）**
+
+```bash
+# 找可用的校验器 Skill
+playcraft skills list --category validator --json
+# 按具体校验目标搜索
+playcraft skills match --intent "validator,balance,compliance,ux" --json
+```
+
+### "写代码前先查 Skill" 规则
+
+在实现任何非平凡组件之前，**必须先执行此检查**：
+
+```
+1. 我即将实现：<描述功能>
+2. 运行：playcraft skills match --engine <e> --intent "<功能关键词>" --json
+3a. 找到完整匹配 Skill → 读取其 SKILL.md → scaffold → 基于 ref 文件实现
+3b. 找到部分匹配 → 使用 Skill 作为基础，参阅 playcraft-research 补充网络研究
+3c. 完全未找到 Skill → 参阅 playcraft-research 执行定向网络研究 → 研究结论写入
+     `atom-plan.md` § Impl Skill Context → 在 `dagRevisions` / DAG Revisions 标注候选新 Skill → 实现
+```
+
+> 本地 Skill 库不可能穷尽所有场景。遇到陌生玩法、新艺术风格、特定算法时，**网络研究是标准流程，不是例外**。关键是把研究结论沉淀进活 DAG，让整个团队受益。
+
+**典型触发场景**：
+
+- 要写一个新的 UI 组件 → `skills match --intent "ui,component,<具体名称>"`
+- 要实现某种玩法规则 → `skills match --intent "<gameplay>,rules,algorithm"`
+- 要做图片后处理/精灵图 → 读取 `playcraft-image-generation` SKILL.md（涵盖后处理管线与脚本模板）
+- 要做音频生成/处理 → 读取 `playcraft-audio-generation` SKILL.md
+- 要读取某个 Skill 的完整说明 → `playcraft skills read <atomId>`
+
+### Skill 依赖链发现
+
+Atom Skill 之间通过 `imports` 字段形成依赖链。发现一个 Skill 可能引出更多：
+
+```bash
+# 读取某 Skill 的完整 SKILL.md（含 imports / Recipe / 操作流程）
+playcraft skills read <atomId>
+
+# match 输出的 JSON 中每个 item 包含 skillDir 字段，可直接访问 ref/ 目录
+# 例如读取 memory_match 的 PGS 规则骨架：
+playcraft skills match --engine phaser --intent "memory,match" --json \
+  | python3 -c "import json,sys; items=json.load(sys.stdin)['items']; [print(i['atomId'], i['skillDir']) for i in items]"
+
+# 查看 skill 的 ref/ 目录文件（先用 read 获取 skillDir）
+playcraft skills read <atomId>  # 找到 skillDir 路径
+# 然后直接读取 ref/ 文件：
+cat <skillDir>/ref/<file>
+
+# 按依赖 Skill 名称递归读取
+playcraft skills match --intent "<imported_skill_keywords>" --json
+```
+
+---
+
+## 活 DAG 分层富集模式（保持一致性）
+
+> **问题**：多个 Agent 各自做 DAG/Skill 搜索，结果会不会冲突？谁的优先？
+>
+> **答案**：不冲突。**活 DAG** 在 `docs/atom-plan.json`（`atoms[]` + `skillsMatch`）；各 Agent 在 `docs/atom-plan.md` 向专属 Context 区富集，形成统一知识库。
+
+### 活 DAG 的分层结构
+
+```
+docs/atom-plan.json
+├── skillsMatch                    ← PM：`playcraft skills match --json`（skillRef 唯一来源）
+├── atoms[]                        ← PM：排期 DAG；Gameplay/Config 的 skillRef 仅来自 skillsMatch.items
+└── dagRevisions[]                 ← 结构变更 / skills-match-gap（可与 md 同步）
+
+docs/atom-plan.md
+├── Atom List（可选镜像表）        ← 与 atoms[] 同步；可省略
+├── ## Acceptance Criteria         ← PM：每 atom 一条可测验收
+├── ## Asset Skill Context         ← Designer
+├── ## TA Skill Context            ← TA
+├── ## Impl Skill Context          ← Developer
+└── ## DAG Revisions               ← 人类可读修订记录
+```
+
+Skills 路径真源：`playcraft.config.json` → `agent.skillsDir`（**不要**在 atom-plan 写死 node_modules）。格式详解：[`docs/team/atom-plan-format.md`](../../docs/team/atom-plan-format.md)
+
+### 各 Agent 的读写职责
+
+| Agent                | 读取                                                     | 写入                                                                            |
+| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| **PM**               | design-brief, layout-spec                                | `atom-plan.json`（skillsMatch + atoms[]）                                       |
+| **Designer**         | `atoms[]` + `mediaGroups` + design-brief                 | `atom-plan.md` § Asset Skill Context；`atoms[].status` + `atoms[].actualOutput` |
+| **Technical Artist** | `atoms[]` + `mediaGroups` + Asset Context + designer-log | `atom-plan.md` § TA Skill Context；`atoms[].status` + `atoms[].actualOutput`    |
+| **Developer**        | `atoms[]` + Context 区 + design-brief                    | `atom-plan.md` § Impl Skill Context；`atoms[].status` + `atoms[].actualOutput`  |
+| **Reviewer**         | JSON + MD（只读）                                        | 不写                                                                            |
+
+### ⚠️ Status Update 纪律（所有 Agent 必须遵守）
+
+每个 Agent 完成 atom 后 **立即** 更新 `atom-plan.json`：
+
+```json
+{
+  "atomId": "<id>",
+  "status": "done",
+  "actualOutput": "<deliverable_path>"
+}
+```
+
+- **Designer**: `actualOutput` = 文件路径 或 `"ASR:<sheet>:<region>"` (when covered by ASR)
+- **TA**: `actualOutput` = `"assets/images/<path>.webp"` (final WebP contract path)
+- **Developer**: `actualOutput` = `"game/<path>.ts"` (implementation file)
+
+**atom-plan 不是 PM 的一次性输出文档，而是贯穿全流程的活依赖追踪系统。**
+
+### mediaGroups 使用纪律（Designer + TA 必须遵守）
+
+`skillsMatch.mediaGroups` 包含 PM 通过 `playcraft skills match` 找到的可复用预制资产。
+
+**流程**：
+
+```
+Designer/TA 读 mediaGroups
+  ├─ 匹配当前 atom？
+  │   ├─ 是 → `playcraft skills link --atom <atomId>` → 后处理 → status=done
+  │   └─ 否 / 质量不够 → 记录跳过原因到 dagRevisions → 正常生产流程
+  └─ mediaGroups 为空？→ 正常生产流程
+```
+
+**禁止**：忽略 mediaGroups 中存在匹配的预制资产而从零生成（浪费 token + 引入不一致风险）。
+
+### 为什么这样设计能避免冲突
+
+**示例**：游戏风格为"像素风"
+
+```
+PM:
+  → 搜索 aigameplay skills，得到 arrow_pick_match_rules
+  → 在 atoms[] 填：arrow_rules | skillRef = arrow_pick_match_rules.aigameplay
+  → 不知道像素风需要什么具体的图片参数，留 VisualAtom skillRef 为空（—）
+
+Designer:
+  → 读到 StyleDirection = "像素风 8-bit 高饱和"
+  → 搜索 aiimage skills，得到 pixel_art_sprite.aiimage
+  → 读 pixel_art_sprite 的 manifest.json：了解 prompt 模板、block 尺寸参数
+  → 在 Asset Skill Context 写：bg_atom → pixel_art_sprite → 关键参数...
+  → 现在知道"像素风"具体怎么生产了
+
+Developer:
+  → 读 PM 的 skillRef = arrow_pick_match_rules.aigameplay
+  → 读 Designer 的 Asset Skill Context（了解视觉风格，确保代码绑定正确）
+  → 搜索额外的 aicomponent skills
+  → 在 Impl Skill Context 写：arrow_rules_impl → 实现细节...
+
+Reviewer:
+  → 读 Atom List + Asset Skill Context + Impl Skill Context
+  → 有了完整 Skill 依据，搜索 aivalidator skills 进行验证
+```
+
+**无冲突的根本原因**：每个 Agent 的写入区域不重叠。DAG 是合作共建的，不是争夺的。
+
+---
+
+## Scaffold 所有权模型（防冲突）
+
+> **核心规则**：`playcraft skills match/list` 是只读操作，任何 Agent 随时可用，零冲突。
+> **唯一风险**：`playcraft skills scaffold`（写文件），必须遵守所有权规则。
+
+### 每个 Agent 的 Scaffold 域
+
+| Agent                | 可 Scaffold 的 Skill 类型                                      | 写入目录  | 禁止 Scaffold                                             |
+| -------------------- | -------------------------------------------------------------- | --------- | --------------------------------------------------------- |
+| **Developer**        | `aicomponent`, `aigameplay`, `aiconfig`                        | `game/`   | `aiimage`, `aiaudio`, `aivalidator`                       |
+| **Technical Artist** | ❌ 不 Scaffold（读 manifest.json generation 参数，直接调 CLI） | `assets/` | **全部**（TA 通过 CLI 管线生产，不 Scaffold）             |
+| **Designer**         | ❌ 不 Scaffold                                                 | `assets/` | **全部**（只读 manifest.json 的 generation 参数用于生成） |
+| **Reviewer**         | ❌ 不 Scaffold                                                 | 只读      | **全部**（read-only 角色）                                |
+| **PM**               | ❌ 不 Scaffold                                                 | `docs/`   | **全部**（只做规划 + 协调）                               |
+
+### 为什么 Designer 和 TA 不需要 Scaffold
+
+`aiimage` / `aiaudio` Skill 没有 `ref/` 代码文件，只有 `manifest.json` 中的 `generation` 字段（prompt、aspectRatio、duration 等）。Designer 和 TA 读取这些参数作为生成基准，通过 `playcraft image *`、`playcraft tools generate-image` 等 CLI 命令执行，不复制任何文件到项目。
+
+**Reviewer（convergence-v1）**
+
+- **`design_check`**：Gate #1 / #2b 前 — 文档完整性 checklist（无需浏览器）
+- **`ui_diff`**：读取 **`playwright-cli`** skill — 截图 vs MC 各面板
+- **`load_check`**：读取 **`playwright-cli`** skill — 页面加载 + console 无 Error
+
+### Production 串行编排（convergence-v1）
+
+Gate #2b 通过后 **严格串行**（见 `workflow-changelog.md`）：
+
+```
+Wave 1 Designer Ph.2 → Wave 2 TA → ui_pass Developer → ui_review (Reviewer ui_diff) → gameplay_pass Developer → load_check → Gate #3
+```
+
+Developer 在 **`ui_pass`** 写入 UI shell（无核心玩法）；**`gameplay_pass`** 叠加玩法逻辑。TA 已交付合同路径上的真实资产。
+
+### 避免重复 Scaffold 的规则
+
+同一个 Skill 不应被多次 Scaffold 到同一目录：
+
+- PM 在 `atom-plan.json` → `atoms[]` 标注 `skillRef`（若有）+ 调度元信息（assignTo/dependsOn/priority/parallelGroup/referenceSource）
+- Developer 在 **`ui_pass`** 开始时，按 `atoms[]` 中 `assignTo: Developer` 批量 scaffold 一次
+- **不要在实现单个 Atom 时反复 scaffold** — 先统一 scaffold 所有依赖，再逐一实现
+
+---
+
+## 如何阅读 Atom Skill 的 SKILL.md
+
+每个 Atom Skill 的 `SKILL.md` 包含：
+
+1. **YAML frontmatter**：`name`（格式为 `<name>.<bundleType>`）、`description`、`triggers`
+2. **功能说明**：Skill 做什么、输出什么
+3. **Scaffold / Imports**：依赖哪些其他 Skill
+4. **Skill Definition 区块**（部分 Skill 有）：
+   ```yaml
+   ## Skill Definition
+   tools:
+     - bash
+     - read
+   prompt_extension: |
+     这里是注入给 agent 的操作指令
+   ```
+   `prompt_extension` 的内容是 agent 执行此 Skill 时需要遵循的具体指令。
+
+---
+
+## Skill 推荐示例
+
+```bash
+# Three.js 3D 棋盘消除游戏
+playcraft skills match --engine threejs --intent "board,3d,path,animation"
+
+# Phaser 三消游戏
+playcraft skills match --engine phaser --intent "match3,grid,tile,score"
+
+# 跑酷游戏
+playcraft skills match --engine phaser --intent "parkour,left_right,run,obstacle"
+
+# 查看所有可用 Skill
+playcraft skills list --json
+```
+
+---
+
+## 平台工具快速参考
+
+### Claude Code Skills（`.claude/skills/` 目录，自动注入）
+
+> ⚠️ 下表只列出**项目模板中实际存在**的 Skill。不要查找或引用表外的 Skill 名称。
+
+| Skill                          | 职责                                                                                                                   | 主要角色      |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `playcraft-workflow`（本文件） | 工作流入口、Skill 体系、DAG 协作规范                                                                                   | 全员          |
+| `playcraft-image-generation`   | AI 图片生成全指南：模型选择、gpt-image-2 双 provider、精灵图直出、绿幕策略、edit 变体、错误恢复、ta-workspace 脚本模板 | Designer / TA |
+| `playcraft-audio-generation`   | AI 音频生成全指南：SFX/BGM 生成参数、prompt 套路、本地音频后处理（compress/fade/loop）                                 | Designer      |
+| `playcraft-research`           | 网络研究协议：`tools research/fetch-url/search-image` 三工具标准流程、研究结果融入活 DAG                               | 全员          |
+
+### CLI 命令组（`playcraft <group>`，无需 Skill 文件）
+
+| 命令组                                              | 能力摘要                                                                                                                                                         | 主要角色             | 完整文档                                                     |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------ |
+| `playcraft tools generate-image`                    | AI 文生图/图生图；`--reference-image`、`--image-model`（裸模型名时后端按优先级 fallback）、`--count N`（同 prompt 批量出图）、`--timeout`                        | Designer / TA        | `docs/cli/tools.md §1.2`                                     |
+| `playcraft tools generate-sfx/bgm`                  | AI 音效/背景音乐生成                                                                                                                                             | Designer             | `docs/cli/tools.md §1.2`                                     |
+| `playcraft tools generate-3d` 系列                  | AI 3D 模型生成、贴图、重拓扑、UV 展开、动作                                                                                                                      | TA                   | `docs/cli/tools.md §1.3`                                     |
+| `playcraft tools research/fetch-url`                | AI 网络研究与 URL 读取                                                                                                                                           | 全员                 | `docs/cli/tools.md §1.7`                                     |
+| `playcraft tools save-to-git/build-project/publish` | 项目保存、构建、发布                                                                                                                                             | Developer            | `docs/cli/tools.md §1.4`                                     |
+| `playcraft image`                                   | 本地图片处理 + 后端抠图/分层：resize/crop/decompose-layers/segment/remove-background/sprite-split/sprite-sheet/batch/pipeline/animate/tint/overlay/gen-tile-back | TA                   | `docs/cli/tools.md §2`；分层与蒙版选型见 `playcraft-masking` |
+| `playcraft audio`                                   | 本地音频处理：compress/trim/fade/loop/normalize/mix                                                                                                              | Designer / TA        | `docs/cli/tools.md §3`                                       |
+| `playcraft 3d`                                      | 本地 3D 处理：白模库/apply-texture/optimize/convert                                                                                                              | TA                   | `docs/cli/tools.md §4`                                       |
+| `npm run dev`                                       | 项目 Dev 预览（`package.json` → `scripts.dev`）                                                                                                                  | Developer / Reviewer | 用户不执行；Gate #3 由 orchestrator 递 devUrl                |
+| `playcraft build / build-all`                       | 打包 Playable Ads（**未来**交付路径，非当前 `done` 条件）                                                                                                        | —                    | —                                                            |
+| `playcraft skills match/list/link/scaffold/read`    | DAG Atom Skill 推荐、IDE 软链、脚手架、内容读取（`link` 供 PM；`read` 供 Developer Preflight）                                                                   | 全员                 | —                                                            |
+
+---
+
+## Skill 目录发现优先级
+
+`playcraft skills` 命令按以下优先级发现 Skill 目录：
+
+1. `--skills-dir <path>` 参数
+2. `playcraft.config.json` 中的 `skillsDir` 字段
+3. `AGENT_SKILLS_PATHS` 环境变量
+4. `<项目根>/node_modules/@playcraft/skills/skills`（npm 安装后）