claudecode-omc 5.2.0 → 5.3.0

package/src/utils/overlap.js

@@ -0,0 +1,300 @@
+/* eslint-disable no-console */
+
+const fs = require('fs');
+const path = require('path');
+const { evaluateSkillQuality } = require('./quality');
+
+// ---------------------------------------------------------------------------
+// Text similarity
+// ---------------------------------------------------------------------------
+
+/**
+ * Tokenise text into meaningful words (lowercase, >2 chars, no stop-words).
+ */
+function tokenise(text) {
+  const stop = new Set([
+    'the', 'and', 'for', 'with', 'this', 'that', 'from', 'are', 'was',
+    'will', 'can', 'has', 'have', 'been', 'not', 'but', 'all', 'its',
+    'use', 'used', 'using', 'when', 'how', 'what', 'who', 'which',
+    'you', 'your', 'they', 'their', 'more', 'also', 'into', 'than',
+    'each', 'other', 'about', 'should', 'would', 'could',
+  ]);
+  return text.toLowerCase()
+    .replace(/[^a-z0-9-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !stop.has(w));
+}
+
+/**
+ * Jaccard similarity between two token arrays.
+ */
+function jaccard(a, b) {
+  const setA = new Set(a);
+  const setB = new Set(b);
+  if (setA.size === 0 || setB.size === 0) return 0;
+  const intersection = new Set([...setA].filter(x => setB.has(x)));
+  const union = new Set([...setA, ...setB]);
+  return intersection.size / union.size;
+}
+
+/**
+ * Weighted cosine similarity using term frequency.
+ */
+function cosineTF(a, b) {
+  const freqA = {};
+  const freqB = {};
+  for (const w of a) freqA[w] = (freqA[w] || 0) + 1;
+  for (const w of b) freqB[w] = (freqB[w] || 0) + 1;
+
+  const allWords = new Set([...Object.keys(freqA), ...Object.keys(freqB)]);
+  let dot = 0, magA = 0, magB = 0;
+  for (const w of allWords) {
+    const va = freqA[w] || 0;
+    const vb = freqB[w] || 0;
+    dot += va * vb;
+    magA += va * va;
+    magB += vb * vb;
+  }
+  if (magA === 0 || magB === 0) return 0;
+  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+
+// ---------------------------------------------------------------------------
+// Domain classification
+// ---------------------------------------------------------------------------
+
+const DOMAIN_KEYWORDS = {
+  debugging:    ['debug', 'trace', 'root-cause', 'investigation', 'diagnose', 'stack-trace', 'breakpoint', 'bisect'],
+  testing:      ['tdd', 'bdd', 'coverage', 'red-green', 'test-driven', 'playwright', 'vitest', 'jest', 'assertion'],
+  planning:     ['plan', 'architect', 'requirement', 'roadmap', 'strategy', 'specification', 'decompose', 'scope'],
+  execution:    ['autopilot', 'parallel', 'worker', 'dispatch', 'pipeline', 'orchestrat', 'ultrawork', 'ralph'],
+  review:       ['code-review', 'critique', 'slop', 'cleanup', 'refactor', 'lint', 'approve'],
+  verification: ['verify', 'validate', 'evidence', 'completion', 'passing', 'ultraqa'],
+  research:     ['research', 'multi-model', 'codex', 'gemini', 'deepsearch', 'documentation'],
+  git:          ['worktree', 'rebase', 'cherry-pick', 'pull-request', 'release-branch'],
+  skilldev:     ['skill-creator', 'skill-tester', 'skill-quality', 'skill-debug', 'writing-skills', 'trigger-rate', 'skill-md', 'frontmatter'],
+  brainstorm:   ['brainstorm', 'interview', 'ideate', 'crystalliz', 'deep-interview', 'ambiguity'],
+  setup:        ['install', 'setup', 'configure', 'mcp-setup', 'omc-setup', 'doctor', 'notification'],
+};
+
+/**
+ * Classify a skill into domains based on its description + body keywords.
+ * Returns array of { domain, strength } sorted by strength descending.
+ */
+function classifyDomains(tokens) {
+  const scores = {};
+  const tokenSet = new Set(tokens);
+  for (const [domain, keywords] of Object.entries(DOMAIN_KEYWORDS)) {
+    let hits = 0;
+    for (const kw of keywords) {
+      // Exact match or compound keyword match (e.g. "skill-creator" in tokens)
+      if (tokenSet.has(kw)) {
+        hits += 2;
+      } else {
+        // Partial: check if any token starts with the keyword
+        for (const tok of tokens) {
+          if (tok.startsWith(kw) && kw.length >= 4) { hits++; break; }
+        }
+      }
+    }
+    if (hits > 0) scores[domain] = hits;
+  }
+  return Object.entries(scores)
+    .map(([domain, strength]) => ({ domain, strength }))
+    .sort((a, b) => b.strength - a.strength);
+}
+
+// ---------------------------------------------------------------------------
+// Overlap detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Load skill content tokens for overlap analysis.
+ */
+function loadSkillTokens(skillPath) {
+  const file = path.join(skillPath, 'SKILL.md');
+  if (!fs.existsSync(file)) return [];
+  const content = fs.readFileSync(file, 'utf8');
+  return tokenise(content);
+}
+
+/**
+ * Detect functional overlaps across multiple skill sources.
+ *
+ * @param {Array} sources — [{ name, items: [{ name, path, metadata }] }]
+ * @param {object} options — { threshold: 0.3 }
+ * @returns {Array} overlap groups
+ */
+function detectOverlaps(sources, options = {}) {
+  const threshold = options.threshold || 0.3;
+
+  // Flatten all skills with source info and pre-compute tokens/domains
+  const allSkills = [];
+  for (const source of sources) {
+    for (const item of (source.items || source.skills || [])) {
+      const tokens = loadSkillTokens(item.path);
+      const domains = classifyDomains(tokens);
+      allSkills.push({
+        ...item,
+        sourceName: source.name,
+        tokens,
+        domains,
+        descTokens: tokenise(item.metadata?.description || ''),
+      });
+    }
+  }
+
+  // Find pairs with high similarity (cross-source only)
+  const pairs = [];
+  for (let i = 0; i < allSkills.length; i++) {
+    for (let j = i + 1; j < allSkills.length; j++) {
+      const a = allSkills[i];
+      const b = allSkills[j];
+
+      // Skip same-source pairs
+      if (a.sourceName === b.sourceName) continue;
+
+      // Description similarity
+      const descSim = jaccard(a.descTokens, b.descTokens);
+
+      // Body content similarity
+      const bodySim = cosineTF(a.tokens, b.tokens);
+
+      // Domain overlap
+      const aDomains = new Set(a.domains.slice(0, 3).map(d => d.domain));
+      const bDomains = new Set(b.domains.slice(0, 3).map(d => d.domain));
+      const domainIntersect = [...aDomains].filter(d => bDomains.has(d)).length;
+      const domainUnion = new Set([...aDomains, ...bDomains]).size;
+      const domainSim = domainUnion > 0 ? domainIntersect / domainUnion : 0;
+
+      // Combined similarity (weighted — description is the skill's identity)
+      const combined = descSim * 0.4 + bodySim * 0.3 + domainSim * 0.3;
+
+      if (combined >= threshold) {
+        pairs.push({ a, b, descSim, bodySim, domainSim, combined });
+      }
+    }
+  }
+
+  // Cluster pairs into groups using union-find
+  const parent = {};
+  function find(x) {
+    if (!parent[x]) parent[x] = x;
+    if (parent[x] !== x) parent[x] = find(parent[x]);
+    return parent[x];
+  }
+  function union(x, y) {
+    parent[find(x)] = find(y);
+  }
+
+  for (const pair of pairs) {
+    const keyA = `${pair.a.sourceName}:${pair.a.name}`;
+    const keyB = `${pair.b.sourceName}:${pair.b.name}`;
+    union(keyA, keyB);
+  }
+
+  // Build groups
+  const groups = {};
+  const skillMap = {};
+  for (const skill of allSkills) {
+    const key = `${skill.sourceName}:${skill.name}`;
+    skillMap[key] = skill;
+  }
+  for (const pair of pairs) {
+    const keyA = `${pair.a.sourceName}:${pair.a.name}`;
+    const keyB = `${pair.b.sourceName}:${pair.b.name}`;
+    const root = find(keyA);
+    if (!groups[root]) groups[root] = new Set();
+    groups[root].add(keyA);
+    groups[root].add(keyB);
+  }
+
+  // Convert groups to output format with quality scores
+  const result = [];
+  for (const members of Object.values(groups)) {
+    const skills = [...members].map(key => {
+      const skill = skillMap[key];
+      const quality = evaluateSkillQuality(skill);
+      return {
+        name: skill.name,
+        source: skill.sourceName,
+        description: skill.metadata?.description || '',
+        domains: skill.domains.slice(0, 3).map(d => d.domain),
+        quality,
+      };
+    });
+
+    // Sort by quality score descending
+    skills.sort((a, b) => b.quality.score - a.quality.score);
+
+    // Find the best similarity pair for the group label
+    const groupPairs = pairs.filter(p => {
+      const keyA = `${p.a.sourceName}:${p.a.name}`;
+      const keyB = `${p.b.sourceName}:${p.b.name}`;
+      return members.has(keyA) && members.has(keyB);
+    });
+    const maxSim = groupPairs.length > 0
+      ? Math.max(...groupPairs.map(p => p.combined))
+      : 0;
+
+    // Primary domain for the group
+    const domainCounts = {};
+    for (const s of skills) {
+      for (const d of s.domains) {
+        domainCounts[d] = (domainCounts[d] || 0) + 1;
+      }
+    }
+    const primaryDomain = Object.entries(domainCounts)
+      .sort((a, b) => b[1] - a[1])[0]?.[0] || 'unknown';
+
+    result.push({
+      domain: primaryDomain,
+      similarity: Math.round(maxSim * 100),
+      skills,
+      winner: skills[0],
+    });
+  }
+
+  // Sort groups by similarity descending
+  result.sort((a, b) => b.similarity - a.similarity);
+  return result;
+}
+
+/**
+ * Generate merge-config preference recommendations from overlap analysis.
+ *
+ * Only produces recommendations for exact-name conflicts where quality
+ * scores differ meaningfully (>10 points).
+ *
+ * @param {Array} overlapGroups — output of detectOverlaps
+ * @returns {object} preferences map { skillName: sourceName }
+ */
+function generateRecommendations(overlapGroups) {
+  const preferences = {};
+
+  for (const group of overlapGroups) {
+    if (group.skills.length < 2) continue;
+
+    // Check for exact name matches within the group
+    const byName = {};
+    for (const s of group.skills) {
+      if (!byName[s.name]) byName[s.name] = [];
+      byName[s.name].push(s);
+    }
+
+    for (const [name, variants] of Object.entries(byName)) {
+      if (variants.length < 2) continue;
+      // Sort by quality
+      variants.sort((a, b) => b.quality.score - a.quality.score);
+      const best = variants[0];
+      const second = variants[1];
+      if (best.quality.score - second.quality.score >= 10) {
+        preferences[name] = best.source;
+      }
+    }
+  }
+
+  return preferences;
+}
+
+module.exports = { detectOverlaps, generateRecommendations, tokenise, jaccard, cosineTF, classifyDomains };

package/src/utils/quality.js

@@ -1,53 +1,307 @@
+/* eslint-disable no-console */
+
 const fs = require('fs');
 const path = require('path');
 
 /**
- * Evaluate Claude Code skill quality
- * Returns { score: number, signals: string[] }
+ * Multi-dimensional skill quality evaluator.
+ *
+ * Scoring aligned with Anthropic's official skill authoring best practices
+ * (sourced from .upstream/anthropic-skills/).  When that upstream updates,
+ * quick_validate.py constraints are re-read automatically.
+ *
+ * Dimensions (each 0-25, total 0-100):
+ *   1. Metadata   — frontmatter completeness, description quality
+ *   2. Content    — body depth, progressive disclosure, examples
+ *   3. Structure  — organization, reference hygiene, anti-patterns
+ *   4. Actionability — workflow clarity, scripts, concrete guidance
  */
-function evaluateSkillQuality(skill) {
-  const skillDoc = path.join(skill.path, 'SKILL.md');
-  if (!fs.existsSync(skillDoc)) {
-    return { score: 0, signals: ['missing_skill_doc'] };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readSkillMd(skillPath) {
+  const file = path.join(skillPath, 'SKILL.md');
+  if (!fs.existsSync(file)) return null;
+  return fs.readFileSync(file, 'utf8');
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const meta = {};
+  match[1].split('\n').forEach((line) => {
+    const idx = line.indexOf(':');
+    if (idx === -1) return;
+    meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  });
+  return meta;
+}
+
+function getBody(content) {
+  return content.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+}
+
+function countLines(text) {
+  return text ? text.split('\n').length : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 1: Metadata (0-25)
+// ---------------------------------------------------------------------------
+
+function scoreMetadata(content, meta) {
+  const signals = [];
+  let score = 25;
+
+  if (!meta) {
+    return { score: 0, signals: ['missing_frontmatter'] };
+  }
+
+  // name
+  const name = meta.name || '';
+  if (!name) {
+    score -= 5; signals.push('missing_name');
+  } else {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+      score -= 3; signals.push('name_not_kebab_case');
+    }
+    if (name.length > 64) {
+      score -= 2; signals.push('name_too_long');
+    }
+  }
+
+  // description
+  const desc = meta.description || '';
+  if (!desc) {
+    score -= 10; signals.push('missing_description');
+  } else {
+    if (desc.length > 1024) {
+      score -= 3; signals.push('description_too_long');
+    }
+    if (desc.length < 20) {
+      score -= 3; signals.push('description_too_short');
+    }
+    // Should contain trigger context ("Use when", "when", etc.)
+    if (!/\b(use when|when|trigger|invoke|activate)\b/i.test(desc)) {
+      score -= 2; signals.push('description_missing_trigger_context');
+    }
+    // Should not summarize workflow (Anthropic anti-pattern)
+    if (/\b(step 1|first,? then|workflow:|process:)\b/i.test(desc)) {
+      score -= 2; signals.push('description_summarizes_workflow');
+    }
+    // Vague words
+    if (/\b(helps?|various|many|stuff|things|general)\b/i.test(desc)) {
+      score -= 1; signals.push('description_vague_words');
+    }
   }
 
-  const content = fs.readFileSync(skillDoc, 'utf8');
+  return { score: Math.max(0, score), signals };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 2: Content (0-25)
+// ---------------------------------------------------------------------------
+
+function scoreContent(body) {
   const signals = [];
-  let score = 100;
+  let score = 25;
+
+  const lines = countLines(body);
+
+  if (lines < 5) {
+    score -= 10; signals.push('body_too_short');
+  } else if (lines > 500) {
+    score -= 5; signals.push('body_exceeds_500_lines');
+  }
+
+  // Has examples (code blocks)
+  const codeBlocks = (body.match(/```/g) || []).length / 2;
+  if (codeBlocks < 1) {
+    score -= 3; signals.push('no_code_examples');
+  }
 
-  // Must have frontmatter
-  if (!/^---\n[\s\S]*?\n---\n?/m.test(content)) {
-    score -= 30;
-    signals.push('missing_frontmatter');
+  // Has concrete examples (not abstract)
+  if (!/example|e\.g\.|for instance|sample/i.test(body)) {
+    score -= 2; signals.push('no_concrete_examples');
   }
 
-  // Must have name field
-  if (!/name:\s*[^\n]+/.test(content)) {
-    score -= 15;
-    signals.push('missing_name');
+  // Progressive disclosure — references to other files
+  const refs = body.match(/\[.*?\]\(.*?\.md\)/g) || [];
+  if (lines > 300 && refs.length === 0) {
+    score -= 3; signals.push('long_body_no_progressive_disclosure');
   }
 
-  // Must have description field
-  if (!/description:\s*[^\n]+/.test(content)) {
-    score -= 15;
-    signals.push('missing_description');
+  // Check for nested references (anti-pattern: A -> B -> C)
+  // We just check if referenced files themselves reference other files
+  // This is a heuristic — actual check would need file reads
+  if (refs.length > 10) {
+    score -= 1; signals.push('excessive_references');
   }
 
-  // Should have usage/workflow/instructions section
-  if (!/usage|when to use|instructions|workflow|steps/i.test(content)) {
-    score -= 10;
-    signals.push('missing_structure');
+  return { score: Math.max(0, score), signals };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 3: Structure (0-25)
+// ---------------------------------------------------------------------------
+
+function scoreStructure(content, body, skillPath) {
+  const signals = [];
+  let score = 25;
+
+  // Valid frontmatter already checked in metadata, but check YAML parse
+  if (!content.startsWith('---')) {
+    score -= 5; signals.push('no_frontmatter_delimiter');
   }
 
-  // Should have reasonable length (not just frontmatter)
-  const bodyContent = content.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
-  if (bodyContent.length < 50) {
-    score -= 10;
-    signals.push('too_short');
+  // Sections — should have headers for organization
+  const headers = (body.match(/^#{1,3}\s+.+/gm) || []);
+  if (headers.length === 0 && countLines(body) > 30) {
+    score -= 5; signals.push('no_section_headers');
   }
 
-  score = Math.max(0, Math.min(100, score));
-  return { score, signals };
+  // Check reference depth — files referenced from SKILL.md
+  const refFiles = (body.match(/\[.*?\]\(((?!http)[^)]+)\)/g) || []);
+  for (const ref of refFiles) {
+    const match = ref.match(/\(([^)]+)\)/);
+    if (!match) continue;
+    const refPath = path.join(skillPath, match[1]);
+    if (fs.existsSync(refPath)) {
+      const refContent = fs.readFileSync(refPath, 'utf8');
+      // Check if reference itself has deep references
+      const nestedRefs = (refContent.match(/\[.*?\]\(((?!http)[^)]+\.md)\)/g) || []);
+      if (nestedRefs.length > 0) {
+        score -= 2; signals.push('nested_references');
+        break;
+      }
+      // Long reference without table of contents
+      if (countLines(refContent) > 100 && !/^#{1,2}\s+.*contents|^#{1,2}\s+.*toc/im.test(refContent)) {
+        score -= 1; signals.push('long_reference_no_toc');
+      }
+    }
+  }
+
+  // Anti-patterns
+  if (/before \d{4}|after \d{4}|until \d{4}/i.test(body)) {
+    score -= 3; signals.push('time_sensitive_content');
+  }
+  if (/\\/g.test(body) && /\.exe|\.bat|\.cmd/i.test(body)) {
+    score -= 2; signals.push('windows_paths');
+  }
+
+  // Consistent terminology — check for mixed naming of same concept
+  // Heuristic: if "skill" and "command" both used to describe the same thing
+  const skillMentions = (body.match(/\bskill\b/gi) || []).length;
+  const commandMentions = (body.match(/\bcommand\b/gi) || []).length;
+  if (skillMentions > 3 && commandMentions > 3) {
+    score -= 1; signals.push('mixed_terminology');
+  }
+
+  return { score: Math.max(0, score), signals };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 4: Actionability (0-25)
+// ---------------------------------------------------------------------------
+
+function scoreActionability(body, skillPath) {
+  const signals = [];
+  let score = 25;
+
+  // Has workflow/steps/checklist
+  const hasSteps = /step \d|^\d+\.\s|^-\s\[[ x]\]/im.test(body);
+  const hasWorkflow = /workflow|process|procedure|checklist/i.test(body);
+  if (!hasSteps && !hasWorkflow) {
+    score -= 5; signals.push('no_workflow_or_steps');
+  }
+
+  // Has checklist items (Claude can track)
+  if (/^-\s\[[ x]\]/m.test(body)) {
+    score += 0; // bonus: good practice, but don't exceed max
+  } else if (countLines(body) > 50) {
+    score -= 1; signals.push('long_skill_no_checklist');
+  }
+
+  // Has scripts/ directory
+  const scriptsDir = path.join(skillPath, 'scripts');
+  if (fs.existsSync(scriptsDir)) {
+    const scripts = fs.readdirSync(scriptsDir).filter(f => !f.startsWith('.'));
+    if (scripts.length > 0) {
+      // Good: has executable tools
+    }
+  }
+
+  // "Do X" or "Run X" — clear execution intent
+  if (!/\b(run|execute|invoke|call)\b/i.test(body) && countLines(body) > 20) {
+    score -= 2; signals.push('no_clear_execution_intent');
+  }
+
+  // Error handling guidance
+  if (!/\b(error|fail|fallback|if .* fails|when .* fails)\b/i.test(body) && countLines(body) > 50) {
+    score -= 2; signals.push('no_error_handling_guidance');
+  }
+
+  // Anti-pattern: purely descriptive, no actionable instructions
+  const imperatives = (body.match(/\b(must|should|always|never|do not|ensure|verify|check|create|use|add|remove|run)\b/gi) || []);
+  if (imperatives.length < 3 && countLines(body) > 20) {
+    score -= 3; signals.push('purely_descriptive');
+  }
+
+  return { score: Math.max(0, score), signals };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate a single skill's quality.
+ *
+ * @param {object} skill  — { name, path, metadata }
+ * @returns {{ score: number, dimensions: object, signals: string[] }}
+ */
+function evaluateSkillQuality(skill) {
+  const content = readSkillMd(skill.path);
+  if (!content) {
+    return {
+      score: 0,
+      dimensions: { metadata: 0, content: 0, structure: 0, actionability: 0 },
+      signals: ['missing_skill_md'],
+    };
+  }
+
+  const meta = parseFrontmatter(content) || skill.metadata || {};
+  const body = getBody(content);
+
+  const d1 = scoreMetadata(content, meta);
+  const d2 = scoreContent(body);
+  const d3 = scoreStructure(content, body, skill.path);
+  const d4 = scoreActionability(body, skill.path);
+
+  const total = d1.score + d2.score + d3.score + d4.score;
+  const allSignals = [...d1.signals, ...d2.signals, ...d3.signals, ...d4.signals];
+
+  return {
+    score: total,
+    dimensions: {
+      metadata: d1.score,
+      content: d2.score,
+      structure: d3.score,
+      actionability: d4.score,
+    },
+    signals: allSignals,
+  };
+}
+
+/**
+ * Get the path to Anthropic's upstream quick_validate.py (if available).
+ */
+function getUpstreamValidatorPath(root) {
+  const p = path.join(root, '.upstream', 'anthropic-skills', 'skills',
+    'skill-creator', 'scripts', 'quick_validate.py');
+  return fs.existsSync(p) ? p : null;
 }
 
-module.exports = { evaluateSkillQuality };
+module.exports = { evaluateSkillQuality, getUpstreamValidatorPath };