@playcraft/cli 0.1.54 → 0.1.56-beta

package/project-template-v2/skills/_shared/scripts/dod-check.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * DoD 检查执行器 — 跑当前 pipeline stage 所有有 script 绑定的 DoD key。
+ *
+ * 用法：
+ *   npm run dod:check
+ *   node skills/_shared/scripts/dod-check.mjs --root=. [--json] [--key=build,contract]
+ *
+ * 行为：
+ *   1. 读当前 state → 得到 iteration + stage
+ *   2. 从 dod-config 拿该阶段的 key 列表
+ *   3. 对每个有 script 的 key 执行 npm run <script>
+ *   4. 把结果（pass/fail）写回 gate.stageDoD
+ *   5. 输出汇总：哪些通过、哪些失败、失败路由给谁
+ *
+ * Exit 0 = 全部通过（或无可执行 key）
+ * Exit 2 = 至少一个 key 失败
+ */
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { resolve } from 'node:path';
+import {
+  readState,
+  applyStateUpdates,
+  stateExists,
+} from './state-store.mjs';
+import {
+  dodKeysForStage,
+  dodDefinition,
+  scriptForDoDKey,
+  routeForFailedDoDKeys,
+} from './pipeline/index.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false, keys: null };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      opts.root = resolve(arg.slice('--root='.length));
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg.startsWith('--key=')) {
+      opts.keys = arg.slice('--key='.length).split(',').map((k) => k.trim()).filter(Boolean);
+    } else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: dod-check.mjs [--root=.] [--json] [--key=build,contract]');
+      console.log('Runs DoD script verifiers for the current pipeline stage and writes results to gate.stageDoD.');
+      process.exit(0);
+    }
+  }
+  return opts;
+}
+
+function runScript(root, script) {
+  const result = spawnSync('npm', ['run', script, '--'], {
+    cwd: root,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return {
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (!stateExists(opts.root)) {
+    console.error('[dod:check] Missing docs/project-state.json — run npm run ensure:project');
+    process.exit(1);
+  }
+
+  const state = readState(opts.root);
+  const { iteration, stage } = state.pipeline;
+
+  const allKeys = dodKeysForStage(iteration, stage);
+  if (!allKeys.length) {
+    console.log(`[dod:check] No DoD keys defined for iteration=${iteration} stage=${stage}`);
+    process.exit(0);
+  }
+
+  // 支持 --key 过滤（只跑指定 key）
+  const keys = opts.keys ? allKeys.filter((k) => opts.keys.includes(k)) : allKeys;
+
+  const results = {};
+  const passed = [];
+  const failed = [];
+  const skipped = []; // 无 script 的 key（需人工确认）
+
+  for (const key of keys) {
+    const def = dodDefinition(key);
+    const script = scriptForDoDKey(key);
+
+    if (!script) {
+      skipped.push(key);
+      if (!opts.json) console.log(`  ⊘  ${key} — 无脚本，需人工确认（${def?.label ?? key}）`);
+      continue;
+    }
+
+    if (!opts.json) process.stdout.write(`  ▷  ${key} (npm run ${script}) ... `);
+
+    const { exitCode, stdout, stderr } = runScript(opts.root, script);
+    const ok = exitCode === 0;
+    results[key] = ok ? 'passed' : 'failed';
+
+    if (ok) {
+      passed.push(key);
+      if (!opts.json) console.log('✓ pass');
+    } else {
+      failed.push(key);
+      if (!opts.json) {
+        console.log('✗ fail');
+        if (stderr.trim()) console.error(`     stderr: ${stderr.trim().split('\n')[0]}`);
+      }
+    }
+  }
+
+  // 写回 gate.stageDoD（合并，不覆盖已有结果）
+  const existingDoD = state.gate?.stageDoD ?? {};
+  const newDoD = { ...existingDoD, ...results };
+  applyStateUpdates(opts.root, { gatePatch: JSON.stringify({ stageDoD: newDoD }) });
+
+  // 输出汇总
+  const failRoute = failed.length ? routeForFailedDoDKeys(failed) : null;
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      iteration,
+      stage,
+      keys,
+      passed,
+      failed,
+      skipped,
+      failRoute,
+    }, null, 2));
+  } else {
+    console.log(`\n[dod:check] iteration=${iteration} stage=${stage}`);
+    if (passed.length) console.log(`  ✓ passed: ${passed.join(', ')}`);
+    if (skipped.length) console.log(`  ⊘ skipped (manual): ${skipped.join(', ')}`);
+    if (failed.length) {
+      console.log(`  ✗ failed: ${failed.join(', ')}`);
+      console.log(`  → routeTo: ${failRoute.routeTo}`);
+      console.log(`  → nextAction: ${failRoute.nextAction}`);
+    } else if (!skipped.length) {
+      console.log('  All DoD checks passed.');
+    }
+  }
+
+  process.exit(failed.length > 0 ? 2 : 0);
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/handoff-append.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * handoff:append — append one entry to handoff.history. Pipeline v2.
+ *
+ * Called by subagent at STOP to record what it did. The entry is appended
+ * with an auto-incremented seq; iteration and stage are read from current
+ * pipeline state and need not be passed.
+ *
+ * Usage:
+ *   npm run handoff:append -- role=developer summary="tap feedback done" artifactRefs="game/scene.ts"
+ *   npm run handoff:append -- role=developer summary="..." artifactRefs="a.ts;b.ts" blockers=""
+ *   npm run handoff:append -- role=game-designer status=awaiting_user_input \
+ *     summary="Needs user input" pendingUserInput='{"status":"awaiting_user_input","id":"q-core-loop-1","prompt":"..."}'
+ */
+import { resolve } from 'node:path';
+import { appendHandoff } from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), kv: {} };
+  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: handoff-append.mjs [--root=.] role=<role> summary="..." [status=completed|awaiting_user_input] [artifactRefs="a;b"] [blockers=""] [pendingUserInput=\'{"status":"awaiting_user_input","id":"...","prompt":"...","options":[...]}\' ]');
+      process.exit(0);
+    }
+    const m = arg.match(/^([a-zA-Z0-9_]+)=([\s\S]*)$/);
+    if (m) opts.kv[m[1]] = m[2];
+  }
+  return opts;
+}
+
+function parseJsonObject(raw, key) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not object');
+    return parsed;
+  } catch {
+    console.error(`[handoff:append] ${key} must be a JSON object`);
+    process.exit(1);
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = resolve(opts.root);
+  if (!opts.kv.role) { console.error('[handoff:append] role= is required'); process.exit(1); }
+  if (!opts.kv.summary) { console.error('[handoff:append] summary= is required'); process.exit(1); }
+
+  const state = appendHandoff(root, {
+    role: opts.kv.role,
+    status: opts.kv.status,
+    summary: opts.kv.summary,
+    artifactRefs: opts.kv.artifactRefs ?? '',
+    blockers: opts.kv.blockers ?? '',
+    pendingUserInput: opts.kv.pendingUserInput
+      ? parseJsonObject(opts.kv.pendingUserInput, 'pendingUserInput')
+      : undefined,
+  });
+
+  const entry = state.handoff.history[state.handoff.history.length - 1];
+  console.log(`[handoff:append] seq=${entry.seq} role=${entry.role} stage=${entry.stage}`);
+  console.log(`  summary: ${entry.summary}`);
+  if (entry.artifactRefs.length) console.log(`  artifactRefs: ${entry.artifactRefs.join(', ')}`);
+  if (entry.pendingUserInput?.status === 'awaiting_user_input') {
+    console.log(`  pendingUserInput: ${entry.pendingUserInput.id}`);
+  }
+}
+
+main();

package/project-template-v2/skills/_shared/scripts/lib/validator-artifacts.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Programmatic validator artifact persistence.
+ * All writes are script-owned; agents should read these artifacts instead of
+ * hand-writing validator results.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+export function ringArtifactDir(root, ring) {
+  return join(resolve(root), `validate/ring${ring}`);
+}
+
+export function ringAutoplayMp4(ring, label = 'autoplay') {
+  return `validate/ring${ring}/${label}.mp4`;
+}
+
+export async function writeValidatorArtifact(root, name, data, ring = 1) {
+  const dir = ringArtifactDir(root, ring);
+  await mkdir(dir, { recursive: true });
+  const relPath = `validate/ring${ring}/${name}.json`;
+  const path = join(resolve(root), relPath);
+  await writeFile(path, `${JSON.stringify(makeEnvelope(name, data), null, 2)}\n`, 'utf8');
+  return { path, relPath };
+}
+
+export function writeRingArtifactSync(root, ring, name, data) {
+  const dir = ringArtifactDir(root, ring);
+  mkdirSync(dir, { recursive: true });
+  const relPath = `validate/ring${ring}/${name}.json`;
+  const absPath = join(resolve(root), relPath);
+  writeFileSync(absPath, `${JSON.stringify(makeEnvelope(name, data), null, 2)}\n`, 'utf8');
+  return { path: absPath, relPath };
+}
+
+function makeEnvelope(name, data) {
+  return {
+    generatedAt: new Date().toISOString(),
+    name,
+    ok: typeof data === 'object' && data !== null && 'ok' in data ? Boolean(data.ok) : undefined,
+    result: data,
+  };
+}
+
+const RING_ARTIFACT_JSON_NAMES = {
+  1: ['contract', 'firstwin', 'fusion', 'vlm-video'],
+};
+
+const RING_MP4_LABELS = {
+  1: [],
+  2: ['one-click', 'full-playthrough'],
+  3: ['one-click', 'full-playthrough'],
+  4: ['one-click', 'full-playthrough'],
+};
+
+export function collectRingArtifactPaths(root, ring) {
+  const out = {};
+  const jsonNames = RING_ARTIFACT_JSON_NAMES[ring] ?? [];
+  for (const name of jsonNames) {
+    const rel = `validate/ring${ring}/${name}.json`;
+    if (existsSync(join(resolve(root), rel))) out[name] = rel;
+  }
+  const reviewRel = `validate/ring${ring}/review.json`;
+  if (existsSync(join(resolve(root), reviewRel))) out.review = reviewRel;
+  const mp4Labels = RING_MP4_LABELS[ring] ?? [];
+  for (const label of mp4Labels) {
+    const rel = ringAutoplayMp4(ring, label);
+    if (existsSync(join(resolve(root), rel))) out[`mp4-${label}`] = rel;
+  }
+  if (ring === 1) {
+    for (let i = 1; i <= 3; i += 1) {
+      const frameRel = `validate/ring1/frames/0${i}.png`;
+      if (existsSync(join(resolve(root), frameRel))) out[`frame0${i}`] = frameRel;
+    }
+  }
+  return out;
+}
+
+export const RING1_ARTIFACT_DIR = 'validate/ring1';
+export const RING1_FRAMES_DIR = 'validate/ring1/frames';
+export const RING1_AUTOPLAY_MP4 = 'validate/ring1/autoplay.mp4';
+
+export function ring1ArtifactDir(root) {
+  return ringArtifactDir(root, 1);
+}
+
+export function collectRing1ArtifactPaths(root) {
+  return collectRingArtifactPaths(root, 1);
+}

package/project-template-v2/skills/_shared/scripts/pipeline/dod-config.mjs

@@ -0,0 +1,131 @@
+/**
+ * DoD（Definition of Done）配置 — pipeline 版。
+ *
+ * 每个 DoD key 绑定：
+ *   script     → 对应的 npm script 名（可直接 spawnSync('npm', ['run', script])）
+ *   routeTo    → 失败时路由给哪个角色
+ *   nextAction → 给 orchestrator 的修复指引（自然语言）
+ *   label      → 人读描述，用于渲染和日志
+ *
+ * 按 iteration × stage 组织的 DOD_BY_STAGE 是消费入口：
+ *   DOD_BY_STAGE[iteration][stage] → string[]（key 列表，顺序即执行顺序）
+ *
+ * 参考旧 ring-config.mjs 写法，但精简到 pipeline 三迭代所需范围。
+ * Ring 4 的精细视觉验证（bgClean/tileConsistency/textOverlap 等）在迭代3再补。
+ */
+
+// ── DoD key 定义表 ─────────────────────────────────────────────────────────
+
+/**
+ * script: null 表示无自动脚本（orchestrator 人工确认）。
+ * 后续每新增 verify:xxx script 时直接在这里补 script 字段即可。
+ */
+export const DOD_DEFINITIONS = {
+  // ── 构建类 ──────────────────────────────────────────────────────────────
+  build: {
+    label: 'vite build 通过，无报错',
+    script: 'build',
+    routeTo: 'developer',
+    nextAction: '修复构建报错后重跑 npm run build',
+  },
+
+  // ── 合约 / 生命周期 ─────────────────────────────────────────────────────
+  contract: {
+    label: 'verify:contract — HOOK/autoPlay/ENDCARD 合约检查',
+    script: 'verify:contract',
+    routeTo: 'developer',
+    nextAction: '修复合约违反后重跑 npm run verify:contract',
+  },
+  firstLevelWin: {
+    label: 'verify:firstwin — headless autoPlay 能到达 ENDCARD',
+    script: 'verify:firstwin',
+    routeTo: 'developer',
+    nextAction: '修复胜利条件后重跑 npm run verify:firstwin',
+  },
+  fusion: {
+    label: 'verify:fusion — 多玩法融合接线证据检查',
+    script: 'verify:fusion',
+    routeTo: 'developer',
+    nextAction: '修复多玩法接线或 fusion 设计说明后重跑 npm run verify:fusion',
+  },
+
+  // ── 录像 / 视觉 ─────────────────────────────────────────────────────────
+  autoplay: {
+    label: 'autoPlay 接入，游戏可自动演示',
+    script: null,
+    routeTo: 'developer',
+    nextAction: '检查 autoPlay 函数是否已接入并可触发完整演示流程',
+  },
+  record: {
+    label: 'record:mp4 — 录制可玩广告演示视频',
+    script: 'record:mp4',
+    routeTo: 'developer',
+    nextAction: '修复录像问题后重跑 npm run record:mp4',
+  },
+  vlmVideo: {
+    label: 'verify:vlm-video — VLM 语义评审录像',
+    script: 'verify:vlm-video',
+    routeTo: 'technical-artist',
+    nextAction: '查看 validate/ringN/vlm-video.json，按建议修复视频语义问题',
+  },
+};
+
+// ── 按 iteration × stage 的 DoD key 列表 ─────────────────────────────────
+
+/**
+ * 消费入口。key 列表顺序即 orchestrator 执行验证的顺序。
+ * 只在有实际检查需求的阶段填写，空阶段不列（ideate/context/wrapup 通常无脚本检查）。
+ */
+export const DOD_BY_STAGE = {
+  1: {
+    optimize: ['build', 'contract', 'firstLevelWin', 'fusion', 'autoplay', 'record'],
+  },
+  2: {
+    optimize: ['build', 'contract', 'firstLevelWin', 'fusion', 'autoplay', 'record'],
+  },
+};
+
+// ── 查询 helper ───────────────────────────────────────────────────────────
+
+/** 返回指定 iteration + stage 的 DoD key 列表，无则返回空数组。 */
+export function dodKeysForStage(iteration, stage) {
+  return DOD_BY_STAGE[Number(iteration)]?.[stage] ?? [];
+}
+
+/** 返回 key 的完整定义，未知 key 返回 null。 */
+export function dodDefinition(key) {
+  return DOD_DEFINITIONS[key] ?? null;
+}
+
+/** 返回 key 对应的 npm script 名，无脚本返回 null。 */
+export function scriptForDoDKey(key) {
+  return DOD_DEFINITIONS[key]?.script ?? null;
+}
+
+/** 返回 key 失败时的路由信息 { routeTo, nextAction }。 */
+export function routeForDoDKey(key) {
+  const def = DOD_DEFINITIONS[key];
+  if (!def) return { routeTo: 'developer', nextAction: `修复 ${key} 相关问题` };
+  return { routeTo: def.routeTo, nextAction: def.nextAction };
+}
+
+/**
+ * 给定一组失败的 key，返回优先级最高的路由目标。
+ * 优先级：game-designer < technical-artist < artist < developer < reviewer < none
+ */
+const ROUTE_PRIORITY = ['game-designer', 'technical-artist', 'artist', 'developer', 'reviewer', 'none'];
+
+export function routeForFailedDoDKeys(failedKeys) {
+  if (!failedKeys.length) return { routeTo: 'none', nextAction: 'none' };
+  const routes = failedKeys.map((k) => ({ key: k, ...routeForDoDKey(k) }));
+  routes.sort((a, b) => ROUTE_PRIORITY.indexOf(a.routeTo) - ROUTE_PRIORITY.indexOf(b.routeTo));
+  const primary = routes[0];
+  const owners = [...new Set(routes.map((r) => r.routeTo).filter((r) => r !== 'none'))];
+  if (owners.length > 1) {
+    return {
+      routeTo: primary.routeTo,
+      nextAction: `依序修复：${failedKeys.map((k) => `${k}(→${routeForDoDKey(k).routeTo})`).join(' → ')}`,
+    };
+  }
+  return { routeTo: primary.routeTo, nextAction: primary.nextAction };
+}

package/project-template-v2/skills/_shared/scripts/pipeline/index.mjs

@@ -0,0 +1,80 @@
+/**
+ * entry. 按 iteration 选 spec,提供查询 helper。不做模板展开(三循环物理分离)。
+ *
+ * 受众区分(§3.3):subagentFieldsForStage 只暴露给 subagent 的字段;
+ * orchestrator 直接读 stageConfig 拿全量(含 exit/dispatchableRoles/canWriteTodo/dod)。
+ */
+
+import { ITERATION_1 } from './iteration-1-core.mjs';
+import { ITERATION_2 } from './iteration-2-wrap.mjs';
+import { ITERATION_3 } from './iteration-3-visual.mjs';
+export {
+  dodKeysForStage,
+  dodDefinition,
+  scriptForDoDKey,
+  routeForDoDKey,
+  routeForFailedDoDKeys,
+} from './dod-config.mjs';
+
+export const PIPELINE_SPEC_VERSION = 'pipeline';
+
+/** 五阶段固定顺序。各迭代内容不同,但阶段名与推进次序一致。 */
+export const STAGES = ['ideate', 'context', 'generate', 'optimize', 'wrapup'];
+
+const SPECS = {
+  1: ITERATION_1,
+  2: ITERATION_2,
+  3: ITERATION_3,
+};
+
+export const MAX_ITERATION = 3;
+
+/** 整个迭代 spec(goal/timeBudget/stages)。未知迭代返回 null。 */
+export function specForIteration(iteration) {
+  return SPECS[Number(iteration)] ?? null;
+}
+
+/** 单个阶段配置(全量,给调度者)。未知则 null。 */
+export function stageConfig(iteration, stage) {
+  return specForIteration(iteration)?.stages?.[stage] ?? null;
+}
+
+/** 该迭代在某阶段可被派发的角色。 */
+export function dispatchableRoles(iteration, stage) {
+  return stageConfig(iteration, stage)?.dispatchableRoles ?? [];
+}
+
+/** 该迭代在某阶段拥有 todo 写权限的角色白名单。 */
+export function canWriteTodo(iteration, stage) {
+  return stageConfig(iteration, stage)?.canWriteTodo ?? [];
+}
+
+/** 阶段退出条件(自然语言 string,给调度者判断)。 */
+export function stageExit(iteration, stage) {
+  return stageConfig(iteration, stage)?.exit ?? null;
+}
+
+/** 下一个阶段名;已是 wrapup 返回 null(需 advanceStage 进位到下一迭代)。 */
+export function nextStage(stage) {
+  const i = STAGES.indexOf(stage);
+  if (i === -1 || i === STAGES.length - 1) return null;
+  return STAGES[i + 1];
+}
+
+/**
+ * 从阶段配置里摘出【可下发给 subagent】的字段子集。
+ * 不含 exit / dispatchableRoles / canWriteTodo / dod(防发散,§3.3)。
+ * flowRef 可下发:角色读它拿本阶段执行序(HOW),给路径不复述。
+ */
+export function subagentFieldsForStage(iteration, stage) {
+  const cfg = stageConfig(iteration, stage);
+  if (!cfg) return null;
+  return {
+    guidance: cfg.guidance ?? '',
+    fixedPrompt: cfg.fixedPrompt ?? '',
+    skillHints: cfg.skillHints ?? [],
+    artifacts: cfg.artifacts ?? [],
+    artifactRules: cfg.artifactRules ?? {},
+    flowRef: cfg.flowRef ?? '',
+  };
+}

package/project-template-v2/skills/_shared/scripts/pipeline/iteration-1-core.mjs

@@ -0,0 +1,90 @@
+/**
+ * Iteration 1: 主核心玩法 (core gameplay).
+ *
+ * 主线骨架的单一真相之一。三循环物理分离(见 docs/harness/pipeline-design.md):
+ * 本文件只描述迭代1,目标/skill 引导/固定 prompt 都独立,不与迭代2/3 共享模板。
+ *
+ * 字段受众:
+ *   - guidance / fixedPrompt / skillHints / artifacts / artifactRules / flowRef → 给 subagent(经 dispatch 收窄)
+ *   - dispatchableRoles / canWriteTodo / exit / dod                            → 只给调度者 / hook,不下发 subagent
+ *
+ * flowRef 指向 docs/harness/iteration-1/<stage>-flow.md —— 该阶段的执行序/产物结构/评价。
+ * 派发时给路径不复述(角色读 flow 文档拿 HOW,role card 拿稳定职责)。
+ */
+
+export const ITERATION_1 = {
+  iteration: 1,
+  goal: '主核心玩法',
+  timeBudget: '30-40min',
+  stages: {
+    ideate: {
+      dispatchableRoles: ['game-designer'],
+      canWriteTodo: [],
+      guidance:
+        '先建立完整 playable 的玩法预期,再聚焦交互闭环与核心规则:先明晰单玩法的交互规则(玩法1/玩法2),再到多玩法整体。'
+        + '做融合时要写清两个强信号分别由什么画面对象/目标实体/反馈层承载,避免一个是真实玩法、另一个只停留在文档命名。'
+        + 'Hook、教程、完整游戏段、成功/失败和结束动机用于筛选核心玩法;只有影响发现、候选、用户输入或取舍时才写入 brief。docs/design.md 只落核心玩法合同。'
+        + '先发散,再由编排者向用户确认方向。',
+      fixedPrompt: '',
+      skillHints: ['brainstorming', 'playcraft-skill-recommender'],
+      artifacts: ['docs/design.md', 'docs/design-brief.md'],
+      artifactRules: {
+        'docs/design-brief.md':
+          '工作日志:只在发现、候选、用户输入或取舍影响设计判断时追加;不要求章节完整,不要写成 design 规则;带 [WEB]/[SKILL]/[USER] 来源标记;禁写 gate/handoff 流程状态',
+        'docs/design.md': '仅聚焦核心玩法:交互闭环、单/多玩法、最简成功失败',
+      },
+      flowRef: 'docs/harness/iteration-1/ideate-flow.md',
+      exit: '发散完成,且编排者已向用户确认核心玩法方向(user-confirm)',
+    },
+
+    context: {
+      dispatchableRoles: ['game-designer'],
+      canWriteTodo: ['game-designer'],
+      guidance:
+        '基于 design.md + design-brief.md + skills match,先用 atom-tree 中间产物完成 Atom 引入,再把核心玩法闭环收敛成 1-5 个可派发的功能点 TODO。'
+        + '每个 todo 都应是适合单独实现和单独验收的功能点,而不是完整游戏清单或技术横切层分工。'
+        + '不得发明关卡尺寸/数量/计时/血量等参数;测试数据优先用 selected atom 的 generator/scaffold/sample,手写只作失败 fallback;非最小闭环必需的 VFX (Visual Effects, 视觉特效)/动效/音效/连击/倒计时不进入 acceptance。',
+      fixedPrompt: '',
+      skillHints: ['playcraft-skill-recommender'],
+      inputs: ['docs/design.md', 'docs/design-brief.md', 'docs/atom-tree.json'],
+      artifacts: ['docs/todo_list.md'],
+      flowRef: 'docs/harness/iteration-1/context-flow.md',
+      exit: 'todo 池已 seed(1-5 个),覆盖核心玩法闭环成立所需的关键功能点',
+    },
+
+    generate: {
+      dispatchableRoles: ['developer'],
+      canWriteTodo: ['developer', 'reviewer'],
+      guidance:
+        '按 todo 分玩法生产。每个 todo 只做 acceptance 所列内容,不越界做 CTA/包装/视觉。',
+      fixedPrompt: '',
+      skillHints: [],
+      artifacts: ['game/**'],
+      flowRef: 'docs/harness/iteration-1/generate-flow.md',
+      exit: 'todo 池全部 done —— 本迭代结束前 todo 池必须清空',
+    },
+
+    optimize: {
+      dispatchableRoles: ['developer'],
+      canWriteTodo: ['developer', 'reviewer'],
+      guidance:
+        'build 并修复报错 → 接入 autoPlay → build & 录像。产出可自动演示并录像的 game。',
+      fixedPrompt: '',
+      skillHints: ['playable-record', 'playable-debug', 'playable-validate'],
+      artifacts: ['game/**', 'recordings/*.mp4', 'validate/**'],
+      dod: ['build', 'contract', 'firstLevelWin', 'fusion', 'autoplay', 'record'],
+      flowRef: 'docs/harness/iteration-1/optimize-flow.md',
+      exit: 'build 通过、autoPlay 接入、录像产出',
+    },
+
+    wrapup: {
+      dispatchableRoles: [],
+      canWriteTodo: [],
+      guidance: '迭代整理:回收测试资源/释放端口占用;根据当前目录状态重写 CLAUDE.md。',
+      tasks: ['reclaim-ports', 'rewrite-claude-md'],
+      artifacts: [],
+      flowRef: 'docs/harness/iteration-1/wrapup-flow.md',
+      exit: '端口回收完成、CLAUDE.md 已按当前目录重写',
+    },
+  },
+};