@waoooo/claude-skills 1.0.0

package/skills/roadmap-generate/SKILL.md

@@ -0,0 +1,396 @@
+# Skill: roadmap-generate
+
+## 功能
+
+生成全局视图：roadmap.json（所有 Job 的路线图）、global-todo.json（全局待办）、dependency-graph.json（依赖关系图）。
+
+## 何时调用
+
+- 单个 Job 的 spec-generate 完成后
+- 需要查看全局进度时
+- 需要分析跨 Job 依赖时
+
+## 输入
+
+- `jobsDir` - Jobs 目录路径（exports/jobs/）
+- `outputDir` - 输出目录路径（exports/generated/）
+
+## 输出
+
+- `generated/roadmap.json` - 全局路线图
+- `generated/global-todo.json` - 全局待办列表
+- `generated/dependency-graph.json` - 跨 Job 依赖关系图
+
+## 执行步骤
+
+### 1. 扫描所有 Job
+
+```bash
+pnpm generate:roadmap \
+  exports/jobs/ \
+  exports/generated/
+```
+
+**输出**：`generated/` 目录及所有文件
+
+### 2. 文件结构
+
+#### generated/roadmap.json
+
+```json
+{
+  "version": "1.0.0",
+  "generatedAt": "2026-02-10T16:00:00Z",
+  "summary": {
+    "totalJobs": 3,
+    "totalTasks": 45,
+    "completedTasks": 12,
+    "inProgressTasks": 5,
+    "pendingTasks": 28,
+    "totalEstimatedHours": 120,
+    "completedHours": 30,
+    "remainingHours": 90
+  },
+  "jobs": [
+    {
+      "jobId": "2026-02-10-1520-pricing-system",
+      "name": "Pricing System",
+      "status": "in-progress",
+      "createdAt": "2026-02-10T15:20:00Z",
+      "updatedAt": "2026-02-10T15:55:00Z",
+      "progress": {
+        "totalTasks": 12,
+        "completed": 3,
+        "inProgress": 2,
+        "pending": 7,
+        "percentage": 25
+      },
+      "capabilities": {
+        "required": 8,
+        "available": 5,
+        "missing": 3
+      },
+      "estimatedHours": 40,
+      "remainingHours": 30,
+      "nextTask": "TASK-004"
+    },
+    {
+      "jobId": "2026-02-09-1400-user-dashboard",
+      "name": "User Dashboard",
+      "status": "completed",
+      "createdAt": "2026-02-09T14:00:00Z",
+      "updatedAt": "2026-02-10T10:00:00Z",
+      "progress": {
+        "totalTasks": 8,
+        "completed": 8,
+        "inProgress": 0,
+        "pending": 0,
+        "percentage": 100
+      },
+      "capabilities": {
+        "required": 5,
+        "available": 5,
+        "missing": 0
+      },
+      "estimatedHours": 20,
+      "remainingHours": 0,
+      "nextTask": null
+    }
+  ],
+  "timeline": [
+    {
+      "date": "2026-02-09",
+      "jobs": ["user-dashboard"],
+      "tasksCompleted": 8,
+      "hoursSpent": 20
+    },
+    {
+      "date": "2026-02-10",
+      "jobs": ["pricing-system", "analytics-module"],
+      "tasksCompleted": 4,
+      "hoursSpent": 10
+    }
+  ],
+  "milestones": [
+    {
+      "id": "M1",
+      "name": "Q1 2026 - Core Features",
+      "targetDate": "2026-03-31",
+      "jobs": ["pricing-system", "analytics-module"],
+      "status": "in-progress",
+      "progress": 40
+    }
+  ]
+}
+```
+
+#### generated/global-todo.json
+
+```json
+{
+  "version": "1.0.0",
+  "generatedAt": "2026-02-10T16:00:00Z",
+  "summary": {
+    "totalTasks": 28,
+    "highPriority": 8,
+    "mediumPriority": 12,
+    "lowPriority": 8
+  },
+  "tasks": [
+    {
+      "taskId": "TASK-004",
+      "jobId": "2026-02-10-1520-pricing-system",
+      "jobName": "Pricing System",
+      "title": "Develop payment-gateway capability",
+      "priority": "high",
+      "status": "pending",
+      "estimatedHours": 8,
+      "dependencies": ["auth"],
+      "blockedBy": [],
+      "canStartNow": true
+    },
+    {
+      "taskId": "TASK-007",
+      "jobId": "2026-02-10-1600-analytics-module",
+      "jobName": "Analytics Module",
+      "title": "Implement data aggregation",
+      "priority": "medium",
+      "status": "pending",
+      "estimatedHours": 6,
+      "dependencies": ["database", "pricing"],
+      "blockedBy": ["TASK-004"],
+      "canStartNow": false
+    }
+  ],
+  "readyToStart": [
+    "TASK-004",
+    "TASK-005",
+    "TASK-010"
+  ],
+  "blocked": [
+    {
+      "taskId": "TASK-007",
+      "blockedBy": ["TASK-004"],
+      "reason": "Waiting for payment-gateway capability"
+    }
+  ]
+}
+```
+
+#### generated/dependency-graph.json
+
+```json
+{
+  "version": "1.0.0",
+  "generatedAt": "2026-02-10T16:00:00Z",
+  "nodes": [
+    {
+      "id": "auth",
+      "type": "capability",
+      "name": "Authentication",
+      "layer": "L1",
+      "status": "available",
+      "usedByJobs": ["pricing-system", "analytics-module"]
+    },
+    {
+      "id": "payment-gateway",
+      "type": "capability",
+      "name": "Payment Gateway",
+      "layer": "L2",
+      "status": "missing",
+      "requiredByJobs": ["pricing-system"]
+    },
+    {
+      "id": "2026-02-10-1520-pricing-system",
+      "type": "job",
+      "name": "Pricing System",
+      "status": "in-progress"
+    }
+  ],
+  "edges": [
+    {
+      "from": "auth",
+      "to": "payment-gateway",
+      "type": "capability-dependency"
+    },
+    {
+      "from": "payment-gateway",
+      "to": "2026-02-10-1520-pricing-system",
+      "type": "job-requires-capability"
+    },
+    {
+      "from": "2026-02-10-1520-pricing-system",
+      "to": "2026-02-10-1600-analytics-module",
+      "type": "job-blocks-job"
+    }
+  ],
+  "clusters": {
+    "L1": ["auth", "user-profile"],
+    "L2": ["payment-gateway", "dashboard"],
+    "L3": ["pricing", "analytics"]
+  }
+}
+```
+
+### 3. 验证输出
+
+- 检查 generated/ 目录是否创建
+- 检查所有 3 个文件是否生成
+- 检查 JSON 格式是否正确
+- 检查统计数据是否准确
+
+## 使用示例
+
+### 示例 1：生成全局视图
+
+```
+Agent 调用 roadmap-generate:
+  输入:
+  - jobsDir: exports/jobs/
+  - outputDir: exports/generated/
+
+执行:
+  🔧 步骤 1: 扫描 Jobs
+  ⏳ 扫描: exports/jobs/
+  ✅ 找到 3 个 Job
+
+  🔧 步骤 2: 聚合数据
+  ⏳ 读取: 3 个 metadata.json
+  ⏳ 读取: 3 个 tasks.json
+  ⏳ 读取: 3 个 progress.json
+
+  🔧 步骤 3: 分析依赖
+  ⏳ 分析: 跨 Job 能力依赖
+  ⏳ 分析: 任务阻塞关系
+
+  🔧 步骤 4: 生成视图
+  ⏳ 运行: pnpm generate:roadmap
+  ✅ 生成: roadmap.json
+  ✅ 生成: global-todo.json
+  ✅ 生成: dependency-graph.json
+
+显示结果:
+  📋 全局视图已生成
+
+  📊 总览:
+  - 总 Job 数: 3
+  - 总任务数: 45
+  - 已完成: 12 (27%)
+  - 进行中: 5 (11%)
+  - 待开始: 28 (62%)
+
+  ⏱️  工时统计:
+  - 总预估: 120 小时
+  - 已完成: 30 小时
+  - 剩余: 90 小时
+
+  🚀 可立即开始的任务 (3):
+  - TASK-004: Develop payment-gateway (8h)
+  - TASK-005: Update capability tree (1h)
+  - TASK-010: Implement dashboard UI (6h)
+
+  🔒 被阻塞的任务 (5):
+  - TASK-007: 等待 payment-gateway
+  - TASK-012: 等待 pricing
+  - ...
+
+  🔗 跨 Job 依赖:
+  - pricing-system → analytics-module
+  - analytics-module → reporting-system
+```
+
+### 示例 2：单个 Job（无跨 Job 依赖）
+
+```
+Agent 调用 roadmap-generate:
+  输入:
+  - jobsDir: exports/jobs/
+  - outputDir: exports/generated/
+
+执行:
+  🔧 扫描 Jobs
+  ✅ 找到 1 个 Job
+
+  🔧 生成视图
+  ✅ 生成: roadmap.json
+  ✅ 生成: global-todo.json
+  ✅ 生成: dependency-graph.json
+
+显示结果:
+  📋 全局视图已生成
+
+  📊 总览:
+  - 总 Job 数: 1
+  - 总任务数: 12
+  - 待开始: 12 (100%)
+
+  💡 提示:
+  这是第一个 Job，没有跨 Job 依赖
+```
+
+## 错误处理
+
+### 错误 1：Jobs 目录为空
+
+```
+❌ 错误: Jobs 目录为空
+🔍 原因: exports/jobs/ 中没有 Job
+
+💡 建议:
+1. 先创建至少一个 Job
+2. 使用 job-create Skill
+```
+
+### 错误 2：Job 数据不完整
+
+```
+❌ 错误: Job 数据不完整
+🔍 原因: 某个 Job 缺少 tasks.json
+
+💡 建议:
+1. 检查 Job 目录结构
+2. 重新运行 spec-generate
+3. 跳过不完整的 Job
+```
+
+### 错误 3：依赖循环
+
+```
+❌ 错误: 检测到跨 Job 依赖循环
+🔍 原因: Job A → Job B → Job C → Job A
+
+💡 建议:
+1. 检查 Job 之间的依赖关系
+2. 手动调整依赖
+3. 重新生成
+```
+
+## 相关脚本
+
+- `src/scripts/generate-roadmap.ts` - 生成全局视图
+
+## 注意事项
+
+1. **增量更新** - 每次只更新变化的 Job
+2. **性能优化** - Job 数量多时使用缓存
+3. **数据一致性** - 确保所有 Job 的数据格式一致
+4. **可视化** - dependency-graph.json 可用于前端可视化
+5. **实时性** - 建议每次 Job 更新后重新生成
+
+## 高级功能（阶段 2）
+
+### 1. 自动调度
+- 根据依赖关系自动安排任务顺序
+- 识别可并行执行的任务
+
+### 2. 资源分配
+- 根据工时预估分配开发资源
+- 识别瓶颈任务
+
+### 3. 风险预警
+- 识别高风险依赖
+- 预测延期风险
+
+### 4. 进度预测
+- 根据历史数据预测完成时间
+- 生成燃尽图数据