@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

package/plugins/req/skills/show/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: show
+description: |
+  查看需求详情 - 阅读需求完整内容
+---
+
+# 查看需求详情
+
+阅读需求文档的完整业务内容，纯只读，不改变任何状态。
+
+与 `/req:status`（查看进度）互补：`status` 回答"进展如何"，`show` 回答"需求是什么"。
+
+## 命令格式
+
+```
+/req:show [REQ-XXX|QUICK-XXX] [--summary]
+```
+
+**说明**：
+- 编号可选，省略时自动选择最近活跃的需求
+- `--summary`：仅展示摘要（元信息 + 需求描述 + 功能清单）
+
+---
+
+## 执行流程
+
+### 0. 自动识别需求
+
+如果未提供编号：
+
+按修改时间排序扫描角色对应的 active 目录（readonly 用缓存，primary 优先本地不存在时用缓存，未绑定只用本地）。无结果时提示创建；唯一时自动选中；多个时列表让用户输入序号选择。
+
+### 1. 解析存储路径（按角色）
+
+读取 `.claude/settings.local.json` 的 `requirementProject` 和 `requirementRole`，按角色确定路径：
+- `readonly`：根目录为 `~/.claude-requirements/projects/$PROJECT`
+- `primary`：本地根目录为 `docs/requirements`，缓存为备用
+- 未绑定：仅使用 `docs/requirements`
+
+### 2. 查找需求文档（按角色）
+
+**`primary` 角色**搜索位置（按优先级）：
+1. `$ACTIVE/REQ-XXX-*.md`（本地）
+2. `$COMPLETED/REQ-XXX-*.md`（本地）
+3. `$CACHE_ACTIVE/REQ-XXX-*.md`（本地不存在时）
+4. `$CACHE_COMPLETED/REQ-XXX-*.md`（本地不存在时）
+
+**`readonly` 角色**搜索位置：
+1. `$ACTIVE/REQ-XXX-*.md`（缓存）
+2. `$COMPLETED/REQ-XXX-*.md`（缓存）
+
+如果未找到：
+```
+❌ 未找到需求：REQ-XXX
+
+可用操作：
+- 查看所有需求：/req
+- 创建新需求：/req:new
+```
+
+### 3. 读取需求文档
+
+使用 Read 工具读取找到的需求文档完整内容。
+
+### 4. 输出需求详情
+
+根据需求类型（REQ / QUICK）和模式（完整 / 摘要）展示内容。
+
+#### REQ-XXX 完整模式
+
+```
+
+需求详情：REQ-001 部门渠道关联
+
+
+元信息
+编号：REQ-001
+状态：开发中
+类型：后端
+模块：系统管理
+优先级：P1
+负责人：张三
+数据来源：本地 (primary)
+项目：my-saas-product
+
+
+
+## 一、需求描述
+
+### 1.1 背景
+[文档原文...]
+
+### 1.2 目标
+[文档原文...]
+
+### 1.3 客户场景
+[文档原文...]
+
+### 1.4 价值
+[文档原文...]
+
+
+
+## 二、功能清单
+
+- [ ] **功能点1**：描述...
+- [x] **功能点2**：描述...
+...
+
+
+
+## 三、业务规则
+
+[文档原文...]
+
+
+
+## 四、使用场景
+
+[文档原文...]
+
+
+
+## 五、接口需求
+
+[文档原文...]
+
+
+
+## 六、测试要点
+
+[文档原文...]
+
+
+
+## 七、图示（可选）
+
+> 仅在已填写时展示，未填写时跳过本章节
+
+[文档原文...]
+
+
+
+## 十一、实现方案
+
+> 仅在已填写时展示，未填写时跳过本章节
+
+[文档原文...]
+
+
+
+## 十、关联信息
+
+[文档原文...]
+
+
+
+可用操作：
+# primary 角色显示完整操作
+- 查看进度：/req:status REQ-001
+- 继续开发：/req:dev REQ-001
+- 编辑需求：/req:edit REQ-001
+- 进入测试：/req:test REQ-001
+
+# readonly 角色仅显示只读操作
+# - 查看进度：/req:status REQ-001
+# - 查看需求列表：/req
+```
+
+**展示规则**：
+- 一~六章（需求定义区）：**完整展示原文**，这是本命令的核心价值
+- 七、八章（评审记录、变更记录）：**跳过**，这些属于流程记录，用 `/req:status` 查看
+- 九章（关联信息）：展示，便于了解上下文
+- 十章（实现方案）：仅在已填写时展示（判断依据：内容不是模板占位文本 `_开发阶段填充_`）
+
+#### REQ-XXX 摘要模式（--summary）
+
+```
+
+需求摘要：REQ-001 部门渠道关联
+
+
+元信息
+编号：REQ-001
+状态：开发中
+类型：后端
+模块：系统管理
+优先级：P1
+负责人：张三
+
+
+
+## 一、需求描述
+
+[文档原文...]
+
+
+
+## 二、功能清单
+
+[文档原文...]
+
+
+
+查看完整内容：/req:show REQ-001
+```
+
+#### QUICK-XXX 完整模式
+
+```
+
+快速需求详情：QUICK-001 修复登录验证码失效
+
+
+元信息
+编号：QUICK-001
+改动类型：bug修复
+端类型：后端
+状态：开发中
+模块：用户
+优先级：P1
+负责人：张三
+数据来源：本地 (primary)
+项目：my-saas-product
+
+
+
+## 问题描述
+
+### 现象
+[文档原文...]
+
+### 期望
+[文档原文...]
+
+
+
+## 实现方案
+
+### 问题分析
+[文档原文...]
+
+### 解决方案
+[文档原文...]
+
+### 涉及文件
+[文档原文...]
+
+### 改动量
+[文档原文...]
+
+
+
+## 验证方式
+
+[文档原文...]
+
+
+
+可用操作：
+- 查看进度：/req:status QUICK-001
+- 继续开发：/req:dev QUICK-001
+- 编辑需求：/req:edit QUICK-001
+```
+
+#### QUICK-XXX 摘要模式（--summary）
+
+```
+
+快速需求摘要：QUICK-001 修复登录验证码失效
+
+
+元信息
+编号：QUICK-001
+改动类型：bug修复
+端类型：后端
+状态：开发中
+模块：用户
+
+
+
+## 问题描述
+
+[文档原文...]
+
+
+
+查看完整内容：/req:show QUICK-001
+```
+
+---
+
+## 注意事项
+
+1. **纯只读**：本命令不修改任何文件，不触发缓存同步
+2. **展示原文**：直接展示需求文档中的原始内容，不做摘要或改写
+3. **跳过占位文本**：如果某章节仅包含模板占位文本（如 `_开发阶段填充_`），标注"（未填写）"并跳过内容
+4. **支持 QUICK 和 REQ**：自动识别需求类型，按对应模板结构展示
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/specs/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: specs
+description: |
+  规范文档管理 - 项目级公共知识层，集中沉淀散落在代码中的枚举、规则、契约
+---
+
+# 规范文档管理
+
+项目级公共知识层——把散落在代码各处、不易直接阅读的枚举值、业务规则、接口契约整理成可查阅的文档，供 AI 和人随时参考。
+
+**典型内容**：订单状态枚举含义、错误码定义、跨模块共用的业务规则、前后端字段命名约定。
+
+## 命令格式
+
+```
+/req:specs [子命令] [文档名]
+```
+
+## 子命令
+
+| 子命令 | 说明 | 权限 | 示例 |
+|--------|------|------|------|
+| (空) | 列出所有规范文档 | 所有角色 | `/req:specs` |
+| `new` | 创建规范文档 | 仅 primary | `/req:specs new 订单数据类型` |
+| `show` | 查看规范文档 | 所有角色 | `/req:specs show order-types` |
+| `edit` | 编辑规范文档 | 仅 primary | `/req:specs edit order-types` |
+
+---
+
+## 存储路径
+
+```
+<需求根目录>/specs/        # 本地（primary）
+~/.claude-requirements/projects/<project>/specs/   # 缓存（readonly 读此处）
+```
+
+- **primary**：读写本地 `docs/requirements/specs/`
+- **readonly**：只读缓存，禁止写操作
+
+---
+
+## 规范文档格式
+
+每份文档 frontmatter 必须包含：
+
+```markdown
+---
+category: <分类>
+description: <一句话描述>
+updated: <YYYY-MM-DD>
+---
+```
+
+**常见分类**：数据类型、接口契约、错误码、业务规则、编码规范、配置说明
+
+正文格式不作统一要求，同一分类下的文档应保持风格一致，建议按分类采用如下风格：
+
+| 分类 | 建议风格 |
+|------|---------|
+| 数据类型 / 枚举 | 表格（值、含义、备注） |
+| 错误码 | 表格（code、message、适用场景） |
+| 接口契约 | 表格（字段、类型、说明）+ 示例 |
+| 业务规则 | 编号列表（规则 + 适用条件） |
+| 编码规范 | 列表 |
+
+列表展示时从 frontmatter 提取 `category`、`description`、`updated` 三个字段。
+
+---
+
+## 约束
+
+- **文件命名**：用户输入中文名时，生成 kebab-case 英文文件名（如 `订单数据类型` → `order-types.md`）
+- **查找**：`show` / `edit` 支持中文名或文件名模糊匹配
+- **edit**：修改完成后必须更新 `updated` 字段为当天日期
+- **缓存同步**：Write/Edit 操作 `specs/` 下的文件后，PostToolUse Hook 自动同步到缓存（仅 primary）
+
+---
+
+## 列表输出格式
+
+```
+规范文档
+
+| 文档 | 分类 | 描述 | 更新时间 |
+|------|------|------|----------|
+| order-types | 数据类型 | 订单相关枚举和结构体定义 | 2026-03-25 |
+
+共 N 份规范文档
+
+/req:specs show <名称> · /req:specs new <名称> · /req:specs edit <名称>
+```
+
+无文档时提示：`/req:specs new <名称>`
+
+---
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/split/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: split
+description: |
+  需求拆分分析 - 判断需求粒度并给出拆分建议
+---
+
+# 需求拆分分析
+
+纯分析命令，帮助用户在创建需求前判断粒度是否合适，给出拆分或合并建议。
+
+> **Audience:** Product Manager
+> 粒度规则参考 [_granularity.md](./_granularity.md)
+
+## 命令格式
+
+```
+/req:split [需求描述或标题]
+```
+
+**示例：**
+- `/req:split 用户积分系统`
+- `/req:split 给订单列表加一个导出按钮`
+- `/req:split 重构用户认证模块，支持 OAuth2.0 和 LDAP`
+
+---
+
+## 执行流程
+
+### 1. 接收输入
+
+- 用户提供需求标题或简要描述
+- 无输入时提示用户描述想做的事情
+
+### 2. 读取上下文
+
+读取已有模块文档和需求列表，了解项目现状：
+
+- `docs/requirements/modules/` — 现有模块及其职责
+- `docs/requirements/active/` — 进行中的需求（避免重复）
+- `docs/requirements/completed/` — 已完成的需求（了解历史）
+
+### 3. 粒度分析
+
+按以下维度逐项评估：
+
+#### 3.1 粒度信号检测
+
+| 信号 | 判断 | 建议 |
+|------|------|------|
+| 标题含「系统」「模块」「平台」「管理」 | 可能太大 | 列出子功能，建议拆分 |
+| 标题含「接口」「字段」「按钮」「样式」 | 可能太小 | 合并到功能级 REQ 或改用 QUICK |
+| 描述中包含多个独立的业务功能 | 太大 | 按可独立交付的功能拆分 |
+| CRUD 属于同一业务实体 | 合适 | 增删改查放一个 REQ |
+| 仅修改少量文件（< 5 个） | 可能太小 | 考虑用 QUICK |
+
+**核心判断标准**：这个需求完成后，用户能感知到一个完整的功能变化吗？
+
+#### 3.2 功能独立性分析
+
+识别描述中包含的功能点，判断是否可独立交付：
+
+- 功能可独立上线、独立使用 → 拆分
+- 功能之间无强时序依赖（可并行开发） → 拆分
+- 功能之间强耦合，必须同时上线 → 不拆
+- 拆开后单个 REQ 无法独立验证 → 不拆
+
+#### 3.3 前后端拆分判断
+
+- 仅涉及后端 → 类型=后端，一个 REQ
+- 仅涉及前端 → 类型=前端，一个 REQ
+- 前后端都涉及，功能简单 → 类型=全栈，一个 REQ
+- 前后端都涉及，功能复杂 → 拆分为后端 REQ + 前端 REQ，互相关联
+
+#### 3.4 REQ vs QUICK 判断
+
+| 场景 | 建议 |
+|------|------|
+| 新业务功能（CRUD、新页面） | REQ |
+| 已有功能的小调整（加字段、改逻辑） | QUICK |
+| Bug 修复 | QUICK |
+| 重构/优化，改动 ≤ 5 个文件 | QUICK |
+| 重构/优化，改动 > 5 个文件 | REQ |
+
+### 4. 输出建议
+
+根据分析结果，输出三种结论之一：
+
+#### 结论一：粒度合适
+
+```
+需求拆分分析
+
+标题：用户积分规则管理-后端
+
+粒度判断：✅ 合适
+
+分析：
+- 功能完整：包含积分规则的 CRUD 和校验逻辑
+- 可独立交付：完成后用户可以管理积分规则
+- 改动范围适中：预估涉及 8-10 个文件
+
+下一步：
+- /req:new 用户积分规则管理-后端 --type=后端
+```
+
+#### 结论二：建议拆分
+
+```
+需求拆分分析
+
+标题：用户积分系统
+
+粒度判断：⚠️ 太大，建议拆分
+
+分析：
+- 包含多个独立功能：积分规则管理、积分查询、积分兑换、积分排行
+- 各功能可独立交付和验证
+- 前后端都涉及，建议分开管理
+
+建议拆分为：
+1. REQ: 用户积分规则管理-后端（类型=后端）
+   - 积分规则 CRUD、规则校验
+2. REQ: 用户积分规则管理-前端（类型=前端，关联=1）
+   - 积分规则管理页面
+3. REQ: 积分查询与展示-后端（类型=后端）
+   - 积分余额查询、积分明细
+4. REQ: 积分兑换-后端（类型=后端）
+   - 兑换逻辑、库存扣减
+
+建议先创建：
+- /req:new 用户积分规则管理-后端 --type=后端
+```
+
+#### 结论三：建议用 QUICK
+
+```
+需求拆分分析
+
+标题：给订单列表加一个导出按钮
+
+粒度判断：⚠️ 太小，建议用快速修复
+
+分析：
+- 改动范围小：仅涉及 1-2 个文件
+- 风险低：不影响现有功能
+- 无需完整设计和评审
+
+下一步：
+- /req:new-quick 订单列表导出按钮
+```
+
+---
+
+## 注意事项
+
+- 此命令**只做分析，不创建文件**
+- 分析基于用户描述和项目上下文，建议仅供参考
+- 用户可以不采纳建议，直接按自己的判断创建需求
+
+---
+
+## 用户输入
+
+$ARGUMENTS