@playcraft/cli 0.0.40 → 0.0.42

package/project-template/docs/team/collaboration.md

@@ -0,0 +1,297 @@
+# Agent Collaboration Reference
+
+## Glossary
+
+Canonical terms used across `CLAUDE.md`, agent L1 files, and `refs/`. Prefer the **Canonical** column in new edits.
+
+| Canonical                      | Also called                                | Meaning                                                                                                                                                                            |
+| ------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Gate #1 package** (四件套)   | four design docs, PM four docs             | PM deliverables before Gate #1 STOP: `docs/project-state.md` + `docs/design-brief.md` + `docs/layout-spec.md` + **`docs/atom-plan.json`**（主）+ `docs/atom-plan.md`（Context 辅） |
+| **Asset Contract**             | Asset Path Contract, assetMapping contract | Locked `layout-spec.md` `assetMapping` paths (+ atlas groups, `frameId`) after Gate #1 — no unilateral path changes                                                                |
+| **devUrl**                     | Dev URL, preview link                      | Local Dev server URL from `npm run dev`; orchestrator shares at Gate #3; user never runs dev themselves                                                                            |
+| **Designer Phase 1 / Phase 2** | —                                          | Ph.1 = MC + ASR + Handoff Pack; Ph.2 = audio + digit + VisualAtom status (v2)                                                                                                      |
+| **ASR Coverage Matrix**        | —                                          | `designer-log` table: every contract id → ASR slot; Gate #2b mandatory                                                                                                             |
+| **Palette Locked**             | —                                          | MC-sampled hex in `designer-log`; delta vs `layout-spec`                                                                                                                           |
+| **production-serial-v1**       | workflow spec version (superseded)         | See `workflow-changelog.md`; serial production waves within `production` stage                                                                                                     |
+| **convergence-v1**             | workflow spec version (current)            | Three convergence loops: design_check → ui_diff → load_check + Gate #3 user                                                                                                        |
+| **design_check**               | Reviewer mode                              | Soft checklist before Gate #1 / #2b — completeness only, not subjective quality                                                                                                    |
+| **ui_diff**                    | Reviewer mode                              | Browser screenshots vs MC panels; routes ui_rework (max 5 rounds)                                                                                                                  |
+| **load_check**                 | Reviewer mode                              | Page loads + no console errors before Gate #3; no gameplay walkthrough                                                                                                             |
+| **ui_ready**                   | devStatus value                            | UI shell complete; gameplay rules not yet implemented                                                                                                                              |
+| **designer-handoff-v2**        | visual handoff spec                        | MC + ASR + Handoff Pack; bundled in convergence-v1                                                                                                                                 |
+| **Production Pipeline**        | serial waves in `project-state`            | Wave 1 Designer Ph.2 → Wave 2 TA; Developer in `ui_pass`                                                                                                                           |
+| **Developer ui_pass**          | —                                          | UI shell + scene switch + simple states; no core gameplay rules                                                                                                                    |
+| **Developer gameplay_pass**    | —                                          | Core gameplay on verified UI; PGS + first level success                                                                                                                            |
+| **Four-doc discipline**        | 四件套写作纪律                             | PM/Designer: contracts only in four docs; narrative in style-exploration + designer-log; TA/Dev intake: agent-conduct + log templates                                              |
+| **TA Step 0 / 1 / 2**          | (not "Phase")                              | **TA cookbook only**: Step 0 = Skill Discovery; Step 1 = Asset Completion; Step 2 = Technical Pipeline — TA runs all three in one `production` invoke                              |
+| **reworkRound**                | `handoff.rework_round` (legacy)            | Superseded by **`uiReworkRound`** for UI convergence (0–5)                                                                                                                         |
+| **uiReworkRound**              | `handoff.ui_rework_round`                  | Counts **ui_diff failures** (0 → 5 max); at 5 → orchestrator decision                                                                                                              |
+| **ICP**                        | Intent Clarification Protocol              | Async agent Q&A in `docs/intent-clarifications.md`; orchestrator does not interrupt user                                                                                           |
+| **MC**                         | Master Composite                           | Five 9:16 panels in one image: concept panel + Hook / Onboarding / End Card / CTA storyboards                                                                                      |
+| **ASR**                        | Asset State Reference Sheet                | 资产状态参考精灵图板：UI 组件状态板 + 元素状态板；Gate #2a 后产出；供 TA crop 量产（非 runtime atlas）                                                                             |
+
+## Mission vs Goals vs Workflow
+
+| Layer            | Location                           | Purpose                                                                       |
+| ---------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
+| **Team Mission** | `CLAUDE.md` § Mission              | Shared vision — why we build playable ads                                     |
+| **Role Goals**   | `.claude/agents/<role>.md` § Goals | **What this role must achieve**, in priority order (Top 3 + success criteria) |
+| **Workflow**     | Same agent file + `refs/`          | How to execute; exit criteria point back to Goals                             |
+
+When instructions conflict: **Goals § Core responsibilities** wins over workflow shortcuts (e.g. Developer must not set `devStatus: ready` with open upstream blockers). Enforceable MUST/NEVER: [agent-conduct.md](agent-conduct.md).
+
+## Gate Protocol (Orchestrator-Only)
+
+Only the **Orchestrator** (main session) may use `AskUserQuestion` toward the user. Sub-agents prepare materials, update `project-state`, then **STOP**.
+
+| Gate    | Sub-agent deliverable                                            | STOP signal (`project-state`) | Orchestrator action                                                                                                                                 |
+| ------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **#1**  | PM: four design docs ready for review                            | `gates.#1 = pending`          | Invoke `@reviewer design_check` → pass → `AskUserQuestion` → on pass: `gates.#1 = passed`, `stage: style_exploration`, invoke `@designer`           |
+| **#2a** | Designer: MC options A/B[/C] + partial `style-exploration.md`    | `gates.#2a = pending`         | `AskUserQuestion` pick option → set `selectedMcOption` → resume `@designer` (no Reviewer pre-check)                                                 |
+| **#2b** | Designer: ASR 双板 + complete `style-exploration` + designer-log | `gates.#2b = pending`         | Invoke `@reviewer design_check` → pass → `AskUserQuestion` confirm MC+ASR → `gates.#2b = passed`, `stage: production`, invoke `@designer` Ph.2 only |
+| **#3**  | Reviewer `load_check` pass + `devStatus: ready`                  | `gates.#3 = pending`          | Show **devUrl** → user accept → `stage: done` (gameplay judged by user)                                                                             |
+
+Sub-agent pattern: **write artifacts → update `## Agent handoff` + gates → STOP (no user questions).**
+
+## Agent Handoff
+
+Machine-readable runtime block in `docs/project-state.md` (YAML fence under `## Agent handoff`). Sub-agents and orchestrator use it as the **single source** for STOP / resume / next step.
+
+| Field                      | Writer                                  | Meaning                                                                                          |
+| -------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `subagent`                 | Sub-agent on STOP                       | Role that just finished (`pm`, `designer`, `technical-artist`, `developer`, `reviewer`, `none`)  |
+| `subagent_stop`            | Sub-agent on STOP                       | `true` = do not continue work until orchestrator acts                                            |
+| `waiting_for`              | Both                                    | `user_gate` = orchestrator must run Gate; `orchestrator` = wait for invoke; `none` = active work |
+| `gate_pending`             | Sub-agent when gate pending             | `"1"` \| `"2a"` \| `"2b"` \| `"3"` \| `null` — sync with Gates table                             |
+| `next_orchestrator_action` | Sub-agent on STOP (**required**)        | One sentence: the **only** legal next step for orchestrator                                      |
+| `last_completed_by`        | Sub-agent on STOP                       | Same as `subagent` or action label                                                               |
+| `rework_round`             | Reviewer on ui_diff fail / orchestrator | Keep in sync with `uiReworkRound` in Gate resume fields (legacy alias)                           |
+| `block_reason`             | Optional                                | Why pipeline cannot advance                                                                      |
+
+**Orchestrator loop:** read handoff → if `gate_pending` + `user_gate` → Gate only → else if `subagent_stop` → execute `next_orchestrator_action` → reset handoff before invoke.
+
+**Sub-agent loop:** read handoff → if already stopped for this role → refuse duplicate work → else branch per agent `## Runtime` → update handoff → append `--- PLAYCRAFT_STOP ---` footer.
+
+## STOP sync checklist
+
+On every sub-agent STOP, update **in order** (see [agent-conduct.md § Invoke protocol](agent-conduct.md#invoke-protocol-all-sub-agents)):
+
+1. **Gates table** — set `#N = pending` when gate materials ready (if applicable).
+2. **`## Agent handoff`** — all fields; `subagent_stop: true`; `next_orchestrator_action` required.
+3. **Progress Checkpoint** — one row (stage, agent, action, outcome).
+4. **Production Pipeline** — when `stage: production`, set this role's wave row to `done` + notes when wave complete.
+5. **Plan convergence (TA / Developer only)** — before STOP, ensure `logs/ta-log.md` § **Production Plan** or `logs/developer-log.md` § **UI Pass Plan** / **Gameplay Pass Plan** is complete (Risk Checklist all `[x]`, no `{{placeholders}}`). Hook `validate-workflow-stop.mjs` enforces on subagent stop.
+
+Example (update only your row when track complete):
+
+| Wave | Agent            | Status | Notes                                               |
+| ---- | ---------------- | ------ | --------------------------------------------------- |
+| 1    | Designer         | done   | Ph.2: BGM + SFX + digit strip; VisualAtoms ASR-done |
+| 2    | Technical Artist | done   | All TA atoms + Compliance green                     |
+
+Checkpoint is a **human log** for context — **not** the routing source (handoff is).
+
+## Stage field ownership
+
+| Field / transition                                                                                                              | Writer                                    |
+| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `gates.#N = pending`                                                                                                            | Sub-agent before STOP                     |
+| `gates.#N = passed`                                                                                                             | **Orchestrator** after user confirms Gate |
+| Mainline `stage` (`pm` → `style_exploration` → `production` → `ui_pass` → `ui_review` → `ui_rework` → `gameplay_pass` → `done`) | **Orchestrator only**                     |
+| `selectedMcOption`                                                                                                              | Orchestrator after Gate #2a               |
+| `devStatus`, `devUrl`, `devBlockers`                                                                                            | Developer                                 |
+| `uiReviewStatus`, `uiReworkRound`, `loadCheck`                                                                                  | Reviewer                                  |
+
+Sub-agents **MUST NOT** set mainline `stage`. They request orchestrator via `next_orchestrator_action` (e.g. `Invoke @reviewer`).
+
+## UI rework sequence (orchestrator-owned)
+
+1. **Reviewer** (`ui_diff`) — screenshots vs MC panels → fail: UI Diff Report in `review-report.md`, `uiReworkRound` +1, handoff `next_orchestrator_action: "Set stage=ui_rework, invoke routed agents per review-report"` → STOP (**no** `stage: ui_rework` in reviewer write).
+2. **Orchestrator** — Set `stage: ui_rework`, invoke `@developer` / `@technical-artist` / `@designer` per Action Items (`routeTo`).
+3. **Developer** (primary) — Fix UI issues → `devStatus: ui_ready` → handoff `Invoke @reviewer ui_diff` → STOP.
+4. **Orchestrator** — Invoke `@reviewer ui_diff` again; on pass (or `uiReworkRound == 5`) → `stage: gameplay_pass`.
+
+Max **5** UI rework rounds. Gameplay has no AI rework loop — only `load_check` before Gate #3.
+
+## Master Composite — five panels
+
+| Name                  | Panel | `playcraft-storyboard` label                      | Role                                                                     |
+| --------------------- | ----- | ------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Concept panel**     | 1     | Main Gameplay                                     | All key element types + static text + full UI; TA primary extract source |
+| **Storyboard panels** | 2–5   | Hook / Onboarding / End Card / CTA Always Visible | Per-stage visual intent; Developer scene reference                       |
+
+## User interaction model (three phases)
+
+| Phase                | User                                                            | Agents                                                                              |
+| -------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **A — Choose**       | **Orchestrator only** — `AskUserQuestion` for Gate #1, #2a, #2b | Sub-agents STOP when gate materials ready; no mass production until Gate #2b passed |
+| **B — Produce**      | Not interrupted for terminal commands                           | Serial: Designer Ph.2 → TA → Developer (`ui_pass` → `gameplay_pass`)                |
+| **C — Dev delivery** | **Gate #3 only**: open **devUrl** from orchestrator             | Developer UI+gameplay → Reviewer `load_check` → user accepts gameplay in browser    |
+
+**User never runs `npm run dev`.** Delivery endpoint = Dev URL acceptance (`done`), not `playcraft build`.
+
+## Agent responsibility matrix (priority order)
+
+| #        | PM                                                        | Designer                                                          | Technical Artist                                                 | Developer                                                        | Reviewer                                         |
+| -------- | --------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
+| **1**    | Define experience + gameplay (`design-brief`, flow)       | Lock visual + narrative — **MC = UI spec for Developer**          | Style-faithful mass production from MC/ASR                       | **UI shell** (`ui_pass`: layout + scene switch)                  | `design_check` before Gates; `ui_diff` vs MC     |
+| **2**    | Zero-ambiguity contracts (`layout-spec`, `atom-plan`)     | Handoff Pack: ASR Coverage Matrix, Palette Locked, Motion Notes   | 100% `assetMapping` at spec (path check only)                    | **Gameplay** (`gameplay_pass`: PGS, first level success)         | `load_check` before Gate #3                      |
+| **3**    | Gates + ICP; **spec-gap** vs **asset rework** arbitration | Audio + digit strip; **respond to Developer visual/audio rework** | Production-grade assets; **respond on `routeTo: ta` in ui_diff** | **Dev preview owner** (`npm run dev`, devUrl, upstream blockers) | Route UI issues in ui_diff; no gameplay AI audit |
+| **Last** | —                                                         | —                                                                 | —                                                                | `playcraft build` = **future**, not `done`                       | —                                                |
+
+Full detail: `.claude/agents/<role>.md` § Goals.
+
+## Project Directory — What Exists vs What Agents Create
+
+```
+<project-root>/                     ← playcraft create <name> 初始化后
+│
+├── CLAUDE.md                       ✅ 已存在（协作总纲）
+├── .claude/agents/                 ✅ 已存在（5 个 Agent 指令 + refs/ 详细参考）
+│   ├── pm.md                       PM（项目管理）
+│   ├── designer.md                 Designer（设计）
+│   ├── technical-artist.md         Technical Artist（技术美术）
+│   ├── developer.md                Developer（开发）
+│   ├── reviewer.md                 Reviewer（审核）
+│   └── refs/                       L2 按需细则
+├── .claude/skills/                 ✅ 已存在（平台工具 Skill）
+├── .claude/settings.local.json     ✅ 模板（权限白名单，见文件内说明）
+├── .cursor/rules/                  ✅ 编排与边界规则（Cursor 主会话）
+├── .cursor/hooks.json              ✅ Cursor subagentStop → validate-workflow-stop
+├── .claude/settings.json           ✅ Claude Code SubagentStop hooks（可提交）
+├── .claude/hooks/                  ✅ 共享校验脚本（见 README）
+├── docs/team/agent-conduct.md      ✅ 已存在（MUST/NEVER 行为契约）
+├── templates/                      ✅ 已存在（只读，Agent 创建文档时参考）
+├── .gitignore                      ✅ 已存在
+│
+├── ta-workspace/scripts/           ✅ 已存在（TA 写 Node.js 批量脚本，入库）
+├── ta-workspace/logs/              ✅ 已存在（gitkeep，脚本日志不入库）
+├── ta-workspace/tmp/               ✅ 已存在（gitkeep，临时产物不入库）
+│
+├── assets/images/{bg,tiles,ui,vfx,reference}/  ✅ 已存在（gitkeep 占位；reference = ASR 双板）
+├── assets/audio/{bgm,sfx}/           ✅ 已存在（gitkeep 占位）
+├── assets/models/                    ✅ 已存在（gitkeep 占位，3D GLB 资产）
+├── assets/bundles/                   ✅ 已存在（gitkeep 占位）
+│
+│   以下目录/文件在 playcraft create 时为空，由 Agent 运行时填充：
+│
+├── docs/project-state.md           ⏳ PM 创建
+├── docs/design-brief.md            ⏳ PM 创建
+├── docs/layout-spec.md             ⏳ PM 创建
+├── docs/atom-plan.json             ⏳ PM 创建（skillsMatch + atoms[] DAG）
+├── docs/atom-plan.md               ⏳ PM 创建（验收标准 + Context 富集区）
+├── docs/style-exploration.md       ⏳ Designer Phase 1 创建
+│
+├── assets/images/**                ⏳ Designer (样本) + TA (补全)
+├── assets/audio/**                 ⏳ Designer (生成) + TA (后处理)
+├── assets/models/**                ⏳ TA (3D 管线)
+├── assets/bundles/**               ⏳ Designer + TA (atom 封包)
+│
+├── game/gameplay/                  ⏳ Developer Phase 1
+├── game/config/                    ⏳ Developer Phase 1
+├── game/scenes/                    ⏳ Developer Phase 1
+├── game/index.html                 ⏳ Developer Phase 1 + 2
+│
+├── logs/designer-log.md            ⏳ Designer
+├── logs/ta-log.md                  ⏳ Technical Artist
+├── logs/developer-log.md           ⏳ Developer
+└── logs/review-report.md           ⏳ Reviewer
+```
+
+## Directory Conventions
+
+**All agents MUST follow this structure.**
+
+```
+<project-root>/
+├── docs/                  Design documents (PM creates, all agents reference)
+├── assets/
+│   ├── images/{bg,tiles,ui,vfx,reference}   Visual assets (ASR in reference/; samples + TA completions)
+│   ├── audio/{bgm,sfx}       Audio assets (Designer generates, TA post-processes)
+│   ├── models/                3D GLB assets (TA production)
+│   └── bundles/               Atom bundles (Designer + TA create)
+├── game/
+│   ├── gameplay/              PGS + state machine (Developer)
+│   ├── config/                Level configs (Developer)
+│   ├── scenes/                Scene definitions (Developer)
+│   └── index.html             Entry point (Developer)
+├── logs/                  Work logs + review report
+├── ta-workspace/          TA batch scripts + temp files
+└── templates/             Read-only reference templates
+```
+
+## File Read/Write Matrix
+
+| File/Directory              | PM     | Designer                | **TA**                                | Developer               | Reviewer |
+| --------------------------- | ------ | ----------------------- | ------------------------------------- | ----------------------- | -------- |
+| `docs/project-state.md`     | Create | Update stage            | **Update stage**                      | Update stage            | Read     |
+| `docs/design-brief.md`      | Create | Read                    | **Read**                              | Read                    | Read     |
+| `docs/layout-spec.md`       | Create | **Read (contract)**     | **Read (contract)**                   | **Read (contract)**     | Read     |
+| `docs/atom-plan.json`       | Create | Update `atoms[].status` | Update `atoms[].status`               | Update `atoms[].status` | Read     |
+| `docs/atom-plan.md`         | Create | Asset Skill Context     | TA Skill Context                      | Impl Skill Context      | Read     |
+| `docs/style-exploration.md` | —      | Create (Phase 1)        | **Read**                              | Read                    | Read     |
+| `assets/images/`            | —      | **Create (samples)**    | **Create (completions + processing)** | Read                    | Read     |
+| `assets/audio/`             | —      | **Create**              | **Post-process**                      | Read                    | Read     |
+| `assets/models/`            | —      | —                       | **Create (3D pipeline)**              | Read                    | Read     |
+| `assets/bundles/`           | —      | **Create (partial)**    | **Create (TA atoms)**                 | Read                    | Read     |
+| `game/`                     | —      | —                       | —                                     | **Create**              | Read     |
+| `logs/designer-log.md`      | —      | Create+Update           | Read                                  | Read                    | Read     |
+| `logs/ta-log.md`            | —      | —                       | **Create**                            | Read                    | Read     |
+| `logs/developer-log.md`     | —      | —                       | —                                     | Create+Update           | Read     |
+| `logs/review-report.md`     | —      | —                       | —                                     | —                       | Create   |
+
+**Key**: Designer and TA both write `assets/`, but responsibilities don't overlap:
+
+- Designer: MC + ASR (Phase 1), audio + digit strip + atom status (Phase 2)
+- TA writes completion assets and technically processed production-grade files
+
+## Asset Contract (Asset Path Contract)
+
+`layout-spec.md` defines **element ID → atlas+frame or file path**, **locked after Gate #1**:
+
+- **PM** defines `assetMapping`, **atlas grouping table**, and specs (default: **WebP** images, **MP3** audio)
+- **≥2 elements same class** (tiles / ui / vfx) → one **`.webp` + `.json`** atlas per group; each element has `frameId`
+- **Exceptions**: full-screen bg (single webp), digit strip (single webp), MC/ASR reference (non-runtime)
+- **Designer** delivers MP3 audio + digit strip webp at contracted paths
+- **TA** delivers runtime atlases + post-processed MP3 per [ta-atlas-deliverable-standard.md](../../.claude/agents/refs/ta-atlas-deliverable-standard.md)
+- **Developer** (`ui_pass` / `gameplay_pass`) binds `loadImage`/atlas+frame at contract paths with **real files** on disk, then integrates in Dev
+- **Path / frame mismatch = integration failure** — TA Compliance + Reviewer check
+- **No unilateral path changes** — PM + user-approved contract change only
+
+## Four-doc discipline
+
+PM and Designer **own different layers**; TA and Developer **read all layers** at wave start (Upstream Intake).
+
+| Layer                  | Files                                                                                                                                   | Writer                                         | Content rule                                                                                                                       |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| **Contracts (四件套)** | `project-state`, `design-brief`, `layout-spec`, `atom-plan`（**`atom-plan.json`** 机器契约 + **`atom-plan.md`** Gate #1 仅 Acceptance） | PM (Designer: read-only except ICP path fixes) | **Key fields only** — decisions, paths, DAG (`atoms[]`), status. No hex in brief; no Atom List mirror; no prompts or MC/ASR prose. |
+| **Visual narrative**   | `style-exploration`, `logs/designer-log`                                                                                                | Designer                                       | MC/ASR intent, Handoff Pack, Coverage Matrix, Style Intent Notes                                                                   |
+| **Production proof**   | `logs/ta-log`, `logs/developer-log`                                                                                                     | TA / Developer                                 | Upstream Intake table (mandatory), then pipeline / implementation logs                                                             |
+
+Enforceable rules: [agent-conduct.md](agent-conduct.md) (§ PM / Designer / TA / Developer). L2: `ta-pipeline-cookbook.md` Step 0a, `developer-phase1-flow.md` Step 0.
+
+## Spec Quick-Check
+
+Within 30 seconds of each wave start, the active agent validates Layout Spec:
+
+| Checker   | When                                                       | Checks                                               | On Gap                                                            |
+| --------- | ---------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| TA        | Production Pipeline Wave 2 (TA entry)                      | Every assetMapping entry has clear size/format specs | Write `spec-gap` to project-state.md, PM supplements within 5 min |
+| Developer | `ui_pass` / `gameplay_pass` start (after TA Wave 2 `done`) | Every GameplayAtom reference exists in assetMapping  | Same                                                              |
+
+## DAG Modification Protocol
+
+- **Default**: Follow PM's plan
+- **Allowed**: Add/remove/modify atoms — update `atom-plan.json` `atoms[]` + record in `atom-plan.md` § DAG Revisions
+- **Stop for direction changes**: Switching gameplay/style → report back
+- **Reviewer audits**: Every revision evaluated for reasonableness
+
+## Upstream rework routing (Dev blockers)
+
+| `routeTo`    | Trigger                                                              | Orchestrator action                               |
+| ------------ | -------------------------------------------------------------------- | ------------------------------------------------- |
+| **TA**       | Missing file, wrong size/format, style drift in mass-produced assets | Re-invoke `@technical-artist` → then `@developer` |
+| **Designer** | Wrong/missing sample, audio mood, supplementary art                  | Re-invoke `@designer` → then `@developer`         |
+| **PM**       | Contract ambiguity, gameplay vs spec conflict                        | `@pm` arbitrates ICP → then `@developer`          |
+
+Developer sets `devStatus: blocked_upstream` and **STOPs** until rework completes.

package/project-template/docs/team/core-model.md

@@ -0,0 +1,50 @@
+# Core Model — Remix = DAG(Atom[])
+
+## Atom DAG Structure
+
+```
+ScaffoldAtom (skeleton)
+  ├── VisualAtom[] (baseline)   → Designer (Phase 1 ASR; v2)
+  ├── VisualAtom[] (completions)→ Technical Artist
+  ├── VisualAtom[] (sprites/3D) → Technical Artist
+  ├── AudioAtom[] (generation)  → Designer
+  ├── AudioAtom[] (processing)  → Technical Artist
+  ├── VFXAtom[] / AnimationAtom[]→ Technical Artist
+  ├── ConfigAtom[]              → Developer
+  └── GameplayAtom              → Developer
+```
+
+## Atom Three Elements
+
+| Element     | Meaning                                      |
+| ----------- | -------------------------------------------- |
+| **Recipe**  | How it was made (prompt, model, seed)        |
+| **Result**  | What it is (image/audio/JSON file)           |
+| **Binding** | How it's used (where in the DAG it connects) |
+
+## Atom Assignment Rules (5 Agents)
+
+| Atom Type                                      | assignTo  | Notes                                                                                                                                    |
+| ---------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `GameplayAtom`                                 | Developer | PGS rules, state machine                                                                                                                 |
+| `ConfigAtom`                                   | Developer | Level config, difficulty curve                                                                                                           |
+| `VisualAtom` (baseline)                        | Designer  | **designer-handoff-v2**: baseline = ASR slots in Phase 1; Phase 2 mark `done` with `actualOutput: ASR:...` or ICP supplementary PNG only |
+| `VisualAtom` (completions: remaining elements) | TA        | Derive full set from samples                                                                                                             |
+| `VisualAtom` (sprite sheets/animation/VFX)     | TA        | Technical pipeline                                                                                                                       |
+| `VisualAtom` (3D models/GLB)                   | TA        | 3D pipeline; needs `referenceSource`                                                                                                     |
+| `AudioAtom` (original generation)              | Designer  | BGM/SFX generation                                                                                                                       |
+| `AudioAtom` (post-processing)                  | TA        | compress/trim/loop                                                                                                                       |
+| `VFXAtom`                                      | TA        | VFX sprite sheets                                                                                                                        |
+| `AnimationAtom`                                | TA        | Animation sprite sheets                                                                                                                  |
+
+**Simple rule** (v2): Designer locks **MC + ASR** direction; TA mass-produces from ASR/MC to contract paths. Designer does not batch-export tile/UI PNGs at `assetMapping` in Phase 2.
+
+## Scheduling Metadata (PM injects into `docs/atom-plan.json` → `atoms[]`)
+
+| Field                       | Meaning                             | Impact                                                              |
+| --------------------------- | ----------------------------------- | ------------------------------------------------------------------- |
+| `assignTo`                  | Which agent executes                | Required for all atoms                                              |
+| `referenceSource`           | Reference image source for 3D atoms | `"designer-sample"` → starts immediately; `"ta-completion"` → waits |
+| `dependsOn: [atomId]`       | Explicit prerequisites              | Determines execution order                                          |
+| `priority: high/normal/low` | Priority level                      | Affects TA scheduling                                               |
+| `parallelGroup`             | Parallel execution group            | Same-group atoms start simultaneously                               |

package/project-template/docs/team/platform-capabilities.md

@@ -0,0 +1,15 @@
+# Platform Capabilities
+
+| Category            | Command Prefix                                                  | Used By                                              |
+| ------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
+| AI Image Generation | `playcraft tools generate-image`                                | Designer / TA                                        |
+| AI 3D Generation    | `playcraft tools generate-3d`                                   | **TA**                                               |
+| 3D Pipeline         | `playcraft 3d *`                                                | **TA**                                               |
+| Sprite Sheets       | `playcraft image sprite-sheet/sprite-split/animate/use-vfx`     | **TA**                                               |
+| Image Processing    | `playcraft image resize/crop/convert/remove-background/overlay` | **TA**                                               |
+| Audio Generation    | `playcraft tools generate-sfx/generate-bgm`                     | Designer                                             |
+| Audio Processing    | `playcraft audio compress/trim/loop/...`                        | **TA**                                               |
+| Skills Discovery    | `playcraft skills list/match`                                   | All agents                                           |
+| Asset Info          | `playcraft image info` / `playcraft audio info`                 | TA / Reviewer                                        |
+| Dev preview         | `npm run dev` (project `scripts.dev`)                           | Developer / Reviewer / orchestrator (refresh devUrl) |
+| Build (future)      | `playcraft build` / `build-all`                                 | Not required for current `done` gate                 |

package/project-template/docs/team/workflow-changelog.md

@@ -0,0 +1,65 @@
+# Workflow Changelog
+
+Template workflow spec versions for `packages/cli/project-template`. New projects from `playcraft create` copy the current template; record the version in each project's `docs/project-state.md` § Workflow spec.
+
+## convergence-v1 (current)
+
+**Effective**: project-template default for new playable-ad projects.
+
+### Summary
+
+- **Three convergence loops**: (1) Reviewer `design_check` before Gate #1 / #2b; (2) `ui_pass` → `ui_review` ⇄ `ui_rework` (max 5 rounds) with `ui_diff` (browser screenshots vs MC); (3) `gameplay_pass` → Reviewer `load_check` → Gate #3 user gameplay acceptance.
+- **Developer split**: `ui_pass` (UI shell + light logic, `devStatus: ui_ready`) then `gameplay_pass` (core gameplay, `devStatus: ready`).
+- **Removed**: `integration`, `review`, `rework`, six-dimension final review, AI gameplay walkthrough.
+- **Production orchestration** unchanged: after Gate #2b, **strict serial** — Designer Ph.2 → TA → Developer (`ui_pass`).
+- Visual delivery unchanged from **designer-handoff-v2** (MC + ASR, Handoff Pack, Phase 2 audio/digit only).
+- **Reviewer tooling**: `playwright-cli` skill for browser automation (screenshot, console, resize).
+
+### Stage chain
+
+```
+pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done
+```
+
+### Production waves (serial)
+
+| Wave | Agent            | Stage        | Orchestrator invoke                                 |
+| ---- | ---------------- | ------------ | --------------------------------------------------- |
+| 1    | Designer         | `production` | `@designer` Ph.2 only after Gate #2b                |
+| 2    | Technical Artist | `production` | `@technical-artist` after Wave 1 `done`             |
+| 3    | Developer        | `ui_pass`    | `@developer` after Wave 2 `done` + Compliance green |
+
+### Trade-offs
+
+| Benefit                                                      | Cost                                              |
+| ------------------------------------------------------------ | ------------------------------------------------- |
+| UI convergence independently verifiable before gameplay      | Extra Reviewer round + up to 5 UI rework cycles   |
+| Design defects caught before user Gates                      | Gate #1/#2b require extra Reviewer invoke         |
+| Gameplay quality left to human (Canvas opaque to automation) | No AI gameplay audit — user must judge at Gate #3 |
+
+---
+
+## production-serial-v1
+
+**Superseded by** `convergence-v1` for orchestration; serial production waves below still apply within `production` stage.
+
+---
+
+## designer-handoff-v2
+
+**Superseded by** `production-serial-v1` for orchestration; visual rules below still apply.
+
+### Summary
+
+- Visual baseline locked in **Phase 1**: Master Composite (MC) + **ASR** dual sheets (UI + element state reference).
+- **Phase 2 Designer**: BGM, SFX, digit strip only; `assignTo: Designer` VisualAtoms marked `done` when covered by ASR (not separate `tile_sample_*.png` batch).
+- **Gate #2b Handoff Pack**: ASR Coverage Matrix, Palette Locked, Motion Notes in `designer-log` / `style-exploration`.
+- Retired paths: `exploded_view_*.png`, `concept_selected.png`, per-frame `concept_*.png` / `hook_*.png` deliverable tables.
+
+---
+
+## designer-handoff-v1 (legacy)
+
+- Single **Exploded View** (or scattered concept/storyboard PNGs) as TA extract source.
+- Phase 2 sometimes assumed Designer outputs `tile_sample_*.png` at `assetMapping` paths.
+- `playcraft-exploded-view` skill id (removed in v2).

package/project-template/docs/team/workflow-consistency-checklist.md

@@ -0,0 +1,140 @@
+# Workflow Consistency Checklist
+
+Maintenance checklist after editing `packages/cli/project-template`. Run before merging doc changes.
+
+## Phase A — Invoke protocol
+
+- [x] `agent-conduct.md`: § Invoke protocol (all sub-agents)
+- [x] All five agents: First Step = handoff → Runtime → conditional refs
+- [x] Checkpoint documented as human log only (collaboration § STOP sync)
+
+## Phase B — Track done & stage sync
+
+- [x] Each agent Runtime has **Track done** note
+- [x] `CLAUDE.md` + `playcraft-orchestrator.mdc`: § Stage sync on handoff
+- [x] `project-state.template.md`: handoff Examples comment block
+
+## Phase C — STOP sync
+
+- [x] `collaboration.md`: § STOP sync checklist (4 steps)
+- [x] `agent-conduct.md`: sub-agents MUST complete STOP sync
+
+## Phase D — L1 < 220 lines
+
+- [x] `pm.md`, `designer.md`, `developer.md`, `reviewer.md`, `technical-artist.md` each **< 220** lines
+- [x] New refs registered in `refs/README.md` with L1 back-links
+- [x] `designer-deliverable-spec.md`, `designer-style-exploration-flow.md`, `developer-phase1-flow.md` exist
+
+## Phase F — TA atlas / WebP / MP3
+
+- [x] `ta-atlas-deliverable-standard.md` exists; TA L1 + Runtime reference it
+- [x] `layout-spec.template.md`: atlas grouping table, webp defaults, frameId column
+- [x] `collaboration.md` § Asset Contract: WebP atlas + MP3
+- [x] PM `pm-workflow-detail.md`: Atlas grouping at Gate #1
+- [x] Developer cookbook: atlasPath + frameId binding
+
+## Round 3 — Invoke 体感打磨
+
+### Phase A — Runtime 入口微调
+
+- [x] Designer Runtime: Phase 1 Skill Discovery → style-exploration-flow (one line)
+- [x] Developer Runtime: Spec Quick-Check (30s, MUST) on production branch
+- [x] Developer Ph.1 STOP: `next_orchestrator_action` = single value `Wait for parallel tracks`
+- [x] TA Step 0: verb pipeline (no E→A→B→C→D shorthand in L1)
+- [x] TA Compliance: atlas grouping table check + spec-gap routeTo PM
+
+### Phase B — L1 术语显式化
+
+- [x] PM Runtime: 四件套 list + atlas groups + Style Direction in Track done
+- [x] Reviewer Goals: six dimension names + Vetoes listed
+- [x] Designer Track done: MC 5×9:16 ratio (≈ 2.81)
+
+### Phase C — 跨 Agent 同步
+
+- [x] `collaboration.md` § STOP sync: Parallel Tracking table example
+- [x] `CLAUDE.md` + `playcraft-orchestrator.mdc`: Stage sync includes `Run Gate #2a`
+- [x] All five L1 Mission: link to CLAUDE § Stage Model
+- [x] `developer-phase1-flow.md`: linear Step 1–8 ordering
+
+### Phase D — 重复段清理
+
+- [x] Developer L1: no separate `## Phase 1` / `## Phase 2` headings (Execute L2 under Runtime)
+- [x] Designer Phase 2: skills/refs/output only (no duplicate Trigger)
+- [x] Developer Important Rules: Test-first + Atlas binding split (#5 / #6)
+- [x] Reviewer Output: sync `handoff.rework_round` on fail
+
+## Gate & orchestration (baseline)
+
+- [x] Gate Protocol matches CLAUDE Orchestration table
+- [x] All five agents: Runtime + PLAYCRAFT_STOP
+- [x] PM Gate #1 four docs; Reviewer no `stage: rework`; Developer handoff Invoke @reviewer
+
+## Polish pass (Glossary / deliverable cards / TA Step naming)
+
+- [x] `collaboration.md`: § Glossary (canonical terms)
+- [x] `pm.md`: § Gate #1 Deliverable Card
+- [x] Reviewer: `rework_round` failure budget explicit in L1 + `reviewer-six-dimension-eval.md`
+- [x] `refs/README.md`: § 按 invoke 场景反查
+- [x] `ta-pipeline-cookbook.md`: Step 0/1/2 (not Phase 0/1/2)
+- [x] `CLAUDE.md`: Single-Agent Fallback removed; sub-agent invoke required
+
+## Phase G — Designer Handoff v2
+
+- [x] `docs/team/workflow-changelog.md` documents `designer-handoff-v2`
+- [x] `templates/project-state.template.md` § Workflow spec + Parallel Tracking (audio + digit + atom status)
+- [x] `designer-deliverable-spec.md`: Handoff Pack, Phase 2 VisualAtom rules; no legacy Phase 2 visual-only-TA sentence
+- [x] `designer-handoff-v2-checklist.md` linked from `designer-style-exploration-flow.md` Step 5
+- [x] `templates/style-exploration.template.md` uses MC + ASR (no `concept_{{a}}.png`)
+- [x] `templates/designer-log.template.md`: ASR Coverage Matrix + Palette Locked
+- [x] `playcraft-style-qa` uses MC path; no `concept_selected.png`
+- [x] `playcraft-asset-state-sheet` skill exists; `playcraft-exploded-view` removed
+- [x] `core-model.md` + `atom-plan.template.md` v2 VisualAtom baseline
+- [x] Vitest `designer-handoff-v2` cases pass
+
+## Phase J — atom-plan JSON canonical
+
+- [x] `docs/team/atom-plan-format.md` — JSON + MD split, PM Gate #1 flow
+- [x] `templates/atom-plan.template.json` + trimmed `atom-plan.template.md` (no inline Skills Match Snapshot)
+- [x] `pm-workflow-detail.md` Step 8 + Gate checklist → `atom-plan.json` + `validate-atom-plan`
+- [x] `playcraft-workflow` living DAG + `collaboration.md` / `agent-conduct.md` aligned
+- [x] `.claude/hooks/validate-atom-plan.mjs` + PM STOP in `settings.json` / `.cursor/hooks.json`
+- [x] `validate-workflow-stop.mjs` requires `atom-plan.json` for TA/Developer intake
+- [x] Vitest `atom-plan-json-and-validate-hook` passes
+
+## Phase I — Upstream intake + four-doc discipline + hooks
+
+- [x] `agent-conduct.md`: PM/Designer four-doc discipline; TA/Developer Upstream Intake MUST
+- [x] `ta-pipeline-cookbook.md` Step 0a + `developer-phase1-flow.md` Step 0
+- [x] `ta-log.template.md` + `developer-log.template.md` § Upstream Intake
+- [x] `pm.md` + `pm-workflow-detail.md` + `designer.md` + `collaboration.md` § Four-doc discipline
+- [x] `.claude/settings.json` + `.cursor/hooks.json` → `validate-workflow-stop.mjs`
+- [x] Vitest `upstream-intake` + `validate-workflow-stop.test.ts` pass
+
+## Phase H — Production serial v1
+
+- [x] `workflow-changelog.md`: `production-serial-v1` current; no Migration section
+- [x] `templates/project-state.template.md`: `workflowSpecVersion` = `production-serial-v1`; § Production Pipeline (no Parallel Tracking / THREE-WAY)
+- [x] Gate #2b: orchestrator invokes `@designer` only; serial `@technical-artist` → `integration` `@developer`
+- [x] `designer.md` STOP: `Invoke @technical-artist`; `technical-artist.md`: `Set stage=integration, invoke @developer`
+- [x] `developer.md` Runtime: no `stage: production` row; single `integration` branch
+- [x] `developer-phase1-flow.md`: trigger `integration`; no assets-not-required / Parallel with
+- [x] `CLAUDE.md` + `playcraft-orchestrator.mdc` + `collaboration.md` + `agent-conduct.md` + `agent-runtime-matrix.md` aligned
+- [x] Vitest `production-serial-v1` cases pass
+
+## Phase K — Plan convergence (TA + Developer)
+
+- [x] `templates/ta-log.template.md`: § Production Plan (Coverage / Atlas / Pipeline Order / Risk)
+- [x] `templates/developer-log.template.md`: § Implementation Plan (Architecture / Scene-Asset / PGS / Risk)
+- [x] `validate-workflow-stop.mjs`: validates Plan section + Risk Checklist + no placeholders
+- [x] `.claude/hooks/README.md`: documents Plan validation on STOP
+- [x] `technical-artist.md` + `developer.md`: Runtime + Track done + Important Rules reference Plan
+- [x] `ta-pipeline-cookbook.md` Step 0d + `developer-phase1-flow.md` Step 3b
+- [x] `agent-conduct.md`: TA/Developer MUST/MUST NOT for Plan before production/code
+- [x] `collaboration.md` § STOP sync checklist step 5 (Plan convergence)
+- [x] Vitest `validate-workflow-stop.test.ts` covers `validatePlan`
+
+## Automated
+
+```bash
+cd packages/cli && pnpm exec vitest run test/project-template-workflow.test.ts test/validate-workflow-stop.test.ts
+```

package/project-template/templates/atom-plan.template.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 1,
+  "skillsMatch": {
+    "engine": "{{engine}}",
+    "engineSource": "inferred",
+    "intent": ["{{gameplayType}}", "{{mechanic}}", "{{keywords}}"],
+    "items": [],
+    "mediaGroups": []
+  },
+  "atoms": [
+    {
+      "atomId": "{{production_atom_id}}",
+      "slot": "{{slot_name}}",
+      "type": "GameplayAtom",
+      "assignTo": "Developer",
+      "dependsOn": [],
+      "skillRef": "{{aigameplay_atomId_or_null}}",
+      "priority": "high",
+      "parallelGroup": null,
+      "referenceSource": null,
+      "status": "pending",
+      "actualOutput": null
+    }
+  ],
+  "dagRevisions": []
+}