ai-developer-skill-os 7.5.0 → 8.1.4

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();

package/.agents/_template/BEHAVIOR_SPEC.md

@@ -1,96 +0,0 @@
----
-name: qk-[tên-behavior]
-version: 6.0.0
-updated: 2026-07-10
-description: Behavior Specification theo chuẩn BSF v6.0.
----
-
-# 📜 Behavior Specification: [Tên Behavior]
-
-## 1. Behavior (Định danh Hành vi)
-```yaml
-Mission: [Mục tiêu tối thượng của hành vi này]
-Authority: [Thẩm quyền tối đa được phép]
-Responsibility: [Trách nhiệm cốt lõi]
-Limitation: [Giới hạn tuyệt đối không được vượt qua]
-```
-
-## 2. Contracts (Hợp đồng)
-
-### 2.1. Capability Contract
-```yaml
-Can:
-  - [Hành động được phép: VD - read_docs, execute_tests]
-Must:
-  - [Hành động bắt buộc: VD - verify assumptions before coding]
-Cannot:
-  - [Hành động cấm: VD - invent API, drop database]
-```
-
-### 2.2. Output Contract
-```yaml
-Artifacts:
-  - [Artifact 1: VD - plan.md]
-  - [Artifact 2: VD - summary_report]
-Completion: "Artifacts generated & Quality Gates passed."
-```
-
-## 3. Policies (Chính sách)
-
-### 3.1. Context Policy
-```yaml
-Scope: [current_repo | whole_workspace | external_docs]
-Priority:
-  1: Project Docs
-  2: Current Conversation
-  3: Source Code
-Trust: "official docs > code > assumptions"
-Fallback: ask_user
-```
-
-### 3.2. Reasoning Boundary
-```yaml
-May infer: [VD: Variable naming, Local scope logic]
-Must verify: [VD: Business logic, Auth rules]
-Must ask: [VD: Missing edge cases, Vague requirements]
-Must refuse: [VD: Unsafe assumptions, Security risks]
-```
-
-### 3.3. Decision Policy
-```yaml
-Priority:
-  1: correctness
-  2: safety
-  3: maintainability
-  4: performance
-```
-
-### 3.4. Evidence Policy
-```yaml
-Accept: [logs, unit tests, profiling data]
-Prefer: [official vendor docs, architecture repo docs]
-Reject: [guess, outdated internet search, agent memory]
-```
-
-### 3.5. Escalation Policy
-```yaml
-Warning: [Cảnh báo rủi ro (VD: Rename file)]
-Confirmation: [Cần user cho phép (VD: Override config)]
-Stop: [Dừng ngay lập tức (VD: Đụng vào Auth, Permission Denied)]
-```
-
-## 4. Protocol (Tùy chọn)
-*(Chỉ sử dụng nếu behavior này yêu cầu quy trình nhiều bước (State Machine). Xóa phần này nếu không cần thiết).*
-
-```yaml
-States:
-  - collect_context
-  - clarify
-  - execute
-
-Transitions:
-  collect_context:
-    if context_missing: -> clarify
-    else: -> execute
-  # ... (Các rule chuyển trạng thái khác) ...
-```

package/.agents/_template/examples/example-en.md

@@ -1,49 +0,0 @@
----
-# AI Developer Skill OS
-# Example usage file (English)
-# Copy this as a starting point for your skill examples
----
-
-# Example: [Skill Name]
-
-## Input
-
-**User request:**
-```
-[Describe what the user said or asked]
-```
-
-**Project context:**
-- Framework: [React 18 / Next.js 14 / Vue 3 / etc.]
-- Relevant files: `[path/to/file.ts]`
-- Current state: [Brief description]
-
----
-
-## Execution
-
-**Skill activated:** `[skill-name]`
-
-**Phase 1 — Analysis:**
-> [What the AI analyzed]
-
-**Phase 2 — Plan:**
-> [What the AI decided to do]
-
-**Phase 3 — Output:**
-
-```typescript
-// [filename.ts]
-// [Generated or modified code]
-```
-
----
-
-## Result
-
-```
-✅ Summary:    [What was done]
-📁 Files:      [List of files]
-⚠️  Warnings:  [Any notes]
-🔗 Next steps: [Follow-up suggestion]
-```

package/.agents/_template/examples/example-vi.md

@@ -1,49 +0,0 @@
----
-# AI Developer Skill OS
-# File ví dụ sử dụng (Tiếng Việt)
-# Sao chép file này làm điểm khởi đầu cho ví dụ của bạn
----
-
-# Ví dụ: [Tên Skill]
-
-## Input (Đầu vào)
-
-**Yêu cầu của người dùng:**
-```
-[Mô tả người dùng đã nói hoặc yêu cầu gì]
-```
-
-**Bối cảnh dự án:**
-- Framework: [React 18 / Next.js 14 / Vue 3 / v.v.]
-- File liên quan: `[path/to/file.ts]`
-- Trạng thái hiện tại: [Mô tả ngắn]
-
----
-
-## Thực thi
-
-**Skill được kích hoạt:** `[skill-name]`
-
-**Phase 1 — Phân tích:**
-> [AI đã phân tích gì]
-
-**Phase 2 — Kế hoạch:**
-> [AI quyết định làm gì]
-
-**Phase 3 — Kết quả:**
-
-```typescript
-// [filename.ts]
-// [Code được tạo hoặc chỉnh sửa]
-```
-
----
-
-## Kết quả
-
-```
-✅ Tóm tắt:       [Đã làm gì]
-📁 Files:         [Danh sách file]
-⚠️  Lưu ý:        [Ghi chú quan trọng]
-🔗 Bước tiếp theo: [Gợi ý skill hoặc hành động tiếp theo]
-```