@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/packages/cli/src/data/repositories/signal-repository.js

@@ -0,0 +1,119 @@
+/**
+ * SignalRepository - Data Access Layer
+ * 
+ * Manages persistence of evolution signals.
+ * Provides CRUD operations with storage abstraction.
+ */
+
+import { EvolutionSignal } from '../../core/evolution/evolution-signal.js';
+
+export class SignalRepository {
+    constructor(storage) {
+        this.storage = storage;
+        this.storageKey = 'evolution-signals';
+    }
+
+    /**
+     * Load all signals from storage
+     * @returns {Promise<Array<EvolutionSignal>>}
+     */
+    async findAll() {
+        try {
+            const data = await this.storage.read(this.storageKey);
+
+            // Restore EvolutionSignal instances with methods
+            return (data?.signals || []).map(s => {
+                const signal = new EvolutionSignal(s.lessonId, s.reason, s.confidence, s.metadata);
+                signal.id = s.id;
+                signal.status = s.status;
+                signal.createdAt = s.createdAt;
+                signal.resolvedAt = s.resolvedAt;
+                return signal;
+            });
+        } catch (error) {
+            console.error('Failed to load signals:', error.message);
+            return [];
+        }
+    }
+
+    /**
+     * Find pending signals
+     * @returns {Promise<Array<EvolutionSignal>>}
+     */
+    async findPending() {
+        const all = await this.findAll();
+        return all.filter(s => s.isPending());
+    }
+
+    /**
+     * Find signals by lesson ID
+     * @param {string} lessonId
+     * @returns {Promise<Array<EvolutionSignal>>}
+     */
+    async findByLesson(lessonId) {
+        const all = await this.findAll();
+        return all.filter(s => s.lessonId === lessonId);
+    }
+
+    /**
+     * Find signal by ID
+     * @param {string} signalId
+     * @returns {Promise<EvolutionSignal|null>}
+     */
+    async findById(signalId) {
+        const all = await this.findAll();
+        return all.find(s => s.id === signalId) || null;
+    }
+
+    /**
+     * Save signal
+     * @param {EvolutionSignal} signal
+     * @returns {Promise<EvolutionSignal>}
+     */
+    async save(signal) {
+        const all = await this.findAll();
+        const updated = [...all.filter(s => s.id !== signal.id), signal];
+
+        await this.storage.write(this.storageKey, {
+            signals: updated,
+            version: 1.0
+        });
+
+        return signal;
+    }
+
+    /**
+     * Save all signals (batch operation)
+     * @param {Array<EvolutionSignal>} signals
+     */
+    async saveAll(signals) {
+        await this.storage.write(this.storageKey, {
+            signals,
+            version: 1.0
+        });
+    }
+
+    /**
+     * Delete signal
+     * @param {string} signalId
+     */
+    async delete(signalId) {
+        const all = await this.findAll();
+        const updated = all.filter(s => s.id !== signalId);
+        await this.saveAll(updated);
+    }
+
+    /**
+     * Clean up old resolved signals (older than 30 days)
+     */
+    async cleanup() {
+        const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000);
+        const all = await this.findAll();
+
+        const kept = all.filter(s =>
+            s.isPending() || s.resolvedAt > thirtyDaysAgo
+        );
+
+        await this.saveAll(kept);
+    }
+}

package/packages/cli/src/data/storage/index.js

@@ -0,0 +1,8 @@
+/**
+ * Storage Adapters - Data Layer
+ * 
+ * Storage implementations for different file formats.
+ */
+
+export { JsonStorage } from './json-storage.js';
+export { YamlStorage } from './yaml-storage.js';

package/packages/cli/src/data/storage/json-storage.js

@@ -0,0 +1,64 @@
+/**
+ * JsonStorage - Storage Adapter
+ * 
+ * JSON file storage implementation.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export class JsonStorage {
+    constructor(basePath) {
+        this.basePath = basePath;
+    }
+
+    /**
+     * Read JSON file
+     * @param {string} key - File identifier
+     * @returns {Promise<object>}
+     */
+    async read(key) {
+        const filePath = path.join(this.basePath, `${key}.json`);
+
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+
+        const content = fs.readFileSync(filePath, 'utf8');
+        return JSON.parse(content);
+    }
+
+    /**
+     * Write JSON file
+     * @param {string} key - File identifier
+     * @param {object} data - Data to write
+     */
+    async write(key, data) {
+        fs.mkdirSync(this.basePath, { recursive: true });
+
+        const filePath = path.join(this.basePath, `${key}.json`);
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+    }
+
+    /**
+     * Delete JSON file
+     * @param {string} key - File identifier
+     */
+    async delete(key) {
+        const filePath = path.join(this.basePath, `${key}.json`);
+
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+
+    /**
+     * Check if file exists
+     * @param {string} key - File identifier
+     * @returns {Promise<boolean>}
+     */
+    async exists(key) {
+        const filePath = path.join(this.basePath, `${key}.json`);
+        return fs.existsSync(filePath);
+    }
+}

package/packages/cli/src/data/storage/yaml-storage.js

@@ -0,0 +1,66 @@
+/**
+ * YamlStorage - Storage Adapter for YAML Files
+ * 
+ * Handles YAML file read/write operations.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+export class YamlStorage {
+    constructor(basePath) {
+        this.basePath = basePath;
+    }
+
+    /**
+     * Read YAML file
+     * @param {string} key - File identifier
+     * @returns {Promise<object>}
+     */
+    async read(key) {
+        const filePath = path.join(this.basePath, `${key}.yaml`);
+
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+
+        const content = fs.readFileSync(filePath, 'utf8');
+        return yaml.load(content);
+    }
+
+    /**
+     * Write YAML file
+     * @param {string} key - File identifier
+     * @param {object} data - Data to write
+     */
+    async write(key, data) {
+        fs.mkdirSync(this.basePath, { recursive: true });
+
+        const filePath = path.join(this.basePath, `${key}.yaml`);
+        const yamlStr = yaml.dump(data, { lineWidth: -1, quotingType: '"' });
+        fs.writeFileSync(filePath, yamlStr, 'utf8');
+    }
+
+    /**
+     * Delete YAML file
+     * @param {string} key - File identifier
+     */
+    async delete(key) {
+        const filePath = path.join(this.basePath, `${key}.yaml`);
+
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+
+    /**
+     * Check if file exists
+     * @param {string} key - File identifier
+     * @returns {Promise<boolean>}
+     */
+    async exists(key) {
+        const filePath = path.join(this.basePath, `${key}.yaml`);
+        return fs.existsSync(filePath);
+    }
+}

package/packages/cli/src/infrastructure/index.js

@@ -0,0 +1,13 @@
+/**
+ * Infrastructure Layer
+ * 
+ * Cross-cutting concerns: config, logging, dependency injection.
+ * 
+ * Exported:
+ * - config: Application configuration
+ * - di: Dependency injection container
+ * - logging: Logger utilities
+ */
+
+export * from './config/index.js';
+export * from './di/index.js';

package/packages/cli/src/presentation/formatters/skill-formatter.js

@@ -0,0 +1,232 @@
+/**
+ * SkillFormatter - Presentation Layer
+ * 
+ * Formats cognitive lessons into Gemini-compatible skill markdown.
+ * Pure formatter - no business logic, no side effects.
+ */
+
+export class SkillFormatter {
+    /**
+     * Format a cognitive lesson as a Gemini skill
+     * @param {object} lesson - Cognitive lesson from LessonSynthesizer
+     * @returns {{name: string, filename: string, content: string}}
+     */
+    format(lesson) {
+        const name = this.sanitizeName(lesson.tag);
+        const frontmatter = this.buildFrontmatter(lesson);
+        const content = this.buildContent(lesson);
+
+        return {
+            name,
+            filename: `learned-${name}.md`,
+            content: `---\n${frontmatter}\n---\n\n${content}`
+        };
+    }
+
+    /**
+     * Sanitize tag as filename-safe name
+     */
+    sanitizeName(tag) {
+        return tag.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    }
+
+    /**
+     * Build YAML frontmatter
+     */
+    buildFrontmatter(lesson) {
+        const totalHits = this.calculateTotalHits(lesson);
+        const evidenceCount = lesson.mistakes.length + lesson.improvements.length;
+
+        return [
+            `name: ${lesson.tag}`,
+            `description: ${lesson.intent.goal}`,
+            `maturity: ${lesson.maturity.state}`,
+            `confidence: ${lesson.maturity.confidence}`,
+            `evidence: ${evidenceCount} patterns, ${totalHits} detections`,
+            `trigger: always_on`
+        ].join('\n');
+    }
+
+    /**
+     * Calculate total hits across mistakes and improvements
+     */
+    calculateTotalHits(lesson) {
+        const mistakeHits = lesson.mistakes.reduce((sum, m) => sum + (m.hitCount || 0), 0);
+        const improvementHits = lesson.improvements.reduce((sum, i) => sum + (i.appliedCount || 0), 0);
+        return mistakeHits + improvementHits;
+    }
+
+    /**
+     * Build main content
+     */
+    buildContent(lesson) {
+        let md = `# ${lesson.title}\n\n`;
+
+        // Header section
+        md += this.buildHeader(lesson);
+
+        // Anti-patterns section
+        if (lesson.mistakes.length > 0) {
+            md += this.buildAntiPatterns(lesson.mistakes);
+        }
+
+        // Best practices section
+        if (lesson.improvements.length > 0) {
+            md += this.buildBestPractices(lesson.improvements);
+        }
+
+        // Evolution status
+        md += this.buildEvolutionStatus(lesson);
+
+        // When to apply
+        md += this.buildApplicationGuide(lesson);
+
+        // Confidence metrics
+        md += this.buildMetrics(lesson);
+
+        // Footer
+        md += this.buildFooter();
+
+        return md;
+    }
+
+    /**
+     * Build header section
+     */
+    buildHeader(lesson) {
+        return [
+            `> **Intent:** ${lesson.intent.goal}`,
+            `> **Maturity:** ${lesson.maturity.state} (${(lesson.maturity.confidence * 100).toFixed(0)}% confidence)`,
+            `> **Coverage:** ${lesson.maturity.coverage}`,
+            '',
+            `**Recommendation:** ${lesson.maturity.recommendation}`,
+            '',
+            ''
+        ].join('\n');
+    }
+
+    /**
+     * Build anti-patterns section
+     */
+    buildAntiPatterns(mistakes) {
+        let md = `## 🚫 Anti-Patterns (Avoid These)\n\n`;
+
+        mistakes.forEach(mistake => {
+            md += `### ❌ ${mistake.id}: ${mistake.message}\n\n`;
+            md += `**Pattern:** \`${mistake.pattern}\`  \n`;
+            md += `**Severity:** ${mistake.severity}  \n`;
+            md += `**Hit Count:** ${mistake.hitCount || 0} detections  \n`;
+
+            if (mistake.lastHit) {
+                const lastHit = new Date(mistake.lastHit).toLocaleDateString();
+                md += `**Last Seen:** ${lastHit}  \n`;
+            }
+
+            md += '\n';
+
+            // Add tags if available
+            if (mistake.tags && mistake.tags.length > 0) {
+                md += `**Tags:** ${mistake.tags.join(', ')}  \n\n`;
+            }
+        });
+
+        return md;
+    }
+
+    /**
+     * Build best practices section
+     */
+    buildBestPractices(improvements) {
+        let md = `## ✅ Best Practices (Do This Instead)\n\n`;
+
+        improvements.forEach(improvement => {
+            md += `### ✅ ${improvement.id}: ${improvement.message}\n\n`;
+            md += `**Pattern:** \`${improvement.pattern}\`  \n`;
+            md += `**Applied Count:** ${improvement.appliedCount || 0} times  \n`;
+
+            if (improvement.lastApplied) {
+                const lastApplied = new Date(improvement.lastApplied).toLocaleDateString();
+                md += `**Last Applied:** ${lastApplied}  \n`;
+            }
+
+            md += '\n';
+
+            // Add tags if available
+            if (improvement.tags && improvement.tags.length > 0) {
+                md += `**Tags:** ${improvement.tags.join(', ')}  \n\n`;
+            }
+        });
+
+        return md;
+    }
+
+    /**
+     * Build evolution status section
+     */
+    buildEvolutionStatus(lesson) {
+        let md = `## 📊 Evolution Status\n\n`;
+
+        if (lesson.evolution.signals && lesson.evolution.signals.length > 0) {
+            md += `**Active Signals:**\n`;
+            lesson.evolution.signals.forEach(signal => {
+                md += `- **${signal.type}** (${signal.priority}): ${signal.reason}\n`;
+            });
+            md += '\n';
+        }
+
+        if (lesson.evolution.missingAreas && lesson.evolution.missingAreas.length > 0) {
+            md += `**Missing Areas:**\n`;
+            lesson.evolution.missingAreas.forEach(area => {
+                md += `- ${area.area}: ${area.reason}\n`;
+            });
+            md += '\n';
+        }
+
+        md += `**Next Action:** ${lesson.evolution.nextAction}\n\n`;
+
+        return md;
+    }
+
+    /**
+     * Build application guide
+     */
+    buildApplicationGuide(lesson) {
+        let md = `## 🎯 When to Apply\n\n`;
+        md += `This skill applies when:\n`;
+        md += `- Working with **${lesson.intent.category}**\n`;
+        md += `- Goal: ${lesson.intent.goal}\n`;
+        md += `- Confidence level: ${lesson.intent.strength >= 0.7 ? 'High' : 'Moderate'}\n\n`;
+
+        return md;
+    }
+
+    /**
+     * Build confidence metrics
+     */
+    buildMetrics(lesson) {
+        let md = `## 📈 Confidence Metrics\n\n`;
+
+        const indicators = lesson.maturity.indicators;
+        md += `- **Balance Score:** ${(indicators.balance * 100).toFixed(0)}% (improvement/total ratio)\n`;
+        md += `- **Evidence Score:** ${(indicators.evidence * 100).toFixed(0)}% (validation from hits)\n`;
+        md += `- **Recency Score:** ${(indicators.recency * 100).toFixed(0)}% (freshness)\n`;
+        md += `- **Overall Confidence:** ${(lesson.maturity.confidence * 100).toFixed(0)}%\n\n`;
+
+        return md;
+    }
+
+    /**
+     * Build footer
+     */
+    buildFooter() {
+        const timestamp = new Date().toISOString();
+
+        return [
+            '---',
+            '',
+            '*Auto-generated from Agent Skill Kit*  ',
+            `*Source: \`.agent/knowledge/mistakes.yaml\` + \`improvements.yaml\`*  `,
+            `*Generated: ${timestamp}*`
+        ].join('\n');
+    }
+}

package/packages/cli/src/services/export-service.js

@@ -0,0 +1,162 @@
+/**
+ * ExportService - Application Service
+ * 
+ * Orchestrates skill export workflow:
+ * - Load cognitive lessons
+ * - Filter by maturity
+ * - Format as Gemini skills
+ * - Write to .agent/skills/
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export class ExportService {
+    constructor(learningService, skillFormatter) {
+        this.learningService = learningService;
+        this.skillFormatter = skillFormatter;
+    }
+
+    /**
+     * Export all mature skills to Gemini format
+     * @param {string} outputDir - Output directory (default: .agent/skills)
+     * @param {number} minConfidence - Minimum confidence threshold (default: 0.8)
+     * @returns {Promise<Array>} Exported skills
+     */
+    async exportMatureSkills(outputDir = '.agent/skills', minConfidence = 0.8) {
+        // 1. Get all cognitive lessons
+        const lessons = await this.learningService.getCognitiveLessons();
+
+        // 2. Filter mature lessons
+        const mature = this.filterMature(lessons, minConfidence);
+
+        // 3. Format as skills
+        const skills = mature.map(lesson =>
+            this.skillFormatter.format(lesson)
+        );
+
+        // 4. Write to output directory
+        const exported = await this.writeSkills(skills, outputDir);
+
+        return exported;
+    }
+
+    /**
+     * Export a specific lesson by ID
+     * @param {string} lessonId - Lesson ID (e.g., LESSON-008)
+     * @param {string} outputDir - Output directory
+     * @returns {Promise<object>} Exported skill
+     */
+    async exportLesson(lessonId, outputDir = '.agent/skills') {
+        // 1. Get all lessons
+        const lessons = await this.learningService.getCognitiveLessons();
+
+        // 2. Find specific lesson
+        const lesson = lessons.find(l => l.id === lessonId);
+
+        if (!lesson) {
+            throw new Error(`Lesson not found: ${lessonId}`);
+        }
+
+        // 3. Format as skill
+        const skill = this.skillFormatter.format(lesson);
+
+        // 4. Write to output
+        await this.writeSkill(skill, outputDir);
+
+        return skill;
+    }
+
+    /**
+     * Preview mature skills without writing
+     * @param {number} minConfidence - Minimum confidence threshold
+     * @returns {Promise<Array>} Skills preview
+     */
+    async previewMatureSkills(minConfidence = 0.8) {
+        const lessons = await this.learningService.getCognitiveLessons();
+        const mature = this.filterMature(lessons, minConfidence);
+
+        return mature.map(lesson => ({
+            id: lesson.id,
+            title: lesson.title,
+            state: lesson.maturity.state,
+            confidence: lesson.maturity.confidence,
+            coverage: lesson.maturity.coverage,
+            filename: `learned-${this.skillFormatter.sanitizeName(lesson.tag)}.md`
+        }));
+    }
+
+    /**
+     * Filter mature lessons
+     * @param {Array} lessons - All cognitive lessons
+     * @param {number} minConfidence - Minimum confidence
+     * @returns {Array} Filtered lessons
+     */
+    filterMature(lessons, minConfidence) {
+        return lessons.filter(lesson => {
+            const isMature = lesson.maturity.state === 'MATURE' || lesson.maturity.state === 'IDEAL';
+            const isConfident = lesson.maturity.confidence >= minConfidence;
+            return isMature && isConfident;
+        });
+    }
+
+    /**
+     * Write multiple skills to directory
+     * @param {Array} skills - Formatted skills
+     * @param {string} outputDir - Output directory
+     * @returns {Promise<Array>} Written skills with paths
+     */
+    async writeSkills(skills, outputDir) {
+        // Ensure directory exists
+        fs.mkdirSync(outputDir, { recursive: true });
+
+        const written = [];
+
+        for (const skill of skills) {
+            const filePath = path.join(outputDir, skill.filename);
+            fs.writeFileSync(filePath, skill.content, 'utf8');
+
+            written.push({
+                ...skill,
+                path: filePath
+            });
+        }
+
+        return written;
+    }
+
+    /**
+     * Write a single skill to directory
+     * @param {object} skill - Formatted skill
+     * @param {string} outputDir - Output directory
+     */
+    async writeSkill(skill, outputDir) {
+        fs.mkdirSync(outputDir, { recursive: true });
+
+        const filePath = path.join(outputDir, skill.filename);
+        fs.writeFileSync(filePath, skill.content, 'utf8');
+
+        return {
+            ...skill,
+            path: filePath
+        };
+    }
+
+    /**
+     * Get export statistics
+     * @returns {Promise<object>} Export stats
+     */
+    async getExportStats() {
+        const lessons = await this.learningService.getCognitiveLessons();
+        const mature = this.filterMature(lessons, 0.8);
+
+        return {
+            total: lessons.length,
+            mature: mature.length,
+            learning: lessons.filter(l => l.maturity.state === 'LEARNING').length,
+            raw: lessons.filter(l => l.maturity.state === 'RAW').length,
+            ideal: lessons.filter(l => l.maturity.state === 'IDEAL').length,
+            exportable: mature.length
+        };
+    }
+}

package/packages/cli/src/services/index.js

@@ -0,0 +1,13 @@
+/**
+ * Services Layer
+ * 
+ * Application services that orchestrate core domain logic.
+ * Services have NO business logic, only coordination.
+ * 
+ * Exported:
+ * - LearningService
+ * - ExportService
+ */
+
+export { LearningService } from './learning-service.js';
+export { ExportService } from './export-service.js';