@playcraft/cli 0.0.40 → 0.0.41

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

@@ -0,0 +1,396 @@
+---
+name: playcraft-workflow
+description: PlayCraft 可玩广告开发工作流与 Skill 体系入口。在开始构建任何游戏项目、选择组件、查找 Skill、生成图片/音频、创建 Remix 时自动触发。解释双层 Skill 体系并引导正确工作流。
+triggers: 构建游戏,开始开发,创建项目,选择组件,选择 skill,查找 skill,生成图片,生成音频,工作流,workflow
+---
+
+# PlayCraft 工作流与 Skill 体系
+
+## 执行模式（首先判断）
+
+在开始任何工作前，先判断当前执行环境：
+
+### Multi-Agent Mode（默认，优先使用）
+
+如果当前环境支持 sub-agent 调用（Claude Code 的 `@agent` 语法可用）：
+
+1. **你是 orchestrator**，不要自己执行任何 Agent 的工作
+2. 按 `CLAUDE.md` 中 Orchestration Protocol 的阶段转换表 spawn sub-agents
+3. 每个 sub-agent 完成后，读取 `docs/project-state.md` 的 **`## Agent handoff`** YAML + Gates 表，再决定下一步
+4. **Orchestrator 会话**优先遵循 `.cursor/rules/playcraft-orchestrator.mdc`；子 Agent 会话不加载 orchestrator rule
+5. **仅 orchestrator** 对用户 `AskUserQuestion` — 子 Agent **禁止**问用户（见 `docs/team/agent-conduct.md`）
+   - `gate_pending` 非 null 且 `waiting_for: user_gate` 时：**只跑 Gate**，不得 invoke 子 Agent
+   - `subagent_stop: true` 时：只执行 `next_orchestrator_action`
+   - Gate #1 / #2a / #2b：`AskUserQuestion`（子 Agent 更新 handoff 后 STOP）
+   - Gate #3：Reviewer 通过后展示 **devUrl**（用户只点链，不跑 `npm run dev`）
+   - Gate / handoff 细则：`docs/team/collaboration.md` § Gate Protocol、§ Agent Handoff
+6. `devStatus: ready` → `@reviewer`；`devStatus: blocked_upstream` → 按 `devBlockers.routeTo` 调度 TA/Designer → 再 `@developer`
+7. 当前交付终点 = 用户在 Dev URL 验收通过（`done`），**不要求** `playcraft build`
+
+### Single-Agent Mode（降级模式，当 sub-agent 不可用时）
+
+串行执行所有阶段，但**必须**：
+
+- 每进入一个新阶段时，先完整读取对应 `.claude/agents/<role>.md` 的所有指令
+- 不可跳过任何阶段的必选产出（特别是 TA 的完整素材生产——UI 图、VFX、精灵图都必须生产）
+- 必须执行 Spec Quick-Check：TA 在 production Wave 2 启动后 30s 内；Developer 在 `integration` 启动后 30s 内
+- PM 定稿后运行 `playcraft skills link --from-atom-plan`；Developer 优先读 `.claude/skills/<atomId>/SKILL.md`，仅断链时用 `playcraft skills read`
+
+---
+
+## 双层 Skill 体系
+
+PlayCraft 使用 **两套互补的 Skill 系统**：
+
+| 层                     | 位置                                            | 用途                                             | 发现方式                                                                                                                       |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| **Claude Code Skills** | `.claude/skills/`                               | 平台工具使用指南（图片生成、音频、代码编辑器等） | IDE 自动发现和注入                                                                                                             |
+| **DAG Atom Skills**    | `playcraft skills match` 返回的 `skillDir` 路径 | 游戏积木（玩法规则、组件、图片、音效、配置）     | `playcraft skills match` CLI 推荐；PM 定稿后 `playcraft skills link --from-atom-plan` 软链到 `.claude/skills/` 供 IDE 自动发现 |
+
+**关键规则**：构建任何新游戏项目前，**必须先运行 `playcraft skills match`** 获取完整的推荐积木清单，再动手写代码。
+
+---
+
+## 标准工作流（必须遵守）
+
+```
+① 运行本地 Skill 推荐（必须）
+   playcraft skills match --intent "<关键词,逗号分隔>" --json
+   # 自动推断引擎；若已定：加 --engine <threejs|phaser>
+
+② 评估本地 Skill 覆盖度
+   - 完整覆盖 → 进入步骤 ③
+   - 部分覆盖 → 进入步骤 ③，同时触发 ②-ext
+   - 完全没有 → 触发 ②-ext
+
+② -ext（本地不足时）网络研究补充
+   - 参阅 playcraft-research SKILL，按角色执行定向研究
+   - 研究结论写入 `docs/atom-plan.md` 的对应 Context 区域
+   - 标记候选新 Skill（在 DAG Revisions 中记录）
+
+③ 读取每个代码 Skill 的 SKILL.md（PM 已 link 后优先项目内路径）：
+   cat .claude/skills/<atomId>/SKILL.md
+   # 软链缺失时兜底：playcraft skills read <atomId>
+   - 理解 Recipe；列出将使用的 ref/ 文件
+   - 将关键信息记入 `docs/atom-plan.md` 对应的 Context 区域
+
+④ PM 定稿 `atom-plan.json` 后，软连接 DAG Skill 到项目（IDE 自动发现，强烈推荐）：
+   playcraft skills link --from-atom-plan --prune
+
+⑤ 执行 scaffold 命令，复制 ref 文件到项目（注：package.json/tsconfig.json 使用 merge-json 模式，不覆盖已有配置）
+   playcraft skills scaffold --engine <引擎> --atoms <skill1,skill2> --out ./game
+
+⑥ 按各媒体 Skill 的参数（或网络研究得出的参数）生成图片/音频资产
+   playcraft tools generate-image --prompt "..." --output ta-workspace/xxx.png
+   playcraft tools generate-sfx --prompt "..." --duration 1.5
+   playcraft tools generate-bgm --prompt "..."
+
+⑦ 在已有 ref 文件基础上（或基于研究方案）编写项目代码
+```
+
+**禁止**：
+
+- ❌ 未运行 `skills match` 就开始写引擎/布局/输入/渲染代码
+- ❌ 未读 SKILL.md（项目软链或 CLI 兜底）就跳过 Skill 内容直接从头实现
+- ❌ 对已有 ref 文件重新实现相同功能
+- ❌ 手动猜测 Skill 名称
+- ❌ 本地无 Skill 就直接凭感觉写——先做网络研究，把依据记录在活 DAG 里
+
+---
+
+## Agent 自增强协议（Skill-on-Demand）
+
+> **核心原则**：Skill 是持续可用的资源，不是一次性查询。每个 Agent 在其专属阶段都应独立做角色相关的 Skill 发现。
+
+### 为什么需要多次 Skill 查询
+
+- 每个 Agent 是独立 session，不继承前一个 Agent 的 Skill 搜索结果
+- 每个角色需要的 Skill 类型完全不同
+- 在实现某个具体功能时才知道需要什么，无法在规划阶段完全预见
+
+### 按角色的 Skill 发现模式
+
+**PM（规划阶段）**
+
+```bash
+# 确认玩法类型的已有实现和依赖关系
+playcraft skills match --engine <engine> --intent "<gameplay_type>,<game_mechanic>" --json
+# 浏览所有可用配置封包
+playcraft skills list --category config --json
+```
+
+**Designer（创意样本生产阶段）**
+
+```bash
+# 找视觉资产参考和生成参数（aiimage Skill 包含 manifest.json 里的 generation 字段）
+playcraft skills list --category visual --json
+# 找音频资产参考
+playcraft skills list --category audio --json
+# 按具体元素类型搜索
+playcraft skills match --intent "<element_type>,<art_style>" --json
+```
+
+**Technical Artist（技术生产阶段）**
+
+```bash
+# 找精灵图/图集生产 Skill
+playcraft skills list --category visual --json
+playcraft skills match --intent "<element_type>,sprite,atlas,sheet" --json
+# 找 3D 渲染/翻转精灵图 Skill
+playcraft skills match --intent "3d,sprite,flip,render" --json
+# 找图片处理 Skill
+playcraft skills match --intent "image,processing,pipeline" --json
+# 找验证器（用于合规检查）
+playcraft skills list --category validator --json
+```
+
+**Developer（代码实现阶段）**
+
+```bash
+# 每实现一个 Atom 前，先搜索是否有现成的代码积木
+playcraft skills match --engine <engine> --intent "<feature_name>,<component_type>" --json
+# 找引擎适配层
+playcraft skills list --category engine --json
+# 找布局/UI 组件
+playcraft skills list --category layout --json
+```
+
+**Reviewer（质量验证阶段）**
+
+```bash
+# 找可用的校验器 Skill
+playcraft skills list --category validator --json
+# 按具体校验目标搜索
+playcraft skills match --intent "validator,balance,compliance,ux" --json
+```
+
+### "写代码前先查 Skill" 规则
+
+在实现任何非平凡组件之前，**必须先执行此检查**：
+
+```
+1. 我即将实现：<描述功能>
+2. 运行：playcraft skills match --engine <e> --intent "<功能关键词>" --json
+3a. 找到完整匹配 Skill → 读取其 SKILL.md → scaffold → 基于 ref 文件实现
+3b. 找到部分匹配 → 使用 Skill 作为基础，参阅 playcraft-research 补充网络研究
+3c. 完全未找到 Skill → 参阅 playcraft-research 执行定向网络研究 → 研究结论写入
+     `atom-plan.md` § Impl Skill Context → 在 `dagRevisions` / DAG Revisions 标注候选新 Skill → 实现
+```
+
+> 本地 Skill 库不可能穷尽所有场景。遇到陌生玩法、新艺术风格、特定算法时，**网络研究是标准流程，不是例外**。关键是把研究结论沉淀进活 DAG，让整个团队受益。
+
+**典型触发场景**：
+
+- 要写一个新的 UI 组件 → `skills match --intent "ui,component,<具体名称>"`
+- 要实现某种玩法规则 → `skills match --intent "<gameplay>,rules,algorithm"`
+- 要做图片后处理/精灵图 → 读取 `playcraft-image-generation` SKILL.md（涵盖后处理管线与脚本模板）
+- 要做音频生成/处理 → 读取 `playcraft-audio-generation` SKILL.md
+- 要读取某个 Skill 的完整说明 → `playcraft skills read <atomId>`
+
+### Skill 依赖链发现
+
+Atom Skill 之间通过 `imports` 字段形成依赖链。发现一个 Skill 可能引出更多：
+
+```bash
+# 读取某 Skill 的完整 SKILL.md（含 imports / Recipe / 操作流程）
+playcraft skills read <atomId>
+
+# match 输出的 JSON 中每个 item 包含 skillDir 字段，可直接访问 ref/ 目录
+# 例如读取 memory_match 的 PGS 规则骨架：
+playcraft skills match --engine phaser --intent "memory,match" --json \
+  | python3 -c "import json,sys; items=json.load(sys.stdin)['items']; [print(i['atomId'], i['skillDir']) for i in items]"
+
+# 查看 skill 的 ref/ 目录文件（先用 read 获取 skillDir）
+playcraft skills read <atomId>  # 找到 skillDir 路径
+# 然后直接读取 ref/ 文件：
+cat <skillDir>/ref/<file>
+
+# 按依赖 Skill 名称递归读取
+playcraft skills match --intent "<imported_skill_keywords>" --json
+```
+
+---
+
+## 活 DAG 分层富集模式（保持一致性）
+
+> **问题**：多个 Agent 各自做 DAG/Skill 搜索，结果会不会冲突？谁的优先？
+>
+> **答案**：不冲突。**活 DAG** 在 `docs/atom-plan.json`（`atoms[]` + `skillsMatch`）；各 Agent 在 `docs/atom-plan.md` 向专属 Context 区富集，形成统一知识库。
+
+### 活 DAG 的分层结构
+
+```
+docs/atom-plan.json
+├── skillsMatch                    ← PM：`playcraft skills match --json`（skillRef 唯一来源）
+├── atoms[]                        ← PM：排期 DAG；Gameplay/Config 的 skillRef 仅来自 skillsMatch.items
+└── dagRevisions[]                 ← 结构变更 / skills-match-gap（可与 md 同步）
+
+docs/atom-plan.md
+├── Atom List（可选镜像表）        ← 与 atoms[] 同步；可省略
+├── ## Acceptance Criteria         ← PM：每 atom 一条可测验收
+├── ## Asset Skill Context         ← Designer
+├── ## TA Skill Context            ← TA
+├── ## Impl Skill Context          ← Developer
+└── ## DAG Revisions               ← 人类可读修订记录
+```
+
+Skills 路径真源：`playcraft.config.json` → `agent.skillsDir`（**不要**在 atom-plan 写死 node_modules）。格式详解：[`docs/team/atom-plan-format.md`](../../docs/team/atom-plan-format.md)
+
+### 各 Agent 的读写职责
+
+| Agent                | 读取                                     | 写入                                                  |
+| -------------------- | ---------------------------------------- | ----------------------------------------------------- |
+| **PM**               | design-brief, layout-spec                | `atom-plan.json`（skillsMatch + atoms[]）             |
+| **Designer**         | `atoms[]` + design-brief                 | `atom-plan.md` § Asset Skill Context                  |
+| **Technical Artist** | `atoms[]` + Asset Context + designer-log | `atom-plan.md` § TA Skill Context；`atoms[].status`   |
+| **Developer**        | `atoms[]` + Context 区 + design-brief    | `atom-plan.md` § Impl Skill Context；`atoms[].status` |
+| **Reviewer**         | JSON + MD（只读）                        | 不写                                                  |
+
+### 为什么这样设计能避免冲突
+
+**示例**：游戏风格为"像素风"
+
+```
+PM:
+  → 搜索 aigameplay skills，得到 arrow_pick_match_rules
+  → 在 atoms[] 填：arrow_rules | skillRef = arrow_pick_match_rules.aigameplay
+  → 不知道像素风需要什么具体的图片参数，留 VisualAtom skillRef 为空（—）
+
+Designer:
+  → 读到 StyleDirection = "像素风 8-bit 高饱和"
+  → 搜索 aiimage skills，得到 pixel_art_sprite.aiimage
+  → 读 pixel_art_sprite 的 manifest.json：了解 prompt 模板、block 尺寸参数
+  → 在 Asset Skill Context 写：bg_atom → pixel_art_sprite → 关键参数...
+  → 现在知道"像素风"具体怎么生产了
+
+Developer:
+  → 读 PM 的 skillRef = arrow_pick_match_rules.aigameplay
+  → 读 Designer 的 Asset Skill Context（了解视觉风格，确保代码绑定正确）
+  → 搜索额外的 aicomponent skills
+  → 在 Impl Skill Context 写：arrow_rules_impl → 实现细节...
+
+Reviewer:
+  → 读 Atom List + Asset Skill Context + Impl Skill Context
+  → 有了完整 Skill 依据，搜索 aivalidator skills 进行验证
+```
+
+**无冲突的根本原因**：每个 Agent 的写入区域不重叠。DAG 是合作共建的，不是争夺的。
+
+---
+
+## Scaffold 所有权模型（防冲突）
+
+> **核心规则**：`playcraft skills match/list` 是只读操作，任何 Agent 随时可用，零冲突。
+> **唯一风险**：`playcraft skills scaffold`（写文件），必须遵守所有权规则。
+
+### 每个 Agent 的 Scaffold 域
+
+| Agent                | 可 Scaffold 的 Skill 类型                                      | 写入目录  | 禁止 Scaffold                                             |
+| -------------------- | -------------------------------------------------------------- | --------- | --------------------------------------------------------- |
+| **Developer**        | `aicomponent`, `aigameplay`, `aiconfig`                        | `game/`   | `aiimage`, `aiaudio`, `aivalidator`                       |
+| **Technical Artist** | ❌ 不 Scaffold（读 manifest.json generation 参数，直接调 CLI） | `assets/` | **全部**（TA 通过 CLI 管线生产，不 Scaffold）             |
+| **Designer**         | ❌ 不 Scaffold                                                 | `assets/` | **全部**（只读 manifest.json 的 generation 参数用于生成） |
+| **Reviewer**         | ❌ 不 Scaffold                                                 | 只读      | **全部**（read-only 角色）                                |
+| **PM**               | ❌ 不 Scaffold                                                 | `docs/`   | **全部**（只做规划 + 协调）                               |
+
+### 为什么 Designer 和 TA 不需要 Scaffold
+
+`aiimage` / `aiaudio` Skill 没有 `ref/` 代码文件，只有 `manifest.json` 中的 `generation` 字段（prompt、aspectRatio、duration 等）。Designer 和 TA 读取这些参数作为生成基准，通过 `playcraft image *`、`playcraft tools generate-image` 等 CLI 命令执行，不复制任何文件到项目。
+
+### Production 串行编排（production-serial-v1）
+
+Gate #2b 通过后 **严格串行**（见 `workflow-changelog.md`）：
+
+```
+Wave 1 Designer Ph.2 → Wave 2 TA → integration Developer
+```
+
+Developer 仅在 `integration` 写入 `game/**`，此时 TA 已交付合同路径上的真实资产。
+
+### 避免重复 Scaffold 的规则
+
+同一个 Skill 不应被多次 Scaffold 到同一目录：
+
+- PM 在 `atom-plan.json` → `atoms[]` 标注 `skillRef`（若有）+ 调度元信息（assignTo/dependsOn/priority/parallelGroup/referenceSource）
+- Developer 在 `integration` 开始时，按 `atoms[]` 中 `assignTo: Developer` 批量 scaffold 一次
+- **不要在实现单个 Atom 时反复 scaffold** — 先统一 scaffold 所有依赖，再逐一实现
+
+---
+
+## 如何阅读 Atom Skill 的 SKILL.md
+
+每个 Atom Skill 的 `SKILL.md` 包含：
+
+1. **YAML frontmatter**：`name`（格式为 `<name>.<bundleType>`）、`description`、`triggers`
+2. **功能说明**：Skill 做什么、输出什么
+3. **Scaffold / Imports**：依赖哪些其他 Skill
+4. **Skill Definition 区块**（部分 Skill 有）：
+   ```yaml
+   ## Skill Definition
+   tools:
+     - bash
+     - read
+   prompt_extension: |
+     这里是注入给 agent 的操作指令
+   ```
+   `prompt_extension` 的内容是 agent 执行此 Skill 时需要遵循的具体指令。
+
+---
+
+## Skill 推荐示例
+
+```bash
+# Three.js 3D 棋盘消除游戏
+playcraft skills match --engine threejs --intent "board,3d,path,animation"
+
+# Phaser 三消游戏
+playcraft skills match --engine phaser --intent "match3,grid,tile,score"
+
+# 跑酷游戏
+playcraft skills match --engine phaser --intent "parkour,left_right,run,obstacle"
+
+# 查看所有可用 Skill
+playcraft skills list --json
+```
+
+---
+
+## 平台工具快速参考
+
+### Claude Code Skills（`.claude/skills/` 目录，自动注入）
+
+> ⚠️ 下表只列出**项目模板中实际存在**的 Skill。不要查找或引用表外的 Skill 名称。
+
+| Skill                          | 职责                                                                                                                   | 主要角色      |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `playcraft-workflow`（本文件） | 工作流入口、Skill 体系、DAG 协作规范                                                                                   | 全员          |
+| `playcraft-image-generation`   | AI 图片生成全指南：模型选择、gpt-image-2 双 provider、精灵图直出、绿幕策略、edit 变体、错误恢复、ta-workspace 脚本模板 | Designer / TA |
+| `playcraft-audio-generation`   | AI 音频生成全指南：SFX/BGM 生成参数、prompt 套路、本地音频后处理（compress/fade/loop）                                 | Designer      |
+| `playcraft-research`           | 网络研究协议：`tools research/fetch-url/search-image` 三工具标准流程、研究结果融入活 DAG                               | 全员          |
+
+### CLI 命令组（`playcraft <group>`，无需 Skill 文件）
+
+| 命令组                                              | 能力摘要                                                                                                                                                         | 主要角色             | 完整文档                                                     |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------ |
+| `playcraft tools generate-image`                    | AI 文生图/图生图；`--reference-image`、`--image-model`（裸模型名时后端按优先级 fallback）、`--count N`（同 prompt 批量出图）、`--timeout`                        | Designer / TA        | `docs/cli/tools.md §1.2`                                     |
+| `playcraft tools generate-sfx/bgm`                  | AI 音效/背景音乐生成                                                                                                                                             | Designer             | `docs/cli/tools.md §1.2`                                     |
+| `playcraft tools generate-3d` 系列                  | AI 3D 模型生成、贴图、重拓扑、UV 展开、动作                                                                                                                      | TA                   | `docs/cli/tools.md §1.3`                                     |
+| `playcraft tools research/fetch-url`                | AI 网络研究与 URL 读取                                                                                                                                           | 全员                 | `docs/cli/tools.md §1.7`                                     |
+| `playcraft tools save-to-git/build-project/publish` | 项目保存、构建、发布                                                                                                                                             | Developer            | `docs/cli/tools.md §1.4`                                     |
+| `playcraft image`                                   | 本地图片处理 + 后端抠图/分层：resize/crop/decompose-layers/segment/remove-background/sprite-split/sprite-sheet/batch/pipeline/animate/tint/overlay/gen-tile-back | TA                   | `docs/cli/tools.md §2`；分层与蒙版选型见 `playcraft-masking` |
+| `playcraft audio`                                   | 本地音频处理：compress/trim/fade/loop/normalize/mix                                                                                                              | Designer / TA        | `docs/cli/tools.md §3`                                       |
+| `playcraft 3d`                                      | 本地 3D 处理：白模库/apply-texture/optimize/convert                                                                                                              | TA                   | `docs/cli/tools.md §4`                                       |
+| `npm run dev`                                       | 项目 Dev 预览（`package.json` → `scripts.dev`）                                                                                                                  | Developer / Reviewer | 用户不执行；Gate #3 由 orchestrator 递 devUrl                |
+| `playcraft build / build-all`                       | 打包 Playable Ads（**未来**交付路径，非当前 `done` 条件）                                                                                                        | —                    | —                                                            |
+| `playcraft skills match/list/link/scaffold/read`    | DAG Atom Skill 推荐、IDE 软链、脚手架、内容读取（`link` 供 PM；`read` 供 Developer Preflight）                                                                   | 全员                 | —                                                            |
+
+---
+
+## Skill 目录发现优先级
+
+`playcraft skills` 命令按以下优先级发现 Skill 目录：
+
+1. `--skills-dir <path>` 参数
+2. `playcraft.config.json` 中的 `skillsDir` 字段
+3. `AGENT_SKILLS_PATHS` 环境变量
+4. `<项目根>/node_modules/@playcraft/skills/skills`（npm 安装后）

package/project-template/.cursor/hooks.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "hooks": {
+    "subagentStop": [
+      {
+        "command": "node .claude/hooks/validate-atom-plan.mjs",
+        "timeout": 30,
+        "failClosed": false
+      },
+      {
+        "command": "node .claude/hooks/validate-workflow-stop.mjs",
+        "timeout": 30,
+        "failClosed": false
+      }
+    ]
+  }
+}

package/project-template/.cursor/rules/playcraft-orchestrator.mdc

@@ -0,0 +1,87 @@
+---
+description: PlayCraft playable ad orchestrator — gates, stages, sub-agent spawn only
+alwaysApply: true
+---
+
+# PlayCraft Orchestrator
+
+You are the **orchestrator** for a PlayCraft playable ad project. Do not role-play PM, Designer, TA, Developer, and Reviewer in one session when `@agent` invoke is available.
+
+## Invoke `@developer` (`integration` only)
+
+Sub-agents start a **fresh session** — they do not see your `playcraft skills match` output. Before spawn (after TA Wave 2 `done`):
+
+1. Confirm PM ran `playcraft skills link --from-atom-plan --prune` (or run it before spawn).
+2. Read `docs/atom-plan.json` → `atoms[]` where `assignTo: Developer` and `skillRef` is non-null.
+3. Optional 30s spot-check: `ta-log` Compliance green + contract paths exist under `assets/`.
+4. In the **first message** to `@developer`, paste skillRef list and require: read `.claude/skills/<skillRef>/SKILL.md` + `ref/` first; **only if** `test -f .claude/skills/<skillRef>/SKILL.md` fails, use `playcraft skills read` (uses `playcraft.config.json` `skillsDir`); then `playcraft skills scaffold --atoms … --out ./game`.
+5. Ban hand-written PGS that ignores linked Skill `ref/`.
+
+Integration STOP invalid without **§ Skill Preflight** (each row: `linked` or `cli-fallback`).
+
+## Before every decision
+
+1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML + Gates table + **Production Pipeline** waves.
+2. If `gate_pending` non-null and `waiting_for: user_gate` → **Gate only** — do **not** invoke sub-agents.
+3. If `subagent_stop: true` and `waiting_for: orchestrator` → execute **only** `next_orchestrator_action`.
+4. Follow `CLAUDE.md` Orchestration Protocol and `docs/team/collaboration.md` § Gate Protocol, § Agent Handoff.
+5. Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, `subagent: <target>`).
+
+## Gates (only you ask the user)
+
+| Gate | When | Action |
+| ---- | ---- | ------ |
+| #1 | handoff `gate_pending: "1"` or `gates.#1 = pending` | `AskUserQuestion` → pass → `stage: style_exploration` → `@designer` |
+| #2a | `gate_pending: "2a"` | `AskUserQuestion` → `selectedMcOption` → resume `@designer` |
+| #2b | `gate_pending: "2b"` | Confirm MC+ASR → `stage: production` → invoke `@designer` Ph.2 **only** |
+| #3 | Reviewer pass, `devStatus: ready` | Show **devUrl** via `AskUserQuestion` — user never runs `npm run dev` |
+
+Sub-agents **must not** use `AskUserQuestion` or set mainline `stage`. See `docs/team/agent-conduct.md`.
+
+## Workflow STOP hooks (Claude Code + Cursor)
+
+After **Technical Artist** or **Developer** subagent STOP, `.claude/hooks/validate-workflow-stop.mjs` runs automatically:
+
+- **Claude Code**: `.claude/settings.json` → `SubagentStop`
+- **Cursor**: `.cursor/hooks.json` → `subagentStop`
+
+If intake validation fails, the subagent **cannot stop** until `logs/ta-log.md` or `logs/developer-log.md` § **Upstream Intake** is complete. Do **not** invoke the next role until handoff shows a successful STOP (or re-invoke the same agent to fix intake).
+
+**Serial spawn after Gate #2b:** `@designer` → (Wave 1 done) `@technical-artist` → (Wave 2 done) `stage: integration` + `@developer`. **Never** spawn `@developer` during `production`.
+
+## Stage sync on handoff
+
+When executing `next_orchestrator_action`, **also** update `stage` / gates (sub-agents never do this):
+
+| Action substring | Must write |
+| ---------------- | ---------- |
+| `Run Gate #1` | After pass: `stage: style_exploration`, `gates.#1 = passed` |
+| `Run Gate #2a` | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` (stage stays `style_exploration`) |
+| `Run Gate #2b` | `stage: production`, `gates.#2b = passed`, invoke `@designer` Ph.2 only |
+| `Invoke @technical-artist` | Wave 1 `done` → invoke TA (stay `production`) |
+| `Set stage=integration` / invoke `@developer` | Wave 2 `done` → `stage: integration` |
+| `Invoke @reviewer` | `stage: review` |
+| `Set stage=rework` | `stage: rework` + invoke routed agents |
+| `Run Gate #3` | `gates.#3 = pending` → accept → `stage: done` |
+
+## Handoff × stage matrix
+
+| stage | gate_pending | Typical `next_orchestrator_action` |
+| ----- | ------------ | ------------------------------------ |
+| `pm` | `"1"` | Run Gate #1 |
+| `style_exploration` | `"2a"` | Run Gate #2a |
+| `style_exploration` | `"2b"` | Run Gate #2b → `stage: production` → `@designer` Ph.2 |
+| `production` | null, Wave 1 pending | `@designer` Ph.2 |
+| `production` | null, Wave 1 done | `Invoke @technical-artist` |
+| `production` | null, Wave 2 done | `Set stage=integration, invoke @developer` |
+| `integration` | null, `devStatus: ready` | Invoke `@reviewer` |
+| `integration` | null, `blocked_upstream` | Re-invoke per `devBlockers.routeTo` → `@developer` |
+| `review` | — (fail handoff) | Set `stage: rework`, invoke routed agents |
+| `rework` | null | Fixes → `@developer` → `@reviewer` |
+| `review` | `"3"` or pass | Gate #3 devUrl |
+
+## Stage shortcuts
+
+- Gate #2b → `@designer` only; Wave 1 done → `@technical-artist`; Wave 2 done → `integration` + `@developer`
+- Review fail → **you** set `stage: rework` (Reviewer does not)
+- `done` = user accepts devUrl; **not** `playcraft build`

package/project-template/.cursor/rules/playcraft-subagent-boundary.mdc

@@ -0,0 +1,18 @@
+---
+description: PlayCraft sub-agent file boundaries — no user gates, STOP protocol
+globs: .claude/agents/**,docs/**,logs/**,assets/**,game/**
+alwaysApply: false
+---
+
+# Sub-Agent Boundary
+
+When editing project outputs as a **sub-agent** (PM / Designer / TA / Developer / Reviewer):
+
+- **Do not** `AskUserQuestion` or ask the user to choose Gate options.
+- On gate-ready work: update `## Agent handoff` YAML + `gates.#*` = `pending` + Progress Checkpoint → **STOP** (see `## Runtime` in your agent file).
+- If `subagent_stop: true` for your role → do not duplicate work; wait for orchestrator.
+- Read `docs/team/agent-conduct.md` and your `.claude/agents/<role>.md` § Runtime + § Agent Conduct.
+- **Do not** change mainline `stage` — use `next_orchestrator_action` in handoff.
+- R/W matrix: `docs/team/collaboration.md`.
+
+Designer: read `selectedMcOption` before ASR (UI + element state sheets). TA: only after Production Pipeline Wave 1 `done`. Developer: only in `integration`; complete `developer-log.md` § Skill Preflight before `game/` edits; never `devStatus: ready` with open `devBlockers`.