@agentskillkit/agent-skills 1.0.1

package/packages/cli/lib/skill-learn.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+/**
+ * Skill Learn - Auto-update SKILL.md from Hot Patterns
+ * 
+ * When patterns reach threshold hits, automatically add them
+ * to the relevant SKILL.md file as learned rules.
+ * 
+ * This makes the Self-Learning Engine truly "self-learning"!
+ * 
+ * Usage: ag-smart sync-skills
+ */
+
+import fs from "fs";
+import path from "path";
+import { loadKnowledge, saveKnowledge } from "./recall.v2.js";
+import { AGENT_DIR, VERSION } from "./config.js";
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const SYNC_THRESHOLD = 10; // Hits required before syncing to SKILL.md
+const SKILLS_DIR = path.join(AGENT_DIR, "skills");
+
+// Category to skill folder mapping
+const CATEGORY_MAP = {
+    "general": "clean-code",
+    "security": "vulnerability-scanner",
+    "code-quality": "clean-code",
+    "performance": "performance-profiling",
+    "testing": "testing-patterns",
+    "react": "react-patterns",
+    "api": "api-patterns",
+    "database": "database-design"
+};
+
+// ============================================================================
+// SKILL UPDATER
+// ============================================================================
+
+/**
+ * Find the SKILL.md file for a category
+ * @param {string} category 
+ * @returns {string|null}
+ */
+function findSkillFile(category) {
+    const skillFolder = CATEGORY_MAP[category] || CATEGORY_MAP["general"];
+    const skillPath = path.join(SKILLS_DIR, skillFolder, "SKILL.md");
+
+    if (fs.existsSync(skillPath)) {
+        return skillPath;
+    }
+
+    // Fallback to clean-code
+    const fallback = path.join(SKILLS_DIR, "clean-code", "SKILL.md");
+    return fs.existsSync(fallback) ? fallback : null;
+}
+
+/**
+ * Parse SKILL.md structure to find best insertion point
+ * @param {string} skillPath 
+ * @returns {{ sections: Array<{name: string, start: number, end: number}>, content: string }}
+ */
+function parseSkillStructure(skillPath) {
+    const content = fs.readFileSync(skillPath, "utf8");
+    const lines = content.split("\n");
+    const sections = [];
+
+    let currentSection = null;
+
+    lines.forEach((line, idx) => {
+        // Detect section headers (## or ###)
+        const headerMatch = line.match(/^(#{2,3})\s+(.+)/);
+        if (headerMatch) {
+            if (currentSection) {
+                currentSection.end = idx - 1;
+                sections.push(currentSection);
+            }
+            currentSection = {
+                name: headerMatch[2].trim(),
+                level: headerMatch[1].length,
+                start: idx,
+                end: lines.length - 1
+            };
+        }
+    });
+
+    if (currentSection) {
+        sections.push(currentSection);
+    }
+
+    return { sections, content, lines };
+}
+
+/**
+ * Find best section to insert pattern based on category
+ * @param {Array} sections 
+ * @param {string} category 
+ * @returns {number} - Line number to insert at
+ */
+function findInsertionPoint(sections, category) {
+    // Look for "Auto-learned" section first
+    const autoSection = sections.find(s =>
+        s.name.toLowerCase().includes("auto-learned") ||
+        s.name.toLowerCase().includes("learned patterns")
+    );
+    if (autoSection) {
+        return autoSection.end + 1;
+    }
+
+    // Look for relevant category section
+    const categoryMap = {
+        "security": ["security", "vulnerab"],
+        "performance": ["performance", "optim"],
+        "code-quality": ["quality", "best practice", "rule"],
+        "testing": ["test", "spec"]
+    };
+
+    const keywords = categoryMap[category] || ["rule", "pattern"];
+    const matchSection = sections.find(s =>
+        keywords.some(kw => s.name.toLowerCase().includes(kw))
+    );
+    if (matchSection) {
+        return matchSection.end + 1;
+    }
+
+    // Default: append at end
+    return -1; // -1 means append
+}
+
+/**
+ * Generate rule entry for SKILL.md
+ * @param {object} lesson 
+ * @returns {string}
+ */
+function generateRuleEntry(lesson) {
+    const date = new Date().toISOString().split("T")[0];
+    return `
+### 🤖 Auto-learned: ${lesson.id}
+
+> **Pattern:** \`${lesson.pattern}\`
+> 
+> ${lesson.message}
+
+- **Severity:** ${lesson.severity}
+- **Detected:** ${lesson.hitCount} times
+- **Added:** ${date}
+
+---
+`;
+}
+
+/**
+ * Check if pattern already exists in SKILL.md
+ */
+function patternExistsInSkill(skillPath, pattern) {
+    const content = fs.readFileSync(skillPath, "utf8");
+    // Check multiple formats
+    return content.includes(`\`${pattern}\``) ||
+        content.includes(`Pattern:** \`${pattern}\``) ||
+        content.includes(`"${pattern}"`) ||
+        content.includes(`'${pattern}'`);
+}
+
+/**
+ * Insert rule at specific line or append
+ * @param {string} skillPath 
+ * @param {object} lesson 
+ * @param {string} category 
+ */
+function insertRule(skillPath, lesson, category) {
+    const { sections, content, lines } = parseSkillStructure(skillPath);
+    const insertPoint = findInsertionPoint(sections, category);
+    const entry = generateRuleEntry(lesson);
+
+    if (insertPoint === -1 || insertPoint >= lines.length) {
+        // Append at end
+        fs.appendFileSync(skillPath, entry, "utf8");
+    } else {
+        // Insert at specific line
+        lines.splice(insertPoint, 0, entry);
+        fs.writeFileSync(skillPath, lines.join("\n"), "utf8");
+    }
+}
+
+/**
+ * Sync hot patterns to SKILL.md files
+ */
+function syncSkills() {
+    console.log(`\n🔄 Skill Sync v${VERSION}`);
+    console.log(`📊 Threshold: ${SYNC_THRESHOLD} hits\n`);
+    console.log("─".repeat(50));
+
+    const db = loadKnowledge();
+
+    if (!db.lessons || db.lessons.length === 0) {
+        console.log("\nℹ️  No lessons learned yet.");
+        return { synced: 0, skipped: 0 };
+    }
+
+    // Find hot patterns
+    const hotPatterns = db.lessons.filter(l => (l.hitCount || 0) >= SYNC_THRESHOLD && !l.syncedToSkill);
+
+    if (hotPatterns.length === 0) {
+        console.log("\nℹ️  No patterns have reached the sync threshold yet.");
+        console.log(`   Patterns need ${SYNC_THRESHOLD}+ hits to be synced to SKILL.md\n`);
+
+        // Show progress
+        const inProgress = db.lessons.filter(l => l.hitCount > 0 && l.hitCount < SYNC_THRESHOLD);
+        if (inProgress.length > 0) {
+            console.log("📈 Patterns in progress:\n");
+            inProgress.forEach(l => {
+                const progress = Math.round((l.hitCount / SYNC_THRESHOLD) * 100);
+                const bar = "█".repeat(Math.floor(progress / 10)) + "░".repeat(10 - Math.floor(progress / 10));
+                console.log(`   [${l.id}] ${l.hitCount}/${SYNC_THRESHOLD} hits (${progress}%)`);
+                console.log(`   ${bar}`);
+            });
+        }
+        return { synced: 0, skipped: 0 };
+    }
+
+    console.log(`\n🔥 Found ${hotPatterns.length} hot pattern(s) ready to sync:\n`);
+
+    let synced = 0;
+    let skipped = 0;
+
+    hotPatterns.forEach(lesson => {
+        const category = lesson.category || "general";
+        const skillPath = findSkillFile(category);
+
+        if (!skillPath) {
+            console.log(`⚠️  [${lesson.id}] No SKILL.md found for category: ${category}`);
+            skipped++;
+            return;
+        }
+
+        // Check if already synced
+        if (patternExistsInSkill(skillPath, lesson.pattern)) {
+            console.log(`⏭️  [${lesson.id}] Already in ${path.basename(path.dirname(skillPath))}/SKILL.md`);
+            lesson.syncedToSkill = true;
+            skipped++;
+            return;
+        }
+
+        // Append to SKILL.md
+        const entry = generateRuleEntry(lesson);
+        fs.appendFileSync(skillPath, entry, "utf8");
+
+        // Mark as synced
+        lesson.syncedToSkill = true;
+        lesson.syncedAt = new Date().toISOString();
+
+        console.log(`✅ [${lesson.id}] → ${path.basename(path.dirname(skillPath))}/SKILL.md`);
+        console.log(`   Pattern: /${lesson.pattern}/`);
+        console.log(`   Hits: ${lesson.hitCount}`);
+        synced++;
+    });
+
+    // Save updated knowledge base
+    saveKnowledge(db);
+
+    console.log(`\n${"─".repeat(50)}`);
+    console.log(`📊 Summary: ${synced} synced, ${skipped} skipped`);
+
+    if (synced > 0) {
+        console.log(`\n🎉 SKILL.md files updated! The agent will now remember these patterns.`);
+    }
+
+    return { synced, skipped };
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+    console.log(`
+🔄 Skill Sync - Auto-update SKILL.md
+
+Usage:
+  ag-smart sync-skills
+
+When patterns reach ${SYNC_THRESHOLD}+ violations, they are automatically
+added to the relevant SKILL.md file as learned rules.
+
+This makes the Self-Learning Engine truly "self-learning"!
+
+Options:
+  --help    Show this help
+`);
+    process.exit(0);
+}
+
+syncSkills();

package/packages/cli/lib/stats.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Smart Stats - Knowledge Base Statistics
+ * 
+ * Display statistics about the knowledge base:
+ * - Total lessons learned
+ * - Most triggered patterns
+ * - Violation trends
+ * 
+ * Usage: ag-smart stats
+ */
+
+import { loadKnowledge } from "./recall.v2.js";
+import { VERSION } from "./config.js";
+
+// ============================================================================
+// STATS DISPLAY
+// ============================================================================
+
+function displayStats() {
+    const db = loadKnowledge();
+
+    console.log(`\n📊 Smart Agent Knowledge Base v${VERSION}\n`);
+    console.log("─".repeat(50));
+
+    if (!db.lessons || db.lessons.length === 0) {
+        console.log("\nℹ️  No lessons learned yet.");
+        console.log("   Use 'ag-smart learn' to add patterns.\n");
+        return;
+    }
+
+    // Summary
+    console.log(`\n📚 Total Lessons: ${db.lessons.length}`);
+
+    const totalHits = db.lessons.reduce((sum, l) => sum + (l.hitCount || 0), 0);
+    console.log(`🎯 Total Violations Detected: ${totalHits}`);
+
+    const errorCount = db.lessons.filter(l => l.severity === "ERROR").length;
+    const warningCount = db.lessons.filter(l => l.severity === "WARNING").length;
+    console.log(`❌ ERROR patterns: ${errorCount}`);
+    console.log(`⚠️  WARNING patterns: ${warningCount}`);
+
+    // Most triggered
+    console.log("\n" + "─".repeat(50));
+    console.log("🔥 Most Triggered Patterns:\n");
+
+    const sorted = [...db.lessons]
+        .filter(l => l.hitCount > 0)
+        .sort((a, b) => (b.hitCount || 0) - (a.hitCount || 0))
+        .slice(0, 5);
+
+    if (sorted.length === 0) {
+        console.log("   No violations detected yet.\n");
+    } else {
+        sorted.forEach((lesson, idx) => {
+            const bar = "█".repeat(Math.min(20, Math.ceil((lesson.hitCount / (sorted[0].hitCount || 1)) * 20)));
+            console.log(`   ${idx + 1}. [${lesson.id}] ${lesson.hitCount} hits`);
+            console.log(`      ${bar}`);
+            console.log(`      ${lesson.message}`);
+            console.log("");
+        });
+    }
+
+    // Auto-escalated
+    const escalated = db.lessons.filter(l => l.autoEscalated);
+    if (escalated.length > 0) {
+        console.log("─".repeat(50));
+        console.log("⚡ Auto-Escalated Patterns:\n");
+        escalated.forEach(l => {
+            console.log(`   [${l.id}] ${l.pattern} → Escalated to ERROR after ${l.hitCount} violations`);
+        });
+        console.log("");
+    }
+
+    // Recent activity
+    const withHits = db.lessons.filter(l => l.lastHit);
+    if (withHits.length > 0) {
+        console.log("─".repeat(50));
+        console.log("🕐 Recent Activity:\n");
+
+        const recent = [...withHits]
+            .sort((a, b) => new Date(b.lastHit) - new Date(a.lastHit))
+            .slice(0, 3);
+
+        recent.forEach(l => {
+            const date = new Date(l.lastHit);
+            const timeAgo = getTimeAgo(date);
+            console.log(`   [${l.id}] Last hit: ${timeAgo}`);
+        });
+        console.log("");
+    }
+
+    // Sources breakdown
+    const sources = {};
+    db.lessons.forEach(l => {
+        const src = l.source || "manual";
+        sources[src] = (sources[src] || 0) + 1;
+    });
+
+    console.log("─".repeat(50));
+    console.log("📥 Lesson Sources:\n");
+    Object.entries(sources).forEach(([src, count]) => {
+        const icon = src === "manual" ? "✍️" : src === "eslint" ? "🔧" : "🧪";
+        console.log(`   ${icon} ${src}: ${count}`);
+    });
+    console.log("");
+}
+
+/**
+ * Get human-readable time ago string
+ */
+function getTimeAgo(date) {
+    const seconds = Math.floor((Date.now() - date) / 1000);
+
+    if (seconds < 60) return "just now";
+    if (seconds < 3600) return `${Math.floor(seconds / 60)} minutes ago`;
+    if (seconds < 86400) return `${Math.floor(seconds / 3600)} hours ago`;
+    return `${Math.floor(seconds / 86400)} days ago`;
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+    console.log(`
+📊 Smart Stats - Knowledge Base Statistics
+
+Usage:
+  ag-smart stats
+
+Shows:
+  - Total lessons and violations
+  - Most triggered patterns
+  - Auto-escalated patterns
+  - Recent activity
+`);
+    process.exit(0);
+}
+
+displayStats();

package/packages/cli/lib/types.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Type Definitions for agent-skill-kit CLI
+ */
+
+/**
+ * @typedef {Object} Lesson
+ * @property {string} id - Lesson ID (e.g., LEARN-001)
+ * @property {string} pattern - Regex pattern to match
+ * @property {string} message - Explanation message
+ * @property {'WARNING'|'ERROR'} severity - Severity level
+ * @property {string} addedAt - ISO timestamp
+ */
+
+/**
+ * @typedef {Object} KnowledgeBase
+ * @property {Lesson[]} lessons - Array of learned lessons
+ */
+
+/**
+ * @typedef {Object} AuditResult
+ * @property {string} file - File path
+ * @property {string[]} violations - List of violations found
+ * @property {boolean} passed - Whether file passed audit
+ */
+
+/**
+ * @typedef {Object} CLIConfig
+ * @property {string} agentDir - Path to .agent directory
+ * @property {string} knowledgePath - Path to lessons file
+ * @property {string} rulesPath - Path to rules directory
+ */
+
+export { };