@waoooo/claude-skills 1.0.0

package/skills/roadmap-docs-generate/SKILL.md

@@ -0,0 +1,483 @@
+# Skill: roadmap-docs-generate
+
+## 功能
+
+将 JSON 格式的数据转换为 MDX 格式的规划文档，用于项目管理和进度跟踪。
+
+## 何时调用
+
+- **步骤 13**（规划阶段）：生成初始规划文档
+- **步骤 24**（归档阶段）：更新最终规划文档
+
+## 输入
+
+- `roadmapPath` - roadmap.json 文件路径
+- `todoPath` - global-todo.json 文件路径
+- `dependencyPath` - dependency-graph.json 文件路径
+- `outputDir` - 输出目录（例如：waoooo-docs/developer-docs/planning/）
+
+## 输出
+
+- `ROADMAP.md` - 项目路线图
+- `TODO.md` - 全局待办列表
+- `DEPENDENCIES.md` - 依赖关系文档
+
+## 转换逻辑
+
+### 1. roadmap.json → ROADMAP.md
+
+**输入示例**：
+```json
+{
+  "version": "1.0.0",
+  "generatedAt": "2026-02-11T03:14:51Z",
+  "summary": {
+    "totalJobs": 3,
+    "completedJobs": 1,
+    "inProgressJobs": 1,
+    "pendingJobs": 1
+  },
+  "jobs": [
+    {
+      "id": "2026-02-10-1520-pricing-system",
+      "name": "Pricing System",
+      "status": "completed",
+      "progress": 100,
+      "startedAt": "2026-02-10T15:20:00Z",
+      "completedAt": "2026-02-11T10:30:00Z",
+      "totalTasks": 12,
+      "completedTasks": 12
+    }
+  ]
+}
+```
+
+**输出模板**：
+```markdown
+# Project Roadmap
+
+**Generated**: {generatedAt}  
+**Total Jobs**: {totalJobs}  
+**Status**: {completedJobs} completed, {inProgressJobs} in progress, {pendingJobs} pending
+
+---
+
+## Overview
+
+| Status | Count | Percentage |
+|--------|-------|------------|
+| ✅ Completed | {completedJobs} | {completedPercentage}% |
+| 🔄 In Progress | {inProgressJobs} | {inProgressPercentage}% |
+| ⏳ Pending | {pendingJobs} | {pendingPercentage}% |
+
+---
+
+## Jobs
+
+### ✅ Completed ({completedJobs})
+
+{for each completed job}
+#### {job.name}
+- **Job ID**: {job.id}
+- **Status**: Completed
+- **Progress**: {job.progress}%
+- **Started**: {job.startedAt}
+- **Completed**: {job.completedAt}
+- **Duration**: {duration}
+- **Tasks**: {job.completedTasks}/{job.totalTasks}
+{end for}
+
+---
+
+### 🔄 In Progress ({inProgressJobs})
+
+{for each in-progress job}
+#### {job.name}
+- **Job ID**: {job.id}
+- **Status**: In Progress
+- **Progress**: {job.progress}%
+- **Started**: {job.startedAt}
+- **Tasks**: {job.completedTasks}/{job.totalTasks}
+{end for}
+
+---
+
+### ⏳ Pending ({pendingJobs})
+
+{for each pending job}
+#### {job.name}
+- **Job ID**: {job.id}
+- **Status**: Pending
+- **Tasks**: {job.totalTasks}
+{end for}
+```
+
+### 2. global-todo.json → TODO.md
+
+**输入示例**：
+```json
+{
+  "version": "1.0.0",
+  "generatedAt": "2026-02-11T03:14:51Z",
+  "tasks": [
+    {
+      "taskId": "TASK-001",
+      "jobId": "2026-02-10-1520-pricing-system",
+      "jobName": "Pricing System",
+      "title": "Develop payment-gateway capability",
+      "status": "completed",
+      "priority": "high",
+      "canStartNow": false,
+      "blockedBy": [],
+      "estimatedHours": 8
+    }
+  ],
+  "summary": {
+    "total": 50,
+    "completed": 20,
+    "inProgress": 5,
+    "pending": 25,
+    "canStartNow": 8
+  }
+}
+```
+
+**输出模板**：
+```markdown
+# Global TODO
+
+**Generated**: {generatedAt}  
+**Total Tasks**: {total}  
+**Progress**: {completedPercentage}% ({completed}/{total} completed)
+
+---
+
+## Summary
+
+| Status | Count | Percentage |
+|--------|-------|------------|
+| ✅ Completed | {completed} | {completedPercentage}% |
+| 🔄 In Progress | {inProgress} | {inProgressPercentage}% |
+| ⏳ Pending | {pending} | {pendingPercentage}% |
+| 🚀 Can Start Now | {canStartNow} | {canStartNowPercentage}% |
+
+---
+
+## 🚀 Ready to Start ({canStartNow})
+
+Tasks that can be started immediately (no blockers):
+
+### High Priority
+
+{for each high priority task where canStartNow}
+- [ ] **{taskId}** - {title}  
+  Job: {jobName}  
+  Estimated: {estimatedHours}h
+{end for}
+
+### Medium Priority
+
+{for each medium priority task where canStartNow}
+- [ ] **{taskId}** - {title}  
+  Job: {jobName}  
+  Estimated: {estimatedHours}h
+{end for}
+
+---
+
+## 🔄 In Progress ({inProgress})
+
+{for each in-progress task}
+- [x] **{taskId}** - {title}  
+  Job: {jobName}  
+  Estimated: {estimatedHours}h  
+  Started: {startedAt}
+{end for}
+
+---
+
+## ✅ Completed ({completed})
+
+{group by job}
+### {jobName} ({count} tasks)
+
+{for each completed task in job}
+- [x] **{taskId}** - {title}  
+  Completed: {completedAt}  
+  Duration: {duration}
+{end for}
+{end group}
+
+---
+
+## ⏳ Pending ({pending})
+
+### Blocked ({blockedCount})
+
+Tasks waiting for dependencies:
+
+{for each blocked task}
+- [ ] **{taskId}** - {title}  
+  Job: {jobName}  
+  Blocked by: {blockedBy}  
+  Estimated: {estimatedHours}h
+{end for}
+
+### Not Started ({notStartedCount})
+
+Tasks not yet started:
+
+{for each not-started task}
+- [ ] **{taskId}** - {title}  
+  Job: {jobName}  
+  Estimated: {estimatedHours}h
+{end for}
+```
+
+### 3. dependency-graph.json → DEPENDENCIES.md
+
+**输入示例**：
+```json
+{
+  "version": "1.0.0",
+  "generatedAt": "2026-02-11T03:14:51Z",
+  "nodes": [
+    {
+      "id": "pricing",
+      "type": "capability",
+      "layer": "L3",
+      "status": "implemented"
+    }
+  ],
+  "edges": [
+    {
+      "from": "pricing",
+      "to": "membership",
+      "type": "requires"
+    }
+  ]
+}
+```
+
+**输出模板**：
+```markdown
+# Dependency Graph
+
+**Generated**: {generatedAt}  
+**Total Capabilities**: {totalCapabilities}  
+**Total Dependencies**: {totalDependencies}
+
+---
+
+## Overview
+
+\`\`\`mermaid
+graph TD
+{for each node}
+    {node.id}[{node.name}<br/>{node.layer} - {node.status}]
+{end for}
+
+{for each edge}
+    {edge.from} --> {edge.to}
+{end for}
+
+{style nodes by status}
+    style implemented fill:#4caf50,stroke:#2e7d32,color:#fff
+    style in-progress fill:#ff9800,stroke:#f57c00,color:#fff
+    style pending fill:#9e9e9e,stroke:#616161,color:#fff
+\`\`\`
+
+---
+
+## Capabilities by Layer
+
+{for each layer}
+### {layer}: {layerName} ({count})
+
+| Capability | Status | Requires | Required By |
+|------------|--------|----------|-------------|
+{for each capability in layer}
+| {capability.name} | {capability.status} | {capability.requires} | {capability.requiredBy} |
+{end for}
+{end for}
+
+---
+
+## Dependency Details
+
+{for each capability}
+### {capability.name}
+
+**Requires**:
+{for each required}
+- {required.name} ({required.layer}) - {required.status}
+{end for}
+
+**Required By**:
+{for each requiredBy}
+- {requiredBy.name} ({requiredBy.layer}) - {requiredBy.status}
+{end for}
+
+**Status**: {dependencyStatus}
+{end for}
+
+---
+
+## Critical Path
+
+The following capabilities are on the critical path:
+
+{for each critical capability}
+1. **{capability.name}** ({capability.layer}) → Required by {count} capabilities
+{end for}
+
+Delays in these capabilities will impact downstream work.
+```
+
+## 执行步骤
+
+### 1. 读取 JSON 文件
+
+```typescript
+const roadmap = JSON.parse(readFile(roadmapPath))
+const todo = JSON.parse(readFile(todoPath))
+const dependency = JSON.parse(readFile(dependencyPath))
+```
+
+### 2. 转换数据
+
+```typescript
+// ROADMAP.md
+const roadmapMd = generateRoadmapMd(roadmap)
+
+// TODO.md
+const todoMd = generateTodoMd(todo)
+
+// DEPENDENCIES.md
+const dependenciesMd = generateDependenciesMd(dependency)
+```
+
+### 3. 写入文件
+
+```typescript
+writeFile(`${outputDir}/ROADMAP.md`, roadmapMd)
+writeFile(`${outputDir}/TODO.md`, todoMd)
+writeFile(`${outputDir}/DEPENDENCIES.md`, dependenciesMd)
+```
+
+## 使用示例
+
+### 示例 1：规划阶段（步骤 13）
+
+```
+Agent 调用 roadmap-docs-generate:
+  输入:
+  - roadmapPath: exports/generated/roadmap.json
+  - todoPath: exports/generated/global-todo.json
+  - dependencyPath: exports/generated/dependency-graph.json
+  - outputDir: ../../../waoooo-docs/developer-docs/planning/
+
+执行:
+  🔧 步骤 1: 读取 JSON 文件
+  ⏳ 读取: roadmap.json (3 Jobs)
+  ⏳ 读取: global-todo.json (50 tasks)
+  ⏳ 读取: dependency-graph.json (15 capabilities)
+
+  🔧 步骤 2: 转换为 MDX
+  ⏳ 生成: ROADMAP.md
+  ⏳ 生成: TODO.md
+  ⏳ 生成: DEPENDENCIES.md
+
+  🔧 步骤 3: 写入文件
+  ✅ 写入: waoooo-docs/developer-docs/planning/ROADMAP.md
+  ✅ 写入: waoooo-docs/developer-docs/planning/TODO.md
+  ✅ 写入: waoooo-docs/developer-docs/planning/DEPENDENCIES.md
+
+显示结果:
+  ✅ 规划文档已生成
+
+  📄 生成的文件:
+  - ROADMAP.md (3 Jobs, 1 completed, 1 in progress, 1 pending)
+  - TODO.md (50 tasks, 20 completed, 5 in progress, 25 pending)
+  - DEPENDENCIES.md (15 capabilities, 23 dependencies)
+
+  💡 下一步:
+  用户可以查看规划文档，确认执行计划
+```
+
+### 示例 2：归档阶段（步骤 24）
+
+```
+Agent 调用 roadmap-docs-generate:
+  输入:
+  - roadmapPath: exports/generated/roadmap.json
+  - todoPath: exports/generated/global-todo.json
+  - dependencyPath: exports/generated/dependency-graph.json
+  - outputDir: ../../../waoooo-docs/developer-docs/planning/
+
+执行:
+  🔧 步骤 1-3: 读取、转换、写入
+
+显示结果:
+  ✅ 规划文档已更新（最终状态）
+
+  📄 更新的文件:
+  - ROADMAP.md (3 Jobs, 全部完成)
+  - TODO.md (50 tasks, 全部完成)
+  - DEPENDENCIES.md (15 capabilities, 全部实现)
+
+  💡 下一步:
+  归档完成，项目历史已记录
+```
+
+## 错误处理
+
+### 错误 1：JSON 文件不存在
+
+```
+❌ 错误: JSON 文件不存在
+🔍 原因: roadmap.json 文件未找到
+
+💡 建议:
+1. 检查文件路径
+2. 确认 roadmap-generate 已执行
+```
+
+### 错误 2：JSON 格式错误
+
+```
+❌ 错误: JSON 解析失败
+🔍 原因: global-todo.json 格式不正确
+
+💡 建议:
+1. 检查 JSON 格式
+2. 重新生成 JSON 文件
+```
+
+### 错误 3：输出目录不存在
+
+```
+❌ 错误: 输出目录不存在
+🔍 原因: waoooo-docs/developer-docs/planning/ 不存在
+
+💡 建议:
+1. 创建输出目录
+2. 或检查路径配置
+```
+
+## 注意事项
+
+1. **两次调用** - 步骤 13（初始）和步骤 24（最终）
+2. **覆盖写入** - 每次调用会覆盖现有文件
+3. **格式化** - 自动格式化表格、列表、Mermaid 图
+4. **时间格式** - 自动转换 ISO 时间为可读格式
+5. **百分比计算** - 自动计算进度百分比
+
+## 相关文件
+
+- `exports/generated/roadmap.json`
+- `exports/generated/global-todo.json`
+- `exports/generated/dependency-graph.json`
+- `waoooo-docs/developer-docs/planning/ROADMAP.md`
+- `waoooo-docs/developer-docs/planning/TODO.md`
+- `waoooo-docs/developer-docs/planning/DEPENDENCIES.md`

package/skills/roadmap-docs-generate/assets/templates/ROADMAP.mdx

@@ -0,0 +1,75 @@
+---
+title: '开发路线图'
+description: 'Waoooo 平台开发路线图 - 宏观规划和进度追踪'
+---
+
+> **最后更新**: {{lastUpdated}}
+> **维护者**: Product Builder (Auto-generated)
+> **数据来源**: roadmap.json v{{version}}
+
+本文档提供 Waoooo 平台的**宏观开发规划和进度追踪**，帮助团队了解整体方向和优先级。
+
+<Note>
+**ROADMAP 定位**：
+- 📊 **宏观视图**：提供整体方向和优先级
+- 🔄 **动态更新**：根据规划和 TODO 的变化自动更新
+- 🎯 **进度追踪**：可视化展示项目进度
+- 📝 **不包含细节**：详细实现内容在各能力的规划文档中
+- 🤖 **自动生成**：由 Product Builder 自动生成，请勿手动编辑
+</Note>
+
+---
+
+## 📊 总体进度
+
+| 指标 | 数值 |
+|------|------|
+| **总任务数** | {{totalTasks}} |
+| **已完成** | {{completedTasks}} |
+| **进行中** | {{inProgressTasks}} |
+| **待开始** | {{pendingTasks}} |
+| **完成率** | {{completionRate}}% |
+| **总预计工时** | {{totalEstimatedHours}}h |
+| **已完成工时** | {{completedHours}}h |
+| **剩余工时** | {{remainingHours}}h |
+
+<Note>
+**进度说明**：
+- 🎯 **当前完成率**: {{completionRate}}%
+- ⏱️ **预计剩余时间**: {{remainingHours}}h ({{remainingDays}} 工作日)
+- 📈 **总任务数**: {{totalTasks}} 个任务
+- 🚀 **活跃任务**: {{inProgressTasks}} 个任务正在进行中
+</Note>
+
+---
+
+## 📅 时间线
+
+{{timeline}}
+
+---
+
+## 🎯 里程碑
+
+{{milestones}}
+
+---
+
+## 🔗 相关文档
+
+<CardGroup cols={2}>
+  <Card title="TODO 列表" icon="list-check" href="/planning/todo">
+    查看具体待办任务
+  </Card>
+
+  <Card title="详细规划" icon="file-lines" href="/planning">
+    查看各能力的详细规划
+  </Card>
+</CardGroup>
+
+---
+
+**维护者**: Product Builder (Auto-generated)
+**最后更新**: {{generatedAt}}
+**数据版本**: {{version}}
+**生成时间**: {{sourceGeneratedAt}}