paseo-req-kit 0.0.0-stage → 1.7.0-beta.3

package/skills/req/playbooks/change.md

@@ -0,0 +1,51 @@
+# 手册：修改需求
+
+需求方想改一个已经确认过的需求：加一条、删一条、改规则、改验收标准。无论流水线是否在运行都适用。
+
+## 步骤
+
+1. 找到需求并查看状态
+2. 暂停流水线（如在运行）
+3. 只谈变化的部分
+4. 更新需求说明和变更记录
+5. 请需求方确认
+6. 继续开发
+
+## 1. 找到需求并查看状态
+
+按 `{{REQ_KIT_ROOT}}/skills/req/playbooks/status.md` 第 1 步找到功能目录，执行"查看进度"命令，知道现在在哪一步。
+
+需求在另一个工作区（`--list` 的输出中"位置"不是当前工作区）时，告诉需求方到那个工作区的对话中修改，不要在这里改。
+
+已经验收通过、甚至上线的需求，建议作为新需求提出（用 `new.md` 或 `small.md`），在新需求的背景中引用原需求，而不是改旧的 spec。
+
+## 2. 暂停流水线（如在运行）
+
+状态为"运行中"时，说明修改需求需要先暂停：当前步骤做到一半的工作不保留，已完成的步骤保留；改完后会从方案设计开始，在已有方案和代码的基础上只处理变化的部分。确认后执行"暂停"命令。
+
+需求方只是想补充一个不影响已有内容的小细节、而且开发已接近完成时，可以提出另一种做法供选择：先让这次开发完成，再作为一个小改动单独提出。
+
+## 3. 只谈变化的部分
+
+先读 `spec.md`、`alignment.md` 和 `changes.md`（如有）。请需求方说要改什么，复述确认。然后按 `{{REQ_KIT_ROOT}}/skills/requirement-interview/SKILL.md` 的方式，只针对变化的部分提问：
+
+- 改动影响哪些已有的 FR、AC、规则
+- 新增或改动的部分的异常、边界、权限
+- 与已确认内容有冲突的地方，请对方选择
+- 改动后怎么算做对了（新的或修改后的 AC）
+
+问答记入 `alignment.md`（新的小节，标明"第 N 版修改"）。
+
+## 4. 更新需求说明和变更记录
+
+- 改 `spec.md`：顶部"版本"加 1，"状态"改回 `- 状态：草稿`。保留已有编号：删除的需求注明"已取消（第 N 版）"而不是删掉编号；新增的接着往后编号。按 `{{REQ_KIT_ROOT}}/skills/spec-writing/SKILL.md` 的清单自查。
+- 在 `changes.md` 末尾追加一节，格式见 `{{REQ_KIT_ROOT}}/contracts/feature-files.md`：变更内容、原因、对进度的影响、提出人。
+
+## 5. 请需求方确认
+
+给出变更摘要（改了什么、对进度的影响），确认后把状态改为 `- 状态：已确认（<日期>）`，提交 `spec.md`、`alignment.md`、`changes.md`。
+
+## 6. 继续开发
+
+- 之前已经启动过流水线：执行"继续"命令。流水线发现 spec 变了，会从方案设计开始，在已有方案和代码的基础上只处理变化的部分（通常比第一次快）。告诉需求方这一点。
+- 还没有启动过：问是否现在开始，同意后执行"启动"命令。

package/skills/req/playbooks/incident.md

@@ -0,0 +1,55 @@
+# 手册：上线后发现的问题
+
+需求方报告已上线（或已合并）的功能有问题。把问题问清楚，关联到原来的需求，生成一份缺陷说明，按小改动的流程修复。
+
+## 步骤
+
+1. 判断紧急程度
+2. 问清现象
+3. 关联原需求
+4. 写缺陷说明
+5. 请需求方确认
+6. 启动修复
+
+## 1. 判断紧急程度
+
+先问一个问题：这个问题现在是否正在影响真实用户或数据（例如无法登录、数据错误、资金相关）？
+
+- **是**：告诉需求方立即联系开发同事或值班人员处理线上情况（回滚、关闭开关、临时修复），这些不在 req-kit 的范围内，流水线也不会碰生产环境。然后继续下面的步骤，为正式修复准备缺陷说明。
+- **否**：继续。
+
+## 2. 问清现象
+
+按 `{{REQ_KIT_ROOT}}/skills/requirement-interview/SKILL.md` 的方式，一次一个问题，问清：
+
+- 现象：看到了什么，预期是什么
+- 复现步骤：在哪个环境、用什么账号或数据、做了什么操作；能否稳定复现
+- 影响范围：哪些用户、多少数据、从什么时候开始
+- 证据：截图、错误信息、日志片段、接口返回（请需求方提供；不要索要或记录生产凭据和个人敏感信息）
+
+能在本地复现的，在当前工作区尝试复现，并告诉需求方结果。
+
+## 3. 关联原需求
+
+用 `start-pipeline --list` 和 `docs/features/` 找到相关的原需求，读它的 `spec.md`、`report.md` 和 `acceptance.md`：
+
+- 原来的验收标准是否覆盖了这个情况？覆盖了但没做对，属于缺陷；没覆盖，可能是需求遗漏，告诉需求方这一点。
+- 原需求在另一个工作区或已经合并：这次修复用新的工作区和新的功能目录，不改原来的功能目录。
+
+## 4. 写缺陷说明
+
+在新的工作区中（必要时先按 `new.md` 第 1 步建议新建 worktree），创建功能目录 `docs/features/<YYYYMMDD>-fix-<英文短名>/`，按 `{{REQ_KIT_ROOT}}/skills/spec-writing/SKILL.md` 写 `spec.md`：
+
+- 顶部：`- 档位：快速`（涉及数据修复、权限或多个模块时用标准档）、`- 类型：缺陷`
+- 背景：现象、影响范围、关联的原需求（功能目录和对应的 FR/AC 编号）
+- 功能需求：修复后应有的行为
+- 验收标准：至少一条复现步骤对应的 AC（修复前失败、修复后通过），加上相邻的不应受影响的行为
+- 已有的错误数据是否需要修正：需要的话单独作为一条需求，并请需求方确认修正规则
+
+## 5. 请需求方确认
+
+给出摘要：问题是什么、修复后会怎样、怎么验证。确认后标记"已确认"并提交。
+
+## 6. 启动修复
+
+问是否现在开始，同意后执行"启动"命令。告诉需求方：修复完成后照常验收（`accept.md`），验收通过后请开发同事合并上线。

package/skills/req/playbooks/new.md

@@ -0,0 +1,83 @@
+# 手册：新需求
+
+## 步骤
+
+1. 确认工作区
+2. 阅读项目资料
+3. 听需求并复述
+4. 判断规模，确定档位和执行方式
+5. 访谈
+6. 写需求说明并自查
+7. 独立审阅
+8. 请需求方确认
+9. 启动开发
+
+## 1. 确认工作区
+
+每个需求最好在自己独立的 worktree 工作区中进行：流水线会在这个对话的工作目录里运行几个小时并提交代码，独立的工作区不影响项目主目录，几个需求也可以同时进行。
+
+运行 `git rev-parse --git-dir --git-common-dir` 和 `git branch --show-current`：
+
+- **两个路径相同（项目主目录）**：说明上面的好处，用一个选择题请用户选：
+  1. **开发时自动新建工作区**（推荐，不熟悉 worktree 也没关系）：就在这个对话里谈需求，需求说明先写在这里、不提交；启动开发时流水线会为这个需求新建一个 worktree 工作区，把需求说明移过去提交，在那里开发。这个对话不用动，之后的进度、暂停、继续、验收都在这里说。记下这个选择，第 9 步用"启动（自动新建工作区）"命令。
+  2. **自己新建工作区**：在 Paseo 中 **New workspace** → 选择这个项目 → **Isolation** 选 **New worktree** → 起点选主分支（如 `origin/main`），然后在新工作区的对话里重新输入 `/req`。
+  3. **就在这里开发**：到第 3 步之后新建功能分支（见下）。开发期间这个目录会被占用几个小时。
+- **两个路径不同（已在 worktree 中）**：直接继续，使用当前分支，不要再新建分支。
+- **不是 git 仓库**：直接继续，跳过所有分支相关的操作。
+
+## 2. 阅读项目资料
+
+按 `{{REQ_KIT_ROOT}}/skills/requirement-interview/SKILL.md` 中"开口之前"一节阅读项目资料。能从代码和文档得到的答案不拿去问。
+
+## 3. 听需求并复述
+
+请用户用自己的话讲一遍。用两三句话复述你的理解，确认后再往下。
+
+然后确定功能目录：`docs/features/<YYYYMMDD>-<英文短名>/`，例如 `docs/features/20261012-sms-login/`，英文短名用小写字母和连字符。创建该目录。
+
+只有用户在第 1 步选了"就在这里开发"、且当前在默认分支（如 `main`、`master`）上时，才新建并切换到分支 `feature/<功能目录名>`。选了"自动新建工作区"的，不建分支、不提交，留在当前分支上即可。不要动工作区里已有的、与本需求无关的改动。流水线不会在默认分支上提交代码。
+
+## 4. 判断规模，确定档位和执行方式
+
+向用户推荐一个档位，说明理由，请用户确认：
+
+- **快速档**：小改动，影响面窄，不涉及数据结构、权限、计费或对外接口。例如改文案或样式、加一个配置项、调整一个字段的显示。之后按 `small.md` 手册继续（从它的"访谈"一步开始）。
+- **标准档**：其他情况，继续本手册。
+
+拿不准时选标准档。访谈中发现需求比预想的复杂（涉及数据、权限、多个角色或流程），改为标准档并告诉用户。
+
+标准档再确定**执行方式**。项目根目录的 `.requirement-pipeline.json` 中已经写了 `phases.mode` 的，按它来，不问。否则用一个选择题请用户选：
+
+- **连续**（推荐，默认）：研发完成后流水线接着做测试验证，一次跑完。适合本地就能验证的项目。
+- **分阶段**：研发完成、写好提测说明后停下来通知你，由你或测试同事决定什么时候开始测试验证（可以先部署到测试环境、准备测试数据，也可以预约时间）。适合有专门测试、需要测试环境的项目。
+- **只做研发**：只做到提测说明和研发报告，测试由人完成。
+
+选了"分阶段"或"只做研发"的，第 6 步在需求说明头部写上 `- 执行方式：分阶段` 或 `- 执行方式：只做研发`。快速档一律连续，不问。
+
+## 5. 访谈
+
+按 `{{REQ_KIT_ROOT}}/skills/requirement-interview/SKILL.md` 进行访谈，边谈边写 `alignment.md`，直到满足其中"标准档"的结束条件。
+
+## 6. 写需求说明并自查
+
+按 `{{REQ_KIT_ROOT}}/skills/spec-writing/SKILL.md` 写 `spec.md`（顶部 `- 档位：标准`），验收标准按 `{{REQ_KIT_ROOT}}/skills/acceptance-criteria/SKILL.md` 写，然后按其中的清单自查。
+
+## 7. 独立审阅
+
+请另一个模型在确认之前独立审一遍需求说明：执行 `/req` 中的"需求说明审阅"命令。
+
+- 输出"已开始需求说明的独立审阅"：告诉用户正在请另一个模型检查需求说明，通常几分钟，结果会发回这个对话。等待期间可以和用户确认摘要里的其他细节，但先不要把状态改为"已确认"。收到审阅结果的通知后，按通知中的做法处理，然后进入下一步。
+- 输出"跳过"（配置关闭了审阅，或快速档不需要）：直接进入下一步。
+- 输出"未启动"或审阅失败：告诉用户审阅没能进行，直接进入下一步，不影响开发。
+
+## 8. 请需求方确认
+
+按 `spec-writing` 中"确认"一节：给出 10 行以内的摘要，确认后把状态改为"已确认"并提交。选了"自动新建工作区"的，只改状态、不提交（不在默认分支上提交），启动时流水线会在新工作区中提交。
+
+## 9. 启动开发
+
+告诉用户需求说明保存在哪里，然后问是现在开始开发，还是预约一个时间开始（例如晚上或明天早上，机器空闲、额度充足的时候）。说明三点：开发在后台进行，通常需要几个小时；过程中不需要盯着；有进展、需要他们决定或完成时，会在这个对话里通知。
+
+执行方式是"分阶段"的，顺便问用户是否要在研发完成后的某个时间自动开始测试验证；要的话在启动命令后加 `--verify-at <时间>`。
+
+用户想预约时，执行"预约启动"命令（选了"自动新建工作区"的加上 `--worktree`），把预约的时间告诉用户，并说明到时会在这个对话里自动开始、想取消就说"先停一下"。用户同意现在开始后，执行 `/req` 中的"启动"命令；第 1 步选了"自动新建工作区"的，执行"启动（自动新建工作区）"命令，并把输出中的新工作区位置告诉用户（在 Paseo 侧边栏中可以看到它）。用户没有同意时，告诉他们之后随时说"开始开发"即可。

package/skills/req/playbooks/small.md

@@ -0,0 +1,48 @@
+# 手册：小改动
+
+适用于影响面窄的改动：改文案或样式、加一个配置项、调整一个字段的显示、修一个明确的小问题。不涉及数据结构、权限、计费或对外接口。走快速档：开发流程每个环节只做一轮，通常更快完成。
+
+## 步骤
+
+1. 确认工作区
+2. 听需求并复述
+3. 访谈（2–3 个关键问题）
+4. 写简版需求说明
+5. 请需求方确认
+6. 启动开发
+
+## 1. 确认工作区
+
+同 `{{REQ_KIT_ROOT}}/skills/req/playbooks/new.md` 第 1 步。快速改动也建议用独立的 worktree 工作区，但用户想在当前目录做时不必坚持。
+
+## 2. 听需求并复述
+
+请用户讲一遍要改什么。快速看一下相关代码或页面，用一两句话复述，包括你看到的现状（"现在这个按钮写的是'提交'，你想改成'提交审批'，对吗？"）。
+
+建功能目录 `docs/features/<YYYYMMDD>-<英文短名>/`；第 1 步选了"就在这里开发"、且处于默认分支时，新建并切换到 `feature/<功能目录名>`。
+
+## 3. 访谈
+
+按 `{{REQ_KIT_ROOT}}/skills/requirement-interview/SKILL.md` 的方式提问，但只问清这几件事，通常 2–3 个问题就够：
+
+- 要改什么，改成什么样
+- 哪些地方不改（例如"只改这个页面，其他地方的同名按钮不动"）
+- 怎么算做对了（每条变化一条验收标准）
+
+仍然要在 `alignment.md` 中记录结论。
+
+**升级为标准档的信号**：谈着谈着发现涉及数据、权限、多个角色、对外接口，或者问题超过 3 个还没谈完。这时告诉用户这个需求比预想的复杂，建议改用标准档，同意后切换到 `new.md` 的第 5 步继续。
+
+## 4. 写简版需求说明
+
+按 `{{REQ_KIT_ROOT}}/skills/spec-writing/SKILL.md` 写 `spec.md`，顶部 `- 档位：快速`、`- 类型：小改动`。只保留"背景与目标"（两三句）、"范围"、"功能需求与验收标准"、"假设"几节，其余与这次改动无关的章节省略。按其中的清单自查。
+
+## 5. 请需求方确认
+
+按 `spec-writing` 中"确认"一节，摘要控制在 5 行以内。选了"自动新建工作区"的，只改状态、不提交。
+
+快速档默认不做独立审阅（团队配置为"总是审阅"时，先按 `new.md` 第 7 步执行"需求说明审阅"命令）。
+
+## 6. 启动开发
+
+问用户是否现在开始，同意后执行 `/req` 中的"启动"命令（选了"自动新建工作区"的执行"启动（自动新建工作区）"命令）。流水线会读取 spec 中的"快速"档位。

package/skills/req/playbooks/status.md

@@ -0,0 +1,39 @@
+# 手册：查看进度、暂停、继续
+
+## 步骤
+
+1. 找到功能目录
+2. 执行对应的命令
+3. 转告结果
+
+## 1. 找到功能目录
+
+- 这个对话里已经谈过的需求：用它的功能目录。
+- 否则执行"列出需求"命令。当前工作区只有一个开发相关的需求时用它；有多个时，把它们（标题、阶段）列出来请用户选择。
+- 需求在另一个工作区：暂停、继续、从头重来都要在那个工作区的对话中进行，请用户到那里操作。查看进度可以在这里读它的 `progress.md` 回答。例外：用"启动（自动新建工作区）"开发的需求，研发完成后可以在这里开始测试验证（见 `verify.md`）。
+- 一个也没有：告诉用户当前项目里没有找到需求，问他是不是想提一个新需求，或者需求在另一个项目里。
+
+## 2. 执行对应的命令
+
+命令见 `/req` 中的"开发流水线命令"一节。
+
+**查看进度**（"做到哪了""进展怎么样"）：执行"查看进度"命令。
+
+**暂停**（"先停一下""别做了"）：先确认一次，说明停止后当前步骤做到一半的工作不会保留，已完成的步骤会保留。确认后执行"暂停"命令。暂停命令同时会取消预约的开始、提醒和自动继续；只想取消这些时也用它。
+
+**继续**（"继续开发""接着做"）：执行"继续"命令。
+- 如果上次停在"需要需求方决定"，或者 spec 在暂停期间改过，流水线会从方案设计开始，在已有方案和代码的基础上处理变化的部分，提前告诉用户这一点。
+- 输出"未启动"时，按 `/req` 中的说明处理。
+
+**研发完成，待测试验证**（分阶段执行，查看进度显示这个状态时）：告诉用户下一步是提测，转到 `verify.md` 手册。用户说"继续"时也按 `verify.md` 处理，不要直接执行继续命令。
+
+**从头重来**：只有用户明确要求放弃之前的结果时才执行"从头重来"命令，执行前确认一次。
+
+## 3. 转告结果
+
+按 `{{REQ_KIT_ROOT}}/skills/result-report/SKILL.md` 用一两句话说明：现在在做什么、已经完成了哪些、进行了多久，有遗留问题或等待决定的事项时一并说明。输出中有"agent 最近在做"几行时（从 Paseo 实时读取），挑一两条用白话转述，例如"正在运行测试""刚修改了登录接口"，不要原样贴命令。
+
+用户想看细节时，可以告诉他：
+- 每个步骤都在这个对话的子 agent 列表里，点开可以看到它的工作过程。
+- 功能目录下的 `progress.md` 按时间记录了每一步的结果。
+- 出问题时，`.pipeline/pipeline.log` 是运行日志。

package/skills/req/playbooks/takeover.md

@@ -0,0 +1,51 @@
+# 手册：接手需求
+
+需求方要接手别人提出的需求，或者隔了一段时间回来想知道一个需求的情况。讲清现状和待决事项，然后转入对应的手册。
+
+## 步骤
+
+1. 找到需求
+2. 读全部记录
+3. 讲清现状
+4. 转入下一步
+
+## 1. 找到需求
+
+执行 `node "{{PIPELINE_LAUNCHER}}" --list`，列出这个项目所有工作区中的需求。根据需求方说的名称或描述找到它；拿不准时把候选列出来请对方选。
+
+需求在另一个工作区时，告诉需求方：后续的修改、继续开发、验收都要在那个工作区的对话中进行（流水线的步骤挂在发起的对话下，并在那个目录里工作）。可以在 Paseo 中打开那个工作区，新开一个对话后再输入 `/req 接手 <需求名称>`。这一步只读文件，可以在当前对话完成。
+
+## 2. 读全部记录
+
+按顺序读功能目录中的文件（存在哪个读哪个）：
+
+1. `spec.md`：要做什么、版本、档位
+2. `changes.md`：改过几次、为什么
+3. `alignment.md`：访谈中定下的事和假设
+4. 状态：执行"查看进度"命令（只有在需求所在的工作区才能得到准确的运行状态；在别的工作区时，读 `.pipeline/state.json` 和 `progress.md`）
+5. `handoff.md`（提测说明，有就读）、`report.md`、`acceptance.md`：改了什么、结论、遗留问题、验收结果
+6. `decisions.tsv`：`needs_human` 为 `yes` 且还没有被确认的决定
+
+## 3. 讲清现状
+
+按 `{{REQ_KIT_ROOT}}/skills/result-report/SKILL.md` 的"接手"场景说明，不超过 10 行：
+
+- 这个需求要做什么（一两句）
+- 现在在哪个阶段：对齐中 / 已确认未开发 / 开发中 / 中断 / 等待决定 / 研发完成待测试验证 / 待验收 / 已验收
+- 待决事项：需要回答的问题、需要确认的决定、遗留问题
+- 建议的下一步
+
+需求方追问细节时，以文件为准回答，并说明出处。
+
+## 4. 转入下一步
+
+按需求方的选择转入对应手册（在需求所在的工作区中）：
+
+| 情况 | 手册 |
+| --- | --- |
+| 还在对齐、spec 未确认 | `new.md` 从第 5 步继续访谈（先读 `alignment.md`，已经定下的不要再问） |
+| 要改需求 | `change.md` |
+| 开发中断或暂停，要继续 | `status.md` 的"继续" |
+| 等待需求方决定 | 用访谈的方式回答问题，更新 spec 后继续（见 `/req` 中"收到流水线通知时"） |
+| 研发完成，待测试验证 | `verify.md`（测试同事接手测试也走这里） |
+| 已完成，待验收 | `accept.md` |

package/skills/req/playbooks/verify.md

@@ -0,0 +1,57 @@
+# 手册：开始测试验证
+
+需求按"分阶段"执行，研发已经完成（状态"研发完成，待测试验证"），现在要提测、开始测试验证。也用于"只做研发"完成后，用户又想让流水线做测试验证的情况。发起开发的人和测试同事都可以用这本手册。
+
+## 步骤
+
+1. 确认需求处在待测试
+2. 讲提测说明
+3. 确定测试方式
+4. 准备测试环境说明（在测试环境中验证时）
+5. 开始或预约
+
+## 1. 确认需求处在待测试
+
+找到功能目录（同 `status.md` 第 1 步），执行"查看进度"命令：
+
+- 状态是"研发完成，待测试验证"：继续。
+- 状态是"已完成"且执行方式是"只做研发"：用户想让流水线来做测试验证时继续；只想自己测试时，转到 `accept.md`。
+- 还在研发（运行中、中断、等待决定）：告诉用户研发还没有完成，按 `status.md` 处理。
+- 需求说明在研发完成后又改过：告诉用户，开始时流水线会先回到研发阶段处理这些修改，研发完成后再提测。
+
+**测试同事在自己的对话里接手**：需求是用"启动（自动新建工作区）"开发的，研发完成后，这个项目任何工作区里的对话都可以开始测试验证，之后的通知会发到这个对话。其他需求要在发起开发的那个工作区的对话中进行；不在那里时，请用户到那个工作区新开一个对话，再输入 `/req 开始测试验证`。
+
+## 2. 讲提测说明
+
+读功能目录中的 `handoff.md`（需求在自动新建的工作区中时，用查看进度输出中的完整路径），用几句话讲给用户听：这次改了什么、自测结果、建议重点测试什么、已知问题、测试前要准备什么。用户可能就是测试同事，按他关心的讲。
+
+## 3. 确定测试方式
+
+用选择题逐个确定，配置里已经定好、用户也没有异议的不必再问：
+
+1. **在哪里验证**：
+   - **本地**（推荐，项目能在本机跑起来时）：流水线在本地启动服务验证。
+   - **已部署的测试环境**：版本已经（或即将）部署到测试环境，在那里验证。需要下一步写好测试环境说明。
+2. **发现缺陷怎么办**：
+   - **当场修复并复验**（推荐，默认）。
+   - **退回研发**：只记录缺陷，回到研发阶段修复、经过代码评审后重新提测。团队要求测试发现的问题必须走研发流程时选它。
+   - **只记录**：只出缺陷清单和报告，不修复。
+
+选择和配置不同时，在第 5 步的命令中加上 `--verify-env local|deployed`、`--defects fix|handback|report`。
+
+## 4. 准备测试环境说明（在测试环境中验证时）
+
+在功能目录中写 `test-env.md`，格式见 `{{REQ_KIT_ROOT}}/contracts/feature-files.md`。逐项问用户：地址、怎么确认测试环境上是这次的版本、测试账号、口令放在哪里（环境变量或本机文件）、可以用的测试数据、不能碰的东西、怎么清理测试数据。
+
+- **只写口令在哪里取，不写口令本身。** 用户把口令发在对话里时，提醒他换一种方式提供（例如设置环境变量），不要写进任何文件。
+- **只能是测试环境。** 地址或说明看起来像生产环境时，停下来和用户确认；确认是生产环境的，不能用于测试验证。
+- 写完读给用户确认。这个文件不需要提交。
+
+## 5. 开始或预约
+
+问用户现在开始，还是预约一个时间（例如等测试环境部署好之后）：
+
+- **现在开始**：执行"开始测试验证"命令（按第 3 步加上需要的参数），告诉用户测试验证已经开始，完成或发现问题时会通知这个对话。
+- **预约**（例如等测试环境部署好之后）：在"开始测试验证"命令后加 `--at <时间>`，到时 Paseo 定时任务会在这个对话里执行开始命令。把时间告诉用户，想取消就说"先停一下"。
+
+输出"未启动"时按 `/req` 中的说明处理；原因是缺少 `test-env.md` 时回到第 4 步。

package/skills/req-doctor/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: req-doctor
+description: req-kit 体检。检查 req-kit 的安装、本机配置、Paseo daemon 与 agent、当前项目和进行中的流水线，给出 ✓ / ⚠ / ✗ 清单和修复方法。在 /req 报错、升级之后、更换 agent 或 Paseo 版本之后，或用户输入 /req-doctor 时使用。
+metadata:
+  opencode/slash: "true"
+---
+
+# req-kit 体检（{{REQ_KIT_VERSION}}）
+
+体检只读取信息，不修改任何文件。
+
+## 执行
+
+在当前工作目录执行（bash、PowerShell、cmd 写法相同）：
+
+```
+node "{{REQ_KIT_ROOT}}/bin/req-doctor.mjs"
+```
+
+它会检查当前工作目录所在的项目。只想检查安装和配置、不检查项目时，加 `--no-project`；不想连接 daemon 时，加 `--offline`。
+
+## 转告结果
+
+1. 先说总体结论：全部正常，或者有几项需要处理。
+2. 逐项说明 ✗（必须处理）和 ⚠（建议处理）：是什么问题、会造成什么影响、怎么修。输出里每项都附了修复方法，照着讲清楚即可；命令原样给出。
+3. 涉及安装目录、本机配置（`~/.req-kit/config.json`）或 Paseo 设置的修改，由用户自己（或开发同事）完成。你不要直接改这些文件，除非用户明确要求。
+4. 修好后建议再运行一次 `/req-doctor` 确认。
+
+## 常见问题
+
+- **skill 版本与安装目录不一致**：在要使用的版本目录中运行 `node install.mjs`。
+- **配置中的 provider 还是示例值，或者在 daemon 中不存在**：在终端运行配置向导 `req configure`（或在安装目录运行 `node install.mjs --configure`），按提示选择即可。向导需要在终端里交互，请用户自己运行，你不要代为运行。
+- **有新版本**（输出中的 ↑ 行）：不是问题，告诉用户可以在终端运行 `req upgrade` 升级；正在运行的流水线不受影响。
+- **连不上 daemon**：确认 Paseo 桌面端或 daemon 在运行；设置了密码时，确认环境变量（默认 `PASEO_DAEMON_PASSWORD`）已设置。
+- **发现卡住的流水线**（状态为运行中但进程已不在）：用 `/req` 说"继续开发"即可从中断处继续。
+- **状态文件需要迁移**：下次继续时会自动迁移并保留备份，无需手动处理。

package/skills/req-retro/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: req-retro
+description: req-kit 复盘。一个需求完成、中断、验收不通过或上线后出问题之后，找出过程中的问题和根因，按"能用机器挡住的不写进文档"的顺序提出改进，并在批准后落地。用户输入 /req-retro 或说"复盘一下这个需求"时使用。
+metadata:
+  opencode/slash: "true"
+---
+
+# req-kit 复盘（{{REQ_KIT_VERSION}}）
+
+复盘的目的不是追责，而是让同样的问题下次不再发生，并且把改进放在最可靠的位置。通常由开发同事或熟悉项目的测试同事运行。
+
+## 步骤
+
+1. 选定需求
+2. 收集事实
+3. 找出问题和根因
+4. 按层次提出改进
+5. 展示并请人批准
+6. 落地并记录
+
+## 1. 选定需求
+
+用户指明了需求就用它；否则执行 `node "{{PIPELINE_LAUNCHER}}" --list`，把最近完成、中断或验收未通过的需求列出来请用户选。复盘只读取需求所在工作区的文件，可以在任意工作区运行；但第 6 步的改动要提交到合适的分支（见下）。
+
+## 2. 收集事实
+
+读功能目录中的文件，只记录事实，先不下结论：
+
+- `progress.md`、`.pipeline/state.json` 中的 `history`：经过了哪些步骤、各几轮、用时、哪一步失败或超时、提醒了几次结果文件
+- `.pipeline/pipeline.log`：错误、权限等待、被忽略的配置
+- `design-review.md`、`code-review.md`：每轮意见的数量和级别，哪些被驳回；有评审小组时看"评审小组意见汇总"
+- `verification.md`：缺陷、未验证项、"建议写入 verify.md 的内容"
+- `service-start.md`：启动是否顺利、是否需要摸索
+- `decisions.tsv`：假设、偏离方案、驳回意见、不修复的问题
+- `report.md`、`acceptance.md`：结论、遗留问题、验收不通过的项及原因
+- `changes.md`、`alignment.md`：需求改过几次、为什么；哪些问题本可以在对齐时问清
+
+需要时可以问用户一两个问题，例如验收不通过的真实原因、上线后出了什么问题。
+
+## 3. 找出问题和根因
+
+列出这次过程中值得改进的问题（通常 2–5 个，没有就如实说没有）。每个问题写清：现象、影响（多花了几轮、几小时，或者做错了什么）、根因。
+
+追问根因直到落到一个可以改的地方，例如：
+
+- 验证步骤每次都要花 40 分钟摸索怎么启动服务 → 根因是项目没有 `verify.md`，或者其中的启动命令过时
+- 评审第 2、3 轮都在提同一类问题（缺少输入校验）→ 根因是项目没有对应的 lint 规则或测试约定
+- 验收时发现需求理解错了 → 根因是访谈中没有追问某类边界情况
+- 实现步骤反复改了不该改的目录 → 根因是项目说明里没有写明这个限制
+
+## 4. 按层次提出改进
+
+每个根因，按下面的顺序选择**最靠前、能解决它**的落点。越靠前越可靠，因为它不依赖模型记得遵守：
+
+1. **项目的自动检查**：测试、lint 规则、类型约束、CI 检查。例如加一条 lint 规则禁止直接拼接 SQL。
+2. **项目配置** `.requirement-pipeline.json`：轮数、超时、档位、agent 选择、评审小组。
+3. **项目说明** `.requirement-pipeline/project-notes.md`、验证方法 `.requirement-pipeline/verify.md`、按步骤说明 `.requirement-pipeline/steps/<步骤>.md`：本项目的约定、命令和坑。
+4. **本机提示词覆盖** `~/.req-kit/prompts.local/`：只有前三层都不适用、并且问题确实出在通用的步骤说明上时才用。它会让这台机器跟随不到新版本对同一提示词的改进，要写明原因。
+5. **req-kit 本身的问题**：例如某个手册的流程有缺陷、引擎行为不合理。不在本地改 req-kit 的文件，而是写一份问题报告草稿（现象、复现方式、相关文件、建议），交给用户提给 req-kit 的维护者。
+
+每条改进写清：针对哪个问题、落在哪一层、具体改什么（文件和内容）、为什么这一层合适、预期效果。只记录在文档里、却能用前两层解决的，要说明为什么没用前两层。
+
+## 5. 展示并请人批准
+
+把复盘结果给用户看：
+
+- 问题和根因（简短）
+- 改进清单，每条附上具体的改动（新文件的内容，或现有文件的差异）
+
+逐条请用户批准、修改或否决。**没有批准的改动一律不做。** 不修改产品代码之外的业务逻辑；第 1 层涉及代码的改动（新增测试、lint 规则），如果用户希望，可以作为一个新的需求用 `/req` 提出，而不是在复盘中直接改。
+
+## 6. 落地并记录
+
+- 批准的第 2、3 层改动：写入文件，提交到项目主分支（推荐在主目录的对话中运行复盘，这样改进对之后所有需求生效）；当前在某个需求的分支上时，提醒用户改进合并之后才对其他需求生效。提交信息例如 `chore(req-kit): 复盘 <功能目录名> 的改进`。
+- 第 4 层：写入 `~/.req-kit/prompts.local/<文件名>`，在文件开头用注释写明原因和日期。不提交（它不在仓库里）。
+- 第 5 层：把问题报告草稿交给用户。
+- 在功能目录中写 `retro.md`：日期、问题与根因、每条改进的落点和处理结果（已落地 / 否决 / 转为新需求 / 已提交给维护者）。随功能目录一起提交。
+
+最后用两三句话告诉用户做了哪些改进、下次会有什么不同。

package/skills/req-setup/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: req-setup
+description: req-kit 项目接入。在项目根目录为 req-kit 生成或更新项目说明、验证方法（实际运行其中的命令）、Paseo 的 paseo.json 和项目配置，确认后提交。新项目第一次使用 /req 之前、项目的构建或测试方式变了、或用户输入 /req-setup 时使用。
+metadata:
+  opencode/slash: "true"
+---
+
+# req-kit 项目接入（{{REQ_KIT_VERSION}}）
+
+为当前项目生成以下文件，让流水线的每个步骤不必每次重新摸索这个项目：
+
+| 文件 | 内容 | 谁读 |
+| --- | --- | --- |
+| `.requirement-pipeline/project-notes.md` | 本项目的约定：包管理工具、目录结构、不能改的地方、提交信息格式、已知的坑 | 流水线每个步骤、`/req` 访谈前 |
+| `.requirement-pipeline/verify.md` | 验证方法：安装依赖、启动服务、运行测试、准备测试数据，命令都实际跑过 | 实现、修复、服务启动、验证、复验步骤 |
+| `paseo.json` | Paseo 的工作区设置（推荐）：新建 worktree 时自动安装依赖、复制本地配置；把常驻服务定义为由 Paseo 管理的服务，每个 worktree 分到独立的端口 | Paseo；流水线在服务启动和验证前通过 Paseo 启动这些服务 |
+| `.requirement-pipeline.json` | 项目配置（可选）：本项目用的 agent、默认档位、轮数、超时 | 流水线 |
+
+格式见 `{{REQ_KIT_ROOT}}/contracts/verify.md`。这个入口通常由开发同事或熟悉项目的测试同事运行。
+
+## 步骤
+
+1. 确认位置
+2. 自己读项目
+3. 只问读不出来的事
+4. 实际运行验证命令
+5. 写文件并展示
+6. 确认后提交
+
+## 1. 确认位置
+
+在项目的根目录（git 仓库根）运行。用 `git rev-parse --show-toplevel` 确认当前目录就是仓库根；不是的话，告诉用户到仓库根目录的对话中运行。不要 `cd` 到别处。
+
+建议在项目主目录、主分支上运行，这样文件提交后，之后从主分支新建的 worktree 都会带上。当前在某个需求的 worktree 中时，提醒用户：提交只在这个分支上，合并后其他需求才能用到。
+
+已经有这些文件时，这次是更新：读出现有内容，只改过时或缺失的部分，最后以差异形式展示。
+
+## 2. 自己读项目
+
+先读，不要先问：
+
+- `README`、`CONTRIBUTING`、`AGENTS.md`、`CLAUDE.md`、`docs/` 下的开发文档
+- 包管理与脚本：`package.json`（scripts、packageManager、engines）、锁文件类型、`Makefile`、`justfile`、`pyproject.toml`、`go.mod`、`pom.xml`、`build.gradle`、`Cargo.toml` 等
+- 测试：测试框架和配置、测试目录、端到端测试工具（Playwright、Cypress 等）
+- 运行：`docker-compose.yml`、`.env.example`、启动脚本、`paseo.json`
+- CI 配置（`.github/workflows/` 等）：它跑的命令通常就是最可靠的验证命令
+- 提交历史：`git log --oneline -20`，看提交信息的格式
+- 功能目录中已有的 `service-start.md`、`verification.md` 里"建议写入 verify.md 的内容"一节（如有）
+
+## 3. 只问读不出来的事
+
+一次一个问题，给选项和推荐。通常只有这些需要问：
+
+- 有没有不能改的目录或文件（例如生成的代码、第三方代码、迁移历史）
+- 测试账号、测试数据从哪里来（只记录位置，不要把真实口令写进文件）
+- 外部服务（短信、支付、邮件）在本地怎么替代
+- 端到端验证用什么方式：现有工具，还是手工按步骤走
+- 这个项目的需求默认走哪个档位，要不要换 agent（不需要就不写项目配置）
+- 项目已经有 `paseo.json` 时，要不要由你补充；没有时，要不要生成（推荐生成，见第 5 步）
+
+## 4. 实际运行验证命令
+
+按读到的做法，依次实际运行：安装依赖、构建或类型检查、代码检查、测试、启动服务并确认就绪、端到端检查（有的话）。每条记录：命令、所在目录、用时、结果（例如"412 个用例全部通过"）。
+
+- 失败的命令不要写成可用。查明原因：是环境问题（缺少服务、缺少配置）就写明准备步骤后重试；是项目本身的问题就写进"已知问题"。
+- 启动的服务、容器在结束前关掉。
+- 生成了 `paseo.json` 的服务定义时，设置环境变量 `PASEO_PORT=<一个空闲端口>` 后手工跑一遍它的启动命令（`node scripts/paseo/with-port.mjs …`），确认服务确实监听这个端口，再关掉。准备命令也照样跑一遍（`copy-local-files.mjs` 需要设置 `PASEO_SOURCE_CHECKOUT_PATH`）。
+- 不连接生产环境，不使用生产凭据，不触发真实的外部动作。
+
+## 5. 写文件并展示
+
+- `verify.md`：按 `{{REQ_KIT_ROOT}}/contracts/verify.md` 的结构，第一行之后写"最后核对：<日期>（/req-setup，<全部命令已运行 / 哪些没能运行>）"。只写实际跑通的命令；跑不通的写在"已知问题"。
+- `project-notes.md`：一条一行，只写对做需求有影响的约定。例如"包管理用 pnpm，不要用 npm""数据库变更必须写成 migrations/ 下的迁移脚本""不要改动 legacy/ 目录""提交信息用 Conventional Commits 格式"。
+- `paseo.json`（Paseo 读取，格式见 Paseo 文档的 Git worktrees 一节）。它会提交、整个团队共用，而团队成员的电脑可能是 macOS、Linux 或 Windows，Paseo 在各系统上用不同的 shell 执行其中的命令（macOS/Linux：bash 和 sh；Windows：准备命令用 PowerShell、脚本用 cmd.exe）。所以**命令一律写成各系统都一样的形式**：只调用程序本身（`npm`、`pnpm`、`node`、`python` 等），不用 shell 的语法——不写 `$变量`、`%变量%`、`$env:变量`，不用 `&&`、`||`、`cp`、`[ -f … ]`、`Copy-Item`。需要读环境变量或判断文件的逻辑交给下面两个脚本：
+  - 把 `{{REQ_KIT_ROOT}}/skills/req-setup/templates/paseo/` 中的 `with-port.mjs` 和 `copy-local-files.mjs` 复制到项目的 `scripts/paseo/`（已有就比较，内容相同不动），和 `paseo.json` 一起提交。它们只依赖 Node.js（req-kit 本来就需要）。
+  - `worktree.setup`：写成数组，一行一条命令。通常是安装依赖（用锁文件对应的命令，例如 `npm ci`、`pnpm install --frozen-lockfile`），以及复制不提交的本地配置：`node scripts/paseo/copy-local-files.mjs .env config/local.json`（来源目录里没有的文件会跳过，不会报错）。
+  - `scripts`：常用的命令写成脚本（如 `test`、`lint`）；常驻服务写成 `"type": "service"`，必须监听 Paseo 分配的端口，不要写死。写法：`node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}`（`{PORT}` 换成 Paseo 分配的端口，同时设置环境变量 `PORT`）；程序本来就读取 `PORT` 环境变量的，`node scripts/paseo/with-port.mjs npm start` 即可。服务之间互相调用的地址，让程序读取环境变量 `PASEO_SERVICE_<名称>_URL`。
+  - 例子：
+
+    ```json
+    {
+      "worktree": { "setup": ["npm ci", "node scripts/paseo/copy-local-files.mjs .env"] },
+      "scripts": {
+        "test": { "command": "npm test" },
+        "web": { "type": "service", "command": "node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}" }
+      }
+    }
+    ```
+  - 团队确定只用一种系统、并且用户明确要求时，才可以用那种系统的 shell 写法；`/req-doctor` 会提示它在其他系统上不能用。
+  - 已有 `paseo.json` 时只补充缺少的部分，不改别人写的内容。
+  - 在 `verify.md` 的启动服务一节注明：服务已定义在 `paseo.json`，由流水线通过 Paseo 启动；同时保留手工启动的命令，供没有 Paseo 时使用。
+- `.requirement-pipeline.json`：只在需要和本机配置不同的设置时才写，例如 `{ "defaultProfile": "quick" }`。不要写 `daemonUrl`、`daemonPasswordEnv`、`teamConfig`，写了也会被忽略。
+- `.gitignore`：确认包含 `docs/features/*/.pipeline/`（流水线的运行状态），没有就建议加上。
+
+把这些文件的内容（更新时是差异）展示给用户，并说明运行验证的结果：哪些通过、哪些没能运行以及原因。
+
+## 6. 确认后提交
+
+用户确认后，只提交这几个文件（以及 `scripts/paseo/` 和 `.gitignore` 的改动）。`paseo.json` 必须提交：Paseo 新建 worktree 时读取的是基准分支上已提交的版本，提交信息例如 `chore(req-kit): 项目接入说明与验证方法`。不 push。
+
+最后告诉用户：之后项目的构建、测试或启动方式有变化时，再运行一次 `/req-setup`；也可以直接编辑这些文件。可以运行 `/req-doctor` 确认项目检查全部正常。