@chenmk/superflow 0.1.0 → 0.1.2

package/assets/skills-en/superflow-pipeline/references/batch-split-guide.md

@@ -1,140 +1,26 @@
-# 分批实现拆分指南
+# Batch Split Guide
 
-## 为什么要拆分
+Split implementation by independently verifiable business closure.
 
-复杂需求一次性塞给单个 agent，会导致：
-- 看似功能都写了，但关键链路没有闭环
-- SQL、实体、Mapper 字段不一致
-- 子功能没有复用既有链路，而是重复实现
-- 服务间调用契约不完整，出现 fail-open 风险
-- 外部协议逻辑写进业务核心
-- 边界不清，测试验收困难
+## Good Batches
 
-拆分的核心目标：**把复杂需求切成"可实现、可测试、可评审、可回滚"的小批次**。
+- Baseline and schema preparation.
+- Core master data or model changes.
+- Core business workflow.
+- Async/external integration.
+- End-to-end verification and closeout.
 
----
+## Bad Batches
 
-## 触发条件：何时必须拆分
+- One batch per file type.
+- One batch for all controllers.
+- One batch for all tests after coding.
+- A batch that cannot be verified without hidden future work.
 
-当需求满足**任一**条件时，skill 必须自动拆分 implementation prompt：
+## Required For Each Batch
 
-| # | 条件 | 说明 |
-|---|------|------|
-| 1 | 涉及 2 个以上仓库 | 跨仓库变更不能在一个 prompt 中完成 |
-| 2 | 涉及 SQL + 后端业务 + MQ/定时/异步 | 技术栈跨度大，需要分阶段 |
-| 3 | 涉及外部系统接口 | 外部协议适配与业务实现需分离 |
-| 4 | 涉及支付、退款、余额、发票、权益等资金或权益链路 | 资金链路必须独立验证 |
-| 5 | 涉及历史字段兼容 | 兼容逻辑容易污染新功能 |
-| 6 | 涉及用户侧交易、审批、履约或核心业务状态机 | 状态机复杂，需独立闭环验证 |
-| 7 | 预计修改文件超过 20 个 | 上下文超载，agent 会遗漏 |
-| 8 | 测试用例超过 10 条 | 验证范围过大，难以一次通过 |
-| 9 | 涉及 3 个以上业务闭环 | 每个闭环应独立验收 |
-
-**判断方式**：在 Stage 5（生成 Tasks）完成后，统计任务数量和涉及范围，自动触发判断。
-
----
-
-## 功能闭环拆分原则
-
-### 什么是"功能闭环"
-
-一个功能闭环是指：**从输入到输出，不依赖外部未实现部分，可独立编译、独立启动、独立测试验证的最小业务单元**。
-
-**好的闭环示例**：
-- "主数据 CRUD + 数据库表 + 后台列表接口" — 可自行验证
-- "外部事件接入 + MQ 发布" — 可独立测试消息流
-- "业务下单/创建接口 + 状态机" — 可端到端验证
-
-**不好的拆分示例**：
-- "前半部分改 SQL，后半部分改 Service" — 无法独立验证
-- "改 Controller 但不改对应的 Service" — 接口调不通
-- "同时改两个微服务的一半逻辑" — 两边都无法启动
-
-### 拆分规则
-
-**规则 1：按可独立验收的闭环拆分**
-- 每个 prompt 只覆盖一个明确闭环
-- 闭环内部必须能走完"编译 → 启动 → 调接口 → 查数据库 → 看日志"全流程
-- 闭环之间通过"前置依赖"声明关系
-
-**规则 2：每份 prompt 必须写清楚"不允许做什么"**
-- 明确列出禁止修改的文件和方法
-- 明确列出禁止引入的依赖
-- 明确列出禁止改动的既有接口签名
-
-**规则 3：禁止跨边界修改**
-- 处理外部协议的 prompt，不允许改业务状态机
-- 处理业务状态机的 prompt，不允许改外部协议解析
-- 处理外部接口适配的 prompt，不允许改内部核心逻辑
-
----
-
-## 跨仓库任务拆分规则
-
-### 拆分维度
-
-按"生产者 / 消费者 / 契约 / 业务归口"拆分：
-
-| 角色 | 职责 | 示例 |
-|------|------|------|
-| **生产者** | 负责数据采集、协议解析、事件发布 | connector-service：解析外部事件，发布 MQ |
-| **消费者** | 负责消费事件、固化业务状态 | domain-api：消费 MQ，更新业务状态 |
-| **契约层** | 负责外部协议适配、内部 HTTP 调用 | integration-service：适配外部协议，同步调用 domain-api |
-| **业务归口** | 负责核心业务逻辑、状态机、资金/权益 | domain-api：业务记录、权益、退款等核心逻辑 |
-
-### 每个仓库的 prompt 必须声明
-
-1. **本仓库职责边界**：我负责什么，不负责什么
-2. **上游依赖**：我依赖哪个仓库的什么接口/消息
-3. **下游契约**：我向谁提供什么接口/消息
-4. **交互契约详情**：HTTP 路径、方法、请求/响应字段、MQ topic、消息格式
-
-**禁止**：靠实现 agent 自行猜测与其他仓库的交互方式。
-
-### 跨仓库示例
-
-**通用业务平台的跨仓库拆分**：
-
-```
-Repository: connector-service
-  Role: 生产者
-  Scope: 外部协议解析、事件格式化、MQ 发布
-  Downstream: 向 topic "domain.business.event" 发布 BusinessEvent
-  Forbidden: 不处理业务状态、不操作数据库、不调用 domain-api
-
-Repository: domain-api
-  Role: 消费者 + 业务归口
-  Scope: 消费 BusinessEvent、业务状态机、权益/退款链路
-  Upstream: 从 topic "domain.business.event" 消费
-  Downstream: 向 integration-service 提供 HTTP /api/v1/business-records
-  Forbidden: 不处理外部协议、不直接对接外部平台
-
-Repository: integration-service
-  Role: 契约层
-  Scope: 外部协议适配、鉴权、转换、同步调用 domain-api
-  Upstream: 调用 domain-api /api/v1/business-records
-  Forbidden: 不直接操作数据库、不处理外部协议底层细节、不写核心业务状态机
-```
-
----
-
-## 默认批次顺序
-
-对复杂需求，默认推荐以下顺序。每批必须等前一批验收通过后才能开始。
-
-```
-P0 基线 → P1 核心主数据 → P2 交易链路 → P3 异步/外部系统 → P4 联调验收
-```
-
-| 批次 | 内容 | 验收标准 |
-|------|------|---------|
-| **P0** | 清理工作树、确认仓库/分支、校验 SQL/实体/Mapper/DTO 字段一致、最小编译验证 | git status 干净、编译通过、字段一致性校验通过 |
-| **P1** | 数据库基线（SQL）、实体/Mapper/DTO、枚举常量、核心主数据接口 | 表结构与实体一致、基础 CRUD 可调用 |
-| **P2** | 交易链路核心（下单、状态机、优惠命中、快照、预充值/退款） | 端到端交易流程可验证 |
-| **P3** | 异步/外部系统（事件接入、MQ 消费、外部集成适配、权益接口） | 消息流/外部调用可验证 |
-| **P4** | 联调验收、全链路回归、批量导入、后台列表、边界场景 | 全部 tests.md 用例通过 |
-
-**注意**：
-- P0 是**强制前置**，复杂需求必须先过 P0
-- 实际批次数量和命名根据需求调整，不是固定 5 批
-- 每批的验收标准必须可独立验证，不依赖后续批次
+- Clear input and output.
+- Allowed and forbidden files.
+- Dependencies on previous batches.
+- Tests and real-entry evidence.
+- Documentation update responsibility.

package/assets/skills-en/superflow-pipeline/references/document-templates.md

@@ -1,123 +1,50 @@
-# 文档格式模板
-
-## Proposal 格式
-
-```markdown
-# Proposal: <功能名称>
-
-## Motivation
-为什么需要这个功能
-
-## Proposed Solution
-提议的解决方案
-
-## Alternatives Considered
-考虑的替代方案
-```
-
-## Spec 格式
-
-```markdown
-# Spec: <功能名称>
-
-## ADDED Requirements
-### Requirement: <需求描述>
-#### Scenario: <场景名称>
-- **WHEN** <前置条件>
-- **THEN** <预期结果>
-- **AND** <附加条件>
-```
-
-## Design 格式
-
-```markdown
-# Design: <功能名称>
-
-## Overview
-设计概述
-
-## Source Code Analysis
-源码分析（引用具体文件、类、方法、行号）
-
-## Change Matrix
-| Requirement | 修改文件 | 修改方法 | 变更类型 |
-|---|---|---|---|
-
-## Detailed Design
-详细设计
-
-## API Design（如有）
-接口设计
-
-## Migration Plan
-迁移计划（如有）
-
-## Risk Assessment
-风险评估（并发、性能、兼容性）
-```
-
-## Tasks 格式
-
-```markdown
-# Tasks: <功能名称>
-
-## 需求级汇总 SQL 文件
-- 路径：`openspec/changes/{change-id}/sql/{汇总SQL文件名}`（如 `sql/{version}.sql`）
-- 所有新增表、改表、索引、默认值、初始化数据脚本统一追加到该文件
-- 禁止各任务各自新建独立 SQL 文件
-- 不需要 SQL 的任务也需写明"本任务不新增 SQL，但开始前仍需核查依赖表结构是否已满足设计"
-
-## 1. Requirement A 实现
-- [ ] 1.1 修改 `FilePath.java`，在 `methodName()` 中增加 X 逻辑
-  - 源码锚点：`FilePath.java:line-start-line-end`
-  - 验收标准：调用 Y 接口后，Z 状态变为 W
-  - 依赖的汇总 SQL：`openspec/changes/{change-id}/sql/{文件名}` 第 XX-XX 行（或"本任务不新增 SQL，但开始前仍需核查依赖表结构"）
-  - blocked by: 无
-- [ ] 1.2 修改 `FilePath2.java`，调整 `methodName2()` 返回值
-  - 源码锚点：`FilePath2.java:line-start-line-end`
-  - 验收标准：单元测试通过
-  - 依赖的汇总 SQL：`openspec/changes/{change-id}/sql/{文件名}` 第 XX-XX 行
-  - blocked by: 1.1
-```
-
-## Tests 格式
-
-```markdown
-# Tests: <功能名称>
-
-## 0. 应用运行配置
-- **配置文件**: `src/main/resources/application.yml`
-- **端口号**: {port}
-- **上下文路径**: {context-path}
-- **基础 URL**: `http://localhost:{port}{context-path}`
-- **启动命令**: `mvn spring-boot:run -Dspring-boot.run.profiles={profile}`
-
-## 0.1 数据库结构核查（每个批次必须执行）
-- **核查目标**: 确认开发环境数据库表结构与设计文档一致
-- **汇总 SQL 文件**: `openspec/changes/{change-id}/sql/{文件名}`
-- **执行步骤**:
-  1. 连接开发环境数据库
-  2. 对本需求涉及的每张表执行 `SHOW CREATE TABLE {表名}`，对照 design.md / database-contract.md 确认字段、类型、默认值、索引
-  3. 对需要初始化数据的表执行 `SELECT COUNT(*) FROM {表名} WHERE {条件}`，确认初始化数据已存在
-  4. 如果发现缺失，从汇总 SQL 文件中取对应脚本执行
-  5. 执行后再次查询确认
-- **断言标准**:
-  - 所有设计要求的表、字段、索引、默认值在实际数据库中存在
-  - 所有初始化数据已插入
-- **自动化**: [自动化]
-
-## N. Requirement N 测试
-
-### Scenario: <场景描述>
-- **前置条件**: 数据库状态 / 缓存状态 / 环境配置
-- **接口 URL**: `http://localhost:{port}{context-path}{接口路径}`
-- **请求参数**: JSON / Query / Path / Form
-- **执行步骤**: 1. 启动应用 2. 调用接口 3. 验证结果
-- **断言标准**:
-  - 接口返回值：`code == 0`，`message == "xxx"`
-  - 数据库状态：`SELECT ... FROM ... WHERE ...` 期望值为 N
-  - 日志输出：日志中包含 `"xxx"`
-  - 缓存状态：`CacheManager.get()` 返回期望值
-- **自动化**: [自动化] / [需手工]
-- **关联**: spec.md Requirement N → Scenario X
-```
+# Document Templates
+
+## proposal.md
+
+- Problem
+- Goals
+- Non-goals
+- Scope
+- Risks
+- Open questions
+
+## api.md
+
+- Endpoint and message contracts
+- Field mapping
+- Compatibility
+- Examples
+- Test commands
+
+## design.md
+
+- Source-of-truth contracts
+- Architecture boundary
+- Data model
+- Field semantics
+- Write/read loop
+- No-fallback decisions
+- Superpowers technical design handoff
+
+## tests.md
+
+- Case ID
+- Level L0-L4
+- Preconditions
+- RED expectation
+- GREEN expectation
+- Command
+- Response, DB, and log assertions
+- Evidence location in test-report.md
+
+## test-report.md
+
+- Environment
+- Commands
+- RED evidence
+- GREEN evidence
+- Real-entry evidence
+- DB/log evidence
+- Hook output
+- Blocked or skipped cases with reasons

package/assets/skills-en/superflow-pipeline/references/feature-gated-workflow.md

@@ -1,124 +1,17 @@
-# 功能点串行门禁工作流
+# Feature-Gated Requirement Workflow
 
-复杂 PRD、飞书文档、原型图或口头大需求必须使用本工作流。目标是把需求理解
-外部化、逐功能点确认，防止上下文丢失、图片归属错误、过度设计字段和缺接口。
+Use this for long PRDs, online docs, screenshots, prototypes, or mixed feature
+requests. Process one feature at a time.
 
-## 1. 硬门禁
+## Artifacts
 
-- 必须按产品文档顺序一次只处理一个功能点。
-- 当前功能点未由编程人员明确确认前，不得进入下一个功能点的澄清、接口草案、
-  `api.md`、`spec.md`、`design.md`、`tasks.md`、`tests.md` 或 prompt。
-- 当前功能点未冻结前，不得生成全局 P0-Pn 实现 prompt。
-- 不得把多个功能点的问题混在同一轮澄清里。
-- 不得依赖对话上下文记忆保存未落盘信息。
-- 页面、原型和产品文档都没有的字段，不得进入 API 必填项；若后端需要，必须
-  标记为后端默认、后端推导或待确认。
-- 后续联调发现的问题必须作为 CR/Px 追加任务新增 prompt，不得污染已执行 prompt。
+- source-ingestion.md: source list, section range, screenshots, and read status.
+- feature-inventory.md: feature list, priority, owner, and dependency.
+- feature-gates.md: per-feature status: pending, clarifying, frozen, blocked.
+- ui-contract.md: screen field to API/DTO/DB/test mapping.
+- gap-analysis.md: unknowns, contradictions, and owner decisions.
+- spec-freeze-review.md: final frozen scope and excluded items.
 
-## 2. 每个功能点的固定步骤
+## Gate
 
-1. 读取当前功能点的文字需求、相邻图片和相关附件。
-2. 输出 AI 理解，包含业务目标、用户动作、页面入口、按钮动作和列表列。
-3. 标注当前功能点对应的 PRD 段落、图片、附件或口头来源。
-4. 输出页面字段契约：页面字段、是否可见、控件类型、下拉来源、API 入参、
-   API 出参、DTO/VO、DB 字段、默认/推导策略。
-5. 输出差距分析：
-   - 页面有、后端无：缺接口或缺字段。
-   - 后端有、页面无：疑似过度设计或隐藏必填。
-   - 文档有、页面无：待确认是否废弃。
-   - 页面有、文档无：原型隐含需求，必须补 spec。
-6. 只针对当前功能点提出澄清问题。
-7. 等待编程人员明确确认或修正理解范围。
-8. 输出当前功能点粗接口草案，只列路径、动作、核心入参、核心出参。
-9. 等待编程人员确认粗接口草案。
-10. 输出正式 `api.md` 章节，精确到字段名、类型、必填、默认值、枚举、错误码、
-    示例请求响应和 curl。
-11. 基于已确认的 `api.md` 生成当前功能点的 `spec.md`、`design.md`、`tasks.md`、
-    `tests.md` 和实现 prompt。
-12. 在 `feature-gates.md` 标记当前功能点 `已冻结` 后，才允许进入下一个功能点。
-
-## 3. 必备落盘文件
-
-复杂需求必须在 change 目录下维护以下文件。没有这些文件时不得生成实现 prompt。
-
-### `source-ingestion.md`
-
-记录原始资料摄取：
-
-| 顺序 | 资料 | 来源 | 已读取范围 | 图片/附件 | 结果 |
-|---|---|---|---|---|---|
-| 1 | PRD | 飞书/本地文件 | 第 1 节 | 图 1/2 | 已读取 |
-
-### `feature-gates.md`
-
-记录功能点串行确认状态：
-
-| 顺序 | 功能点 | 来源段落 | 来源图片 | 理解确认 | 接口草案确认 | SDD 已生成 | 状态 |
-|---|---|---|---|---|---|---|---|
-| 1 | 主数据新增/编辑 | PRD 2.1 | 图 1/2 | 已确认 | 已确认 | 已生成 | 已冻结 |
-| 2 | 业务开通/创建流程 | PRD 2.2 | 图 3 | 待确认 | 未开始 | 未生成 | 阻塞 |
-
-状态只能使用：`未开始`、`理解待确认`、`接口草案待确认`、`SDD生成中`、
-`已冻结`、`阻塞`。
-
-### `feature-inventory.md`
-
-记录需求库存：
-
-| 功能点 | 来源文字 | 来源图片 | 页面/入口 | 用户动作 | 后端接口 | 数据表 | spec | task |
-|---|---|---|---|---|---|---|---|---|
-
-### `ui-contract.md`
-
-记录原型字段契约：
-
-| 功能点 | 页面字段 | 是否可见 | 控件类型 | API 入参 | API 出参 | DTO/VO | DB 字段 | 策略 |
-|---|---|---|---|---|---|---|---|---|
-
-策略填写：前端提交、后端默认、后端推导、废弃、待确认。
-
-### `gap-analysis.md`
-
-记录页面、文档、源码差距：
-
-| 功能点 | 类型 | 差距 | 风险 | 处理方式 | 状态 |
-|---|---|---|---|---|---|
-| 业务开通/创建流程 | 后端有页面无 | paymentMethod 必填 | 接口 500 | 后端默认 | 已确认 |
-
-### `spec-freeze-review.md`
-
-每个功能点进入编码前必须有冻结卡：
-
-```markdown
-## 功能点：____
-
-- 来源：____
-- 图片：____
-- 页面字段：____
-- 新增接口：____
-- 修改接口：____
-- 后端默认字段：____
-- 后端推导字段：____
-- 明确不做：____
-- 待确认：无 / ____
-- 冻结结论：已冻结，可生成 prompt / 不通过
-```
-
-## 4. API 先行规则
-
-- 涉及前后端联调时，正式 `api.md` 必须在编码 prompt 之前冻结。
-- `design.md` 必须引用已冻结的 `api.md` 设计业务逻辑，不得另起字段口径。
-- `tasks.md`、`tests.md` 和 prompt 只能使用已冻结 `api.md` 中的接口和字段。
-- 若实现时发现 `api.md` 不可行，必须停止，更新冻结卡并让编程人员确认后再继续。
-
-## 5. 质量门失败处理
-
-任一门禁失败时：
-
-1. 停止后续功能点处理。
-2. 输出失败项和证据。
-3. 让编程人员确认修正方案。
-4. 修正当前功能点文档。
-5. 重新执行当前功能点门禁。
-
-不得为了推进速度而跳过失败门禁。
+Do not generate full OpenSpec docs until the target feature is frozen.