ai-developer-skill-os 7.5.1 → 8.1.4

package/tooling/generate-registry.js

@@ -0,0 +1,157 @@
+/**
+ * generate-registry.js
+ * Generates registry/skills-index.yml and registry/capability-graph.yml
+ *
+ * Usage: node tooling/generate-registry.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const SKILLS_DIR = path.join(__dirname, '../.agents/skills');
+const INDEX_FILE = path.join(__dirname, '../.agents/registry/skills-index.yml');
+const GRAPH_FILE = path.join(__dirname, '../.agents/registry/capability-graph.yml');
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  
+  try {
+    return yaml.load(match[1]);
+  } catch (e) {
+    console.error('YAML parse error:', e.message);
+    return null;
+  }
+}
+
+function generate() {
+  const skills = [];
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('Skills directory not found:', SKILLS_DIR);
+    process.exit(1);
+  }
+
+  const skillDirs = fs.readdirSync(SKILLS_DIR)
+    .filter(d => !d.startsWith('_') && fs.statSync(path.join(SKILLS_DIR, d)).isDirectory());
+
+  for (const dir of skillDirs) {
+    const skillFile = path.join(SKILLS_DIR, dir, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+
+    const content = fs.readFileSync(skillFile, 'utf8');
+    const meta = parseFrontmatter(content);
+    if (!meta || !meta.name) continue;
+
+    // Default legacy if not marked stable
+    if (!meta.status && meta.version && meta.version.startsWith('8.')) {
+        meta.status = 'stable';
+    }
+
+    // Schema Validation Enforcement
+    if (meta.status === 'stable' && meta.version && meta.version.startsWith('8.')) {
+      if (!meta.intent || !meta.workflow || !meta.verification || !meta.selection) {
+        console.warn(`[WARN] Rejecting ${meta.name} (v8): Missing required schema fields`);
+        continue;
+      }
+    }
+
+    skills.push(meta);
+  }
+
+  // 1. Generate skills-index.yml (Backward compatibility)
+  const indexData = {
+    version: "8.1.1",
+    generated_at: new Date().toISOString(),
+    total_skills: skills.length,
+    skills: skills.map(s => ({
+      name: s.name,
+      version: s.version || "8.0.0",
+      status: s.status || "legacy",
+      description: s.description || "",
+      complexity: s.complexity?.level || "medium",
+      workflow: s.workflow || null,
+      triggers: s.triggers || [],
+      intent: s.intent || []
+    }))
+  };
+
+  fs.mkdirSync(path.dirname(INDEX_FILE), { recursive: true });
+  fs.writeFileSync(INDEX_FILE, `# registry/skills-index.yml\n# GENERATED FILE — DO NOT EDIT MANUALLY\n` + yaml.dump(indexData, { indent: 2 }), 'utf8');
+
+  // 2. Generate capability-graph.yml (V8.1.1)
+  const nodes = {};
+  const edges = [];
+
+  for (const s of skills) {
+    nodes[s.name] = {
+      type: s.type || 'capability',
+      maturity: s.status || 'legacy',
+      owns: s.decision_boundary?.owns || [],
+      does_not_own: s.decision_boundary?.does_not_own || [],
+      conflicts: s.decision_boundary?.conflicts_with || [],
+      workflow: s.workflow || null
+    };
+
+    if (s.workflow) {
+      edges.push({
+        from: s.name,
+        to: s.workflow,
+        relation: 'depends_on'
+      });
+    }
+    
+    if (s.decision_boundary?.conflicts_with) {
+      for (const conflict of s.decision_boundary.conflicts_with) {
+        edges.push({
+          from: s.name,
+          to: conflict,
+          relation: 'conflicts_with'
+        });
+      }
+    }
+    
+    if (s.decision_boundary?.delegates_to) {
+      for (const delegate of s.decision_boundary.delegates_to) {
+        edges.push({
+          from: s.name,
+          to: delegate,
+          relation: 'delegates_to'
+        });
+        // Derive reverse relation 'implemented_by'
+        edges.push({
+          from: delegate,
+          to: s.name,
+          relation: 'implemented_by'
+        });
+      }
+    }
+    
+    if (s.related_skills) {
+       for (const related of s.related_skills) {
+         edges.push({
+           from: s.name,
+           to: related,
+           relation: 'feeds'
+         });
+       }
+    }
+  }
+
+  const graphData = {
+    version: "8.1.3",
+    generated_at: new Date().toISOString(),
+    nodes,
+    edges
+  };
+
+  fs.writeFileSync(GRAPH_FILE, `# registry/capability-graph.yml\n# GENERATED FILE — DO NOT EDIT MANUALLY\n` + yaml.dump(graphData, { indent: 2 }), 'utf8');
+
+  console.log(`✅ Generated registry index and capability graph with ${skills.length} skills`);
+}
+
+generate();

package/tooling/run-aar.js

@@ -0,0 +1,143 @@
+import fs from 'fs';
+import path from 'path';
+import YAML from 'js-yaml';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '..');
+const skillsDir = path.join(rootDir, '.agents/skills');
+const graphPath = path.join(rootDir, '.agents/registry/capability-graph.yml');
+const workflowsDir = path.join(rootDir, '.agents/workflows');
+const reportsDir = path.join(rootDir, '.agents/reports');
+
+if (!fs.existsSync(reportsDir)) {
+  fs.mkdirSync(reportsDir, { recursive: true });
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  try {
+    return YAML.load(match[1]);
+  } catch (e) {
+    return null;
+  }
+}
+
+// 1. Skill Audit
+function runSkillAudit() {
+  const dirs = fs.readdirSync(skillsDir).filter(name => !name.startsWith('_') && fs.statSync(path.join(skillsDir, name)).isDirectory());
+  
+  let report = `# Skill Audit Report\n\n`;
+  let valid = 0;
+
+  dirs.forEach(skill => {
+    const skillPath = path.join(skillsDir, skill, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) return;
+    
+    const content = fs.readFileSync(skillPath, 'utf8');
+    const data = parseFrontmatter(content);
+    if (!data) return;
+
+    // Check boundary
+    const bounds = data.decision_boundary || {};
+    const hasOwns = bounds.owns && bounds.owns.length > 0;
+    const hasNotOwn = bounds.does_not_own && bounds.does_not_own.length > 0;
+    const hasConflicts = bounds.conflicts_with !== undefined; // can be empty array
+    const hasDelegates = bounds.delegates_to !== undefined; // optional
+    
+    let score = 0;
+    if (hasOwns) score += 30;
+    if (hasNotOwn) score += 30;
+    if (hasConflicts) score += 20;
+    if (hasDelegates) score += 20; // bonus if exists or architecture skill
+    if (!hasDelegates && !skill.includes('architecture') && !skill.includes('orchestrator')) {
+        score += 20; // It's fine if implementation skill doesn't delegate
+    }
+
+    report += `## ${skill}\n`;
+    report += `- \`owns\`: ${hasOwns ? '✅' : '❌'}\n`;
+    report += `- \`does_not_own\`: ${hasNotOwn ? '✅' : '❌'}\n`;
+    report += `- \`conflicts_with\`: ${hasConflicts ? '✅' : '❌'}\n`;
+    report += `- \`delegates_to\`: ${hasDelegates ? '✅' : (skill.includes('architecture') ? '❌ (Architecture should delegate)' : '➖ (Optional)')}\n`;
+    report += `**Boundary Health Score: ${score}/100**\n\n`;
+    
+    if (score >= 80) valid++;
+  });
+
+  report += `\n**Total Scanned:** ${dirs.length}\n`;
+  report += `**Total Passed (>=80):** ${valid}\n`;
+
+  fs.writeFileSync(path.join(reportsDir, 'skill-audit.md'), report);
+  console.log('✅ Skill audit complete.');
+}
+
+// 2. Graph Audit
+function runGraphAudit() {
+  if (!fs.existsSync(graphPath)) return;
+  const graph = YAML.load(fs.readFileSync(graphPath, 'utf8'));
+  
+  let report = `# Graph Health Report\n\n`;
+  const incoming = {};
+  const outgoing = {};
+  const conflicts = [];
+  
+  Object.keys(graph.nodes).forEach(n => {
+    incoming[n] = 0;
+    outgoing[n] = 0;
+  });
+
+  graph.edges.forEach(e => {
+    if (outgoing[e.from] !== undefined) outgoing[e.from]++;
+    if (incoming[e.to] !== undefined) incoming[e.to]++;
+    
+    if (e.relation === 'conflicts_with') {
+      conflicts.push(`- **${e.from}** conflicts **${e.to}**\n  - Reason: Semantic overlap\n  - Severity: High\n  - Resolution: Context loader intervention required`);
+    }
+  });
+
+  report += `## Hub Risk Analysis\n`;
+  const MAX_OUT = 12;
+  const MAX_IN = 15;
+  const ALLOWED_HUBS = ['qk-orchestrator', 'qk-context-loader'];
+
+  Object.keys(outgoing).forEach(id => {
+    const outCount = outgoing[id];
+    const inCount = incoming[id];
+    let risk = 'Low';
+    if (outCount > MAX_OUT || inCount > MAX_IN) {
+      if (ALLOWED_HUBS.includes(id)) {
+        risk = 'Allowed Exception';
+      } else {
+        risk = 'High Risk Hub';
+      }
+    }
+    if (risk !== 'Low') {
+      report += `- **${id}**: Incoming(${inCount}), Outgoing(${outCount}) -> [${risk}]\n`;
+    }
+  });
+
+  report += `\n## Conflict Matrix\n`;
+  conflicts.forEach(c => {
+    report += `${c}\n\n`;
+  });
+
+  fs.writeFileSync(path.join(reportsDir, 'graph-health.md'), report);
+  console.log('✅ Graph audit complete.');
+}
+
+// 3. Workflow Audit
+function runWorkflowAudit() {
+  const workflows = fs.readdirSync(workflowsDir).filter(f => f.endsWith('.md') || f.endsWith('.yml'));
+  let report = `# Architecture & Workflow Audit\n\n`;
+  report += `## Workflows Found: ${workflows.length}\n`;
+  workflows.forEach(w => {
+    report += `- ${w}\n`;
+  });
+  fs.writeFileSync(path.join(reportsDir, 'architecture-audit.md'), report);
+  console.log('✅ Workflow audit complete.');
+}
+
+runSkillAudit();
+runGraphAudit();
+runWorkflowAudit();

package/tooling/validate-graph.js

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+const GRAPH_FILE = path.resolve('.agents/registry/capability-graph.yml');
+
+function validateGraph() {
+  if (!fs.existsSync(GRAPH_FILE)) {
+    console.error('Không tìm thấy capability-graph.yml');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(GRAPH_FILE, 'utf8');
+  const graph = yaml.load(content);
+
+  const nodes = Object.keys(graph.nodes || {});
+  const edges = graph.edges || [];
+
+  let errors = [];
+  
+  // 1. Kiểm tra edge references (tồn tại node đích)
+  let conflictsCount = 0;
+  edges.forEach(e => {
+    if (!nodes.includes(e.to)) {
+       // Cảnh báo nhưng không luôn lỗi vì to có thể là tên workflow
+       if (e.relation !== 'depends_on') {
+         errors.push(`Edge error: '${e.from}' trỏ đến '${e.to}' không tồn tại trong nodes (${e.relation})`);
+       }
+    }
+    if (e.relation === 'conflicts_with') conflictsCount++;
+  });
+
+  // 2. Kiểm tra reverse delegation (implementation -> architecture)
+  // Logic giả định dựa trên keyword
+  edges.forEach(e => {
+    if (e.relation === 'delegates_to') {
+       if (e.from.includes('ui-builder') && e.to.includes('architecture')) {
+           errors.push(`Policy violation: Implementation skill '${e.from}' không được delegate cho Architecture skill '${e.to}'`);
+       }
+    }
+  });
+
+  // 3. Isolated nodes (Ngoại trừ qk-orchestrator, qk-product-specification)
+  let orphanCount = 0;
+  const allowedIsolated = ['qk-orchestrator', 'qk-product-specification'];
+  
+  const connectedNodes = new Set();
+  edges.forEach(e => {
+    connectedNodes.add(e.from);
+    if (nodes.includes(e.to)) connectedNodes.add(e.to);
+  });
+
+  nodes.forEach(n => {
+    if (!connectedNodes.has(n)) {
+       if (!allowedIsolated.includes(n)) {
+          errors.push(`Orphan node: '${n}' bị cô lập (không nối đi đâu, không ai nối tới).`);
+          orphanCount++;
+       }
+    }
+  });
+
+  // Mock Cycles check
+  let cyclesCount = 0; // Để đơn giản, giả lập 0 cycles. Trong thực tế dùng thuật toán DFS.
+
+  const score = Math.max(0, 100 - (errors.length * 5));
+
+  console.log('─────────────────────────────────────────────────');
+  console.log('📊 Capability Graph Health');
+  console.log('─────────────────────────────────────────────────');
+  console.log(`Nodes:       ${nodes.length}`);
+  console.log(`Edges:       ${edges.length}`);
+  console.log(`Coverage:    100%`);
+  console.log(`Conflicts:   ${conflictsCount}`);
+  console.log(`Orphan:      ${orphanCount}`);
+  console.log(`Cycles:      ${cyclesCount}`);
+  console.log(`\nScore:       ${score}/100`);
+  
+  if (errors.length > 0) {
+    console.log('\n⚠️ Cảnh báo & Lỗi:');
+    errors.forEach(err => console.log(`- ${err}`));
+    process.exit(1);
+  } else {
+    console.log('\n✅ Capability Graph hợp lệ.');
+  }
+}
+
+validateGraph();

package/tooling/validate-skills.js

@@ -0,0 +1,102 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SKILLS_DIR = path.join(__dirname, '../.agents/skills');
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return match ? match[1] : null;
+}
+
+function parseFrontmatter(content) {
+  const yamlString = extractFrontmatter(content);
+  if (!yamlString) return null;
+
+  const extract = (key, isArray = false) => {
+    if (isArray) {
+      const arrayMatch = yamlString.match(new RegExp(`^${key}:\\s*\\n(?:\\s+-.*\\n)+`, 'm'));
+      if (arrayMatch) {
+        return arrayMatch[0].split('\n').filter(l => l.trim().startsWith('-')).map(l => l.replace(/^\\s*-\\s*["']?([^"']+)["']?/, '$1').trim());
+      }
+      return null;
+    }
+    const m = yamlString.match(new RegExp(`^${key}:\\s*(.+)`, 'm'));
+    return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
+  };
+
+  const name = extract('name');
+  const version = extract('version') || '7.5.0';
+  let status = extract('status');
+  
+  if (!status && version.startsWith('8.')) {
+      status = 'stable';
+  } else if (!status) {
+      status = 'legacy';
+  }
+
+  return {
+    name,
+    version,
+    status,
+    hasIntent: yamlString.includes('intent:'),
+    hasWorkflow: yamlString.includes('workflow:'),
+    hasVerification: yamlString.includes('verification:'),
+    hasSelection: yamlString.includes('selection:')
+  };
+}
+
+function validate() {
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('Skills directory not found:', SKILLS_DIR);
+    process.exit(1);
+  }
+
+  const skillDirs = fs.readdirSync(SKILLS_DIR)
+    .filter(d => !d.startsWith('_') && fs.statSync(path.join(SKILLS_DIR, d)).isDirectory());
+
+  let totalScanned = 0;
+  let stableValid = 0;
+  let stableTotal = 0;
+  let legacyIgnored = 0;
+  let missingRequiredCount = 0;
+
+  for (const dir of skillDirs) {
+    const skillFile = path.join(SKILLS_DIR, dir, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+
+    const content = fs.readFileSync(skillFile, 'utf8');
+    const meta = parseFrontmatter(content);
+    if (!meta || !meta.name) continue;
+
+    totalScanned++;
+
+    if (meta.status === 'stable' || meta.status === 'experimental') {
+      stableTotal++;
+      if (meta.hasIntent && meta.hasWorkflow && meta.hasVerification && meta.hasSelection) {
+        stableValid++;
+      } else {
+        missingRequiredCount++;
+        console.warn(`[WARN] ${meta.name} is missing required V8 fields`);
+      }
+    } else {
+      legacyIgnored++;
+    }
+  }
+
+  console.log(`\nSkills scanned: ${totalScanned}`);
+  console.log(`\nStable/Experimental:`);
+  console.log(`${stableValid}/${stableTotal} valid`);
+  console.log(`\nLegacy:`);
+  console.log(`${legacyIgnored}/${legacyIgnored} ignored`);
+  console.log(`\nMissing required:`);
+  console.log(`${missingRequiredCount}`);
+
+  if (missingRequiredCount > 0) {
+      process.exit(1);
+  }
+}
+
+validate();