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

package/skills/req-setup/SKILL.md

@@ -0,0 +1,118 @@
+---
+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` 访谈前 |
+| `GLOSSARY.md` | 术语表（推荐）：业务词、含义、代码中的名字。访谈和方案设计会继续补充 | `/req` 访谈、流水线每个步骤 |
+| `.requirement-pipeline/verify.md` | 验证方法：安装依赖、启动服务、运行测试、准备测试数据，命令都实际跑过 | 实现、修复、服务启动、验证、复验步骤 |
+| `paseo.json` | Paseo 的工作区设置（推荐）：新建 worktree 时自动安装依赖、复制本地配置；把常驻服务定义为由 Paseo 管理的服务，每个 worktree 分到独立的端口 | Paseo；流水线在服务启动和验证前通过 Paseo 启动这些服务 |
+| `.requirement-pipeline.json` | 项目配置：**质量门的检查命令**（`checks`，推荐）、关联仓库（`relatedRepos`，有就写）；本项目用的 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（不需要就不写这些项）
+- 有没有相关的其他仓库（例如这是前端，接口在另一个后端仓库）：在这台机器上的位置、它提供什么。登记后流水线的步骤可以只读参考它，不会改动它
+- 多模块的仓库（例如 `web/` 和 `server/` 各有自己的测试）：确认各模块的检查命令，第 5 步按模块写进 `checks`
+- 项目已经有 `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 格式"。再加一节**范例文件**：各类代码（接口、页面、数据访问、测试、迁移脚本等）在项目里写得最好的一个文件，例如"接口：`src/api/orders.ts`；单元测试：`test/api/orders.test.ts`"。方案设计会让每个任务照着范例写，代码更像项目原有的样子。只列你读过、确认写得规范的文件。
+- `GLOSSARY.md`（仓库根目录）：项目还没有术语表时，从代码、文档和界面文字中整理主要的业务词，每条写含义和代码中的名字（类名、字段、接口路径或表名），格式见 `{{REQ_KIT_ROOT}}/skills/requirement-interview/SKILL.md` 的"术语"一节。已有的只补充"代码中的名字"等缺失的部分，不改别人写的含义。拿不准含义的不要写，留给访谈时问。
+- `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`：
+  - `checks`（推荐）：质量门的检查。流水线会在写代码和修复的步骤之后**自己运行**它们，只拦"改动之前通过、现在失败"的检查，并把输出发回给那一步的 agent 修复，不依赖 agent 自己说"测试通过了"。把第 4 步实际跑通、几分钟内能跑完的检查写进去：格式、lint、类型检查、单元测试、构建（端到端测试和需要启动服务的检查不要写，它们由功能验证负责）。命令同样写成各系统通用的形式。多模块的仓库按模块分开写，用 `cwd` 指定模块目录（这项检查只在该模块有改动时运行；需要更精确时用 `paths` 列出它关心的目录）：
+
+    ```json
+    {
+      "checks": [
+        { "name": "lint", "command": "npm run lint" },
+        { "name": "web 测试", "command": "npm test", "cwd": "web" },
+        { "name": "server 测试", "command": "npm test", "cwd": "server", "timeoutMinutes": 15 }
+      ]
+    }
+    ```
+  - `relatedRepos`（有关联仓库时）：`[{ "name": "后端", "path": "../backend", "role": "提供登录和订单接口" }]`。`path` 写相对项目目录的路径（团队约定把相关仓库放在同一个上级目录最方便），也可以写 `~/` 开头的路径。平时流水线的步骤只读不改；需求说明写了"联合开发"时，流水线会为这个需求在它那里新建工作区，一起开发。关联仓库最好也运行过 `/req-setup`，它自己的检查命令、验证方法和项目说明会用在它的步骤里。
+  - 其他设置只在需要和本机配置不同时才写，例如 `"defaultProfile": "quick"`。不要写 `daemonUrl`、`daemonPasswordEnv`、`teamConfig`，写了也会被忽略。
+- `.gitignore`：确认包含 `docs/features/*/.pipeline/`（流水线的运行状态），没有就建议加上。
+
+把这些文件的内容（更新时是差异）展示给用户，并说明运行验证的结果：哪些通过、哪些没能运行以及原因。
+
+## 6. 确认后提交
+
+用户确认后，只提交这几个文件（以及 `GLOSSARY.md`、`scripts/paseo/` 和 `.gitignore` 的改动）。`paseo.json` 必须提交：Paseo 新建 worktree 时读取的是基准分支上已提交的版本，提交信息例如 `chore(req-kit): 项目接入说明与验证方法`。不 push。
+
+最后告诉用户：之后项目的构建、测试或启动方式有变化时，再运行一次 `/req-setup`；也可以直接编辑这些文件。可以运行 `/req-doctor` 确认项目检查全部正常。

package/skills/req-setup/templates/paseo/copy-local-files.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Written into the project by req-kit's /req-setup. Copies local files that are not committed
+// (for example .env) from the checkout a new Paseo worktree was created from, the same way on
+// macOS, Linux and Windows. Files that do not exist there, or already exist here, are skipped.
+//
+//   paseo.json: "worktree": { "setup": ["npm ci", "node scripts/paseo/copy-local-files.mjs .env"] }
+
+import fs from "node:fs";
+import path from "node:path";
+
+const source = process.env.PASEO_SOURCE_CHECKOUT_PATH;
+const files = process.argv.slice(2);
+if (!source) {
+  console.log("没有环境变量 PASEO_SOURCE_CHECKOUT_PATH（不是 Paseo 新建 worktree 时运行的），跳过。");
+  process.exit(0);
+}
+for (const file of files) {
+  const from = path.resolve(source, file);
+  const to = path.resolve(process.cwd(), file);
+  if (path.resolve(from) === path.resolve(to)) continue;
+  if (!fs.existsSync(from)) {
+    console.log(`跳过 ${file}：来源目录中没有`);
+    continue;
+  }
+  if (fs.existsSync(to)) {
+    console.log(`跳过 ${file}：这里已经有了`);
+    continue;
+  }
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.cpSync(from, to, { recursive: true });
+  console.log(`已复制 ${file}`);
+}

package/skills/req-setup/templates/paseo/with-port.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Written into the project by req-kit's /req-setup. Runs a command with {PORT} replaced by
+// the port Paseo assigned (PASEO_PORT), the same way on macOS, Linux and Windows, whatever
+// shell Paseo uses there (bash, sh, cmd.exe). Also sets PORT for programs that read it.
+//
+//   paseo.json: "command": "node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}"
+//   by hand:    PASEO_PORT=4100 node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}
+
+import { spawn } from "node:child_process";
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error("用法：node scripts/paseo/with-port.mjs <命令> [参数…]（参数中的 {PORT} 换成环境变量 PASEO_PORT）");
+  process.exit(2);
+}
+const port = process.env.PASEO_PORT ?? process.env.PORT;
+if (!port && args.some((a) => a.includes("{PORT}"))) {
+  console.error("没有环境变量 PASEO_PORT：它由 Paseo 提供，手工运行时请自己设置。");
+  process.exit(2);
+}
+const resolved = args.map((a) => (port ? a.replaceAll("{PORT}", port) : a));
+// npm, npx and other .cmd shims need a shell on Windows.
+const windows = process.platform === "win32";
+const child = spawn(resolved[0], resolved.slice(1).map((a) => (windows && /[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)), {
+  stdio: "inherit",
+  shell: windows,
+  env: port ? { ...process.env, PORT: port } : process.env,
+});
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => child.kill(signal));
+}
+child.on("error", (error) => {
+  console.error(`无法启动 ${resolved[0]}：${error.message}`);
+  process.exit(127);
+});
+child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));

package/skills/requirement-interview/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: requirement-interview
+description: req-kit 方法：通过一次一问、带选项和推荐的访谈，把一个需求谈到"换一个人来做也会做出同一个东西"的程度，并边谈边记录到 alignment.md 和 GLOSSARY.md。由 /req 的手册调用；单独使用时也适用于任何需求澄清。
+---
+
+# 需求访谈
+
+## 目标
+
+把需求谈到"换一个人来做，也会做出同一个东西"的清晰程度。访谈的结果之后交给无人值守的开发流水线，流水线里没有人能再回头问，所以**现在没问清楚的地方，后面只能靠猜**。
+
+## 对面是谁
+
+需求方通常是测试、产品经理或项目经理：有一定技术背景，熟悉接口、字段、状态、测试用例、测试环境这些概念，但不读代码。据此：
+
+- 可以直接用他们熟悉的概念提问，例如"这个接口失败时返回什么错误码""列表要不要按创建时间倒序"。
+- 不问代码层面的选择（用哪个框架、怎么拆模块、同步还是异步）。这些由你决定，记入 spec 的"技术假设"。
+- 他们往往最清楚异常流程、测试数据和环境，这些要重点问。
+
+## 开口之前
+
+1. 先读项目里已有的资料：`GLOSSARY.md`（术语表；较早的项目可能叫 `CONTEXT.md`）、`docs/adr/`（已做的决定）、`README`、`CLAUDE.md` / `AGENTS.md`、`.requirement-pipeline/project-notes.md`，以及与需求相关的代码和现有页面、接口。
+2. 能从代码和文档里得到答案的事，不拿去问。可以说"我看到现在的列表是按创建时间倒序的，新功能沿用这个顺序，对吗？"，把发现变成一个确认题。
+
+## 怎么问
+
+**先听，再复述。** 请对方用自己的话把想要的东西讲一遍。用两三句话复述你的理解，确认后再往下问。
+
+**一次只问一个问题。** 每个问题给 2–4 个选项，把你推荐的放在第一个并说明理由。环境里有选择题式的提问工具就用它，否则用带编号的文字选项。对方说"你定"时，采用推荐项，记为假设。
+
+**问结果，不问手段。** 问"提交之后，谁应该在多久之内看到这条记录"，不问"要不要用消息队列"。
+
+**技术限制翻译成可见后果。** 不说"这需要改表结构"，而说"这样做的话，以前的历史订单不会带上这个信息，只有新订单才有。可以接受吗？"
+
+**用具体例子提问。** "张三周五下午 6 点提交了申请，审批人周一才上班，这期间张三看到的状态是什么？"比"审批超时怎么处理"更好回答。
+
+**追问到目的。** 对方说"加一个导出按钮"时，问清楚导出之后拿去做什么。真正的需求常常是另一件事。
+
+**主动问对方没想到的情况：**
+- 出错和中断：输入不合法、提交到一半关掉、重复提交、依赖的服务不可用
+- 反悔：能不能撤销、修改、删除，谁可以
+- 权限：谁能看、谁能改、谁不能看
+- 边界：数量上限、时间期限、空值、超长输入、并发
+- 已有的数据和进行中的业务怎么办
+- 测试：用什么测试数据、在哪个环境验证、有没有现成的测试账号或测试替身
+- 这次明确不做什么
+
+**每条需求都问"怎么算做对了"。** 要一个可以实际检查的答案，它会成为验收标准（写法见 `{{REQ_KIT_ROOT}}/skills/acceptance-criteria/SKILL.md`）。
+
+**控制节奏。** 每谈完一个主题，用一两句话小结"已经定了什么、还剩什么"。对方的说法与现有文档或系统行为矛盾时，直接指出并请对方选择。
+
+**区分"必须问"和"可以假设"。** 猜错会做出错误东西的，一定问；其余的按最合理的理解假设并记录（见原则 `principle-dont-block-on-humans`）。
+
+## 边谈边记
+
+在功能目录下维护 `alignment.md`，每定下一件事就追加一条，不要等到最后再回忆：
+
+```markdown
+## <主题>
+- 问题：<问题>
+- 结论：<定下来的答案>
+- 理由 / 被否的选项：<一句话>
+- 来源：需求方明确确认 / 需求方说"你定"（记为假设）/ 从现有代码或文档得出
+```
+
+**术语。** 出现新的业务或领域术语，或者发现同一个词在不同地方意思不同时，写入仓库根目录的 `GLOSSARY.md`（不存在就创建）：
+
+```markdown
+## <术语>
+<在本项目中的确切含义。一两句话。>
+- 代码中的名字：`<类名、字段名、接口路径或表名>`（从代码中查到的；还没有的不写，方案设计时会补上）
+- 不要与"<容易混淆的词>"混用：<区别>
+```
+
+"代码中的名字"让需求方的说法和代码里的叫法对上：流水线的步骤会用它命名，评审会检查是否一致。
+
+项目里已有 `CONTEXT.md`（旧名）时，先读它；新增的术语仍写入 `GLOSSARY.md`，两者是否合并由开发同事决定。
+
+**重要决定。** 影响以后很多需求、并且不容易推翻的决定（例如"订单号对外展示时一律脱敏"），在 `docs/adr/` 下新建一条记录：`<四位编号>-<英文短名>.md`，写明背景、决定、理由。不确定是否算重要时，不写。
+
+## 什么时候可以结束
+
+**快速档**：要改什么、改成什么样、不改什么、每条验收标准，都有了结论。
+
+**标准档**：下面每一项都有了结论，或被明确标为"假设"或"本次不做"：
+
+- 要解决的问题，以及做成之后怎么衡量
+- 谁会用，在什么场景下用
+- 主流程的每一步
+- 规则（计算方式、状态变化、限制条件）
+- 出错、反悔、权限、边界、已有数据
+- 测试数据和验证环境
+- 本次不做的范围
+- 每条需求的验收标准
+- 优先级：哪些必须有，哪些可以以后再说
+
+还有只有需求方能回答、且答错会导致做错东西的问题时，继续问，不要带着它进入下一步。

package/skills/requirement-kickoff/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: requirement-kickoff
+description: 旧入口，已改名为 /req。用户输入 /requirement-kickoff 时使用：提示改用 /req，并按 /req 继续处理。
+metadata:
+  opencode/slash: "true"
+---
+
+# 旧入口：/requirement-kickoff
+
+用户的话：$ARGUMENTS
+
+这个入口已经改名为 `/req`（req-kit {{REQ_KIT_VERSION}}），功能相同，并且新增了小改动、查看进度、暂停和继续等场景。
+
+1. 先用一句话告诉用户：以后请输入 `/req`（Pi 中为 `/skill:req`），这次照常处理。
+2. 然后读取 `{{REQ_KIT_ROOT}}/skills/req/SKILL.md`，把用户的话当作 `/req` 的输入，按它的说明继续。
+
+这个过渡入口会在 req-kit 2.0 中移除。

package/skills/result-report/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: result-report
+description: req-kit 方法：把流水线的通知、状态和各步骤产物整理成需求方能核对的结果说明，结论先行，分清已验证和未验证，写明证据位置和下一步。由 /req 转述进度、通知、完成报告和接手时调用。
+---
+
+# 结果说明
+
+需求方（测试、产品、项目经理）要根据你的话做决定：是否验收、是否需要回答问题、是否找开发同事。说清楚，并且让他们能自己核对。
+
+## 写法
+
+1. **结论先行。** 第一句话就是结论：做到哪一步了、成没成、要不要他们做什么。
+2. **分清三类。** 已验证（有运行证据）、未验证（说明原因）、有问题（现象和影响）。不要把未验证的说成完成。
+3. **给出证据位置。** 结论来自哪个文件的哪一节，例如"验收对照表见 report.md 第 3 节""AC-2.1 的测试输出见 verification.md"。能用命令复核的，给出命令。
+4. **讲需求和结果，不讲实现。** 可以说接口、字段、页面、测试用例；不说类名、函数名、提交号，除非对方问起。
+5. **下一步具体到动作。** "请按 report.md 的验收对照表逐条试用，AC-3.2 需要用测试账号 B 登录"，而不是"请验收"。
+6. **长度。** 进展一句话；状态两三句；完成或中断不超过 8 行，详细内容指向文件。
+
+## 常见场景
+
+- **进展通知**：一句话，例如"方案已经定了（审核 1 轮），开始写代码"。
+- **查看进度**：现在在做什么、已完成哪些、进行了多久；有等待决定或遗留问题时一并说明。
+- **中断**：在哪一步、原因、日志位置；对方能自己处理的（例如测试服务没启动）给出做法，否则建议找开发同事；处理后怎么继续。
+- **完成**：结论（可以验收 / 有遗留问题 / 未完成），最重要的一两条遗留问题，需要他们确认的决定有几条，下一步做什么。
+- **接手**：这个需求要做什么（一两句）、现在在哪个阶段、有哪些待决事项、接下来建议做什么。
+
+## 数据来源
+
+以文件为准，不凭记忆：
+
+- 进度：`start-pipeline --status` 的输出、`progress.md`
+- 结论和证据：`report.md`、`verification.md`、`code-review.md`
+- 需要人确认的决定：`report.md` 的"需要你确认的决定"、`decisions.tsv` 中 `needs_human` 为 `yes` 的行
+- 需求和变更：`spec.md`、`changes.md`；验收结果：`acceptance.md`

package/skills/spec-writing/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: spec-writing
+description: req-kit 方法：把访谈记录（alignment.md）整理成标准需求说明 spec.md，自查后给需求方一份 10 行以内的摘要请其确认，确认后标记为"已确认"并提交。由 /req 的手册调用。
+---
+
+# 需求说明（spec）
+
+spec 是开发流水线判断"要做什么"的唯一依据。流水线的每一步都会引用它的编号（FR-n、AC-n.m），最终报告也按它逐条对照。
+
+## 写
+
+1. 按模板 `{{REQ_KIT_ROOT}}/skills/spec-writing/spec-template.md` 的结构，把 `alignment.md` 的内容整理成 `<功能目录>/spec.md`。
+2. 填好顶部的几行。流水线读其中四行，写法要保持原样：
+   - `- 状态：草稿`（确认后改为 `- 状态：已确认（<日期>）`）
+   - `- 档位：标准` 或 `- 档位：快速`
+   - `- 类型：新需求` / `小改动` / `缺陷` / `重构` / `评估`：缺陷、重构、评估各有自己的开发做法（见下文"按类型的写法"）
+   - `- 执行方式：分阶段` 或 `- 执行方式：只做研发`：只在用户选了这两种时写；连续（默认）不写这一行。评估不写
+   - `- 联合开发：后端`：这个需求还要改其他仓库时才写，写项目配置 `relatedRepos` 中登记的名称，最多两个，用顿号分开
+   其余几行（版本、格式）给人和 `/req` 看。新需求的版本是 1，每次修改需求加 1。
+3. 快速档可以省略与这次改动无关的章节，但"范围""功能需求与验收标准""假设"必须有。
+4. 写作要求：
+   - 只写"要什么"和"怎么算做对"，不写"怎么实现"。技术上的想法只进入"技术假设"一节。
+   - 每条功能需求有编号（FR-1、FR-2…），每条验收标准有编号（AC-1.1、AC-1.2…），写法见 `acceptance-criteria`（`{{REQ_KIT_ROOT}}/skills/acceptance-criteria/SKILL.md`）。
+   - 没谈到的内容不要自己补。需要补的，回去问，或写进"假设"并说明依据。
+   - 术语与仓库的 `GLOSSARY.md` 一致。
+
+## 按类型的写法
+
+模板按新需求写成。另外三种类型的重点不同，流水线也会按类型走不同的做法：
+
+- **缺陷**：背景写现象、影响范围、从什么时候开始。必须有**复现步骤**：环境、账号或数据、操作、看到的结果、应有的结果。验收标准至少一条"按复现步骤操作，应该看到……"（修复前不通过、修复后通过），再加上相邻的、不应受影响的行为。流水线会先复现再修，复现不了会回来问，所以复现步骤越具体越好。
+- **重构**：目标写改进什么，并且可以检查（例如"订单模块不再引用旧的支付库"）。第一条验收标准是**行为不变**：列出必须保持不变的主要行为（接口、页面、数据、导出的文件），然后是改进目标的验收标准。"本次不做"写明不顺带修改的行为。
+- **评估**：功能需求写成**要回答的问题**（例如"FR-1 现有的订单接口能否支持按门店筛选"），每个问题的验收标准写清楚回答里要有什么（可选方案的对比、影响的模块和功能、工作量和风险、推荐和理由）。范围写明只做评估、不改代码，以及评估的结论用来做什么决定。可以省略"主流程""权限与数据"等与评估无关的章节。
+
+项目有多个模块或多个仓库（例如前端和后端）时，在"范围"中写明这次涉及哪些模块；只改一边、需要参考另一边的，写明参考哪个仓库的什么（例如"后端已有的登录接口"）。
+
+**联合开发**（几个仓库都要改）：头部写 `- 联合开发：<仓库名称>`；"范围"按仓库写各自要做什么；每条验收标准注明由哪个仓库负责，或者是"端到端"（几个仓库一起才能验证）；双方要约定的接口（字段、错误码）在需求层面能说清的写进来，细节由方案设计写成接口约定。
+
+## 自查
+
+写完后逐项检查，发现问题就改：
+
+- 每条 FR 至少有一条可以实际检查的 AC，每条 AC 至少有一组具体的输入和期望输出
+- 异常和边界情况都有对应的 AC，而不是只有正常流程
+- 没有"快速""友好""合理"这类无法检查的词，除非给出了具体标准
+- 各条需求之间没有互相矛盾
+- "测试与验证"一节写明了测试数据和验证环境（快速档可以只写一句）
+- "待确认问题"一节为空。不为空就回去问
+
+## 确认
+
+1. 给需求方一份 10 行以内的摘要：会做什么、不做什么、有哪些假设需要他们知情、他们之后会怎么验收。告诉他们完整文件的位置，愿意的话可以直接打开看。
+2. 请他们确认。提出修改时，回到访谈，改完再自查、再确认。
+3. 确认后，把顶部改为 `- 状态：已确认（<日期>）`。没有确认的 spec 不要标为"已确认"。
+4. 如果是 git 仓库，把功能目录、`GLOSSARY.md` 和 `docs/adr/` 中本次的改动提交到当前分支。只提交这些文件，不 push。提交信息例如 `docs(<功能目录名>): 需求说明已确认`。

package/skills/spec-writing/spec-template.md

@@ -0,0 +1,109 @@
+# <需求名称>
+
+- 状态：草稿 / 已确认（<确认日期>）
+- 档位：标准 / 快速
+<!-- 执行方式选了"分阶段"或"只做研发"时，在这里加一行"- 执行方式：分阶段"或"- 执行方式：只做研发"；连续执行（默认）不写 -->
+- 类型：新需求 / 小改动 / 缺陷 / 重构 / 评估
+<!-- 这个需求还要改其他仓库（例如后端）时，加一行"- 联合开发：后端"，写项目配置 relatedRepos 中登记的名称，最多两个，用顿号分开 -->
+- 版本：1
+- 格式：req-kit/spec@1
+- 需求提出人：<姓名或角色>
+- 功能目录：`docs/features/<YYYYMMDD>-<英文短名>/`
+- 对齐记录：`alignment.md`
+
+## 1. 背景与目标
+
+<现在遇到了什么问题，影响了谁。两三句话。>
+
+**目标**：<做成之后，什么会变好。>
+
+**怎么衡量做成了**：<可以观察或统计的结果。>
+
+## 2. 用户与使用场景
+
+| 角色 | 是谁 | 在什么情况下会用到 |
+| --- | --- | --- |
+| <角色名> | <一句话描述> | <典型场景> |
+
+## 3. 范围
+
+**本次要做**
+- <条目>
+
+**本次不做**（已和需求方确认）
+- <条目>：<不做的原因，或以后再考虑>
+
+<!-- 多模块或多仓库的项目：写明涉及的模块（如 web/、server/）；只改一边时写明参考另一边的什么（如"后端已有的登录接口"） -->
+
+## 4. 主流程
+
+<按顺序描述用户从开始到结束会经历的每一步，以及每一步之后系统的表现。可以提到页面、接口、字段，不写代码实现。>
+
+1. <步骤>
+2. <步骤>
+
+## 5. 功能需求与验收标准
+
+每条需求按下面的格式写。优先级：必须有 / 应该有 / 可以以后再说。验收标准的写法见 `acceptance-criteria`：前置条件、操作、预期结果，简单的可以写成一句话。
+
+### FR-1 <需求标题>（优先级：必须有）
+
+<用一两句话说明用户需要什么，以及为什么。>
+
+验收标准：
+
+- **AC-1.1** <标题>
+  - 前置条件：<数据、账号、环境>
+  - 操作：<做了什么>
+  - 预期结果：<应该看到什么>
+- **AC-1.2** 在<异常或边界情况>下，当<做了什么>，应该<看到什么结果>。
+
+### FR-2 <需求标题>（优先级：…）
+
+…
+
+## 6. 业务规则
+
+| 编号 | 规则 | 例子 |
+| --- | --- | --- |
+| BR-1 | <计算方式、状态变化条件、限制条件等> | <一个具体的例子> |
+
+## 7. 权限与数据
+
+- **谁能看 / 谁能改**：<按角色说明>
+- **涉及的业务信息**：<有哪些信息，哪些是必填，哪些敏感>
+- **已有数据和进行中的业务**：<上线时怎么处理>
+
+## 8. 测试与验证
+
+- **测试数据 / 账号**：<访谈中定下的>
+- **验证环境**：<本地 / 测试环境 / 其他，以及需要的准备>
+- **需求方会怎么验收**：<亲自试用的步骤，或者执行的命令>
+
+## 9. 其他要求
+
+<只写谈到过的。例如：多久之内要有反应、同时多少人使用、需要保留多长时间的记录、哪些设备上要能用。每一条都给出可以检查的标准。>
+
+## 10. 假设
+
+没有得到需求方明确回答、由 AI 按推荐方案定下的事项。需求方请过目。
+
+| 编号 | 假设内容 | 依据 | 如果假设不成立会影响什么 |
+| --- | --- | --- | --- |
+| A-1 | | | |
+
+## 11. 技术假设（给方案设计阶段参考）
+
+访谈中没有问需求方、留给技术方案决定的事项，以及从现有代码中观察到的相关情况。这里的内容不是需求，方案设计时可以调整。
+
+- <条目>
+
+## 12. 待确认问题
+
+<定稿时这一节应该为空。>
+
+## 13. 术语
+
+| 术语 | 含义 |
+| --- | --- |
+| <需求方使用的词> | <在本需求中的确切意思。与仓库的 `GLOSSARY.md` 保持一致> |