@playcraft/cli 0.0.41 → 0.0.42

package/project-template/.claude/agents/refs/developer-phase1-flow.md

@@ -1,211 +1,136 @@
-# Developer Integration Flow — Gameplay + Assets (L2)
+# Developer Flow — ui_pass + gameplay_pass (L2)
 
-> **Trigger**: `docs/project-state.md` stage = `integration`. Agent context + STOP rules: [`../developer.md`](../developer.md).
-> **Prerequisites**: Production Pipeline Wave 1 (Designer Ph.2) + Wave 2 (TA) both `done`; TA Compliance green; contract paths have real files on disk.
+> **Trigger**: `docs/project-state.md` stage = `ui_pass`, `ui_rework`, or `gameplay_pass`.
+> Agent context + STOP rules: [`../developer.md`](../developer.md).
 
-> **Before implementation**, read [`developer-impl-cookbook.md`](./developer-impl-cookbook.md) for PGS patterns, `index.html` skeleton, CTA handler, and **atlas binding** (`atlasPath` + `frameId` + WebP + JSON sidecar). Dev ready gate: [`developer-dev-handoff.md`](./developer-dev-handoff.md).
+---
 
-## Step 0: Upstream Intake (mandatory, before Spec Quick-Check)
+# Part A: ui_pass (UI shell only)
 
-> **Purpose:** Know what happened before `integration` — PM contracts, Designer visual lock, TA delivery — so gameplay and UI match intent.
+> **Goal:** Runnable UI matching MC — scene switching, asset binding, simple states. **No core gameplay rules.**
 
-Read each file (Read tool or shell), then fill **`logs/developer-log.md` § Upstream Intake** before any `game/` edit or Spec Quick-Check.
+## Step 0: Upstream Intake (mandatory)
 
-```bash
-cat docs/project-state.md
-cat docs/design-brief.md
-cat docs/layout-spec.md
-cat docs/atom-plan.json docs/atom-plan.md
-cat docs/style-exploration.md
-cat logs/designer-log.md
-cat logs/ta-log.md
-# Spot-check contract paths exist:
-ls assets/images/ assets/audio/ assets/bundles/ assets/models/ 2>/dev/null | head
-```
+Read each file; fill **`logs/developer-log.md` § Upstream Intake** before any `game/` edit.
 
-| Doc                 | You need from it (one line in developer-log)       |
+| Doc                 | You need from it                                   |
 | ------------------- | -------------------------------------------------- |
-| `project-state`     | Pipeline complete, `devBlockers`, dev fields       |
-| `design-brief`      | Gameplay type, flow, first-level success, Near-Win |
+| `project-state`     | Wave 2 done, stage `ui_pass`, dev fields           |
+| `design-brief`      | Experience flow scene names (for navigation only)  |
 | `layout-spec`       | Zones, elementIds, assetMapping, atlasPath/frameId |
-| `atom-plan.json`    | Developer atoms, `skillRef`, `dependsOn`（机器源） |
-| `atom-plan.md`      | Acceptance criteria + Impl/Asset/TA Context        |
-| `style-exploration` | MC + experience flow — input for Step 2 mapping    |
-| `designer-log`      | Palette / motion / ASR coverage notes              |
-| `ta-log`            | Compliance status, atlas params                    |
-
-**MUST NOT** proceed to Step 1 until every row is ticked with a concrete takeaway.
-
----
+| `atom-plan.json`    | Developer atoms, skillRef, dependsOn               |
+| `atom-plan.md`      | Acceptance + Impl Context                          |
+| `style-exploration` | MC panels — primary UI reference                   |
+| `designer-log`      | Palette / motion notes                             |
+| `ta-log`            | Compliance / atlas params                          |
 
-## Step 1: Spec Quick-Check (30s, mandatory)
+## Step 1: Spec Quick-Check (30s)
 
-> Formerly Step 0a.
+- Every referenced `elementId` exists in `assetMapping`
+- Gaps → `spec-gap` in project-state → wait for PM
 
-Before any implementation, validate Layout Spec:
+## Step 2: Experience Flow → Code Mapping
 
-- Every GameplayAtom's referenced `elementId` exists in `assetMapping`
-- Every code-referenced path has a corresponding assetMapping entry
-- If gaps found → write `spec-gap` to `project-state.md`, wait for PM to supplement (≤ 5 min)
+Write to `developer-log.md` — map MC panels to scenes (Hook / Tutorial / EndCard / CTA). See template.
 
-## Step 2: Experience Flow Visual Mapping (mandatory)
+## Step 3: Skill Preflight + Scaffold
 
-> Formerly Step 0c.
+Per `atom-plan.json` Developer `skillRef` entries — read `.claude/skills/<skillRef>/` or CLI fallback; run `playcraft skills scaffold --out ./game` once.
 
-**Read `docs/style-exploration.md` Master Composite + experience flow design before any implementation.**
+Fill **`§ Skill Preflight`** in developer-log.
 
-The Master Composite is five 9:16 panels in one image: **Panel 1 = concept panel** (Main Gameplay — full UI + all element types); **Panels 2–5 = storyboard** (Hook, Onboarding, End Card, CTA). TA extracts from concept panel / ASR state sheets; study each panel for per-stage visual intent.
+## Step 3b: UI Pass Plan (mandatory before `game/` edits)
 
-Write to `logs/developer-log.md` "Experience Flow → Code Mapping":
+Write **`logs/developer-log.md` § UI Pass Plan**:
 
-| Storyboard Frame          | Scene/State      | Code Location             | Visual Intent                                           |
-| ------------------------- | ---------------- | ------------------------- | ------------------------------------------------------- |
-| Hook (0-3s)               | `scene.hook`     | `game/scenes/hook.ts`     | {{from storyboard: contrast, pace, first interaction}}  |
-| Tutorial (3-10s)          | `scene.tutorial` | `game/scenes/tutorial.ts` | {{from storyboard: low pressure, guaranteed success}}   |
-| Gameplay+NearWin (10-25s) | `scene.gameplay` | `game/scenes/gameplay.ts` | {{from storyboard: core mechanic, near-win visual cue}} |
-| EndCard (25-30s)          | `scene.endcard`  | `game/scenes/endcard.ts`  | {{from storyboard: CTA prominence, unresolved emotion}} |
+1. **Architecture** — engine, entry, scene flow
+2. **Scene-Asset Binding Plan** — verify every path with `ls`
+3. **Scene navigation** — how Reviewer reaches each MC panel (URL param or button)
+4. **Risk Checklist** — all `[x]`
 
-**Rules**:
+**Forbidden in ui_pass:** PGS rules, scoring, elimination, win/lose, Near-Win logic.
 
-- Every scene file MUST have a top comment: `// Visual reference: Master Composite (frame: [position])`
-- If storyboard visuals conflict with layout-spec zones → storyboard takes precedence; ask PM in `intent-clarifications.md`
-- Visual Intent captures EMOTION and ATTENTION FLOW, not just mechanics
+Hook validates § UI Pass Plan on STOP.
 
-## Step 3: 读活 DAG + Skill Discovery + 统一 Scaffold（必须先做，只做一次）
+## Step 4: Implement UI shell
 
-> Formerly Step 0b.
+- Bind **real** assets at contract paths (WebP atlas + JSON sidecar)
+- Implement scenes + `index.html` skeleton (see [`developer-impl-cookbook.md`](./developer-impl-cookbook.md))
+- Scene switching only — static/simple interactive states OK
+- Text-as-image per `playcraft-text-rendering` skill
 
-**第一步：读取骨架与已有上下文**
+## Step 5: Dev self-check (ui_pass)
 
 ```bash
-cat docs/design-brief.md    # gameplayType, engine, StyleDirection
-cat docs/atom-plan.json     # atoms[] skillRef + dependsOn
-cat docs/atom-plan.md       # Asset Skill Context + acceptance criteria
+npm run dev
 ```
 
-**第二步：读取 PM 已标注的 skillRef 内容（必须）**
-
-> **Skill 获取优先级**（见 [`atom-plan-format.md`](../../../docs/team/atom-plan-format.md)）：
->
-> 1. **Project Skills**（PM 已执行 `playcraft skills link`）：`.claude/skills/<skillRef>/SKILL.md` + `ref/`
-> 2. **兜底**：软链不存在或断链 → `playcraft skills read <skillRef>`（自动读 `playcraft.config.json` → `skillsDir`）
-> 3. `skillRef` 为空 → 独立 `playcraft skills match` 搜索
-> 4. 完全无匹配 → `playcraft-research` 后自行实现
+- All MC-reachable scenes render with real assets
+- No white screen; layout matches zones
+- Record devUrl in developer-log
 
-对 `atoms[]` 中每个 `assignTo: Developer` 且 `skillRef` 非空的 atom，逐一读取 Recipe：
+## Step 6: ui_pass STOP
 
-```bash
-# 优先：项目内软链（PM 应在 Gate #1 前已 link）
-test -f .claude/skills/memory_match.aigameplay/SKILL.md && echo "linked OK"
+- `devStatus: ui_ready` (not `ready`)
+- handoff: `Invoke @reviewer ui_diff`
+- **Do not** set mainline `stage`
 
-# 读 Recipe（二选一，link 正常时用文件路径即可）
-cat .claude/skills/memory_match.aigameplay/SKILL.md
-
-# 仅当上面 test 失败时兜底：
-playcraft skills read memory_match.aigameplay
-```
+---
 
-**访问 ref/ 文件**（同样优先 Project Skills）：
+# Part B: ui_rework
 
-```bash
-cat .claude/skills/memory_match.aigameplay/ref/pgs-schema.json
+1. Read `logs/review-report.md` UI Diff section
+2. Fix only Action Items with `routeTo: Developer`
+3. Re-run `npm run dev` → `devStatus: ui_ready` → handoff `Invoke @reviewer ui_diff`
 
-# 兜底：playcraft skills read 输出的 skillDir，或 playcraft.config.json 中的 skillsDir
-# cat <skillsDir>/memory_match.aigameplay/ref/pgs-schema.json
-```
+If `routeTo: ta` or `designer` — STOP; orchestrator invokes them first.
 
-不读 SKILL.md 就 scaffold 或实现 = 丢弃 PM 的规则蓝图。Skill Preflight 须记录每个 `skillRef` 用的是 `linked` 还是 `cli-fallback`。
+---
 
-**STOP 门槛**：`logs/developer-log.md` 的 **§ Skill Preflight** 必须已填（每个 `skillRef` 一行 + CLI 输出摘要）。未填则不得编辑 `game/**`，不得将 atom 标为 `done`，handoff 不得写 Ph.1 完成。
+# Part C: gameplay_pass (core gameplay)
 
-**第三步：补充搜索你域内的 Skills**
+> **Prerequisites:** `uiReviewStatus: passed` (or max ui rework rounds). **Do not rewrite UI layout.**
 
-```bash
-# 按引擎 + 玩法类型搜索（可发现 PM 未找到的组件层 Skill）
-playcraft skills match --engine <engine> --intent "<gameplayType>,rules,algorithm" --json
-# 搜索代码组件层
-playcraft skills match --engine <engine> --intent "<layout>,<ui_components>,<state>" --json
-# 列出配置封包
-playcraft skills list --category config --json
-```
+## Step 0: Read UI baseline
 
-**第四步：富集 `## Impl Skill Context`（写入 atom-plan.md）**
+- Confirm `devStatus` was `ui_ready` / UI diff passed
+- Read existing `game/` scenes — extend, do not replace layout
 
-```markdown
-### {{atom_id}} — {{slot_name}}
+## Step 1: Gameplay Pass Plan (mandatory)
 
-- 实现方案：（简述，基于 SKILL.md Recipe）
-- 匹配 Skills：`memory_match.aigameplay` — 提供 PGS 规则 schema + reducer 接口约束
-- ref 文件：ref/pgs-schema.json（规则骨架）、ref/reducer.template.ts（接口模板）
-- Scaffold 路径：game/gameplay/reducer.ts
-- 实现决策：与 Skill 模板的差异点（如网格从 4×4 改为 4×3）
-```
+Write **`logs/developer-log.md` § Gameplay Pass Plan**:
 
-**第五步：统一 Scaffold（一次性执行，不拆分）**
+1. **PGS Strategy** — rules from design-brief + Skill recipe
+2. **First level guarantee** — how tutorial/config ensures win
+3. **State machine** — Hook → Tutorial → Gameplay → EndCard transitions with logic
+4. **Risk Checklist** — all `[x]`
 
-```bash
-playcraft skills scaffold \
-  --engine <engine> \
-  --atoms <skillRef1>,<skillRef2>,<skillRef3> \
-  --out ./game
-```
+Hook validates § Gameplay Pass Plan on STOP.
 
-注：scaffold 对标注了 `merge-json` 的文件（package.json / tsconfig.json）会自动合并而非覆盖。
+## Step 2: Implement GameplayAtom + ConfigAtom
 
-若某 Atom 本地无结果：参阅 `playcraft-research` SKILL → 执行定向网络研究 → 写入 Impl Skill Context → 标注"候选新 Skill" → 基于研究方案实现。
+- Write testCases FIRST
+- Core rules, scoring, Near-Win, CTA handler
+- First level MUST guarantee player success
 
-## Step 4: Validate Prerequisites
+## Step 3: Dev self-check (gameplay_pass)
 
 ```bash
-ls docs/project-state.md docs/design-brief.md docs/layout-spec.md docs/atom-plan.md
-```
-
-Verify: stage is `integration`, Production Pipeline Wave 2 = `done`, you have atoms with `assignTo: Developer`, Layout Spec has element IDs / grid size / zones.
-
-**Use real assets on disk** at Asset Contract paths from `assetMapping` (TA Wave 2 must have completed):
-
-```
-Layout Spec assetMapping:
-  { elementId: "strawberry", visualAsset: "assets/images/tiles/strawberry_atlas.webp", frameId: "strawberry_01" }
-
-Your code:
-  loadAtlas('assets/images/tiles/strawberry_atlas.webp', 'assets/images/tiles/strawberry_atlas.json', 'strawberry_01')
-
-If file missing → devStatus: blocked_upstream, routeTo TA (do not placeholder)
+npm run dev
 ```
 
-## Step 5: Implement GameplayAtom + ConfigAtom
-
-- **GameplayAtom**: entities from `colorPalette.tileColors[].id`, rules from design-brief flow, write testCases FIRST
-- **ConfigAtom**: number of levels, difficulty progression, score targets — **first level MUST guarantee player success**
-
-## Text-as-Image Rendering
-
-**All visible text in the game is image assets — no font files, no CSS text.** Static text is loaded as images from `layout-spec.md` `textAssets` paths. Dynamic numbers use a Digit Sprite Strip with runtime frame-cutting.
+- Gameplay loop works; CTA fires; audio loads
+- Record devUrl
 
-> **Invoke the `playcraft-text-rendering` skill** for the full spec, rendering code templates (Canvas 2D + PlayCanvas), alignment helpers, and per-role responsibilities.
+## Step 4: gameplay_pass STOP
 
-## Step 6: Write index.html Skeleton
+- `devStatus: ready`
+- handoff: `Invoke @reviewer load_check`
+- **Do not** set Gate #3 or `stage: done`
 
-> **Read [`developer-impl-cookbook.md`](./developer-impl-cookbook.md)** for the complete skeleton with multi-platform CTA handler.
-
-Key requirements: viewport meta with `user-scalable=no`, CTA handler with mraid/FbPlayableAd/ExitApi fallbacks, all CSS/JS inline.
-
-## Step 7: Early Dev smoke (recommended)
-
-After scaffold + core scenes exist:
-
-```bash
-cat package.json   # confirm scripts.dev exists
-npm run dev
-```
-
-Fix fatal errors early. Record devUrl in `developer-log.md` when useful.
-
-## Step 8: Integration completion
+---
 
-> **Exit criteria**: see [`../developer.md`](../developer.md) → **Goals** → `integration` row.
+## Shared references
 
-1. All GameplayAtom + ConfigAtom marked `done` in `atom-plan.json` `atoms[]`
-2. `developer-log.md` includes Experience Flow → Code Mapping + **UI/gameplay self-check notes**
-3. Complete [`developer-dev-handoff.md`](./developer-dev-handoff.md) → `devStatus: ready` + devUrl → handoff `Invoke @reviewer` — **do not** set `stage: review` yourself.
+- PGS patterns, CTA, atlas binding: [`developer-impl-cookbook.md`](./developer-impl-cookbook.md)
+- Dev ready gate details: [`developer-dev-handoff.md`](./developer-dev-handoff.md)

package/project-template/.claude/agents/refs/pm-workflow-detail.md

@@ -143,6 +143,8 @@ Design the shared contract between Designer, TA, and Developer:
 
 **Critical**: `assetMapping` paths are **locked after Gate #1**. No agent may unilaterally change paths — this is the Asset Contract: TA fills paths in production Wave 2; Developer binds **real files** in `integration` after TA Compliance green.
 
+**Transparency**: TA auto-derives transparency requirements from `assetMapping` path conventions (`bg/` = opaque, `ui/`/`vfx/`/`txt/` = needs alpha, `tiles/` = needs alpha unless card faces). PM does NOT need to define transparency fields — chroma key selection and background removal are TA's technical domain. See `ta-pipeline-cookbook.md` Step 0e.
+
 ---
 
 ## Atlas grouping at Gate #1
@@ -403,6 +405,10 @@ Scheduling:
 - [ ] Every group with **≥ 2** raster elements names **one** `.webp` + **one** `.json` path in `assetMapping`
 - [ ] Audio entries specify **`.mp3`** paths where applicable
 
+**Transparency (no PM action needed)**:
+
+- [ ] `assetMapping` paths follow directory conventions (`bg/` for backgrounds, `ui/` for overlays, `vfx/` for effects, `txt/` for text images, `tiles/` for game elements) — TA derives transparency requirements from these paths automatically
+
 ---
 
 ## Design North Star

package/project-template/.claude/agents/refs/reviewer-convergence-eval.md

@@ -0,0 +1,130 @@
+# Reviewer: Convergence Evaluation (design_check / ui_diff / load_check)
+
+> **Read before executing any Reviewer mode.** Replaces six-dimension final review in `convergence-v1`.
+> Invoked from `agents/reviewer.md` — orchestrator specifies mode per invoke.
+
+---
+
+## Mode: design_check
+
+Soft checklist only — **do not judge subjective design quality**.
+
+### Gate #1 checklist (PM four docs)
+
+```
+[ ] design-brief exists; Style Direction has Dimension / Modality / Arc
+[ ] layout-spec exists; assetMapping non-empty
+[ ] atom-plan.json exists; skillsMatch non-empty
+[ ] every atom has assignTo + dependsOn
+[ ] no obvious cross-doc contradictions (assetMapping paths align with atoms)
+```
+
+**Fail →** list missing items + `routeTo: pm` (or `designer` if visual doc gap).
+
+### Gate #2b additional checklist
+
+```
+[ ] MC five panels complete (concept + 4 storyboard)
+[ ] MC aspect ratio correct — verify with: playcraft image info <mc-path>
+[ ] ASR dual sheets (UI + element) exist under assets/images/reference/
+[ ] ASR covers main assetMapping element ids
+```
+
+**Pass →** handoff `Run Gate #1` or `Run Gate #2b`. **Fail →** routeTo PM/Designer with specific gaps.
+
+---
+
+## Mode: ui_diff
+
+> **Read `playwright-cli` skill first.** Save all screenshots under `logs/`.
+
+### Procedure
+
+1. Read MC panel paths from `style-exploration.md` / `assets/images/reference/`.
+2. `npm run dev` if devUrl down; read devUrl from `project-state.md`.
+3. For each scene Developer exposed (URL param or UI button):
+
+```bash
+playwright-cli open <devUrl>[?scene=hook|tutorial|endcard|cta]
+playwright-cli resize 390 844
+playwright-cli screenshot --filename=logs/ui-diff-<scene>.png
+```
+
+4. Compare each screenshot vs corresponding MC panel:
+
+| Scene      | MC panel        | Check                                   |
+| ---------- | --------------- | --------------------------------------- |
+| Initial    | Panel 1 Concept | Layout, hierarchy, element completeness |
+| Hook       | Panel 2         | Color mood, hook composition            |
+| Onboarding | Panel 3         | Tutorial UI, low-pressure layout        |
+| EndCard    | Panel 4         | CTA zone, unresolved emotion            |
+| CTA        | Panel 5         | Button prominence, accent color         |
+
+5. `playwright-cli console` — log errors (informational for ui_diff; critical only if UI broken).
+6. `playwright-cli close`.
+
+### UI Diff Report (write to review-report.md)
+
+For each difference:
+
+- Screenshot path + MC reference path
+- Description + severity (`critical` / `major` / `minor`)
+- `routeTo: developer | ta | designer`
+- Fix suggestion
+
+**Pass:** no critical/major diffs (minor logged, do not block).
+**Fail:** `uiReworkRound` +1; handoff orchestrator to `ui_rework`.
+
+### Routing guide
+
+| Issue type                         | routeTo   |
+| ---------------------------------- | --------- |
+| Layout, code binding, scene switch | developer |
+| Wrong asset color/size/style       | ta        |
+| Ambiguous design intent            | designer  |
+
+---
+
+## Mode: load_check
+
+Minimal pre-Gate #3 sanity check — **not gameplay QA**.
+
+### Procedure
+
+1. `npm run dev` if needed; `playwright-cli open <devUrl>`.
+2. Wait for load (≤10s); confirm not white screen.
+3. `playwright-cli console` — fail if any **Error**-level log.
+4. `playwright-cli screenshot --filename=logs/load-check.png`.
+5. `playwright-cli close`.
+
+### Checklist
+
+```
+[ ] Page loads within 10s (not white screen)
+[ ] Console has no Error-level messages
+[ ] game/index.html reachable
+```
+
+**Pass →** `loadCheck: passed`, handoff `Run Gate #3 with devUrl`.
+**Fail →** routeTo Developer with console error summary.
+
+---
+
+## Severity (ui_diff only)
+
+| Severity | Meaning                     | Blocks pass? |
+| -------- | --------------------------- | ------------ |
+| critical | UI broken / missing         | Yes          |
+| major    | Clear visual mismatch vs MC | Yes          |
+| minor    | Polish / slight drift       | No (log)     |
+
+---
+
+## project-state fields (Reviewer writes)
+
+| Field            | Mode         | Values                    |
+| ---------------- | ------------ | ------------------------- |
+| `uiReviewStatus` | ui_diff      | pending / passed / failed |
+| `uiReworkRound`  | ui_diff fail | 0–5                       |
+| `loadCheck`      | load_check   | pending / passed / failed |
+| `loadCheckNotes` | load_check   | console + load summary    |