@playcraft/cli 0.0.57 → 0.0.58

package/project-template-v2/skills/_shared/scripts/pipeline/iteration-2-wrap.mjs

@@ -0,0 +1,93 @@
+/**
+ * Iteration 2: 玩法包装 (wrap / hook).
+ *
+ * 与迭代1物理分离:读 design-brief.md 的 hook 说明,识别基础玩法作为完整 playable
+ * 还缺少哪些包装层信息,再迭代原文档章节。
+ *
+ * flowRef 指向 docs/harness/iteration-2/<stage>-flow.md。
+ */
+
+export const ITERATION_2 = {
+  iteration: 2,
+  goal: '玩法包装(hook)',
+  timeBudget: '30-40min',
+  stages: {
+    ideate: {
+      dispatchableRoles: ['game-designer'],
+      canWriteTodo: [],
+      guidance:
+        'game-designer 先判断本轮进入迭代2的性质:核心玩法刚完成后的包装构建,或已执行一轮后的目标优化。'
+        + '两条路径的文档扩充方式不同:包装构建要补齐完整 playable 的 hook、包装、关卡、引导、成功/失败和体验流程;'
+        + '目标优化要先确认用户输入/执行结果影响了什么,只更新保持不变项、本轮修正项、用户输入处理和设计边界。'
+        + '迭代1已做过增强维度思考和提问,本阶段先参考已有记录;关键包装决策无法自洽时可在 handoff 中提出问题和推荐判断。'
+        + '调度者回来后区分可自行做结论还是真实用户确认;如有用户输入影响玩法,以用户为准并继续写 brief。',
+      fixedPrompt: '',
+      skillHints: ['brainstorming', 'playcraft-ad-psychology'],
+      inputs: ['docs-last/**', 'docs/design.md', 'docs/design-brief.md', 'game/**'],
+      artifacts: ['docs/design.md', 'docs/design-brief.md'],
+      artifactRules: {
+        'docs/design.md':
+          '原文件迭代:包装构建路径追加/更新“迭代2:玩法包装升级”;目标优化路径追加/更新“目标优化记录”并只修正受影响小节',
+        'docs/design-brief.md':
+          '原 brief 继续追加:包装构建路径写 Packaging Build Log;目标优化路径写 Target Optimization Log;如有用户输入影响玩法,以用户为准',
+      },
+      flowRef: 'docs/harness/iteration-2/ideate-flow.md',
+      exit: '已说明本轮采用包装构建或目标优化策略;docs/design.md 与 docs/design-brief.md 已完成迭代2章节/记录;如有待确认问题,调度者已区分为自行结论或真实用户确认,并确认可进入 context(user-confirm)',
+    },
+    context: {
+      dispatchableRoles: ['game-designer'],
+      canWriteTodo: ['game-designer'],
+      guidance:
+        '基于 ideate 已明确的路径和 docs-last/current docs 差异拆 TODO。'
+        + 'context 只负责说明要做什么、上下文是什么、参考是什么;不提前写 verifier 或 optimize 验证细节。'
+        + '每个差异点需判断为重写、优化或功能补充,并用不同粒度分发;根据新意图从 atom-tree 中间产物/skill 库查找参考,'
+        + '并确认强相关参考是否包含代码实现过程、模板或脚本;参考变化时必须明确指出。'
+        + '本阶段禁止写 docs/design-brief.md,设计缺口必须 STOP 回 ideate。',
+      fixedPrompt: '',
+      skillHints: [],
+      inputs: ['docs-last/**', 'docs/design.md', 'docs/design-brief.md', 'docs/todo_list.md', 'docs/atom-tree.json', 'game/**'],
+      artifacts: ['docs/todo_list.md', 'docs/atom-tree.json'],
+      flowRef: 'docs/harness/iteration-2/context-flow.md',
+      exit: 'todo 池已 seed(非空),每个 todo 都来自明确差异点并标注重写/优化/功能补充;任务卡说明 work/context/reference;参考变化已记录;context 未写 brief',
+    },
+    generate: {
+      dispatchableRoles: ['developer'],
+      canWriteTodo: ['developer', 'reviewer'],
+      guidance:
+        '按当前 dispatch 对应的迭代2任务卡生产包装升级。developer 必须读取 Work/Context/Reference/Implementation Notes,'
+        + '按参考实现过程和代码入口落地,不重新拆任务、不补设计、不无依据重做整套包装。'
+        + '评价从完整游戏角度判断:包装构建要让游戏清晰、有趣、可完成;目标优化只修改受影响目标。'
+        + '开发结束后由调度者整理完整 TODO 历史总览。',
+      fixedPrompt: '',
+      skillHints: [],
+      artifacts: ['game/**', 'docs/todo_list.md'],
+      flowRef: 'docs/harness/iteration-2/generate-flow.md',
+      exit: 'todo 池全部 done,且 docs/todo_list.md 已合并当前 todo 与之前 todo 的历史总览 —— 本迭代结束前 todo 池必须清空',
+    },
+    optimize: {
+      dispatchableRoles: ['developer'],
+      canWriteTodo: ['developer', 'reviewer'],
+      guidance:
+        'build、contract、first win、fusion、autoplay、录像。先回读迭代2任务卡,确认 Work/Context/Reference 没有实现偏离;'
+        + '再按完整游戏体验评价 hook、引导、成功/失败和基础玩法是否组成清晰、有趣、可完成的 playable。'
+        + '包装构建关注完整闭环;目标优化关注用户输入/执行反馈影响项是否修正且无无关大改。',
+      fixedPrompt: '',
+      skillHints: ['playcraft-playable-optimization'],
+      artifacts: ['game/**', 'validate/*.mp4'],
+      dod: ['build', 'contract', 'firstLevelWin', 'fusion', 'autoplay', 'record'],
+      flowRef: 'docs/harness/iteration-2/optimize-flow.md',
+      exit: 'build/contract/first win/fusion/autoplay/record 通过或明确 no-op;任务卡实现未偏离;录像能按完整游戏评价看到包装升级',
+    },
+    wrapup: {
+      dispatchableRoles: [],
+      canWriteTodo: [],
+      guidance:
+        '迭代整理:回收测试资源/释放端口占用;确认 docs-last→design/brief→todo→handoff/validate/recordings 差异链完整;'
+        + '确认 TODO 历史总览;包装流程真实落地后重写 CLAUDE.md;第二轮结束后向用户确认是否接受当前完整包装结果。',
+      tasks: ['reclaim-ports', 'rewrite-claude-md'],
+      artifacts: [],
+      flowRef: 'docs/harness/iteration-2/wrapup-flow.md',
+      exit: '端口回收完成、TODO 历史总览完整、CLAUDE.md 已按真实状态重写、第二轮结束用户确认已发起或记录 pending',
+    },
+  },
+};

package/project-template-v2/skills/_shared/scripts/pipeline/iteration-3-visual.mjs

@@ -0,0 +1,23 @@
+/**
+ * Iteration 3: 视觉优化 (visual). 占位骨架,细节待定(见设计文档 §8 待定项)。
+ *
+ * 时长约 1h。阶段是否套用 5-stage(换 artist/TA),还是另设,尚未确认。
+ * 当前仅确定 wrapup 与前两迭代一致。
+ */
+
+export const ITERATION_3 = {
+  iteration: 3,
+  goal: '视觉优化',
+  timeBudget: '1h',
+  stages: {
+    // TODO: 视觉阶段细节待定 —— artist / technical-artist 的 ideate/context/generate/optimize
+    wrapup: {
+      dispatchableRoles: [],
+      canWriteTodo: [],
+      guidance: '迭代整理:回收端口;重写 CLAUDE.md。',
+      tasks: ['reclaim-ports', 'rewrite-claude-md'],
+      artifacts: [],
+      exit: '端口回收完成、CLAUDE.md 已重写',
+    },
+  },
+};

package/project-template-v2/skills/_shared/scripts/render-project-state.mjs

@@ -0,0 +1,230 @@
+/**
+ * Deterministic JSON → markdown renderer for docs/project-state.md.
+ *
+ * The markdown is a GENERATED, read-only human view of docs/project-state.json
+ * (the process backing file). It is re-rendered after every write through
+ * state-store.mjs.
+ *
+ * View: Pipeline table, Current Dispatch, TODO Pool table, Last Handoff,
+ * Stage DoD. See docs/harness/pipeline-design.md.
+ *
+ * Never throws — persistState wraps this in try/catch.
+ */
+
+const GENERATED_BANNER =
+  '<!-- GENERATED — do not hand-edit. Read via `npm run state:get`; process backing file: docs/project-state.json. ' +
+  'Write via `npm run state:set`. -->';
+
+function ser(value) {
+  if (value == null) return '—';
+  const s = String(value);
+  return s === '' ? '—' : s;
+}
+
+function listItems(items) {
+  if (!Array.isArray(items) || items.length === 0) return '—';
+  return items.map((item) => String(item)).join(', ');
+}
+
+/** ## Pipeline table */
+function renderPipeline(state) {
+  const p = state.pipeline || {};
+  const specVersion = state.specVersion ?? 'pipeline';
+  return `## Pipeline
+
+| field | value |
+| ----- | ----- |
+| specVersion | ${ser(specVersion)} |
+| iteration | ${ser(p.iteration)} |
+| stage | ${ser(p.stage)} |
+| stageStatus | ${ser(p.stageStatus)} |
+| userConfirm | ${ser(p.userConfirm)} |`;
+}
+
+/** ## Current Dispatch */
+function renderDispatch(state) {
+  const d = state.dispatch || {};
+  const todoId = ser(d.activeTodoId);
+  const goal = ser(d.goal);
+  const requiredContext = listItems(d.requiredContext);
+  const reuse = ser(d.contextReuse);
+  const allowedFiles = listItems(d.allowedFiles);
+  const forbiddenTasks = listItems(d.forbiddenTasks);
+  const acceptance = listItems(d.acceptance);
+  return `## Current Dispatch
+
+- role: @${ser(d.role)}
+- todo: ${todoId} — ${goal}
+- read: ${requiredContext}
+- context reuse: ${reuse}
+- write boundary: ${allowedFiles}
+- forbidden: ${forbiddenTasks}
+- acceptance: ${acceptance}
+- verifier: ${ser(d.verifier)}`;
+}
+
+/** ## TODO Pool */
+function renderTodoPool(state) {
+  const iteration = state.pipeline?.iteration ?? 1;
+  const todos = (state.todos || []).filter((t) => Number(t.iteration ?? iteration) === Number(iteration));
+  if (todos.length === 0) {
+    return `## TODO Pool (iteration ${iteration})
+
+_no todos yet_`;
+  }
+  const rows = todos
+    .map((t) => {
+      return `| ${ser(t.id)} | ${ser(t.stage)} | ${ser(t.role)} | ${ser(t.status)} | ${ser(t.contextReuse)} | ${ser(t.title)} |`;
+    })
+    .join('\n');
+  return `## TODO Pool (iteration ${iteration})
+
+| id | stage | role | status | contextReuse | title |
+| -- | ----- | ---- | ------ | ------------ | ------ |
+${rows}`;
+}
+
+/** ## Last Handoff (tail of history) */
+function renderLastHandoff(state) {
+  const history = state.handoff?.history || [];
+  if (history.length === 0) {
+    return `## Last Handoff
+
+_no handoff entries yet_`;
+  }
+  const last = history[history.length - 1];
+  const artifacts = Array.isArray(last.artifactRefs) && last.artifactRefs.length > 0
+    ? ` → ${last.artifactRefs.join(', ')}`
+    : '';
+  const status = last.status && last.status !== 'completed' ? ` [${last.status}]` : '';
+  return `## Last Handoff
+
+- ${ser(last.role)} (seq ${ser(last.seq)})${status}: ${ser(last.summary)}${artifacts}`;
+}
+
+function renderPendingUserInput(state) {
+  const pending = state.handoff?.pendingUserInput || {};
+  if (!pending.status || pending.status === 'none' || pending.status === 'resolved') {
+    return `## Pending User Input
+
+none`;
+  }
+  const options = Array.isArray(pending.options) && pending.options.length > 0
+    ? pending.options.map((option) => `${option.label}: ${option.description}`).join('; ')
+    : '—';
+  return `## Pending User Input
+
+| Field | Value |
+| ----- | ----- |
+| status | ${ser(pending.status)} |
+| id | ${ser(pending.id)} |
+| requestedBy | ${ser(pending.requestedBy)} |
+| prompt | ${ser(pending.prompt)} |
+| options | ${options} |
+| recommended | ${ser(pending.recommended)} |
+| impact | ${ser(pending.impact)} |
+| answer | ${ser(pending.answer)} |`;
+}
+
+/** ## Stage DoD */
+function renderStageDoD(state) {
+  const gate = state.gate || {};
+  const dod = gate.stageDoD || {};
+  const entries = Object.entries(dod);
+  if (entries.length === 0) {
+    return `## Stage DoD
+
+| canAskUser |
+| ---------- |
+| ${ser(gate.canAskUser)} |`;
+  }
+  const headers = entries.map(([k]) => k).join(' | ');
+  const values = entries.map(([, v]) => ser(v)).join(' | ');
+  return `## Stage DoD
+
+| ${headers} | canAskUser |
+| ${entries.map(() => '------').join(' | ')} | ---------- |
+| ${values} | ${ser(gate.canAskUser)} |`;
+}
+
+/** ## Dev Preview */
+function renderDevPreview(state) {
+  const d = state.devPreview || {};
+  const blockers =
+    Array.isArray(d.devBlockers) && d.devBlockers.length > 0 ? d.devBlockers.join('; ') : 'none';
+  return `## Dev Preview
+
+> Written programmatically. Do not hand-edit.
+
+| Field | Value |
+| ----- | ----- |
+| devStatus | ${ser(d.devStatus)} |
+| devUrl | ${ser(d.devUrl)} |
+| devStartedBy | ${ser(d.devStartedBy)} |
+| devLastChecked | ${ser(d.devLastChecked)} |
+| loadCheck | ${ser(d.loadCheck)} |
+| loadCheckNotes | ${ser(d.loadCheckNotes)} |
+| uiReviewStatus | ${ser(d.uiReviewStatus)} |
+| uiDiffNotes | ${ser(d.uiDiffNotes)} |
+| uiReworkRound | ${ser(d.uiReworkRound)} |
+| devBlockers | ${blockers} |`;
+}
+
+/** ## Shared Decisions */
+function renderSharedDecisions(state) {
+  const shared = state.handoff?.sharedDecisions || {};
+  const entries = Object.entries(shared);
+  if (entries.length === 0) return '';
+  const rows = entries.map(([k, v]) => `| ${k} | ${ser(v)} |`).join('\n');
+  return `## Shared Decisions
+
+| Key | Value |
+| --- | ----- |
+${rows}`;
+}
+
+/**
+ * Render a full docs/project-state.md from a normalized state object.
+ * Never throws.
+ * @param {object} state
+ * @returns {string}
+ */
+export function renderProjectState(state) {
+  try {
+    const userIntent = state.userIntent && !/\{\{/.test(state.userIntent)
+      ? state.userIntent
+      : '{{user intent — ≤2 sentences}}';
+
+    const parts = [
+      `# Project State (generated — do not edit)`,
+      '',
+      GENERATED_BANNER,
+      '',
+      `> **Agent entry**: run \`npm run state:get\` first. Do **not** hand-edit this file — it is generated from the process backing file \`docs/project-state.json\`. Write via \`npm run state:set\`.`,
+      '',
+      `## User Intent`,
+      '',
+      `> ${userIntent}`,
+      '',
+      renderPipeline(state),
+      '',
+      renderDispatch(state),
+      '',
+      renderTodoPool(state),
+      '',
+      renderLastHandoff(state),
+      '',
+      renderPendingUserInput(state),
+      '',
+      renderStageDoD(state),
+      '',
+      renderDevPreview(state),
+      '',
+      renderSharedDecisions(state),
+      '',
+    ];
+    return parts.filter((p) => p !== null && p !== undefined).join('\n');
+  } catch {
+    return `# Project State (generated — do not edit)\n\n${GENERATED_BANNER}\n\n_render error — check docs/project-state.json_\n`;
+  }
+}

package/project-template-v2/skills/_shared/scripts/state-advance-stage.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Advance the pipeline stage. Calls advanceStage() from state-store.mjs and
+ * reads stage order from ./pipeline/index.mjs (STAGES).
+ *
+ * Usage:
+ *   npm run stage:advance -- --accepted
+ *   node skills/_shared/scripts/state-advance-stage.mjs --root=. --accepted [--json]
+ */
+
+import { resolve } from 'node:path';
+import { advanceStage } from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), accepted: false, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--root=')) {
+      const value = arg.slice('--root='.length);
+      opts.root = value.startsWith('/') ? value : resolve(process.cwd(), value);
+    } else if (arg === '--accepted') {
+      opts.accepted = true;
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: state-advance-stage.mjs [--root=.] --accepted [--json]');
+      console.log('Advances pipeline.stage to the next stage (or next iteration when past wrapup).');
+      console.log('Blocked if current-iteration todos are not all done at generate/wrapup boundaries.');
+      process.exit(0);
+    }
+    // stage is explicit in state; nothing is derived from iteration here.
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  try {
+    const state = advanceStage(opts.root, { accepted: opts.accepted });
+    const summary = {
+      iteration: state.pipeline.iteration,
+      stage: state.pipeline.stage,
+      stageStatus: state.pipeline.stageStatus,
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log(`iteration: ${summary.iteration}`);
+      console.log(`stage: ${summary.stage}`);
+      console.log(`stageStatus: ${summary.stageStatus}`);
+    }
+  } catch (error) {
+    console.error(`[state:advance-stage] ${error.message}`);
+    process.exit(2);
+  }
+}
+
+main();