@jspg-ai/coding-bb 0.0.1

package/config/openspec/schemas/spec-driven/schema.yaml

@@ -0,0 +1,247 @@
+name: spec-driven
+version: 2
+description: spec-driven 工作流（项目默认，安装时自动选用）- proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: 概述本次变更的初始提案文档
+    template: proposal.md
+    instruction: |
+      编写 proposal 文档，明确这次变更"为什么"要做。
+
+      **写作流程（四阶段顺序执行，禁止跳过或颠倒）：**
+
+      ### 阶段一：收集需求（第一步永远是问用户，禁止先扫代码）
+
+      1. 用 AskUserQuestion 询问用户：本次想做什么？是否有 PRD / MRD / 需求文档链接？
+      2. 拿到用户输入后，整理并复述目标，**让用户确认**理解是否正确。未确认前禁止进入下一阶段。
+      3. 信息不足或目标模糊时，继续追问，直到目标清晰无歧义。
+
+      ### 阶段二：查阅知识库（需求确认后，代码扫描前）
+
+      1. 询问用户是否有知识库、参考文档等可提供。
+      2. 若有知识库：通过 INDEX.md（路径见 CLAUDE.md "知识库" 章节）按层级进入。从 INDEX.md → 域索引 → 子域 → 知识条目。仅跟随索引中的已有链接，**禁止 glob 或全库搜索**。记录每个被引用的文档。
+      3. 若无知识库或 INDEX.md 不存在：记录"知识库暂无覆盖"，直接进入阶段三，**禁止编造或强行搜索**。
+
+      ### 阶段三：扫描代码（带着确认后的目标 + 知识库结果去扫）
+
+      1. 以阶段一确认的目标和阶段二收集的知识库为上下文，扫描代码库。
+      2. 只扫与本次需求相关的入口类/方法、已有实现、依赖链。**禁止无目标的全库扫描**。
+      3. 扫描结果应直接支撑「四、代码改动清单」的编写。
+
+      ### 阶段四：撰写 proposal
+
+      以上三阶段完成后，才开始动笔写 proposal.md。
+
+      **写作约束：**
+      - **禁止推测**：需求细节必须来自上述三阶段的产出；信息不足时回退到对应阶段补充
+      - **来源标注**：一、为什么 / 二、变更简述 / 三、变更清单 / 四、代码改动清单 / 五、影响 中每一条断言后附来源，示例：
+        - "（来自 PRD §3.2）"
+        - "（知识库: myb-user-domain/auth-flow.md）"
+        - "（代码: com.x.user.facade.UserFacade#resetPassword）"
+      - **存疑必问，禁止猜测**：撰写过程中遇到以下情况，必须暂停并用 AskUserQuestion 让用户决策，禁止自行假设后继续：
+        - 需求逻辑不合理或自相矛盾
+        - 信息缺失无法判断（不确定调用哪个接口、数据从哪来等）
+        - 存在潜在风险（资损、性能、兼容性、安全）
+        - 多种可行方案各有取舍
+        每次向用户确认后，将决策逐条记录到「六、决策记录」表格中。
+      - **知识库引用**还应一并带到 design.md 的"知识库参考"章节
+
+      章节（顺序：动机 → 变更简述 → 能力契约 → 代码入口 → 影响 → 决策记录；每章带中文数字序号）：
+      - **一、为什么**（必选）：1-3 句话说清问题或机会。要解决什么？为什么是现在？
+      - **二、变更简述**（必选）：1-5 句话最精简易读地描述本需求要做的事情
+      - **三、变更清单**（必选）：能力维度的变更盘点（新增 / 修改 / 删除）。每个能力对应 `openspec/specs/<name>/spec.md`。identifier 与中文名解耦
+        - **identifier 与展示名解耦**：identifier 列（`能力名` / `现有 spec 名` / `已废弃 spec 名`）填英文 kebab-case（用于 path / CLI / 跨引用），新增一列 `中文名` 填人类阅读用名
+        - **新增能力**：每个对应一份新建 `specs/<name>/spec.md`
+        - **修改能力**：每个对应一份 delta spec 文件
+        - **删除能力**：整段能力下线。spec 文件保留并写 `## REMOVED Requirements` 段，避免后续误用
+      - **四、代码改动清单**（必选）：每个代码入口一行。
+        - **必须基于实际扫代码 + 读知识库得出，禁止凭 PRD 直接推测**
+        - 字段：应用 / 变更类型 / 代码入口类型 / 代码入口 / 所属能力 / 变更简述 / 备注
+        - 后端 代码入口类型 仅允许：rpc / rest / mq / job / sql / config / constant / enum
+        - 前端 代码入口类型 固定为 `前端`；代码入口列允许 `文件路径 —— 简短描述` 自然语言
+        - 代码入口（前端除外）必须可被代码搜索（完整方法签名、REST 路径、MQ topic、SQL 片段、配置 key 等）
+        - `所属能力` 列强制填写：填第三章的能力名（含删除能力）；无对应能力的纯基础设施改动填 `（基础设施）`
+        - `constant` 类型仅当「被 ≥2 个 entry 引用」或「属于业务规则配置」时才单列；其余并入最近上游 entry 的备注
+        - 反向校验：每个 entry 应真的对应一次代码改动，不应"凑行"
+      - **五、影响**（必选）：列出受影响的代码、接口、依赖、上下游系统。**复杂影响分析**（灰度步骤、回滚方案、跨团队协作）进入 § design 阶段
+      - **六、决策记录**（必选）：撰写过程中向用户确认过的每个决策点，逐条填入表格。字段：序号 / 决策点 / 用户决策 / 影响。无决策则填一行"无"
+
+      重要：变更清单章节是 proposal 与 spec 阶段的契约核心。动笔前先研究现有 spec。每列出的能力都对应一份 spec 文件。
+
+      保持简洁（1-2 页）。专注"为什么"而非"怎么做"——实现细节归 design.md。
+
+      这是整个工作流的基础——specs、design、tasks 都建立在它之上。
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: 本次变更的详细规范
+    template: spec.md
+    instruction: |
+      Create spec files defining WHAT the system does — one per capability in the proposal's Capabilities section.
+      - New capability → `specs/<capability>/spec.md` (exact kebab-case name from the proposal).
+      - Modified capability → delta spec at `specs/<capability>/spec.md`, reusing the existing folder name under `openspec/specs/`.
+
+      Use `##` headers for delta operations:
+      - **ADDED Requirements**: new behavior.
+      - **MODIFIED Requirements**: changed behavior — MUST paste the ENTIRE updated requirement block (header through all scenarios), not just the diff. Partial content loses detail at archive time; if only adding concerns without changing existing behavior, use ADDED instead.
+      - **REMOVED Requirements**: MUST include **Reason** and **Migration**.
+      - **RENAMED Requirements**: name-only change, `FROM:`/`TO:` format.
+
+      Format (the template shows the skeleton):
+      - `### Requirement: <name>` + normative description using SHALL/MUST (avoid should/may).
+      - `#### Scenario: <name>` in **WHEN/THEN** form; every requirement needs ≥1 scenario.
+      - **CRITICAL: scenarios MUST use exactly 4 hashtags (`####`)** — 3 hashtags or bullets fail silently.
+
+      Specs must be testable — each scenario is a potential test case.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: 含实施细节的技术方案文档
+    template: design.md
+    instruction: |
+      Create the design document that explains HOW to implement the change.
+
+      **Knowledge Base Reference (MANDATORY):**
+      Before writing design, you MUST consult the project's knowledge base:
+      1. Read the knowledge base root INDEX.md (path defined in CLAUDE.md under "知识库")
+      2. Navigate from INDEX.md → relevant domain index → sub-domain → knowledge chunks
+      3. Collect all knowledge documents relevant to this change's design sections
+      4. Fill the "知识库参考" section in the template with: knowledge point name, full file path, corresponding design section
+      5. If a design section has no matching knowledge base coverage, note it as "知识库暂无覆盖，建议补充"
+
+      Knowledge-to-design-section mapping reference:
+      - 需求背景 → business domain indexes (myb-*-domain/)
+      - 架构设计 → application indexes (project/<app>/)
+      - 领域模型设计 → domain indexes (myb-*-domain/)
+      - 核心流程设计 → domain knowledge chunks
+      - 数据库模型 → application indexes + domain knowledge
+      - MQ设计 → domain knowledge chunks
+      - 稳定性设计 → tech-asset/tech-gray/
+      - 防资损设计 → domain knowledge chunks
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections (follow design.md template):
+      - **知识库参考**（必选）：列出本次设计参考的知识库文档路径及对应章节
+      - **需求或项目背景**（必选）：问题/目标、PRD/DMPT链接
+      - **Checklist事项**（必选）：逐项检查技术风险（新接口、改接口、新枚举、新依赖、新表/MQ、sentinel、敏感数据、SQL、历史兼容、Redis、验签）
+      - **功能拆解**（必选）：按模块拆分功能点，标注变更类型和FTAPI
+        - **必须基于 proposal.md > 四、代码改动清单 展开**：每条功能拆解条目都应可追溯到代码改动清单里的某一行（或几行），禁止平行枚举
+        - **禁止出现代码改动清单之外的 entry 类型**：若需新增 entry 类型，先回退更新 proposal.md 的代码改动清单
+        - 在代码改动清单的基础上补充：工作量估算、字段级细节、上下游协同计划、影响范围
+      - **架构设计**（必选）：模块划分 + 分层依赖关系
+      - **领域模型设计**（可选）：聚合根/实体/值对象/领域事件的变更
+      - **核心流程设计**（必选）：跨服务时序图（仅跨应用时绘制，participant：应用用英文名、操作角色用中文名，禁止类名，同一应用不重复）/泳道图/流程图/状态机，用PlantUML；修改型功能点须包含触发入口及上下至少各一层上下文节点，变更节点统一高亮
+      - **代码设计**（必选）：UML类图（禁止类级别时序图），用PlantUML；修改型功能点须包含触发入口及上下至少各一层上下文节点，变更点（类、方法、属性等）统一高亮
+      - **分层设计**（必选）：Controller/Facade/Service/Repo各层方法与职责，接口契约含请求/响应参数表；依赖RPC标注强弱依赖、超时、降级策略
+      - **数据库模型设计**（可选）：DDL语句及变更说明
+      - **MQ设计**（可选）：Topic、角色、幂等方案
+      - **JOB设计**（可选）：JobHandler、Cron、参数格式
+      - **Redis设计**（可选）：key/value格式、TTL
+      - **配置设计**（可选）：配置key及QA/生产值
+      - **测试策略**（必选）：测试场景与验证点，满足TDD
+      - **稳定性设计**（必选）：发布方案（灰度/兼容）+ 回滚方案 + 监控告警
+      - **防资损设计**（必选）：资损场景、资金流、防控与监控方案
+      - **其他风险/遗留问题**（可选）
+
+      可选章节不涉及则删除整章。所有图用PlantUML生成。**MANDATORY**：画任何图之前，用 Skill tool 调用 `cbb-plantuml-authoring`（该技能包含完整配色方案、图类型选型、语法校验、模板及常见语法坑）。
+
+      【修改型功能点规则】
+      当功能点变更类型为"修改"时，所有图表必须：
+      1. 展示触发入口（REST 接口 / RPC 调用 / MQ 消费者 / Job Handler）
+      2. 展示上游一层（直接调用变更点的调用方节点）
+      3. 展示下游一层（变更点直接调用的被调方节点）
+      4. 变更节点用约定颜色高亮（新增/修改/删除各有对应色，由 cbb-plantuml-authoring 统一）
+      5. 不展示完整调用链，避免图表冗长失焦
+
+      【图表质量准则】
+      - 聚焦核心：每张图聚焦单一业务流程或功能点
+      - 层次鲜明：配色区分入口/新增/修改/删除/未变更节点
+      - 粒度适中：节点粒度为方法或步骤级
+      - 逻辑完整：所有路径有入口和出口，无孤立节点或断链
+
+      以 proposal.md > 一、为什么 为动机来源，以 proposal.md > 四、代码改动清单 为入口范围依据。代码改动清单是「功能拆解」章节的输入，不允许平行重列。specs（specs/**/*.md）提供需求/验收口径。
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: 可追踪的实施任务清单
+    template: tasks.md
+    instruction: |
+      Create the task list that breaks down the implementation work.
+
+      **IMPORTANT: Follow the template exactly.** The apply phase parses checkbox
+      format to track progress. Tasks not using `- [ ]` won't be tracked.
+
+      **Scope note**: tasks.md 是 OpenSpec 的**粗粒度人类可见进度表**。详细 TDD 实施计划（每步：写失败测试 → 跑测试 → 写最小实现 → 跑通 → 提交）由 superpowers:writing-plans 在 apply 阶段单独生成到 `openspec/changes/<name>/plan.md`，不在本文件展开。
+
+      Guidelines:
+      - Group related tasks under ## numbered headings
+      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Tasks should be small enough to complete in one session
+      - Order tasks by dependency (what must be done first?)
+
+      Reference specs for what needs to be built, design for architecture.
+      Each task should be verifiable — you know when it's done.
+
+      Example:
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure
+      - [ ] 1.2 Add dependencies to package.json
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function
+      - [ ] 2.2 Add CSV formatting utilities
+      ```
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Run superpowers TDD pipeline against this change. tasks.md 是人类可见的进度表，详细 TDD 计划由 superpowers 自行生成。
+
+    1. **Generate detailed TDD plan**:
+       - 用 Skill tool 调用 `superpowers:writing-plans`，传入 `proposal.md`、`specs/**/*.md`、以及 `design.md`（如果存在）作为输入
+       - **路径覆盖**: 本项目把 plan 写到 `openspec/changes/<name>/plan.md`（覆盖 writing-plans 的默认 `docs/superpowers/plans/`）。写作时使用 change 名作为输出路径
+       - writing-plans 自己负责 TDD step 结构、任务粒度划分
+    2. **Execute via subagent**:
+       - 用 Skill tool 调用 `superpowers:subagent-driven-development`，目标指向上一步生成的 `plan.md`
+       - subagent-driven-development 自己拥有 implementer / reviewer / fixer 循环和内部进度 ledger
+       - Read `specs/**/*.md` for acceptance criteria
+    3. **Mirror progress to tasks.md**:
+       - subagent-driven-development 报告一个粗粒度任务完成（与 `tasks.md` 中某行 `- [ ] X.Y` 对应）时，把那一行翻成 `- [x]`
+       - **回写粒度**: 每个粗粒度 task 翻一次，**不照 plan.md 里的 TDD step 翻**
+       - OpenSpec 用这些 checkbox 展示进度；subagent 的内部 ledger 才是真实状态源
+    4. **Mid-flight fixes**:
+       - 如果 `plan.md` 路径或测试错了，原地编辑再继续
+       - 如果 `tasks.md` 任务边界与 subagent 报告不对应，原地编辑 tasks.md 以匹配
+
+    `plan.md` 跟 change 同住一个目录，archive 阶段会被一起带走。
+
+verify:
+  tracks: cr.md
+  requires: [tasks]
+  instruction: |
+    Verify 在 tasks.md 全部翻成 `- [x]` 后执行。
+
+    **两条硬性约束(项目级,不被 `cbb update --upstream-openspec` 覆盖,不论官方 verify 命令如何升级都生效):**
+
+    1. **MANDATORY Code Review**:用 `Skill` tool 调用 `superpowers:requesting-code-review`。
+       即便 AI 自认能 review,仍必须调 skill。
+    2. **MANDATORY 产出 `cr.md`**:把完整 Verification Report 写到 `openspec/changes/<name>/cr.md`,
+       缺则视为 verify 未完成。报告必须包含五段:Summary / CRITICAL / WARNING / SUGGESTION / Code Review。