pm-workflow-studio 0.1.0

package/.codex/templates/delivery-README.md

@@ -0,0 +1,37 @@
+# 开发交付包
+
+本目录包含产品开发所需的核心文档、审核报告和原型。
+
+## 使用方式
+
+1. 在本目录启动开发会话。
+2. 先阅读 `AGENTS.md`。
+3. 按照 `dev-tasks.md` 的任务顺序执行开发。
+4. 每完成一个任务，按任务中的验证方式检查结果。
+
+## 文档清单
+
+| 文档 | 说明 |
+|---|---|
+| `AGENTS.md` | 开发执行准则 |
+| `project-config.md` | 项目配置和定位 |
+| `prd.md` | 产品需求文档 |
+| `handoff-prd.md` | 需求交接摘要 |
+| `tech-architecture.md` | 技术架构方案 |
+| `handoff-architecture.md` | 架构交接摘要 |
+| `ui-design.md` | 界面与体验设计文档 |
+| `handoff-ui.md` | 界面交接摘要 |
+| `prototype-review.md` | 高保真原型自审报告 |
+| `dev-tasks.md` | 开发任务清单 |
+| `review-*.md` | 阶段审核报告 |
+| `prototype/` | 高保真 HTML 原型 |
+
+## 缺失项
+
+{{MISSING_SECTION}}
+
+## 执行提醒
+
+- 严格按任务编号顺序执行。
+- 遇到需求矛盾时先回看需求文档和审核报告。
+- 不默认新增需求范围外的功能。

package/.codex/templates/framework-AGENTS.md

@@ -0,0 +1,74 @@
+# {{PRODUCT_NAME}} - 产品开发工作室
+
+本目录是一个 Codex 项目级工作室。请把这里当作产品从想法到开发施工蓝图的主工作区。
+
+## 工作室角色
+
+- 产品经理：项目初始化、阶段路由、用户引导、状态记录。
+- 需求分析师：需求文档、功能编号、P0/P1/P2、边界和验收。
+- 技术架构师：技术选型、数据库、接口、部署和架构映射。
+- 界面设计师：设计方向、界面文档、高保真 HTML 原型。
+- 开发规划师：可执行任务拆解和验证方式。
+- 质量审核官：评分、仿真测试、结构化对账和返工建议。
+
+## 项目结构约定
+
+- Codex 结构：根目录 `AGENTS.md` 是总控说明，`.codex/agents/` 存放 6 个角色配置，`.agents/skills/pm-workflow/` 是主入口技能，`.agents/skills/*/` 是角色技能，`.agents/skills/impeccable/` 是界面原型自审和打磨技能。
+- Claude Code 结构：`.claude/CLAUDE.md` 是总控说明，`.claude/agents/` 存放 Markdown subagents，`.claude/commands/pm-workflow/` 存放 slash commands，`.claude/skills/pm-workflow/` 是主入口技能，`.claude/skills/*/` 是角色和第三方技能。
+- `.agents/context/` 或 `.claude/context/` 存放 Impeccable 使用的产品和设计上下文。
+- `docs/` 是阶段文档产出区。
+- `prototype/` 是高保真 HTML 原型区。
+- `outputs/dev-package/` 是最终交付包。
+
+## 启动方式
+
+用户可以直接说产品想法，也可以使用自然语言命令：
+
+- `开始分析需求`
+- `开始设计技术架构`
+- `开始界面原型设计`
+- `开始规划`
+- `审核一下`
+- `开始打包`
+- `当前进度`
+
+主入口技能：Codex 使用 `.agents/skills/pm-workflow/SKILL.md`；Claude Code 使用 `.claude/skills/pm-workflow/SKILL.md`。
+
+## 阶段纪律
+
+- 阶段 00 的需求澄清由主 agent 直接完成：欢迎、复述、追问、整理缺口和请用户确认都不能外包给子 agent。
+- 禁止把用户刚输入的需求先总结成二手摘要，再交给 `product_manager` 或其他子 agent 继续澄清；主 agent 持有完整对话上下文，必须亲自判断真实需求。
+- 阶段 00 必须摸清谁高频使用、用户真正的高频需求、打开产品的触发点、从开始到结束的真实使用流程，以及页面/模块减负边界；这些信息是需求分析识别真需求和 UI 设计制定页面访问逻辑的依据。
+- 除阶段 00 的需求澄清外，每个阶段命令都必须先启动当前 CLI 结构下对应的项目子 agent：Codex 使用 `.codex/agents/*.toml`，Claude Code 使用 `.claude/agents/*.md`。
+- 阶段到 agent 的固定映射：`help/status/deliver -> product_manager/product-manager`，`analyze -> demand_analyst/demand-analyst`，`architect -> tech_architect/tech-architect`，`design -> ui_designer/ui-designer`，`plan -> dev_planner/dev-planner`，`review -> quality_reviewer/quality-reviewer`。`init` 在用户确认前不启动子 agent，确认后可调用产品经理子 agent 做文档沉淀和状态维护。
+- 每个阶段开始都先输出阶段开场卡：当前用户情况、推荐方案、为什么这样选、接下来产出什么。
+- 进入需求分析前，`docs/workflow-state.json` 中的 `clarification.status` 默认必须是 `user_confirmed`，且 `user_confirmation_required=false`。
+- 需求分析先产出 PRD 草稿和待用户回答问题；用户回答后再完善最终稿，并自动触发 `quality_reviewer` 审核 analyze。
+- 需求分析必须基于高频真实需求和真实使用流程识别真需求与伪需求，P0 功能必须映射到高频场景和流程位置，功能模块优先合并同类能力。
+- 如果当前环境无法启动后续阶段所需的项目子 agent，必须停止对应阶段执行，不生成或修改阶段产物，不运行阶段脚本，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。
+- 每阶段结束必须引导用户选择：审核、修改、进入下一阶段。
+- 审核是软门控：不强制阻断，但必须记录风险。
+- 不要让后续阶段静默新增需求范围。
+- 如果下游文档改变需求、平台、范围、功能编号、技术约束、页面路径或验收标准，必须同步回写上游源文档，并在 `docs/workflow-state.json` 的 `notes` 记录同步说明。
+- 功能编号必须从需求文档贯穿到架构、界面和开发任务。
+- 原型必须能演示 P0 功能的关键路径和状态。
+- UI 页面访问逻辑必须从真实使用流程推导，页面数量以完成高频路径为准；能合并的入口、状态、表单、列表、详情必须合并并记录理由。
+- UI 页面可见文案、按钮、导航、空状态和提示语禁止使用 emoji；图标必须使用图标库、SVG 或图片资源，不用 emoji 代替。
+- UI 正文、表单、按钮、列表文本默认不小于 16px；辅助说明不得低于 14px。
+- 界面设计师交付完整原型前，必须完成 Playwright 截图和 Impeccable 自审，并写入 `docs/prototype-review.md`。
+- 交付后停止，不要默认进入研发实现。
+
+## 脚本路径
+
+在本框架内运行脚本时使用：
+
+```bash
+node .agents/skills/pm-workflow/scripts/review_stage.js --root . --stage analyze
+node .agents/skills/pm-workflow/scripts/package_delivery.js --root .
+node .claude/skills/pm-workflow/scripts/review_stage.js --root . --stage analyze
+node .claude/skills/pm-workflow/scripts/package_delivery.js --root .
+```
+
+## 后续开发执行
+
+当 `outputs/dev-package/` 生成后，可以在交付包目录中启动新的开发会话，并按 `dev-tasks.md` 顺序执行。

package/.codex/templates/framework-README.md

@@ -0,0 +1,65 @@
+# {{PRODUCT_NAME}} 工作室说明
+
+这是一个可直接进入并运行的产品开发工作室目录。它可以按 Codex 或 Claude Code 结构安装；`pmflow init` 会根据 `--ai auto|codex|claude` 选择对应目录。
+
+## 目录说明
+
+```text
+AGENTS.md
+.codex/
+  config.toml
+  agents/
+.agents/
+  context/
+  skills/
+.claude/
+  CLAUDE.md
+  agents/
+  commands/
+  skills/
+docs/
+prototype/
+  directions/
+  review/screenshots/
+outputs/dev-package/
+```
+
+- Codex 使用 `AGENTS.md`、`.codex/agents/`、`.agents/skills/pm-workflow/`、`.agents/skills/<role>/`、`.agents/skills/impeccable/` 和 `.agents/context/`。
+- Claude Code 使用 `.claude/CLAUDE.md`、`.claude/agents/`、`.claude/commands/pm-workflow/`、`.claude/skills/pm-workflow/`、`.claude/skills/<role>/` 和 `.claude/skills/impeccable/`。
+- `docs/`：阶段文档产出区。
+- `prototype/`：高保真 HTML 原型区；`directions/` 存放候选方向首页 demo，`review/screenshots/` 存放自审截图。
+- `outputs/dev-package/`：最终开发交付包。
+
+## 开始使用
+
+1. 在本目录启动开发会话。
+2. 直接输入你的产品想法，例如：`我想做一个每天记录习惯的 App`，或先说 `澄清需求`。
+3. 产品经理会先用普通聊天方式帮你澄清真实需求，重点摸清谁高频使用、用户真正的高频需求、打开产品的触发点和真实使用流程；等你确认理解无误后，再进入需求、架构、界面、任务规划、审核和打包。
+
+常用自然语言：
+
+- `澄清需求`
+- `开始分析需求`
+- `开始设计技术架构`
+- `开始界面原型设计`
+- `开始规划`
+- `审核一下`
+- `开始打包`
+- `当前进度`
+
+## 脚本
+
+```bash
+node .agents/skills/pm-workflow/scripts/review_stage.js --root . --stage analyze
+node .agents/skills/pm-workflow/scripts/package_delivery.js --root .
+node .claude/skills/pm-workflow/scripts/review_stage.js --root . --stage analyze
+node .claude/skills/pm-workflow/scripts/package_delivery.js --root .
+```
+
+## 流程规则
+
+- 下游文档如果改变需求、平台、范围、功能编号、技术约束、页面路径或验收标准，必须同步回写上游源文档，并在 `docs/workflow-state.json` 的 `notes` 记录。
+- 需求分析必须基于高频真实需求和真实使用流程识别真需求与伪需求，合并同类能力，避免功能清单堆叠。
+- UI 页面访问逻辑必须从真实使用流程推导，页面数量以完成高频路径为准，能合并的页面/模块必须合并并记录理由。
+- UI 原型页面可见文案、按钮、导航、空状态和提示语禁止使用 emoji；图标必须使用图标库、SVG 或图片资源。
+- UI 正文、表单、按钮、列表文本默认不小于 16px，辅助说明不得低于 14px。

package/.codex/templates/project-config.md

@@ -0,0 +1,117 @@
+# {{PRODUCT_NAME}} 项目配置
+
+## 真实需求澄清
+
+- 用户原话：
+- AI 理解：
+- 真实需求摘要：
+- 使用人群：
+- 高频真实需求：
+- 使用触发点：
+- 真实使用流程：
+- 用户想达成的结果：
+- 页面访问逻辑约束：
+- 功能整合原则：
+- 当前澄清状态：not_started
+- 用户确认记录：未确认
+
+## 术语与概念对齐
+
+| 用户/AI 提到的词 | 当前理解 | 可能的另一种理解 | 确认状态 |
+|---|---|---|---|
+| 待补充 | 待补充 | 待补充 | 待确认 |
+
+## 澄清完成标准
+
+| 标准 | 当前状态 | 证据或待补 |
+|---|---|---|
+| 产品给谁用 | 未完成 | 待补充 |
+| 用户真正的高频需求是什么 | 未完成 | 待补充 |
+| 解决什么场景问题 | 未完成 | 待补充 |
+| 用户想达成什么结果 | 未完成 | 待补充 |
+| 用户从开始到结束的真实使用流程是什么 | 未完成 | 待补充 |
+| 首版平台与使用设备 | 未完成 | 待补充 |
+| MVP 必须做和暂不做边界，包括功能整合和页面/模块减负原则 | 未完成 | 待补充 |
+| 无阻塞开放问题，包括关键术语和概念没有歧义 | 未完成 | 待补充 |
+
+## 待补材料
+
+| 材料 | 用途 | 状态 |
+|---|---|---|
+| 类似产品或截图 | 帮助判断功能边界和体验预期 | 待补充 |
+| 当前工作方式或替代方案 | 帮助确认真实痛点 | 待补充 |
+| 目标用户示例 | 帮助区分自己用还是多人使用 | 待补充 |
+| 高频使用流程或操作步骤 | 帮助后续减少页面跳转和模块堆叠 | 待补充 |
+
+## 产品定位
+
+- 一句话描述：
+- 目标用户：
+- 核心问题：
+- 平台类型：
+- 使用场景：
+- 高频触发：
+- 核心使用流程：
+- 页面与功能减负原则：
+
+## 六个核心问题
+
+| 问题 | 当前答案 | 待确认点 |
+|---|---|---|
+| 产品是什么 | 待补充 | 待补充 |
+| 平台类型 | 待补充 | 待补充 |
+| 核心场景和高频需求 | 待补充 | 待补充 |
+| 真实使用流程 | 待补充 | 待补充 |
+| 参考产品 | 待补充 | 待补充 |
+| 特殊要求 | 待补充 | 待补充 |
+
+## 关键场景
+
+| 场景 | 用户是谁 | 当前问题 | 希望结果 | 首版是否覆盖 |
+|---|---|---|---|---|
+| 待补充 | 待补充 | 待补充 | 待补充 | 待确认 |
+
+## 高频使用流程
+
+| 步骤 | 用户动作 | 触发原因 | 期望反馈 | 是否高频 | 页面/模块设计提示 |
+|---|---|---|---|---|---|
+| 待补充 | 待补充 | 待补充 | 待补充 | 待确认 | 待补充 |
+
+## 功能与页面减负原则
+
+- 必须合并的同类能力：
+- 必须避免的页面/模块堆叠：
+- 允许后置的低频能力：
+- 后续需求分析和 UI 设计必须优先服务的高频路径：
+
+## 核心场景
+
+1. 待补充
+2. 待补充
+3. 待补充
+
+## 竞品参考
+
+| 产品 | 优势 | 可借鉴 | 不采用 |
+|---|---|---|---|
+| 待补充 | 待补充 | 待补充 | 待补充 |
+
+## 特殊要求
+
+- 必须有：
+- 明确不要：
+- 约束条件：
+
+## 工作量粗估
+
+- 预计总时长：
+- 初始化与需求：
+- 技术架构：
+- 界面体验与原型：
+- 开发规划：
+- 打包交付：
+
+## 下一步建议
+
+- 推荐下一步：
+- 需要确认的问题：

package/.codex/templates/prototype-README.md

@@ -0,0 +1,45 @@
+# HTML 原型目录
+
+`prototype/index.html` 始终是原型入口。
+
+## 单页面产品
+
+```text
+prototype/
+  directions/
+  index.html
+  layout/
+  assets/
+  review/
+    screenshots/
+```
+
+## 多页面系统
+
+```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 和主要原型页面都要覆盖。 |
+
+界面设计师应根据真实需求动态决定页面数量和结构，但必须沉淀可复用布局，避免原型结构在实际开发中无法稳定复现。原型必须覆盖 P0 功能的可点击路径、成功、失败、空状态、关键异常和主要响应式视口。完整原型交付前必须完成 Playwright 截图和 Impeccable 自审，结果记录到 `docs/prototype-review.md`。
+
+UI 可见文案、按钮、导航、空状态和提示语禁止使用 emoji；图标必须使用图标库、SVG 或图片资源。正文、表单、按钮、列表文本默认不小于 16px，辅助说明不得低于 14px。

package/.codex/templates/workflow-state.json

@@ -0,0 +1,47 @@
+{
+  "project_name": "{{PRODUCT_NAME}}",
+  "current_stage": "init",
+  "recommended_next": "clarify init",
+  "clarification": {
+    "status": "not_started",
+    "summary": "",
+    "missing_context": [
+      "目标用户",
+      "高频真实需求",
+      "核心场景",
+      "用户想达成的结果",
+      "真实使用流程",
+      "首版平台与使用设备",
+      "MVP 必做和暂不做边界",
+      "页面/模块减负边界",
+      "阻塞开放问题",
+      "关键术语和概念歧义"
+    ],
+    "materials_needed": [],
+    "terminology": [],
+    "concepts_aligned": false,
+    "completion_criteria": {
+      "target_user": false,
+      "high_frequency_need": false,
+      "scenario_problem": false,
+      "desired_outcome": false,
+      "core_usage_flow": false,
+      "first_platform": false,
+      "mvp_boundary": false,
+      "no_blocking_questions": false
+    },
+    "user_confirmed_at": null
+  },
+  "pending_user_questions": [],
+  "user_confirmation_required": true,
+  "artifacts": {
+    "init": ["docs/project-config.md"],
+    "analyze": [],
+    "architect": [],
+    "design": [],
+    "plan": [],
+    "deliver": []
+  },
+  "reviews": {},
+  "notes": []
+}

package/README.md

@@ -0,0 +1,28 @@
+# PM Workflow Studio
+
+AI 产品开发工作室 CLI。安装后用一条命令生成 Codex 或 Claude Code 可直接使用的产品工作室目录。
+
+## Install
+
+```bash
+npm install -g .
+```
+
+如果你在仓库根目录调试，进入本包目录再安装：
+
+```bash
+cd skills/pm/pm-workflow
+npm install -g .
+```
+
+## Usage
+
+```bash
+pmflow init --ai codex --root ./pm-workflow-demo --name "习惯打卡"
+pmflow init --ai claude --root ./pm-workflow-claude-demo --name "习惯打卡"
+pmflow init --ai auto --name "习惯打卡"
+```
+
+`pmflow` 也提供 `pm-workflow` 命令别名。
+
+`pmflow init` 只依赖 Node.js，不依赖 Python。包内只维护 `.codex/` 和 `.claude/` 两套结构镜像；初始化时按 `--ai` 选择复制对应结构。