@playcraft/cli 0.0.39 → 0.0.41

package/project-template/.claude/agents/refs/developer-dev-handoff.md

@@ -0,0 +1,109 @@
+# Developer Dev Handoff (L2)
+
+Use during **Phase 2 integration** and before marking `devStatus: ready`.
+
+## Dev command
+
+```bash
+cat package.json   # read scripts.dev (webpack / vite / etc.)
+npm run dev
+```
+
+- **Not** `playcraft start` — Dev is the project's `scripts.dev`.
+- Record the URL from terminal output (e.g. `http://localhost:5173`) in `project-state.md` → `devUrl`.
+- Prefer leaving the server running for Reviewer; if it stops, Reviewer or orchestrator may restart and refresh `devUrl`.
+
+## Dev iteration rhythm
+
+During integration, repeat:
+
+1. Change code / wire assets
+2. `npm run dev` (restart if HMR is insufficient)
+3. Self-check UI + gameplay + runtime (checklists below)
+4. Log in `developer-log.md` → **Dev self-check**
+5. If upstream issue → blockers + ICP + STOP (orchestrator routes TA/Designer)
+
+**Do not** wait until the last minute for a single Dev pass.
+
+## UI checklist (vs MC + layout-spec)
+
+| Check                                              | Source                                  |
+| -------------------------------------------------- | --------------------------------------- |
+| Zones and hierarchy match layout-spec              | `docs/layout-spec.md`                   |
+| Colors / mood match approved style                 | `docs/style-exploration.md`, Gate #2 MC |
+| Element placement matches storyboard Visual Intent | Master Composite frames                 |
+| Text-as-image assets visible, correct aspect       | `assetMapping` paths                    |
+| No broken images / wrong sprites / style drift     | Dev browser                             |
+| Mobile viewport (e.g. 750×1334) acceptable         | Dev browser resize                      |
+
+## Gameplay checklist (vs design-brief + PGS)
+
+| Check                                      | Source                 |
+| ------------------------------------------ | ---------------------- |
+| Hook → Tutorial → Gameplay → End Card flow | `docs/design-brief.md` |
+| Rules, scoring, win/lose match PM contract | design-brief + PGS     |
+| **First level guaranteed success**         | atom-plan / PGS        |
+| Near-Win and difficulty feel as specified  | design-brief           |
+| CTA on End Card                            | runtime test           |
+
+## Runtime checklist
+
+- No white screen or blocking console errors
+- Full playthrough without dead ends
+- BGM/SFX at correct events
+- State machine stable; CTA handler fires (`mraid` / `FbPlayableAd` / `ExitApi` as applicable)
+
+## devUrl recording
+
+In `docs/project-state.md` → **Dev Preview**:
+
+| Field            | When                                                 |
+| ---------------- | ---------------------------------------------------- |
+| `devUrl`         | After `npm run dev` shows listening URL              |
+| `devStatus`      | `pending` → `ready` or `blocked_upstream` / `failed` |
+| `devStartedBy`   | `developer`                                          |
+| `devLastChecked` | ISO timestamp after each meaningful Dev pass         |
+
+Also note devUrl in `docs/developer-log.md` → **Dev self-check**.
+
+## Upstream blocker template
+
+Add to `developer-log.md` → **## Upstream blockers**:
+
+```markdown
+| Path              | Issue   | Expected                           | routeTo | Status |
+| ----------------- | ------- | ---------------------------------- | ------- | ------ |
+| assets/ui/foo.png | missing | 256×256 PNG per layout-spec zone A | TA      | open   |
+```
+
+In `docs/intent-clarifications.md`:
+
+- **Context**: what Dev showed (screenshot description or path)
+- **Gap**: vs MC / contract / design-brief
+- **Acceptance**: exact path, dimensions, style, or audio mood required
+- **routeTo**: TA | Designer | PM
+
+Set `project-state.md`:
+
+- `devStatus: blocked_upstream`
+- `devBlockers`: same rows as log
+
+**STOP** after filing — wait for orchestrator to re-invoke upstream role, then **re-run Dev loop**.
+
+## After rework — re-verify checklist
+
+1. Confirm blocker paths exist on disk (`ls`, `playcraft image info` if needed)
+2. `npm run dev`
+3. Re-run UI + gameplay + runtime checklists for affected areas
+4. Close blocker rows (`status: resolved`) or escalate if still wrong
+5. Only then set `devStatus: ready` and stage → `review`
+
+## Dev ready checklist (`devStatus: ready` — all required)
+
+- [ ] UI checklist pass in Dev
+- [ ] Gameplay checklist pass in Dev
+- [ ] Runtime checklist pass in Dev
+- [ ] No open rows in Upstream blockers / `devBlockers`
+- [ ] `devUrl` recorded and server reachable
+- [ ] `developer-log.md` Dev self-check complete
+- [ ] **Not** required: `playcraft build`, user running terminal commands

package/project-template/.claude/agents/refs/developer-impl-cookbook.md

@@ -0,0 +1,134 @@
+# Developer Implementation Cookbook
+
+> Read before writing index.html (Phase 1 Step 4) and during Phase 2 asset integration. Contains index.html skeleton, CTA handler patterns, and integration binding checklist.
+
+## Atlas binding (Phase 1 + Phase 2)
+
+When `layout-spec` (or atom-plan handoff) defines **`atlasPath` + `frameId`** for an element or tile set, treat it as the source of truth for sprite geometry — **not** ad-hoc single-file crops.
+
+- **Load the atlas image** as **WebP** at the path given by `atlasPath` (or the paired TA-delivered file beside the JSON).
+- **Load the frame map** from the **JSON sidecar** shipped with the atlas (frame rectangles / pivots / names keyed by `frameId`).
+- **Phase 1**: stub or procedural placeholders are acceptable only where the contract is path + id; still wire code to read `atlasPath` / `frameId` so Phase 2 is a file drop-in.
+- **Phase 2**: verify WebP + JSON exist at the contract paths, then bind textures using `frameId` → sub-rect from the sidecar (same pattern in Integration checklist below).
+
+---
+
+## index.html Skeleton (Phase 1)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no"
+    />
+    <title>Playable Ad</title>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+      }
+      canvas {
+        display: block;
+        width: 100%;
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <canvas id="game"></canvas>
+    <script>
+      // Game initialization — asset loading will be added in Phase 2
+      // Gameplay logic from game/gameplay/
+      // Config from game/config/
+
+      // CTA handler (required — multi-platform fallback)
+      function onCTAClick() {
+        if (typeof mraid !== "undefined") {
+          mraid.open("{{store_url}}");
+        } else if (typeof FbPlayableAd !== "undefined") {
+          FbPlayableAd.onCTAClick();
+        } else if (typeof ExitApi !== "undefined") {
+          ExitApi.exit();
+        } else {
+          window.open("{{store_url}}");
+        }
+      }
+    </script>
+  </body>
+</html>
+```
+
+**Phase 2 additions**: add asset loading (inline base64 or relative paths), connect gameplay logic, wire audio triggers, ensure ALL resources are inline (zero external requests).
+
+---
+
+## Phase 2: Asset Integration Binding Checklist
+
+Connect Designer's assets to gameplay code:
+
+| Check                                                                | Source                 |
+| -------------------------------------------------------------------- | ---------------------- |
+| Every `tileColors[].id` has image file at `assetMapping.visualAsset` | layout-spec + `ls`     |
+| Board position = `zones["board"].rect`                               | layout-spec            |
+| Tile size = `assetSpec.tileSize`                                     | layout-spec            |
+| All sfx files exist per `assetMapping`                               | layout-spec + `ls`     |
+| Background at correct path                                           | layout-spec + `ls`     |
+| Sprite sheet atlas bound with JSON frame data                        | atom-plan + TA handoff |
+
+**Binding pattern**:
+
+1. Load images at paths from `assetMapping`; for atlas-backed assets, load **WebP atlas + JSON sidecar** and resolve **`frameId`** from `layout-spec` (see § Atlas binding).
+2. Bind visuals to game entities: element ID → texture (or atlas sub-rect)
+3. Bind audio to gameplay events: match → sfx, level complete → success sfx
+4. Position elements per `zones[].rect` coordinates
+
+---
+
+## Phase 2: Dev iteration (integration complete)
+
+| Requirement                          | How to Verify                                                 |
+| ------------------------------------ | ------------------------------------------------------------- |
+| Entry point: `game/index.html`       | `ls game/index.html`                                          |
+| All asset references: relative paths | Read game code                                                |
+| No Node.js APIs                      | Code review                                                   |
+| No dynamic imports or CDN references | `grep -r "import(" game/`                                     |
+| Zero external requests in Dev        | Browser console + `grep -r "http" game/`                      |
+| UI + gameplay + runtime in Dev       | `npm run dev` + checklists in `refs/developer-dev-handoff.md` |
+| No open upstream blockers            | `developer-log.md` + `project-state.devBlockers`              |
+
+```bash
+npm run dev
+# Record devUrl in project-state.md; leave server running for Reviewer when possible
+```
+
+> **`playcraft build` is not required** for `devStatus: ready` or project `done`. See `refs/developer-dev-handoff.md` for Dev ready checklist.
+
+---
+
+## PGS Implementation Pattern
+
+```
+1. Load reference: playcraft skills match --engine <engine> --intent "<gameplay>" --json
+2. Write PGS JSON:
+   - entities[] — from layout-spec colorPalette.tileColors[].id
+   - rules[] — from design-brief experience flow
+   - algorithm{} — matching/gravity/refill logic
+   - testCases[] — write FIRST, then implement rules
+3. Validate logic passes all testCases
+```
+
+Key constraints (all from layout-spec, NOT invented):
+
+- Grid dimensions = `zones["board"].rect` / `assetSpec.tileSize`
+- Element types = `colorPalette.tileColors[]`
+- Element IDs = `colorPalette.tileColors[].id`

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

@@ -0,0 +1,211 @@
+# Developer Integration Flow — Gameplay + Assets (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.
+
+> **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)
+
+> **Purpose:** Know what happened before `integration` — PM contracts, Designer visual lock, TA delivery — so gameplay and UI match intent.
+
+Read each file (Read tool or shell), then fill **`logs/developer-log.md` § Upstream Intake** before any `game/` edit or Spec Quick-Check.
+
+```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
+```
+
+| Doc                 | You need from it (one line in developer-log)       |
+| ------------------- | -------------------------------------------------- |
+| `project-state`     | Pipeline complete, `devBlockers`, dev fields       |
+| `design-brief`      | Gameplay type, flow, first-level success, Near-Win |
+| `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.
+
+---
+
+## Step 1: Spec Quick-Check (30s, mandatory)
+
+> Formerly Step 0a.
+
+Before any implementation, validate Layout Spec:
+
+- 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)
+
+## Step 2: Experience Flow Visual Mapping (mandatory)
+
+> Formerly Step 0c.
+
+**Read `docs/style-exploration.md` Master Composite + experience flow design before any implementation.**
+
+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.
+
+Write to `logs/developer-log.md` "Experience Flow → Code Mapping":
+
+| 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}} |
+
+**Rules**:
+
+- 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
+
+## Step 3: 读活 DAG + Skill Discovery + 统一 Scaffold（必须先做，只做一次）
+
+> Formerly Step 0b.
+
+**第一步：读取骨架与已有上下文**
+
+```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
+```
+
+**第二步：读取 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` 后自行实现
+
+对 `atoms[]` 中每个 `assignTo: Developer` 且 `skillRef` 非空的 atom，逐一读取 Recipe：
+
+```bash
+# 优先：项目内软链（PM 应在 Gate #1 前已 link）
+test -f .claude/skills/memory_match.aigameplay/SKILL.md && echo "linked OK"
+
+# 读 Recipe（二选一，link 正常时用文件路径即可）
+cat .claude/skills/memory_match.aigameplay/SKILL.md
+
+# 仅当上面 test 失败时兜底：
+playcraft skills read memory_match.aigameplay
+```
+
+**访问 ref/ 文件**（同样优先 Project Skills）：
+
+```bash
+cat .claude/skills/memory_match.aigameplay/ref/pgs-schema.json
+
+# 兜底：playcraft skills read 输出的 skillDir，或 playcraft.config.json 中的 skillsDir
+# cat <skillsDir>/memory_match.aigameplay/ref/pgs-schema.json
+```
+
+不读 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 完成。
+
+**第三步：补充搜索你域内的 Skills**
+
+```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
+```
+
+**第四步：富集 `## Impl Skill Context`（写入 atom-plan.md）**
+
+```markdown
+### {{atom_id}} — {{slot_name}}
+
+- 实现方案：（简述，基于 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）
+```
+
+**第五步：统一 Scaffold（一次性执行，不拆分）**
+
+```bash
+playcraft skills scaffold \
+  --engine <engine> \
+  --atoms <skillRef1>,<skillRef2>,<skillRef3> \
+  --out ./game
+```
+
+注：scaffold 对标注了 `merge-json` 的文件（package.json / tsconfig.json）会自动合并而非覆盖。
+
+若某 Atom 本地无结果：参阅 `playcraft-research` SKILL → 执行定向网络研究 → 写入 Impl Skill Context → 标注"候选新 Skill" → 基于研究方案实现。
+
+## Step 4: Validate Prerequisites
+
+```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)
+```
+
+## 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.
+
+> **Invoke the `playcraft-text-rendering` skill** for the full spec, rendering code templates (Canvas 2D + PlayCanvas), alignment helpers, and per-role responsibilities.
+
+## Step 6: Write index.html Skeleton
+
+> **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.
+
+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.