@chenmk/superflow 0.1.1 → 0.1.2

package/assets/skills-en/api-doc-changelog/SKILL.md

@@ -1,193 +1,106 @@
 ---
 name: api-doc-changelog
-description: >
-  规范 API 联调文档（api.md）的变更标注格式。当编写或更新前后端联调接口文档时，
-  自动在接口和字段级别标注变更类型，让前端 agent 一眼看出两个版本之间改了什么。
-  适用于：写 api.md、更新 api.md、推送飞书前检查文档、SuperBridge Flow 流程生成接口设计。
-  触发词：api文档变更、接口变更标记、changelog、联调文档更新、接口变更标注、
-  变更追踪、接口diff、版本变更、提测文档。
+description: Standardize API documentation changelog annotations. Use when writing or updating api.md, preparing frontend integration docs, marking API/field-level changes, or reviewing API docs before handoff.
 ---
 
-# API 文档变更标注规范
+# API Documentation Changelog Standard
 
-## 为什么需要这个规范
+Use this skill when `api.md` must show what changed between the previous
+baseline and the current delivery. The goal is to make API deltas visible to
+frontend, QA, and integration agents without forcing them to diff a large file.
 
-每次提测新版本时，前端 agent 需要快速回答三个问题：
-1. 这次新增了哪些接口？
-2. 哪些接口的参数/返回值改了？改了哪个字段？
-3. 哪些接口被废弃或删除了？
+## Required Structure
 
-如果这些信息藏在 2000+ 行的文档底部一个概要表格里，前端 agent 基本找不到。
-本规范通过**文档顶部的变更概览 + 接口内联标注**，让变更信息对前端 agent 零门槛可见。
-
----
-
-## 一、文档顶部变更概览
-
-在 `## 1. 通用约定` 之前，插入变更概览节。格式如下：
+Add a changelog overview before the first normal API section:
 
 ```markdown
-## 0. 变更概览（本次提测变更）
+## 0. Change Overview
 
-> 基线版本：v1.0 | 当前版本：v1.1 | 变更日期：2026-05-22
+> Baseline: v1.0 | Current: v1.1 | Date: YYYY-MM-DD
 
-### 新增接口
+### Added APIs
 
-| 接口 | 说明 |
-|------|------|
-| `POST /api/xxx` | 新增 xxx 功能 |
+| API | Summary |
+|-----|---------|
+| `POST /api/example` | Adds example creation |
 
-### 修改接口
+### Changed APIs
 
-| 接口 | 变更摘要 |
-|------|----------|
-| `GET /api/yyy` | 新增 query 参数 `keyword`；响应增加 `tag` 字段 |
-| `PUT /api/zzz/{id}` | 入参 `status` 枚举值新增 `3=待审核` |
+| API | Change Summary |
+|-----|----------------|
+| `GET /api/example` | Adds query parameter `keyword`; response adds `tag` |
 
-### 废弃接口
+### Deprecated APIs
 
-| 接口 | 替代方案 | 移除计划 |
-|------|----------|----------|
-| `GET /api/old` | 使用 `GET /api/new` | v2.0 移除 |
+| API | Replacement | Removal Plan |
+|-----|-------------|--------------|
+| `GET /api/old` | `GET /api/new` | v2.0 |
 ```
 
-### 规则
-
-1. **每次提测必须更新**：推送飞书前，必须刷新变更概览节的内容和日期。
-2. **只写本次变更**：变更概览只记录"上一版基线 → 当前版本"的差量，不是完整历史。
-3. **完整历史在第 8 节**：文档末尾的"接口变更记录"表保留完整历史，格式不变。
-4. **无变更也要写**：如果没有变更，写"本次提测无接口变更，仅修复已知问题"。
-
----
-
-## 二、接口级别内联标注
-
-每个接口的标题行后紧跟变更标签，用方括号标注变更类型：
+If there are no API changes, write that explicitly:
 
 ```markdown
-#### `GET /api/charging-package/templates` `[新增]`
-
-#### `PUT /api/parking-guns/{id}` `[修改]`
-
-#### `DELETE /api/old-endpoint` `[废弃]`
+No API contract changes in this delivery.
 ```
 
-### 标签类型
-
-| 标签 | 含义 | 使用场景 |
-|------|------|----------|
-| `[新增]` | 本次新增的接口 | 全新开发的接口 |
-| `[修改]` | 本次有改动的接口 | 参数、响应、行为有任何变化 |
-| `[废弃]` | 已废弃但暂未移除 | 已有替代方案，但保留兼容 |
-| 无标签 | 本次无变更 | 上个版本就存在且未修改的接口 |
-
-### 规则
-
-1. **只有本次变更的接口才加标签**，稳定接口不加。
-2. 下次提测时，上一轮的标签要**清除**（上一轮的变更已不再是"新"变更）。
-3. 接口标题和标签之间用空格分隔。
+## API-Level Labels
 
----
+For each changed API heading, append one label:
 
-## 三、字段级别内联标注
+- `[Added]`
+- `[Changed]`
+- `[Deprecated]`
 
-在参数表和响应字段表中，变更的字段在"说明"列末尾追加标注：
+Stable APIs from earlier versions do not need labels. Remove old labels during
+the next delivery cycle so labels always mean "changed in this delivery".
 
-### 参数/响应表的标注方式
+Example:
 
 ```markdown
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| name | String | 是 | 套餐名称 |
-| keyword | String | 否 | 搜索关键词 `【本次新增】` |
-| status | Integer | 否 | 状态：1 上架，2 下架，3 待审核 `【枚举值变更：新增 3】` |
-| oldField | String | 否 | ~~已废弃，使用 newField~~ `【本次废弃】` |
+#### `GET /api/orders` `[Changed]`
 ```
 
-### 字段标注类型
-
-| 标注 | 含义 | 在说明列中的写法 |
-|------|------|-----------------|
-| 新增字段 | 本次新增的入参或返回字段 | 追加 `【本次新增】` |
-| 字段修改 | 类型、校验规则、枚举值等有变化 | 追加 `【本次变更：具体改了什么】` |
-| 字段废弃 | 仍在返回但已不推荐使用 | 用删除线 + 追加 `【本次废弃】` |
-| 字段移除 | 不再返回或不再接受 | 从表中移除，在变更概览中说明 |
-
-### 规则
-
-1. 标注追加在说明文字末尾，用 `【】` 包裹，与正常说明文字区分。
-2. 变更描述要**具体**：写"枚举值新增 3=待审核"，不要只写"有变更"。
-3. 下次提测时清除上一轮标注。
-4. JSON 响应示例中不需要标注，以字段表为准。
-
----
-
-## 四、操作流程
+## Field-Level Labels
 
-### 4.1 首次编写 api.md（新模块）
+In request and response field tables, append change notes to the description
+column:
 
-首次编写时不需要任何变更标注，因为没有"上一版"做对比。
-文档正常编写即可，变更概览节写：
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `keyword` | String | No | Search keyword `[Added]` |
+| `status` | Integer | No | Status enum `[Changed: adds 3=Pending Review]` |
+| `oldField` | String | No | ~~Deprecated; use `newField`~~ `[Deprecated]` |
 
-```markdown
-## 0. 变更概览（本次提测变更）
-
-> 首个版本，全部接口为新增。详见接口列表。
-```
+Rules:
 
-### 4.2 更新已有 api.md（迭代开发）
+- Be concrete. Write what changed, not just "changed".
+- Mark added, changed, deprecated, and removed fields.
+- Remove prior delivery labels in the next delivery cycle.
+- JSON examples do not need inline labels; field tables are the source of truth.
 
-1. **读取当前 api.md**，识别所有接口和字段。
-2. **对比代码变更**（git diff、接口实现变化、DTO 字段变化）确定变更范围。
-3. **更新变更概览**：在 `## 0. 变更概览` 节中列出新增/修改/废弃的接口。
-4. **添加接口级标签**：在变更接口的标题行后追加 `[新增]`/`[修改]`/`[废弃]`。
-5. **添加字段级标注**：在变更字段的说明列末尾追加 `【本次新增】`/`【本次变更：...】`。
-6. **清除上一轮标注**：删除上一轮提测的变更标签和字段标注。
-7. **更新第 8 节历史表**：在文档末尾的变更记录表中追加一行。
+## Change Classification
 
-### 4.3 推送飞书前检查
+Mark a change when any of these happen:
 
-推送前确认：
-- [ ] 变更概览节的版本号和日期已更新
-- [ ] 所有变更接口有标签
-- [ ] 所有变更字段有标注
-- [ ] 上一轮的标注已清除
-- [ ] 第 8 节历史表已追加
+- API added, removed, or deprecated.
+- Request parameter added, removed, renamed, made required, or made optional.
+- Response field added, removed, renamed, or type-changed.
+- Enum value added, removed, or meaning-changed.
+- Validation rule, sorting, permission behavior, error code, or idempotency
+  behavior changes.
 
----
-
-## 五、变更判定标准
-
-以下情况算"变更"，必须标注：
-
-| 变更类型 | 示例 |
-|----------|------|
-| 新增接口 | 新增 POST /api/xxx |
-| 删除接口 | 移除 GET /api/old |
-| 新增参数/字段 | 入参增加 keyword 字段 |
-| 删除参数/字段 | 不再返回 oldField |
-| 修改字段类型 | String → Long |
-| 修改枚举值 | status 新增值 3 |
-| 修改校验规则 | 长度限制从 64 改为 128 |
-| 修改必填状态 | 可选 → 必填 |
-| 修改行为逻辑 | 排序规则改变、权限逻辑变更 |
-| 修改错误码 | 新增错误码或修改错误码含义 |
-
-以下情况**不算变更**，不需要标注：
-- 修正错别字
-- 调整文档格式
-- 补充边界说明（不改变接口行为）
-- curl 示例调整（不改变接口契约）
-
----
+Do not mark a change for typo fixes, formatting, or explanatory notes that do
+not change the contract.
 
-## 六、与 SuperBridge Flow 流程的集成
+## Superflow Integration
 
-本规范是 SuperBridge Flow 流程的一部分。在 `superflow-docs` 阶段生成 `api.md` 时：
+During `superflow-docs`:
 
-1. **首次生成**：按本规范第四条第 4.1 款处理，写首个版本标记。
-2. **迭代更新**：按第四条第 4.2 款处理，对比已有 api.md 标注变更。
-3. **推送飞书前**：按第四条第 4.3 款检查清单验证。
+1. If `api.md` is new, write "initial version" in the overview.
+2. If `api.md` exists, compare the current contract against the baseline and
+   update the overview plus inline labels.
+3. Before handoff, verify that frontend-facing changes are visible both in the
+   overview and near the affected API/field.
 
-SDD 的 `api-design-template.md` 中"第 8 节 接口变更记录"继续保留作为完整历史记录。
-本规范新增的"第 0 节 变更概览"是提测时的增量视图，两者互补。
+The full historical API change log can stay near the end of `api.md`; the
+overview is the delivery-specific delta.

package/assets/skills-en/superflow-clarify/SKILL.md

@@ -43,7 +43,7 @@ any full SDD document or implementation prompt is generated.
 - When a feature relies on a status, enum, sync field, derived field, default
   value, or compatibility behavior, freeze the business semantics before API or
   design freezing. Record:
-  `真源字段 | 真源枚举 | 目标字段 | 目标枚举 | 消费方解释 | 业务依据 | 不确定项`.
+  `Source field | Source enum | Target field | Target enum | Consumer meaning | Business basis | Unknowns`.
   Do not treat non-null, present, successful, or "has any value" as correct.
   Do not accept fallback/default/keep-old-value behavior unless the requirement
   or owner explicitly approves it for dirty historical data or uncontrollable
@@ -119,11 +119,11 @@ Use the detailed workflow in:
    clarification questions.
 9. For database-backed behavior, add a table reverse impact table before
    freezing:
-   `表/字段 | 写入方 | 读取/过滤方 | 跨仓/外部消费方 | 真实入口 | 反向状态场景 | 必测用例`.
+   `Table/field | Writer | Reader/filter | Cross-repo/external consumer | Real entry | Reverse-state scenario | Required test`.
    If any consumer or real entry is unknown, mark the feature blocked.
 10. For status/enum/sync/default behavior, add a semantic mapping table before
     freezing:
-    `真源字段 | 真源枚举 | 目标字段 | 目标枚举 | 消费方解释 | 业务依据 | 不确定项`.
+    `Source field | Source enum | Target field | Target enum | Consumer meaning | Business basis | Unknowns`.
     If a proposed default, fallback, old-value retention, or null conversion is
     not explicitly approved by the requirement or owner, mark it rejected and do
     not include it in the design.
@@ -132,7 +132,7 @@ Use the detailed workflow in:
 13. Draft a rough API contract: path, action, core request, core response. Field types can be approximate.
 14. Wait for programmer confirmation of the rough API.
 15. Produce a precise API section with field names, types, requiredness, defaults, enums, errors, examples, and curl.
-16. Mark the feature as `已冻结` only when understanding, rough API, precise API,
+16. Mark the feature as `frozen` only when understanding, rough API, precise API,
     and validation data needs are confirmed or explicitly blocked.
 17. Only after the current feature is frozen or blocked, move to the next
     indexed feature. Do not batch-confirm multiple features from memory or a

package/assets/skills-en/superflow-clarify/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "SDD Clarify"
-  short_description: "需求理解澄清、功能点串行门禁与 API 草案冻结阶段"
+  short_description: "Clarify requirements, confirm features one by one, and freeze API drafts"
   default_prompt: "Use $superflow-clarify to process this requirement one confirmed feature at a time before SDD docs."

package/assets/skills-en/superflow-design/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "SDD Design"
-  short_description: "用 Superpowers 生成源码级技术详设和反向影响面分析"
+  short_description: "Use Superpowers for source-level technical design and reverse impact analysis"
   default_prompt: "Use $superflow-design to create the Superpowers technical design after SDD contract docs are complete."

package/assets/skills-en/superflow-docs/SKILL.md

@@ -72,7 +72,7 @@ For complex requirements, verify these before writing docs:
   `$superflow-table-impact-analysis` when available.
 - For any status, enum, sync, derived, default, or compatibility behavior, the
   docs include business semantic evidence:
-  `真源字段 | 真源枚举 | 目标字段 | 目标枚举 | 消费方解释 | 业务依据 | 不确定项`.
+  `Source field | Source enum | Target field | Target enum | Consumer meaning | Business basis | Unknowns`.
   If the docs only prove that a value exists, is non-null, or lets the request
   succeed, stop and return to `$superflow-clarify`. If fallback/default/keep-old-value
   behavior is proposed without explicit requirement or owner approval, stop.
@@ -121,7 +121,7 @@ For complex requirements, verify these before writing docs:
   DB/log evidence, and matching `test-report.md` section. If test data,
   token, device, third-party dependency, or environment is unavailable, mark
   that case `Blocked`/`Partially verified`; do not leave it as an open TODO.
-- `feature-gates.md` exists and the current feature is `已冻结`.
+- `feature-gates.md` exists and the current feature is `frozen`.
 - `ui-contract.md` contains page-to-API/DTO/DB mapping.
 - `gap-analysis.md` has no unresolved blocker for the current feature.
 - A precise `api.md` section exists or can be generated from the confirmed API draft.
@@ -201,8 +201,8 @@ Use references only as needed:
   platform adapters, or configuration consumers are affected.
 - Do not freeze cross-module design from "this module can technically call it"
   evidence. `design.md` or `traceability-matrix.md` must include:
-  `链路步骤 | 调用方向 | 业务入口 owner | 出口/适配 owner | 既有入口/出口 |
-  拟新增入口/出口 | 是否符合职责 | 证据锚点 | 禁止绕路`.
+  `Flow step | Call direction | Business-entry owner | Adapter owner | Existing entry/exit |
+  Proposed entry/exit | Responsibility fit | Evidence anchor | No bypass`.
   Outbound adapters, protocol translators, MQ notification consumers, and
   device gateways must not be promoted into business-entry orchestrators unless
   the contract says they own that entry and records approval.
@@ -213,33 +213,33 @@ Use references only as needed:
   turn an assumption into a requirement, table design, API contract, or prompt.
 - Do not finalize database-backed design from a forward-only flow. For each
   affected table/field, `design.md` or `traceability-matrix.md` must include:
-  `表/字段 | 写入方 | 读取/过滤方 | 跨仓/外部消费方 | 真实入口 | 反向状态场景 | 必测用例`.
+  `Table/field | Writer | Reader/filter | Cross-repo/external consumer | Real entry | Reverse-state scenario | Required test`.
   Status fields must include recovery scenarios such as offline -> online,
   deleted -> restored, missing -> reappearing, and old invalid value -> valid
   after an upstream omission.
 - Do not finalize status/enum/sync/default design from "has a value" evidence.
   `design.md` or `traceability-matrix.md` must include:
-  `真源字段 | 真源枚举 | 目标字段 | 目标枚举 | 消费方解释 | 业务依据 | 不确定项`.
+  `Source field | Source enum | Target field | Target enum | Consumer meaning | Business basis | Unknowns`.
   Default values, fallback values, null-to-available conversions, old-value
   retention, and alternative-field substitution are forbidden unless explicitly
   required for dirty historical data or uncontrollable external input. Approved
   compatibility must document:
-  `兜底触发条件 | 业务依据 | 会掩盖的异常 | 监控/告警/暴露方式 | 移除条件 | owner确认`.
+  `Fallback trigger | Business basis | Masked anomaly | Monitoring/alert/exposure | Removal condition | Owner approval`.
 - `design.md`, `tests.md`, `sdd-quality-gate.md`, or `test-report.md` must name
-  the relationship judgment as `确定/部分确定/不确定` when a bug fix hinges on
+  the relationship judgment as `confirmed/partially confirmed/unknown` when a bug fix hinges on
   existing data or call-chain behavior.
 - `design.md` must reference the frozen `api.md` fields and errors.
-- `design.md` must include a "字段语义合同" table for every risky field:
-  `字段 | 来源表/DTO/事件 | 真实语义 | 目标字段 | 目标语义 | 是否可等价 |
-  证据锚点 | 禁止用法 | 不确定项/owner`.
-- `design.md` or `traceability-matrix.md` must include a "写入闭环" table for
+- `design.md` must include a "Field Semantic Contract" table for every risky field:
+  `Field | Source table/DTO/event | Real semantics | Target field | Target semantics | Equivalent? |
+  Evidence anchor | Forbidden usage | Unknowns/owner`.
+- `design.md` or `traceability-matrix.md` must include a "Write-Through Closure" table for
   every persisted or synchronized value:
-  `业务动作 | Java setter/赋值点 | Converter/DTO 映射 | Mapper insert/update |
-  DB column | 后续读取方 | 消费入口 | 验证 SQL | 测试用例`.
-- `design.md` must include a "真实入口调用链" table:
-  `用户/外部动作 | 上游服务/接口 | 本仓入口 | MQ/异步回调 | 关键字段变化 |
-  DB 状态 | 结算/通知/展示消费点 | 真实验证方式`.
-- `design.md` or `sdd-quality-gate.md` must include a "禁止 fallback 与猜测实现"
+  `Business action | Java setter/assignment | Converter/DTO mapping | Mapper insert/update |
+  DB column | Later reader | Consumer entry | Verification SQL | Test case`.
+- `design.md` must include a "Real Entry Call Chain" table:
+  `User/external action | Upstream service/API | Current repo entry | MQ/async callback | Key field change |
+  DB state | Settlement/notification/display consumer | Real verification method`.
+- `design.md` or `sdd-quality-gate.md` must include a "No Fallback Or Guesswork"
   section. It must explicitly list forbidden defaults, fallback queries,
   substitute fields, keep-old-value behavior, null conversion, and downstream
   compensation. Approved compatibility must include owner confirmation and
@@ -250,16 +250,16 @@ Use references only as needed:
   OpenSpec/SDD owns WHAT/API/DB/tests/gates; Superpowers owns source-level HOW,
   TDD/RED order, team split, worktree/port plan, and verification choreography.
   The final technical design is created by `$superflow-design`, not `$superflow-docs`.
-- `test-report.md` skeleton must include an "Agent 执行前自检" section with:
-  `真实入口已定位 | 字段语义合同已核对 | 写入闭环已核对 |
-  禁止兜底边界已确认 | RED 测试已执行 | 允许修改文件 | 禁止修改文件 |
-  阻塞项`.
+- `test-report.md` skeleton must include an "Agent Pre-Execution Self-Check" section with:
+  `Real entry located | Field semantic contract checked | Write-through closure checked |
+  No-fallback boundary confirmed | RED test executed | Allowed files | Forbidden files |
+  Blockers`.
 - `tasks.md`, `tests.md`, and later prompts must use the same field names as `api.md`.
 - `tests.md` is a pre-implementation contract. It must not be a vague checklist.
   Every case must include:
-  `用例ID | 需求/Scenario | 层级L1/L2/L3/L4 | 前置数据 | 操作步骤 |
-  自动化命令 | 响应断言 | DB断言 | 日志断言 | RED预期失败 | GREEN预期通过 |
-  test-report证据位置`.
+  `Case ID | Requirement/scenario | Level L1/L2/L3/L4 | Precondition data | Steps |
+  Automation command | Response assertion | DB assertion | Log assertion | RED expected failure | GREEN expected pass |
+  test-report evidence location`.
 - Each visible UI field, button action, list column, dropdown, and enum must map to API/DTO/DB/tests or be explicitly out of scope.
 - Every spec scenario must have at least one test case.
 - Every implementation batch must have at least one test that can fail before
@@ -290,8 +290,8 @@ Use references only as needed:
   CR/Px follow-ups: failing evidence before the fix, then the same path passing
   after the fix.
 - `test-report.md` skeleton must include these sections before implementation:
-  `RED 失败证据`, `GREEN 通过证据`, `接口自动化证据`, `DB 核查证据`,
-  `日志核查证据`, `未自动化/阻塞用例`, and `Partially verified 边界`.
+  `RED failure evidence`, `GREEN pass evidence`, `interface automation evidence`, `DB evidence`,
+  `log evidence`, `manual/blocking cases`, and `Partially verified boundary`.
   Each section must reference concrete `tests.md` case IDs.
 - `sdd-quality-gate.md` must include blocking checks for:
   executable tests frozen, RED/GREEN expectations present, interface automation

package/assets/skills-en/superflow-docs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "SDD Docs"
-  short_description: "基于冻结功能点生成 API 先行的完整 SDD 文档集"
+  short_description: "Generate API-first SDD document sets from frozen feature scope"
   default_prompt: "Use $superflow-docs to generate API-first OpenSpec SDD documents from the confirmed feature."