@playcraft/cli 0.0.40 → 0.0.42

package/project-template/CLAUDE.md

@@ -0,0 +1,280 @@
+# PlayCraft Playable Ads Project
+
+## Mission
+
+> **构建超高品质的可玩广告。** 品质优先，不惜体积与时长。打造让玩家沉浸、让广告主满意的顶级 HTML5 迷你游戏体验。每一个环节都追求极致——从视觉到交互，从音感到节奏，从第一秒的 Hook 到最后一个 CTA。
+
+## What You're Building
+
+A **playable ad** — a self-contained HTML5 mini-game that runs inside an ad slot.
+It hooks the player in 3 seconds, delivers a compressed gameplay experience, then drives to an install CTA.
+
+### Hard Constraints (non-negotiable)
+
+- **First level guarantees player success** — tutorial must be unlosable
+- **Hook decides everything** — first 3 seconds are the lifeline
+
+## Project State
+
+**Always read `docs/project-state.md` first.** Parse **`## Agent handoff`** (YAML) before any orchestration or sub-agent work. It tracks:
+
+- Current stage and active agent(s)
+- Gates (#1, #2a, #2b, #3), `selectedMcOption`, `uiReworkRound`
+- Handoff: `subagent_stop`, `gate_pending`, `next_orchestrator_action`
+- Completed checkpoints (resume from here, not from scratch)
+- File index pointing to all design docs and assets
+- Production Pipeline serial waves (Designer Ph.2 → TA → Developer in `ui_pass` / `gameplay_pass`)
+
+## Stage Model
+
+```
+pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done
+```
+
+| Stage               | Active Agent(s)                       | Completion                                                                |
+| ------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
+| `pm`                | PM                                    | Gate #1 passed (after Reviewer `design_check`)                            |
+| `style_exploration` | Designer Phase 1                      | Gate #2b passed (MC + ASR; after Reviewer `design_check`)                 |
+| `production`        | Designer Ph.2 → **TA** (serial waves) | Production Pipeline Wave 1 + Wave 2 both `done`                           |
+| `ui_pass`           | **Developer** (UI shell only)         | `devStatus: ui_ready` + devUrl; light logic only (no core gameplay rules) |
+| `ui_review`         | Reviewer (`ui_diff`)                  | Browser screenshots vs MC panels pass (or max 5 `ui_rework` rounds)       |
+| `ui_rework`         | Developer (+ TA/Designer on demand)   | Fixes per UI Diff Report → re-enter `ui_review`                           |
+| `gameplay_pass`     | **Developer** (core gameplay)         | `devStatus: ready` + devUrl; Reviewer `load_check` → Gate #3              |
+| `done`              | —                                     | Gate #3 passed (user accepts at devUrl)                                   |
+
+## Agent Team
+
+5 specialized agents, each with full instructions in `.claude/agents/<name>.md` (see **Goals** § Core responsibilities in each file).
+
+| Agent                | Top 3 responsibilities (priority order)                                                          | Invoke when                                        |
+| -------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| **PM**               | 1) Experience + gameplay design 2) Zero-ambiguity contracts 3) Gates + ICP                       | `@pm` — start project, spec gaps                   |
+| **Designer**         | 1) Gate #2 visual+narrative (MC = Developer UI spec) 2) TA-ready handoff 3) Audio + digit strip  | `@designer` — style exploration, audio             |
+| **Technical Artist** | 1) Style-faithful mass production 2) 100% assetMapping 3) Production-grade assets for Developer  | `@technical-artist` — asset pipeline               |
+| **Developer**        | 1) Dev UI matches MC 2) Dev gameplay matches PM 3) Dev preview owner — **final owner of devUrl** | `@developer` — integrate, `npm run dev` self-check |
+| **Reviewer**         | 1) `design_check` before Gates 2) `ui_diff` (screenshots vs MC) 3) `load_check` before Gate #3   | `@reviewer` — design / UI / load convergence       |
+
+### PM is the project owner
+
+PM is accountable for **intent and contracts** (Layout Spec + Atom Plan, degradation decisions). **User-facing Gate dialogue** is handled by the **Orchestrator** (you), not sub-agents — see [agent-conduct.md](docs/team/agent-conduct.md).
+
+### Gates (Orchestrator-Only)
+
+Full protocol: [docs/team/collaboration.md § Gate Protocol](docs/team/collaboration.md#gate-protocol-orchestrator-only).
+
+1. **Gate #1 (Direction)** — PM prepares four docs → **Reviewer `design_check`** → **you** `AskUserQuestion` → user confirms gameplay + style direction
+2. **Gate #2a (MC selection)** — Designer produces MC options → **you** `AskUserQuestion` → set `selectedMcOption` (no Reviewer pre-check)
+3. **Gate #2b (MC + ASR final)** — Designer produces ASR sheets (UI + element) + docs → **Reviewer `design_check`** → **you** `AskUserQuestion` → then `stage: production`
+4. **Gate #3 (Dev delivery)** — Reviewer `load_check` pass → **you** share **devUrl** → user accepts in browser (user never runs `npm run dev`; gameplay judged by user)
+
+**Master Composite** — five 9:16 panels in one image: **Panel 1 = concept panel** (Main Gameplay, all element types); **Panels 2–5 = storyboard** (Hook, Onboarding, End Card, CTA). See collaboration.md § MC five panels.
+
+### Key Mechanisms
+
+**Asset Contract** — Layout Spec `assetMapping` paths are locked after Gate #1:
+
+- **TA** produces files at these exact paths (production Wave 2)
+- **Developer** (`ui_pass`): bind real assets, scene switching, simple states → **`npm run dev`** → `devStatus: ui_ready` + devUrl
+- **Developer** (`gameplay_pass`): add core gameplay on verified UI → `devStatus: ready` + devUrl (see Dev Preview Protocol)
+
+**Spec Quick-Check** — 30s validation per wave:
+
+- **TA** (production Wave 2 start): every assetMapping entry has clear size/format specs
+- **Developer** (`ui_pass` start): every GameplayAtom reference exists in assetMapping
+- Gaps → `spec-gap` in project-state.md → PM auto-supplements within 5 min
+
+**UI Rework Loop** — Max 5 iterations (`uiReworkRound` in project-state):
+
+- Reviewer `ui_diff` routes issues by target agent (`developer` / `ta` / `designer`)
+- Severity: `critical` / `major` (must fix) / `minor` (log only, does not block pass)
+- After 5 rounds → orchestrator decision (proceed to `gameplay_pass` or escalate to user)
+
+**Gameplay delivery** — No AI rework loop. Reviewer `load_check` only (page loads, no console errors). Gameplay quality = **user at Gate #3**.
+
+**Intent Clarification Protocol (ICP)** — Agent-to-agent async Q&A during production:
+
+- Any agent writes questions to `docs/intent-clarifications.md`; target agent answers
+- Non-blocking: asker continues with reasonable assumption, adjusts if needed after answer
+- PM monitors: >3 open questions or single agent receiving >3 questions → intent transmission fault
+- Designer adds Style Intent Notes + Anti-Pattern Notes to `designer-log.md` to reduce TA ambiguity
+- TA runs Style Interpretation Check + Micro-Batch Validation before batch production
+- Developer maps storyboard frames to code scenes in `developer-log.md`
+- **Developer is the final owner of the Dev preview outcome** — if Dev shows missing/wrong assets, Developer routes rework to TA/Designer via ICP (see Dev Preview Protocol)
+
+### Designer vs Technical Artist
+
+Designer = **"生"** (creative generation): **Master Composite** (concept panel + four storyboard panels), **ASR** (UI + element state reference sheets), all audio (BGM + SFX).
+TA = **"产"** (production pipeline): extract from MC/ASR (via `crop` / `segment`), complete full asset set, runtime atlases, 3D, VFX, post-processing.
+
+## User interaction model
+
+Three phases — **do not ask the user to run terminal commands** for preview.
+
+| Phase                  | Who talks to user                         | User does                                                       |
+| ---------------------- | ----------------------------------------- | --------------------------------------------------------------- |
+| **A — Choose**         | **Orchestrator only** (`AskUserQuestion`) | Gate #1, #2a, #2b — no sub-agent user prompts                   |
+| **B — Produce**        | Nobody (ICP is agent-to-agent)            | Nothing                                                         |
+| **C — Deliver in Dev** | **Orchestrator**                          | Gate #3: open **devUrl** you provide; accept or request changes |
+
+## Dev preview protocol
+
+**Dev** = local preview via **`npm run dev`** at project root (implementation is whatever `package.json` → `scripts.dev` defines). **Not** `playcraft start` unless the project script explicitly uses it.
+
+| Role                   | Runs `npm run dev`?                              | Responsibility                                                                                       |
+| ---------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| **Developer**          | **Yes** (throughout `ui_pass` + `gameplay_pass`) | **Final owner of Dev outcome** — UI shell then gameplay at devUrl                                    |
+| **Reviewer**           | **Yes** if needed                                | **`playwright-cli`**: `design_check` (docs), `ui_diff` (screenshots vs MC), `load_check` (no errors) |
+| **You (orchestrator)** | Only if dev server stopped                       | Keep devUrl valid for Gate #3; **user only clicks the link**                                         |
+| **PM / Designer / TA** | No                                               | Fix assets when Developer blocks upstream (see below)                                                |
+| **User**               | **Never**                                        | Gate #3: click devUrl only                                                                           |
+
+### Developer upstream rework
+
+When Developer finds **missing or substandard** Designer/TA output in Dev:
+
+1. Log blockers in `developer-log.md` + `project-state.md` (`devStatus: blocked_upstream`, `devBlockers`).
+2. Write `docs/intent-clarifications.md` with paths, gap vs MC/spec, and acceptance criteria.
+3. Mark affected atoms `blocked` in `atom-plan.md`.
+4. **You** re-invoke `@technical-artist` and/or `@designer` for targeted rework → then `@developer` again.
+5. Developer re-runs `npm run dev` until no open blockers → `devStatus: ui_ready` (after `ui_pass`) or `devStatus: ready` (after `gameplay_pass`) + **devUrl**.
+
+**Never** set `devStatus: ui_ready` or `ready` with placeholders, open `devBlockers`, or silent skips.
+
+### Gate #3 (orchestrator only)
+
+1. Reviewer `load_check: passed` (page loads within 10s, console has no Error-level logs).
+2. Read **devUrl** from `project-state.md`; if dev server down, run `npm run dev` and refresh devUrl (user still only opens the link).
+3. `AskUserQuestion`: show devUrl + accept / request changes (route to PM/Designer/TA/Developer).
+4. User accepts → `stage: done`, `gates.#3 = passed`.
+
+**Current delivery endpoint = user acceptance in Dev.** `playcraft build` is **future**, not required for `done`.
+
+## Orchestration Protocol
+
+When you receive a user request to create a playable ad, determine your execution mode first.
+
+### Multi-Agent Mode (default, preferred)
+
+If sub-agent invocation is available (Claude Code `@agent` syntax), **you are the orchestrator**. Do NOT role-play all agents yourself in one session.
+
+### Orchestrator startup (every turn)
+
+1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML + Gates table.
+2. If `gate_pending` is non-null and `waiting_for: user_gate` → run **only** that Gate (`AskUserQuestion`) — **do not** invoke sub-agents.
+3. If `subagent_stop: true` and `waiting_for: orchestrator` → execute **only** `next_orchestrator_action`.
+4. Confirm `stage` matches last passed gate before advancing.
+5. Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target).
+
+See `docs/team/collaboration.md` § Agent Handoff, § Stage field ownership, § Rework sequence.
+
+### Stage sync on handoff
+
+When executing `next_orchestrator_action`, **also** update mainline `stage` / gates:
+
+| `next_orchestrator_action` contains       | Orchestrator **must** write                                                                        |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `Run Gate #1`                             | After user pass: `gates.#1 = passed`, `stage: style_exploration`                                   |
+| `Invoke @reviewer design_check Gate #1`   | Before Gate #1 — Reviewer soft checklist on four docs                                              |
+| `Run Gate #2a`                            | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` (stage stays `style_exploration`) |
+| `Invoke @reviewer design_check Gate #2b`  | Before Gate #2b — Reviewer soft checklist on MC + ASR                                              |
+| `Run Gate #2b`                            | `gates.#2b = passed`, `stage: production`, invoke `@designer` Ph.2 only                            |
+| `Invoke @technical-artist`                | Production Pipeline Wave 1 `done` → invoke TA (Wave 2)                                             |
+| `Set stage=ui_pass` / invoke `@developer` | Production Pipeline Wave 2 `done` → `stage: ui_pass`                                               |
+| `Invoke @reviewer ui_diff`                | `stage: ui_review`; Developer `devStatus: ui_ready`                                                |
+| `Set stage=ui_rework`                     | `stage: ui_rework` + invoke routed agents per UI Diff Report                                       |
+| `Set stage=gameplay_pass`                 | UI convergence pass → `stage: gameplay_pass` → invoke `@developer`                                 |
+| `Invoke @reviewer load_check`             | `devStatus: ready` → Reviewer load_check before Gate #3                                            |
+| `Run Gate #3`                             | `gates.#3 = pending` → user accept → `stage: done`, `gates.#3 = passed`                            |
+
+**Stage transition table:**
+
+| Current Stage       | Trigger                               | Your Action                                                                                           |
+| ------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| (start)             | User prompt received                  | Invoke `@pm`                                                                                          |
+| `pm`                | PM STOP + `gates.#1 = pending`        | Invoke `@reviewer` `design_check` Gate #1 → pass → Gate #1 → on pass invoke `@designer`               |
+| `style_exploration` | Designer STOP + `gates.#2a = pending` | Gate #2a `AskUserQuestion` → set `selectedMcOption` → resume `@designer`                              |
+| `style_exploration` | Designer STOP + `gates.#2b = pending` | Invoke `@reviewer` `design_check` Gate #2b → pass → Gate #2b → `stage: production` → `@designer` Ph.2 |
+| `production`        | Designer Wave 1 `done`                | Invoke `@technical-artist` (Wave 2)                                                                   |
+| `production`        | TA Wave 2 `done` (Compliance green)   | `stage: ui_pass` → invoke `@developer` (UI shell only)                                                |
+| `ui_pass`           | `devStatus: ui_ready`                 | `stage: ui_review` → invoke `@reviewer` `ui_diff`                                                     |
+| `ui_pass`           | `devStatus: blocked_upstream`         | Re-invoke `@technical-artist` / `@designer` per `devBlockers` → then `@developer`                     |
+| `ui_review`         | Fail + `uiReworkRound` &lt; 5         | `stage: ui_rework` → invoke routed agents → `@developer` → `@reviewer` `ui_diff`                      |
+| `ui_review`         | Pass or 5 rounds reached              | `stage: gameplay_pass` → invoke `@developer` (gameplay)                                               |
+| `gameplay_pass`     | `devStatus: ready`                    | Invoke `@reviewer` `load_check` → Gate #3 devUrl                                                      |
+| `gameplay_pass`     | `load_check` fail                     | Re-invoke `@developer` → `@reviewer` `load_check`                                                     |
+| `done`              | Gate #3 passed                        | Project complete                                                                                      |
+
+**How to invoke sub-agents:**
+
+- Each `@agent-name` corresponds to `.claude/agents/<name>.md`
+- Sub-agents read `project-state.md` + **`## Agent handoff`**; follow each agent's **Runtime** section
+- Sub-agents update handoff + gates and **STOP** — they do **not** `AskUserQuestion` or change mainline `stage`
+- You read handoff between every invoke (startup checklist above)
+- **Only you** run Gate #1 / #2a / #2b / #3 user interactions
+
+**Requires sub-agent invoke** (`@pm`, `@designer`, `@technical-artist`, `@developer`, `@reviewer`). Do not role-play all five roles in one session — use Claude Code or Cursor agent spawn.
+
+### Dispatching Principle (WHAT not HOW)
+
+**你不是全知全能的指挥官。** Sub-agent 有完整的 `.claude/agents/<role>.md` + `refs/` + Skills。
+
+**调度时只传递：**
+
+1. **目标**（atoms to complete, stage entry condition）
+2. **关键约束/提醒**（如 `mediaGroups` 有可用预制资产、`skillRef` 列表）
+3. **上游状态**（which Waves done, which files exist）
+
+**禁止在调度消息中：**
+
+- 编写详细生产步骤（agent 自己读 refs/ + Skills 决定 HOW）
+- 越俎代庖选择 prompt / model / 工具参数
+- 替 agent 做 Skill Preflight 或 Transparency Classification
+
+### Post-STOP Verification (阶段转换前必须)
+
+Sub-agent STOP 后，**先验证再转阶段**：
+
+| 验证项                        | 失败处理          |
+| ----------------------------- | ----------------- |
+| 所有 atoms `status ≠ pending` | 要求补全          |
+| `actualOutput` 文件存在       | 要求补全          |
+| `atom-plan.md` Context 非空   | 要求回填          |
+| Skill Preflight 已完成        | 拒绝 STOP，重新入 |
+| mediaGroups 处置已记录        | 要求补充          |
+
+验证失败 → **不转阶段**，re-invoke 该 agent 补全。详见 `.cursor/rules/playcraft-orchestrator.mdc`。
+
+## Directory Layout
+
+```
+docs/           Design documents (project-state, design-brief, layout-spec, atom-plan, style-exploration)
+assets/         images/{bg,tiles,ui,vfx,storyboard,reference}  audio/{bgm,sfx}  models/  bundles/
+game/           gameplay/  config/  scenes/  index.html
+logs/           designer-log / ta-log / developer-log / review-report
+templates/      Read-only reference templates
+ta-workspace/   TA batch scripts (scripts/) + temp files (logs/, tmp/)
+```
+
+## Golden Rules
+
+Project-level principles (full MUST/NEVER: [docs/team/agent-conduct.md](docs/team/agent-conduct.md)):
+
+1. First level must guarantee player success
+2. Hook decides everything — first 3 seconds
+3. Quality first — do not compromise quality for file size or play time
+4. Style Gate (#2a + #2b) cannot be skipped — no production without confirmed MC + ASR
+5. Layout Spec is the sole three-way alignment mechanism — do not violate
+6. Asset Contract paths are immutable after Gate #1
+7. Production serial: Designer Ph.2 → TA → Developer (`ui_pass` → `gameplay_pass`) — never invoke `@developer` during `production`
+8. UI rework max 5 rounds (`uiReworkRound`) — then orchestrator decision or proceed to `gameplay_pass`
+9. Dev delivery: Developer owns Dev quality; Reviewer `load_check` + user gameplay judgment at Gate #3
+10. No `playcraft build` for `done` — endpoint is `devStatus: ready` + user devUrl acceptance
+
+## Detailed References
+
+| Document                                                                 | Contents                                             |
+| ------------------------------------------------------------------------ | ---------------------------------------------------- |
+| [docs/team/agent-conduct.md](docs/team/agent-conduct.md)                 | MUST/NEVER behavior contract                         |
+| [docs/team/collaboration.md](docs/team/collaboration.md)                 | Gate Protocol, directory tree, R/W matrix, MC panels |
+| [docs/team/core-model.md](docs/team/core-model.md)                       | Remix = DAG(Atom[]) model                            |
+| [docs/team/platform-capabilities.md](docs/team/platform-capabilities.md) | `playcraft` CLI by role                              |

package/project-template/docs/team/agent-conduct.md

@@ -0,0 +1,121 @@
+# Agent Conduct — MUST / NEVER
+
+> Single source for enforceable behavior. When this conflicts with workflow shortcuts, **this wins** (except where an agent Goals § Core responsibilities explicitly overrides for that role).
+>
+> Gate flow detail: [collaboration.md § Gate Protocol](collaboration.md#gate-protocol-orchestrator-only). STOP fields: [§ STOP sync checklist](collaboration.md#stop-sync-checklist).
+
+## Invoke protocol (all sub-agents)
+
+On every invoke, in order:
+
+1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML (routing truth — not Progress Checkpoint alone).
+2. Read **this role's `## Runtime`** in `.claude/agents/<role>.md` → pick **one** branch.
+3. Read `refs/` or SKILL **only when** Runtime or that branch says so — do not read long Workflow first.
+4. On STOP: complete [§ STOP sync checklist](collaboration.md#stop-sync-checklist).
+
+## All roles (including Orchestrator)
+
+|              | Rule                                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Read `docs/project-state.md` before any work; parse `## Agent handoff` YAML; resume from Progress Checkpoint when present |
+| **MUST**     | Update `docs/project-state.md` Progress Checkpoint when finishing a major step                                            |
+| **MUST**     | On STOP: update `## Agent handoff` (`subagent_stop: true`, `next_orchestrator_action` required)                           |
+| **MUST NOT** | Change `layout-spec.md` `assetMapping` paths after Gate #1 without PM + user-approved contract change                     |
+| **MUST NOT** | Treat `playcraft build` as required for `done` — endpoint is **user acceptance at devUrl**                                |
+| **MUST NOT** | Ask the **user** to run `npm run dev` (Gate #3 = open orchestrator-provided link only)                                    |
+
+## Orchestrator only
+
+|              | Rule                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **MUST**     | Be the **only** role that uses `AskUserQuestion` toward the user (Gate #1, #2a, #2b, #3)                                                         |
+| **MUST**     | After any sub-agent STOP, read `## Agent handoff` in `project-state.md` before spawn / resume / Gate                                             |
+| **MUST**     | After any sub-agent STOP, verify: all atoms `status ≠ pending`, `actualOutput` files exist, Context sections filled, Skill Preflight done        |
+| **MUST**     | If `gate_pending` is non-null and `waiting_for: user_gate`, run **only** the matching Gate (`AskUserQuestion`) — **do not** invoke sub-agents    |
+| **MUST**     | If `subagent_stop: true` and `waiting_for: orchestrator`, execute **only** `next_orchestrator_action`                                            |
+| **MUST**     | Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target role)                                        |
+| **MUST**     | Dispatch = WHAT + skill refs + constraints only; do NOT write detailed production steps for sub-agents                                           |
+| **MUST**     | Run Reviewer `design_check` before Gate #1 and Gate #2b — do **not** ask user until Reviewer passes soft checklist                               |
+| **MUST NOT** | Role-play all five agents in one session when sub-agent invoke is available                                                                      |
+| **MUST NOT** | Skip Gate #2a / #2b while gates are `pending`                                                                                                    |
+| **MUST NOT** | Invoke `@technical-artist` before Production Pipeline Wave 1 (Designer Ph.2) is `done`                                                           |
+| **MUST NOT** | Invoke `@developer` or set `stage: ui_pass` before Production Pipeline Wave 2 (TA) is `done`                                                     |
+| **MUST NOT** | Spawn `@developer` during `stage: production` (serial workflow: Designer → TA → Developer ui_pass)                                               |
+| **MUST NOT** | Advance mainline `stage` when a sub-agent could do it — **orchestrator owns** `stage` transitions (see collaboration.md § Stage field ownership) |
+| **MUST NOT** | Advance to next stage if post-STOP verification fails (atom status, actualOutput, Context, Skill Preflight)                                      |
+
+## Sub-agents only (PM, Designer, TA, Developer, Reviewer)
+
+|              | Rule                                                                                                                                                                                                  |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST NOT** | Use `AskUserQuestion` or present Gate choices to the user                                                                                                                                             |
+| **MUST**     | On Gate-ready materials: sync `gates.#N = pending` + handoff (`gate_pending`, `waiting_for: user_gate`) → **STOP**                                                                                    |
+| **MUST**     | Run Spec Quick-Check within 30s: TA when starting production Wave 2; Developer when starting `ui_pass`                                                                                                |
+| **MUST**     | Update `atom-plan.json` → `atoms[].status` + `atoms[].actualOutput` upon completing each assigned atom — never leave `pending` after delivery                                                         |
+| **MUST**     | Fill corresponding `atom-plan.md` § Context section (Asset / TA / Impl Skill Context) — never leave `(Pending)` after delivery                                                                        |
+| **MUST**     | Check `atom-plan.json` → `skillsMatch.mediaGroups` for reusable assets before generating from scratch (Designer/TA)                                                                                   |
+| **MUST**     | Complete Skill Preflight (read relevant platform Skills) before production — TA: `ta-log § Skill Preflight`; Developer: `developer-log § Skill Preflight`; Designer: `designer-log § Skill Preflight` |
+| **MUST NOT** | Continue producing while `subagent_stop: true` and `waiting_for: orchestrator` (resume only when orchestrator clears handoff)                                                                         |
+| **MUST NOT** | Change mainline `stage` (orchestrator only — see collaboration.md § Stage field ownership)                                                                                                            |
+| **MUST NOT** | Skip required logs (`designer-log`, `ta-log`, `developer-log`, `review-report`)                                                                                                                       |
+| **MUST NOT** | Ignore `mediaGroups` matches and generate from scratch when a pre-matched asset exists — link first, skip only with documented reason                                                                 |
+| **MUST**     | Complete [STOP sync checklist](collaboration.md#stop-sync-checklist) on every STOP                                                                                                                    |
+
+### PM (four-doc discipline)
+
+|              | Rule                                                                                                                                                                                                                                                                                           |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Keep **四件套** contract-only: playable decisions in `design-brief` (no hex — palette in `layout-spec`); paths/zones/specs in `layout-spec`; DAG in **`atom-plan.json`**; acceptance one-liners in **`atom-plan.md`**; status/handoff in `project-state` — **key fields only**, no prose dumps |
+| **MUST**     | Before Gate #1: `playcraft skills match --json` → `docs/atom-plan.json` → `skillsMatch`; bind `GameplayAtom`/`ConfigAtom` `skillRef` only from `skillsMatch.items` (or `null` + `dagRevisions` gap); run `playcraft skills validate-atom-plan`                                                 |
+| **MUST NOT** | Paste long research, full prompts, MC/ASR narrative, or generation logs into the four docs — point downstream to `style-exploration.md` / `logs/designer-log.md` instead                                                                                                                       |
+| **MUST NOT** | Put `playcraft-*` in `skillRef`, or use atomIds absent from `skillsMatch.items` without `dagRevisions` — format: [`atom-plan-format.md`](atom-plan-format.md)                                                                                                                                  |
+| **MUST NOT** | Duplicate the same fact across multiple four-doc files — one canonical home per fact (see `collaboration.md` § Four-doc discipline); Gate #1: no Atom List / DAG Order in `atom-plan.md`; no hex in `design-brief`; no Emotion Target in Experience Flow                                       |
+
+### Designer (four-doc discipline)
+
+|              | Rule                                                                                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Put visual narrative, Handoff Pack, ASR tables, and generation notes in **`style-exploration.md`** + **`logs/designer-log.md`** — not in PM's four docs                   |
+| **MUST NOT** | Edit `design-brief.md` or `layout-spec.md` except ICP-driven contract fixes (paths/palette deltas) — do not rewrite gameplay or duplicate PM contracts                    |
+| **MUST**     | When PM needs a contract delta, write **one-line deltas** (e.g. Palette Locked vs layout-spec) in `designer-log.md`; PM patches layout-spec if user/orchestrator approves |
+
+### Technical Artist
+
+|              | Rule                                                                                                                                                                                                                                        |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Before any asset generation in production Wave 2: complete **Upstream Intake** in `logs/ta-log.md` — Read (tool or `cat`) **四件套** + `docs/style-exploration.md` + `logs/designer-log.md`; tick every row; note one-line takeaway per doc |
+| **MUST**     | Execute `refs/ta-pipeline-cookbook.md` **Step 0a → Step 0** in order after intake                                                                                                                                                           |
+| **MUST NOT** | Start bulk generation or write `ta-log` Style Interpretation until Upstream Intake is complete                                                                                                                                              |
+| **MUST NOT** | Mark TA wave `done` without Upstream Intake + Style Interpretation sections filled                                                                                                                                                          |
+| **MUST**     | Before any asset generation: complete **`logs/ta-log.md` § Production Plan** — Coverage Plan covering 100% `assetMapping`, Atlas Assembly Plan matching layout-spec groups, Risk Checklist all `[x]`                                        |
+| **MUST NOT** | Start bulk generation or write deliverables under `assets/` until Production Plan Risk Checklist is fully checked                                                                                                                           |
+| **MUST**     | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (Claude `SubagentStop` + Cursor `subagentStop` — see `.claude/hooks/README.md`)                                                                                                 |
+
+### Developer
+
+|              | Rule                                                                                                                                                                                                                                                     |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Before Spec Quick-Check or any `game/` work in `ui_pass`: complete **Upstream Intake** in `logs/developer-log.md` — Read **四件套** + `docs/style-exploration.md` + `logs/designer-log.md` + `logs/ta-log.md`; tick every row; one-line takeaway per doc |
+| **MUST**     | Execute `refs/developer-phase1-flow.md` **Step 0 → Step 1** in order after intake                                                                                                                                                                        |
+| **MUST NOT** | Start Skill Preflight or edit `game/**` until Upstream Intake is complete                                                                                                                                                                                |
+| **MUST**     | **`ui_pass` scope only**: scene switching, element placement, simple state display — bind real assets at contract paths; **MUST NOT** implement core gameplay rules (scoring, elimination, level logic, win/lose)                                        |
+| **MUST**     | Before `ui_pass` STOP: complete **`logs/developer-log.md` § UI Pass Plan** — Scene-Asset Binding + scene navigation + Risk Checklist all `[x]`                                                                                                           |
+| **MUST**     | Set `devStatus: ui_ready` (not `ready`) after `ui_pass`; handoff `Invoke @reviewer ui_diff`                                                                                                                                                              |
+| **MUST**     | **`gameplay_pass` scope**: add core gameplay on verified UI shell — PGS, first level success, CTA; complete **`logs/developer-log.md` § Gameplay Pass Plan** before gameplay logic                                                                       |
+| **MUST**     | Before any `game/` implementation: for each non-empty `skillRef`, read Recipe + `ref/` from `.claude/skills/<skillRef>/` when link exists; else `playcraft skills read` — log in `developer-log.md` § Skill Preflight                                    |
+| **MUST NOT** | Rewrite UI layout during `gameplay_pass` unless open UI Diff items remain                                                                                                                                                                                |
+| **MUST NOT** | Set `devStatus: ready` while `devBlockers` has open items                                                                                                                                                                                                |
+| **MUST NOT** | Use placeholder assets or silently skip `blocked` atoms                                                                                                                                                                                                  |
+| **MUST**     | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (plan section validated per stage: UI Pass Plan vs Gameplay Pass Plan)                                                                                                                       |
+
+### Reviewer
+
+|              | Rule                                                                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **MUST**     | Operate in one of three modes per orchestrator invoke: **`design_check`** \| **`ui_diff`** \| **`load_check`**                                                                                         |
+| **MUST**     | Read **`playwright-cli`** skill before `ui_diff` or `load_check` browser steps                                                                                                                         |
+| **MUST**     | **`design_check`**: soft checklist only — block obvious defects (missing docs, wrong MC ratio, empty assetMapping); do **not** judge subjective design quality                                         |
+| **MUST**     | **`ui_diff`**: screenshot each MC panel scene via `playwright-cli`; compare layout/color/elements; route issues with `routeTo: developer \| ta \| designer`; increment `uiReworkRound` on fail (max 5) |
+| **MUST**     | **`load_check`**: confirm page loads within 10s, no Error-level console logs; do **not** perform gameplay walkthrough                                                                                  |
+| **MUST NOT** | Modify production files (only `logs/review-report.md` + `project-state` checkpoint)                                                                                                                    |
+| **MUST NOT** | Write mainline `stage` — set handoff `next_orchestrator_action` for orchestrator (`Set stage=ui_rework`, `Run Gate #3`, etc.)                                                                          |

package/project-template/docs/team/agent-runtime-matrix.md

@@ -0,0 +1,62 @@
+# Agent Runtime Matrix
+
+Fake-invoke reference: `(stage, gates snapshot, handoff snapshot) → expected behavior / forbidden behavior`.
+
+See also: [agent-conduct.md](agent-conduct.md), [collaboration.md](collaboration.md) § Agent Handoff, [workflow-consistency-checklist.md](workflow-consistency-checklist.md).
+
+## PM
+
+| stage        | gates            | handoff                           | Expected                         | Forbidden                                      |
+| ------------ | ---------------- | --------------------------------- | -------------------------------- | ---------------------------------------------- |
+| `pm`         | `#1` pending     | `gate_pending: "1"`, `user_gate`  | Orchestrator runs Gate #1 only   | Invoke designer before Gate #1 pass            |
+| `pm`         | `#1` not started | —                                 | Write four docs → pending → STOP | Skip four docs; set `stage: style_exploration` |
+| `production` | `#1` passed      | spec-gap                          | Patch layout/atom ≤5 min → STOP  | Re-open Gate #1                                |
+| any          | —                | `subagent_stop`, pm, orchestrator | Reply already STOPPED            | Rewrite four docs                              |
+
+## Designer
+
+| stage               | gates                                | handoff              | Expected                                                         | Forbidden                                       |
+| ------------------- | ------------------------------------ | -------------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
+| `style_exploration` | `#2a` not passed                     | —                    | Phase 1 Skill Discovery → style-exploration-flow → `#2a` pending | Skip Skill Discovery; MC before art-style-guide |
+| `style_exploration` | `#2a` pending                        | `gate_pending: "2a"` | Orchestrator Gate #2a only                                       | User A/B/C in chat                              |
+| `style_exploration` | `#2a` passed, `selectedMcOption` set | —                    | ASR 双板 + docs → `#2b` pending                                  | Regenerate MC options                           |
+| `style_exploration` | `#2b` pending                        | `gate_pending: "2b"` | Orchestrator Gate #2b                                            | Phase 2 audio                                   |
+| `production`        | `#2b` passed                         | —                    | Ph.2 atoms + audio → track done STOP                             | Set `stage`                                     |
+| `rework`            | —                                    | routeTo Designer     | Fix report paths → STOP                                          | Full style re-exploration                       |
+
+## Technical Artist
+
+| stage         | gates                     | handoff                        | Expected                                                                     | Forbidden                                      |
+| ------------- | ------------------------- | ------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------- |
+| `production`  | `#2b` passed, Wave 1 done | —                              | Spec check → bulk → **webp atlas+json** Compliance → STOP when TA atoms done | Start before Designer Wave 1 done; set `stage` |
+| `integration` | —                         | `blocked_upstream`, routeTo TA | Fix listed paths → STOP                                                      | `npm run dev`                                  |
+| `rework`      | —                         | Action Items TA                | Scoped fixes → STOP                                                          | Redefine MC                                    |
+
+## Developer
+
+| stage         | gates | handoff                 | Expected                                                                              | Forbidden                                         |
+| ------------- | ----- | ----------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `production`  | —     | —                       | **Do not run** — orchestrator invokes Developer only in `integration`                 | Any `game/**` work in `production`                |
+| `integration` | —     | —                       | Spec Quick-Check → Skill Preflight → PGS/scenes → bind assets → `npm run dev` → ready | Skip Spec Quick-Check; `stage: review` self-write |
+| `integration` | —     | ready + invoke reviewer | STOP handoff                                                                          | Skip Reviewer invoke                              |
+| `rework`      | —     | —                       | Fix Developer Action Items → re-integrate                                             | `playcraft build` as done                         |
+
+## Reviewer
+
+| stage    | gates | handoff | Expected                                       | Forbidden             |
+| -------- | ----- | ------- | ---------------------------------------------- | --------------------- |
+| `review` | —     | —       | Dev walkthrough → **六维度 ≥24/30, no vetoes** | Edit production files |
+| `review` | —     | pass    | `reviewerDevCheck: passed`, Gate #3 handoff    | `AskUserQuestion`     |
+| `review` | —     | fail    | `reworkRound` +1, handoff rework               | Write `stage: rework` |
+
+## Orchestrator
+
+| handoff                                     | Expected                                                       | Forbidden                      |
+| ------------------------------------------- | -------------------------------------------------------------- | ------------------------------ |
+| `gate_pending` + `user_gate`                | Gate `AskUserQuestion` only                                    | Invoke sub-agent               |
+| `subagent_stop` + `orchestrator`            | Execute `next_orchestrator_action`                             | Skip handoff read              |
+| Before invoke                               | Reset handoff fields                                           | Leave `subagent_stop: true`    |
+| `Invoke @reviewer` in action                | Also set `stage: review`                                       | Invoke without stage sync      |
+| `Run Gate #2a`                              | `gates.#2a = passed`, set `selectedMcOption`, resume @designer | Jump to production without #2b |
+| `Invoke @technical-artist`                  | Wave 1 done → invoke TA                                        | Invoke TA before Wave 1 done   |
+| `Set stage=integration` / invoke @developer | Wave 2 done → `stage: integration`                             | Jump to integration early      |

package/project-template/docs/team/atom-plan-format.md

@@ -0,0 +1,105 @@
+# Atom Plan 格式（JSON 主 + Markdown 辅）
+
+> Gate #1 起，**机器可读主文件**为 `docs/atom-plan.json`；`docs/atom-plan.md` 仅承载各角色富集的 Context 与 DAG Revisions。
+
+## Skills 包路径（不在 atom-plan 里写死）
+
+**真源**：项目根 `playcraft.config.json` → `agent.skillsDir`（`playcraft create` 时可配置）。
+
+```json
+{
+  "agent": {
+    "dir": ".",
+    "skillsDir": "/path/to/your/skills/skills"
+  }
+}
+```
+
+`playcraft skills match` / `link` / `read` / `validate-atom-plan` 均按该配置（及 `AGENT_SKILLS_PATHS`、默认 `node_modules` 等）解析，**无需**在 `atom-plan.json` 重复填写 `packageSkillsRoot`。若误填了与 config 不一致的路径，校验会给出 warning。
+
+## 文件分工
+
+| 文件                    | 谁写                    | 内容                                                                                                                 |
+| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `docs/atom-plan.json`   | **PM**（Gate #1）       | `skillsMatch`（`playcraft skills match --json` 原文）、`atoms[]`（排期 DAG + `skillRef`）                            |
+| `docs/atom-plan.md`     | PM 骨架 + 各 Agent 富集 | Gate #1：**仅** `## Acceptance Criteria` + 空 Context 占位 + `## DAG Revisions`；**不要** Atom List / DAG Order 镜像 |
+| `playcraft.config.json` | 项目初始化              | `agent.skillsDir` — skills 库磁盘路径                                                                                |
+
+## PM Gate #1 流程
+
+```bash
+# 确认 playcraft.config.json 已配置 agent.skillsDir（或依赖 node_modules/@playcraft/skills）
+
+playcraft skills match --intent "<gameplayType>,<mechanic>,<keywords>" --json \
+  > /tmp/skills-match.json
+# 包一层写入 docs/atom-plan.json（见下方 jq 示例）
+
+playcraft skills validate-atom-plan
+playcraft skills link --from-atom-plan --prune
+```
+
+PM **STOP** 时 hook `validate-atom-plan.mjs` 会再次校验：所有非空 `skillRef` ∈ skills 库，且在 `skillsMatch.items` 中。
+
+### 最小 atom-plan.json 骨架（无需 cp template）
+
+```bash
+jq -n \
+  --argfile sm /tmp/skills-match.json \
+  '{
+    schemaVersion: 1,
+    skillsMatch: $sm,
+    atoms: [],
+    dagRevisions: []
+  }' > docs/atom-plan.json
+```
+
+再编辑 `atoms[]`；`atom-plan.md` 仍可从 `templates/atom-plan.template.md` 复制（Context 区）。
+
+## skillRef 规则
+
+- 仅 **GameplayAtom** / **ConfigAtom** 可有 `skillRef`
+- 必须为 `*.aigameplay` 或 `*.aiconfig`
+- 禁止 `playcraft-*`（平台管线 skill 在 `.claude/skills/playcraft-*`）
+- 禁止编造未出现在 `skillsMatch.items` 的 atomId（除非 `dagRevisions` 记录 `skills-match-gap`）
+
+## 下游如何读
+
+| 角色                     | 读 JSON                  | 读 MD                    | Skills 路径                                      |
+| ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------ |
+| Orchestrator / Developer | `atoms[]`、`skillsMatch` | `## Impl Skill Context`  | `playcraft.config.json` + `.claude/skills/` 软链 |
+| TA                       | `atoms[]`、`mediaGroups` | `## TA Skill Context`    | 同上                                             |
+| Designer                 | `atoms[]`、`mediaGroups` | `## Asset Skill Context` | 同上                                             |
+| Reviewer                 | 两者只读                 | 两者只读                 | —                                                |
+
+Developer 软链：`.claude/skills/<skillRef>/`（`playcraft skills link --from-atom-plan`）。断链时用 `playcraft skills read <skillRef>`（自动读 config，勿手抄 node_modules 路径）。
+
+## Status Update Protocol（所有产出 Agent 必须遵守）
+
+**atom-plan.json 是活的追踪系统，不是一次性规划文档。** 每个 Agent 完成 atom 后立即更新：
+
+```json
+{
+  "atomId": "<id>",
+  "status": "done", // or "skipped" with reason in dagRevisions
+  "actualOutput": "<path>" // the actual deliverable path on disk
+}
+```
+
+| Agent     | 何时更新                        | `actualOutput` 格式                                   |
+| --------- | ------------------------------- | ----------------------------------------------------- |
+| Designer  | Phase 2 每完成一个 atom         | `"assets/audio/bgm.mp3"` 或 `"ASR:ui_sheet:region_3"` |
+| TA        | 每完成一个 atlas/asset          | `"assets/images/ui/ui_atlas.webp"`                    |
+| Developer | 每完成一个 gameplay/config atom | `"game/gameplay/reducer.ts"`                          |
+
+**Context 回填同样强制**：对应 agent 的 `atom-plan.md` § Context 区不得为空（`Pending`）。Orchestrator 在阶段转换前验证。
+
+## mediaGroups 使用规则
+
+`skillsMatch.mediaGroups` 包含 `playcraft skills match` 自动发现的可复用预制资产（图片/音频/3D）。
+
+**协议**：
+
+1. **Designer / TA 必须读** `mediaGroups` 并对每个 entry 判断是否匹配当前 atom
+2. **匹配 → 直接 link**：`playcraft skills link --atom <atomId>` → 后处理（resize/convert/mix）→ `status: done`
+3. **不匹配 → 跳过并记录**：在 `dagRevisions` 记录 skip 原因
+4. **禁止**：mediaGroups 中有匹配项却无视、从零生成