@playcraft/cli 0.0.42 → 0.0.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/atom-plan/validate-asr-coverage.js +317 -0
  2. package/dist/commands/prad.js +61 -0
  3. package/dist/commands/remix.js +4 -2
  4. package/dist/commands/skills.js +24 -0
  5. package/dist/prad/atom-ref.js +23 -0
  6. package/dist/prad/check.js +377 -0
  7. package/dist/prad/check.test.js +27 -0
  8. package/dist/prad/explain.js +109 -0
  9. package/dist/prad/load-spec.js +23 -0
  10. package/dist/prad/paths.js +83 -0
  11. package/dist/prad/skills-index.js +60 -0
  12. package/package.json +3 -3
  13. package/project-template/.claude/agents/designer.md +26 -22
  14. package/project-template/.claude/agents/developer.md +2 -0
  15. package/project-template/.claude/agents/pm.md +3 -1
  16. package/project-template/.claude/agents/refs/designer-deliverable-spec.md +46 -7
  17. package/project-template/.claude/agents/refs/designer-handoff-v2-checklist.md +21 -13
  18. package/project-template/.claude/agents/refs/designer-style-exploration-flow.md +39 -9
  19. package/project-template/.claude/agents/refs/developer-dev-handoff.md +1 -1
  20. package/project-template/.claude/agents/refs/pm-workflow-detail.md +18 -2
  21. package/project-template/.claude/agents/refs/reviewer-convergence-eval.md +17 -5
  22. package/project-template/.claude/agents/refs/ta-pipeline-cookbook.md +42 -6
  23. package/project-template/.claude/agents/reviewer.md +8 -5
  24. package/project-template/.claude/agents/technical-artist.md +2 -0
  25. package/project-template/.claude/hooks/README.md +34 -6
  26. package/project-template/.claude/hooks/asr-coverage-validate.mjs +381 -0
  27. package/project-template/.claude/hooks/validate-workflow-stop.mjs +113 -7
  28. package/project-template/.claude/skills/playcraft-asset-state-sheet/SKILL.md +76 -22
  29. package/project-template/.claude/skills/playcraft-image-generation/SKILL.md +19 -0
  30. package/project-template/docs/team/agent-runtime-matrix.md +71 -39
  31. package/project-template/docs/team/atom-plan-format.md +68 -0
  32. package/project-template/docs/team/core-model.md +20 -19
  33. package/project-template/docs/team/workflow-consistency-checklist.md +52 -0
  34. package/project-template/templates/atom-plan.template.json +18 -0
  35. package/project-template/templates/designer-log.template.md +78 -5
  36. package/project-template/templates/layout-spec.template.md +48 -8
  37. package/project-template/templates/ta-log.template.md +50 -22
@@ -14,6 +14,23 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
14
14
  - **仅在 Gate #2a 通过、`selectedMcOption` 已写入 `project-state.md` 之后** 才能生成 ASR
15
15
  - **禁止**为未选中的 MC 方案生成 ASR
16
16
  - 两张板均使用已确认 MC 作 `--reference-image`,且 `--image-model` 与 MC 一致
17
+ - **生成 ASR 前必读** `playcraft-image-generation` Skill §3(色幕矩阵)— 格内元素须可抠
18
+
19
+ ## 0.1 Sheet 底色 + 格内抠图(必读)
20
+
21
+ > **整图 opaque 是预期行为** — ASR PNG 本身**不需要**也**不应**交付透明 PNG。TA 负责 `crop → remove-background → WebP atlas`。
22
+ > Designer 的职责是:让 **每个格内的单元素** 在 crop 后能被 TA 可靠抠图。
23
+
24
+ | 层级 | 规则 |
25
+ | --------------------- | --------------------------------------------------------------------------------- |
26
+ | **Sheet canvas** | 不透明;默认 **中性灰 `#808080` flat background**(整板统一,禁止渐变/场景/纹理) |
27
+ | **Sheet 备选** | 若全板元素均非金/橙/绿,可用 **统一绿幕 `#00FF00`** 整板底色 |
28
+ | **Cell 内容** | **单元素 isolated、居中**;禁止格内地面/阴影/白盒/场景/context |
29
+ | **金/橙/黄/绿元素格** | 该格背景用 **蓝幕 `#0000FF`**(见 `playcraft-image-generation` 色幕矩阵) |
30
+ | **蓝/紫元素格** | 该格背景用 **绿幕 `#00FF00`** |
31
+ | **Designer 禁止** | 对 ASR 做 `remove-background` 量产;那是 TA 在 `production` 的工作 |
32
+
33
+ **错误示例(必须重生成)**:格内白底方块、渐变底、整屏 HUD 截屏、两元素叠在同一格、元素带地面阴影。
17
34
 
18
35
  ## 1. 交付物:两张状态参考板
19
36
 
@@ -24,6 +41,8 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
24
41
 
25
42
  `[X]` = `selectedMcOption`(A/B/C)。
26
43
 
44
+ **多板扩展**(`unique element types > 12` 或 Layer1 槽位 > 12):允许追加 `element_state_sheet_[X]_2.png`;Coverage Matrix 的 `sheet` 列填 `element_2`。详见 `docs/team/atom-plan-format.md` § `asrSlot`.
45
+
27
46
  ### UI State Reference Sheet — 放什么
28
47
 
29
48
  - CTA 按钮、安装条、HUD 条、进度/分数框、手指引导、高亮框、徽章、弹窗底板等
@@ -35,11 +54,23 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
35
54
  ### Element State Reference Sheet — 放什么
36
55
 
37
56
  - 棋子、牌面、角色、道具、匹配特效关键帧等(MC 概念面板里出现的玩法元素)
38
- - 每个元素类型 **2–3 个代表状态**(完整全集由 TA `production` 扩展),例如:
57
+ - 每个元素 **type** 至少 **1 个代表态** 占物理槽位;同 type 的 color 变体可标 `CoverageLayer: ta-extends`(见 `designer-deliverable-spec.md`)
58
+ - 每 type **2–3 个代表状态** 优先(完整全集由 TA 在 `production` 扩展),例如:
39
59
  - `tile_gold`: idle | selected | matched
40
60
  - `panda_char`: idle | happy | win
41
61
 
42
- **元素总数**:每张板独立统计,每板 **8–12 个状态槽**(宁可少槽、加大间距,也不要重叠)。
62
+ **物理槽位预算**:每张板 **8–12 个状态槽**(宁可少槽、加大间距,也不要重叠)。
63
+ **Coverage Matrix 100% 行** ≠ 每行都有物理槽位 — 见 §1.1 三层覆盖。
64
+
65
+ ### 1.1 三层覆盖(与 Coverage Matrix 对齐)
66
+
67
+ | CoverageLayer | 含义 | Matrix 填写 |
68
+ | -------------- | ------------------------------------------- | ---------------------------------------- |
69
+ | **on-asr** | 该 contract id 在 ASR PNG 有物理槽位 `R#C#` | `ASR sheet` + `Grid` |
70
+ | **mc-crop** | MC Panel 1 可见、ASR 无槽位 | `ASR sheet` = `MC-crop` + Panel 区域说明 |
71
+ | **ta-extends** | 颜色变体 / 额外状态,TA 从 ASR 或 MC 扩展 | `TA extends? = yes` + Style Intent 一句 |
72
+
73
+ **硬规则**:每种 **element type** 至少在 **on-asr** 或 **mc-crop** 有一处代表态;禁止全部 `ta-extends` 且 MC/ASR 均无参考。
43
74
 
44
75
  ## 2. 布局策略 — 规则网格、零重叠
45
76
 
@@ -64,17 +95,21 @@ Row 2: [char idle] [char happy] [char win] (empty)
64
95
 
65
96
  ## 3. Prompt 模板
66
97
 
98
+ **生成前**:按 `playcraft-image-generation` §3 为每格元素选定 cell 背景色(灰/绿/蓝幕)。
99
+
67
100
  **UI 板** — 在 prompt 中显式写 `UI component state reference sprite sheet`:
68
101
 
69
102
  ```
70
103
  UI component state reference sprite sheet for [GAME_TYPE] playable ad.
71
- 3840x1152 canvas, [BG_COLOR] flat background.
104
+ 3840x2160 canvas, solid flat #808080 gray background on entire sheet. NO gradient, NO scene.
72
105
 
73
106
  STRICT LAYOUT: orthographic grid, fixed non-overlapping cells. Each UI widget state in exactly one cell, 80px margin, 100px column gap, 120px row gap. NO overlapping.
74
107
 
108
+ Each cell: ONE isolated UI widget, centered, no drop shadow on floor, no white box behind widget, no scene context.
109
+
75
110
  Row 1 — CTA / HUD:
76
- - CTA install button, default state: ...
77
- - CTA install button, pressed state: ...
111
+ - Cell 1: CTA install button, default state, isolated, centered ...
112
+ - Cell 2: CTA install button, pressed state, isolated, centered ...
78
113
  ...
79
114
 
80
115
  Art style: [SAME as Master Composite]. Front-facing UI, crisp edges, consistent lighting.
@@ -84,18 +119,21 @@ Art style: [SAME as Master Composite]. Front-facing UI, crisp edges, consistent
84
119
 
85
120
  ```
86
121
  Gameplay element state reference sprite sheet for [GAME_TYPE].
87
- [same STRICT LAYOUT block]
122
+ 3840x2160 canvas, solid flat #808080 gray background on entire sheet. NO gradient, NO scene.
123
+
124
+ STRICT LAYOUT: [same as UI sheet]
125
+
126
+ Each cell: ONE isolated game element, centered. Gold/orange/yellow elements: cell background solid bright blue #0000FF. Blue/purple elements: cell background solid bright green #00FF00. NO white box, NO ground shadow, NO scene.
88
127
 
89
128
  Row 1 — Core tiles/items:
90
- - [Element] idle: ...
91
- - [Element] selected: ...
92
- - [Element] matched: ...
129
+ - Cell 1: [Element type A] idle, isolated, centered ...
130
+ - Cell 2: [Element type A] selected, isolated, centered ...
93
131
  ...
94
132
 
95
133
  Art style: [SAME as Master Composite].
96
134
  ```
97
135
 
98
- **Prompt 必须包含**:`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素。
136
+ **Prompt 必须包含**:`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素、`isolated`、`NO white box`、`NO scene`.
99
137
 
100
138
  ## 4. 生成命令
101
139
 
@@ -117,25 +155,41 @@ playcraft tools generate-image \
117
155
  --image-model <与 MC 相同> \
118
156
  --aspect-ratio 16:9 \
119
157
  --image-size 4K
158
+
159
+ # 元素板溢出时(可选第二张)
160
+ playcraft tools generate-image \
161
+ --prompt "<Element sheet part 2 prompt>" \
162
+ --output assets/images/reference/element_state_sheet_[X]_2.png \
163
+ --reference-image assets/images/storyboard/master_composite_option_[X].png \
164
+ --image-model <与 MC 相同> \
165
+ --aspect-ratio 16:9 \
166
+ --image-size 4K
120
167
  ```
121
168
 
122
169
  ## 5. 核查清单
123
170
 
124
- | # | 核查项 | 标准 |
125
- | --- | ------ | ---------------------------------------- |
126
- | 1 | 时机 | `selectedMcOption` 已设置 |
127
- | 2 | 数量 | UI 板 + 元素板各一张 |
128
- | 3 | 视觉 | 两板均无重叠;有重叠则重生成 |
129
- | 4 | 语义 | UI 板无玩法棋子;元素板无整屏 HUD 截屏 |
130
- | 5 | 清单 | `designer-log` 含每张板的状态→槽位映射表 |
171
+ | # | 核查项 | 标准 |
172
+ | --- | ------------ | ------------------------------------------------------------------------------ |
173
+ | 1 | 时机 | `selectedMcOption` 已设置 |
174
+ | 2 | 数量 | UI 板 + 元素板各至少一张 |
175
+ | 3 | 视觉 | 两板均无重叠;有重叠则重生成 |
176
+ | 4 | 语义 | UI 板无玩法棋子;元素板无整屏 HUD 截屏 |
177
+ | 5 | 格内可抠 | 目视:无白盒/场景底/格内渐变;金橙元素格用蓝幕 |
178
+ | 6 | 整图 opaque | 预期行为 — 不要求透明 PNG |
179
+ | 7 | 清单 | `designer-log` § **ASR Coverage Matrix** 100% contract 行 + `CoverageLayer` 列 |
180
+ | 8 | 网格元数据 | Sheet grid 表:rows × cols + cell W×H + padding(非 `{{placeholder}}`) |
181
+ | 9 | type 代表态 | 每种 element type 至少在 on-asr 或 mc-crop 有一处 |
182
+ | 10 | asrSlot 镜像 | on-asr 行已写入 `atom-plan.json` → `atoms[].asrSlot` |
131
183
 
132
184
  ## 6. 与 TA 的协作协议
133
185
 
134
- Designer:风格与 MC 一致;在 `designer-log.md` 标注每张 ASR **已覆盖的状态** vs **TA 需扩展的状态**。
186
+ Designer:风格与 MC 一致;在 `designer-log.md` § **ASR Coverage Matrix** 标注 **CoverageLayer** 与 **TA 需扩展的状态**。
135
187
 
136
188
  TA 提取(详见 `playcraft-masking`):
137
189
 
138
- | 来源图 | 推荐方式 | 说明 |
139
- | -------------------- | -------------------------- | ----------------------------------------------------------------------------------- |
140
- | **ASR**(规则网格) | `playcraft image crop` | 槽位坐标来自 `designer-log` ASR State Inventory;**禁止**对 ASR 用纯 text `segment` |
141
- | **Master Composite** | `decompose-layers` 或 crop | ASR 未覆盖的类型从此补提取 |
190
+ | 来源图 | 推荐方式 | 说明 |
191
+ | -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
192
+ | **ASR**(规则网格) | `playcraft image crop` | 槽位坐标来自 `designer-log` § **ASR Coverage Matrix**(含 Sheet grid 元数据)或 `atom-plan.json` → `asrSlot`;**禁止**对 ASR 用纯 text `segment` |
193
+ | **Master Composite** | `decompose-layers` 或 crop | `mc-crop` 层从此补提取 |
194
+
195
+ **若 TA crop 后仍不可抠**(白边/色幕残留/元素被截断)→ `routeTo: designer` 重生成 ASR 格,**非** TA 自行重画 ASR。
@@ -258,6 +258,25 @@ playcraft image overlay \
258
258
 
259
259
  ---
260
260
 
261
+ ## 3.1 ASR 专用分支(Designer · Gate #2b)
262
+
263
+ > **Read `playcraft-asset-state-sheet` Skill first.** ASR 是制作期参考板,不是 runtime 透明资产。
264
+
265
+ | 阶段 | Designer | TA |
266
+ | ----------------- | ------------------------------------- | ----------------------------- |
267
+ | ASR 整图 | **opaque**(灰底或统一色幕)— 正常 | — |
268
+ | ASR 格内元素 | **isolated** + 按色幕矩阵选 cell 背景 | `crop` 后 `remove-background` |
269
+ | remove-background | **禁止** — Designer 不做 | production Wave 2 |
270
+
271
+ **Designer ASR prompt 要点**:
272
+
273
+ 1. Sheet canvas:`solid flat #808080` 或整板统一绿幕(非渐变)
274
+ 2. 每格:`ONE isolated element, centered, NO white box, NO scene, NO ground shadow`
275
+ 3. 金/橙/黄/绿元素格 → cell 背景 `#0000FF`;蓝/紫 → `#00FF00`
276
+ 4. 生成后**目视**格内可抠性 — 不要求 `channels=4`(那是 TA 后处理产物)
277
+
278
+ ---
279
+
261
280
  ## 4. 脚本决策
262
281
 
263
282
  - **<=5 个文件** → 直接使用 CLI 命令
@@ -1,62 +1,94 @@
1
1
  # Agent Runtime Matrix
2
2
 
3
+ > **Workflow spec**: `convergence-v1` (see [`workflow-changelog.md`](workflow-changelog.md)). Legacy stages `integration` / `review` / `rework` and fields `reworkRound` / `reviewerDevCheck` are **removed** — replaced by `ui_pass` / `ui_review` / `ui_rework` / `gameplay_pass` and `uiReworkRound` / `devStatus` / `loadCheck`.
4
+
3
5
  Fake-invoke reference: `(stage, gates snapshot, handoff snapshot) → expected behavior / forbidden behavior`.
4
6
 
5
7
  See also: [agent-conduct.md](agent-conduct.md), [collaboration.md](collaboration.md) § Agent Handoff, [workflow-consistency-checklist.md](workflow-consistency-checklist.md).
6
8
 
7
9
  ## PM
8
10
 
9
- | stage | gates | handoff | Expected | Forbidden |
10
- | ------------ | ---------------- | --------------------------------- | -------------------------------- | ---------------------------------------------- |
11
- | `pm` | `#1` pending | `gate_pending: "1"`, `user_gate` | Orchestrator runs Gate #1 only | Invoke designer before Gate #1 pass |
12
- | `pm` | `#1` not started | — | Write four docs pendingSTOP | Skip four docs; set `stage: style_exploration` |
13
- | `production` | `#1` passed | spec-gap | Patch layout/atom ≤5 min → STOP | Re-open Gate #1 |
14
- | any | — | `subagent_stop`, pm, orchestrator | Reply already STOPPED | Rewrite four docs |
11
+ | stage | gates | handoff | Expected | Forbidden |
12
+ | ------------ | ---------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
13
+ | `pm` | `#1` not started | | Write four docs (project-state, design-brief, layout-spec, atom-plan) → `gates.#1 = pending` → STOP | Skip four docs; set `stage: style_exploration` |
14
+ | `pm` | `#1 = pending` | `gate_pending: "1"`, `user_gate` | Orchestrator runs Reviewer `design_check` Gate #1then Gate #1 only | Invoke designer before Gate #1 pass |
15
+ | `production` | `#1 = passed` | `block_reason: spec-gap` | Patch `layout-spec` / `atom-plan` per spec-gap entry 5 min → STOP | Re-open Gate #1; rewrite four docs |
16
+ | any | — | `subagent: pm`, `subagent_stop: true` | Reply **Already STOPPED** — do nothing | Rewrite four docs |
15
17
 
16
18
  ## Designer
17
19
 
18
- | stage | gates | handoff | Expected | Forbidden |
19
- | ------------------- | ------------------------------------ | -------------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
20
- | `style_exploration` | `#2a` not passed | — | Phase 1 Skill Discovery → style-exploration-flow`#2a` pending | Skip Skill Discovery; MC before art-style-guide |
21
- | `style_exploration` | `#2a` pending | `gate_pending: "2a"` | Orchestrator Gate #2a only | User A/B/C in chat |
22
- | `style_exploration` | `#2a` passed, `selectedMcOption` set | — | ASR 双板 + docs`#2b` pending | Regenerate MC options |
23
- | `style_exploration` | `#2b` pending | `gate_pending: "2b"` | Orchestrator Gate #2b | Phase 2 audio |
24
- | `production` | `#2b` passed | — | Ph.2 atoms + audiotrack done STOP | Set `stage` |
25
- | `rework` | — | routeTo Designer | Fix report paths → STOP | Full style re-exploration |
20
+ | stage | gates | handoff | Expected | Forbidden |
21
+ | --------------------------- | -------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
22
+ | `style_exploration` | `#2a` not passed | — | Phase 1 Skill Discovery → MC ≥2 options `gates.#2a = pending` → STOP | Skip Skill Discovery; MC before art-style-guide |
23
+ | `style_exploration` | `#2a = pending` | `gate_pending: "2a"`, `user_gate` | Orchestrator runs Gate #2a only | Present A/B/C choice to user in chat |
24
+ | `style_exploration` | `#2a = passed`, `selectedMcOption` set | — | ASR 双板 (UI + element) + Handoff Pack `gates.#2b = pending` → STOP | Regenerate MC options |
25
+ | `style_exploration` | `#2b = pending` | `gate_pending: "2b"`, `user_gate` | Orchestrator runs Reviewer `design_check` Gate #2b → then Gate #2b | Start Phase 2 audio before Gate #2b pass |
26
+ | `production` | `#2b = passed` | — | Ph.2: audio + digit strip + VisualAtom status (ASR-covered done) → STOP when all `assignTo: Designer` atoms `done` | Set mainline `stage`; batch produce element PNGs at `assetMapping` |
27
+ | `ui_rework` | — | `block_reason: routeTo Designer` | Fix report paths only (audio mood, ICP supplementary PNG) → STOP | Full style re-exploration |
28
+ | `ui_pass` / `gameplay_pass` | — | `devStatus: blocked_upstream`, routeTo Designer | Upstream blocker fixes per `developer-log` → STOP | Modify `game/` |
26
29
 
27
30
  ## Technical Artist
28
31
 
29
- | stage | gates | handoff | Expected | Forbidden |
30
- | ------------- | ------------------------- | ------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------- |
31
- | `production` | `#2b` passed, Wave 1 done | — | Spec checkbulk**webp atlas+json** ComplianceSTOP when TA atoms done | Start before Designer Wave 1 done; set `stage` |
32
- | `integration` | — | `blocked_upstream`, routeTo TA | Fix listed paths → STOP | `npm run dev` |
33
- | `rework` | — | Action Items TA | Scoped fixes → STOP | Redefine MC |
32
+ | stage | gates | handoff | Expected | Forbidden |
33
+ | --------------------------- | --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
34
+ | `production` | `#2b = passed`, Wave 1 done | — | Step 0a Upstream Intake Step 0 Pre mediaGroups Skill Preflight Style Interpretation Production Plan Step 0e Transparency → bulk → Compliance green → STOP | Start before Designer Wave 1 done; set `stage` |
35
+ | `ui_pass` | — | `devStatus: blocked_upstream`, routeTo TA | Fix listed paths only re-Compliance affected items → STOP | Run `npm run dev`; design new elements |
36
+ | `ui_rework` | — | Action Items routeTo TA | Fix `ui_diff` report items at contract paths → STOP | Redefine MC; modify `game/` |
37
+ | `ui_pass` / `gameplay_pass` | — | `subagent: technical-artist`, `subagent_stop: true` | Reply **Already STOPPED** | Continue producing |
34
38
 
35
39
  ## Developer
36
40
 
37
- | stage | gates | handoff | Expected | Forbidden |
38
- | ------------- | ----- | ----------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------- |
39
- | `production` | — | — | **Do not run** — orchestrator invokes Developer only in `integration` | Any `game/**` work in `production` |
40
- | `integration` | — | — | Spec Quick-Check → Skill Preflight → PGS/scenes → bind assets → `npm run dev` → ready | Skip Spec Quick-Check; `stage: review` self-write |
41
- | `integration` | — | ready + invoke reviewer | STOP handoff | Skip Reviewer invoke |
42
- | `rework` | — | — | Fix Developer Action Items re-integrate | `playcraft build` as done |
41
+ | stage | gates | handoff | Expected | Forbidden |
42
+ | --------------- | ----- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
43
+ | `production` | — | — | **Do not run** — orchestrator invokes Developer only in `ui_pass` / `gameplay_pass` / `ui_rework` | Any `game/**` work in `production` |
44
+ | `ui_pass` | — | — | Upstream Intake → Spec Quick-Check → Skill Preflight → UI Pass Plan → bind real assets → `npm run dev` → `devStatus: ui_ready` + `devUrl` → STOP | Implement gameplay rules (PGS / scoring / win-lose); set `devStatus: ready` |
45
+ | `ui_pass` | — | `devStatus: ui_ready` | Handoff `next_orchestrator_action: "Invoke @reviewer ui_diff"` STOP | Skip Reviewer invoke; advance to `gameplay_pass` |
46
+ | `ui_review` | — | — | **Do not run** Reviewer's turn | Edit `game/**` |
47
+ | `ui_rework` | — | Action Items routeTo Developer | Fix UI Diff Report items → re-run `npm run dev` → `devStatus: ui_ready` → STOP | Rewrite UI shell; mark `ui_ready` with open `devBlockers` |
48
+ | `gameplay_pass` | — | — | Gameplay Pass Plan → PGS + state machine + first-level success → `npm run dev` → `devStatus: ready` + `devUrl` → STOP | Rewrite UI layout (unless open `ui_diff` items); set `devStatus: ready` with open `devBlockers` |
49
+ | `gameplay_pass` | — | `devStatus: ready` | Handoff `next_orchestrator_action: "Invoke @reviewer load_check"` → STOP | Treat `playcraft build` as required for `done` |
50
+ | any | — | `devStatus: blocked_upstream` | Write `devBlockers` (path, issue, routeTo TA/Designer/PM), STOP for orchestrator to re-invoke upstream | Use placeholder assets; silently skip atoms |
43
51
 
44
52
  ## Reviewer
45
53
 
46
- | stage | gates | handoff | Expected | Forbidden |
47
- | -------- | ----- | ------- | ---------------------------------------------- | --------------------- |
48
- | `review` | | | Dev walkthrough**六维度 ≥24/30, no vetoes** | Edit production files |
49
- | `review` | — | pass | `reviewerDevCheck: passed`, Gate #3 handoff | `AskUserQuestion` |
50
- | `review` | — | fail | `reworkRound` +1, handoff rework | Write `stage: rework` |
54
+ | stage | gates | handoff | Expected | Forbidden |
55
+ | ----------------------------- | --------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
56
+ | `pm` | `#1 = pending` | invoked as `design_check Gate #1` | Soft checklist on four docs (completeness only) write `review-report.md` STOP | Judge subjective design quality |
57
+ | `style_exploration` | `#2b = pending` | invoked as `design_check Gate #2b` | Soft checklist on MC + ASR + Handoff Pack → STOP | Re-judge `#2a` selection |
58
+ | `ui_review` | — | invoked as `ui_diff` after `devStatus: ui_ready` | `playwright-cli` screenshots vs MC panels → UI Diff Report with `routeTo: developer/ta/designer` per item; increment `uiReworkRound` on fail (max 5) → STOP | Set `stage: ui_rework` (orchestrator's job); perform gameplay walkthrough |
59
+ | `gameplay_pass` | — | invoked as `load_check` after `devStatus: ready` | Page loads ≤ 10s + no Error-level console logs → set `loadCheck: passed` → STOP | Gameplay walkthrough; judge fun-ness |
60
+ | `ui_review` / `gameplay_pass` | — | result pass | `next_orchestrator_action`: `Set stage=gameplay_pass, invoke @developer` (after `ui_diff` pass) or `Run Gate #3` (after `load_check` pass) | `AskUserQuestion`; modify production files |
61
+ | `ui_review` | — | result fail | `uiReworkRound` +1; `next_orchestrator_action: "Set stage=ui_rework, invoke routed agents per review-report"` → STOP | Write mainline `stage: ui_rework` |
51
62
 
52
63
  ## Orchestrator
53
64
 
54
- | handoff | Expected | Forbidden |
55
- | ------------------------------------------- | -------------------------------------------------------------- | ------------------------------ |
56
- | `gate_pending` + `user_gate` | Gate `AskUserQuestion` only | Invoke sub-agent |
57
- | `subagent_stop` + `orchestrator` | Execute `next_orchestrator_action` | Skip handoff read |
58
- | Before invoke | Reset handoff fields | Leave `subagent_stop: true` |
59
- | `Invoke @reviewer` in action | Also set `stage: review` | Invoke without stage sync |
60
- | `Run Gate #2a` | `gates.#2a = passed`, set `selectedMcOption`, resume @designer | Jump to production without #2b |
61
- | `Invoke @technical-artist` | Wave 1 done invoke TA | Invoke TA before Wave 1 done |
62
- | `Set stage=integration` / invoke @developer | Wave 2 done `stage: integration` | Jump to integration early |
65
+ | handoff | Expected | Forbidden |
66
+ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
67
+ | `gate_pending` non-null + `waiting_for: user_gate` | Run **only** that Gate (`AskUserQuestion`); update `gates.#N = passed` | Invoke sub-agent |
68
+ | `subagent_stop: true` + `waiting_for: orchestrator` | Execute **only** `next_orchestrator_action` | Skip handoff read |
69
+ | Before invoke | Reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target) | Leave `subagent_stop: true` |
70
+ | `Invoke @reviewer ui_diff` in action | Also set `stage: ui_review` | Invoke without stage sync |
71
+ | `Set stage=ui_rework` | Set `stage: ui_rework` + invoke routed agents per `review-report.md` | Let Reviewer write `stage` |
72
+ | `Set stage=gameplay_pass` | After `ui_review` pass (or `uiReworkRound == 5`): set `stage: gameplay_pass` + `@developer` | Skip `gameplay_pass` |
73
+ | `Invoke @reviewer load_check` | After `devStatus: ready`: set Reviewer mode | Skip `load_check` before Gate #3 |
74
+ | `Run Gate #2a` | Set `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` | Jump to `production` without #2b |
75
+ | `Run Gate #2b` | Set `gates.#2b = passed`, set `stage: production`, invoke `@designer` Ph.2 only | Spawn `@technical-artist` before Wave 1 done |
76
+ | `Invoke @technical-artist` | Wave 1 done → invoke TA (Wave 2) | Invoke TA before Wave 1 done |
77
+ | `Set stage=ui_pass, invoke @developer` | Wave 2 `done` + Compliance green → set `stage: ui_pass` → invoke `@developer` | Jump to `ui_pass` before Wave 2 done |
78
+ | `Run Gate #3` | After `load_check: passed`: `AskUserQuestion` with `devUrl` → user accept → `stage: done`, `gates.#3 = passed` | Treat `playcraft build` as required |
79
+
80
+ ## Post-STOP verification (before stage transition)
81
+
82
+ Orchestrator MUST verify each item before advancing `stage` / invoking the next agent. Failure → re-invoke the same agent to fix, do **not** advance.
83
+
84
+ | 验证项 | 方法 | 失败处理 |
85
+ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------- |
86
+ | Atom status updated | `atom-plan.json` → that agent's all atoms `status ≠ pending` | Re-invoke to fill |
87
+ | `actualOutput` files exist | `atoms[].actualOutput` path on disk | Re-invoke |
88
+ | Skill Context filled | `atom-plan.md` corresponding section has no `(Pending …)` | Re-invoke |
89
+ | Skill Preflight done | Designer: `designer-log § Skill Preflight`; TA: `ta-log § Skill Preflight`; Developer: `developer-log § Skill Preflight` | Reject STOP (hook) |
90
+ | Plan section complete (TA / Dev) | `ta-log § Production Plan` or `developer-log § UI Pass Plan` / `Gameplay Pass Plan` Risk Checklist all `[x]` | Reject STOP (hook) |
91
+ | mediaGroups disposition recorded | Designer/TA: each `.aiaudio` / `.aiimage` / `.aisprite` entry → linked or skipped + reason | Re-invoke |
92
+ | `devStatus` consistency | `devStatus: ui_ready` / `ready` requires `devBlockers` empty | Re-invoke developer |
93
+
94
+ See [`agent-conduct.md`](agent-conduct.md) § Orchestrator only for the full MUST/NEVER list.
@@ -93,6 +93,74 @@ Developer 软链:`.claude/skills/<skillRef>/`(`playcraft skills link --from-
93
93
 
94
94
  **Context 回填同样强制**:对应 agent 的 `atom-plan.md` § Context 区不得为空(`Pending`)。Orchestrator 在阶段转换前验证。
95
95
 
96
+ ## `asrSlot` 字段(可选 — VisualAtom 基线绑定)
97
+
98
+ `atoms[].asrSlot` 是 **VisualAtom**(`assignTo: Designer`)专用的可选字段,把"Designer ASR Coverage Matrix 上的网格坐标"机器可读化,TA 据此自动算 crop 像素坐标,省掉人工对照表的步骤。
99
+
100
+ ### Schema
101
+
102
+ ```ts
103
+ type AsrSlot = {
104
+ sheet: "ui" | "element" | "element_2"; // element_2 = overflow ASR board when types > 12
105
+ row: number; // 1-based 行号 (row-major)
106
+ col: number; // 1-based 列号
107
+ };
108
+
109
+ // 字段位置
110
+ atoms[i].asrSlot?: AsrSlot | null
111
+ ```
112
+
113
+ ### 谁写
114
+
115
+ | 谁 | 何时 | 写什么 |
116
+ | ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
117
+ | **PM** | Gate #1(可选) | 已知会出现在 ASR 的 VisualAtom 预填一个建议 slot(Designer 可改);不确定时留空 |
118
+ | **Designer** | Phase 1 完成 ASR 后(必填,所有 ASR-覆盖的 atom) | 与 `designer-log.md § ASR Coverage Matrix § Coverage` 一致;同时 `status: done` + `actualOutput: ASR:<sheet>:R{row}C{col}` |
119
+ | **TA** | 只读 | 用 `asrSlot.sheet/row/col` + `designer-log` § Sheet grid metadata → 算 `playcraft image crop` 像素 |
120
+
121
+ ### TA crop 自动化(参考公式)
122
+
123
+ `designer-log.md § ASR Coverage Matrix § Sheet grid metadata` 给出每张 sheet 的 `cellW × cellH × padding`。
124
+
125
+ ```
126
+ sheetPath = sheet === "ui"
127
+ ? "assets/images/reference/ui_state_sheet_<selectedMcOption>.png"
128
+ : sheet === "element_2"
129
+ ? "assets/images/reference/element_state_sheet_<selectedMcOption>_2.png"
130
+ : "assets/images/reference/element_state_sheet_<selectedMcOption>.png"
131
+
132
+ x = (col - 1) * (cellW + padding) + padding
133
+ y = (row - 1) * (cellH + padding) + padding
134
+ width = cellW
135
+ height = cellH
136
+
137
+ playcraft image crop <sheetPath> --x <x> --y <y> --width <width> --height <height> --output <assetMapping_path>
138
+ ```
139
+
140
+ ### 与 `actualOutput` 的关系
141
+
142
+ `asrSlot` 是**绑定信息**(这个 atom 对应 ASR 哪个格子),`actualOutput` 是**完成证明**(已交付到哪里)。
143
+ 两者并存而非互斥:
144
+
145
+ ```json
146
+ {
147
+ "atomId": "vatom_tile_default",
148
+ "type": "VisualAtom",
149
+ "assignTo": "Designer",
150
+ "asrSlot": { "sheet": "element", "row": 1, "col": 2 },
151
+ "status": "done",
152
+ "actualOutput": "ASR:element_state_sheet_B:R1C2"
153
+ }
154
+ ```
155
+
156
+ TA 之后用 `asrSlot` 提取出 PNG 到 `assets/images/tiles/tile_default.webp`;这一步发生时 TA atom(不同的 atomId)有自己的 `actualOutput`,**不修改** Designer atom 的 `actualOutput`。
157
+
158
+ ### 禁止
159
+
160
+ - 跨 ASR-mediaGroups 混用:`asrSlot` 只描述"本项目 Designer 产出的 ASR",**不**复用 `skillsMatch.mediaGroups`(那是技能库预制资产,不在项目 ASR 上)。
161
+ - ICP 补丁 PNG 的 VisualAtom 不设 `asrSlot`(已脱离 ASR 网格)。`actualOutput` 直接给文件路径。
162
+ - TA atom 不写 `asrSlot`(这是 Designer-owned 字段,TA 通过 `dependsOn` 引用 Designer atom)。
163
+
96
164
  ## mediaGroups 使用规则
97
165
 
98
166
  `skillsMatch.mediaGroups` 包含 `playcraft skills match` 自动发现的可复用预制资产(图片/音频/3D)。
@@ -24,27 +24,28 @@ ScaffoldAtom (skeleton)
24
24
 
25
25
  ## Atom Assignment Rules (5 Agents)
26
26
 
27
- | Atom Type | assignTo | Notes |
28
- | ---------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
29
- | `GameplayAtom` | Developer | PGS rules, state machine |
30
- | `ConfigAtom` | Developer | Level config, difficulty curve |
31
- | `VisualAtom` (baseline) | Designer | **designer-handoff-v2**: baseline = ASR slots in Phase 1; Phase 2 mark `done` with `actualOutput: ASR:...` or ICP supplementary PNG only |
32
- | `VisualAtom` (completions: remaining elements) | TA | Derive full set from samples |
33
- | `VisualAtom` (sprite sheets/animation/VFX) | TA | Technical pipeline |
34
- | `VisualAtom` (3D models/GLB) | TA | 3D pipeline; needs `referenceSource` |
35
- | `AudioAtom` (original generation) | Designer | BGM/SFX generation |
36
- | `AudioAtom` (post-processing) | TA | compress/trim/loop |
37
- | `VFXAtom` | TA | VFX sprite sheets |
38
- | `AnimationAtom` | TA | Animation sprite sheets |
27
+ | Atom Type | assignTo | Notes |
28
+ | ---------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
+ | `GameplayAtom` | Developer | PGS rules, state machine |
30
+ | `ConfigAtom` | Developer | Level config, difficulty curve |
31
+ | `VisualAtom` (baseline) | Designer | **designer-handoff-v2**: baseline = ASR slots in Phase 1; set `atoms[].asrSlot: { sheet, row, col }` (see [atom-plan-format.md § `asrSlot`](atom-plan-format.md#asrslot-字段可选--visualatom-基线绑定)); Phase 2 mark `done` with `actualOutput: ASR:...` or ICP supplementary PNG only |
32
+ | `VisualAtom` (completions: remaining elements) | TA | Derive full set from samples |
33
+ | `VisualAtom` (sprite sheets/animation/VFX) | TA | Technical pipeline |
34
+ | `VisualAtom` (3D models/GLB) | TA | 3D pipeline; needs `referenceSource` |
35
+ | `AudioAtom` (original generation) | Designer | BGM/SFX generation |
36
+ | `AudioAtom` (post-processing) | TA | compress/trim/loop |
37
+ | `VFXAtom` | TA | VFX sprite sheets |
38
+ | `AnimationAtom` | TA | Animation sprite sheets |
39
39
 
40
40
  **Simple rule** (v2): Designer locks **MC + ASR** direction; TA mass-produces from ASR/MC to contract paths. Designer does not batch-export tile/UI PNGs at `assetMapping` in Phase 2.
41
41
 
42
42
  ## Scheduling Metadata (PM injects into `docs/atom-plan.json` → `atoms[]`)
43
43
 
44
- | Field | Meaning | Impact |
45
- | --------------------------- | ----------------------------------- | ------------------------------------------------------------------- |
46
- | `assignTo` | Which agent executes | Required for all atoms |
47
- | `referenceSource` | Reference image source for 3D atoms | `"designer-sample"` → starts immediately; `"ta-completion"` → waits |
48
- | `dependsOn: [atomId]` | Explicit prerequisites | Determines execution order |
49
- | `priority: high/normal/low` | Priority level | Affects TA scheduling |
50
- | `parallelGroup` | Parallel execution group | Same-group atoms start simultaneously |
44
+ | Field | Meaning | Impact |
45
+ | ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
46
+ | `assignTo` | Which agent executes | Required for all atoms |
47
+ | `referenceSource` | Reference image source for 3D atoms | `"designer-sample"` → starts immediately; `"ta-completion"` → waits |
48
+ | `dependsOn: [atomId]` | Explicit prerequisites | Determines execution order |
49
+ | `priority: high/normal/low` | Priority level | Affects TA scheduling |
50
+ | `parallelGroup` | Parallel execution group | Same-group atoms start simultaneously |
51
+ | `asrSlot: { sheet, row, col }` | VisualAtom baseline → ASR grid cell (optional) | TA auto-derives crop pixels from `designer-log § Sheet grid metadata` — eliminates manual lookup |
@@ -133,6 +133,58 @@ Maintenance checklist after editing `packages/cli/project-template`. Run before
133
133
  - [x] `collaboration.md` § STOP sync checklist step 5 (Plan convergence)
134
134
  - [x] Vitest `validate-workflow-stop.test.ts` covers `validatePlan`
135
135
 
136
+ ## Phase L — convergence-v1 doc alignment audit (2026-05)
137
+
138
+ Documents missed during the `production-serial-v1` → `convergence-v1` upgrade (commit `9fdc39a06`). Each item below has a [W#] tag indicating which audit wave applied the fix.
139
+
140
+ > **⚠️ Critical finding** — commit `9fdc39a06` introduced `convergence-v1` but did **not modify any vitest test files**. Result: 23 tests under `packages/cli/test/project-template-workflow.test.ts` + `validate-workflow-stop.test.ts` are pre-existing failures against the new spec. Audit Wave W4 includes the full test suite re-alignment.
141
+
142
+ ### W1 — Doc alignment
143
+
144
+ - [x] `agent-runtime-matrix.md`: rewritten — replaced `integration` / `review` / `rework` with `ui_pass` / `ui_review` / `ui_rework` / `gameplay_pass`; `reworkRound` → `uiReworkRound`; added `devStatus` / `loadCheck` columns; added Post-STOP verification table
145
+ - [x] All five agent L1 files (`pm.md`, `designer.md`, `technical-artist.md`, `developer.md`, `reviewer.md`): added `> **Workflow spec**: convergence-v1` declaration line at top
146
+ - [x] `pm-workflow-detail.md`: `integration` → `ui_pass` (lines 144, 247)
147
+ - [x] `developer-dev-handoff.md`: `stage → review` → `devStatus: ui_ready` / `ready` + handoff `Invoke @reviewer ui_diff/load_check` (line 99)
148
+
149
+ ### W2 — Term alignment (ASR)
150
+
151
+ - [ ] `playcraft-asset-state-sheet` Skill: "ASR State Inventory" → "ASR Coverage Matrix" (designer-log only has Coverage Matrix)
152
+ - [ ] `designer-log.template.md` § ASR Coverage Matrix: add "Sheet grid" metadata (rows × cols + cell width × height + cell padding)
153
+ - [ ] `ta-pipeline-cookbook.md` Step 0a + ASR extraction: aligned references
154
+
155
+ ### W3 — Machine-readable ASR binding
156
+
157
+ - [x] `atom-plan.template.json`: add `atoms[].asrSlot?: { sheet, row, col }` optional field (example VisualAtom row included)
158
+ - [x] `atom-plan-format.md`: document `asrSlot` field semantics + crop formula + ownership table
159
+ - [x] `core-model.md`: VisualAtom baseline → `asrSlot` linkage (assignment rule + scheduling metadata table)
160
+ - [x] `ta-pipeline-cookbook.md` § ASR 提取方法: prepend "优先路径" reading `atom-plan.json` → `atoms[].asrSlot` for batch crop
161
+ - [x] `designer-log.template.md` § Coverage: instruct Designer to mirror Coverage rows into `atom-plan.json asrSlot`
162
+
163
+ ### W4 — Hook hardening + test suite re-alignment
164
+
165
+ - [ ] `validate-workflow-stop.mjs`: add `designer` branch validating `designer-log.md § Skill Preflight`
166
+ - [ ] `validate-workflow-stop.mjs`: `readStage()` regex accepts `stage: ui_pass` (YAML, no backticks)
167
+ - [ ] `packages/cli/test/validate-workflow-stop.test.ts`: add designer + YAML stage test cases; rewrite `Developer Implementation Plan sample` → use `UI Pass Plan` / `Gameplay Pass Plan`
168
+ - [ ] `packages/cli/test/project-template-workflow.test.ts`: rewrite stale describes (originally pre-existing failures from commit `9fdc39a06`):
169
+ - `workflow-docs` (9 tests): replace six-dimension scoring / `rework_round` / `stage: review` assertions with `convergence-v1` equivalents (`uiReworkRound`, `ui_diff`, `load_check`)
170
+ - `production-serial-v1` (6 tests): delete or migrate to `convergence-v1` describe
171
+ - `upstream-intake-four-doc-discipline` (1 test): align with current `developer-phase1-flow.md`
172
+ - `plan-convergence-ta-developer` (6 tests): "Implementation Plan" → "UI Pass Plan" / "Gameplay Pass Plan"
173
+ - hooks README test: same alignment
174
+
175
+ ### W5 — TA Compliance Gate coverage
176
+
177
+ - [x] `ta-log.template.md` § Compliance Gate: add `Text dimensions` row (for `images/txt/*`)
178
+ - [x] `ta-log.template.md` § Compliance Gate: add `Digit Strip dimensions` row (separate from UI)
179
+ - [x] `layout-spec.template.md` Digit Sprite Strip section: recommend `images/txt/digits.webp` path
180
+ - [x] `ta-pipeline-cookbook.md` § Transparency Classification example table: align digit path with `images/txt/` recommendation
181
+
182
+ ### W6 — Interface polish
183
+
184
+ - [x] `designer-deliverable-spec.md` § Phase 2: clarify ICP supplementary PNG trigger condition (only when TA Step 0c confidence=low **and** crop/segment failed)
185
+ - [x] `ta-log.template.md` Style Interpretation: change "Do NOT proceed with any asset type where confidence = low" → atom-granularity ("hold that asset type; other types continue")
186
+ - [x] `designer-log.template.md` + `ta-log.template.md` § mediaGroups Reuse: add `extension` column + filter note (Designer: `.aiaudio` only; TA: `.aiimage` + `.aisprite`)
187
+
136
188
  ## Automated
137
189
 
138
190
  ```bash
@@ -20,6 +20,24 @@
20
20
  "referenceSource": null,
21
21
  "status": "pending",
22
22
  "actualOutput": null
23
+ },
24
+ {
25
+ "atomId": "{{visual_atom_id}}",
26
+ "slot": "{{element_id_from_assetMapping}}",
27
+ "type": "VisualAtom",
28
+ "assignTo": "Designer",
29
+ "dependsOn": [],
30
+ "skillRef": null,
31
+ "priority": "normal",
32
+ "parallelGroup": null,
33
+ "referenceSource": null,
34
+ "asrSlot": {
35
+ "sheet": "element",
36
+ "row": 1,
37
+ "col": 1
38
+ },
39
+ "status": "pending",
40
+ "actualOutput": null
23
41
  }
24
42
  ],
25
43
  "dagRevisions": []