@ifrankwang/openspec-agents 0.133.2 → 0.135.0

package/README.md

@@ -11,6 +11,7 @@
 
 - **多工具支持**：Claude Code、Codex、ZCode、DeepSeek Harness（DSH）、OpenCode 均可原生接入。
 - **规范驱动**：直接消费 OpenSpec 变更规范（proposal / design / tasks / specs），流程与规范一一对应。
+- **提案标准化**：内置 OpenSpec 提案标准（关联场景清点、契约变更详列、动笔前访谈与用户确认），一键初始化到任意项目，在提 change 阶段防漏考虑、防拆分割裂。
 - **智能体团队**：不再是单个 AI 从头写到尾，而是「实现者 + 审查者 + 质量把关者」分工协作，结果更稳。
 - **质量门禁**：实现之后经过工具检查、任务验证与多维度质量审查；发现的问题自动回退修复，也可按规则豁免并留痕。任务验证层（任务审查 / 合并审查）以通过（passed）提交时必须逐项确认全部已申报任务（verified_tasks 全覆盖为工具强制门禁）；已通过但漏带确认导致阻塞时，审查者可补交确认结果解除阻塞。simple 模式下验证按性质分流——开发者执行确定性检查并申报，审查者分级复验（低成本项实跑、高成本项核验申报加抽样重放）并专注对抗性判断。
 - **隔离执行**：每个变更在独立的环境中实施，互不干扰；变更完成后合并并清理。
@@ -72,12 +73,26 @@ npm install -D @ifrankwang/openspec-agents
 
 如果已经安装，只需说一句「请运行 openspec-agents 编排流程」即可开工。AI 会负责完成安装、初始化、任务分派与质量把关的全部步骤。
 
+## 标准化提 change（提案标准初始化）
+
+插件内置一套 OpenSpec 提案标准，在「提 change」阶段就把好质量关：
+
+- **关联场景清点**：动笔前以代码检索为证据，枚举变更触及能力的全部消费方（功能入口、共享处理逻辑、数据流下游）；共享处理逻辑变更时全部消费入口必须同一 change 统一适配，防止同一逻辑两边割裂维护。
+- **契约变更详列 / 动笔前访谈门 / 用户确认门**：DDL 与接口契约逐条列明；决策树访谈穷尽疑点；方案摘要经用户确认后才动笔。
+- **任务组实质变更主体**：任务组以真实代码变更为主体，禁止收尾验证组与人工门禁任务。
+
+在装了插件的工具里，于目标项目的**常规主代理会话**（非编排流程中的主代理——编排人格禁止修改文件，无法执行初始化）说一句：
+
+> 初始化 openspec 提案标准
+
+即可把标准写入该项目（`openspec/config.yaml` + `openspec/schemas/spec-driven-standard/`），此后该项目用 openspec 提 change 自动遵循标准。已初始化的项目重跑即升级到最新标准，项目自定义 rules 条目与 context 保留；标准方法论自包含，不依赖任何外部 skill。
+
 ## 工作原理（简述）
 
 1. **输入**：项目中的 OpenSpec 变更规范（变更说明、设计、任务清单、验收规格）。
 2. **分派**：主智能体把任务交给专职智能体——实现者负责写代码，审查者负责检查，质量把关者负责多维验证。
 3. **门禁**：每一步的结论通过检查后才进入下一步；不通过的结论自动回到实现环节修复。
-4. **收尾**：变更完成后自动合并分支并清理执行环境，全程留痕可审计。
+4. **收尾**：变更完成后自动合并分支并清理执行环境；change 的全部任务组完成后，主智能体按状态视图指引汇总部署注意事项（规划文档提取 + 开发者实施补充点）向用户汇报。全程留痕可审计。
 
 ## 独立审查会话
 

package/assets/agents/openspec-main.md

@@ -6,6 +6,7 @@ permission:
   read:
     "*": deny
     "openspec/states/*": allow
+    "openspec/changes/*": allow
   edit: deny
   write: deny
   grep: allow

package/assets/skills/openspec-standard/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: openspec-standard
+description: OpenSpec 提案标准初始化与升级——把标准版提案规则（openspec/config.yaml + spec-driven-standard schema 全套）安装到当前项目，统一后续提 change 的质量门槛（关联场景清点、契约变更详列、动笔前访谈与用户确认）。当用户要求初始化、升级或标准化 openspec 提案标准/提案规范时使用。
+capabilities: ["openspec-standard"]
+---
+
+## 职责
+
+把本 skill 目录 `templates/` 下的标准文件安装到当前项目的 `openspec/` 目录，使该项目此后用 openspec 提 change 时自动遵循统一标准：关联场景清点（共享处理逻辑的变更须与其全部消费入口同一 change 统一适配）、契约变更详列、动笔前访谈门与用户确认门、任务组实质变更主体等。幂等：重跑即把标准升级到插件当前版本，项目自定义内容按下方合并策略保留。
+
+## 前置检查
+
+- 当前项目根不存在 `openspec/` 目录 → 该项目尚未初始化 OpenSpec。提示用户先完成 openspec 初始化（建立 `openspec/` 目录与基础配置）后再执行本 skill，终止。
+
+## 安装/升级流程
+
+1. 读取本 skill 目录 `templates/` 下全部文件。
+2. `openspec/config.yaml`：
+   - 项目尚无该文件 → 直接写入模板内容；
+   - 已存在 → 合并升级：`schema:` 一律改为 `spec-driven-standard`；`context:` 保留项目已有内容（无则用模板内容）；`rules.*` / `operations.*` 各小节中，与标准条目同源的条目替换为模板最新文本，项目自定义条目（模板中不存在的）原样保留并追加在同小节标准条目之后。
+3. `openspec/schemas/spec-driven-standard/`：整目录写入（schema.yaml、README.md、`templates/` 下五个文档模板）；该目录为标准自有内容，已存在时直接覆盖。
+4. 项目既有其它 schema 目录一律不动（既有 change 的 `.openspec.yaml` 可能引用）；在汇报中说明：确认没有 change 再引用旧 schema 后，可手动删除旧目录。
+5. 汇报：本次新建/更新/保留的文件与 config.yaml 条目清单；如项目此前使用其它 schema，说明此后新 change 将使用 spec-driven-standard。
+
+## 约束
+
+- 只允许写 `openspec/config.yaml` 与 `openspec/schemas/spec-driven-standard/` 下的文件，不修改项目其它任何文件。
+- 标准文本原样落盘，不自行改写；项目特化约束（技术栈、分层架构、质量门工具等）属于项目 AGENTS.md，不在本 skill 范围。

package/assets/skills/openspec-standard/templates/openspec/config.yaml

@@ -0,0 +1,39 @@
+schema: spec-driven-standard
+
+context: |
+  项目技术背景、架构约定与工程规范以项目根目录 AGENTS.md 为准。
+  本文件仅承载 OpenSpec 流程的通用规则；与项目相关的特化约束
+  （技术栈、分层架构、数据库约定、质量门、方法论选择等）一律写入
+  项目 AGENTS.md，生成与复核子代理会被指示读取它。
+  explore 模式与 proposal 侧同源同严：凡涉及理清需求，必须按
+  spec-driven-standard schema clarify 指令的决策树访谈方法论逐轮穷尽
+  疑点；疑点未穷尽不得收束结论、不得捕获任何变更工件
+  （proposal/specs/design/tasks），不得以「需求简单」等理由跳过。
+
+rules:
+  proposal:
+    - "关联场景清点（强制）：proposal 动笔前必须完成「关联场景清点」并以代码检索为证据记入 clarify.md 的「关联场景清点（Related-Surface Survey）」小节：枚举本变更触及能力的全部消费方与关联面——功能入口（API 端点、导入/导出入口、定时任务、消息消费、前端调用等）、共享处理逻辑（被多个入口复用的处理链路）、数据模型与数据流下游（表/字段/事件/导出产物的读写双方），每条附代码位置证据（文件/类/方法）。凡共享处理逻辑发生变更，其全部消费入口必须在同一 change 内统一适配，禁止按入口分别提 change 导致共享逻辑两边割裂维护；确需拆分时必须在 proposal.md 单列「拆分边界」小节论证（每个 change 覆盖哪些入口、共享逻辑变更归属哪个 change、入口间契约），并经用户确认。proposal.md 必须单列「关联场景（Related Surface）」小节逐条列出清点结论与划界结论；泛写「无关联影响」而不附检索证据视为 proposal 未完成。"
+    - "契约变更详列（强制）：凡变更涉及 DDL（建表/加列/索引/约束）或接口契约（新增/修改端点、请求响应结构、错误码），proposal.md 必须单列「契约变更点」小节逐条列出——DDL 逐表逐列给全表名、列名、类型、可空性、默认值与用途；API 逐端点给全方法+路径、请求/响应结构变化、新增/修改标记与兼容性影响。泛写「有契约变更」不逐条展开视为 proposal 未完成。"
+    - "动笔前访谈门（强制）：proposal/specs/design/tasks 任一文档动笔前，必须已按 spec-driven-standard schema clarify 指令的决策树访谈方法论完成对用户的访谈——把方案建模为决策树逐轮穷尽疑点：每轮将前提已落定、当前可回答的问题一次性编号抛出并逐题附推荐答案，用户答复后重算下一轮前沿，直到决策树所有分支走完、无未决疑点、无静默假设；访谈问答全程记入 clarify.md（Open Questions / User Answers / 关联场景清点）。事实类问题必须自行查代码与 spec 求证，不抛给用户；疑点未穷尽时禁止写任何文档，不得以「需求简单」等理由跳过。"
+    - "动笔前用户确认门（强制）：proposal/specs/design/tasks 任一文档动笔前，clarify.md 的 Architecture Direction 必须已记录用户对方案摘要的明确确认；未记录时禁止写任何文档——主代理亲自写时先停下向用户补确认，生成子代理则立即终止并向编排方报告，不得以「需求简单」等理由跳过或代用户确认。"
+  specs:
+    - "数据行为需求（如\"系统 SHALL 持久化 X 含审计字段\"）放 spec；物理 DDL 放 design.md。"
+    - "MODIFIED 的需求描述直接给出变更后的终态契约表述（\"系统 SHALL 使用 Y\"），供归档合并时原样落入主 spec；禁止以\"原 X 改为 Y\"的历史对比充当主 spec 内容。"
+    - "同一语义只保留一条需求：修改已有需求用 MODIFIED，不得以新标题重复描述同一能力。"
+  tasks:
+    - "每个任务组必须以实质变更为主体（强制）：组内至少一个任务承载真实的代码/配置行为变更（实现 + 测试）；文档/脚本/部署文档同步、验证、回归、质量门只是随行工作，不构成组的实质内容。任务条数不等于实质——排到末位的剩余工作若只剩同步与验证，必须并入前一个功能组，禁止为其新开组（反例：「阶段二收尾：文档、脚本与全量验证」式收尾组）。"
+    - "任务组覆盖关联入口（强制）：tasks.md 的任务组划分必须覆盖 proposal.md「关联场景」小节划入本 change 的全部消费入口；任一划入入口缺少对应适配任务视为 tasks 未完成。"
+    - "真跨组依赖应拆为独立前置 change，在组标题下用 `> **前置 change：**` 标注，组间不可并行。"
+    - "禁止人工门禁任务：不得生成\"等待用户确认/人工验收/人工回归后再继续\"式的任务或检查点；验证一律以自动化手段（编译、测试、质量门）闭环，确需人工执行的回归留档于 design.md 的 Risks/Migration，不进入 tasks.md。"
+    - "禁止真实调用生产接口的任务：联调与验证只允许本地/测试环境（容器化测试、桩/mock 服务、本地 profile 的 API 测试），生产环境接口调用不得作为任务出现。"
+
+operations:
+  archive:
+    guidance:
+      - "归档前必须完成变更同步：delta 与主 spec 有差异时禁止直接归档。"
+      - "归档同步无条件执行，无需用户确认：delta 与主 spec 存在差异时直接同步后归档，禁止提供\"不同步归档\"选项或就此询问用户；仅当同步失败或一致性校验无法收敛时停止并向用户报告。"
+      - "主 spec 只描述当前契约：应用 MODIFIED 时把\"原 X 改为 Y\"式描述改写为终态表述，已废弃组件（表/类/接口/端点）不得保留在主 spec。"
+      - "delta 出现移除/废弃/不再语义时，必须在主 spec 删除对应需求或场景，并在 delta spec 补写 `## REMOVED Requirements` 保持可追溯。"
+      - "同一语义只保留一条需求：与已有需求重叠时合并，不得新增重复标题。"
+      - "同步收敛：同步完成后主 spec 须完整反映 delta——ADDED 已存在、MODIFIED 为终态、REMOVED 已消失。"
+      - "归档前运行 `openspec validate` 校验 MODIFIED 与主 spec 一致性，并核对主 spec 无变更式表述残留、无 REMOVED 残留、无重复需求、无空 spec 目录、无残留 TBD；未通过先修复。"

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/README.md

@@ -0,0 +1,78 @@
+# OpenSpec Schema: spec-driven-standard
+
+通用 spec-driven 工作流模板：clarify → proposal → specs → design → tasks，
+增强三点：
+1. **clarify 前置门槛 + 关联场景清点**：每次变更先做需求澄清与关联场景清点
+   （枚举变更触及能力的全部消费方——功能入口 / 共享处理逻辑 / 数据流下游，
+   附代码证据；共享处理逻辑变更须与其全部消费入口同一 change 统一适配）；
+   访谈结束后、写任何文档之前，主代理必须先向用户简单直接汇报方案（一句话
+   讲清做什么 + 是否动契约 + 取舍 + 影响面）并取得用户明确确认（HARD-GATE，
+   访谈中的问答不视为确认），确认记录落在 clarify.md，后续文档不得偏离。
+2. **主代理访谈直录 + 分级撰写 + 独立复核循环**：主代理亲自访谈，问答
+   直接记入 clarify.md（访谈阶段唯一落笔的文档，不设独立访谈文件）；
+   架构方向经用户确认后，按复杂度分级产出其余文档（proposal → specs →
+   design → tasks，不逐文档分派）——简单变更由主代理本人按依赖顺序撰写
+   （省 token），复杂变更派发唯一一个独立生成子代理在同一会话内撰写（保
+   主代理上下文精简），分级判定与理由记入 clarify.md；无论哪级，主代理
+   必须派发独立复核子代理全量检查（结构校验 + 规则核对 + 与主 spec 交叉
+   核对），发现问题由主代理本人修复后再次复核，循环最多 3 轮，复核干净
+   通过（PASS）才算完成。完整三阶段编排契约写在 clarify 的 instruction
+   里——这是主代理必读的一份，复核派发由此可达；复杂变更的生成子代理
+   最终汇报必须提示主代理进入复核阶段，双保险防契约断链。
+3. **自包含方法论**：决策树逐轮访谈（frontier 机制）全文内联在 clarify
+   instruction 的 Methodology 节，不依赖任何外部 skill。
+
+## 目录
+
+```
+openspec/schemas/<schema-name>/
+├── schema.yaml    # 流程与文档结构定义（纯通用，无项目内容）
+├── templates/     # 各文档模板（纯通用）
+└── README.md      # 本说明
+```
+
+配套文件（一并安装）：项目根 `openspec/config.yaml`（通用流程规则）。
+
+## 接入新项目
+
+**方式一（推荐，插件一键初始化）**：安装了 openspec-agents 插件的 AI 编码
+工具中，在目标项目的常规主代理会话里说一句「初始化 openspec 提案标准」，
+即自动写入本 schema 目录与配套 `openspec/config.yaml`；已初始化的项目重跑
+即升级到最新标准（项目自定义 rules 条目与 context 保留）。
+
+**方式二（手动回退，无插件环境）**：
+1. 把本目录整体 copy 到新项目 `openspec/schemas/spec-driven-standard/`。
+2. 把通用版 `openspec/config.yaml` copy 到新项目，确认 `schema:` 指向
+   `spec-driven-standard`。
+3. 在新项目 `AGENTS.md` 中写清项目特化约束（见下节），并确认每次变更的
+   `.openspec.yaml` 的 `schema:` 字段指向正确。
+
+> 生成子代理（复杂变更时）与复核子代理会被指示读取项目 `AGENTS.md` 与
+> `openspec/config.yaml`，因此项目特化约束写在 `AGENTS.md` 即可自动生效，
+> schema 本身无需改动。
+
+## 项目特化约束清单（写进 AGENTS.md 的内容）
+
+| 类别 | 示例 |
+|---|---|
+| 技术栈 | 语言/框架/版本、构建工具、依赖管理 |
+| 分层架构 | 分层/包组织、依赖方向、层间规则 |
+| 领域约定 | 确定性 vs 不确定性分工、领域模型规范 |
+| 数据库约定 | 表前缀、主键策略、审计字段、逻辑删除、迁移方式 |
+| 质量门 | 格式/静态检查工具、测试策略、覆盖率门槛 |
+| 方法论 | 澄清/评审/开发流程约定（如 TDD） |
+
+## 三层分工（不重复原则）
+
+| 位置 | 承载内容 | 例子 |
+|---|---|---|
+| `schema.yaml` instruction | 生成方法论与文档格式要求（官方方法论为底） | 场景标题 4 个 #、SHALL/MUST、ADDED/MODIFIED/REMOVED、任务组格式、每组自带测试与质量门、关联场景清点维度 |
+| `openspec/config.yaml` rules | **仅** schema 未覆盖的项目补充规则 | MODIFIED 终态契约表述、同语义一条需求、前置 change 标注格式、契约变更详列、访谈门与用户确认门 |
+| 项目 `AGENTS.md` | 项目特化约束 | 技术栈、分层架构、数据库约定、质量门工具、方法论 |
+
+同一规则只写一处：config.yaml rules 不重复 schema instruction 已有内容；
+schema 不写项目专属内容。新增规则时先查上一层的 instruction 是否已覆盖。
+
+官方升级 `openspec update` 会覆盖 `.agents/skills/` 下的 skill，本 schema
+与 config.yaml 不受影响；CLI 升级后可重新对齐官方 `spec-driven`
+（`openspec schema fork`）再叠加本模板的增强段落。