diff --git a/CHANGELOG.md b/CHANGELOG.md index c6e735c..46e42f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## 2026-11-01 — REQ 连续推进(continuous)模式 + +### 新增 + +- `req-workflow` 新增参考文档 `skills/references/continuous-mode.md`(中文):连续模式的目标与边界、阶段循环(做事 → 留证据 → checkpoint → 自动 `/req next`)、门禁分级(hard / soft)、`.ai-proj/req-.state.json` checkpoint 约定与恢复协议、停止格式、staging 段与冒烟验证、反例。 +- `req` 与 `req-workflow` 的 `SKILL.md` 增加 continuous 模式说明:默认自动 `/req next`,自动终点 = staging 部署成功 + 冒烟验证通过;只有 hard 门禁(方案确认、PRD 评审通过、生产发布授权、force、密钥/权限缺失、范围变更)才停下。 + +### 变更 + +- 门禁分级落地:讨论摘要确认、部署范围确认改为 soft 门禁(无人值守下按默认策略继续,把「待用户确认」写入 checkpoint / REQ 备注);「评审必须用户确认」「禁止自审批」保持 hard。 +- 阶段切换新增 checkpoint 约定:每次 `/req next` 前后写 `.ai-proj/req-.state.json`,新会话先读 checkpoint、复核 evidence 再按 `next_command` 继续。 +- 版本:`req-plugin` 2.1.0 → 2.2.0;`req-workflow-plugin` 1.0.0 → 1.1.0。 +- `docs/skill-routing.md` 补 `req` / `req-workflow` 的 continuous 模式指引;`catalog.json` 重新生成。 + ## Unreleased — 2026-10-31 ### 新增 diff --git a/catalog.json b/catalog.json index 4c798c1..9c26340 100644 --- a/catalog.json +++ b/catalog.json @@ -7,7 +7,7 @@ "missing_evals": [], "missing_docs": [] }, - "generated_at": "2026-10-31T21:33:50Z", + "generated_at": "2026-11-01T01:55:45Z", "total": 62, "counts": { "promoted/user-invoked": 18, @@ -710,13 +710,13 @@ { "name": "req", "category": "req", - "version": "2.1.0", + "version": "2.2.0", "status": "promoted", "invocation": "model-invoked", "description": "需求工作流管理。用于 /req 命令使用、需求全生命周期管理(创建→PRD→评审→开发→测试→部署→归档)。当用户提到需求管理、/req 命令、REQ-XXX 相关任务时自动激活。", "description_len": 90, "path": "skills-req/req-plugin/skills/SKILL.md", - "digest": "193cf871b73faff1", + "digest": "1ba369ef4a51c0c7", "has_evals": true, "has_docs": true }, @@ -801,13 +801,13 @@ { "name": "req-workflow", "category": "req", - "version": "1.0.0", + "version": "1.1.0", "status": "promoted", "invocation": "model-invoked", "description": "需求完整工作流。用于从创建到归档的完整流程、Hook 自动同步、测试环境流程。当需要了解需求完整生命周期或同步策略时使用。", "description_len": 61, "path": "skills-req/req-workflow-plugin/skills/SKILL.md", - "digest": "87499da3817d162d", + "digest": "74ec85536d97b8c9", "has_evals": true, "has_docs": true }, diff --git a/docs/skill-routing.md b/docs/skill-routing.md index 46ce631..94afb32 100644 --- a/docs/skill-routing.md +++ b/docs/skill-routing.md @@ -15,7 +15,8 @@ | 任务 | 技能 | | --- | --- | -| 讨论 / 调研 / 对比 | `req`、`req-research`、`req-compare` | +| 讨论 / 调研 / 对比 | `req`、`req-research`、`req-compare`(无人值守推进见 `req-workflow` 的 continuous 模式) | +| 完整流程 / 连续推进 / checkpoint | `req-workflow`(continuous 模式见 references/continuous-mode.md) | | PRD / 原型 | `req-prd`、`req-prototype` | | PRD 评审 | `req-review` | | 设计 / 拆任务 | `req-design`、`dev-arch`、`db-migration` | diff --git a/skills-req/req-plugin/.claude-plugin/plugin.json b/skills-req/req-plugin/.claude-plugin/plugin.json index 6b40015..6b40984 100644 --- a/skills-req/req-plugin/.claude-plugin/plugin.json +++ b/skills-req/req-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "req-plugin", "description": "需求工作流管理入口。用于 /req 命令使用、需求生命周期管理、需求撰写(含草稿门禁)。", - "version": "2.1.0", + "version": "2.2.0", "author": { "name": "qiudl" }, diff --git a/skills-req/req-plugin/skills/SKILL.md b/skills-req/req-plugin/skills/SKILL.md index bc5018c..8d29de3 100644 --- a/skills-req/req-plugin/skills/SKILL.md +++ b/skills-req/req-plugin/skills/SKILL.md @@ -29,21 +29,24 @@ analysis → design → dev → review → testing → [待部署池] → releas - **讨论结束后必须输出方案确认摘要**(强制流程:讨论 → 摘要 → 用户确认 → PRD): 1. AI 输出结构化摘要(`## 讨论结论` 章节),`ai-proj req update` 追加到 description 末尾 2. AskUserQuestion 确认:「方案确认通过」或「需要修改」 - 3. **用户确认后才能开始 PRD 编写,禁止跳过确认** + 3. 用户确认后才能开始 PRD 编写;**无人值守/连续模式下「讨论摘要确认」按 soft 门禁处理** — 在 `## 讨论结论` 标注「待用户确认」并写入 checkpoint 后继续,但不得据此自行变更方案或需求范围(方案/范围变更仍是 hard 门禁) - 需求描述三段式(技术方案写入 PRD,不写在需求中): 1. **需求描述** — 问题背景、现状痛点 2. **预期结果** — 期望达到的效果 3. **验收标准** — 可检查的完成条件(checklist,≥2 条) - PRD 文档是提交评审的前置条件;代码评审是测试的前置条件 -- **force=true 禁止自动使用** — 门禁未通过时必须 AskUserQuestion 确认 + 记录跳过原因 -- **评审必须用户确认** — 禁止 AI 自审批 +- **force=true 禁止自动使用** — 门禁未通过时必须 AskUserQuestion 确认 + 记录跳过原因(**hard 门禁**) +- **评审必须用户确认** — 禁止 AI 自审批(**hard 门禁**) +- **只有 hard 门禁才必须停下问人** — hard:需求方案确认、PRD 评审通过、生产发布授权、`force` 放行、密钥/权限缺失、需求范围变更;硬门禁未清空时禁止推进下一阶段 +- **soft 门禁不停** — 讨论摘要确认、部署范围确认属 soft:无人值守/连续模式下按默认策略继续(摘要写 `## 讨论结论` 后即推进;部署范围按 REQ 关联任务推导),把「待用户确认」写入 checkpoint / REQ 备注,交付时统一列出 +- **每次阶段切换写 checkpoint** — 写 `.ai-proj/req-.state.json`(`stage` / `evidence` / `next_command` / `blockers`),新会话先读它再推进;规则见 `req-workflow` 技能的 `references/continuous-mode.md` - **归档前 AC 逐条验收(Gate 0,强制)** — `/req done` 必须先提取需求描述中的验收标准逐条确认,无 AC 或有未确认项均阻断,用户必须提供证据或说明跳过原因 - **归档前类型化门禁检查** — Gate 0 通过后,`/req done` 再按需求类型(code/skill/ops)动态检查 - **部署是项目级动作**,由 `/req deploy` 统一触发 - **需求完成后必须 git 提交并 push** — commit 格式:`feat(skill): REQ-XXXX 需求标题` - **操作前先确认实际 ID** — 从 URL 提取 ID(如 `/requirements/897` → ID=897) - **务实路线关闭也必须补全关联任务** — 每个进度条阶段需创建关联任务 -- **阶段内容门禁(防空转)** — `/req next` 时检查关键阶段任务是否有实质内容 +- **阶段内容门禁(防空转)** — `/req next` 时检查关键阶段任务是否有实质内容(连续模式下缺内容就补齐文档再推进,不停下等确认) - **复用盘点先于估工(Gate 5,强制)** — PRD 必须含「现有实现与复用盘点」章节:每个能力点给出**现有实现(file:line)+ 结论(复用 / 改造 / 新增)**;结论=复用/改造的只按「接入差异」估工,结论=新增的必须写「为什么现有实现不能满足」。没有 file:line 证据、或标「未排查」的,**禁止 submit、禁止按全新增估工**;独立复查由非 PRD 写作者用 grep 复核并在 note 留命令与命中结果 - **Harness 环境检测** — `/req dev` 启动开发前,快速检测项目基础设施(`.husky/` 存在?`scripts/check-*.sh` 存在?)。若两者都不存在(Level 0),输出一行提示:「项目无质量护栏,建议先运行 `/harness init`」。检测结果不阻塞开发,仅提示 @@ -149,7 +152,7 @@ PDV 结论: ✅ 全部通过 / ❌ {N}项失败,阻断推进 | **testing** | 测试任务有文档,含测试结果表格,含通过/失败结论 | | **staging** | 部署任务有文档,含健康检查结果 | -未通过 → AskUserQuestion(补充文档 or 强制跳过+记录原因) +未通过 → AskUserQuestion(补充文档 or 强制跳过+记录原因);continuous 模式下默认「补文档后继续」并写 checkpoint,不停下等待 ### 部署门禁(推进到 released 前) diff --git a/skills-req/req-workflow-plugin/.claude-plugin/plugin.json b/skills-req/req-workflow-plugin/.claude-plugin/plugin.json index 028eb48..05064c7 100644 --- a/skills-req/req-workflow-plugin/.claude-plugin/plugin.json +++ b/skills-req/req-workflow-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "req-workflow-plugin", "description": "需求完整工作流。从创建到归档的完整流程、Hook 自动同步、测试环境流程。", - "version": "1.0.0", + "version": "1.1.0", "author": { "name": "qiudl" }, diff --git a/skills-req/req-workflow-plugin/skills/SKILL.md b/skills-req/req-workflow-plugin/skills/SKILL.md index 8646227..e963c99 100644 --- a/skills-req/req-workflow-plugin/skills/SKILL.md +++ b/skills-req/req-workflow-plugin/skills/SKILL.md @@ -32,6 +32,19 @@ description: 需求完整工作流。用于从创建到归档的完整流程、H **每个阶段都有明确的任务、检查点和交付物,防止遗漏。** +## 连续推进(continuous)模式 + +默认按连续模式推进:每个阶段「做事 → 留证据 → 写 checkpoint → **自动 `/req next`** → 下一阶段」,**不在阶段边界停发问**。适合 Codex 等无人值守 agent。 + +- **自动终点**:staging 部署成功 + 冒烟验证通过;生产发布属硬门禁,必须人工授权。 +- **硬门禁(停)**:需求方案确认、PRD 评审通过、生产发布授权、`force` 放行、密钥/权限缺失、需求范围变更。 +- **软门禁(不停)**:讨论摘要确认、部署范围确认 —— 按默认策略继续,把「待用户确认」写入 checkpoint / REQ 备注。 +- **checkpoint**:每次阶段切换写 `.ai-proj/req-.state.json`(`stage` / `evidence` / `next_command` / `blockers`);新会话先读它 → 复核 evidence → 从 `next_command` 继续。 +- **staging 段**:部署路径读目标项目 `AGENTS.md` 的 staging 约定,不在本技能写死。 +- **停止**只输出五段:卡点 / 原因 / 已做到哪 / 下一步命令 / 需要谁确认。 + +规则细节(门禁分级表、checkpoint schema、恢复协议、反例)见 [references/continuous-mode.md](references/continuous-mode.md)。 + ## 5 阶段文档 | 阶段 | 文档名 | 技能 | diff --git a/skills-req/req-workflow-plugin/skills/references/continuous-mode.md b/skills-req/req-workflow-plugin/skills/references/continuous-mode.md new file mode 100644 index 0000000..544034d --- /dev/null +++ b/skills-req/req-workflow-plugin/skills/references/continuous-mode.md @@ -0,0 +1,117 @@ +# 连续推进(continuous)模式 + +> 目的:让 Codex 等**无人值守 agent** 能从一个需求一路推进到 staging 验证通过,**只在硬门禁停**。 +> 默认即 continuous;只有用户明确要求「一步一步来 / 每步问我」时才退回逐阶段确认。 + +## 1. 目标与边界 + +- **自动终点**:一个 REQ 从 `/req new` 自动推进到「**staging 部署成功 + 冒烟验证通过**」,并把证据写进 checkpoint。 +- **不在自动范围内**:生产发布(`/req deploy prod`)属**硬门禁**,必须人工授权;`force` 放行、需求范围变更同样必须人工拍板。 +- 每个阶段的文档、任务、证据都要真实落盘(REQ 备注 / 任务文档 / checkpoint),**不得凭记忆或口头声称阶段完成**。 +- 无人值守不等于无人负责:soft 门禁产生的「待用户确认」项必须在 checkpoint 与交付汇报里显式列出。 + +## 2. 阶段循环 + +每个阶段固定四步,**一步不缺**: + +``` +做事 → 留证据 → 写 checkpoint → 自动 /req next → 下一阶段 +``` + +- **做事**:按阶段职责产出交付物(讨论结论 / PRD / 设计 / 代码 + PR / CR 报告 / 测试报告 / 部署记录)。 +- **留证据**:可复核的命令 + 结果(测试输出、CI 链接、健康检查返回、冒烟截图路径),写入 `evidence[]`。 +- **写 checkpoint**:更新 `.ai-proj/req-.state.json` 的 `stage` / `evidence` / `next_command`。 +- **自动下一步**:直接执行 `/req next`(或等价推进命令),进入下一阶段。 + +**禁止在阶段边界停**:不允许以「这一阶段做完了,请确认是否继续」结束回合;`/req next` 的门禁信息门禁走默认补齐流程(补文档后继续)。 + +## 3. 门禁分级 + +| 级别 | 门禁 | 连续模式下的行为 | +| --- | --- | --- | +| **hard(停)** | 需求方案确认 | 停下,等用户拍板方案 | +| **hard(停)** | PRD 评审通过 | 停下;禁止自审批、禁止代替用户放行 | +| **hard(停)** | 生产发布授权 | 停下,等显式授权才能 `/req deploy prod` | +| **hard(停)** | `force` 放行 | 停下,等用户确认并记录跳过原因 | +| **hard(停)** | 密钥 / 权限缺失 | 停下,说明缺什么、谁能给 | +| **hard(停)** | 需求范围变更 | 停下,范围变更必须重新确认 | +| **soft(不停)** | 讨论摘要确认 | 写 `## 讨论结论` 并追加到需求 description,标注「待用户确认」后**继续**写 PRD | +| **soft(不停)** | 部署范围确认 | 按 REQ 关联任务(`linkRole=deploy` / `implementation`)推导默认部署范围,记录推导依据后**继续** | + +**soft 门禁的落地方式**:不停下发问,但必须把「待用户确认」写进两处——checkpoint 的 `blockers[]`(`type: "soft"`)与 REQ 备注;交付时统一列给用户复核。soft 策略只允许「按已有证据推导默认值」,不允许「替用户改变需求范围或方案」。 + +## 4. checkpoint 约定 + +文件路径:项目根 `.ai-proj/req-.state.json`(一台机器一份,按需求 id 分文件;`` 为数值 id)。 + +```json +{ + "req_id": 897, + "stage": "testing", + "updated_at": "2026-11-01T10:20:00+08:00", + "evidence": [ + { + "stage": "dev", + "command": "go test ./... && /req ci", + "result": "pass", + "artifact": "PR #123 / CI run 4567 全绿" + }, + { + "stage": "staging", + "command": "按项目 AGENTS.md 的 staging 部署约定执行", + "result": "deployed", + "artifact": "staging 健康检查 200;冒烟记录 reports/smoke/REQ-897.md" + } + ], + "next_command": "/req test", + "blockers": [ + { "type": "soft", "reason": "讨论摘要待用户确认", "needs": "用户 5 分钟复核" } + ] +} +``` + +- `stage`:当前所在 `delivery_stage`(`analysis` / `design` / `dev` / `review` / `integration` / `testing` / `staging` / `released`)。 +- `evidence[]`:每项 `stage / command / result / artifact`,`command` 要能原样重跑。 +- `next_command`:恢复后要执行的第一条命令,写具体命令而不是「继续推进」。 +- `blockers[]`:每项 `type`(`hard` / `soft`)/ `reason` / `needs`;hard 未清空时不得推进。 + +**恢复协议**(新会话 / 上下文丢失 / 换 agent 时): + +1. 先读 checkpoint;**没有就重建**:`ai-proj req get --id ` + `ai-proj req tasks --id ` 得到真实 `delivery_stage` 与任务状态,再写 checkpoint。 +2. **复核 evidence 是否仍成立**:命令能否重跑通过、artifact 是否还在、REQ 阶段是否被人改过。失效的证据视为未完成,重做该阶段,不要沿用。 +3. 从 `next_command` 继续;`blockers` 里还有 `type: "hard"` 时按 §5 停下。 +4. checkpoint 与 REQ 实际状态冲突时,**以 REQ 状态为准**,修正 checkpoint 后再推进。 + +## 5. 停止格式 + +**只有命中 hard 门禁才停**,停下时固定输出五段: + +``` +卡点:<哪个 hard 门禁> +原因:<触发它的具体事实:报错 / 缺失 / 待授权的动作> +已做到哪:<最后一个有证据的阶段 + 证据位置> +下一步命令:<解除卡点后要执行的第一条命令> +需要谁确认:<用户 / 复核人 / 运维 / 安全> +``` + +除 hard 门禁外**不得停下发问**;soft 门禁只记录、不阻塞。 + +## 6. staging 段(自动终点) + +- 合并与部署到 staging 的**真实路径不在本技能里写死**:先读目标项目根目录的 `AGENTS.md`,按其「staging 部署约定」执行(分支 / 构建 / 部署触发 / 环境地址 / 验证入口)。 +- 项目 `AGENTS.md` 没有 staging 约定,或缺部署权限 → 视为 hard 门禁,按 §5 格式停下。 +- **部署成功 ≠ 完成**:必须做冒烟验证——关键页面可达、核心 API 返回正常、主流程走通、日志无新增报错;把命令与结果写入 `evidence[]`(`stage: "staging"`),这一步通过才算**自动终点**。 +- 冒烟失败:先自行修复重试;同类失败连续两次且判断需要人拍板(环境权限、外部系统、方案本身有问题)→ 按 hard 门禁停。 +- 自动终点之后的一切(生产发布、验收、归档)都需要人工授权,不在 continuous 范围内。 + +## 7. 反例 + +| 反例 | 正确做法 | +| --- | --- | +| 每个阶段结束都 AskUserQuestion 等确认 | soft 门禁记入 checkpoint 后继续,只在 hard 门禁停 | +| 没有 evidence 就写「阶段已完成」 | 先跑命令拿到可复核结果,再写 `evidence[]` | +| 跳过 `/req ci` 直接推进到 review | `/req ci` 是 dev → review 的必跑门禁 | +| 把 staging 部署命令写死在技能里 | 读目标项目 `AGENTS.md` 的 staging 部署约定 | +| 把生产发布当成「下一步自动执行」 | 生产发布是 hard 门禁,必须显式授权 | +| 新会话凭记忆接着干 | 先读 checkpoint 并复核 evidence,再按 `next_command` 继续 | +| 换 agent 后重跑一遍已通过的阶段 | 证据仍成立就跳过,只补做失败或缺失的阶段 |