@specpow/framework 0.5.11 → 0.5.13

package/builtin/skills/business-java-codegen/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: business-java-codegen
+description: SpecPow business-java-codegen skill
+---
+
+# Java 代码生成
+
+> 根据设计文档和数据库表结构，生成符合项目规范的 Java 后端代码（Entity/Mapper/Service/Controller 四层）
+
+## 技术栈配置
+
+本技能的**默认**技术栈为 MyBatis-Plus + Spring Boot，但会根据项目实际使用的框架自动适配：
+
+- **ORM 框架** — 优先使用项目已有的 ORM（MyBatis-Plus / JPA / MyBatis / JDBC Template）
+- **基类** — 扫描项目已有 BaseEntity、BaseController 等基类并继承
+- **包名规范** — 从已有代码推断包结构，而非硬编码
+- **返回格式** — 使用项目已有的统一返回类型（Result / Response / ApiResponse）
+
+如果项目无已有代码可参考，则在阶段 1 询问用户确认技术选型。
+
+## 触发条件
+
+- 用户要求生成 Java 代码
+- 执行 apply-change 时涉及后端任务
+- 用户提到"生成接口"/"写 Service"/"创建 Controller"
+
+## 铁律
+
+1. **先查 DB 再生成** — 必须确认表结构已存在，字段名以数据库为准
+2. **四层齐全** — Entity、Mapper(XML)、Service(Interface+Impl)、Controller 缺一不可
+3. **不造轮子** — 使用项目已有的基类（BaseEntity、BaseController 等）
+4. **注释完整** — 类注释、方法注释、关键逻辑行注释
+
+## 工作流
+
+### 阶段 1：上下文收集
+
+1. 读取 design.md 获取接口定义和数据模型
+2. 查询数据库表结构（DDL 或已有 Entity）
+3. **扫描项目已有代码，识别技术栈**（ORM 框架、基类、包名、返回格式）
+4. 如果项目无已有代码，询问用户确认技术选型
+
+### 阶段 2：代码生成
+
+按以下顺序生成：
+
+**2.1 Entity（实体类）**
+```
+- 继承 BaseEntity（如有）
+- 字段与数据库列一一对应
+- 使用 @Table、@Column 注解
+- 包含 getter/setter 或 @Data
+```
+
+**2.2 Mapper（数据访问层）**
+```
+- 继承 BaseMapper<T>（MyBatis-Plus）或对应基类
+- 自定义 SQL 写在 XML 中
+- 复杂查询方法命名：select + By + 条件
+```
+
+**2.3 Service（业务逻辑层）**
+```
+- 接口 + 实现分离
+- 继承 IService<T> / ServiceImpl（如有基类）
+- 事务注解 @Transactional 加在实现类方法上
+- 业务异常使用自定义 BusinessException
+```
+
+**2.4 Controller（控制层）**
+```
+- 继承 BaseController（如有）
+- RESTful 风格：GET 查询、POST 创建、PUT 更新、DELETE 删除
+- 参数校验使用 @Valid + DTO
+- 统一返回 Result<T> 格式
+```
+
+### 阶段 3：验证
+
+1. 编译检查：确保无语法错误
+2. 依赖检查：所有 import 可解析
+3. 规范检查：命名、注释、分层符合规范
+
+## 输出格式
+
+每个文件输出时标注：
+```
+文件: src/main/java/com/company/xxx/entity/XxxEntity.java
+类型: Entity
+依赖: BaseEntity, Lombok
+```
+
+## 红旗（立即停止）
+
+- 数据库表不存在 → 先执行 DB 设计
+- 项目无基类且用户未指定 → 询问用户
+- 发现已有同名类 → 报告冲突，不覆盖

package/builtin/skills/business-menu-register/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: business-menu-register
+description: SpecPow business-menu-register skill
+---
+
+# 菜单注册
+
+> 根据新增页面/功能，生成系统菜单注册 SQL 和路由配置
+
+## 触发条件
+
+- 新增页面需要注册到系统菜单
+- 用户提到"注册菜单"/"添加菜单"/"系统菜单"
+- 新模块的权限配置
+
+## 铁律
+
+1. **层级正确** — 一级菜单 → 二级菜单 → 按钮权限
+2. **ID 唯一** — 菜单 ID 不与已有冲突
+3. **路径一致** — 菜单路径与前端路由一致
+4. **权限编码规范** — 模块:功能:操作
+
+## 菜单结构
+
+```sql
+-- 一级菜单（目录）
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, path, menu_type, visible, status)
+VALUES (2000, '模块名称', 0, 1, '/module', 'M', '0', '0');
+
+-- 二级菜单（页面）
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, path, component, menu_type, visible, status)
+VALUES (2001, '页面名称', 2000, 1, 'page', 'module/page/index', 'C', '0', '0');
+
+-- 按钮权限
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2011, '新增', 2001, 1, 'F', 'module:entity:add', '0', '0');
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2012, '修改', 2001, 2, 'F', 'module:entity:edit', '0', '0');
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2013, '删除', 2001, 3, 'F', 'module:entity:remove', '0', '0');
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2014, '查询', 2001, 4, 'F', 'module:entity:query', '0', '0');
+```
+
+## 工作流
+
+1. **扫描已有菜单** — 查询最大 menu_id，避免冲突
+2. **确认菜单层级** — 目录(M) → 菜单(C) → 按钮(F)
+3. **生成 SQL** — 按层级顺序生成 INSERT 语句
+4. **生成路由** — 对应的前端路由配置
+5. **验证** — 检查 ID 唯一性和路径一致性
+
+## 输出格式
+
+1. 菜单注册 SQL（可直接执行）
+2. 前端路由配置
+3. 权限编码清单
+
+## 红旗
+
+- 菜单 ID 冲突 → 重新分配
+- 路径与已有路由冲突 → 报告冲突
+- 缺少父级菜单 → 先创建目录

package/builtin/skills/business-prd-writer/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: business-prd-writer
+description: SpecPow business-prd-writer skill
+---
+
+# PRD 编写
+
+> 将用户口述、会议纪要、原型截图转化为结构化 PRD 文档
+
+## 触发条件
+
+- 用户描述一个新功能/需求
+- 用户提到"写 PRD"/"需求文档"/"产品需求"
+- 项目启动阶段的需求梳理
+
+## 铁律
+
+1. **不替用户决定** — 不确定的地方标注 [待确认]
+2. **用例驱动** — 每个功能点至少 1 个用例
+3. **可验证** — 每个需求有明确的验收标准
+4. **边界清晰** — 明确"做什么"和"不做什么"
+
+## PRD 结构
+
+```markdown
+# [功能名称] PRD
+
+## 1. 背景与目标
+- 业务背景
+- 核心目标（可量化）
+- 成功指标
+
+## 2. 用户角色
+| 角色 | 描述 | 核心诉求 |
+|------|------|----------|
+
+## 3. 功能需求
+### 3.1 [功能模块]
+- 用例 UC-001: [用例名称]
+  - 前置条件:
+  - 主流程:
+  - 备选流程:
+  - 异常流程:
+
+## 4. 非功能需求
+- 性能要求
+- 安全要求
+- 兼容性要求
+
+## 5. 数据需求
+- 核心实体
+- 字段清单
+- 数据流向
+
+## 6. 界面原型
+- 页面列表
+- 关键交互说明
+
+## 7. 排期建议
+- 优先级排序（P0/P1/P2）
+- 依赖关系
+
+## 8. 待确认项
+- [ ] 问题1
+- [ ] 问题2
+```
+
+## 工作流
+
+1. **收集信息** — 与用户对话，提取关键需求
+2. **结构化** — 按 PRD 模板整理
+3. **补充细节** — 推断合理的用例和边界
+4. **标注不确定** — 用 [待确认] 标记
+5. **用户确认** — 输出后请用户审核
+
+## 红旗
+
+- 用户描述模糊 → 提出澄清问题，不猜测
+- 需求超出当前迭代 → 标注"后续迭代"
+- 涉及其他系统 → 标注集成依赖

package/builtin/skills/business-test-gen/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: business-test-gen
+description: SpecPow business-test-gen skill
+---
+
+# 测试代码生成
+
+> 根据业务层代码，生成单元测试
+
+## 技术栈配置
+
+本技能的**默认**技术栈为 JUnit5 + Mockito（Java），但会根据项目实际使用的测试框架自动适配：
+
+- **测试框架** — 优先使用项目已有的框架（JUnit5 / JUnit4 / TestNG / Jest / Vitest / pytest）
+- **Mock 工具** — 匹配项目已有 Mock 方案（Mockito / Sinon / unittest.mock / gomock）
+- **断言库** — 使用项目已有的断言风格（AssertJ / Hamcrest / Jest expect / chai）
+- **运行命令** — 从项目 package.json / pom.xml / build.gradle 推断测试运行命令
+
+## 触发条件
+
+- 用户要求生成测试代码
+- 执行 apply-change 中任务包含验证步骤
+- 用户提到"写测试"/"单测"/"覆盖率"
+
+## 铁律
+
+1. **测行为不测实现** — 测试输入→输出，不关心内部怎么实现
+2. **Mock 外部依赖** — 数据库、RPC、HTTP 全部 Mock
+3. **边界必测** — null、空集合、极值、异常路径
+4. **失败自修** — 测试失败自动修复，最多 3 轮
+
+## 工作流
+
+### 阶段 1：分析被测代码
+1. 读取目标 Service/Mapper 类
+2. 识别所有 public 方法
+3. 分析方法依赖（需要 Mock 的对象）
+4. 提取业务规则和边界条件
+
+### 阶段 2：生成测试
+
+**测试类结构：**
+```java
+@ExtendWith(MockitoExtension.class)
+class XxxServiceTest {
+
+    @InjectMocks
+    private XxxServiceImpl xxxService;
+
+    @Mock
+    private XxxMapper xxxMapper;
+
+    // 每个方法至少 2 个测试：正常路径 + 异常路径
+    @Test
+    @DisplayName("方法名 - 场景描述")
+    void methodName_scenario() {
+        // Given
+        // When
+        // Then
+    }
+}
+```
+
+**覆盖场景类型：**
+- 正常输入 → 预期输出
+- null 参数 → 抛出异常或返回默认值
+- 空集合 → 正确处理
+- 数据库无记录 → 返回 null
+- 业务规则违反 → 抛出 BusinessException
+
+### 阶段 3：执行与自修
+
+1. 运行测试：`mvn test -Dtest=XxxServiceTest`
+2. 如果失败，分析错误原因
+3. 修复测试代码（不修改被测代码）
+4. 最多 3 轮，仍失败则报告问题
+
+## 红旗
+
+- 被测类不存在 → 先生成业务代码
+- 项目无测试框架 → 询问用户选择测试框架
+- 覆盖率低于 60% → 补充测试用例

package/builtin/skills/business-ui-codegen/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: business-ui-codegen
+description: SpecPow business-ui-codegen skill
+---
+
+# UI 代码生成
+
+> 根据设计文档和接口定义，生成前端页面/UI 代码
+
+## 技术栈配置
+
+本技能的**默认**技术栈为 Vue2 + View Design，但会根据项目实际使用的框架自动适配：
+
+- **前端框架** — 优先使用项目已有的框架（Vue2 / Vue3 / React / Angular）
+- **UI 组件库** — 匹配项目已有组件库（View Design / Element / Ant Design / MUI）
+- **状态管理** — 使用项目已有的状态管理（Vuex / Pinia / Redux / NgRx）
+- **样式方案** — 沿用项目已有的 CSS 方案（CSS Modules / Scoped CSS / Tailwind / Less / SCSS）
+
+如果项目无已有前端代码，则在阶段 1 询问用户确认技术选型。
+
+## 触发条件
+
+- 用户要求生成前端页面/UI 代码
+- 执行 apply-change 时涉及前端任务
+- 用户提到"生成页面"/"写组件"/"创建表单"
+
+## 铁律
+
+1. **接口先行** — 必须确认后端 API 已定义（路径、参数、返回值）
+2. **组件复用** — 优先使用 View Design 组件，不造轮子
+3. **样式规范** — 使用项目已有的 CSS 变量/mixin
+4. **响应式** — 表格、表单必须适配常见分辨率
+
+## 工作流
+
+### 阶段 1：上下文收集
+
+1. 读取 design.md 获取页面结构和交互设计
+2. 确认 API 接口定义（路径、Method、参数、响应）
+3. **扫描项目已有页面，识别技术栈**（框架、组件库、状态管理、样式方案）
+4. 如果项目无已有前端代码，询问用户确认技术选型
+5. 确认路由配置方式
+
+### 阶段 2：代码生成
+
+按以下顺序生成：
+
+**2.1 API 接口文件**
+```
+文件: src/api/xxx.js
+- 使用 axios 封装
+- 每个接口一个导出函数
+- 请求/响应拦截器统一处理
+```
+
+**2.2 页面主文件**
+```
+文件: src/views/xxx/index.vue
+- <template>: View Design 组件组合
+- <script>: data/methods/computed/watch 标准结构
+- <style scoped>: 局部样式
+```
+
+**2.3 列表页模板**
+```
+- 搜索表单（Form + FormItem）
+- 操作按钮栏（新增/导出/批量操作）
+- 数据表格（Table + columns 配置）
+- 分页（Page 组件）
+- 新增/编辑弹窗（Modal + Form）
+```
+
+**2.4 表单页模板**
+```
+- 表单验证规则（rules）
+- 提交前校验
+- 返回/重置按钮
+```
+
+**2.5 路由配置**
+```
+- 路由路径与菜单对应
+- meta 包含 title、icon、权限
+```
+
+### 阶段 3：验证
+
+1. 语法检查：Vue 模板无报错
+2. 组件引用：所有使用的组件已注册
+3. API 调用：接口路径和参数与设计一致
+
+## 输出格式
+
+```
+文件: src/views/xxx/index.vue
+类型: 页面组件
+依赖: View Design, axios, 路由
+```
+
+## 红旗（立即停止）
+
+- API 接口未定义 → 先完成后端
+- 项目未使用 View Design → 确认 UI 框架
+- 发现已有同名页面 → 报告冲突

package/builtin/skills/cli-router/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: cli-router
+version: 1.0.0
+trigger: on-demand
+description: SpecPow CLI 命令路由 — 将用户意图映射到 CLI 命令执行
+---
+
+# SpecPow CLI 路由技能
+
+当用户请求执行 SpecPow CLI 命令时，按以下规则执行。
+
+## 铁律
+
+1. **所有 CLI 命令通过 Bash 工具执行**，不在对话中模拟输出
+2. **先检查状态**：执行任何命令前先 `specpow status`
+3. **展示完整输出**：将命令输出完整展示给用户
+4. **链式引导**：执行完一步后建议下一步
+
+## 意图 → 命令映射表
+
+| 用户说 | 执行命令 |
+|--------|---------|
+| "探索需求" / "explore" / "specpow explore" | `specpow explore "主题"` |
+| "创建提案" / "propose" / "specpow propose" | `specpow propose <name>` |
+| "执行" / "apply" / "实现" / "specpow apply" | `specpow apply` |
+| "验证" / "verify" / "检查" / "specpow verify" | `specpow verify` |
+| "归档" / "archive" / "specpow archive" | `specpow archive` |
+| "状态" / "status" / "specpow status" | `specpow status` |
+| "调试" / "debug" / "specpow debug" | `specpow debug "描述"` |
+| "doctor" / "诊断" / "specpow doctor" | `specpow doctor` |
+| "review" / "审查" / "specpow review" | `specpow review` |
+| "schemas" / "schema 列表" | `specpow schemas` |
+| "更新" / "update" / "specpow update" | `specpow update` |
+| "配置" / "config" / "specpow config" | `specpow config` |
+
+## 执行规则
+
+### 交互式命令处理
+
+`specpow explore` 是交互式命令（使用 readline），在 Claude Code 的 Bash 工具中无法交互。
+遇到此命令时：
+1. 告诉用户需要在终端中运行：`specpow explore "主题"`
+2. 或者尝试使用 `--json` 标志获取非交互式输出（如果支持）
+3. 如果用户坚持在 Claude Code 中执行，使用苏格拉底式提问手动模拟探索流程
+
+### 非交互式命令
+
+其他所有命令（propose/apply/verify/archive/status）都是非交互式的，直接通过 Bash 执行：
+
+```bash
+# 示例：执行状态检查
+specpow status
+
+# 示例：创建变更提案
+specpow propose add-login
+
+# 示例：使用特定 schema
+specpow propose fix-bug --schema bug-fix
+
+# 示例：验证变更
+specpow verify --change add-login
+
+# 示例：归档变更
+specpow archive --change add-login
+```
+
+### 错误处理
+
+命令失败时：
+1. 展示完整错误信息
+2. 分析可能的原因
+3. 建议解决方案
+4. 如果适用，运行 `specpow doctor` 进行诊断
+
+### 工作流引导
+
+根据当前阶段引导用户：
+
+```
+[无变更] → propose → [有提案] → apply → [已实现] → verify → [已验证] → archive
+```
+
+每次执行 `specpow status` 后，根据阶段推荐下一步操作：
+- 无活跃变更 → 建议 `/specpow-propose <name>`
+- 有提案但工件未完成 → 建议编辑工件文件
+- 工件已完成 → 建议 `/specpow-apply`
+- 已实现 → 建议 `/specpow-verify`
+- 已验证 → 建议 `/specpow-archive`
+
+## 合理化防御表
+
+| 你以为的 | 实际应该做的 |
+|---------|------------|
+| "我可以直接告诉用户命令是什么" | 用 Bash 工具执行命令并展示结果 |
+| "这个命令太简单了，不需要执行" | 仍然执行，展示实际输出 |
+| "用户应该自己去终端运行" | 用户要求你执行，你就执行 |
+| "explore 是交互式的，我模拟一下" | 告诉用户需要在终端运行，或手动模拟苏格拉底式提问 |
+
+## 红旗
+
+以下想法意味着 STOP：
+
+| 想法 | 现实 |
+|------|------|
+| "我可以假装执行了命令" | 必须真正用 Bash 执行并展示输出 |
+| "这个命令会改变什么，让我先确认" | 直接执行，展示结果让用户确认 |
+| "用户可能不知道这个命令" | 执行命令后解释输出含义 |

package/builtin/skills/execution-finish-branch/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: execution-finish-branch
+description: SpecPow execution-finish-branch skill
+---
+
+# 完成分支
+
+> 分支开发完成后的合并和清理流程
+
+## 触发条件
+
+- 变更所有任务完成 — 准备合并到主分支
+- 用户提到"完成分支"/"合并"/"清理"
+
+## 铁律
+
+1. **验证先行** — 合并前必须通过所有检查
+2. **squash 合并** — 保持主分支历史整洁
+3. **删除分支** — 合并后删除功能分支
+4. **更新状态** — 归档变更
+
+## 工作流
+
+### 1. 最终验证
+```bash
+# 确保测试通过
+pnpm test
+
+# 确保构建通过
+pnpm build
+
+# 确保无未提交变更
+git status
+```
+
+### 2. 合并
+```bash
+git checkout main
+git merge --squash feature-branch
+git commit -m "feat: 变更描述"
+```
+
+### 3. 清理
+```bash
+git branch -d feature-branch
+git worktree remove ../project-feature  # 如果使用了 worktree
+```
+
+### 4. 归档变更
+```bash
+specpow archive <change-id>
+```
+
+## 红旗
+
+- 测试未通过 → 不合并
+- 有冲突未解决 → 先解决冲突
+- 未归档变更 → 完成归档

package/builtin/skills/execution-git-worktrees/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: execution-git-worktrees
+description: SpecPow execution-git-worktrees skill
+---
+
+# Git 工作树
+> 使用 git worktree 管理多个并行开发分支
+
+## 触发条件
+
+- 需要同时处理多个变更
+- 用户提到"工作树"/"worktree"/"并行开发"
+
+## 铁律
+
+1. **一树一分支** — 每个 worktree 对应独立分支
+2. **不共享 node_modules** — 每个工作树独立安装依赖
+3. **完成后清理** — 合并后删除 worktree
+
+## 工作流
+
+### 创建 worktree
+```bash
+git worktree add ../project-feature-a feature-a
+cd ../project-feature-a
+pnpm install
+```
+
+### 列出 worktree
+```bash
+git worktree list
+```
+
+### 删除 worktree
+```bash
+git worktree remove ../project-feature-a
+```
+
+## 适用场景
+
+- 同时开发多个需求
+- 紧急修复需要中断当前工作
+- 对比不同分支的实现
+
+## 红旗
+
+- worktree 超过 5 个 → 清理不用的
+- 忘记切回主 worktree → 注意当前工作目录

package/builtin/skills/execution-parallel-agents/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: execution-parallel-agents
+description: 并行子代理调度。识别独立问题域，并行分发多个子代理同时处理。来自 Superpowers。
+---
+
+# 并行代理调度
+
+## 何时使用
+
+- 有多个独立的问题域
+- 问题之间没有依赖关系
+- 想要加速处理
+
+## 流程
+
+### 1. 识别独立性
+分析问题，识别可以独立处理的子问题：
+- 不同的文件/模块
+- 不同的功能点
+- 不同的关注点（前端/后端/测试）
+
+### 2. 验证独立性
+确保子问题之间：
+- 不修改同一个文件
+- 不依赖彼此的输出
+- 接口已经定义清楚
+
+### 3. 并行分发
+
+为每个子问题分发一个子代理：
+- 每个子代理有独立的上下文
+- 每个子代理有明确的范围
+- 每个子代理有验证标准
+
+### 4. 合并结果
+
+所有子代理完成后：
+- 检查是否有冲突
+- 运行完整测试套件
+- 集成验证
+
+## 注意事项
+
+- **绝不**并行修改同一个文件
+- 合并后必须运行完整测试
+- 如果子代理之间有依赖，改用串行