@playcraft/cli 0.0.44 → 0.0.47

package/project-template/.claude/agents/refs/skill-selector-guide.md

@@ -0,0 +1,465 @@
+# Atom Selection Guide
+
+> Purpose: guide a temporary ref-flow atom-selection subagent to produce `docs/atom-tree.json` and optional `docs/atom-tree.md` as a compact atom-tree package.
+>
+> Scope: selection and reading guidance only. This guide does not define implementation steps, feature plans, or runtime orchestration.
+>
+> **Stage**: In **ring 1**, this subagent runs after Game Designer STOP and before engine scaffold. It produces only the minimal selection package needed for scaffold + Developer. In **ring 2+**, it may deepen the reading guide once layout/periphery specs are disclosed.
+
+## Objective
+
+Build an atom-tree contract that starts from the gameplay Skill closest to the current design.
+
+- `docs/atom-tree.json` is the **single structured contract**: `meta.skillsMatch` snapshot + selected `meta.selectedAtoms` + ring gates + optional product tree.
+- `docs/atom-tree.md` is an optional **human-readable guide** generated from JSON: which Skill acts as the gameplay trunk, which imports matter, how each role slot was resolved, and where true misses remain.
+- Treat `meta.skillsMatch.items[].role` and `meta.skillsMatch.mediaGroups[].role` as **chain-building hints**: they help you infer what each Skill mainly supplies, which semantic slots the trunk depends on, and which provider candidates are most likely relevant.
+
+## Inputs
+
+Read these before writing:
+
+| File                            | Why it matters                                                                     |
+| ------------------------------- | ---------------------------------------------------------------------------------- |
+| `docs/DESIGN.md`                | Consolidated player-experience direction                                           |
+| `docs/design-brief.md`          | Ring 2+ only: deeper gameplay/style/periphery choices                              |
+| `docs/atom-tree.json`           | Existing `skillsMatch` snapshot + selected `meta.selectedAtoms` list when revising |
+| `docs/team/atom-tree-format.md` | Output contract for `atom-tree.json` and `atom-tree.md`                            |
+
+## CLI Reference
+
+Use these commands in this flow:
+
+| Command                                                 | Purpose                                                                                                                              |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `playcraft skills init-atom-tree --intent "<keywords>"` | Create `docs/atom-tree.json` with `skillsMatch` pre-filled                                                                           |
+| `playcraft remix init-template --from-atom-tree`        | Apply engine scaffold (`game/` + `.playcraft-engine`) from `meta.engineDecision.adapter` — **orchestrator runs after selector STOP** |
+| `playcraft skills filter --role "<role>" --json`        | Find providers for a specific semantic role                                                                                          |
+| `playcraft skills read "<skillRef>"`                    | Deep-read trunk candidates and strong adjacent references                                                                            |
+| `playcraft skills validate-atom-tree-selection`         | Validate the JSON contract before STOP                                                                                               |
+| `playcraft skills link --from-atom-tree --prune`        | Link selected skills for downstream readers                                                                                          |
+| `playcraft skills gen-atom-tree-md [--force]`           | Generate an initial `atom-tree.md` skeleton that you may refine                                                                      |
+
+## Core Rules
+
+1. Select for relevance, not completeness.
+2. Work **trunk-first**: start from the gameplay Skill closest to the actual design, then expand outward.
+3. Keep `meta.selectedAtoms` compact: it remains a **string list of selected skill refs only**.
+4. Put reading notes, import interpretation, role decisions, and misses in `docs/atom-tree.md`; keep execution status and production logs outside JSON.
+5. `atom-tree.md` may narrate a gameplay assembly link, but it must not become an execution DAG or implementation plan.
+6. Treat role filling as an explicit decision: `use`, `skip`, or `miss` are all valid outcomes.
+7. If no good fit exists, say so explicitly in `Gaps` instead of forcing a weak match.
+8. Preserve `Level 0-4` reuse language from `creating-playable-games`.
+
+## Ring 1 Workflow
+
+Ring 1 is selection, not planning. The output should let scaffold choose the adapter and let Developer read a few strong Skill references. Stop before the tree turns into a feature plan.
+
+1. Read `DESIGN.md` and extract compact keywords.
+2. Run `playcraft skills init-atom-tree --intent "<keywords>" --project-dir .`.
+3. Choose `meta.selectedAtoms`: engine atom + best gameplay trunk + at most two strong adjacent atoms.
+4. If the match is weak, keep the best useful precedent or only the engine atom, and record the miss in `docs/atom-tree.md` if generated.
+5. Run `playcraft skills validate-atom-tree-selection --project-dir .`.
+6. STOP to orchestrator. Do not run `init-template`; scaffold is orchestrator-owned.
+
+Do not search peripheral systems in ring 1 unless `DESIGN.md` makes them part of the first playable spine. Collection counters, wrappers, full tutorial flow, hook/CTA packaging, and production assets are ring 2+ disclosure.
+
+## Ring 2+ Deepening Workflow
+
+### Step 1: Read the design direction
+
+Extract:
+
+- core gameplay pattern
+- important mechanic variants
+- style and tone constraints
+- obvious no-fit areas
+- **peripheral systems and wrapping** — systems that emerge from tutorial, progression, or packaging needs rather than the core mechanic itself (e.g. collection counters, level/stage structure, unlock progression, scene transitions, themed wrapper logic). These are often described in DESIGN.md under dimensions like "Tutorial and Onboarding", "Peripheral Systems", or "Wrapping / Packaging".
+
+> **Why this matters**: The `init-atom-tree --intent` keywords typically cover only the core mechanic (e.g. "mahjong,tile,match"). Peripheral systems like "collection progress", "level structure", or "stage transitions" use different vocabulary and will NOT appear in the initial `skillsMatch` unless you search for them separately. Failing to search means these systems default to "custom implementation" even when reusable Skills exist.
+
+### Step 2: Initialize or refresh `atom-tree.json`
+
+Use:
+
+```bash
+playcraft skills init-atom-tree --intent "<gameplayType>,<mechanic>,<keywords>" --project-dir .
+# Example: playcraft skills init-atom-tree --intent "mahjong,tile,match,stacking,puzzle"
+```
+
+**Orchestrator next step (ring 1, before Developer build)** — not part of ref-flow selection, but required for a runnable engine skeleton:
+
+```bash
+playcraft remix init-template --from-atom-tree
+npm install && npm run verify:contract
+```
+
+This should give you a valid `docs/atom-tree.json` shape with:
+
+- `meta.skillsMatch`
+- `meta.selectedAtoms`
+- `selectionRevisions[]`
+
+Open the JSON and review:
+
+- `meta.skillsMatch.items[]` — which skills matched, why they matched, and which `role[]` tags hint at their likely place in the chain
+- `meta.skillsMatch.mediaGroups[]` — reusable provider candidates grouped by semantic role, including each candidate's `role[]`
+- existing `meta.selectedAtoms` — only if this is a revision pass
+
+**Important**:
+
+- `meta.selectedAtoms` stays a compact string array of selected `skillRef` values only.
+- Do **not** encode execution status, role assignment, or produced file logs into `docs/atom-tree.json`.
+- Use `role[]` as a selection and reading hint, not as an unquestioned truth source; always confirm against the actual Skill content.
+- The human reading guide belongs in `docs/atom-tree.md`.
+
+### Step 2.5: Choose the gameplay trunk
+
+Pick the Skill that is **closest to the actual game direction**, not merely the highest-scoring generic match.
+
+Check:
+
+- is the core loop aligned?
+- is the interaction pattern aligned?
+- is the progression / failure pressure aligned?
+- do its `role[]` tags suggest it is truly a gameplay trunk / gameplay-rule precedent rather than only a themed asset or helper?
+- is it a real gameplay precedent, or only a theme / asset similarity?
+
+The chosen trunk should become the anchor for the whole atom-tree.
+
+If no gameplay Skill is truly strong:
+
+- pick the best partial precedent only if it still helps reading
+- record the mismatch clearly in `Selected Gameplay Trunk` and `Gaps`
+
+### Step 3: Deep-read the trunk and adjacent strong candidates
+
+Use:
+
+```bash
+playcraft skills read "<skillRef>"
+```
+
+Deep-read only the trunk and the nearby candidates that may materially help downstream readers.
+
+For each strong candidate, extract:
+
+- what the Skill is mainly for
+- what to read first
+- which imports or adjacent refs matter
+- how its `role[]` helps explain where it sits in the trunk chain
+- the single most important limitation or caveat
+
+For the gameplay trunk specifically, identify:
+
+- **hard deps** — actual imported units / components / infra worth reading alongside it
+- **soft roles** — replaceable semantic slots such as `bgMusic`, `tileTextureSet`, `tutorialOverlay`, or similar role-driven providers
+- **role evidence** — which `role[]` tags on the trunk, adjacent matches, or media candidates help you hypothesize the chain before confirming with actual reads
+
+Do not write implementation steps here. You are building a reading map.
+
+### Step 4: Resolve hard deps and role slots
+
+Use a **role-guided, read-confirmed** process:
+
+1. Start from the trunk's real imports / scaffold notes / adjacent refs.
+2. Use `meta.skillsMatch.items[].role` to spot nearby Skills that likely act as infra, component, UI, audio, or helper precedents.
+3. Use `meta.skillsMatch.mediaGroups[].role` to spot likely providers for replaceable slots.
+4. Confirm the candidate by reading the actual Skill before treating it as selected or resolved.
+
+For each dependency or slot discovered from the trunk:
+
+1. **Hard dep**
+   - If it is a real reusable precedent, include the referenced Skill in `meta.selectedAtoms`
+   - If it is infra with little standalone reading value, mention it in `Gameplay Assembly Link` without bloating `meta.selectedAtoms`
+   - If `role[]` suggests relevance but the actual Skill does not support the chain, drop it and note the mismatch mentally rather than forcing it in
+
+2. **Soft role**
+   - Review `meta.skillsMatch.mediaGroups[]`
+   - Prefer candidates whose `role[]` clearly matches the semantic slot you are resolving
+   - If needed, search alternatives with:
+
+   ```bash
+   playcraft skills filter --role bgMusic --json
+   playcraft skills filter --role tileTextureSet --json
+   ```
+
+   - Confirm the substitute declares the same role before selecting it
+
+3. **No fit**
+   - Record a real `miss`
+   - Do not force a weak candidate just to fill the slot
+
+### Step 4.5: Use `role[]` to explain the chain, not replace reading
+
+`role[]` is especially useful when several matched Skills are all "somewhat relevant" and you need to explain why one stays in the shortlist while another does not.
+
+Use it to answer:
+
+- which candidate looks like the **gameplay trunk**?
+- which candidate looks like a **hard dep / adjacent unit**?
+- which candidate looks like a **replaceable provider** for a semantic slot?
+- which candidate only shares theme, but not the right role in the chain?
+
+When `role[]` conflicts with what the Skill actually contains:
+
+- trust the actual Skill content
+- keep the misleading candidate out of `meta.selectedAtoms`
+- mention the real miss or weaker fit in `Role Resolution` / `Gaps` when useful
+
+### Step 4.6: Supplementary search for peripheral systems and wrapping
+
+After resolving the trunk's direct deps and roles, revisit the peripheral systems and wrapping layers identified in Step 1. These often use different keywords from the core mechanic and are missed by the initial `init-atom-tree --intent`.
+
+For each peripheral system or wrapper identified (e.g. "collection progress", "level/stage structure", "scene transitions", "unlock logic"):
+
+1. Run a targeted search:
+
+   ```bash
+   playcraft skills match --intent "collect,progress,counter,hud"
+   playcraft skills match --intent "level,stage,tutorial-scene,progression"
+   playcraft skills filter --role progressUI --json
+   ```
+
+2. Review results. If a Skill provides a reusable pattern for the peripheral system:
+   - Deep-read it with `playcraft skills read "<skillRef>"`
+   - Decide `use` / `skip` / `miss` as with any other role slot
+   - If `use`, add to `meta.selectedAtoms` and document in `Gameplay Assembly Link`
+
+3. If no Skill matches, record it as a confirmed `miss` in Gaps with a note that a supplementary search was performed.
+
+**Key principle**: Do not assume peripheral systems are always custom. A "collection counter" might have a reusable HUD skill; a "level structure" might have a scene-management skill; a "stage transition" might have an animation skill. Search first, then decide.
+
+### Step 5: Assign `reuseLevel`
+
+Use `Level 0-4` as reference strength:
+
+| Level     | Meaning                                      |
+| --------- | -------------------------------------------- |
+| `Level 4` | Direct precedent; highly aligned             |
+| `Level 3` | Strong precedent with some adaptation needed |
+| `Level 2` | Useful skeleton or pattern                   |
+| `Level 1` | Local idea/reference only                    |
+| `Level 0` | No useful precedent                          |
+
+Use this scale in `atom-tree.md` notes and summary tables.
+
+### Step 6: Write the selected `meta.selectedAtoms` list
+
+Keep `docs/atom-tree.json` minimal and opinionated.
+
+Use this shape:
+
+```json
+{
+  "atoms": ["selected-gameplay-skill", "selected-adjacent-skill", "selected-role-provider"]
+}
+```
+
+Rules:
+
+- include the gameplay trunk first when it is a true selected precedent
+- include only selected `skillRef` strings
+- keep the list small and high-signal
+- do not add role-resolution objects, dependency edges, or reading notes to JSON
+
+### Step 7: Generate and complete `docs/atom-tree.md`
+
+Use the CLI skeleton if helpful:
+
+```bash
+playcraft skills gen-atom-tree-md [--force]
+```
+
+Treat the generated file as a starter only. The final markdown must reflect the real trunk-first reading guide.
+
+### Step 7.1: Required sections in `atom-tree.md`
+
+1. `Acceptance Criteria`
+2. `Selected Gameplay Trunk`
+3. `Gameplay Assembly Link`
+4. `Selected Atoms Summary`
+5. `Selected Skill Notes`
+6. `Role Resolution`
+7. `Gaps`
+
+## Section Contract
+
+### 1. `Acceptance Criteria`
+
+Use:
+
+| itemId | Criteria |
+| ------ | -------- |
+
+Rules:
+
+- one short semantic line per item
+- no implementation steps
+- no repeated long-form spec
+
+### 2. `Selected Gameplay Trunk`
+
+Use:
+
+| trunk | whyClosest | readFirst | keyImportsOrRoles |
+| ----- | ---------- | --------- | ----------------- |
+
+Rules:
+
+- exactly one primary trunk when a real gameplay precedent exists
+- if the fit is partial, say so directly
+- `keyImportsOrRoles` should stay compact; the full explanation belongs below in `Gameplay Assembly Link`
+
+### 3. `Gameplay Assembly Link`
+
+Use:
+
+| from | relation | requiredBy | selected | decision | why | readFirst |
+| ---- | -------- | ---------- | -------- | -------- | --- | --------- |
+
+`relation` should be one of:
+
+- `trunk`
+- `hard dep`
+- `role`
+
+Rules:
+
+- narrate one readable gameplay organization chain starting from the selected trunk
+- `selected` may be `—` when the slot is a true miss
+- `decision` should be `use`, `skip`, or `miss`
+- use `role[]` evidence to explain why a node belongs in the chain when that evidence is helpful, but do not rely on role labels alone
+- keep this as a **reading / organization view**, not an execution sequence
+- this link lives in `docs/atom-tree.md` only; do not mirror it into JSON
+
+### 4. `Selected Atoms Summary`
+
+Use:
+
+| atom | useFor | whySelected | readFirst | linkOrScaffoldHint |
+| ---- | ------ | ----------- | --------- | ------------------ |
+
+Rules:
+
+- `atom` must come from `meta.selectedAtoms`
+- `useFor` should describe the main downstream value
+- `whySelected` should explain why it survived the shortlist
+- `linkOrScaffoldHint` should remain short and practical
+
+### 5. `Selected Skill Notes`
+
+Use:
+
+```markdown
+### {atom}
+
+- Main Value: ...
+- Read First: ...
+- Key Files / Refs: ...
+- Watch Out: ...
+```
+
+Rules:
+
+- keep it short
+- guide reading, do not prescribe implementation
+- focus on practical reuse signal and real reference value
+
+### 6. `Role Resolution`
+
+Use:
+
+| role | selectedProvider | decision | source | why | notes |
+| ---- | ---------------- | -------- | ------ | --- | ----- |
+
+Rules:
+
+- one row per role that materially matters to the chosen gameplay trunk
+- prefer role names that already appear in `skillsMatch.matches[].role` or `skillsMatch.mediaGroups[].role` when they are semantically correct
+- `decision` should be `use`, `skip`, or `miss`
+- `source` may point to `mediaGroups`, `filter --role`, a direct import context, or a matched Skill whose `role[]` helped identify the slot
+- when no provider fits, leave `selectedProvider` as `—` and mark `miss`
+
+### 7. `Gaps`
+
+Use:
+
+| need | whyMissing | impact |
+| ---- | ---------- | ------ |
+
+Rules:
+
+- list only true gaps
+- prefer precise misses over vague uncertainty
+- do not pad this section
+
+## Output Quality Bar
+
+Good output should feel like a fast reading guide that tells the next reader:
+
+- which Skill is the gameplay trunk
+- how the important adjacent Skills organize around it
+- which role slots were actually resolved
+- where the real misses are
+
+Bad output:
+
+- copies full Skill docs
+- turns into implementation planning
+- writes a dependency graph into JSON
+- lists skills without explaining why they matter
+- floods the file with weak candidates
+
+## Writing the Gameplay Assembly Link
+
+Use this mental model:
+
+```text
+gameplay trunk
+  ├── hard deps           ← real imported units / adjacent components worth reading
+  ├── soft roles          ← replaceable slots resolved by provider choice or miss
+  └── downstream refs     ← UI / VFX / audio / helper references that improve reuse
+```
+
+### How to build the link
+
+1. Start from the selected gameplay trunk.
+2. Inspect its imports / scaffold notes / adjacent refs.
+3. Use `role[]` on matched Skills and media candidates to propose likely hard deps and soft slots.
+4. Separate **hard deps** from **soft roles**.
+5. For each role, record `use`, `skip`, or `miss`.
+6. Keep only the selected, high-value Skills in `meta.selectedAtoms`.
+7. Write the full organization story in `Gameplay Assembly Link` and `Role Resolution`.
+
+### Completeness checklist
+
+```text
+□ Gameplay trunk is explicitly named
+□ Every selected adjacent Skill has a clear reason to stay in meta.selectedAtoms
+□ Every material role is resolved as use / skip / miss
+□ True misses are recorded in Gaps
+□ atom-tree.md explains how the selected Skills organize the game
+□ atom-tree.json remains a compact string list, not a graph
+```
+
+## Step 8: Validate and link (mandatory final step)
+
+After writing `atom-tree.json` + `atom-tree.md`, run these two commands in order:
+
+```bash
+# 1. Validate — confirms the JSON contract is still valid
+playcraft skills validate-atom-tree-selection
+
+# 2. Link — symlinks selected skills into .claude/skills/ so downstream agents can read them locally
+playcraft skills link --from-atom-tree --prune
+```
+
+**Do not STOP until both commands succeed.** If validate fails, fix the JSON and retry. If link fails, check the error and resolve it.
+
+**Validation reminder**:
+
+- `meta.selectedAtoms` should contain selected `skillRef` strings only
+- `skillsMatch` should remain the broader match context
+- the gameplay organization link should exist in `docs/atom-tree.md`, not in JSON
+
+**Verification:** After link completes, confirm `.claude/skills/.playcraft-dag-links.json` exists. This file proves the batch link was executed.

package/project-template/.claude/agents/refs/skill-value-layers.md

@@ -0,0 +1,145 @@
+# Skill 内容四层价值模型
+
+> **读者**：Developer / TA / Game Designer — 任何需要读取和使用 Skill 的 Agent。
+> **用途**：理解一个 Skill 提供了哪些可复用价值、怎么用、什么不能做。
+
+---
+
+## Skill 类型速查
+
+PlayCraft Skill 库按后缀分类，不同类型提供不同维度的复用价值：
+
+| Skill 后缀     | 类型         | 核心价值                           | 提供的复用内容                                                                                                |
+| -------------- | ------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `.aigameplay`  | 核心玩法规则 | 完整的 PGS 规则定义 + reducer 接口 | `ref/pgs-schema.json`（规则骨架）、`ref/reducer.template.ts`（接口约束）、testCases（验证用例）、分步函数签名 |
+| `.aicomponent` | 可复用组件   | 独立的代码模块 + 集成契约          | `ref/` 中的源码、Adapter（Provides/Requires/Consumed by）、Key API 签名、配置参数、使用示例                   |
+| `.aiconfig`    | 配置/数据    | 数据结构、难度曲线、平台配置       | 配置 schema、默认参数、生成器逻辑                                                                             |
+| `.aiimage`     | 图像资产     | 图像生成 prompt + 风格参考         | prompt 模板、风格约束、后处理参数                                                                             |
+| `.aiaudio`     | 音频资产     | 音频生成 prompt + 处理参数         | 音效/BGM prompt、时长参数、循环设置                                                                           |
+| `.aivalidator` | 验证/测试    | 自动化质量检查逻辑                 | 检查规则、通过标准、边界条件                                                                                  |
+
+---
+
+## 四层价值模型
+
+每个 Skill 提供的复用价值分布在四个层级上。下游 Agent 读取 Skill 时必须按这四个层级结构化提取信息：
+
+```
+┌─────────────────────────────────────────────────────┐
+│ L4 · Scaffold 可直接复用的代码          最高价值     │
+│   → ref/ 源码、类实现、完整模块代码                   │
+│   → 使用方式：scaffold 后直接 import 使用              │
+│   → 有现成的就直接用，比自己从零写更快更稳             │
+├─────────────────────────────────────────────────────┤
+│ L3 · Assets 预制资产                     高价值      │
+│   → mediaGroups 图片/音频/3D 模型                    │
+│   → 使用方式：playcraft skills link 后做后处理        │
+│   → 约束：存在匹配项时必须 link，不得无视后从零生成     │
+├─────────────────────────────────────────────────────┤
+│ L2 · Recipe AI 可再生产的模板/参数        中价值      │
+│   → prompt 模板、生成参数、配置范例                    │
+│   → 使用方式：作为 AI 生产的输入指导，按参数生成        │
+│   → 约束：不可脱离 Recipe 约束自由发挥                 │
+├─────────────────────────────────────────────────────┤
+│ L1 · Reference 设计参考信息               基础价值     │
+│   → 布局坐标、状态机设计、规则逻辑、API 设计模式        │
+│   → 使用方式：作为实现的蓝图参考，非直接代码复用        │
+│   → 约束：借鉴思路但不可照搬不适用的部分               │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 每个 Skill 的结构化字段
+
+下游 Agent 读取 SKILL.md 时，必须关注以下标准字段：
+
+| SKILL.md 字段                   | 含义                                                  | 谁最关注            | 提取内容                                         |
+| ------------------------------- | ----------------------------------------------------- | ------------------- | ------------------------------------------------ |
+| **Recipe**                      | 产出物 + 参考文件 + 核心约束 + 变体 fork 指引         | Developer, TA       | 做什么、产出什么、fork 变体方式                  |
+| **Result**                      | 最终产物文件 + 格式 + 验证方式                        | Developer           | 做到什么算完成                                   |
+| **Binding**                     | 绑定角色 + 挂载目标路径 + 接口契约                    | Developer           | 代码应该放在哪、接口是什么                       |
+| **Scaffold**                    | scaffold 的目标路径 + 源路径                          | Developer           | `playcraft skills scaffold` 的产出位置           |
+| **Adapter**                     | Provides / Requires / Consumed by / Integration point | Developer           | 模块依赖图、集成入口                             |
+| **Imports**                     | 硬依赖 / 软槽位依赖                                   | Developer, TA       | 必须加载的外部模块 + 可替换的资源                |
+| **Key API / 关键接口**          | TypeScript 接口签名、方法列表                         | Developer           | 构造参数、方法名、返回值类型                     |
+| **配置**                        | 可配置参数 + 默认值                                   | Developer, TA       | 哪些行为可通过 config 修改                       |
+| **使用示例**                    | 代码示例                                              | Developer           | 最小可用调用链                                   |
+| **渲染集成** (仅 `.aigameplay`) | 逻辑与动画分离原则、分步函数列表                      | Developer           | 禁止 dispatch() 全量重建，必须用分步函数驱动动画 |
+| **Skill Definition**            | 工具列表 + prompt_extension                           | Orchestrator, Agent | AI 执行时的工具和指令扩展                        |
+
+---
+
+## Skill 读取三层次（必须遵守）
+
+```
+Level 1 · SKILL.md 设计文档 — 了解"这个 Skill 是什么、提供什么"
+Level 2 · ref/ 源码 — 提取真实类签名、事件名、config 结构（BINDING AUTHORITY）
+Level 3 · assets/ 实际文件 — 确认 frame 名、文件路径、资源尺寸
+```
+
+**铁律**：SKILL.md 和源码可能有出入 → **以源码为准**。只读 SKILL.md 不算理解 Skill；不读源码就集成的代码必出 bug。
+
+### Developer 的读取倾向（L1–L4 通用）
+
+无论 skillRef 对应哪个复用层级，Developer 的底层姿态是一致的：**先读代码，再实践**。
+
+| 层级         | 标签          | SKILL.md 告诉你                     | ref/ 源码告诉你                                    | 落地方式                               |
+| ------------ | ------------- | ----------------------------------- | -------------------------------------------------- | -------------------------------------- |
+| L4 Scaffold  | `scaffold`    | 能力入口、产出物、scaffold 目标路径 | **构造参数、方法签名、事件名**（与文档可能有出入） | scaffold import 后按源码接口集成       |
+| L3 Assets    | `mediaGroups` | 用法、Binding 挂载点                | **frame 名、路径格式、atlas 结构**                 | 文件已由 ref-flow link，按源码确认绑定 |
+| L2 Recipe    | `reference`   | 状态机结构、事件模型                | **实际数据流、dispatch 约束、分步函数签名**        | 借鉴核心架构，替换业务逻辑             |
+| L1 Reference | `design-only` | API 设计思路、算法概要              | **实际接口约束、边界条件**                         | 借鉴思路，不照搬不适用部分             |
+
+> L4 也要读源码——scaffold 进来的类其构造参数可能与文档不一致。这不是"勤快程度"问题，是正确性问题。
+
+---
+
+## Skill 库层次结构（从 abstraction-methodology）
+
+PlayCraft Skill 库采用分层架构，每一层有独立的权威边界：
+
+```
+engine       ← 引擎基础设施（框架适配、布局系统、场景管理、状态管理）
+asset        ← 资源层（可替换资源族：音频/配置/图片，无行为权威）
+gameplay     ← 玩法真理层：规则、状态、合法操作、数据结构、算法
+  ├── gameplay-rule    (核心玩法规则：胜负判定、进度、实体调度)
+  ├── gameplay-data    (数据抽象：类型定义、关卡格式、配置 schema)
+  ├── gameplay-system  (补充子系统：货币、等级、提示、undo)
+  └── gameplay-entity  (实体定义：自治游戏对象，组件/状态机/物理)
+visual       ← 非 UI 世界视觉：对象外观、场景合成、VFX 映射
+ui           ← 屏幕空间 UI：引导、转场、HUD、结果面板
+misc         ← 图外：验证器、质量闸门、测试脚本
+```
+
+**关键关系**：
+
+- `gameplay` 拥有玩法真理，不依赖 `visual` 也可逻辑完整
+- `visual` 和 `ui` 消费 gameplay 状态，不得反向拥有玩法真理
+- `.aigameplay` 内部区分 Entity Layer（数据结构）和 Mechanics Layer（交互规则），下游可只复用 Entity Layer 而替换 Mechanics
+- `.aicomponent` 声明 Adapter（Provides/Requires/Consumed by），形成显式依赖图
+
+---
+
+## 复用级别定义
+
+在 atom-tree.md 的 `Matched Skills Summary` 中，每个 skillRef 应声明其复用级别：
+
+| 复用级别      | 标签           | 含义                                                    | 编码约束                                         |
+| ------------- | -------------- | ------------------------------------------------------- | ------------------------------------------------ |
+| `scaffold`    | L3-L4 直接复用 | Skill 有 ref/ 源码且功能高度匹配，scaffold 后改配置即可 | 主动参考 scaffold 代码，能省去大量从零实现的工作 |
+| `reference`   | L2 骨架复用    | 架构匹配但需替换业务逻辑，保留核心设计模式              | 借鉴状态机结构/事件名/数据流等核心模式           |
+| `design-only` | L1 设计参考    | Skill 提供设计灵感但功能差异大，仅借鉴设计思路          | 参考 API 设计/算法/布局/状态机思路               |
+
+**原则**：Skill 库的价值在于让你站在已有高质量实现的肩膀上——不是为了合规填表。读了、参考了、产出更好代码就是好的。如果某个 Skill 确实不适用，记录原因后从零实现完全 OK。
+
+---
+
+## mediaGroups 使用纪律
+
+`skillsMatch.mediaGroups` 包含自动发现的可复用预制资产。下游 Agent 必须：
+
+1. **读取** mediaGroups 并对每个 `candidates[]` entry 判断匹配度
+2. **决策**：`use`（直接 link + 后处理）/ `skip`（记录原因）/ `need-production`（需 AI 生成）
+3. **记录**：在 atom-tree.md 的 `mediaGroups Disposition` 表格中填写决策
+4. **禁止**：mediaGroups 中有匹配项却无视、从零生成