@trench-craft/sds 1.0.0

package/skills/core/claude-code-prompt/SKILL.md

@@ -0,0 +1,283 @@
+---
+id: "claude-code:prompt"
+name: "Prompt 工程"
+description: "构造和优化 AI 提示词"
+category: "core"
+phase: "always"
+---
+
+# Claude Code Prompt 工程
+
+本技能提供构造和优化 AI 提示词的方法论，帮助用户更有效地与 Claude 交互。
+
+## 核心原则
+
+### 1. 清晰性
+
+**明确表达意图：**
+- 使用具体而非模糊的词汇
+- 避免歧义和多义词
+- 提供足够的上下文
+
+**示例：**
+```
+❌ "帮我写个函数"
+✅ "编写一个 TypeScript 函数，接受用户 ID（字符串）作为参数，
+   返回用户对象（包含 name、email、createdAt 字段），
+   如果用户不存在则抛出 NotFoundError"
+```
+
+### 2. 结构化
+
+**使用清晰的结构：**
+- 分点列出需求
+- 使用 Markdown 格式化
+- 按重要性排序
+
+**模板：**
+```markdown
+## 目标
+[一句话描述最终目标]
+
+## 需求
+1. [需求 1]
+2. [需求 2]
+3. [需求 3]
+
+## 约束
+- [约束 1]
+- [约束 2]
+
+## 示例
+[输入/输出示例]
+```
+
+### 3. 具体性
+
+**提供具体细节：**
+- 技术栈和版本
+- 文件路径和位置
+- 输入输出格式
+- 错误处理要求
+
+**示例：**
+```
+❌ "优化这段代码"
+✅ "优化 src/utils/parser.ts 中的 parseConfig 函数：
+   - 当前性能瓶颈在第 45-60 行的嵌套循环
+   - 目标：将时间复杂度从 O(n²) 降到 O(n log n)
+   - 保持现有的函数签名和返回类型不变
+   - 确保所有现有测试通过"
+```
+
+## Prompt 模式
+
+### 模式 1: 角色设定
+
+```markdown
+你是一位资深的 TypeScript 开发者，专注于：
+- 类型安全
+- 性能优化
+- 代码可读性
+
+请以这个角色审查以下代码...
+```
+
+### 模式 2: 链式思考（Chain of Thought）
+
+```markdown
+请按以下步骤思考：
+
+1. **分析问题** - 理解需求和约束
+2. **设计方案** - 提出可能的解决方案
+3. **评估方案** - 比较优缺点
+4. **选择最优** - 给出推荐方案
+5. **实现细节** - 提供具体实现
+
+在每个步骤中明确你的推理过程。
+```
+
+### 模式 3: 少样本学习（Few-Shot）
+
+```markdown
+## 示例
+
+输入: "hello world"
+输出: "Hello World"
+
+输入: "foo bar baz"
+输出: "Foo Bar Baz"
+
+输入: "myVariableName"
+输出: "My Variable Name"
+
+## 任务
+
+请根据上述模式转换以下输入：
+输入: [你的输入]
+```
+
+### 模式 4: 约束满足
+
+```markdown
+## 需求
+[主要需求]
+
+## 必须满足的约束
+1. [硬约束 1] - 不满足则方案无效
+2. [硬约束 2] - 不满足则方案无效
+
+## 优先满足的约束
+1. [软约束 1] - 尽量满足
+2. [软约束 2] - 尽量满足
+
+## 可选优化
+1. [优化 1] - 如果可能
+2. [优化 2] - 如果可能
+```
+
+## 优化技巧
+
+### 技巧 1: 迭代优化
+
+```
+第 1 轮: 提供基本需求，获取初始方案
+第 2 轮: 指出问题和不足，要求改进
+第 3 轮: 细化细节，要求优化
+...
+```
+
+### 技巧 2: 对比评估
+
+```markdown
+请提供 3 个不同的解决方案：
+
+方案 A: [侧重性能]
+方案 B: [侧重可读性]
+方案 C: [侧重可维护性]
+
+对每个方案分析：
+- 优点
+- 缺点
+- 适用场景
+
+最后给出推荐。
+```
+
+### 技巧 3: 反向约束
+
+```markdown
+请确保你的方案：
+- 不使用任何第三方库
+- 不修改现有的 API 接口
+- 不增加额外的配置文件
+- 不引入新的依赖
+```
+
+### 技巧 4: 分步验证
+
+```markdown
+请按以下步骤完成任务：
+
+步骤 1: [任务描述]
+验证: [如何验证步骤 1 完成]
+
+步骤 2: [任务描述]
+验证: [如何验证步骤 2 完成]
+
+步骤 3: [任务描述]
+验证: [如何验证步骤 3 完成]
+```
+
+## 常见场景
+
+### 场景 1: 代码生成
+
+```markdown
+## 任务
+生成一个 [语言] 函数/类/模块
+
+## 规格
+- 输入: [参数类型和含义]
+- 输出: [返回类型和含义]
+- 行为: [功能描述]
+
+## 约束
+- [技术约束]
+- [性能约束]
+- [风格约束]
+
+## 示例
+[输入输出示例]
+```
+
+### 场景 2: 代码审查
+
+```markdown
+## 审查范围
+[文件路径和行号]
+
+## 关注点
+- [ ] 安全性
+- [ ] 性能
+- [ ] 可读性
+- [ ] 错误处理
+- [ ] 测试覆盖
+
+## 标准
+[团队的代码规范或最佳实践]
+```
+
+### 场景 3: 调试
+
+```markdown
+## 问题描述
+[现象和期望行为]
+
+## 复现步骤
+1. [步骤 1]
+2. [步骤 2]
+3. [步骤 3]
+
+## 已尝试
+- [尝试 1] - 结果: [失败原因]
+- [尝试 2] - 结果: [失败原因]
+
+## 环境
+- 操作系统: [OS]
+- 运行时版本: [Node/Python/etc.]
+- 依赖版本: [相关依赖]
+```
+
+### 场景 4: 架构设计
+
+```markdown
+## 背景
+[项目背景和业务需求]
+
+## 需求
+- [功能需求]
+- [非功能需求: 性能、可扩展性、安全性等]
+
+## 约束
+- [技术约束]
+- [资源约束]
+- [时间约束]
+
+## 期望输出
+- 架构图
+- 模块划分
+- 接口定义
+- 技术选型理由
+```
+
+## 红线
+
+| 错误行为 | 正确做法 |
+|---------|---------|
+| 模糊的需求描述 | 提供具体、明确的需求 |
+| 缺少上下文 | 提供足够的背景信息 |
+| 一次性要求太多 | 分步骤、迭代地要求 |
+| 忽略约束条件 | 明确列出所有约束 |
+| 不验证输出 | 要求提供验证步骤 |
+| 过度依赖单一 prompt | 使用多轮对话迭代优化 |

package/skills/core/claude-code-prompt/skill.yaml

@@ -0,0 +1,14 @@
+# skill.yaml
+id: "claude-code:prompt"
+version: "2.0.0"
+name: "prompt-manager"
+description: "构造和优化 AI 提示词"
+category: "core"
+phase: "always"
+source: "claude-code"
+trigger_conditions: []
+dependencies: ["claude-code:core"]
+inputs: []
+outputs: []
+size: "small"
+cache_ttl: "30d"

package/skills/core/claude-code-subagent/SKILL.md

@@ -0,0 +1,168 @@
+---
+id: "claude-code:subagent"
+name: "子代理调度"
+description: "创建和管理子代理执行任务"
+category: "core"
+phase: "always"
+---
+
+# Claude Code 子代理调度
+
+本技能提供创建和管理子代理（Subagent）的能力，用于并行执行独立任务。
+
+## 核心概念
+
+### 什么是子代理
+
+子代理是 Claude Code 会话中派生的独立执行单元，可以：
+- 并行处理多个独立任务
+- 拥有自己的上下文和工具访问权限
+- 将结果返回给主代理
+
+### 何时使用子代理
+
+**适合使用子代理的场景：**
+- 2 个以上可以独立进行的任务
+- 无共享状态的任务
+- 无顺序依赖的任务
+- 需要并行处理以提高效率
+
+**不适合使用子代理的场景：**
+- 任务之间有强依赖关系
+- 需要共享状态或上下文
+- 任务过于简单，调度开销不值得
+
+## 调度策略
+
+### 任务分解
+
+在调度子代理前，先将复杂任务分解为独立子任务：
+
+1. **识别独立性** - 分析任务之间的依赖关系
+2. **划分边界** - 确定每个子任务的输入和输出
+3. **分配资源** - 为每个子任务分配必要的上下文
+
+### 并行调度模式
+
+```yaml
+# 模式 1: 扇出-汇聚（Fan-Out/Fan-In）
+主任务:
+  - 分解为 N 个子任务
+  - 并行派发给 N 个子代理
+  - 等待所有子代理完成
+  - 汇聚结果
+
+# 模式 2: 流水线（Pipeline）
+阶段1 -> 阶段2 -> 阶段3
+每个阶段可以有多个并行子代理
+
+# 模式 3: 工作池（Worker Pool）
+任务队列 -> 子代理池 -> 结果收集
+动态分配任务给空闲子代理
+```
+
+## 使用方式
+
+### 创建子代理
+
+在 Claude Code 中，使用 `dispatching-parallel-agents` 技能来调度子代理：
+
+```
+当面对 2 个以上可以独立进行、无共享状态或顺序依赖的任务时使用
+```
+
+### 子代理配置
+
+每个子代理可以配置：
+- **任务描述** - 明确的输入和预期输出
+- **上下文** - 必要的背景信息和文件路径
+- **约束** - 时间限制、资源限制
+- **验证标准** - 如何判断任务完成
+
+### 结果汇聚
+
+子代理完成后，主代理需要：
+1. **收集结果** - 从所有子代理获取输出
+2. **验证完整性** - 确保所有任务都已完成
+3. **处理错误** - 处理失败的子任务
+4. **整合输出** - 将结果合并为最终输出
+
+## 最佳实践
+
+### 任务粒度
+
+- **不要太细** - 避免创建过多小子任务，增加调度开销
+- **不要太粗** - 避免单个任务过大，失去并行优势
+- **适中原则** - 每个子任务应该在 1-5 分钟内完成
+
+### 上下文管理
+
+```markdown
+# 子代理上下文模板
+
+## 任务描述
+[清晰描述任务目标]
+
+## 输入
+- 文件路径: [相关文件]
+- 数据: [必要数据]
+- 约束: [限制条件]
+
+## 预期输出
+- [输出格式和内容]
+
+## 验证标准
+- [如何判断任务完成]
+```
+
+### 错误处理
+
+1. **超时处理** - 为子任务设置合理超时
+2. **重试策略** - 对于暂时性失败，允许重试
+3. **降级方案** - 子任务失败时的备选方案
+4. **日志记录** - 记录子代理的执行过程
+
+## 常见用例
+
+### 用例 1: 并行代码审查
+
+```
+主代理: 收到代码审查请求
+├─ 子代理1: 安全审查
+├─ 子代理2: 性能审查
+├─ 子代理3: 代码风格审查
+└─ 子代理4: 测试覆盖审查
+主代理: 汇聚所有审查结果
+```
+
+### 用例 2: 多文件重构
+
+```
+主代理: 收到重构需求
+├─ 子代理1: 重构模块 A
+├─ 子代理2: 重构模块 B
+├─ 子代理3: 重构模块 C
+└─ 子代理4: 更新测试
+主代理: 验证整体一致性
+```
+
+### 用例 3: 并行测试
+
+```
+主代理: 运行完整测试套件
+├─ 子代理1: 单元测试
+├─ 子代理2: 集成测试
+├─ 子代理3: E2E 测试
+└─ 子代理4: 性能测试
+主代理: 生成测试报告
+```
+
+## 红线
+
+| 错误行为 | 正确做法 |
+|---------|---------|
+| 创建过多子代理 | 控制并发数量，通常 3-5 个 |
+| 忽略子代理失败 | 处理错误并提供降级方案 |
+| 不验证结果 | 汇聚时验证每个子任务输出 |
+| 共享可变状态 | 通过输入/输出传递数据 |
+| 无超时限制 | 为每个子任务设置超时 |

package/skills/core/claude-code-subagent/skill.yaml

@@ -0,0 +1,14 @@
+# skill.yaml
+id: "claude-code:subagent"
+version: "2.0.0"
+name: "subagent-dispatcher"
+description: "创建和管理子代理执行任务"
+category: "core"
+phase: "always"
+source: "claude-code"
+trigger_conditions: []
+dependencies: ["claude-code:core"]
+inputs: []
+outputs: []
+size: "small"
+cache_ttl: "30d"

package/skills/core/e2e-generate/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: e2e-generate
+description: "从 specs.md 驱动生成 E2E 测试需求、计划和代码骨架。在 opsx:apply 完成后、opsx:verify 之前使用。借鉴 prodready 的 E2E-as-first-class-citizen 设计。"
+---
+
+# E2E 测试生成
+
+从规格文档驱动生成 E2E 测试，而非依赖实现者手写。
+
+## 触发条件
+
+**触发**：
+- opsx:apply 已完成，业务代码已实现
+- 用户要求"生成 E2E 测试"或"跑 E2E"
+- specs.md 中有 MUST/SHALL 级别的需求
+
+**不触发**：
+- ❌ specs.md 尚未生成
+- ❌ 业务代码尚未实现
+
+**开始时宣布：** "我正在使用 e2e-generate 技能生成 E2E 测试。"
+
+## SDS Workflow 位置
+
+```
+Phase 4          Phase 5            Phase 6          Phase 7
+opsx:apply   →   e2e-generate   →  opsx:verify    →  opsx:archive
+                 │
+                 ├── e2e/requirements.md（覆盖矩阵）
+                 ├── e2e/plan.md（测试计划）
+                 ├── e2e/tests/*.test.ts（测试骨架）
+                 └── e2e/report.md（执行报告）
+```
+
+## 流程
+
+### 阶段 1：自动生成 E2E 需求
+
+从 specs.md 解析所有 MUST/SHALL/SHOULD 需求，为每个需求生成测试用例：
+
+- **正向路径**：正常流程应该成功
+- **反向路径**（MUST/SHALL）：参数错误、权限不足等异常
+- **边界情况**（MUST）：空值、极值、并发等
+
+输出：`e2e/requirements.md`
+
+### 阶段 2：自动生成 E2E 计划
+
+输出：`e2e/plan.md`
+
+### 阶段 3：自动生成测试代码骨架
+
+为每个需求生成 fail-first 的测试文件。
+
+输出：`e2e/tests/*.test.ts`
+
+### 阶段 4：调度子代理填充测试代码
+
+使用以下模板调度子代理填充测试代码：
+
+```
+spawn_agent:
+  description: "填充 E2E 测试代码"
+  message: |
+    你正在为以下 E2E 测试需求填充测试代码。
+
+    ## E2E 需求文档
+    [e2e/requirements.md 的完整内容]
+
+    ## 测试代码骨架
+    [e2e/tests/*.test.ts 中需要填充的文件内容]
+
+    ## 业务代码
+    [相关的业务代码文件路径和内容]
+
+    ## 你的工作
+
+    1. 阅读 E2E 需求文档，理解每个测试用例的预期行为
+    2. 阅读业务代码，了解 API 接口和数据格式
+    3. 填充每个测试文件中的 TODO：
+       - 设置测试数据（使用 beforeAll / beforeEach）
+       - 调用 API 或函数
+       - 编写断言（验证状态码、响应格式、业务逻辑）
+    4. 移除 `expect(true).toBe(false)` fail-first 占位
+    5. 运行测试确认可以通过
+
+    ## 要求
+
+    - 测试必须覆盖正向+反向+边界情况
+    - 测试数据必须独立，不依赖其他测试的执行顺序
+    - 每个测试必须可以单独运行
+    - 使用项目已有的测试工具和辅助函数
+```
+
+### 阶段 5：调度子代理执行测试并生成报告
+
+```
+spawn_agent:
+  description: "执行 E2E 测试并生成报告"
+  message: |
+    你正在执行 E2E 测试并生成执行报告。
+
+    ## 测试目录
+    e2e/tests/
+
+    ## 你的工作
+
+    1. 运行所有 E2E 测试
+    2. 收集测试结果（通过/失败/跳过）
+    3. 对于失败的测试：
+       - 分析失败原因
+       - 记录错误信息
+       - 提供排查方向
+    4. 生成执行报告到 e2e/report.md
+
+    ## 报告格式
+
+    # E2E 执行报告
+
+    **结果：** ✅/❌ X/Y 通过 (XX.X%)
+    **耗时：** Xs
+
+    | # | 测试用例 | 结果 | 耗时 |
+    |---|----------|------|------|
+    | 1 | TC-001: 用户注册 | ✅ | 123ms |
+
+    ## 失败分析（如有）
+    ### TC-XXX: [用例名]
+    **错误：** [错误信息]
+    **排查方向：** [建议]
+```
+
+## 与 prodready 的区别
+
+| 维度 | prodready | TrenchCraft E2E |
+|------|-----------|-----------------|
+| 流水线 | 7 个独立阶段 | 1 个技能（3 步自动生成 + 2 步子代理） |
+| 耗时 | ~27 分钟（含完整流水线） | ~3 分钟生成 + 按需填充 |
+| 触发 | 固定阶段，不可跳过 | 可选，apply 后按需触发 |
+| 灵活性 | 测试策略也走完整流水线 | 生成骨架后自由填充 |
+
+## 要点
+
+- **specs.md 是唯一输入** — E2E 从规格驱动生成，不看实现代码
+- **fail-first** — 生成的测试骨架默认失败，填充后才通过
+- **覆盖矩阵** — requirements.md 清晰展示需求→测试的映射
+- **可选阶段** — 不强制，小功能可以跳过

package/skills/core/e2e-generate/skill.yaml

@@ -0,0 +1,12 @@
+id: "e2e-generate"
+version: "2.0.0"
+name: "e2e-generate"
+description: "从 specs.md 驱动生成 E2E 测试需求、计划和代码骨架"
+category: "core"
+phase: "phase-4"
+source: "superpowers"
+dependencies: ["opsx:apply"]
+inputs: ["openspec/changes/{name}/specs.md"]
+outputs: ["openspec/changes/{name}/e2e/requirements.md", "openspec/changes/{name}/e2e/plan.md", "openspec/changes/{name}/e2e/tests/"]
+size: "medium"
+cache_ttl: "7d"