@chenmk/superflow 0.1.0

package/assets/skills/superflow-pipeline/references/p0-baseline-template.md

@@ -0,0 +1,174 @@
+# P0 基线任务模板
+
+## 为什么需要 P0
+
+复杂跨仓库需求中，实现 agent 经常在以下基线问题上出错：
+- 工作树不干净，带着旧改动或脏文件开始开发
+- 改了 SQL 但没同步改实体，字段不一致
+- 改了实体但没同步改 Mapper/DTO，编译报错
+- 不确定自己该改哪个仓库、哪个分支
+- 业务和基线清理混在一起，难以回滚
+
+P0 的目标：**在写任何业务代码之前，先把地基打牢**。
+
+---
+
+## P0 Prompt 模板
+
+```
+使用superpower技能，开启合适的团队，最少包含一名开发和一名测试交叉验证进行需求开发，测试验证闭环交付，更新测试文档和api.md：
+
+# P0 Prompt：基线核查与开发准备
+
+你是 P0 基线 Agent，负责为后续业务开发建立干净、一致、可编译的基线。
+
+## 团队要求
+- 至少 1 名开发 Worker
+- 至少 1 名独立 Tester
+- P0 完成后由 Tester 独立复核基线和编译结果
+
+## 本批目标
+建立可编译、字段一致的代码基线，确认开发环境就绪。
+
+## 并行开发要求（Worktree 隔离）
+
+本任务必须使用独立 git worktree 开分支开发，避免多个 agent 在同一工作树并行修改互相覆盖。
+
+```bash
+git status --short
+git worktree add -b feature/{change-id}-p0-baseline ../{project}-p0-worktree HEAD
+cd ../{project}-p0-worktree
+```
+
+如果分支已存在，改用：
+
+```bash
+git worktree add ../{project}-p0-worktree feature/{change-id}-p0-baseline
+cd ../{project}-p0-worktree
+```
+
+所有基线核查、文档更新和提交都必须在该 worktree 内完成。不要在主工作树直接开发，不要回滚或删除其他 agent 的改动。完成后在报告中写明 worktree 路径、分支名和提交号。
+
+## 允许修改的仓库
+{repository-name}
+
+## 允许修改的目录/文件范围
+- SQL 文件：{sql-file-path}
+- 实体类：{entity-package}/*.java
+- Mapper 接口：{mapper-package}/*.java
+- Mapper XML：{mapper-xml-path}/*.xml
+- DTO：{dto-package}/*.java
+
+## 禁止修改的范围
+- 禁止修改任何 Service/Controller/Listener 业务逻辑
+- 禁止修改任何配置文件（application.yml 除外，如需调整数据库连接需上报）
+- 禁止引入新的外部依赖
+- 禁止提交 .DS_Store、target/、build/、.idea/ 等脏文件
+
+## 依赖的前置批次
+无（P0 是第一批次）
+
+## 执行步骤
+
+### 步骤 1：清理工作树
+1. 执行 `git status`，确认当前分支是 {branch-name}
+2. 如有未提交改动，先提交或暂存（stash）
+3. 检查并删除以下脏文件（如存在）：
+   - .DS_Store
+   - target/
+   - build/
+   - *.iml
+   - .idea/（已跟踪的除外）
+4. 再次执行 `git status`，确认工作树干净
+
+### 步骤 2：确认仓库和分支
+- 当前仓库：{repository-name}
+- 目标分支：{branch-name}
+- 允许改动范围：{allowed-paths}
+- 远程跟踪：确认 `git branch -vv` 显示正确 upstream
+
+### 步骤 3：校验字段一致性
+对照 design.md 或 database-contract.md 中的表结构定义，逐一校验：
+
+| 检查项 | 方法 | 通过标准 |
+|--------|------|---------|
+| SQL 表结构与实体类字段一致 | 对比 CREATE TABLE 与 @Column | 字段名、类型、长度、nullable 一致 |
+| 实体类与 Mapper XML 一致 | 对比 resultMap / 列名 | 无遗漏字段、无拼写错误 |
+| 实体类与 DTO 一致 | 对比字段列表 | DTO 字段是实体字段的子集或超集（设计意图明确） |
+| 枚举值与数据库约束一致 | 对比 enum 定义与 CHECK 约束 | 枚举值在数据库约束范围内 |
+| 主键/索引定义一致 | 对比 @Id/@Index 与 SQL | 主键、索引定义一致 |
+| 版本总 SQL 收口一致 | 对比源码/Mapper、开发库、测试库现状+总 SQL | 源码依赖字段均在最终结构中存在；总 SQL 无漏项、无重复 ADD |
+
+**校验方法**：
+1. 读取 SQL 文件，提取所有表结构和字段定义
+2. 读取对应的实体类，提取所有字段和注解
+3. 读取对应的 Mapper XML，提取所有 resultMap 和 SQL 列
+4. 读取对应的 DTO，提取所有字段
+5. 逐字段对比，列出不一致项
+6. 对涉及数据库的需求，额外对比三方：源码/Mapper 读写字段、开发库结构、测试库现状 + 版本总 SQL 执行后结构
+
+### 步骤 4：修复不一致
+对步骤 3 发现的不一致项：
+- 如果 SQL 是正确的（以设计文档为准），修正实体/Mapper/DTO
+- 如果源码/Mapper 和开发库一致但版本总 SQL 缺失，优先补版本总 SQL，不要改业务代码绕过
+- 如果测试库已有字段，版本总 SQL 不得重复 ADD；字段类型或注释与开发库不一致时生成 MODIFY 或上报不采纳理由
+- 如果设计文档有模糊之处，停止并报告，不允许自行猜测
+
+### 步骤 5：最小编译验证
+1. 执行 `git diff --name-only`，确认只修改了允许范围内的文件
+2. 执行编译命令：{compile-cmd}
+3. 确认 BUILD SUCCESS，无 ERROR
+
+## 数据库字段要求
+- 所有新增/修改字段必须在 SQL、实体、Mapper、DTO 中同步存在
+- 字段命名使用下划线（数据库）和驼峰（Java），转换由 MyBatis 负责
+- 禁止使用数据库保留字作为字段名
+- 时间字段统一使用 datetime，由框架填充
+
+## 验收命令
+```bash
+# 1. 确认工作树干净
+git status
+
+# 2. 确认修改范围正确
+git diff --name-only
+
+# 3. 编译验证
+{compile-cmd}
+
+# 4. 检查无脏文件提交
+git diff --cached --name-only | grep -v '\.java$\|\.xml$\|\.sql$' || echo "无异常文件"
+```
+
+## 完成后必须输出的报告
+
+```
+P0 基线报告：
+- 仓库：{repository-name}
+- 分支：{branch-name}
+- 工作树状态：干净 / 不干净（说明）
+- 删除的脏文件：{list}
+- 字段一致性校验结果：
+  - 检查表：{table-name}
+  - 一致字段：X 个
+  - 不一致字段：X 个（已修复 X 个，上报 X 个）
+  - 不一致详情：
+    - {field}: SQL={type}, Entity={type}, 修复方式={fix}
+- 版本总 SQL 收口对账：
+  - 源码/Mapper vs 开发库：一致 / 不一致
+  - 测试库现状 + 总 SQL：一致 / 不一致
+  - 补入总 SQL 的字段/索引/数据：{list}
+  - 不采纳项及原因：{list}
+- 编译状态：BUILD SUCCESS / 失败（说明）
+- 修改文件清单：{files}
+- 对应 OpenSpec 章节：design.md ## 数据模型
+- 需要人工确认的问题：{list}
+- 后续批次依赖事项：P1 可开始
+```
+
+## 偏离设计时必须停止并报告
+
+- 如果发现 SQL 字段与设计文档定义不一致，**停止**，列出差异，上报 Leader
+- 如果发现实体类使用了设计文档未定义的字段，**停止**，不允许自行添加
+- 如果编译失败且无法通过修改允许范围内的文件解决，**停止**，上报 Leader
+```

package/assets/skills/superflow-pipeline/references/project-config.md

@@ -0,0 +1,40 @@
+# SDD Project Config
+
+Use project-level `.sdd/config.yaml` for defaults that should apply to all SDD
+changes in the repo.
+
+## Supported Fields
+
+```yaml
+auto_transition: true        # true|false
+context_compression: off     # off|beta
+review_mode: standard        # off|standard|thorough
+```
+
+## Precedence
+
+Runtime scripts resolve configuration in this order:
+
+1. Environment variable:
+   - `SUPERFLOW_REVIEW_MODE`
+   - `SDD_AUTO_TRANSITION`
+   - `SDD_CONTEXT_COMPRESSION`
+   - `SDD_REVIEW_MODE`
+2. Change-local config: `<change-dir>/.sdd/config.yaml`
+3. Project config: `<repo-root>/.sdd/config.yaml`
+4. Existing state value when applicable
+5. Script default
+
+## Rules
+
+- Use `auto_transition: false` when the user wants manual review between SDD
+  phases.
+- Use `context_compression: beta` for large changes, long sessions, multi-agent
+  work, or repeated context compression risk.
+- Use `review_mode: standard` for normal full workflow. Use `thorough` when the
+  change touches API contracts, database fields, cross-repo behavior, third-party
+  integrations, or production-like verification. Use `off` only for hotfix/tweak
+  flows or explicitly documented low-risk work.
+- Beta handoff keeps `api.md`, `spec.md`, and `tests.md` projected while
+  supporting docs are referenced by hash. If a supporting detail is needed,
+  read the original source file.

package/assets/skills/superflow-pipeline/references/prompt-usage-template.md

@@ -0,0 +1,152 @@
+# AI 提示词使用记录模板
+
+记录开发过程中使用的 AI 提示词、输出采纳情况和人工修改点，用于比赛交付或项目复盘。
+
+## 记录格式
+
+每个提示词记录为一个条目，按时间顺序排列。
+
+```markdown
+# AI 提示词使用记录
+
+## 条目 N
+
+### 时间
+2026-05-09 10:30
+
+### 上下文
+[描述当前正在解决什么问题，处于哪个开发阶段]
+
+### 原始提示词（Prompt）
+```
+完整的提示词内容
+```
+
+### AI 输出摘要
+[AI 返回的核心内容，2-3 句话概括]
+
+### 采纳情况
+- [x] 直接采纳（无需修改）
+- [ ] 部分采纳（修改后使用）
+- [ ] 未采纳（重新提问或人工解决）
+
+### 人工修改点
+如部分采纳，列出修改内容：
+1. 修改了 ____（原因：____）
+2. 删除了 ____（原因：____）
+3. 增加了 ____（原因：____）
+
+### 校验方式
+[如何验证 AI 输出是否正确，如：编译通过 / 单元测试通过 / 人工 Review]
+
+### 经验教训
+[如果 AI 输出有问题，记录问题原因和避免方式]
+```
+
+## 完整示例
+
+```markdown
+# AI 提示词使用记录
+
+## 条目 1
+
+### 时间
+2026-05-09 09:00
+
+### 上下文
+需要设计门禁系统的数据库表结构，包含人员、门禁设备、通行记录。
+
+### 原始提示词
+```
+帮我设计一个人行门禁系统的数据库表结构，使用 MySQL。
+需要包含：
+1. 人员信息表（姓名、手机号、人脸特征、状态）
+2. 门禁设备表（设备编号、位置、状态）
+3. 通行记录表（人员、设备、时间、方式、结果）
+要求：
+- 使用 InnoDB 引擎
+- 有合适的索引
+- 字段命名用下划线
+- 包含 created_at / updated_at
+```
+
+### AI 输出摘要
+生成了 3 张表的 DDL，包含主键、索引、外键和注释。
+
+### 采纳情况
+- [x] 部分采纳
+
+### 人工修改点
+1. 人脸特征字段从 TEXT 改为 VARCHAR(2048)（实际 base64 长度可控）
+2. 增加了 `tenant_id` 字段（多租户需求，AI 未考虑）
+3. 索引调整：通行记录增加 `(device_id, pass_time)` 联合索引（按设备查历史是高频操作）
+
+### 校验方式
+- 在 MySQL 8.0 执行 DDL，确认无语法错误
+- 使用 EXPLAIN 验证索引生效
+
+### 经验教训
+AI 生成表结构时容易遗漏业务特定的字段（如 tenant_id），需要在提示词中明确说明业务背景。
+
+---
+
+## 条目 2
+
+### 时间
+2026-05-09 11:00
+
+### 上下文
+实现设备回调接口，处理门禁设备的刷卡事件。
+
+### 原始提示词
+```
+帮我写一个 Spring Boot Controller，接收门禁设备的回调请求。
+请求格式：
+POST /device/callback
+{
+  "deviceId": "string",
+  "cardNo": "string",
+  "timestamp": "2026-05-09T10:00:00Z",
+  "eventType": "CARD_SWIPE"
+}
+
+需要：
+1. 校验 deviceId 存在
+2. 根据 cardNo 查询人员
+3. 判断是否有权限
+4. 记录通行日志
+5. 返回开门指令
+```
+
+### AI 输出摘要
+生成了 Controller + Service 代码，包含参数校验、业务逻辑、异常处理。
+
+### 采纳情况
+- [x] 部分采纳
+
+### 人工修改点
+1. 增加了幂等性校验（相同 cardNo + timestamp 5 分钟内不重复处理）
+2. 使用分布式锁（Redisson）防止并发重复开门
+3. 将事务边界从 Controller 移到 Service 层
+
+### 校验方式
+- 单元测试：Mock Service，验证参数校验逻辑
+- 集成测试：启动应用，使用 curl 模拟回调，验证数据库记录
+
+### 经验教训
+AI 生成的代码缺少并发安全考虑，涉及设备控制必须考虑幂等性和并发。
+```
+
+## 汇总统计
+
+| 项目 | 数量 |
+|------|------|
+| 总提示词数 | __ |
+| 直接采纳 | __ |
+| 部分采纳 | __ |
+| 未采纳 | __ |
+| 平均修改点/条 | __ |
+
+## 质量总结
+
+[整体评价 AI 辅助开发的效果，哪些场景效果好，哪些场景需要人工主导]