pm-workflow-studio 0.1.0

package/.codex/bundled-skills/impeccable/scripts/pin.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Pin/unpin sub-commands as standalone skill shortcuts.
+ *
+ * Usage:
+ *   node <scripts_path>/pin.mjs pin <command>
+ *   node <scripts_path>/pin.mjs unpin <command>
+ *
+ * `pin audit` creates a lightweight /audit skill that redirects to /impeccable audit.
+ * `unpin audit` removes that shortcut.
+ *
+ * The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
+ * in the project root and creates/removes the pin in all of them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// All known harness directories
+const HARNESS_DIRS = [
+  '.claude', '.cursor', '.gemini', '.codex', '.agents',
+  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
+];
+
+// Valid sub-command names
+const VALID_COMMANDS = [
+  'craft', 'teach', 'extract', 'document', 'shape',
+  'critique', 'audit',
+  'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
+  'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',
+  'clarify', 'adapt', 'optimize',
+];
+
+// Marker to identify pinned skills (so unpin doesn't delete user skills)
+const PIN_MARKER = '<!-- impeccable-pinned-skill -->';
+
+/**
+ * Walk up from startDir to find a project root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (dir !== '/') {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'skills-lock.json'))
+    ) {
+      return dir;
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(startDir);
+}
+
+/**
+ * Find harness skill directories that have an impeccable skill installed.
+ */
+function findHarnessDirs(projectRoot) {
+  const dirs = [];
+  for (const harness of HARNESS_DIRS) {
+    const skillsDir = join(projectRoot, harness, 'skills');
+    // Only pin in harness dirs that already have impeccable installed
+    const impeccableDir = join(skillsDir, 'impeccable');
+    if (existsSync(impeccableDir) || existsSync(join(skillsDir, 'i-impeccable'))) {
+      dirs.push(skillsDir);
+    }
+  }
+  return dirs;
+}
+
+/**
+ * Load command metadata (descriptions for pinned skills).
+ */
+function loadCommandMetadata() {
+  const metadataPath = join(__dirname, 'command-metadata.json');
+  if (existsSync(metadataPath)) {
+    return JSON.parse(readFileSync(metadataPath, 'utf-8'));
+  }
+  return {};
+}
+
+/**
+ * Generate a pinned skill's SKILL.md content.
+ */
+function generatePinnedSkill(command, metadata) {
+  const desc = metadata[command]?.description || `Shortcut for /impeccable ${command}.`;
+  const hint = metadata[command]?.argumentHint || '[target]';
+
+  return `---
+name: ${command}
+description: "${desc}"
+argument-hint: "${hint}"
+user-invocable: true
+---
+
+${PIN_MARKER}
+
+This is a pinned shortcut for \`{{command_prefix}}impeccable ${command}\`.
+
+Invoke {{command_prefix}}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
+`;
+}
+
+/**
+ * Pin a command: create shortcut skill in all harness dirs.
+ */
+function pin(command, projectRoot) {
+  const metadata = loadCommandMetadata();
+  const harnessDirs = findHarnessDirs(projectRoot);
+
+  if (harnessDirs.length === 0) {
+    console.log('No harness directories with impeccable installed found.');
+    return false;
+  }
+
+  const content = generatePinnedSkill(command, metadata);
+  let created = 0;
+
+  for (const skillsDir of harnessDirs) {
+    // Check if skill already exists (and isn't a pin)
+    const skillDir = join(skillsDir, command);
+    if (existsSync(skillDir)) {
+      const existingMd = join(skillDir, 'SKILL.md');
+      if (existsSync(existingMd)) {
+        const existing = readFileSync(existingMd, 'utf-8');
+        if (!existing.includes(PIN_MARKER)) {
+          console.log(`  SKIP: ${skillDir} (non-pinned skill already exists)`);
+          continue;
+        }
+      }
+    }
+
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+    console.log(`  + ${skillDir}`);
+    created++;
+  }
+
+  if (created > 0) {
+    console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
+    console.log(`You can now use /${command} directly.`);
+  }
+
+  return created > 0;
+}
+
+/**
+ * Unpin a command: remove shortcut skill from all harness dirs.
+ */
+function unpin(command, projectRoot) {
+  const harnessDirs = findHarnessDirs(projectRoot);
+  let removed = 0;
+
+  for (const skillsDir of harnessDirs) {
+    const skillDir = join(skillsDir, command);
+    if (!existsSync(skillDir)) continue;
+
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+
+    // Safety: only remove if it's a pinned skill
+    const content = readFileSync(skillMd, 'utf-8');
+    if (!content.includes(PIN_MARKER)) {
+      console.log(`  SKIP: ${skillDir} (not a pinned skill)`);
+      continue;
+    }
+
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  - ${skillDir}`);
+    removed++;
+  }
+
+  if (removed > 0) {
+    console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
+    console.log(`Use /impeccable ${command} to access it.`);
+  } else {
+    console.log(`No pinned '${command}' shortcut found.`);
+  }
+
+  return removed > 0;
+}
+
+// --- CLI ---
+const [,, action, command] = process.argv;
+
+if (!action || !command) {
+  console.log('Usage: node pin.mjs <pin|unpin> <command>');
+  console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+if (action !== 'pin' && action !== 'unpin') {
+  console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
+  process.exit(1);
+}
+
+if (!VALID_COMMANDS.includes(command)) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+const root = findProjectRoot();
+
+if (action === 'pin') {
+  pin(command, root);
+} else {
+  unpin(command, root);
+}

package/.codex/references/commands/analyze.md

@@ -0,0 +1,39 @@
+# analyze 命令
+
+当用户输入 `$pm-workflow analyze`、"开始分析需求"、"需求分析" 或类似意图时，使用本命令。
+
+## 负责角色
+
+必须启动当前 CLI 结构下的需求分析子 agent 执行需求分析：Codex 使用 `.codex/agents/demand-analyst.toml`，Claude Code 使用 `.claude/agents/demand-analyst.md`。产品经理负责保持对话节奏，并记录关键决策。
+
+如果当前环境无法启动需求分析子 agent，必须停止需求分析，不生成或修改 `docs/prd.md`、`docs/handoff-prd.md` 和 `docs/workflow-state.json`，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+## 输入
+
+- `docs/project-config.md`
+- `docs/workflow-state.json`
+- 当前对话中用户补充的澄清信息
+
+## 必须执行的流程
+
+1. 先输出阶段开场卡：当前用户情况、推荐方案、为什么这样选、接下来产出什么。
+2. 检查 `clarification.status` 是否为 `user_confirmed`。未确认时默认停止需求分析，交回产品经理继续澄清；用户坚持跳过时必须记录风险。
+3. 先生成 PRD 草稿，标记 `文档状态：draft`，并列出 `待用户回答问题`。
+4. 把问题抛给用户，等用户回答后再完善最终稿。
+5. 最终稿必须把 `文档状态` 改为 `final`，清空阻塞的 `待用户回答问题`。
+6. 执行四轮引导：用户角色与场景、功能模块、优先级与边界、规则与验收。
+7. 为每个功能分配 `M{模块号}-F{功能号}` 格式的编号。
+8. 将功能划分为 P0、P1 或 P2。
+9. 明确记录不做项和范围边界。
+10. 如 PRD 最终稿改变了产品定位、目标用户、平台、范围或 MVP 边界，必须同步回写 `docs/project-config.md`。
+11. 写入或更新 `docs/prd.md` 和 `docs/handoff-prd.md`。
+12. 更新 `docs/workflow-state.json`，记录阶段产物和上游同步说明；草稿阶段把 `recommended_next` 设置为 `answer analyze questions`，最终稿阶段设置为 `review analyze`。
+13. 最终稿完成后自动启动 `quality_reviewer` 执行 `$pm-workflow review analyze`。
+
+## 必须具备的追溯关系
+
+`docs/prd.md` 必须包含追溯表，字段包括：功能编号、优先级、用户角色、用户故事、业务规则、验收信号、是否进入最小可行版本。
+
+## 收尾引导
+
+草稿阶段结束时只抛出待用户回答问题。最终稿审核后询问用户：修改需求文档，还是开始技术架构设计。

package/.codex/references/commands/architect.md

@@ -0,0 +1,41 @@
+# architect 命令
+
+当用户输入 `$pm-workflow architect`、"开始设计技术架构"、"技术架构" 或类似意图时，使用本命令。
+
+## 负责角色
+
+必须启动当前 CLI 结构下的技术架构子 agent 执行技术架构设计：Codex 使用 `.codex/agents/tech-architect.toml`，Claude Code 使用 `.claude/agents/tech-architect.md`。
+
+如果当前环境无法启动技术架构子 agent，必须停止技术架构设计，不生成或修改 `docs/tech-architecture.md`、`docs/handoff-architecture.md` 和 `docs/workflow-state.json`，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+## 输入
+
+- `docs/prd.md`
+- `docs/handoff-prd.md`
+- 用户提供的技术约束或偏好
+
+## 必须执行的流程
+
+1. 先输出阶段开场卡：当前用户情况、推荐技术方向、选择原因、接下来产出什么。
+2. 设计前先检查需求文档是否存在歧义。遇到阻塞问题时交给产品经理澄清，不要自行猜测。
+3. 用小白能懂的话说明方案：如果是微信小程序内使用，优先考虑微信原生小程序 + 微信云开发；如果是网页、App 或桌面软件，再根据平台、用户体量、商业化计划、迭代方向和维护成本比较技术栈。
+4. 使用五维度决策框架：平台类型、复杂度、数据规模、第三方集成、维护成本。
+5. 输出技术选型、架构形态、数据库设计、接口清单、部署方案和本地开发说明。
+6. 如架构设计发现需求、平台、范围、功能编号或技术约束需要调整，必须同步回写 `docs/prd.md` 和 `docs/handoff-prd.md`。
+7. 写入或更新 `docs/tech-architecture.md` 和 `docs/handoff-architecture.md`。
+8. 更新 `docs/workflow-state.json`，记录阶段产物和上游同步说明，并把 `recommended_next` 设置为 `review architect` 或 `design`。
+
+## 必须具备的追溯关系
+
+必须包含需求到架构的映射表：
+
+- 功能编号
+- 数据实体或数据表
+- 字段
+- 接口
+- 部署或配置影响
+- 开放技术风险
+
+## 收尾引导
+
+结束时询问用户：是否要先做架构审核、修改架构，还是开始界面与体验设计。

package/.codex/references/commands/deliver.md

@@ -0,0 +1,29 @@
+# deliver 命令
+
+当用户输入 `$pm-workflow deliver`、"开始打包"、"打包交付" 或类似意图时，使用本命令。
+
+## 负责角色
+
+必须启动当前 CLI 结构下的产品经理子 agent 主控交付打包，并在打包前启动质量审核子 agent 做最终完整性检查：Codex 使用 `.codex/agents/product-manager.toml` 和 `.codex/agents/quality-reviewer.toml`，Claude Code 使用 `.claude/agents/product-manager.md` 和 `.claude/agents/quality-reviewer.md`。
+
+如果当前环境无法启动产品经理或质量审核子 agent，必须停止交付打包，不运行打包脚本，不生成或修改 `outputs/dev-package/`，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+## 输入
+
+- `docs/`
+- `prototype/`
+- `AGENTS.md`
+- `docs/review-*.md`
+
+## 必须执行的流程
+
+1. 启动 `quality_reviewer` 检查最终完整性和已知风险。
+2. 运行或等价执行：
+   `node .agents/skills/pm-workflow/scripts/package_delivery.js --root .`
+3. 向用户报告已复制文件、缺失文件和已知审核风险。
+4. 指向最终交付目录 `outputs/dev-package/`。
+5. 交付后停止。除非用户明确要求，不要开始研发实现。
+
+## 收尾引导
+
+结束时询问用户：检查交付包、修改某份文档，还是从交付包启动单独的开发会话。

package/.codex/references/commands/design.md

@@ -0,0 +1,92 @@
+# design 命令
+
+当用户输入 `$pm-workflow design`、"开始界面设计"、"开始界面原型设计"、"界面设计"、"原型设计" 或类似意图时，使用本命令。
+
+## 负责角色
+
+必须启动当前 CLI 结构下的界面设计子 agent 执行界面与原型设计：Codex 使用 `.codex/agents/ui-designer.toml`，Claude Code 使用 `.claude/agents/ui-designer.md`。
+
+如果当前环境无法启动界面设计子 agent，必须停止界面与原型设计，不生成或修改 `docs/ui-design.md`、`docs/handoff-ui.md`、`prototype/` 和 `docs/workflow-state.json`，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+## 输入
+
+- `docs/prd.md`
+- `docs/tech-architecture.md`
+- 已确认的产品约束、品牌线索和用户偏好
+- `assets/design-themes/`
+- Codex: `.agents/skills/impeccable/`
+- Claude Code: `.claude/skills/impeccable/`
+
+## 必须执行的流程
+
+1. 先做上游前置审查。发现需求文档或技术架构歧义时要报告，不要猜测。
+2. 从 `assets/design-themes/` 推荐 2-3 个真正有差异的设计方向。
+3. 必须为每个设计方向生成一个可打开的首页 demo，用真实业务语境展示首屏、核心入口、关键状态和视觉气质。demo 放在 `prototype/directions/`，并生成 `prototype/directions/index.html` 作为预览索引。
+4. UI 页面可见文案、按钮、导航、空状态和提示语禁止使用 emoji；图标必须使用图标库、SVG 或图片资源，不用 emoji 代替。
+5. 默认字号基准：正文、表单、按钮、列表文本不小于 16px；辅助说明可小于 16px 但不得低于 14px；移动端优先保持 16px 起。
+6. 在 `docs/ui-design.md` 中记录每个方向的说明和 demo 预览路径。没有 demo 路径的方向不得交给用户选择。
+7. 等待用户选择方向；只有用户明确授权“按你推荐的继续”时，才使用第一推荐。
+8. 用户选择方向后，基于选定方向产出完整 `docs/ui-design.md` 和 `docs/handoff-ui.md`。
+9. 在 `prototype/` 下构建完整 HTML 原型。完整原型可以复用或重构候选 demo，但不能只停留在候选 demo。
+10. 如果 UI 阶段新增或调整页面清单、交互路径、字段、状态、技术约束或验收标准，必须同步回写 `docs/prd.md`、`docs/handoff-prd.md` 或 `docs/tech-architecture.md`。
+11. 生成 Impeccable 上下文：Codex 写入 `.agents/context/PRODUCT.md` 和 `.agents/context/DESIGN.md`；Claude Code 可写入 `.claude/context/PRODUCT.md` 和 `.claude/context/DESIGN.md` 或沿用 `.agents/context/`。按当前 CLI 运行对应的 `impeccable/scripts/load-context.mjs`，完整读取上下文。
+12. 使用 Playwright 打开候选 demo 和完整原型页面，覆盖 desktop 1440x900、tablet 834x1112、mobile 390x844 三个视口，截图保存到 `prototype/review/screenshots/`。
+13. 使用 Impeccable 执行专项审查和修正：候选方向至少运行 `critique`、`audit`；完整原型运行 `critique`、`audit`、`adapt`，并按问题使用 `layout`、`typeset`、`clarify`、`animate`、`harden`；最后运行 `polish`。
+14. 最多两轮自审修正；仍未解决的问题写入遗留问题。
+15. 产出 `docs/prototype-review.md`，记录页面清单、视口清单、截图路径、控制台错误、Impeccable 审查结论、已修正项、遗留问题和复查结果。
+16. 更新 `docs/workflow-state.json`，记录阶段产物和上游同步说明，并把 `recommended_next` 设置为 `review design` 或 `plan`。
+
+如果当前 CLI 结构下的 Impeccable skill 不存在，必须停止 design 阶段并提示补齐 Impeccable skill；不要用普通 UI 审查代替。
+
+## 原型结构
+
+单页面产品：
+
+```text
+prototype/
+  directions/
+  index.html
+  layout/
+  assets/
+```
+
+多页面系统：
+
+```text
+prototype/
+  directions/
+  index.html
+  pages/
+  layout/
+  components/
+  assets/
+  review/
+    screenshots/
+```
+
+目录职责：
+
+| 路径 | 职责 | 产物要求 |
+|---|---|---|
+| `prototype/directions/` | 设计方向首页 demo | 每个候选方向必须有一个可打开的首页 demo；`index.html` 汇总 2-3 个预览入口，供用户选择方向。 |
+| `prototype/index.html` | 原型入口、全局导航、关键流程起点 | 必须能进入所有 P0 原型路径；多页面系统必须链接到 `pages/` 中的具体页面。 |
+| `prototype/pages/` | 独立业务页面 | 多页面系统的每个主要页面单独存放；页面结构必须引用或遵循 `layout/` 中的复用布局。 |
+| `prototype/layout/` | 可复用页面结构 | 沉淀应用外壳、导航、页头、侧栏、内容网格、表单页骨架、状态页骨架等结构，保证后续开发能稳定复现。 |
+| `prototype/components/` | 可复用界面组件和交互片段 | 存放按钮组、表单控件、卡片、列表、弹窗、状态块等组件示例，并标注使用场景和状态。 |
+| `prototype/assets/` | 公共资源 | 存放样式、脚本、图片、图标、示例数据等资源；页面不得依赖散落在目录外的资源。 |
+| `prototype/review/screenshots/` | 原型自审截图证据 | 按 desktop、tablet、mobile 存放 Playwright 截图；每个候选 demo 和主要原型页面都要覆盖。 |
+
+## 必须具备的追溯关系
+
+必须包含需求到界面的映射表：
+
+- 功能编号
+- 页面或路径
+- 组件或控件
+- 用户动作
+- 成功、失败、空状态、加载状态
+- 原型路径
+
+## 收尾引导
+
+结束时询问用户：是否要先做界面审核、修改设计或原型，还是开始开发规划。

package/.codex/references/commands/help.md

@@ -0,0 +1,24 @@
+# help 命令
+
+当用户输入 `$pm-workflow help`、没有提供参数，或询问"有哪些命令"时，使用本命令。
+
+## 响应要求
+
+必须启动当前 CLI 结构下的产品经理子 agent 展示菜单并引导用户选择阶段：Codex 使用 `.codex/agents/product-manager.toml`，Claude Code 使用 `.claude/agents/product-manager.md`。
+
+如果当前环境无法启动产品经理子 agent，必须停止菜单引导，不修改任何产物，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+按阶段展示命令菜单：
+
+| 命令 | 自然语言说法 | 产物 |
+|---|---|---|
+| `init` | 我想做一个... / 澄清需求 | `docs/project-config.md` |
+| `analyze` | 开始分析需求 | `docs/prd.md`, `docs/handoff-prd.md` |
+| `architect` | 开始设计技术架构 | `docs/tech-architecture.md`, `docs/handoff-architecture.md` |
+| `design` | 开始界面原型设计 | `docs/ui-design.md`, `docs/handoff-ui.md`, `prototype/` |
+| `plan` | 开始规划 | `docs/dev-tasks.md` |
+| `review [stage]` | 审核一下 | `docs/review-{stage}.md` |
+| `deliver` | 开始打包 | `outputs/dev-package/` |
+| `status` | 当前进度 | 阶段进度摘要 |
+
+最后询问用户想执行哪个阶段。

package/.codex/references/commands/init.md

@@ -0,0 +1,40 @@
+# init 命令
+
+当用户带着产品想法开始、输入 `$pm-workflow`，说“澄清需求”“需求澄清”，或给出无法匹配其他命令的模糊自然语言需求时，使用本命令。
+
+## 负责角色
+
+阶段 00 的需求澄清必须由当前主 agent 直接执行，不启动 `product_manager` 或任何其他子 agent 代问。主 agent 持有用户刚输入的产品想法、上下文、语气和补充材料，最适合判断哪些是真需求、哪些只是表达不完整。
+
+用户明确确认“我理解得对”之前，禁止把需求整理成二手摘要交给子 agent 继续澄清。用户确认后，可以由主 agent 直接写入 `docs/project-config.md` 和 `docs/workflow-state.json`；如需调用 `product_manager` 辅助文档沉淀，只能传递完整用户原话、关键问答记录、未确认假设和待补材料，不得让子 agent 覆盖用户已确认的表达。
+
+## 输入
+
+- 用户的产品想法和附带材料。
+- 如果已经存在，读取 `docs/project-config.md`。
+- 如果已经存在，读取 `docs/workflow-state.json`。
+
+## 必须执行的流程
+
+1. 如果当前目录还不是工作室目录，提示用户先在终端运行 npm CLI 初始化：
+   `pmflow init --ai auto --root . --name "<product name>"`
+   Codex 工作室可显式使用：
+   `pmflow init --ai codex --root . --name "<product name>"`
+   Claude Code 工作室可显式使用：
+   `pmflow init --ai claude --root . --name "<product name>"`
+2. 先输出欢迎语和理解复述：
+   `🤖 AI产品开发工作室已就绪`
+   `朋友你好！我是你的产品经理，会带着你一步步把想法变成现实。`
+   然后用普通用户能听懂的话确认“我理解得对不对”。
+3. 主 agent 基于当前对话上下文亲自执行需求澄清协议：每轮只问 3-5 个关键问题，必须覆盖谁最常用、用户真正的高频需求、打开产品的触发点、从开始到结束的真实使用流程、设备/平台、类似产品或反向参考、必须做和可以合并/后置/暂不做的功能。用户不用一次性全答，想到什么说什么即可。
+4. 做术语与概念对齐：用户提到专业词、行业词、产品形态、技术词或容易多义的普通词时，先用白话复述你的理解，再请用户确认是不是同一个意思；你主动描述需求时，也要解释关键概念，不能默认用户和 AI 使用同一套定义。
+5. 如环境允许，主动搜索 2-4 个类似产品作参考；如无法联网，说明无法实时搜索，并把本地经验示例标记为待确认。
+6. 按 8 项澄清完成标准检查：产品给谁用、用户真正的高频需求、解决什么场景问题、用户想达成什么结果、用户从开始到结束的真实使用流程、首版平台与使用设备、MVP 必做和暂不做边界（包括功能整合和页面/模块减负原则）、无阻塞开放问题（包括关键术语和概念没有歧义）。
+7. 只有 8 项达标、`clarification.concepts_aligned=true` 并且用户明确确认后，才将 `clarification.status` 写为 `user_confirmed`，`completion_criteria.high_frequency_need=true`、`completion_criteria.core_usage_flow=true`、`user_confirmation_required=false`，`recommended_next=analyze`；否则保持 `user_confirmation_required=true`，把缺口写入 `clarification.missing_context`、`clarification.terminology` 和 `pending_user_questions`。
+8. 沉淀产品定位、目标用户、使用人群、高频真实需求、使用触发点、真实使用流程、页面访问逻辑约束、功能整合原则、平台类型、核心场景、参考产品、术语概念表、必须有功能、明确不要的内容和工作量粗估。
+9. 写入或更新 `docs/project-config.md`。
+10. 更新 `docs/workflow-state.json`，设置 `current_stage=init`，记录 `project-config.md` 产物，并把 `recommended_next` 设置为 `clarify init`、`review init` 或 `analyze`。
+
+## 收尾引导
+
+结束时如果用户尚未确认，继续围绕缺口提问；如果已确认，询问下一步要做什么：审核本阶段、修改项目配置，还是开始需求分析。

package/.codex/references/commands/plan.md

@@ -0,0 +1,41 @@
+# plan 命令
+
+当用户输入 `$pm-workflow plan`、"开始规划"、"开发规划"、"任务拆解" 或类似意图时，使用本命令。
+
+## 负责角色
+
+必须启动当前 CLI 结构下的开发规划子 agent 执行开发任务规划：Codex 使用 `.codex/agents/dev-planner.toml`，Claude Code 使用 `.claude/agents/dev-planner.md`。
+
+如果当前环境无法启动开发规划子 agent，必须停止开发任务规划，不生成或修改 `docs/dev-tasks.md` 和 `docs/workflow-state.json`，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+## 输入
+
+- `docs/prd.md`
+- `docs/tech-architecture.md`
+- `docs/ui-design.md`
+- `prototype/`
+
+## 必须执行的流程
+
+1. 先检查上游产物是否完整，发现阻塞问题时先报告。
+2. 将实现工作拆成用户可见、可独立验证的任务。
+3. 每个任务控制在约 5-20 分钟 AI 执行粒度。
+4. 用 `Txxx` 编号明确标注任务依赖。
+5. 如果任务拆解发现需求、架构、页面路径、验收标准或技术约束缺口，必须同步回写对应上游文档，不能只在任务中新增需求。
+6. 写入或更新 `docs/dev-tasks.md`。
+7. 更新 `docs/workflow-state.json`，记录阶段产物和上游同步说明，并把 `recommended_next` 设置为 `review plan` 或 `deliver`。
+
+## 必须具备的追溯关系
+
+必须包含需求到任务的映射表：
+
+- 功能编号
+- 任务 ID
+- 前置依赖
+- 可能涉及的文件
+- 验证方式
+- 边缘情况
+
+## 收尾引导
+
+结束时询问用户：是否要先做任务规划审核、修改任务，还是打包交付。

package/.codex/references/commands/review.md

@@ -0,0 +1,33 @@
+# review 命令
+
+当用户输入 `$pm-workflow review [stage]`、"审核"、"检查文档"、"质量把关" 或类似意图时，使用本命令。
+
+## 负责角色
+
+必须启动当前 CLI 结构下的质量审核子 agent 执行审核：Codex 使用 `.codex/agents/quality-reviewer.toml`，Claude Code 使用 `.claude/agents/quality-reviewer.md`。脚本只生成审核草稿，质量审核官必须解释草稿并补充专业判断。
+
+如果当前环境无法启动质量审核子 agent，必须停止审核，不生成或修改 `docs/review-{stage}.md` 和 `docs/workflow-state.json`，不运行审核脚本，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+## 输入
+
+- 用户显式提供的阶段参数。
+- 如果未提供阶段参数，读取 `docs/workflow-state.json`。
+- `docs/` 和 `prototype/` 下的阶段产物。
+
+## 必须执行的流程
+
+1. 确定目标阶段：优先使用用户显式参数，其次使用 workflow state 中的 `current_stage`。
+2. 启动 `quality_reviewer` 子 agent，并把目标阶段、工作室根目录、当前阶段产物路径传给它。
+3. 由 `quality_reviewer` 运行或等价执行：
+   `node .agents/skills/pm-workflow/scripts/review_stage.js --root . --stage <stage>`
+4. 由 `quality_reviewer` 执行三重审核机制：
+   - 对完整性、清晰度、一致性、可执行性评分
+   - 模拟下游角色使用产物
+   - 做结构化追溯对账
+   - design 阶段额外核对 `docs/prototype-review.md`、`prototype/review/screenshots/`、Playwright 三视口截图和 Impeccable 审查修正记录
+5. 如果阶段未通过，给出具体返工指令，并询问用户现在修复还是带风险继续推进。
+6. 如果这是第三轮未通过，必须明确告知风险，并建议先停止推进、修复产物。
+
+## 收尾引导
+
+结束时询问用户：应用审核修复建议、重新审核，还是进入推荐的下一阶段。

package/.codex/references/commands/status.md

@@ -0,0 +1,20 @@
+# status 命令
+
+当用户输入 `$pm-workflow status`、"当前进度"、"现在到哪一步" 或类似意图时，使用本命令。
+
+## 负责角色
+
+必须启动当前 CLI 结构下的产品经理子 agent 汇总当前状态：Codex 使用 `.codex/agents/product-manager.toml`，Claude Code 使用 `.claude/agents/product-manager.md`。
+
+如果当前环境无法启动产品经理子 agent，必须停止状态汇总，不修改任何产物，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+
+## 输入
+
+- `docs/workflow-state.json`
+- `docs/`、`prototype/`、`outputs/dev-package/` 下已经存在的文件
+
+## 必须执行的流程
+
+1. 总结当前阶段、已有产物、审核轮次、最近审核结论和推荐下一步。
+2. 提醒缺失的预期产物，但不要因此阻断用户。
+3. 询问用户下一步要做什么：审核、修改，还是继续推进。

package/.codex/role-skills/demand-analysis/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: demand-analysis
+description: "需求分析师使用：把项目配置和用户补充说明整理为需求文档、功能编号、优先级、边界和验收标准。"
+---
+
+# 需求分析角色技能
+
+服务于本工作室的需求分析师角色。
+
+## 输入
+
+- `docs/project-config.md`
+- `docs/workflow-state.json`
+- 用户补充说明
+- 产品经理记录的开放问题
+
+如果需求分析改变产品定位、目标用户、平台、范围或 MVP 边界，必须同步回写 `docs/project-config.md`，并在 `docs/workflow-state.json` 的 `notes` 记录同步说明。
+
+## 输出
+
+- `docs/prd.md`
+- `docs/handoff-prd.md`
+
+## 工作法
+
+1. 开始前输出阶段开场卡：当前用户情况、推荐方案、选择原因、接下来产物。
+2. 检查 `clarification.status=user_confirmed`；未确认时交回产品经理澄清，用户坚持跳过则记录风险。
+3. 采用两步式流程：先生成 PRD 草稿和 `待用户回答问题`，用户回答后再完善最终稿。
+4. 草稿阶段不触发审核；最终稿完成后清空阻塞问题，并自动触发 `quality_reviewer` 审核 analyze。
+5. 做四轮引导：角色与场景、功能模块、优先级与边界、规则与验收。
+6. 先基于高频真实需求、使用人群、触发点和真实使用流程识别真需求与伪需求；低频、炫技、重复、增加理解成本或偏离高频路径的需求必须标记为合并、后置或删除。
+7. 功能模块必须优先合并同类能力，避免写成一长串功能清单。
+8. 每个功能必须有 `M{模块号}-F{功能号}`。
+9. 每个功能必须标记 P0/P1/P2；每个 P0 必须说明对应的高频场景和流程位置。
+10. P0 功能必须有业务规则、字段/状态/权限、异常和验收标准。
+11. 明确不做清单，防止范围失控。
+12. 下游分析若改变上游事实，必须同步回写上游源文档，不能只改 PRD。
+
+## 检查表
+
+- 是否有目标用户和核心场景。
+- 是否有高频真实需求、使用触发点和真实使用流程。
+- 是否识别并处理了低频、炫技、重复、增加理解成本的伪需求。
+- 是否有功能编号体系。
+- 是否有 P0/P1/P2。
+- P0 是否都能映射到高频场景和流程步骤。
+- 是否有不做清单。
+- 是否每个 P0 都能交给架构师继续设计。
+- 是否没有未回答的阻塞问题。
+- 是否只有 final 状态才触发 analyze 审核。