@playcraft/cli 0.0.41 → 0.0.42

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

@@ -22,10 +22,59 @@ triggers: 构建游戏,开始开发,创建项目,选择组件,选择 skill,查
    - `gate_pending` 非 null 且 `waiting_for: user_gate` 时：**只跑 Gate**，不得 invoke 子 Agent
    - `subagent_stop: true` 时：只执行 `next_orchestrator_action`
    - Gate #1 / #2a / #2b：`AskUserQuestion`（子 Agent 更新 handoff 后 STOP）
-   - Gate #3：Reviewer 通过后展示 **devUrl**（用户只点链，不跑 `npm run dev`）
+   - **Gate #1 / #2b 前**：先 invoke `@reviewer design_check`（软性 checklist）
+   - Gate #3：Reviewer `load_check` 通过后展示 **devUrl**（用户只点链；玩法由用户判断）
    - Gate / handoff 细则：`docs/team/collaboration.md` § Gate Protocol、§ Agent Handoff
-6. `devStatus: ready` → `@reviewer`；`devStatus: blocked_upstream` → 按 `devBlockers.routeTo` 调度 TA/Designer → 再 `@developer`
-7. 当前交付终点 = 用户在 Dev URL 验收通过（`done`），**不要求** `playcraft build`
+6. `devStatus: ui_ready` → `@reviewer ui_diff`；`ui_rework` → 按 report 修复 → 再 `@reviewer ui_diff`
+7. `devStatus: ready` → `@reviewer load_check` → Gate #3
+8. `devStatus: blocked_upstream` → 按 `devBlockers.routeTo` 调度 TA/Designer → 再 `@developer`
+9. 当前交付终点 = 用户在 Dev URL 验收通过（`done`），**不要求** `playcraft build`
+
+### ⚠️ Orchestrator 调度原则：传 WHAT 不传 HOW
+
+**Orchestrator 不是全知全能的指挥官。** 不要在调度时给子 Agent 写详细步骤——子 Agent 有完整的 `.claude/agents/<role>.md` + `refs/` + 相关 Skills。
+
+**正确的调度方式：**
+
+```
+@technical-artist
+目标：完成 atom-plan.json 中所有 assignTo: TA 的 atoms。
+注意：atom-plan.json → skillsMatch.mediaGroups 有 3 个预制图片资产可复用，优先 link。
+```
+
+**错误的调度方式（越俎代庖）：**
+
+```
+@technical-artist
+1. 先生成 tile_01.png，用绿幕...
+2. 然后 remove-background --tolerance 25...
+3. 接着 resize 到 128x128...
+```
+
+**原则：**
+
+- Orchestrator 只传递 **目标 + 约束 + 关键提醒**（如 mediaGroups 可用）
+- 子 Agent 自己读 `refs/` + Skills 找到正确方法论
+- Orchestrator 在 sub-agent STOP 后 **验证结果**（atom status 是否更新、Context 是否填写）
+
+### Orchestrator STOP 后验证清单
+
+Sub-agent STOP 返回后，Orchestrator 必须验证：
+
+```bash
+# 检查 atom status 是否全部更新
+cat docs/atom-plan.json | jq '[.atoms[] | select(.assignTo == "<agent>") | select(.status == "pending")] | length'
+# 应该 = 0（所有该 agent 的 atom 都已 done / skipped）
+
+# 检查 Context 是否填写
+grep -c "Pending" docs/atom-plan.md
+# 对应 agent 的 Context 区不应包含 "Pending"
+
+# 检查 actualOutput 文件是否存在
+cat docs/atom-plan.json | jq '.atoms[] | select(.assignTo == "<agent>" and .status == "done") | .actualOutput' | xargs -I {} test -f {}
+```
+
+如果验证失败 → 不转入下一阶段，而是要求该 agent 补全。
 
 ### Single-Agent Mode（降级模式，当 sub-agent 不可用时）
 
@@ -33,7 +82,7 @@ triggers: 构建游戏,开始开发,创建项目,选择组件,选择 skill,查
 
 - 每进入一个新阶段时，先完整读取对应 `.claude/agents/<role>.md` 的所有指令
 - 不可跳过任何阶段的必选产出（特别是 TA 的完整素材生产——UI 图、VFX、精灵图都必须生产）
-- 必须执行 Spec Quick-Check：TA 在 production Wave 2 启动后 30s 内；Developer 在 `integration` 启动后 30s 内
+- 必须执行 Spec Quick-Check：TA 在 production Wave 2 启动后 30s 内；Developer 在 `ui_pass` 启动后 30s 内
 - PM 定稿后运行 `playcraft skills link --from-atom-plan`；Developer 优先读 `.claude/skills/<atomId>/SKILL.md`，仅断链时用 `playcraft skills read`
 
 ---
@@ -238,13 +287,47 @@ Skills 路径真源：`playcraft.config.json` → `agent.skillsDir`（**不要**
 
 ### 各 Agent 的读写职责
 
-| Agent                | 读取                                     | 写入                                                  |
-| -------------------- | ---------------------------------------- | ----------------------------------------------------- |
-| **PM**               | design-brief, layout-spec                | `atom-plan.json`（skillsMatch + atoms[]）             |
-| **Designer**         | `atoms[]` + design-brief                 | `atom-plan.md` § Asset Skill Context                  |
-| **Technical Artist** | `atoms[]` + Asset Context + designer-log | `atom-plan.md` § TA Skill Context；`atoms[].status`   |
-| **Developer**        | `atoms[]` + Context 区 + design-brief    | `atom-plan.md` § Impl Skill Context；`atoms[].status` |
-| **Reviewer**         | JSON + MD（只读）                        | 不写                                                  |
+| Agent                | 读取                                                     | 写入                                                                            |
+| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| **PM**               | design-brief, layout-spec                                | `atom-plan.json`（skillsMatch + atoms[]）                                       |
+| **Designer**         | `atoms[]` + `mediaGroups` + design-brief                 | `atom-plan.md` § Asset Skill Context；`atoms[].status` + `atoms[].actualOutput` |
+| **Technical Artist** | `atoms[]` + `mediaGroups` + Asset Context + designer-log | `atom-plan.md` § TA Skill Context；`atoms[].status` + `atoms[].actualOutput`    |
+| **Developer**        | `atoms[]` + Context 区 + design-brief                    | `atom-plan.md` § Impl Skill Context；`atoms[].status` + `atoms[].actualOutput`  |
+| **Reviewer**         | JSON + MD（只读）                                        | 不写                                                                            |
+
+### ⚠️ Status Update 纪律（所有 Agent 必须遵守）
+
+每个 Agent 完成 atom 后 **立即** 更新 `atom-plan.json`：
+
+```json
+{
+  "atomId": "<id>",
+  "status": "done",
+  "actualOutput": "<deliverable_path>"
+}
+```
+
+- **Designer**: `actualOutput` = 文件路径 或 `"ASR:<sheet>:<region>"` (when covered by ASR)
+- **TA**: `actualOutput` = `"assets/images/<path>.webp"` (final WebP contract path)
+- **Developer**: `actualOutput` = `"game/<path>.ts"` (implementation file)
+
+**atom-plan 不是 PM 的一次性输出文档，而是贯穿全流程的活依赖追踪系统。**
+
+### mediaGroups 使用纪律（Designer + TA 必须遵守）
+
+`skillsMatch.mediaGroups` 包含 PM 通过 `playcraft skills match` 找到的可复用预制资产。
+
+**流程**：
+
+```
+Designer/TA 读 mediaGroups
+  ├─ 匹配当前 atom？
+  │   ├─ 是 → `playcraft skills link --atom <atomId>` → 后处理 → status=done
+  │   └─ 否 / 质量不够 → 记录跳过原因到 dagRevisions → 正常生产流程
+  └─ mediaGroups 为空？→ 正常生产流程
+```
+
+**禁止**：忽略 mediaGroups 中存在匹配的预制资产而从零生成（浪费 token + 引入不一致风险）。
 
 ### 为什么这样设计能避免冲突
 
@@ -297,22 +380,28 @@ Reviewer:
 
 `aiimage` / `aiaudio` Skill 没有 `ref/` 代码文件，只有 `manifest.json` 中的 `generation` 字段（prompt、aspectRatio、duration 等）。Designer 和 TA 读取这些参数作为生成基准，通过 `playcraft image *`、`playcraft tools generate-image` 等 CLI 命令执行，不复制任何文件到项目。
 
-### Production 串行编排（production-serial-v1）
+**Reviewer（convergence-v1）**
+
+- **`design_check`**：Gate #1 / #2b 前 — 文档完整性 checklist（无需浏览器）
+- **`ui_diff`**：读取 **`playwright-cli`** skill — 截图 vs MC 各面板
+- **`load_check`**：读取 **`playwright-cli`** skill — 页面加载 + console 无 Error
+
+### Production 串行编排（convergence-v1）
 
 Gate #2b 通过后 **严格串行**（见 `workflow-changelog.md`）：
 
 ```
-Wave 1 Designer Ph.2 → Wave 2 TA → integration Developer
+Wave 1 Designer Ph.2 → Wave 2 TA → ui_pass Developer → ui_review (Reviewer ui_diff) → gameplay_pass Developer → load_check → Gate #3
 ```
 
-Developer 仅在 `integration` 写入 `game/**`，此时 TA 已交付合同路径上的真实资产。
+Developer 在 **`ui_pass`** 写入 UI shell（无核心玩法）；**`gameplay_pass`** 叠加玩法逻辑。TA 已交付合同路径上的真实资产。
 
 ### 避免重复 Scaffold 的规则
 
 同一个 Skill 不应被多次 Scaffold 到同一目录：
 
 - PM 在 `atom-plan.json` → `atoms[]` 标注 `skillRef`（若有）+ 调度元信息（assignTo/dependsOn/priority/parallelGroup/referenceSource）
-- Developer 在 `integration` 开始时，按 `atoms[]` 中 `assignTo: Developer` 批量 scaffold 一次
+- Developer 在 **`ui_pass`** 开始时，按 `atoms[]` 中 `assignTo: Developer` 批量 scaffold 一次
 - **不要在实现单个 Atom 时反复 scaffold** — 先统一 scaffold 所有依赖，再逐一实现
 
 ---

package/project-template/.claude/skills/playwright-cli/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: playwright-cli
+description: Automate browser interactions, test web pages and work with Playwright tests.
+allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+# --submit presses Enter after filling the element
+playwright-cli fill e5 "user@example.com"  --submit
+playwright-cli drag e2 e8
+# drop files or data onto an element (from outside the page)
+playwright-cli drop e4 --path=./image.png
+playwright-cli drop e4 --data="text/plain=hello world"
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+# get element id, class, or any attribute not visible in the snapshot
+playwright-cli eval "el => el.id" e5
+playwright-cli eval "el => el.getAttribute('data-testid')" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli requests
+playwright-cli request 5
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli run-code --filename=script.js
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start video.webm
+playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
+playwright-cli video-stop
+
+# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
+playwright-cli show --annotate
+
+# generate a Playwright locator for an element from its ref or selector
+playwright-cli generate-locator e5 --raw
+
+# show a persistent highlight overlay for an element, optionally with a custom style
+playwright-cli highlight e5
+playwright-cli highlight e5 --style="outline: 3px dashed red"
+# hide a single element highlight, or all page highlights when no target is given
+playwright-cli highlight e5 --hide
+playwright-cli highlight --hide
+```
+
+## Raw output
+
+The global `--raw` option strips page status, generated code, and snapshot sections from the output, returning only the result value. Use it to pipe command output into other tools. Commands that don't produce output return nothing.
+
+```bash
+playwright-cli --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
+playwright-cli --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
+playwright-cli --raw snapshot > before.yml
+playwright-cli click e5
+playwright-cli --raw snapshot > after.yml
+diff before.yml after.yml
+TOKEN=$(playwright-cli --raw cookie-get session_id)
+playwright-cli --raw localstorage-get theme
+```
+
+For structured output wrapping every reply as JSON, pass --json
+
+```bash
+playwright-cli list --json
+```
+
+## Open parameters
+
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Connect to browser via Playwright Extension
+playwright-cli attach --extension=chrome
+
+# Connect to a running Chrome or Edge by channel name
+playwright-cli attach --cdp=chrome
+playwright-cli attach --cdp=msedge
+
+# Connect to a running browser via CDP endpoint
+playwright-cli attach --cdp=http://localhost:9222
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Detach from an attached browser (leaves the external browser running)
+playwright-cli -s=msedge detach
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command. All the options below can be combined as needed.
+
+```bash
+# default - save to a file with timestamp-based name
+playwright-cli snapshot
+
+# save to file, use when snapshot is a part of the workflow result
+playwright-cli snapshot --filename=after-click.yaml
+
+# snapshot an element instead of the whole page
+playwright-cli snapshot "#main"
+
+# limit snapshot depth for efficiency, take a partial snapshot afterwards
+playwright-cli snapshot --depth=4
+playwright-cli snapshot e34
+
+# include each element's bounding box as [box=x,y,width,height]
+playwright-cli snapshot --boxes
+```
+
+## Targeting elements
+
+By default, use refs from the snapshot to interact with page elements.
+
+```bash
+# get snapshot with refs
+playwright-cli snapshot
+
+# interact using a ref
+playwright-cli click e15
+```
+
+You can also use css selectors or Playwright locators.
+
+```bash
+# css selector
+playwright-cli click "#main > button.submit"
+
+# role locator
+playwright-cli click "getByRole('button', { name: 'Submit' })"
+
+# test id
+playwright-cli click "getByTestId('submit-button')"
+```
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Installation
+
+If global `playwright-cli` command is not available, try a local version via `npx playwright-cli`:
+
+```bash
+npx --no-install playwright-cli --version
+```
+
+When local version is available, use `npx playwright-cli` in all commands. Otherwise, install `playwright-cli` as a global command:
+
+```bash
+npm install -g @playwright/cli@latest
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli requests
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Example: Interactive session
+
+Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
+
+```bash
+playwright-cli open https://example.com
+playwright-cli show --annotate
+```
+
+## Specific tasks
+
+- **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
+- **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+- **Running Playwright code** [references/running-code.md](references/running-code.md)
+- **Browser session management** [references/session-management.md](references/session-management.md)
+- **Spec-driven testing (plan / generate / heal)** [references/spec-driven-testing.md](references/spec-driven-testing.md)
+- **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+- **Test generation** [references/test-generation.md](references/test-generation.md)
+- **Tracing** [references/tracing.md](references/tracing.md)
+- **Video recording** [references/video-recording.md](references/video-recording.md)
+- **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)

package/project-template/.claude/skills/playwright-cli/references/element-attributes.md

@@ -0,0 +1,23 @@
+# Inspecting Element Attributes
+
+When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
+
+## Examples
+
+```bash
+playwright-cli snapshot
+# snapshot shows a button as e7 but doesn't reveal its id or data attributes
+
+# get the element's id
+playwright-cli eval "el => el.id" e7
+
+# get all CSS classes
+playwright-cli eval "el => el.className" e7
+
+# get a specific attribute
+playwright-cli eval "el => el.getAttribute('data-testid')" e7
+playwright-cli eval "el => el.getAttribute('aria-label')" e7
+
+# get a computed style property
+playwright-cli eval "el => getComputedStyle(el).display" e7
+```

package/project-template/.claude/skills/playwright-cli/references/playwright-tests.md

@@ -0,0 +1,39 @@
+# Running Playwright Tests
+
+To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.
+
+```bash
+# Run all tests
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+
+# Run all tests through a custom npm script
+PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
+```
+
+# Debugging Playwright Tests
+
+To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
+
+**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
+
+Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
+
+```bash
+# Run the test
+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
+# ...
+# ... debugging instructions for "tw-abcdef" session ...
+# ...
+
+# Attach to the test
+playwright-cli attach tw-abcdef
+```
+
+Keep the test running in the background while you explore and look for a fix.
+The test is paused at the start, so you should step over or pause at a particular location
+where the problem is most likely to be.
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
+
+After fixing the test, stop the background test run. Rerun to check that test passes.