@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/hooks/validate-workflow-stop.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft workflow STOP validator — shared by Claude Code (SubagentStop) and Cursor (subagentStop).
+ * Ensures TA / Developer filled logs/<role>-log.md § Upstream Intake before subagent may stop.
+ *
+ * Exit 0 = pass
+ * Exit 2 = block (Claude: decision block; Cursor: block stop)
+ * stdout (Claude): {"decision":"block","reason":"..."} on failure
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+const INTAKE_HEADING = '## Upstream Intake';
+const PLAN_HEADING = {
+  'technical-artist': '## Production Plan',
+  developer: '## UI Pass Plan', // default; gameplay_pass uses ## Gameplay Pass Plan
+};
+const PLAN_HEADING_BY_STAGE = {
+  developer: {
+    ui_pass: '## UI Pass Plan',
+    ui_rework: '## UI Pass Plan',
+    gameplay_pass: '## Gameplay Pass Plan',
+  },
+};
+const PLAN_REQUIRED_SUBS = {
+  developer: {
+    ui_pass: ['### Scene-Asset Binding Plan', '### Scene navigation', '### Risk Checklist'],
+    ui_rework: ['### Scene-Asset Binding Plan', '### Scene navigation', '### Risk Checklist'],
+    gameplay_pass: ['### PGS Strategy', '### Risk Checklist'],
+  },
+  'technical-artist': ['### Coverage Plan', '### Atlas Assembly Plan', '### Risk Checklist'],
+};
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
+const MIN_TAKEAWAY_LEN = 8;
+
+const TA_REQUIRED_DOCS = [
+  'docs/project-state.md',
+  'docs/design-brief.md',
+  'docs/layout-spec.md',
+  'docs/atom-plan.json',
+  'docs/atom-plan.md',
+  'docs/style-exploration.md',
+  'logs/designer-log.md',
+];
+
+const DEV_REQUIRED_DOCS = [...TA_REQUIRED_DOCS, 'logs/ta-log.md'];
+
+const ROLE_LOG = {
+  'technical-artist': { log: 'logs/ta-log.md', docs: TA_REQUIRED_DOCS, label: 'Technical Artist' },
+  developer: { log: 'logs/developer-log.md', docs: DEV_REQUIRED_DOCS, label: 'Developer' },
+};
+
+/** @param {string} raw */
+function parseHookInput(raw) {
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string} s */
+function normalizeRole(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-');
+}
+
+/**
+ * @param {Record<string, unknown>} input
+ * @returns {'technical-artist' | 'developer' | null}
+ */
+function detectRole(input) {
+  const candidates = [
+    input.agent_type,
+    input.agent_name,
+    input.subagent_name,
+    input.subagent_type,
+    input.subagent,
+    input.role,
+  ].filter(Boolean);
+
+  for (const c of candidates) {
+    const n = normalizeRole(String(c));
+    if (n.includes('technical-artist') || n === 'ta') return 'technical-artist';
+    if (n === 'developer' || n === 'dev') return 'developer';
+  }
+
+  const blobs = [
+    input.last_assistant_message,
+    input.last_message,
+    input.message,
+    input.output,
+  ]
+    .filter((v) => typeof v === 'string')
+    .join('\n');
+
+  const stopMatch = blobs.match(/---\s*PLAYCRAFT_STOP\s*---[\s\S]*?role:\s*([^\s\n]+)/i);
+  if (stopMatch) {
+    const r = normalizeRole(stopMatch[1]);
+    if (r in ROLE_LOG) return /** @type {keyof ROLE_LOG} */ (r);
+  }
+
+  return null;
+}
+
+/** @param {string} cell */
+function isReadChecked(cell) {
+  const t = cell.trim();
+  if (/[✓✔☑]/.test(t)) return true;
+  if (/\[x\]/i.test(t)) return true;
+  if (/^(yes|done|true|read)$/i.test(t)) return true;
+  return false;
+}
+
+/**
+ * @param {string} content
+ * @returns {{ rows: { doc: string, read: string, takeaway: string }[], errors: string[] }}
+ */
+function parseUpstreamIntake(content) {
+  const errors = [];
+  const start = content.indexOf(INTAKE_HEADING);
+  if (start === -1) {
+    return { rows: [], errors: [`Missing "${INTAKE_HEADING}" section`] };
+  }
+
+  const after = content.slice(start + INTAKE_HEADING.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  const rows = [];
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Doc\s*\|/i.test(trimmed)) continue;
+
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+
+    if (parts.length < 3) continue;
+
+    const doc = parts[0].replace(/^`/, '').replace(/`$/, '').trim();
+    if (!doc.startsWith('docs/') && !doc.startsWith('logs/')) continue;
+
+    rows.push({ doc, read: parts[1], takeaway: parts[2] });
+  }
+
+  if (rows.length === 0) {
+    errors.push('Upstream Intake table has no data rows');
+  }
+
+  return { rows, errors };
+}
+
+/**
+ * @param {string} content
+ * @param {string[]} requiredDocs
+ */
+function validateIntakeContent(content, requiredDocs) {
+  const { rows, errors } = parseUpstreamIntake(content);
+  const byDoc = new Map(rows.map((r) => [r.doc, r]));
+
+  for (const doc of requiredDocs) {
+    const row = byDoc.get(doc);
+    if (!row) {
+      errors.push(`Missing row for ${doc}`);
+      continue;
+    }
+    if (!isReadChecked(row.read)) {
+      errors.push(`${doc}: mark Read column (✓) after reading`);
+    }
+    const takeaway = row.takeaway.trim();
+    if (!takeaway || PLACEHOLDER_RE.test(takeaway) || takeaway.length < MIN_TAKEAWAY_LEN) {
+      errors.push(`${doc}: add a concrete one-line takeaway (≥${MIN_TAKEAWAY_LEN} chars, no {{placeholders}})`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} content
+ * @param {'technical-artist' | 'developer'} role
+ * @param {string} [stage]
+ */
+function validatePlan(content, role, stage) {
+  let heading = PLAN_HEADING[role];
+  /** @type {string[]} */
+  let requiredSubs = [];
+
+  if (role === 'developer') {
+    if (stage && PLAN_HEADING_BY_STAGE.developer[stage]) {
+      heading = PLAN_HEADING_BY_STAGE.developer[stage];
+      requiredSubs = PLAN_REQUIRED_SUBS.developer[stage] ?? [];
+    }
+  } else if (role === 'technical-artist') {
+    requiredSubs = PLAN_REQUIRED_SUBS['technical-artist'] ?? [];
+  }
+
+  const errors = [];
+  const start = content.indexOf(heading);
+  if (start === -1) {
+    return [`Missing "${heading}" section — write plan before STOP (stage: ${stage || 'unknown'})`];
+  }
+
+  const after = content.slice(start + heading.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  for (const sub of requiredSubs) {
+    if (!section.includes(sub)) {
+      errors.push(`${heading}: missing ${sub}`);
+    }
+  }
+
+  const checkboxes = section.match(/- \[[ xX]\]/gi) || [];
+  const unchecked = checkboxes.filter((c) => /\[ \]/i.test(c));
+  if (checkboxes.length > 0 && unchecked.length > 0) {
+    errors.push(`${heading} Risk Checklist: ${unchecked.length} unchecked item(s)`);
+  }
+
+  if (PLACEHOLDER_RE.test(section)) {
+    errors.push(`${heading}: contains {{placeholders}} — fill with real data`);
+  }
+
+  return errors;
+}
+
+/** @param {string} projectDir */
+function readStage(projectDir) {
+  const statePath = path.join(projectDir, 'docs/project-state.md');
+  if (!fs.existsSync(statePath)) return null;
+  const content = fs.readFileSync(statePath, 'utf8');
+  const m =
+    content.match(/\*\*(ui_pass|ui_rework|gameplay_pass|production|pm)\*\*/i) ||
+    content.match(/stage[=:\s]+`(ui_pass|ui_rework|gameplay_pass|production|pm)`/i);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * @param {string} projectDir
+ * @param {'technical-artist' | 'developer'} role
+ */
+function validateRole(projectDir, role) {
+  const cfg = ROLE_LOG[role];
+  const logPath = path.join(projectDir, cfg.log);
+
+  if (!fs.existsSync(logPath)) {
+    return [
+      `${cfg.label}: create ${cfg.log} from templates/${path.basename(cfg.log).replace('.md', '.template.md')} and complete § Upstream Intake before STOP.`,
+    ];
+  }
+
+  const content = fs.readFileSync(logPath, 'utf8');
+  const intakeErrors = validateIntakeContent(content, cfg.docs);
+  const stage = role === 'developer' ? readStage(projectDir) : undefined;
+  const planErrors = validatePlan(content, role, stage ?? undefined);
+  return [...intakeErrors, ...planErrors];
+}
+
+/** @param {string} projectDir */
+function resolveProjectDir(projectDir) {
+  const statePath = path.join(projectDir, 'docs/project-state.md');
+  if (!fs.existsSync(statePath)) {
+    return { skip: true, reason: 'no docs/project-state.md' };
+  }
+  return { skip: false };
+}
+
+function emitBlock(reason) {
+  const payload = { decision: 'block', reason };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.stderr.write(`[playcraft-workflow-stop] ${reason}\n`);
+  process.exit(2);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export {
+  detectRole,
+  parseUpstreamIntake,
+  validateIntakeContent,
+  validatePlan,
+  validateRole,
+  readStage,
+  TA_REQUIRED_DOCS,
+  DEV_REQUIRED_DOCS,
+  PLAN_HEADING,
+  PLAN_REQUIRED_SUBS,
+};
+
+async function main() {
+  const stdin = await readStdin();
+  const input = parseHookInput(stdin);
+  const role = detectRole(input);
+
+  if (!role) {
+    process.exit(0);
+  }
+
+  const projectDir =
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CURSOR_PROJECT_DIR ||
+    process.cwd();
+
+  const { skip } = resolveProjectDir(projectDir);
+  if (skip) {
+    process.exit(0);
+  }
+
+  const errors = validateRole(projectDir, role);
+  if (errors.length > 0) {
+    const reason = `${ROLE_LOG[role].label} STOP blocked — fix logs/${role === 'technical-artist' ? 'ta' : 'developer'}-log.md § Upstream Intake:\n- ${errors.join('\n- ')}`;
+    emitBlock(reason);
+  }
+
+  process.exit(0);
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === __filename;
+
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`[playcraft-workflow-stop] validator error: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/project-template/.claude/settings.json

@@ -0,0 +1,36 @@
+{
+  "defaultMode": "acceptEdits",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "pm",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-atom-plan.mjs"
+            ],
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "technical-artist|developer",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-workflow-stop.mjs"
+            ],
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/project-template/.claude/settings.local.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "PlayCraft project template — local permission hints. Sub-agents PM/Designer must not use AskUserQuestion; gates are orchestrator-only. See docs/team/agent-conduct.md."
+}

package/project-template/.claude/skills/playcraft-ad-psychology/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: playcraft-ad-psychology
+description: 可玩广告心理设计指南。涵盖四大心理钩子（好奇心缺口/FOMO/即时满足/进度错觉）、60-30-10 色彩法则、CTA 设计规范、各阶段情感设计目标与常见错误。按游戏类型配色方案和音频情绪弧参数见 refs/designer-color-audio-recipes.md。
+triggers: 广告心理,ad psychology,钩子,hook设计,FOMO,近胜,near-win,CTA设计,色彩法则,60-30-10,颜色策略,配色方案,情感弧,emotional arc,安装率,CTR,转化率,EndCard设计,进度条设计,游戏广告设计
+---
+
+# 可玩广告心理设计完整指南
+
+## 0. 核心认知：优化目标是 CTR，不是游戏时长
+
+**最重要的一句话**：可玩广告的成功指标是**安装点击率（CTR > 3%）**，不是玩家在广告内的游戏时长或互动率。
+
+这意味着：
+
+- EndCard 不应该是"胜利满足感"，而应该是"还没玩够"
+- Tutorial 的目标不是让玩家学会玩，而是让玩家感到"我可以玩"
+- Gameplay 不需要公平，需要的是让玩家觉得"再给我一次机会"
+- 每一帧设计都要服务于最终的 CTA 点击
+
+---
+
+## 1. 四大心理钩子
+
+### 钩子 1：好奇心缺口（Curiosity Gap）
+
+**心理原理**：人脑对"未完成"状态有强烈的认知驱动——看到一个悬而未决的问题，大脑会持续寻求解答。
+
+**视觉设计指令**：
+
+- Near-Win 状态：关键元素差一步就能达成（最后一块砖、差 1 颗星、进度条 95%）
+- 不展示解法：只给出问题和"差一点"的状态，**不给解答**
+- 制造张力：用视觉聚焦（模糊背景、高亮关键元素）引导注意力到未解决点
+
+**Prompt 关键词**：`near win moment`, `almost there`, `one step away`, `progress bar at 95%`, `last piece missing`, `unresolved puzzle state`
+
+**错误做法**：在 Gameplay 帧展示"已解决"的完美状态（会消除好奇心，减少安装动机）
+
+---
+
+### 钩子 2：FOMO + 损失厌恶（Fear of Missing Out）
+
+**心理原理**：人对"失去"的感受比对"获得"的感受强 2 倍（Kahneman 损失厌恶理论）。
+
+**视觉设计指令**：
+
+- EndCard 展示"未拿到的奖励"：宝箱半开、金币散落地面、奖励图标模糊显示
+- 不展示胜利：不要"恭喜通关"、不要奖励动画播放完毕的满足状态
+- 制造"差一步就错过"感：宝箱即将关闭、计时器快到零、稀有道具即将消失
+
+**Prompt 关键词**：`treasure chest half open`, `rewards about to expire`, `coins scattered uncollected`, `rare item visible but unreachable`, `countdown almost zero`, `last chance visual`
+
+**EndCard 设计原则**：
+
+1. 主视觉 = 最有价值的游戏内奖励（大宝箱/稀有角色/大金币堆）
+2. 这些奖励处于"触手可及但尚未到手"的状态
+3. CTA 按钮 = 唯一能拿到这些奖励的路径
+
+---
+
+### 钩子 3：即时满足（Instant Gratification）
+
+**心理原理**：人类偏好立即的小奖励胜过未来的大奖励。Tutorial 阶段的核心任务是让玩家在 3-5 秒内体验到"做对了"的反馈。
+
+**视觉设计指令**：
+
+- Tutorial 帧必须"一眼看懂"：画面信息密度最低（只显示 1-2 个可交互元素）
+- 手势引导要大而清晰：手指点击图标 / 虚线箭头 / 高亮光圈，尺寸不小于元素的 1.5 倍
+- 交互结果要夸张：正确操作的视觉反馈（爆炸、星星、得分）要比实际游戏中更夸张
+- 色温略暖：相比 Hook 帧，Tutorial 帧整体色温偏暖，降低压迫感
+
+**Prompt 关键词**：`large finger tap indicator`, `glowing highlight around target`, `bright tutorial arrow`, `warm color temperature`, `simplified single element focus`, `satisfying immediate feedback animation`
+
+**Tutorial 禁忌**：
+
+- 不要出现文字说明（玩家不读广告里的文字）
+- 不要出现超过 3 个可交互元素（信息过载）
+- 不要让 Tutorial 让玩家失败（第一次操作必须成功）
+
+---
+
+### 钩子 4：进度错觉（Progress Illusion）
+
+**心理原理**：看到已完成的进度会激励继续完成，人们对"快完成了"比对"刚开始"更有动力。
+
+**视觉设计指令**：
+
+- 进度条设计在 75-90% 满格状态（而不是 0% 或 50%）
+- 血条/能量条接近满格但不满（如 85%）
+- 积分显示接近整数关卡（如 "980/1000" 而不是 "100/1000"）
+- 成就/收集类：显示"5/6 已收集"而不是"收集了 5 个"
+
+**Prompt 关键词**：`progress bar 80% full`, `health bar nearly complete`, `score counter almost at milestone`, `collection 5 of 6 complete`, `achievement nearly unlocked`
+
+---
+
+## 2. 各阶段情感设计目标
+
+| 阶段         | 时段   | 情感目标    | 关键视觉指标                       |
+| ------------ | ------ | ----------- | ---------------------------------- |
+| **Hook**     | 0–3s   | 震撼 + 好奇 | 最高对比度，最大动感，主视觉冲击   |
+| **Tutorial** | 3–10s  | 安全 + 自信 | 最低信息密度，暖色调，大手势图标   |
+| **Gameplay** | 10–25s | 沉浸 + 紧张 | 进度错觉，Near-Win，最高信息密度   |
+| **EndCard**  | 25–30s | 遗憾 + 渴望 | 奖励可见但未得，CTA 高对比，未竟感 |
+
+---
+
+## 3. 60-30-10 色彩法则（可玩广告版）
+
+### 三色分配
+
+```
+总画面配色 = 60% 主色（背景/场景） + 30% 辅色（游戏主元素） + 10% 强调色（CTA专用）
+```
+
+**"对比稀缺性"原则**：强调色（10%）只出现在 CTA 按钮上时，玩家视线会被自动吸引到 CTA——强调色越少出现在其他地方，CTA 的吸引力越强。
+
+**违规示例**：在游戏元素上大量使用橙色，然后 CTA 按钮也用橙色 → CTA 消失在视觉噪音中。
+
+**正确示例**：游戏用蓝绿主色调，只有 CTA 按钮使用金橙色 → CTA 一眼突出。
+
+## 4. CTA 设计规范
+
+### 尺寸与位置
+
+| 规范项       | 要求                       | 原因                             |
+| ------------ | -------------------------- | -------------------------------- |
+| 最小点击区域 | 48×48 px（设备物理像素）   | 手指触控目标尺寸，防止误触       |
+| 距屏幕边缘   | ≥ 48 px                    | 防止被平台 UI 遮挡，避免误触边框 |
+| 视觉建议尺寸 | 200–400 px 宽（9:16 屏幕） | 足够显眼但不干扰游戏区域         |
+| 位置         | 底部 1/4 区域，水平居中    | 符合拇指操作习惯                 |
+
+### 对比度规范
+
+CTA 按钮与其背景的对比度必须 **≥ 4.5:1**（WCAG AA 标准）。
+
+```
+常见合规组合（按钮色/背景色）：
+- 金橙 #F5A623 / 深蓝 #0D1B2A → 对比度 ~8.5:1 ✅
+- 纯白 #FFFFFF / 主色按钮 → 白色文字在深色按钮上 ✅
+- 鲜绿 #00C851 / 深灰 #222222 → 对比度 ~6.2:1 ✅
+- 浅黄 #FFFF99 / 白色背景 → 对比度 ~1.2:1 ❌（不合规）
+```
+
+快速验证工具：告诉 Designer 用 `playcraft tools research --query "color contrast checker [color1] vs [color2]"` 快速查询。
+
+### 文案优先级
+
+| 优先级    | 文案           | 适用场景                  |
+| --------- | -------------- | ------------------------- |
+| 1（最优） | `Play Now`     | 休闲/消除游戏（情感驱动） |
+| 2         | `Install Free` | 强调免费降低决策成本      |
+| 3         | `Download`     | 通用，略弱于上两者        |
+| 4（避免） | `Click Here`   | 无情感引导，降低 CTR      |
+
+**Google Ads 限制**：不可将 "Download" 或 "Install" 文字**直接叠加在图片上**（会被审核拒绝）。应将文案放在按钮内的独立颜色区域。
+
+### CTA 动画建议
+
+- 使用 `pulse` 动画（参考 `playcraft-vfx-animation` Skill）引导注意力
+- 脉冲频率：1.5-2 秒一次（过快令人烦躁，过慢不引人注意）
+- 第一次脉冲时机：EndCard 出现后 0.5 秒开始
+
+---
+
+## 5. 常见设计错误
+
+| 错误                       | 原因                                      | 正确做法                         |
+| -------------------------- | ----------------------------------------- | -------------------------------- |
+| EndCard 展示胜利/满足状态  | 消除了 FOMO，玩家觉得"看完了，不用下载了" | 展示"差一步"的遗憾状态           |
+| Tutorial 有文字说明        | 玩家不读广告文字                          | 用图形化引导（手势图标/箭头）    |
+| CTA 颜色与游戏主色相同     | 对比稀缺性失效，CTA 不显眼                | CTA 用画面中唯一一种高对比强调色 |
+| Gameplay 展示玩家失败      | 让玩家觉得游戏太难，不想下载              | 展示"即将成功"的 Near-Win 状态   |
+| Hook 超过 3 秒才出现主视觉 | 用户已划走                                | 0 帧就要高对比主视觉，无过渡铺垫 |
+| 信息密度全帧均等           | 视觉无重点，注意力分散                    | 每帧只有一个视觉焦点             |
+
+---
+
+## 6. 按游戏类型配色方案与音频情绪弧
+
+按游戏类型的配色方案（休闲消除、策略战争、益智解谜、RPG 奇幻，含 hex 值与情感定位）和完整音频情绪弧设计参数（BGM 各阶段 BPM、垂直重编排、SFX 时长标准、音频-视觉对齐检查清单）：
+
+详见 `refs/designer-color-audio-recipes.md`。