@chenmk/superflow 0.1.0

package/assets/skills/superflow-pipeline/references/decision-point.md

@@ -0,0 +1,30 @@
+# SDD Decision Point
+
+Use this when an SDD phase needs a human decision before continuing.
+
+## Required Format
+
+Write a short decision block in the relevant SDD document or reply:
+
+```md
+## Decision Point
+
+- phase: docs|implement|verify|archive
+- decision_needed: <one concrete decision>
+- options:
+  - A: <option and consequence>
+  - B: <option and consequence>
+- recommended: <A|B>
+- blocked_until: user confirms the decision
+- state_command: `superflow-state.sh set <change-dir> build_pause plan-ready`
+```
+
+## Rules
+
+- Ask for a decision only when the next action changes scope, API/DB contract,
+  implementation strategy, verification boundary, or archive closeout.
+- Do not ask open-ended questions when a recommended option can be stated.
+- Record the decision in `design.md`, `sdd-quality-gate.md`, `test-report.md`,
+  or the implementation prompt, depending on the phase.
+- After confirmation, update `.sdd/state.yaml` with the selected field and
+  rerun the current phase guard.

package/assets/skills/superflow-pipeline/references/dirty-worktree.md

@@ -0,0 +1,35 @@
+# SDD Dirty Worktree Policy
+
+Use this before implementation, verification, archive, or any worktree split.
+
+## Check
+
+```bash
+git status --short
+git diff --stat
+```
+
+## Rules
+
+- Treat uncommitted files as owned by the user unless the current task created
+  them in this session.
+- Do not revert, overwrite, or clean unrelated files.
+- If SDD docs are dirty, regenerate `.sdd/handoff/sdd-context.*` before
+  creating implementation prompts or coding.
+- If runtime files are dirty before docs are complete, stop and run the docs
+  guard. Runtime edits during `phase: docs` are blocked unless the user
+  explicitly switches to hotfix/tweak and the hard gates allow it.
+- For parallel worktrees, each worker may update only its task-local docs and
+  allowed runtime files. Root aggregate SDD docs are reserved for Leader
+  closeout.
+
+## Handoff Note
+
+When continuing from another session, record:
+
+```md
+- dirty_worktree_checked: yes
+- unrelated_changes_left_untouched: yes|none
+- sdd_docs_changed_since_handoff: yes|no
+- regenerated_handoff: yes|no
+```

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

@@ -0,0 +1,123 @@
+# 文档格式模板
+
+## 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
+```

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

@@ -0,0 +1,124 @@
+# 功能点串行门禁工作流
+
+复杂 PRD、飞书文档、原型图或口头大需求必须使用本工作流。目标是把需求理解
+外部化、逐功能点确认，防止上下文丢失、图片归属错误、过度设计字段和缺接口。
+
+## 1. 硬门禁
+
+- 必须按产品文档顺序一次只处理一个功能点。
+- 当前功能点未由编程人员明确确认前，不得进入下一个功能点的澄清、接口草案、
+  `api.md`、`spec.md`、`design.md`、`tasks.md`、`tests.md` 或 prompt。
+- 当前功能点未冻结前，不得生成全局 P0-Pn 实现 prompt。
+- 不得把多个功能点的问题混在同一轮澄清里。
+- 不得依赖对话上下文记忆保存未落盘信息。
+- 页面、原型和产品文档都没有的字段，不得进入 API 必填项；若后端需要，必须
+  标记为后端默认、后端推导或待确认。
+- 后续联调发现的问题必须作为 CR/Px 追加任务新增 prompt，不得污染已执行 prompt。
+
+## 2. 每个功能点的固定步骤
+
+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. 重新执行当前功能点门禁。
+
+不得为了推进速度而跳过失败门禁。