@waoooo/claude-skills 1.0.0

package/skills/capability-analyze/scripts/analyze-capabilities.ts

@@ -0,0 +1,531 @@
+/**
+ * Analyze Capabilities (Three-Way Comparison)
+ * 
+ * Compare: Requirements vs Capability Tree vs Project Code
+ * Output: capability-analysis.json with available/missing/implemented/dependencies
+ */
+
+import fs from 'fs';
+import path from 'path';
+import type { UnifiedRequirements } from '../types/unified-requirements';
+
+interface CapabilityTree {
+  id: string;
+  name: string;
+  layer: string;
+  status: string;
+  requires?: string[];
+  relatedTo?: string[];
+  children?: CapabilityTree[];
+}
+
+interface CapabilityStatus {
+  capId: string;
+  name: string;
+  layer: string;
+  status: 'available' | 'missing' | 'implemented' | 'available-not-impl';
+  source: 'capability-tree' | 'project-code' | 'both';
+  usedBy?: string[];
+  requiredBy?: string[];
+  detectedIn?: string[];
+  notInTree?: boolean;
+  suggestedAction?: 'use' | 'develop' | 'update-tree' | 'implement';
+}
+
+interface CapabilityAnalysis {
+  version: string;
+  jobId: string;
+  analyzedAt: string;
+  summary: {
+    totalRequirements: number;
+    requiredCapabilities: number;
+    availableCapabilities: number;
+    missingCapabilities: number;
+    implementedInProject: number;
+  };
+  capabilities: {
+    available: CapabilityStatus[];
+    missing: CapabilityStatus[];
+    implemented: CapabilityStatus[];
+  };
+  dependencies: {
+    graph: Record<string, { requires: string[]; blocks: string[] }>;
+    layers: Record<string, string[]>;
+    capabilityDependencies: Record<string, { requires: string[]; requiredBy: string[]; relatedTo: string[] }>;
+  };
+  recommendations: Array<{
+    type: 'develop' | 'update-tree' | 'implement' | 'use';
+    capability: string;
+    reason: string;
+    priority: 'high' | 'medium' | 'low';
+  }>;
+}
+
+/**
+ * Flatten capability tree to a map
+ */
+function flattenCapabilityTree(tree: CapabilityTree[], map: Map<string, CapabilityTree> = new Map()): Map<string, CapabilityTree> {
+  for (const cap of tree) {
+    map.set(cap.id, cap);
+    if (cap.children && cap.children.length > 0) {
+      flattenCapabilityTree(cap.children, map);
+    }
+  }
+  return map;
+}
+
+/**
+ * Extract required capabilities from unified requirements
+ */
+function extractRequiredCapabilities(unified: UnifiedRequirements): string[] {
+  const capabilities = new Set<string>();
+  
+  // From requirements
+  for (const req of unified.requirements || []) {
+    if (req.capabilityHints) {
+      for (const cap of req.capabilityHints) {
+        capabilities.add(cap);
+      }
+    }
+  }
+  
+  // From builder source
+  if (unified.sources?.builder?.capabilities) {
+    for (const cap of unified.sources.builder.capabilities) {
+      capabilities.add(cap);
+    }
+  }
+  
+  return Array.from(capabilities);
+}
+
+/**
+ * Detect capabilities in project code
+ */
+function detectProjectCapabilities(projectPath: string | null): Map<string, { detectedIn: string[] }> {
+  const detected = new Map<string, { detectedIn: string[] }>();
+  
+  if (!projectPath || !fs.existsSync(projectPath)) {
+    return detected;
+  }
+  
+  console.log(`  Scanning project: ${projectPath}`);
+  
+  // Scan directories for capability patterns
+  const scanDir = (dir: string, basePath: string = '') => {
+    if (!fs.existsSync(dir)) return;
+    
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.join(basePath, entry.name);
+      
+      // Skip node_modules, .git, etc.
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+        continue;
+      }
+      
+      if (entry.isDirectory()) {
+        // Check if directory name matches capability pattern
+        const capId = entry.name.toLowerCase();
+        if (!detected.has(capId)) {
+          detected.set(capId, { detectedIn: [] });
+        }
+        detected.get(capId)!.detectedIn.push(relativePath);
+        
+        // Recursively scan subdirectories
+        scanDir(fullPath, relativePath);
+      }
+    }
+  };
+  
+  scanDir(projectPath);
+  
+  return detected;
+}
+
+/**
+ * Three-way comparison: Requirements vs Capability Tree vs Project Code
+ */
+function threeWayComparison(
+  requiredCapabilities: string[],
+  capabilityMap: Map<string, CapabilityTree>,
+  projectCapabilities: Map<string, { detectedIn: string[] }>,
+  unified: UnifiedRequirements
+): {
+  available: CapabilityStatus[];
+  missing: CapabilityStatus[];
+  implemented: CapabilityStatus[];
+} {
+  const available: CapabilityStatus[] = [];
+  const missing: CapabilityStatus[] = [];
+  const implemented: CapabilityStatus[] = [];
+  
+  for (const capId of requiredCapabilities) {
+    const inTree = capabilityMap.get(capId);
+    const inProject = projectCapabilities.get(capId);
+    
+    // Find which requirements use this capability
+    const usedBy = unified.requirements
+      ?.filter(req => req.capabilityHints?.includes(capId))
+      .map(req => req.reqId) || [];
+    
+    if (inTree && inProject) {
+      // ✅ In tree AND in project
+      if (inTree.status === 'implemented') {
+        available.push({
+          capId: inTree.id,
+          name: inTree.name,
+          layer: inTree.layer,
+          status: 'available',
+          source: 'both',
+          usedBy,
+          suggestedAction: 'use',
+        });
+        console.log(`  ✅ ${inTree.name} - available (tree + project)`);
+      } else {
+        available.push({
+          capId: inTree.id,
+          name: inTree.name,
+          layer: inTree.layer,
+          status: 'available-not-impl',
+          source: 'both',
+          usedBy,
+          suggestedAction: 'implement',
+        });
+        console.log(`  ⚠️  ${inTree.name} - in tree but status: ${inTree.status}`);
+      }
+    } else if (inTree && !inProject) {
+      // ✅ In tree but NOT in project
+      if (inTree.status === 'implemented') {
+        available.push({
+          capId: inTree.id,
+          name: inTree.name,
+          layer: inTree.layer,
+          status: 'available',
+          source: 'capability-tree',
+          usedBy,
+          suggestedAction: 'use',
+        });
+        console.log(`  ✅ ${inTree.name} - available (tree only)`);
+      } else if (inTree.status === 'partial') {
+        // Partial implementation - in tree but not fully implemented
+        available.push({
+          capId: inTree.id,
+          name: inTree.name,
+          layer: inTree.layer,
+          status: 'available-not-impl',
+          source: 'capability-tree',
+          usedBy,
+          suggestedAction: 'implement',
+        });
+        console.log(`  ⚠️  ${inTree.name} - in tree but status: ${inTree.status}`);
+      } else {
+        // Planned or missing - not yet implemented
+        missing.push({
+          capId: inTree.id,
+          name: inTree.name,
+          layer: inTree.layer,
+          status: 'missing',
+          source: 'capability-tree',
+          requiredBy: usedBy,
+          suggestedAction: 'develop',
+        });
+        console.log(`  ❌ ${inTree.name} - in tree but not implemented (status: ${inTree.status})`);
+      }
+    } else if (!inTree && inProject) {
+      // 🔍 In project but NOT in tree
+      implemented.push({
+        capId,
+        name: capId,
+        layer: 'unknown',
+        status: 'implemented',
+        source: 'project-code',
+        detectedIn: inProject.detectedIn,
+        notInTree: true,
+        usedBy,
+        suggestedAction: 'update-tree',
+      });
+      console.log(`  🔍 ${capId} - implemented but not in tree`);
+    } else {
+      // ❌ NOT in tree AND NOT in project
+      missing.push({
+        capId,
+        name: capId,
+        layer: 'unknown',
+        status: 'missing',
+        source: 'capability-tree',
+        requiredBy: usedBy,
+        suggestedAction: 'develop',
+      });
+      console.log(`  ❌ ${capId} - missing (not in tree or project)`);
+    }
+  }
+  
+  return { available, missing, implemented };
+}
+
+/**
+ * Build capability dependency graph from capability tree
+ */
+function buildCapabilityDependencyGraph(capabilityMap: Map<string, CapabilityTree>): Record<string, { 
+  requires: string[]; 
+  requiredBy: string[]; 
+  relatedTo: string[] 
+}> {
+  const graph: Record<string, { requires: string[]; requiredBy: string[]; relatedTo: string[] }> = {};
+  
+  // Initialize graph for all capabilities
+  for (const [capId, cap] of capabilityMap.entries()) {
+    graph[capId] = {
+      requires: cap.requires || [],
+      requiredBy: [],
+      relatedTo: cap.relatedTo || [],
+    };
+  }
+  
+  // Build reverse dependencies (requiredBy)
+  for (const [capId, cap] of capabilityMap.entries()) {
+    if (cap.requires) {
+      for (const requiredCapId of cap.requires) {
+        if (graph[requiredCapId]) {
+          graph[requiredCapId].requiredBy.push(capId);
+        }
+      }
+    }
+  }
+  
+  return graph;
+}
+
+/**
+ * Build dependency graph from requirements
+ */
+function buildDependencyGraph(
+  unified: UnifiedRequirements,
+  capabilityMap: Map<string, CapabilityTree>
+): {
+  graph: Record<string, { requires: string[]; blocks: string[] }>;
+  layers: Record<string, string[]>;
+  capabilityDependencies: Record<string, { requires: string[]; requiredBy: string[]; relatedTo: string[] }>;
+} {
+  const graph: Record<string, { requires: string[]; blocks: string[] }> = {};
+  const layers: Record<string, string[]> = {};
+  
+  for (const req of unified.requirements || []) {
+    graph[req.reqId] = {
+      requires: req.capabilityHints || [],
+      blocks: req.blocks || [],
+    };
+    
+    // Group by layer
+    const layer = req.layerHint || 'unknown';
+    if (!layers[layer]) {
+      layers[layer] = [];
+    }
+    if (req.capabilityHints) {
+      layers[layer].push(...req.capabilityHints);
+    }
+  }
+  
+  // Build capability dependency graph
+  const capabilityDependencies = buildCapabilityDependencyGraph(capabilityMap);
+  
+  return { graph, layers, capabilityDependencies };
+}
+
+/**
+ * Generate recommendations
+ */
+function generateRecommendations(
+  available: CapabilityStatus[],
+  missing: CapabilityStatus[],
+  implemented: CapabilityStatus[],
+  capabilityDependencies: Record<string, { requires: string[]; requiredBy: string[]; relatedTo: string[] }>
+): Array<{
+  type: 'develop' | 'update-tree' | 'implement' | 'use';
+  capability: string;
+  reason: string;
+  priority: 'high' | 'medium' | 'low';
+}> {
+  const recommendations: Array<{
+    type: 'develop' | 'update-tree' | 'implement' | 'use';
+    capability: string;
+    reason: string;
+    priority: 'high' | 'medium' | 'low';
+  }> = [];
+  
+  // Missing capabilities - need to develop
+  for (const cap of missing) {
+    recommendations.push({
+      type: 'develop',
+      capability: cap.capId,
+      reason: `Required by ${cap.requiredBy?.join(', ') || 'requirements'}`,
+      priority: cap.layer === 'L1' ? 'high' : cap.layer === 'L2' ? 'medium' : 'low',
+    });
+  }
+  
+  // Implemented but not in tree - update tree
+  for (const cap of implemented) {
+    if (cap.notInTree) {
+      recommendations.push({
+        type: 'update-tree',
+        capability: cap.capId,
+        reason: `Implemented in project but not recorded in capability tree`,
+        priority: 'medium',
+      });
+    }
+  }
+  
+  // Available but not implemented - need to implement
+  for (const cap of available) {
+    if (cap.status === 'available-not-impl') {
+      const deps = capabilityDependencies[cap.capId];
+      let reason = `In capability tree but not implemented`;
+      
+      // Add dependency information
+      if (deps && deps.requires.length > 0) {
+        reason += `. Depends on: ${deps.requires.join(', ')}`;
+      }
+      
+      recommendations.push({
+        type: 'implement',
+        capability: cap.capId,
+        reason,
+        priority: 'high',
+      });
+    }
+  }
+  
+  return recommendations;
+}
+
+/**
+ * Main function
+ */
+function analyzeCapabilities(
+  unifiedPath: string,
+  capabilityTreePath: string,
+  outputPath: string,
+  projectPath: string | null = null,
+  jobId: string = 'unknown'
+) {
+  console.log('🔍 Analyzing capabilities (three-way comparison)...');
+  
+  // Read unified.json
+  if (!fs.existsSync(unifiedPath)) {
+    throw new Error(`Unified file not found: ${unifiedPath}`);
+  }
+  const unified: UnifiedRequirements = JSON.parse(fs.readFileSync(unifiedPath, 'utf-8'));
+  
+  // Read capability-tree.json
+  if (!fs.existsSync(capabilityTreePath)) {
+    throw new Error(`Capability tree not found: ${capabilityTreePath}`);
+  }
+  const capabilityTreeData = JSON.parse(fs.readFileSync(capabilityTreePath, 'utf-8'));
+  const capabilityTree: CapabilityTree[] = capabilityTreeData.capabilities || capabilityTreeData;
+  
+  // Flatten capability tree
+  const capabilityMap = flattenCapabilityTree(capabilityTree);
+  console.log(`  Found ${capabilityMap.size} capabilities in tree`);
+  
+  // Extract required capabilities
+  const requiredCapabilities = extractRequiredCapabilities(unified);
+  console.log(`  Required capabilities: ${requiredCapabilities.length}`);
+  
+  // Detect capabilities in project code
+  const projectCapabilities = detectProjectCapabilities(projectPath);
+  console.log(`  Detected ${projectCapabilities.size} capabilities in project`);
+  
+  // Three-way comparison
+  console.log('\n🔄 Three-way comparison:');
+  const { available, missing, implemented } = threeWayComparison(
+    requiredCapabilities,
+    capabilityMap,
+    projectCapabilities,
+    unified
+  );
+  
+  // Build dependency graph
+  const dependencies = buildDependencyGraph(unified, capabilityMap);
+  
+  // Generate recommendations
+  const recommendations = generateRecommendations(
+    available, 
+    missing, 
+    implemented,
+    dependencies.capabilityDependencies
+  );
+  
+  // Build analysis result
+  const analysis: CapabilityAnalysis = {
+    version: '1.0.0',
+    jobId,
+    analyzedAt: new Date().toISOString(),
+    summary: {
+      totalRequirements: unified.requirements?.length || 0,
+      requiredCapabilities: requiredCapabilities.length,
+      availableCapabilities: available.length,
+      missingCapabilities: missing.length,
+      implementedInProject: implemented.length,
+    },
+    capabilities: {
+      available,
+      missing,
+      implemented,
+    },
+    dependencies,
+    recommendations,
+  };
+  
+  // Write output
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  
+  fs.writeFileSync(outputPath, JSON.stringify(analysis, null, 2));
+  console.log(`\n✅ Capability analysis saved to: ${outputPath}`);
+  console.log(`   Total requirements: ${analysis.summary.totalRequirements}`);
+  console.log(`   Required capabilities: ${analysis.summary.requiredCapabilities}`);
+  console.log(`   Available: ${analysis.summary.availableCapabilities}`);
+  console.log(`   Missing: ${analysis.summary.missingCapabilities}`);
+  console.log(`   Implemented (not in tree): ${analysis.summary.implementedInProject}`);
+  console.log(`   Recommendations: ${recommendations.length}`);
+}
+
+// CLI
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  
+  if (args.length < 3) {
+    console.error('Usage: tsx analyze-capabilities.ts <unified.json> <capability-tree.json> <output.json> [--project-path <path>] [--job-id <id>]');
+    process.exit(1);
+  }
+  
+  const [unifiedPath, capabilityTreePath, outputPath] = args;
+  
+  // Parse optional arguments
+  let projectPath: string | null = null;
+  let jobId = 'unknown';
+  
+  for (let i = 3; i < args.length; i++) {
+    if (args[i] === '--project-path' && i + 1 < args.length) {
+      projectPath = args[i + 1];
+      i++;
+    } else if (args[i] === '--job-id' && i + 1 < args.length) {
+      jobId = args[i + 1];
+      i++;
+    }
+  }
+  
+  try {
+    analyzeCapabilities(unifiedPath, capabilityTreePath, outputPath, projectPath, jobId);
+  } catch (error) {
+    console.error('❌ Error:', error);
+    process.exit(1);
+  }
+}
+
+export { analyzeCapabilities };

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

@@ -0,0 +1,155 @@
+---
+name: capability-docs-generate
+description: 从 OpenSpec 和代码自动生成能力文档（capabilities/*.mdx），包含架构设计、API 接口、使用示例等内容
+version: 0.1.0
+---
+
+# Skill: capability-docs-generate
+
+## 功能
+
+从 OpenSpec 提案和代码实现自动生成能力文档，输出到 waoooo-docs 的 capabilities 目录。
+
+## 何时调用
+
+- 开发完成后，需要生成能力文档
+- 更新能力实现后，需要更新文档
+- 用户说："生成能力文档"、"更新能力文档"
+
+## 输入
+
+- `openspecPath` - OpenSpec 目录路径（包含 proposal.md, design.md）
+- `capabilityId` - 能力 ID（如 `pricing`, `auth`）
+- `layer` - 能力层级（`l1-foundation`, `l2-integration`, `l3-workflow`）
+- `frontendPath` - 前端代码路径（可选）
+- `backendPath` - 后端代码路径（可选）
+
+## 输出
+
+- `waoooo-docs/developer-docs/capabilities/<layer>/<capability-id>.mdx`
+
+## 执行步骤
+
+### 1. 读取 OpenSpec
+
+```bash
+# 读取 OpenSpec 文件
+- proposal.md（提取概述、目标、背景）
+- design.md（提取架构设计、技术方案）
+```
+
+### 2. 分析代码实现
+
+```bash
+# 扫描前端代码
+- 查找 API 调用
+- 查找 Hooks 使用
+- 查找组件实现
+
+# 扫描后端代码
+- 查找 API 端点
+- 查找数据模型
+- 查找业务逻辑
+```
+
+### 3. 生成文档
+
+```bash
+# 使用模板生成
+npx tsx .claude/skills/capability-docs-generate/scripts/generate-capability-docs.ts \
+  --openspec-path <path> \
+  --capability-id <id> \
+  --layer <layer> \
+  --frontend-path <path> \
+  --backend-path <path>
+```
+
+### 4. 验证输出
+
+- 检查文档是否生成
+- 检查 Mermaid 图是否正确
+- 检查代码示例是否完整
+
+## 使用示例
+
+### 示例 1：生成 L1 能力文档
+
+```
+用户: "生成 pricing 能力文档"
+
+Agent 行动:
+1. 读取 OpenSpec: openspec/changes/001-pricing-system/
+2. 扫描前端代码: packages/pricing/
+3. 扫描后端代码: waoooo-service/domains/pricing/
+4. 生成文档: capabilities/l1-foundation/pricing.mdx
+5. 显示结果
+```
+
+### 示例 2：更新能力文档
+
+```
+用户: "更新 auth 能力文档"
+
+Agent 行动:
+1. 读取现有文档: capabilities/l1-foundation/auth.mdx
+2. 读取 OpenSpec（如果有更新）
+3. 扫描代码（获取最新实现）
+4. 更新文档
+5. 显示变更
+```
+
+## 文档结构
+
+生成的文档包含以下章节：
+
+1. **概述** - 能力简介、核心功能、能力定位
+2. **核心职责** - 负责什么、不负责什么
+3. **整体架构** - 系统架构图（Mermaid）
+4. **前端实现** - Hooks、组件、使用示例
+5. **后端实现** - API 端点、数据模型、业务逻辑
+6. **配置说明** - 环境变量、配置文件
+7. **使用示例** - 完整的代码示例
+8. **相关文档** - 链接到其他文档
+
+## 模板文件
+
+- `assets/templates/capability.mdx` - 能力文档模板
+
+## 错误处理
+
+### 错误 1：OpenSpec 不存在
+
+```
+❌ 错误: OpenSpec 目录不存在
+📁 路径: openspec/changes/001-pricing-system/
+
+💡 建议:
+1. 检查 OpenSpec 路径是否正确
+2. 确认 OpenSpec 已创建
+3. 使用 mdx-to-openspec Skill 创建 OpenSpec
+```
+
+### 错误 2：代码路径不存在
+
+```
+❌ 错误: 代码目录不存在
+📁 路径: packages/pricing/
+
+💡 建议:
+1. 检查代码路径是否正确
+2. 确认代码已实现
+3. 如果代码未实现，可以只基于 OpenSpec 生成文档
+```
+
+## 注意事项
+
+1. **文档与代码同步** - 生成的文档应该反映实际代码实现
+2. **Mermaid 图正确性** - 确保架构图准确反映系统设计
+3. **代码示例完整性** - 提供可运行的完整示例
+4. **链接有效性** - 确保相关文档链接正确
+
+## 相关 Skills
+
+- `mdx-to-openspec` - 创建 OpenSpec
+- `spec-generate` - 生成开发规范
+- `api-docs-generate` - 生成 API 文档