sdd-workflow 1.1.0

package/templates/skills/sdd-specify/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: sdd-specify
+description: 创建功能规格文档（Specification）- 定义功能需求、用户故事和验收标准。支持从知识库链接获取原始需求文档。
+invocable: true
+---
+
+# SDD Specify - 功能规格生成器
+
+创建功能规格文档，定义功能需求、用户故事和验收标准。支持从知识库链接自动获取原始需求文档。
+
+## ⚠️ 核心原则：Spec 只描述 What，不描述 How
+
+> **Spec 是需求文档，不是技术设计文档。** 它回答"系统应该做什么"，而不是"系统如何实现"。
+> 技术实现细节（SQL、代码、文件路径、架构图）属于 plan.md，不属于 spec.md。
+
+### 内容边界
+
+#### ✅ spec 中应该包含的内容
+- **业务需求**：用户需要什么、为什么需要
+- **用户故事**：角色、目标、价值
+- **验收标准**：Given-When-Then 格式的行为描述
+- **功能点列表**：功能名称、描述、优先级
+- **界面需求**：页面布局示意（简单 ASCII 即可）、交互流程（用户视角）
+- **数据需求**：业务实体、字段含义、业务规则（不含SQL/DDL）
+- **接口需求**：接口名称、用途、输入输出概述（不含代码实现）
+- **非功能需求**：性能、安全、兼容性的业务指标
+- **边界条件**：异常场景和处理策略（业务层面）
+- **术语表**：业务术语定义
+
+#### ❌ spec 中不应该包含的内容（这些属于 plan.md / tasks.md）
+- ~~SQL 查询语句或 DDL~~
+- ~~代码片段（任何语言的代码）~~
+- ~~具体文件路径~~（如 `src/pages/xxx/CreateModal.jsx`）
+- ~~类名、方法名~~（如 `findEarliestSubTaskId()`、`getSubSoftTask()`）
+- ~~代码调用链路~~（如 Controller → Service → Repository）
+- ~~数据库表的字段级定义~~（如 column type、index）
+- ~~修改清单汇总~~（哪些文件需要改）
+- ~~架构图中的代码级细节~~
+- ~~状态管理变量名、组件内部状态~~
+
+### 反面示例
+
+| 问题 | spec 中写了什么 | 应该写什么 |
+|------|-----------------|------------|
+| SQL 出现在 spec | `SELECT ... FROM ... WHERE ...` | "通过关联关系查找相关记录" |
+| 代码调用链 | `Controller → ServiceImpl → Repository.findById()` | "系统查找指定记录" |
+| 文件路径 | `src/.../CreateModal.jsx` | "配置页面" |
+| 方法名 | `getUserProfile()` | "获取用户信息" |
+| 修改清单 | 7个文件的修改列表 | ~~（删除，移到 plan/tasks）~~ |
+
+### 关联模块的正确写法
+
+**❌ 错误**（太具体）:
+```
+| 前端组件 | src/pages/admin/.../CreateModal.jsx | 配置弹窗 |
+| 后端Service | application/.../AutoQuoteServiceImpl.java | 自动引用 |
+```
+
+**✅ 正确**（模块级别）:
+```
+| 前端 | 自动引用配置页面 | 配置创建/编辑 |
+| 后端 | 自动引用模块 | 自动引用执行逻辑 |
+| 数据 | 条件配置存储 | 复用现有条件表 |
+```
+
+## 知识库链接识别
+
+如果项目配置了知识库 MCP（如 Confluence），自动识别知识库链接并获取文档内容：
+
+- 检测 URL 中的知识库域名
+- 使用对应 MCP 工具获取页面内容
+
+## 执行步骤
+
+### 1. 解析用户输入
+从用户输入中提取：
+- 功能名称
+- 功能描述
+- 业务背景（如果有）
+- **知识库链接**（如果有）
+
+### 2. 获取知识库原始需求文档（如果有链接）
+
+#### 2.1 使用MCP工具获取文档
+如果检测到知识库链接，使用已配置的知识库 MCP 工具获取文档详情：
+
+可用工具（如果项目配置了 Confluence MCP）：
+- `mcp__kb-knowledge__confluence_search`: 搜索文档
+- `mcp__kb-knowledge__confluence_get_page`: 获取页面内容
+- `mcp__kb-knowledge__confluence_get_page_children`: 获取子页面
+
+#### 2.2 保存原始需求文档
+将获取的文档保存到功能目录：
+
+```
+.specify/specs/{feature_id}-{feature-name}/
+├── requirements/              # 原始需求文档目录
+│   ├── original.md           # 知识库原始需求（Markdown格式）
+│   └── metadata.json         # 文档元数据（来源、更新时间等）
+├── spec.md                   # 功能规格
+└── contracts/                # API契约（可选）
+```
+
+#### 2.3 元数据文件格式 (metadata.json)
+```json
+{
+  "source": "confluence",
+  "source_url": "https://知识库URL",
+  "page_id": "123456789",
+  "title": "XXX功能需求文档",
+  "author": "作者名",
+  "last_updated": "2026-03-19T12:00:00Z",
+  "fetched_at": "2026-03-19T14:30:00Z"
+}
+```
+
+### 3. 读取相关文档
+
+#### 3.1 必读文档
+- `.specify/memory/constitution.md` - 项目宪法
+- `CLAUDE.md` - 项目配置
+
+#### 3.2 可选文档（如果存在）
+- 相关模块的现有规格文档
+- API文档
+- 数据库设计文档
+- **刚获取的知识库原始需求文档**（如果有）
+
+### 4. 分析现有代码（如果涉及现有模块）
+
+根据 CLAUDE.md 和 constitution.md 中的项目结构信息，定位并分析相关代码：
+- 前端: 分析项目前端源码目录（参考 CLAUDE.md 项目结构）
+- 后端: 分析项目后端目录（参考 CLAUDE.md 项目结构）
+- 数据库: 使用项目配置的数据库连接查看相关表结构
+
+### 5. 生成规格文档
+
+基于模板 `.specify/templates/spec-template.md` 生成文档，包括：
+
+#### 核心内容：
+1. **需求追溯**（如果有知识库来源）
+   - 原始需求链接
+   - 需求版本信息
+
+2. **功能概述**
+   - 功能名称和描述
+   - 业务背景
+   - 关联模块
+
+3. **用户故事**（至少2个）
+   - 格式: 作为[角色]，我希望[目标]，以便于[价值]
+   - 每个故事包含验收标准（Gherkin格式）
+
+4. **功能需求**
+   - 核心功能列表（带优先级）
+   - 界面需求
+   - 数据需求
+   - 接口需求
+
+5. **非功能需求**
+   - 性能要求
+   - 安全要求
+   - 兼容性
+
+6. **验收标准**
+   - 功能验收
+   - 质量验收
+   - 文档验收
+
+7. **功能分组与完成定义**（SDD v2 新增）
+
+   > **受 Harness Planner 启发**: 将功能按交付批次分组，每组定义明确的"完成定义"（Definition of Done）。
+   > 完成定义来源于验收标准，但更聚焦于**可端到端验证的用户可见行为**。
+   > 这为下游的 Phase Contract（阶段合约）和 Review（评审）提供评判基准。
+
+   格式示例：
+   ```markdown
+   ## 功能分组与完成定义
+
+   ### Group A: 核心查询功能
+   - 包含功能: US-1, US-2, US-3
+   - 完成定义:
+     - [ ] 用户可以通过列表页查询 XXX 数据
+     - [ ] 支持按 YYY 条件筛选
+     - [ ] 查询结果分页展示，每页默认 20 条
+     - [ ] 无数据时显示空状态提示
+
+   ### Group B: 详情与对比功能
+   - 包含功能: US-4, US-5, US-6
+   - 完成定义:
+     - [ ] 点击列表项可查看详情
+     - [ ] 支持 2-4 个实例同时对比
+     - [ ] 对比结果以表格形式展示差异字段
+   ```
+
+   **设计原则**:
+   - 分组粒度：每组对应一个可独立交付和评审的功能切片
+   - 完成定义：使用业务语言描述可验证的用户行为，不涉及技术实现
+   - 完成定义的条目数量：每组 3-8 项，太多应拆分，太少应合并
+   - 优先级：按 Group 顺序隐含优先级，Group A 最重要
+
+### 6. 创建功能目录
+```
+.specify/specs/{feature_id}-{feature-name}/
+├── requirements/              # 原始需求文档（如果有知识库来源）
+│   ├── original.md           # 原始需求
+│   └── metadata.json         # 文档元数据
+├── spec.md                   # 功能规格
+└── contracts/                # API契约（可选）
+```
+
+命名规则：
+- feature_id: **三位数字编号，从 001 自增**（001, 002, 003...）。自动扫描 `.specify/specs/` 下已有目录，取最大编号 + 1
+- feature-name: 英文小写，中划线分隔，简短概括功能
+- 完整目录格式: `{feature_id}-{feature-name}/`（如 `001-user-auth/`, `002-data-export/`）
+
+### 7. 保存文档
+保存到: `.specify/specs/{feature_id}-{feature-name}/spec.md`
+
+### 8. 检测文档大小
+
+spec.md 超过 500 行时，自动执行 `/sdd-split spec {feature_id} --auto` 拆分（在 sdd-run 中）或提示用户使用 `/sdd-split spec {feature_id}`（手动模式下）。
+
+### 9. 交互确认
+向用户展示生成的文档大纲，询问是否需要补充或修改。
+
+## 输出示例
+
+### 有知识库链接时：
+```
+📥 检测到知识库链接
+
+正在获取文档...
+✅ 文档已获取并保存: .specify/specs/001-auto-quote/requirements/original.md
+
+📄 需求来源信息:
+- 标题: 软件任务自动引用功能需求文档
+- 作者: 产品经理A
+- 最后更新: 2026-03-18
+
+✅ 功能规格已生成: .specify/specs/001-auto-quote/spec.md
+
+📋 文档大纲：
+1. 需求追溯
+2. 功能概述
+3. 用户故事
+4. 功能需求
+5. 非功能需求
+6. 验收标准
+
+请检查文档内容，如需补充请告诉我具体内容。
+```
+
+### 无知识库链接时：
+```
+✅ 功能规格已生成: .specify/specs/001-user-authentication/spec.md
+
+📋 文档大纲：
+1. 功能概述
+2. 用户故事
+3. 功能需求
+4. 非功能需求
+5. 验收标准
+
+请检查文档内容，如需补充请告诉我具体内容。
+```
+
+## 注意事项
+
+1. **需求聚焦**: Spec 只描述 What（做什么），不描述 How（怎么做）。所有技术实现细节留给 plan.md
+2. **业务术语**: 使用项目业务领域的标准术语，不使用代码术语
+3. **优先级**: 合理设置功能优先级（P0/P1/P2）
+4. **验收标准**: 确保可测试、可验证，用 Given-When-Then 描述行为
+5. **关联模块**: 只标注模块名称和业务功能，不标注文件路径或类名
+6. **数据需求**: 描述业务实体和字段含义，不写 SQL/DDL
+7. **接口需求**: 描述接口用途和输入输出，不写代码实现
+8. **知识库文档格式**: 知识库文档可能使用富文本格式，需要转换为 Markdown
+9. **渐进式披露**: 原始需求保存后，可按需加载详细内容
+10. **禁止修改清单**: 不在 spec 中列出需要修改的文件清单，这属于 plan/tasks
+11. **接收反馈**: 当下游阶段（testcases/plan/implement）触发反馈回 spec 时，必须修正源头并在变更记录中登记 CR

package/templates/skills/sdd-split/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: sdd-split
+description: 将大型 SDD 文档拆分为模块化结构，支持 spec/plan/tasks 三种文档类型。支持 --auto 模式跳过确认。
+invocable: true
+---
+
+# SDD Split - 文档拆分工具
+
+将现有的大型 SDD 文档拆分为模块化结构，支持渐进式加载。
+
+## 使用模式
+
+### 手动模式（默认）
+用户主动调用，拆分前需要确认。
+
+```bash
+/sdd-split spec {feature_id}
+/sdd-split plan {feature_id}
+/sdd-split tasks {feature_id}
+```
+
+### 自动模式（--auto）
+由 sdd-run 或其他自动化流程调用，跳过确认直接执行。
+
+```bash
+/sdd-split spec {feature_id} --auto
+/sdd-split plan {feature_id} --auto
+/sdd-split tasks {feature_id} --auto
+```
+
+自动模式行为差异：
+- 跳过确认步骤
+- 直接执行拆分
+- 输出简要日志而非完整报告
+
+## 功能概述
+
+将单个大文件（spec.md、plan.md、tasks.md）拆分为多个小文件，提高加载效率和维护性。
+
+## 支持的文档类型
+
+1. **spec.md** - 功能规格文档
+2. **plan.md** - 技术实现计划
+3. **tasks.md** - 任务分解文档
+
+## 拆分阈值
+
+| 文档类型 | 拆分阈值 | 说明 |
+|---------|---------|------|
+| spec.md | 500 行 | 超过此行数建议拆分 |
+| plan.md | 1000 行 | 超过此行数建议拆分 |
+| tasks.md | 800 行 | 超过此行数建议拆分 |
+
+## 执行步骤
+
+### 1. 解析参数
+
+- 提取文档类型（spec/plan/tasks）、feature_id、是否 --auto 模式
+- 如果未指定文档类型，报错提示
+
+### 2. 验证前置条件
+
+- 检查文档是否存在
+- 检查文档行数是否超过阈值
+- 检查是否已经拆分（存在对应的子目录）
+
+如果行数未超过阈值且非 --auto 模式：提示用户文档较小无需拆分，结束。
+
+### 3. 确认拆分（手动模式）
+
+仅在**非 --auto** 模式下执行此步骤：
+
+```
+📄 正在分析文档: .specify/specs/{feature_id}/{doc_type}.md
+📊 文档行数: {N} 行
+✅ 超过拆分阈值 ({threshold} 行)，建议拆分
+
+🔍 识别到以下章节：
+  1. {章节1} ({N} 行)
+  2. {章节2} ({N} 行)
+  ...
+
+❓ 是否确认拆分？(y/n)
+```
+
+**--auto 模式**：跳过此步骤，直接执行拆分。
+
+### 4. 读取原文档
+
+使用 Read 工具读取完整文档内容。
+
+### 5. 分析文档结构
+
+根据文档类型，识别章节结构：
+
+#### Spec 文档结构识别
+
+```markdown
+## 1. 功能概述          → overview.md
+## 2. 用户故事          → user-stories.md
+## 3. 验收标准          → acceptance-criteria.md (从用户故事中提取)
+## 4. 约束条件          → constraints.md
+## 变更记录             → changelog.md
+```
+
+#### Plan 文档结构识别
+
+```markdown
+## 1. 架构设计          → architecture.md
+## 2. 数据模型          → data-model.md
+## 3. API设计           → backend-api.md
+## 4. 后端实现          → backend-impl.md
+## 5. 前端API          → frontend-api.md
+## 6. 前端实现          → frontend-impl.md
+## 7. 安全性设计        → security.md
+## 8. 性能优化          → performance.md
+## 变更记录             → changelog.md
+```
+
+#### Tasks 文档结构识别
+
+```markdown
+## Phase 0: 准备工作    → phase-0-preparation.md
+## Phase 1: 后端开发    → phase-1-backend.md
+## Phase 2: 前端开发    → phase-2-frontend.md
+## Phase 3: 测试验收    → phase-3-testing.md
+## Phase N: ...        → phase-N-*.md
+## 任务依赖关系         → dependencies.md
+## 检查点               → checkpoints.md
+## 实现记录             → implementation-notes.md
+```
+
+### 6. 提取章节内容
+
+使用正则表达式提取各章节内容：
+
+```python
+# 识别一级标题
+pattern = r'^## (.+)$'
+
+# 提取章节内容（从当前标题到下一个同级标题）
+def extract_section(content, start_title, end_title=None):
+    # 实现逻辑
+    pass
+```
+
+### 7. 生成子文档
+
+为每个章节创建独立的 Markdown 文件：
+
+**文件命名规则**：
+- Spec: `overview.md`, `user-stories.md`, `acceptance-criteria.md`, `constraints.md`, `changelog.md`
+- Plan: `architecture.md`, `data-model.md`, `backend-api.md`, `backend-impl.md`, `frontend-api.md`, `frontend-impl.md`, `security.md`, `performance.md`, `changelog.md`
+- Tasks: `phase-0-preparation.md`, `phase-1-backend.md`, `phase-2-frontend.md`, `phase-3-testing.md`, `dependencies.md`, `checkpoints.md`, `implementation-notes.md`
+
+**文件内容格式**：
+
+```markdown
+# {章节标题}
+
+> {章节说明}
+
+{章节内容}
+
+---
+
+返回 [{type}索引](./README.md)
+```
+
+### 8. 生成 README.md 索引
+
+根据文档类型，使用对应的模板生成 README.md：
+
+- Spec: `.specify/templates/spec-modular-template/README.md`
+- Plan: `.specify/templates/plan-modular-template/README.md`
+- Tasks: 参考 `{feature_id}/tasks/README.md`
+
+**替换模板变量**：
+- `{功能名称}`: 从原文档标题提取
+- `{version}`: 从原文档提取
+- `{create_date}`: 从原文档提取
+- `{update_date}`: 当前日期
+- 其他变量根据实际内容填充
+
+### 9. 更新主索引文件
+
+将原文档（spec.md/plan.md/tasks.md）转换为索引文件：
+
+```markdown
+# {功能名称} - {文档类型}
+
+> **文档已拆分为模块化结构，请查看 [{type}/README.md](./{type}/README.md) 获取完整索引。**
+
+## 快速导航
+
+| 模块 | 状态 | 文档 |
+|------|------|------|
+| 模块1 | ✅ 已完成 | [链接](./{type}/module1.md) |
+| 模块2 | ⏳ 进行中 | [链接](./{type}/module2.md) |
+
+## 核心信息
+
+[保留最关键的概览信息，约 50-100 行]
+
+## 详细内容
+
+请查看 [{type}/README.md](./{type}/README.md) 获取完整文档。
+```
+
+### 10. 备份原文档
+
+将原文档重命名为 `{name}.md.backup`：
+
+```bash
+mv spec.md spec.md.backup
+mv plan.md plan.md.backup
+mv tasks.md tasks.md.backup
+```
+
+### 11. 验证拆分结果
+
+- 检查所有子文档是否创建成功
+- 检查 README.md 是否生成
+- 检查索引文件是否更新
+- 检查链接是否正确
+
+### 12. 输出摘要
+
+**手动模式**：向用户展示完整拆分结果。
+
+**--auto 模式**：输出简要日志。
+
+```
+✅ 文档拆分完成: .specify/specs/{feature_id}/spec/
+
+📊 拆分结果：
+┌─────────────────┬──────────┬──────────┐
+│ 文件            │ 行数     │ 大小     │
+├─────────────────┼──────────┼──────────┤
+│ README.md       │ 100      │ 5KB      │
+│ overview.md     │ 150      │ 8KB      │
+│ user-stories.md │ 200      │ 10KB     │
+│ ...             │ ...      │ ...      │
+├─────────────────┼──────────┼──────────┤
+│ 总计            │ 614      │ 30KB     │
+└─────────────────┴──────────┴──────────┘
+
+📁 目录结构：
+spec/
+├── README.md
+├── overview.md
+├── user-stories.md
+├── acceptance-criteria.md
+├── constraints.md
+└── changelog.md
+
+💾 原文档已备份: spec.md.backup
+
+✅ 拆分完成！现在可以按需加载各个模块。
+```
+
+## 实现细节
+
+### 章节识别算法
+
+```python
+def identify_sections(content, doc_type):
+    """
+    识别文档章节结构
+
+    Args:
+        content: 文档内容
+        doc_type: 文档类型 (spec/plan/tasks)
+
+    Returns:
+        List[Section]: 章节列表
+    """
+    sections = []
+    lines = content.split('\n')
+
+    current_section = None
+    current_content = []
+
+    for line in lines:
+        # 识别一级标题 (## 标题)
+        if line.startswith('## '):
+            # 保存上一个章节
+            if current_section:
+                sections.append({
+                    'title': current_section,
+                    'content': '\n'.join(current_content)
+                })
+
+            # 开始新章节
+            current_section = line[3:].strip()
+            current_content = [line]
+        else:
+            if current_section:
+                current_content.append(line)
+
+    # 保存最后一个章节
+    if current_section:
+        sections.append({
+            'title': current_section,
+            'content': '\n'.join(current_content)
+        })
+
+    return sections
+```
+
+### 文件名映射
+
+```python
+def get_filename(section_title, doc_type):
+    """
+    根据章节标题生成文件名
+
+    Args:
+        section_title: 章节标题
+        doc_type: 文档类型
+
+    Returns:
+        str: 文件名
+    """
+    # Spec 映射
+    spec_mapping = {
+        '功能概述': 'overview.md',
+        '用户故事': 'user-stories.md',
+        '验收标准': 'acceptance-criteria.md',
+        '约束条件': 'constraints.md',
+        '变更记录': 'changelog.md'
+    }
+
+    # Plan 映射
+    plan_mapping = {
+        '架构设计': 'architecture.md',
+        '数据模型': 'data-model.md',
+        'API设计': 'backend-api.md',
+        '后端实现': 'backend-impl.md',
+        '前端API': 'frontend-api.md',
+        '前端实现': 'frontend-impl.md',
+        '安全性': 'security.md',
+        '性能优化': 'performance.md',
+        '变更记录': 'changelog.md'
+    }
+
+    # Tasks 映射
+    if doc_type == 'tasks':
+        # Phase 0, Phase 1, Phase 2...
+        if 'Phase' in section_title:
+            phase_num = extract_phase_number(section_title)
+            phase_name = extract_phase_name(section_title)
+            return f'phase-{phase_num}-{phase_name}.md'
+        elif '依赖' in section_title:
+            return 'dependencies.md'
+        elif '检查点' in section_title:
+            return 'checkpoints.md'
+        elif '实现' in section_title:
+            return 'implementation-notes.md'
+
+    # 使用映射表
+    mapping = spec_mapping if doc_type == 'spec' else plan_mapping
+
+    for key, filename in mapping.items():
+        if key in section_title:
+            return filename
+
+    # 默认：转换为小写，替换空格为连字符
+    return section_title.lower().replace(' ', '-') + '.md'
+```
+
+## 注意事项
+
+1. **备份原文档**：拆分前必须备份原文档，防止数据丢失
+2. **验证完整性**：拆分后验证所有内容是否完整
+3. **链接更新**：确保所有内部链接正确指向新文件
+4. **保留格式**：保留原文档的 Markdown 格式和代码块
+5. **模式区分**: 手动模式需用户确认；--auto 模式跳过确认直接执行
+
+## 错误处理
+
+1. **文档不存在**：提示用户文档路径不正确
+2. **已经拆分**：提示用户文档已经拆分，是否重新拆分
+3. **行数不足**：提示用户文档行数未达到拆分阈值
+4. **章节识别失败**：提示用户文档结构不符合规范
+
+## 示例
+
+### 拆分 Spec 文档
+
+```bash
+/sdd-split spec {feature_id}
+```
+
+**输出**：
+
+```
+📄 正在分析文档: .specify/specs/{feature_id}/spec.md
+📊 文档行数: 614 行
+✅ 超过拆分阈值 (500 行)，建议拆分
+
+🔍 识别到以下章节：
+  1. 功能概述 (150 行)
+  2. 用户故事 (300 行)
+  3. 约束条件 (100 行)
+  4. 变更记录 (64 行)
+
+❓ 是否确认拆分？(y/n)
+```
+
+用户确认后：
+
+```
+✅ 开始拆分...
+📁 创建目录: spec/
+📝 生成 README.md
+📝 生成 overview.md
+📝 生成 user-stories.md
+📝 生成 constraints.md
+📝 生成 changelog.md
+📝 更新 spec.md (索引文件)
+💾 备份原文档: spec.md.backup
+
+✅ 拆分完成！
+```
+
+---
+
+## 相关文档
+
+- [SDD 规范](../../templates/README.md)
+- [模块化模板](../../templates/spec-modular-template/)