@waoooo/claude-skills 1.0.0

package/skills/spec-generate/SKILL.md

@@ -0,0 +1,408 @@
+# Skill: spec-generate
+
+## 功能
+
+生成 specs/ 目录的所有文件，包括 README.md、tasks.json、verification.json、progress.json。
+
+## 何时调用
+
+- capability-analyze 完成后
+- 需要生成开发规范时
+- 需要创建任务列表时
+
+## 输入
+
+- `jobId` - Job ID（例如：2026-02-10-1520-pricing-system）
+- `analysisPath` - 能力分析文件路径（capability-analysis.json）
+- `unifiedPath` - 统一需求文件路径（unified.json）
+
+## 输出
+
+- `specs/README.md` - 开发规范总览
+- `specs/tasks.json` - 任务列表（按执行顺序）
+- `specs/verification.json` - 验证命令
+- `specs/progress.json` - 进度跟踪
+
+## 执行步骤
+
+### 1. 生成 specs 目录
+
+```bash
+pnpm spec:generate-specs \
+  exports/jobs/<job-id>/analysis/capability-analysis.json \
+  exports/jobs/<job-id>/parsed/unified.json \
+  exports/jobs/<job-id>/specs/
+```
+
+**输出**：`specs/` 目录及所有文件
+
+### 2. 文件结构
+
+#### specs/README.md
+
+```markdown
+# Development Specification: Pricing System
+
+**Job ID**: 2026-02-10-1520-pricing-system  
+**Generated**: 2026-02-10T15:30:00Z  
+**Status**: Ready for Development
+
+## Overview
+
+This specification outlines the development plan for the Pricing System feature.
+
+## Summary
+
+- **Total Requirements**: 5
+- **Required Capabilities**: 8
+- **Available Capabilities**: 5
+- **Missing Capabilities**: 3
+- **Estimated Tasks**: 12
+
+## Capabilities
+
+### ✅ Available (5)
+
+| Capability | Layer | Status | Action |
+|------------|-------|--------|--------|
+| auth | L1 | available | Use existing |
+| user-profile | L2 | available | Use existing |
+| ... | ... | ... | ... |
+
+### ❌ Missing (3)
+
+| Capability | Layer | Priority | Action |
+|------------|-------|----------|--------|
+| payment-gateway | L2 | High | Develop |
+| invoice | L3 | Medium | Develop |
+| ... | ... | ... | ... |
+
+### 🔍 Implemented but Not in Tree (2)
+
+| Capability | Detected In | Action |
+|------------|-------------|--------|
+| pricing | src/modules/pricing/ | Update tree |
+| discount | src/modules/discount/ | Update tree |
+
+## Dependencies
+
+```mermaid
+graph TD
+  auth --> payment-gateway
+  payment-gateway --> pricing
+  pricing --> invoice
+```
+
+## Execution Plan
+
+### Phase 1: Foundation (L1)
+- Use existing `auth` capability
+
+### Phase 2: Core Features (L2)
+- Develop `payment-gateway`
+- Integrate with `auth`
+
+### Phase 3: Business Logic (L3)
+- Develop `pricing` engine
+- Develop `invoice` system
+
+## Tasks
+
+See [tasks.json](./tasks.json) for detailed task list.
+
+## Verification
+
+See [verification.json](./verification.json) for test commands.
+
+## Progress Tracking
+
+See [progress.json](./progress.json) for current status.
+```
+
+#### specs/tasks.json
+
+```json
+{
+  "version": "1.0.0",
+  "jobId": "2026-02-10-1520-pricing-system",
+  "generatedAt": "2026-02-10T15:30:00Z",
+  "tasks": [
+    {
+      "taskId": "TASK-001",
+      "title": "Develop payment-gateway capability",
+      "type": "capability-development",
+      "priority": "high",
+      "layer": "L2",
+      "capability": "payment-gateway",
+      "requirements": ["REQ-PRICING-022"],
+      "dependencies": ["auth"],
+      "estimatedHours": 8,
+      "status": "pending",
+      "subtasks": [
+        {
+          "id": "TASK-001-1",
+          "title": "Design payment gateway interface",
+          "status": "pending"
+        },
+        {
+          "id": "TASK-001-2",
+          "title": "Implement Stripe integration",
+          "status": "pending"
+        },
+        {
+          "id": "TASK-001-3",
+          "title": "Add payment webhook handlers",
+          "status": "pending"
+        }
+      ],
+      "verification": [
+        "pnpm test:payment-gateway",
+        "pnpm build"
+      ]
+    },
+    {
+      "taskId": "TASK-002",
+      "title": "Update capability tree with pricing",
+      "type": "documentation",
+      "priority": "medium",
+      "capability": "pricing",
+      "estimatedHours": 1,
+      "status": "pending",
+      "subtasks": [
+        {
+          "id": "TASK-002-1",
+          "title": "Document pricing capability",
+          "status": "pending"
+        },
+        {
+          "id": "TASK-002-2",
+          "title": "Add to capability-tree.json",
+          "status": "pending"
+        }
+      ],
+      "verification": [
+        "pnpm capability:build-tree"
+      ]
+    }
+  ],
+  "executionOrder": ["TASK-001", "TASK-002"],
+  "summary": {
+    "totalTasks": 2,
+    "pending": 2,
+    "inProgress": 0,
+    "completed": 0,
+    "estimatedHours": 9
+  }
+}
+```
+
+#### specs/verification.json
+
+```json
+{
+  "version": "1.0.0",
+  "jobId": "2026-02-10-1520-pricing-system",
+  "generatedAt": "2026-02-10T15:30:00Z",
+  "verifications": [
+    {
+      "id": "VERIFY-001",
+      "name": "Type Check",
+      "command": "pnpm type-check",
+      "required": true,
+      "runBefore": "commit"
+    },
+    {
+      "id": "VERIFY-002",
+      "name": "Unit Tests",
+      "command": "pnpm test",
+      "required": true,
+      "runBefore": "commit"
+    },
+    {
+      "id": "VERIFY-003",
+      "name": "Build",
+      "command": "pnpm build",
+      "required": true,
+      "runBefore": "push"
+    },
+    {
+      "id": "VERIFY-004",
+      "name": "Payment Gateway Tests",
+      "command": "pnpm test:payment-gateway",
+      "required": true,
+      "runBefore": "merge"
+    }
+  ],
+  "preCommitChecks": ["VERIFY-001", "VERIFY-002"],
+  "prePushChecks": ["VERIFY-003"],
+  "preMergeChecks": ["VERIFY-004"]
+}
+```
+
+#### specs/progress.json
+
+```json
+{
+  "version": "1.0.0",
+  "jobId": "2026-02-10-1520-pricing-system",
+  "updatedAt": "2026-02-10T15:30:00Z",
+  "status": "pending",
+  "progress": {
+    "totalTasks": 2,
+    "completed": 0,
+    "inProgress": 0,
+    "pending": 2,
+    "percentage": 0
+  },
+  "timeline": [
+    {
+      "timestamp": "2026-02-10T15:30:00Z",
+      "event": "specs-generated",
+      "description": "Development specifications generated"
+    }
+  ],
+  "currentTask": null,
+  "nextTask": "TASK-001",
+  "blockers": []
+}
+```
+
+### 3. 验证输出
+
+- 检查 specs/ 目录是否创建
+- 检查所有 4 个文件是否生成
+- 检查 JSON 格式是否正确
+- 检查任务顺序是否合理
+
+## 使用示例
+
+### 示例 1：完整流程
+
+```
+Agent 调用 spec-generate:
+  输入:
+  - jobId: 2026-02-10-1520-pricing-system
+  - analysisPath: exports/jobs/.../capability-analysis.json
+  - unifiedPath: exports/jobs/.../unified.json
+
+执行:
+  🔧 步骤 1: 加载数据
+  ⏳ 读取: capability-analysis.json
+  ⏳ 读取: unified.json
+
+  🔧 步骤 2: 生成 specs
+  ⏳ 运行: pnpm spec:generate-specs
+  ✅ 生成: specs/README.md
+  ✅ 生成: specs/tasks.json
+  ✅ 生成: specs/verification.json
+  ✅ 生成: specs/progress.json
+
+显示结果:
+  📋 开发规范已生成
+
+  📄 文件:
+  - README.md (开发规范总览)
+  - tasks.json (12 个任务)
+  - verification.json (4 个验证命令)
+  - progress.json (进度跟踪)
+
+  📊 任务统计:
+  - 能力开发: 3 个任务
+  - 文档更新: 2 个任务
+  - 集成对接: 7 个任务
+  - 预计工时: 24 小时
+
+  🔗 执行顺序:
+  1. TASK-001: Develop payment-gateway (8h)
+  2. TASK-002: Update capability tree (1h)
+  3. TASK-003: Develop invoice system (6h)
+  ...
+
+  💡 下一步:
+  1. 查看 specs/README.md 了解完整规范
+  2. 按 tasks.json 顺序执行开发
+  3. 每完成一个任务运行验证命令
+```
+
+### 示例 2：无缺失能力（全部可用）
+
+```
+Agent 调用 spec-generate:
+  输入:
+  - jobId: 2026-02-10-1600-simple-feature
+  - analysisPath: exports/jobs/.../capability-analysis.json
+  - unifiedPath: exports/jobs/.../unified.json
+
+执行:
+  🔧 步骤 1: 加载数据
+  ⏳ 读取: capability-analysis.json
+  ⏳ 读取: unified.json
+
+  🔧 步骤 2: 生成 specs
+  ✅ 生成: specs/README.md
+  ✅ 生成: specs/tasks.json
+  ✅ 生成: specs/verification.json
+  ✅ 生成: specs/progress.json
+
+显示结果:
+  📋 开发规范已生成
+
+  ✅ 所有能力都可用！
+
+  📊 任务统计:
+  - 集成对接: 3 个任务
+  - 预计工时: 4 小时
+
+  💡 下一步:
+  直接开始集成现有能力
+```
+
+## 错误处理
+
+### 错误 1：分析文件不存在
+
+```
+❌ 错误: 找不到能力分析文件
+🔍 原因: capability-analysis.json 不存在
+
+💡 建议:
+1. 先运行 capability-analyze Skill
+2. 确认分析文件路径正确
+```
+
+### 错误 2：无法生成任务
+
+```
+❌ 错误: 无法生成任务列表
+🔍 原因: 需求中没有明确的任务描述
+
+💡 建议:
+1. 检查 unified.json 中的 tasks 字段
+2. 手动补充任务描述
+3. 重新运行生成
+```
+
+### 错误 3：验证命令无效
+
+```
+❌ 错误: 验证命令不存在
+🔍 原因: package.json 中没有对应的脚本
+
+💡 建议:
+1. 检查 package.json 的 scripts
+2. 添加缺失的验证命令
+3. 或修改 verification.json
+```
+
+## 相关脚本
+
+- `src/scripts/generate-specs.ts` - 生成 specs 目录
+- `src/scripts/generate-tasks.ts` - 生成任务列表（已有）
+
+## 注意事项
+
+1. **任务顺序** - 基于依赖关系和层级生成
+2. **验证命令** - 根据项目类型自动推断
+3. **进度跟踪** - 初始状态为 pending
+4. **README 格式** - 使用 Markdown + Mermaid
+5. **可读性** - 所有文件都要易于人类阅读和编辑