@playcraft/cli 0.0.57 → 0.0.59

package/project-template-v2/.claude/agents/refs/artist-dimension-axis.md

@@ -0,0 +1,27 @@
+# Artist Dimension Axis Workflow
+
+> Read in Phase 1 after confirming Dimension Axis from `docs/design-brief.md`. **artist-handoff-v2**: visual baseline = MC + ASR (not scattered sample PNGs). TA handles mass production.
+
+## Flat 2D (Standard)
+
+- **MC** concept panel shows all element types + UI + static text.
+- **ASR** element sheet: 2–3 states per type (idle / selected / matched).
+- TA: bg extract, completions, atlases, VFX.
+
+## 2.5D Visual (Depth Layers)
+
+- MC concept panel: perspective scene + layered elements.
+- ASR: angled sprites in element sheet; note depth layers in Style Intent Notes.
+- Background: default **TA extract from MC**; dedicated bg sample only if Game Designer routes an ICP supplementary art request.
+
+## Isometric
+
+- ASR element sheet: representative isometric tiles (2–3 states).
+- Optional: `playcraft tools search-image` for reference.
+- TA: remaining tiles, atlas, animation.
+
+## True 3D
+
+- Artist does **not** output GLB.
+- Phase 1 ring 3 verify: 2D reference texture PNG (path in `artist-log`) per `artist-deliverable-spec.md` § Phase 1 exception.
+- TA: `generate-3d`, GLB, flip sprites.

package/project-template-v2/.claude/agents/refs/artist-master-composite-recipes.md

@@ -0,0 +1,208 @@
+# Master Composite — 游戏类型 Prompt 配方 & 参考
+
+> 本文件供 Artist 在生成 Master Composite 时按需查阅。核心规则见 `playcraft-storyboard` skill。
+
+## 模型策略（MC 专用 — 仅高质量模型）
+
+Master Composite **禁止**使用低档或实验性模型。生成前可运行 `playcraft tools list-image-models` 核对 capability，但 **MC 只允许下表**：
+
+| 允许 `--image-model`           | 典型分配                                        |
+| ------------------------------ | ----------------------------------------------- |
+| **`mulerouter/gpt-image-2`**   | Option A（主推）；Option C 可复用 + 不同 prompt |
+| **`mulerouter/nano-banana-2`** | Option B；或 A/B 各用一模型做画风对比           |
+
+**禁止用于 MC**：`gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*`、裸 `gpt-image-2`、以及上表以外的任何模型。
+
+> 多方案差异应来自 **prompt / 配色 / 构图**，不是换弱模型。ASR 双板 `--image-model` 须与已选 MC **完全一致**（见 `playcraft-asset-state-sheet` skill）。
+
+### 模型特性速查（仅白名单内）
+
+| 模型                       | 特点                          | 适合                                |
+| -------------------------- | ----------------------------- | ----------------------------------- |
+| `mulerouter/gpt-image-2`   | 细节、光影、复杂 UI、中文元素 | 写实、半写实、精细卡通、麻将/汉字类 |
+| `mulerouter/nano-banana-2` | 色彩、构图、速度快            | 明亮卡通、简洁 UI、快速迭代第二方案 |
+
+> `--reference-image` 只能用于 CAPABILITY 为 `text+image` 或 `image→image` 的模型；白名单内两模型均支持图生图。
+
+---
+
+## 游戏类型 Prompt 配方
+
+以下模板可直接复制修改。所有模板遵循 skill 中的 5 面板并排结构 + 编号标签。
+
+### Match-3 消除游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a match-3 puzzle game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — colorful candy gem grid on [BG_DESCRIPTION], all gem types visible ([TYPE_LIST]), HUD strip showing score and moves counter, 'Play Now' CTA button at bottom. [MASCOT_DESCRIPTION].
+
+Panel 2 '2. Key Hook': Gems exploding in chains, dynamic burst VFX, score [HIGH_SCORE], combo text visible, vivid colors, dramatic moment, high contrast, minimal UI.
+
+Panel 3 '3. Onboarding HUD': Finger tap icon pointing at two matching gems, soft glow highlight on target pair, simplified board, score reset, friendly guidance arrow, speech bubble with hint text.
+
+Panel 4 '4. End Card': Victory celebration — [DARK_BG], '[WIN_TEXT]', treasure chest with rewards, reward amount visible, 'Install Now' CTA button prominent, confetti.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot showing normal gameplay in progress, with 'Play Now' CTA button clearly visible at bottom-right during active play, proving CTA is always accessible.
+
+[STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI (HUD bar, score display, buttons). Consistent art style across all panels. Thin vertical dividers between panels. Each panel has its numbered label at the top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+### 跑酷 / 平台跳跃游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for an endless runner game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — character running through [ENVIRONMENT], coin trail ahead, obstacles visible, HUD showing distance and coins collected, 'Play Now' button at bottom.
+
+Panel 2 '2. Key Hook': Character at maximum speed, motion blur, dynamic camera angle, dramatic lighting, speed lines, high contrast, minimal HUD.
+
+Panel 3 '3. Onboarding HUD': Jump arrow icon showing first obstacle, character highlighted with glow, simple environment, clear guidance text bubble.
+
+Panel 4 '4. End Card': Dark background, distance record display, 'Install Now' CTA button prominent, reward chest, achievement badges.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot with character dodging obstacles, 'Play Now' button clearly visible at bottom-right during active play.
+
+[STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI. Consistent art style across all panels. Thin vertical dividers. Numbered labels at top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+### 卡牌 / 麻将游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a Mahjong Solitaire game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — Mahjong tile grid on dark green felt table, tiles with Chinese symbols, cute mascot character, HUD showing score and timer, 'Play Now' button at bottom. Rich warm lighting.
+
+Panel 2 '2. Key Hook': Near-win combo state — high score, combo text with golden sparkles, most tiles matched with golden borders, mascot excited expression, warm amber glow, dramatic tension.
+
+Panel 3 '3. Onboarding HUD': Clean simplified board, finger tap icon pointing at two matching tiles, speech bubble 'Tap matching tiles', score reset, progress indicator, mascot encouraging smile.
+
+Panel 4 '4. End Card': Victory — dark elegant background, '恭喜通关!' text in gold, treasure chest, reward amount with coin icon, 'Install Now' CTA button in contrasting color, golden confetti.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot showing active gameplay with tiles on board, score and timer visible, 'Play Now' button clearly visible at bottom-right during play.
+
+Premium casual style, warm amber lighting, traditional Chinese aesthetic with modern UI, glossy tile surfaces. All 5 panels portrait-oriented, left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+### 射击 / 动作游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a casual shooting game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — player aiming at enemies in [ENVIRONMENT], weapon visible, HUD showing ammo/health/score, 'Play Now' button at bottom.
+
+Panel 2 '2. Key Hook': Target reticle locking on enemy, muzzle flash, dramatic action lighting, high contrast, speed lines, minimal HUD.
+
+Panel 3 '3. Onboarding HUD': Aim crosshair tutorial overlay, slow-motion visual hint, simple enemy highlighted with marker, guidance text.
+
+Panel 4 '4. End Card': Dark background, victory text, loot box with rewards, 'Install Now' CTA button prominent.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot with active combat, 'Play Now' button clearly visible at bottom-right during play.
+
+[STYLE_KEYWORDS]. All 5 panels portrait-oriented left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels at top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+## 故障恢复
+
+### 问题：模型拒绝生成（content policy）
+
+```bash
+# 移除触发审查的词语，改用间接描述
+# "explosion, fire, destruction" → "dramatic burst effect, particle shower, vivid energy release"
+```
+
+### 问题：面板内容混淆（相邻面板之间内容串了）
+
+```bash
+# 方案 1：强化编号标签
+"Panel 1 '1. Main Gameplay' (leftmost):..., Panel 2 '2. Key Hook' (second from left):..."
+
+# 方案 2：加描述性分隔符
+"5 panels separated by clear vertical white dividers. Each panel has bold numbered header."
+```
+
+### 问题：面板间风格不统一
+
+```bash
+# 强化风格约束词
+# 原始："Consistent art style across all panels."
+# 强化版："All 5 panels MUST use identical art style, color palette, and character design. Same rendering style throughout. All panels depict the SAME game."
+```
+
+### 问题：某帧内容不清晰
+
+发现某帧表达不清晰时，**不必重新生成整张**，而是在 `style-exploration.md` 的 Experience Flow Design 章节补充文字说明。
+
+### 问题：Concept Panel 缺少某些元素类型
+
+```bash
+# 方案 1：在 prompt Panel 1 段明确列出 "all [N] element types visible: [逐个列出]"
+# 方案 2：接受当前 MC，由 ASR 双板补足（ASR 是 TA 的主要提取源）
+```
+
+---
+
+## Reference-Image 与多方案策略
+
+### 首个方案（无 reference）
+
+Master Composite 是 Phase 1 的**第一张生成图**，通常无前序图可作 reference：
+
+```bash
+playcraft tools generate-image \
+  --prompt "<5-panel prompt>" \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+### 后续方案（可选 reference）
+
+后续方案可用已生成的方案 A 作为风格参考：
+
+```bash
+playcraft tools generate-image \
+  --prompt "<方案 B prompt>" \
+  --output assets/images/storyboard/master_composite_option_B.png \
+  --reference-image assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/nano-banana-2 \
+  --image-size 4K
+```
+
+### 输出命名规范
+
+```
+assets/images/storyboard/master_composite_option_A.png  ← 方案 A
+assets/images/storyboard/master_composite_option_B.png  ← 方案 B
+assets/images/storyboard/master_composite.png           ← ring 3 Ring Gate 确认后复制
+```
+
+ring 3 Ring Gate 确认后：
+
+```bash
+cp assets/images/storyboard/master_composite_option_[X].png assets/images/storyboard/master_composite.png
+```

package/project-template-v2/.claude/agents/refs/atom-skill-library.md

@@ -0,0 +1,81 @@
+# Atom Skill 组件库
+
+> **读者**：Game Designer / Developer —— 任何需要发现、评估、复用 Skill 的角色。
+> **用途**：理解 `playcraft skills` 组件库是什么、能带来什么价值、如何按复用等级正确使用。
+> **命令细节不在此文** —— 子命令用法见 `playcraft-skill-recommender` skill。
+
+---
+
+## 1. 是什么：双轨组件库
+
+`playcraft skills` 是一套从真实项目蒸馏出来的双轨组件库：
+
+| 轨                 | 是什么                                            | 命名                                                        | 怎么接触                                                            |
+| ------------------ | ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
+| **Atom Skills**    | 可组装进项目的**代码 / 资源积木**                 | `<name>.<bundleType>`（如 `grid_board_layout.aicomponent`） | 选中后会 link 进 `.claude/skills/`，可直接 read；用 `scaffold` 落地 |
+| **Platform Tools** | 平台**用法指南**（生图 / 生音频 / 构建 / 发布等） | `playcraft-<name>`                                          | 已 link 进 `.claude/skills/`，Claude Code 自动加载                  |
+
+本文只讲 **Atom Skills**（游戏积木）。Platform Tools 各自的 SKILL.md 自解释。
+
+Atom Skills 按 6 层 category 组织：`engine → asset → gameplay → visual → ui → misc`。`gameplay` 层拥有玩法真理（规则 / 状态 / 合法操作）；`visual` / `ui` 消费玩法状态，不反向拥有玩法逻辑。
+
+---
+
+## 2. 价值：站在已有实现的肩膀上
+
+库里的每个 Atom 都蒸馏自真实可玩项目的源码与资产。复用它意味着：
+
+- **省实现量**：现成的类、状态机、布局、规则骨架，比从零写更快更稳。
+- **对齐工程惯例**：接口契约、依赖声明、渲染分层都已经过验证。
+- **不漏现成能力**：库里上百个积木，凭空想象容易重造已有的轮子或漏掉合适的玩法 / 资源。
+
+> 原则：库的价值是让你站在高质量实现上，不是为了合规填表。读了、参考了、产出更好代码就是好的；某个 Atom 确实不适用，**记录原因后从零实现完全 OK**。
+
+---
+
+## 3. 四层复用价值（L1–L4）
+
+一个 Atom 提供的价值分布在四个层级，读取时按层级提取：
+
+| 层级                        | 内容                                 | 使用方式                      | 约束                                 |
+| --------------------------- | ------------------------------------ | ----------------------------- | ------------------------------------ |
+| **L4 · Scaffold 代码**      | `ref/` 源码、类实现、完整模块        | `scaffold` 后直接 import 使用 | 有现成就用，最高价值                 |
+| **L3 · Assets 预制资产**    | mediaGroups 图片 / 音频 / 3D 模型    | link 后做后处理               | 有匹配项必须复用，不得无视后从零生成 |
+| **L2 · Recipe 模板**        | prompt 模板、生成参数、配置范例      | 作为 AI 生产的输入指导        | 不可脱离 Recipe 约束自由发挥         |
+| **L1 · Reference 设计参考** | 布局坐标、状态机、规则逻辑、API 模式 | 作为实现蓝图参考              | 借鉴思路，不照搬不适用部分           |
+
+---
+
+## 4. 复用等级（reuseLevel）
+
+对每个选用的 Atom，按匹配度判定一个复用等级：
+
+| 等级          | 含义                                       | 编码约束                                 |
+| ------------- | ------------------------------------------ | ---------------------------------------- |
+| `scaffold`    | ref 源码且功能高度匹配，落地后改配置即可   | 主动参考 scaffold 代码，省去大量从零实现 |
+| `reference`   | 架构匹配但需替换业务逻辑，保留核心设计模式 | 借鉴状态机结构 / 事件名 / 数据流         |
+| `design-only` | 提供设计灵感但功能差异大                   | 仅借鉴 API / 算法 / 布局 / 状态机思路    |
+
+---
+
+## 5. 怎么读一个 Atom 的 SKILL.md
+
+读取时关注这些结构化段落：
+
+| 段落                   | 提取内容                                              |
+| ---------------------- | ----------------------------------------------------- |
+| **Recipe / Result**    | 做什么、产出什么、做到什么算完成                      |
+| **Scaffold**           | `scaffold` 的产出位置（目标路径）                     |
+| **Adapter**            | Provides / Requires / Consumed by —— 依赖图与集成入口 |
+| **Imports**            | 硬依赖（必须加载）/ 软槽位（可替换资源）              |
+| **Key API / 使用示例** | 构造参数、方法签名、最小调用链                        |
+
+**读取三层次（铁律）**：
+
+```
+L1 · SKILL.md  —— 了解“是什么、提供什么”
+L2 · ref/ 源码 —— 提取真实类签名、事件名、config 结构（以此为准）
+L3 · assets/   —— 确认 frame 名、文件路径、资源尺寸
+```
+
+> **SKILL.md 与源码若有出入，以 ref 源码为准。** 只读 SKILL.md 不算理解 Skill；不读源码就集成，代码必出 bug。