@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/docs/standards/iter1-agent-behavior-standards.md

@@ -0,0 +1,343 @@
+# Iteration 1 Agent Behavior Standards
+
+> 迭代1的 agent 行为评价标准。本文按 flow 拆,只写“这个 flow 下 agent 行为是否合格”的判断标准;详细执行步骤仍在 `docs/harness/iteration-1/*-flow.md`。
+
+## 迭代目标
+
+迭代1的目标是完成主核心玩法闭环:从用户初始意图收敛出核心玩法方向,把方向转成可派发的 todo 与 atom 复用上下文,逐个实现玩法子任务,并最终形成可 build、可自动演示、可验证、可录像的最小 playable。
+
+本迭代只评价核心玩法是否成立和运行时闭环是否可证明。不把包装、广告转化链路、最终视觉质量、复杂关卡扩展或生产级资产完整性纳入完成标准。
+
+## 全 flow 执行过程诊断
+
+以下评价点适用于迭代1所有 flow,不用在每个 flow 里重复展开。
+
+- 行为失败:是否出现工具/bash 等行为失败;失败后是否记录原因和下一步处理。
+- 参数错误:是否出现工具或命令参数用错;同一参数错误重复出现时,应视为执行质量问题。
+- 重试健康度:同一 verifier、tool 或写入动作多次未通过时,是否停止复盘,而不是继续硬跑。
+- 耗时异常:单个行为耗时明显过长时,是否产生了相称的信息、产物或证据。
+- 时间分布:read、update/edit、工具调用、验证、用户等待大致各花了多久。
+- 上下文准备时长:从 dispatch 到“已读完必要上下文,可以开始产出”花了多久。
+- 记录要求:失败、重复重试和明显耗时异常应进入 handoff / run notes,供调度者判断继续、重派或修改 flow。
+
+## 迭代调度者工作预期
+
+以下评价点适用于迭代1所有 flow,不用在每个 flow 里重复展开。
+
+- 能识别 active dispatch / pending user input / todo pool / stage exit,不重复派发或跳过未完成工单。
+- 负责把当前 stage 目标收窄成 dispatch,不替 subagent 产出 design、todo、code 或 review verdict。
+- relay 用户输入时保留原问题、选项、推荐项和影响说明,不自行扩写设计内容。
+- 根据 handoff、artifact 和 verifier 结果更新 todo / gate / stage,不从口头总结直接推进。
+- blocker、failed evidence 或执行诊断异常出现时,能暂停、重派或改 flow,而不是硬推进。
+
+## ideate
+
+Flow 目标:
+
+- 把用户需求收敛成核心玩法方向。
+- 本阶段只评价核心玩法是否清楚,不评价实现计划、包装、视觉终稿或 CTA (Call To Action, 行动召唤)。
+
+skill/文档引用:
+
+- `docs/harness/iteration-1/ideate-flow.md` 必读
+- brainstorming - 需加载
+- playcraft-skill-recommender - 需加载
+- `.claude/agents/refs/game-designer-gameplay-sufficiency.md` - 需阅读
+- `.claude/agents/refs/atom-skill-library.md` - 需阅读
+
+派发信息评价:
+
+- role 必须是 `game-designer`。
+- `requiredContext` 至少包含 ideate flow、用户原始需求和预期产物路径。
+- 用户意图应原语义转发,不能被调度者润色成新的玩法结论。
+- guidance 只写本阶段边界和验收信号,不重复 flow 的完整步骤,也不外行指导 designer 如何逐句思考。
+- forbiddenTasks 明确禁止实现、技术选型、包装、CTA、视觉终稿和复杂关卡展开。
+
+预期流程:
+
+- 先 `state:get -- --json dispatch`,确认自己是 active workticket 的 `game-designer`。
+- 先做 web research 与 skill library exploration,并把发现以来源标记沉淀到 brief。
+- skill exploration 体现 gettags / filter / match / role / keyword 等分层探索,必要时读强相关 atom,不是一次 match 后直接下结论。
+- brainstorm 先自答研究已能决定的问题,再批量提出可选择、可比较、带推荐和影响说明的问题。
+- 需要用户输入时写 `pendingUserInput` 并暂停,交给 orchestrator relay;中途 answer 不等于最终 user-confirm。
+- 写 `docs/design.md` 前完成 gameplay sufficiency 自检,有不通过项时回到定点补充。
+- 最后由 orchestrator 向用户确认核心玩法方向,确认后才能视为 ideate 可退出。
+
+不符合预期的流程:
+
+- brief 是事后总结,看不到探索路径。
+- design 写成实现方案或素材方案。
+- 中途用户回答被当成最终 user-confirm。
+- 玩法结论和用户输入语义不一致,且没有记录取舍原因。
+- 重复问用户相似问题、或选项不可比较,视为 brainstorm 质量问题。
+- 在未完成自检或未处理用户输入前写 design,视为流程跳步。
+- discovery 长时间无有效发现时,应记录 no-match / low-confidence 与下一步选择。
+
+产物评价引用:
+
+- `docs/standards/artifacts/design-brief.md`
+- `docs/standards/artifacts/design.md`
+
+本 flow 额外产物边界:
+
+- `docs/design.md` 只写核心玩法体验:玩家目标、单次操作、系统反馈、下一次决策、最简成功失败。
+- 允许写玩法完整性需要的最小规则和反馈,但不写 runtime 文件、类名、函数签名、事件 payload、engine 初始化。
+- 迭代1不应展开包装、广告话术、复杂关卡细节、最终视觉风格或后续商业转化链路。
+
+State / Handoff 评价:
+
+- `pendingUserInput` 的 id、prompt、options、recommended、impact 足够让 orchestrator 原样 relay。
+- 用户回答被写回 brief 后,当前 pending input 应被 resolved。
+- 最终退出前 handoff 引用 `docs/design-brief.md` 和 `docs/design.md`,并说明是否已等待最终用户确认。
+
+## context
+
+Flow 目标:
+
+- 把已确认的核心玩法转成 generate 可使用的计划等价物:atom-tree、todo_list 和机器态 todo 池。
+- 本阶段锁定引擎与核心动作,为每个玩法子任务建立可派发、可验证、可复用的任务卡。
+
+skill/文档引用:
+
+- `docs/harness/iteration-1/context-flow.md` 必读
+- playcraft-skill-recommender - 需加载
+- `.claude/agents/refs/atom-skill-library.md` - 需阅读
+- `docs/design.md` - 需阅读
+
+派发信息评价:
+
+- role 必须是 `game-designer`,并明确本阶段允许写 todo。
+- flow必须正确是 `docs/harness/iteration-1/context-flow.md`
+
+预期流程:
+
+- 从 design 和 brief 提取 intent,使用 recommender 生成或刷新 `docs/atom-tree.json`。
+- 生成/刷新 atomtree 的时候是使用了desine里面披露的关键字或者关键atom作为起点的
+- 选择 atom 时区分轻量筛选与强相关深读;强相关 atom 的 `ref/` 源是 API (Application Programming Interface, 应用程序编程接口) / event / config 的权威。
+- 根据 tags、DESC 语义、复用程度、依赖完整性和玩法实体/机制层差异进行评分筛选。
+- 玩法相关性是其选择的第一原因，其次才是引擎。引擎不一致就一定是 ref 等级 1
+- 递归补齐依赖,完成 selected atoms 与 link,再把复用结论落到任务卡。
+- 在 generate 前锁定 engine 和 coreAction;锁定后不应在 generate 阶段临时更换。
+- todo 拆分按玩家可感知玩法子任务,每个任务卡都能独立派发、独立验收。
+- todo 不应该过分大也不应该过分小
+- 能把 design intent 转成可执行 contract,而不是把设计文档改写成开发口号。
+- 能区分“atom 可复用”“仅作参考”“不适用”,并记录原因。
+- 拆 todo 不遗漏单玩法、多玩法衔接、最简成功失败这些迭代1核心范围。
+- 不把 context 做成代码设计细节堆叠,也不把 acceptance 写成主观愿望。
+
+不符合预期的流程:
+
+- recommender 命令失败、选择校验失败、link 失败后没有记录失败原因和是否可恢复。
+- 多次 filter / match 没有强相关结果,仍不记录 low-confidence、从零实现或 design-only 的理由。
+- 花大量时间深读无关 atom ref,但没有形成任务卡复用约束。
+- todo 池只有摘要,没有任务卡全文/任务卡全文过于详细
+- dispatch 只能手抄上下文,无法回链 `docs/todo_list.md#todo-<id>`。
+- atom 选择与设计意图脱节,或只选 engine skeleton 忽略玩法/输入/反馈层。
+- 拆 todo 时加入未确认玩法或后续迭代包装内容。
+- `docs/atom-tree.json` 缺失且未说明原因。
+- todo 池未覆盖本迭代所有玩法子任务,或 todo acceptance 不可验证。
+
+产物评价引用:
+
+- `docs/standards/artifacts/todo-list.md`
+
+本 flow 额外产物边界:
+
+- `docs/todo_list.md` 是 generate 的 plan source,不是普通备忘录。
+- todo 可包含必要的 asset binding 约束,但不生产最终资产、不展开视觉终稿。
+- 本阶段应该只聚焦核心的玩法而不是制作完整的游戏，需评价其是否有聚焦玩法核心
+
+State / Handoff 评价:
+
+- 机器态 todo 池非空,且每个 todo 的 `requiredContext` 指向同名任务卡锚点。
+- shared decisions 写入 engine 和 coreAction 时,应有 skill match 或 design evidence 支撑。
+- handoff 引用 atom-tree、todo_list,并说明 todo seed 数量、覆盖范围和无法覆盖的缺口。
+
+## generate
+
+Flow 目标:
+
+- 按 todo 池逐个实现核心玩法闭环。
+- 每个 dispatch 只完成当前 todo 的 acceptance;本阶段结束前当前 iteration todo 必须清空。
+
+skill/文档引用:
+
+- `docs/harness/iteration-1/generate-flow.md` 必读
+- playcraft-skill-recommender - 需要确认 atom/ref/scaffold 使用方式时加载
+- 当前 dispatch 的 `docs/todo_list.md#todo-<id>` - 必读
+- 任务卡指向的 `docs/design.md` 章节和 atom `SKILL.md` / `ref/` 源 - 必读
+
+派发信息评价:
+
+- role 必须是 `developer`,且一次只派一个 todo。
+- dispatch 继承或显式提供 goal、acceptance、allowedFiles、forbiddenTasks、requiredContext、verifier。
+- `requiredContext` 必须包含对应任务卡全文锚点,不能只给 todo 摘要。
+- allowedFiles 收窄到当前 todo 需要的 runtime 文件
+
+预期流程:
+
+- developer 先确认 dispatch,再读任务卡全文、设计章节、现有代码和相关 atom ref。
+- 改动前列清将改文件并确认在 allowedFiles 内;缺合约或意图不清时停止写 blocker。
+- 实现只闭合当前 acceptance,不顺手做未来任务或重写整个项目。
+- 复用 atom 时遵守 ref 源里的真实 API、event、config 和 asset binding。
+- 不会认为ref等级1就完全没价值，还是会去了解其实现
+- 对于参考atom里面的参数、配置需比较敏感，这些是质量保证的重点
+- 写代码时候会先了解当前的实现
+- 不会无脑加代码，会斟酌考虑框架 & 健壮性
+- 写完之后会验证，而不是直接宣告做完了
+- 本地验证使用 dispatch 指定 verifier;done 只能来自验证结果和 artifact,不是总结。
+- STOP 时 append handoff,由 orchestrator 判断 todo done / failed / retry。
+- 不改写 `docs/design.md` 已确认的玩家体验。
+- 不为通过脚本 fake success;玩家可见闭环必须实际可达。
+- 能把失败归类为实现 bug、设计缺口、资产缺口或环境问题,并在 handoff 中说明。
+- 发现本阶段明显漏拆 todo 时,只在被授权范围内补 generate todo,不加后续迭代工作。
+
+不符合预期的流程:
+
+- 一次 dispatch 做多个 todo。
+- 从 dispatch 摘要猜任务,未读任务卡全文。
+- 同一 verifier 多次失败后继续无差别改代码,没有复盘失败 key。
+- 参数错误、allowedFiles 越界、未读任务卡就修改。
+- read 阶段明显不足导致返工,但没有记录缺失上下文并补读。
+- build 通过但核心玩家路径不可达。
+- 为通过脚本 fake success,或改写已确认设计语义。
+- 越过 design / allowedFiles / forbiddenTasks。
+- 当前 iteration todo 仍有 pending / in_progress / failed 时推进到 optimize。
+- done todo 没有 verifier 或运行时证据。
+- 不会读了一堆代码之后写的完全没关系
+- 不应该执行了scaffold之后却在重新写代码
+
+产物评价引用:
+
+- `docs/standards/artifacts/game-code.md`
+
+本 flow 额外产物边界:
+
+- `game/**` 应呈现核心玩法 runtime loop,可以使用 placeholder / minimal visual 支撑验证。
+- 不要求最终视觉质量、商业包装、广告 CTA 或完整关卡内容。
+- 多玩法项目应至少让各玩法子任务的核心路径都可被验证。
+
+State / Handoff 评价:
+
+- developer 不自行 `todo:set`,不清 dispatch,不推进 stage。
+- handoff 包含改动文件、acceptanceResults、verifier 结果、artifactRefs 或 blockers。
+- orchestrator 根据 handoff 和 verifier 更新 todo 状态,直到当前 iteration todo 全部 done。
+
+## optimize
+
+Flow 目标:
+
+- 把 generate 产出的 game 收敛成可自动演示、可验证、可录像的交付物。
+- 本阶段聚焦运行时和视频闭环,不修改已确认核心玩法。
+
+skill/文档引用:
+
+- `docs/harness/iteration-1/optimize-flow.md` 必读
+- `.claude/agents/developer.md` 必读
+- playable-record - 需加载
+- playable-debug - first win / autoplay 排障时加载
+- playable-validate - 需要 runtime / video validation loop 时加载
+- `skills/_shared/scripts/pipeline/dod-config.mjs` - 需阅读
+
+派发信息评价:
+
+- 默认 role 是 `developer`;DoD (Definition of Done, 完成定义) 失败需要路由时,根据 failure key 和 owner 重新派发。
+- dispatch 明确本次修复哪个 DoD key 或验证缺口。
+- `requiredContext` 包含 optimize flow、失败报告、相关 game 文件和运行时/录像 skill。
+- forbiddenTasks 禁止重做玩法设计、扩大视觉包装、把 debug workaround 当交付结果。
+
+预期流程:
+
+- 先 build 并修复报错,再接入/验证 `window.__playable` runtime contract。
+- autoplay 必须能自动跑完整核心闭环并到达 ENDCARD,不能靠人工操作补齐。
+- 依次运行 contract、first win、fusion 等验证;fusion 无适用对象时应明确 no-op。
+- 录像使用 `record:mp4` headed 60fps 路径,产出 MP4 (MPEG-4 Part 14, 数字多媒体容器格式) 证据。
+- 需要语义视频评审时使用 VLM (Vision-Language Model, 视觉语言模型) video verifier,并保留结果路径。
+- DoD 收尾以 `dod:check` 或等价 evidence package 为准;无脚本 DoD 需要 orchestrator 明确确认。
+- 能按失败 key 定位:build、contract、firstLevelWin、fusion、autoplay、record。
+- 修复优先恢复 runtime contract 和状态可达性,不是只让录像脚本不报错。
+- 不把自动演示改成绕过核心玩法的直达成功。
+- handoff 逐项报告 pass/fail、artifactRefs 和 remaining blockers。
+
+不符合预期的流程:
+
+- 跳过 autoplay 直接人工录屏。
+- build、contract 或 first win 失败仍标 DoD 通过。
+- 录像存在但没有核心玩法过程。
+- 为了 first win 直接跳到 ENDCARD。
+- 录制失败后不先检查 contract / first win,而是连续重复 record。
+- build 报错、端口占用、浏览器安装、ffmpeg 缺失等环境问题和代码问题混在一起。
+- verify 参数多次用错或同一失败 key 多轮无进展,仍不暂停重派或改 flow。
+- 新增玩法、重写设计、补广告包装或做最终视觉质量环。
+- MP4 缺失,或 handoff / validate 路径无法证明录像对应当前版本。
+
+产物评价引用:
+
+- `docs/standards/artifacts/game-code.md`
+- `docs/standards/artifacts/recording-evidence.md`
+
+本 flow 额外产物边界:
+
+- 可接受优化是验证闭环、自动演示、稳定录制和小范围 bug fix。
+- 不接受在 optimize 阶段新增玩法、重写设计、补广告包装或做最终视觉质量环。
+
+State / Handoff 评价:
+
+- 有脚本 DoD 由验证结果写入;autoplay 这类无脚本 DoD 由 orchestrator 基于证据显式确认。
+- failed DoD 不应被手动改成 passed;需先修复并重跑或记录 blocker。
+- handoff 应说明各 DoD key 的状态,并引用 `validate/**` 与 `recordings/*.mp4`。
+
+## wrapup
+
+Flow 目标:
+
+- 回收迭代1运行态副作用,刷新项目入口文档,让后续 agent 看到真实工程状态。
+- 本 flow 不派发角色;由 orchestrator / 脚本执行。
+
+skill/文档引用:
+
+- `docs/harness/iteration-1/wrapup-flow.md` 必读
+- `docs/harness/orchestrator-flow.md` 必读
+- `package.json` - 需阅读
+- `npm run state:get` 输出 - 需阅读
+- 当前目录中的关键产物与 runtime 入口 - 需核对
+
+派发信息评价:
+
+- 本 flow 无 subagent dispatch;如果出现角色派发,应能解释为什么 flow 目标已被扩展,否则视为越界。
+- 不应把 wrapup 写成 reviewer 或 developer 的新工作票。
+
+预期流程:
+
+- 检查并回收 dev server、record 进程、临时端口占用和不需要留存的临时产物。
+- 保留交付证据,不删除本迭代验证所需 MP4 / validate artifact。
+- 刷新 `CLAUDE.md` 时只写当前工程事实:包命令、入口、状态与设计产物、目录地图、全员边界、关键缺口。
+- `CLAUDE.md` 不复制调度剧本、完整 todo 池、handoff 历史、未来迭代细节或 role card 全文。
+- orchestrator 以事实核对为主,不借 wrapup 修改设计、代码或验证结论。
+- 能区分“入口速览应记录的稳定事实”和“state/handoff 才该承载的运行态细节”。
+- 如果发现 todo 未清空或 DoD 未通过,应阻塞推进而不是把缺口写进 CLAUDE 后继续。
+
+不符合预期的流程:
+
+- `CLAUDE.md` 写成流程手册或状态历史。
+- 删除了需要保留的录像/验证证据。
+- todo 或 DoD 未完成仍推进阶段。
+- 清理操作耗时异常时,没有说明卡在端口、进程、文件还是验证产物判定。
+- 更新 `CLAUDE.md` 前未覆盖 package、入口、state、关键产物和目录地图,导致事实错误。
+- 执行破坏性交付证据的清理。
+- 仍有悬挂 dev / record 进程且没有明确不可清理原因。
+
+产物评价引用:
+
+- 暂无独立 artifact 标准;按 wrapup flow 的入口卡片规则评价 `CLAUDE.md`。
+
+本 flow 额外产物边界:
+
+- `CLAUDE.md` 是项目速览,不是第二份 pipeline spec。
+- 只刷新当前目录事实和少量关键缺口;不要写过程回忆录。
+
+State / Handoff 评价:
+
+- 进入下一迭代前,当前 iteration todo 必须全部 done。
+- wrapup 完成后 stage advance 应通过 `todosCleared` 等硬门槛。
+- 如仍有悬挂进程、未清理资源或文档事实不一致,不得推进。

package/project-template-v2/game/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Placeholder until `playcraft remix init-template` applies an engine pack.
+ * Safe to replace — see game/.playcraft-scaffold-pending
+ */
+
+export function startGame(parentId: string): { destroy?: (removeCanvas?: boolean) => void } {
+  const parent = document.getElementById(parentId);
+  const message = 'Engine not scaffolded. Run: playcraft remix init-template --from-atom-tree';
+  if (parent) {
+    parent.innerHTML = `<p style="font-family:system-ui,sans-serif;padding:2rem;color:#888">${message}</p>`;
+  }
+  console.warn(`[playcraft] ${message}`);
+  return {
+    destroy() {
+      if (parent) parent.innerHTML = '';
+    },
+  };
+}

package/project-template-v2/globals.d.ts

@@ -0,0 +1,51 @@
+declare module "*.png" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.webp" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.jpg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.jpeg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.svg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.gif" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.mp3" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.ogg" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.wav" {
+  const src: string;
+  export default src;
+}
+
+declare module "*.m4a" {
+  const src: string;
+  export default src;
+}
+
+declare const __DEV__: boolean;

package/project-template-v2/index.css

@@ -0,0 +1,34 @@
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+  -webkit-tap-highlight-color: transparent;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: #000;
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+  overscroll-behavior: none;
+  touch-action: none;
+}
+
+#game-container {
+  width: 100%;
+  height: 100%;
+  padding-top: env(safe-area-inset-top);
+  padding-right: env(safe-area-inset-right);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+}
+
+canvas {
+  display: block;
+}

package/project-template-v2/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
+    />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <meta name="format-detection" content="telephone=no" />
+    <title>PlayCraft Playable</title>
+  </head>
+  <body>
+    <div id="game-container"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/project-template-v2/main.ts

@@ -0,0 +1,9 @@
+import "./index.css";
+import { startGame } from "./game/index";
+
+let game = startGame("game-container");
+
+window.addEventListener("resize", () => {
+  game.destroy?.(true);
+  game = startGame("game-container");
+});

package/project-template-v2/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "playcraft-game",
+  "version": "0.1.0",
+  "playcraftTemplateVersion": "0.4.0-alpha.0",
+  "description": "PlayCraft Playable Ads project",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "state:get": "node skills/_shared/scripts/state-get.mjs --root=.",
+    "state:set": "node skills/_shared/scripts/state-set.mjs --root=.",
+    "stage:advance": "node skills/_shared/scripts/state-advance-stage.mjs --root=.",
+    "todo:add": "node skills/_shared/scripts/todo-add.mjs --root=.",
+    "todo:get": "node skills/_shared/scripts/todo-get.mjs --root=.",
+    "todo:remove": "node skills/_shared/scripts/todo-remove.mjs --root=.",
+    "todo:set": "node skills/_shared/scripts/todo-set.mjs --root=.",
+    "dispatch:set": "node skills/_shared/scripts/dispatch-set.mjs --root=.",
+    "dispatch:clear": "node skills/_shared/scripts/dispatch-clear.mjs --root=.",
+    "handoff:append": "node skills/_shared/scripts/handoff-append.mjs --root=.",
+    "dod:check": "node skills/_shared/scripts/dod-check.mjs --root=.",
+    "verify:env": "node skills/_shared/scripts/verify-env.mjs --root=.",
+    "verify:contract": "node skills/playable-record/scripts/verify-contract.mjs --root=. --use-dev",
+    "verify:lifecycle": "node skills/playable-record/scripts/verify-lifecycle.mjs --root=. --use-dev",
+    "verify:firstwin": "node skills/playable-record/scripts/verify-firstwin.mjs --root=. --use-dev",
+    "verify:fusion": "node skills/playable-record/scripts/verify-fusion.mjs --root=.",
+    "verify:vlm-video": "node skills/playable-record/scripts/verify-vlm-video.mjs --root=.",
+    "verify:placeholders": "node skills/_shared/scripts/verify-placeholders.mjs --root=.",
+    "verify:asset-sync": "node skills/_shared/scripts/verify-asset-code-sync.mjs --root=.",
+    "verify:runtime-contract": "node skills/playable-verify-ui/scripts/verify_runtime_contract.js --root=.",
+    "verify:hardcoded-layout": "node skills/playable-verify-ui/scripts/verify_hardcoded_layout.js",
+    "record:mp4": "node skills/playable-record/scripts/record-playable.mjs --root=. --use-dev",
+    "record:mp4:install": "playwright install chromium"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.19.8",
+    "playwright": "^1.59.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.3"
+  }
+}

package/project-template-v2/skills/_shared/scripts/dispatch-clear.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * dispatch:clear — clear the current subagent workticket.
+ *
+ * Usage:
+ *   npm run dispatch:clear
+ */
+
+import { resolve } from 'node:path';
+import { clearDispatch } from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd() };
+  for (const arg of argv) {
+    if (arg === '--') continue;
+    if (arg.startsWith('--root=')) { opts.root = arg.slice('--root='.length); continue; }
+    if (arg === '--help' || arg === '-h') {
+      console.log('Usage: dispatch-clear.mjs [--root=.]');
+      process.exit(0);
+    }
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  clearDispatch(resolve(opts.root));
+  console.log('[dispatch:clear] dispatch cleared');
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/dispatch-set.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * dispatch:set — replace the current subagent workticket.
+ *
+ * Usage:
+ *   npm run dispatch:set -- id=core-action-v1 role=developer goal="..." \
+ *     allowedFiles="game/**" acceptance="feedback visible;progress+1" --mark-todo
+ *   npm run dispatch:set -- id=stage:ideate role=game-designer goal="lock core gameplay"
+ */
+
+import { resolve } from 'node:path';
+import { readState, setDispatch, setDispatchAndMarkTodoState } from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), kv: {}, markTodo: false };
+  for (const arg of argv) {
+    if (arg === '--') continue;
+    if (arg.startsWith('--root=')) { opts.root = arg.slice('--root='.length); continue; }
+    if (arg === '--mark-todo') { opts.markTodo = true; continue; }
+    if (arg === '--help' || arg === '-h') {
+      console.log('Usage: dispatch-set.mjs [--root=.] id=<todo-or-stage-id> role=<role> goal="..." [guidance="..."] [skillHints="a;b"] [requiredContext="a;b"] [contextReuse="<key-or-note>"] [allowedFiles="a;b"] [forbiddenTasks="a;b"] [acceptance="a;b"] [verifier="..."] [--mark-todo]');
+      process.exit(0);
+    }
+    const m = arg.match(/^([a-zA-Z0-9_]+)=([\s\S]*)$/);
+    if (m) opts.kv[m[1]] = m[2];
+  }
+  return opts;
+}
+
+function isRealTodoId(id) {
+  return id && id !== 'none' && !id.startsWith('stage:');
+}
+
+function hasKv(kv, key) {
+  return Object.prototype.hasOwnProperty.call(kv, key);
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = resolve(opts.root);
+  const id = opts.kv.id || opts.kv.activeTodoId;
+
+  if (!id) { console.error('[dispatch:set] id= is required'); process.exit(1); }
+
+  const currentState = readState(root);
+  const todo = isRealTodoId(id)
+    ? currentState.todos.find((t) => t.id === id && t.iteration === currentState.pipeline.iteration)
+      ?? currentState.todos.find((t) => t.id === id)
+    : null;
+
+  const role = opts.kv.role || todo?.role;
+  if (!role) { console.error('[dispatch:set] role= is required'); process.exit(1); }
+
+  const dispatch = {
+    activeTodoId: id,
+    role,
+    goal: hasKv(opts.kv, 'goal') ? opts.kv.goal : todo?.goal || todo?.title || '',
+    guidance: hasKv(opts.kv, 'guidance') ? opts.kv.guidance : '',
+    skillHints: hasKv(opts.kv, 'skillHints') ? opts.kv.skillHints : [],
+    requiredContext: hasKv(opts.kv, 'requiredContext') ? opts.kv.requiredContext : todo?.requiredContext || [],
+    contextReuse: hasKv(opts.kv, 'contextReuse')
+      ? opts.kv.contextReuse
+      : opts.kv.contextReuseKey || todo?.contextReuse || '',
+    allowedFiles: hasKv(opts.kv, 'allowedFiles') ? opts.kv.allowedFiles : [],
+    forbiddenTasks: hasKv(opts.kv, 'forbiddenTasks') ? opts.kv.forbiddenTasks : [],
+    acceptance: hasKv(opts.kv, 'acceptance') ? opts.kv.acceptance : todo?.acceptance || [],
+    verifier: hasKv(opts.kv, 'verifier') ? opts.kv.verifier : todo?.verifier || '',
+  };
+
+  let state;
+  if (opts.markTodo && isRealTodoId(id)) {
+    try {
+      state = setDispatchAndMarkTodoState(root, dispatch, id, { status: 'in_progress' });
+    } catch (error) {
+      console.error(`[dispatch:set] failed to write dispatch and mark todo in_progress: ${error.message}`);
+      process.exit(2);
+    }
+  } else {
+    state = setDispatch(root, dispatch);
+  }
+
+  console.log(`[dispatch:set] ${state.dispatch.activeTodoId} → role=${state.dispatch.role}`);
+  if (opts.markTodo && isRealTodoId(id)) console.log(`  todo ${id}: status=in_progress`);
+}
+
+main();