@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/bin/lib/skill-matcher.cjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Matcher — Rule-based skill matching algorithm
+ *
+ * Matches context to skills using 5-rule matching:
+ * - Rule 1: Stack skills (mandatory, priority 100)
+ * - Rule 2: Domain skills (if project type detected, priority 90)
+ * - Rule 3: Mode skills (ceremony level, priority 85)
+ * - Rule 4: Constraint-based skills (deadline, team, compliance, priority 80)
+ * - Rule 5: Universal skills (always activate, priority 50)
+ *
+ * Enforces 3-7 skill limit per task (EDGE-05 compliance)
+ *
+ * Usage:
+ *   const { SkillMatcher, SKILL_LIMITS } = require('./skill-matcher.cjs');
+ *   const matcher = new SkillMatcher(registry);
+ *   const result = matcher.match(context);
+ */
+
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Skill activation limits (EDGE-05 compliance)
+ */
+const SKILL_LIMITS = {
+  MIN_ACTIVE: 3,
+  MAX_ACTIVE: 7,
+  CRITICAL_TASK_MAX: 5,  // For security-sensitive tasks
+  MVP_MODE_MAX: 4,       // Rapid MVP mode reduces complexity
+};
+
+/**
+ * Skill Matcher class for matching context to skills
+ */
+class SkillMatcher {
+  /**
+   * Create a SkillMatcher instance
+   * @param {Object} registry - SkillRegistry instance
+   * @param {Object} options - Matcher options
+   */
+  constructor(registry, options = {}) {
+    this.registry = registry;
+    this.logger = options.logger || logger;
+    this.rules = this.loadMatchingRules();
+  }
+
+  /**
+   * Match context to skills
+   * @param {Object} context - Matching context
+   * @returns {Object} Match result: { activatedSkills, rationale, conflicts, metadata }
+   */
+  match(context) {
+    const candidates = [];
+
+    // Rule 1: Stack skills (mandatory)
+    if (context.stack?.framework || context.stack?.language) {
+      const stackSkills = this.findByStack(context.stack);
+      stackSkills.forEach(skill => {
+        candidates.push({ skill, priority: 100, rule: 'stack' });
+      });
+    }
+
+    // Rule 2: Domain skills (if project type detected)
+    if (context.projectType) {
+      const domainSkills = this.findByDomain(context.projectType);
+      domainSkills.forEach(skill => {
+        candidates.push({ skill, priority: 90, rule: 'domain' });
+      });
+    }
+
+    // Rule 3: Mode skills (ceremony level)
+    if (context.mode) {
+      const modeSkills = this.findByMode(context.mode);
+      modeSkills.forEach(skill => {
+        candidates.push({ skill, priority: 85, rule: 'mode' });
+      });
+    }
+
+    // Rule 4: Constraint-based skills
+    const constraintSkills = this.findByConstraints(context.constraints);
+    constraintSkills.forEach(skill => {
+      candidates.push({ skill, priority: 80, rule: 'constraint' });
+    });
+
+    // Rule 5: Universal skills (always activate)
+    const universalSkills = this.registry.findByTag('universal');
+    universalSkills.forEach(skill => {
+      candidates.push({ skill, priority: 50, rule: 'universal' });
+    });
+
+    // Sort by priority and apply limits
+    const sorted = candidates.sort((a, b) => b.priority - a.priority);
+    const limited = this.enforceSkillLimits(sorted, context);
+    const activatedSkills = limited.map(c => c.skill);
+
+    return {
+      activatedSkills,
+      rationale: this.generateRationale(activatedSkills, context),
+      conflicts: [], // Reserved for Phase 36 SKILL-07
+      metadata: {
+        totalCandidates: candidates.length,
+        rulesApplied: [...new Set(candidates.map(c => c.rule))],
+        limitEnforced: candidates.length > limited.length
+      }
+    };
+  }
+
+  /**
+   * Enforce skill activation limits
+   * @param {Object[]} candidates - Sorted candidate skills
+   * @param {Object} context - Matching context
+   * @returns {Object[]} Limited candidate array
+   * @private
+   */
+  enforceSkillLimits(candidates, context) {
+    const maxSkills = context.mode === 'rapid-mvp'
+      ? SKILL_LIMITS.MVP_MODE_MAX
+      : SKILL_LIMITS.MAX_ACTIVE;
+
+    if (candidates.length > maxSkills) {
+      this.logger.warn('Skill limit exceeded', {
+        candidateCount: candidates.length,
+        maxSkills,
+        mode: context.mode,
+        skills: candidates.slice(0, maxSkills).map(c => c.skill.name)
+      });
+    }
+
+    return candidates.slice(0, maxSkills);
+  }
+
+  /**
+   * Generate rationale for skill activation
+   * @param {Object[]} skills - Activated skills
+   * @param {Object} context - Matching context
+   * @returns {string} Rationale string
+   * @private
+   */
+  generateRationale(skills, context) {
+    const categories = {};
+    skills.forEach(skill => {
+      const cat = skill.category || 'other';
+      if (!categories[cat]) categories[cat] = [];
+      categories[cat].push(skill.name);
+    });
+
+    const parts = [];
+    if (categories.stack) parts.push(`stack: ${categories.stack.join(', ')}`);
+    if (categories.domain) parts.push(`domain: ${categories.domain.join(', ')}`);
+    if (categories.mode) parts.push(`mode: ${categories.mode.join(', ')}`);
+    if (categories.constraint) parts.push(`constraint: ${categories.constraint.join(', ')}`);
+    if (categories.universal) parts.push(`universal: ${categories.universal.join(', ')}`);
+
+    return `Activated ${skills.length} skills based on ${context.mode || 'default'} mode: ${parts.join('; ')}`;
+  }
+
+  /**
+   * Find skills by stack
+   * @param {Object|string} stack - Stack identifier
+   * @returns {Object[]} Matching skills
+   */
+  findByStack(stack) {
+    return this.registry.findByStack(stack);
+  }
+
+  /**
+   * Find skills by domain/project type
+   * @param {string} projectType - Project type
+   * @returns {Object[]} Matching skills
+   */
+  findByDomain(projectType) {
+    return this.registry.findByTag(projectType);
+  }
+
+  /**
+   * Find skills by mode
+   * @param {string} mode - Mode identifier
+   * @returns {Object[]} Matching skills
+   */
+  findByMode(mode) {
+    return this.registry.findByTag(mode);
+  }
+
+  /**
+   * Find skills by constraints
+   * @param {Object} constraints - Constraint object
+   * @returns {Object[]} Matching skills
+   * @private
+   */
+  findByConstraints(constraints) {
+    const skills = [];
+    if (!constraints) return skills;
+
+    // Deadline-based skills
+    if (constraints.deadline === '2-weeks' || constraints.deadline === '1-week') {
+      const rapid = this.registry.get('rapid_delivery_skill_v1');
+      if (rapid) skills.push(rapid);
+    }
+
+    // Compliance-based skills
+    if (constraints.compliance?.includes('hipaa')) {
+      const hipaa = this.registry.get('hipaa_compliance_skill_v1');
+      if (hipaa) skills.push(hipaa);
+    }
+
+    // Team size skills
+    if (constraints.teamSize === 1) {
+      const solo = this.registry.get('solo_developer_skill_v1');
+      if (solo) skills.push(solo);
+    }
+
+    return skills;
+  }
+
+  /**
+   * Load matching rules configuration
+   * @returns {Object} Rules configuration
+   * @private
+   */
+  loadMatchingRules() {
+    return {
+      stack: { priority: 100, required: true },
+      domain: { priority: 90, required: false },
+      mode: { priority: 85, required: false },
+      constraint: { priority: 80, required: false },
+      universal: { priority: 50, required: true }
+    };
+  }
+}
+
+module.exports = {
+  SkillMatcher,
+  SKILL_LIMITS
+};

package/ez-agents/bin/lib/skill-registry.cjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Registry — Core module for loading, indexing, and searching skills
+ *
+ * Provides file-based skill registry with:
+ * - Load skills from global and local directories
+ * - Get skill by name
+ * - Filter by tag, category, or stack
+ * - Search across name, description, and tags
+ * - Lazy loading with cache (LazySkillRegistry subclass)
+ *
+ * Usage:
+ *   const { SkillRegistry, LazySkillRegistry } = require('./skill-registry.cjs');
+ *   const registry = new SkillRegistry();
+ *   await registry.load();
+ *   const skill = registry.get('laravel_11_structure_skill_v2');
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { safeReadFile } = require('./safe-path.cjs');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Skill Registry class for managing skills
+ */
+class SkillRegistry {
+  /**
+   * Create a SkillRegistry instance
+   * @param {Object} options - Registry options
+   * @param {string} options.globalPath - Global skills directory (default: skills/)
+   * @param {string} options.localPath - Local project skills directory (default: .planning/skills)
+   */
+  constructor(options = {}) {
+    this.globalSkillsPath = options.globalPath || path.join(__dirname, '../../skills');
+    this.localSkillsPath = options.localPath || '.planning/skills';
+    this.skills = new Map();
+    this.loaded = false;
+    this.logger = logger;
+  }
+
+  /**
+   * Load skills from global and local directories
+   * @returns {Promise<SkillRegistry>} this for chaining
+   */
+  async load() {
+    // Load global skills
+    await this._loadFromPath(this.globalSkillsPath, 'global');
+
+    // Load local project skills (override global)
+    if (fs.existsSync(this.localSkillsPath)) {
+      await this._loadFromPath(this.localSkillsPath, 'local');
+    }
+
+    this.loaded = true;
+    this.logger.info('Skill registry loaded', {
+      skillCount: this.skills.size,
+      globalPath: this.globalSkillsPath,
+      localPath: this.localSkillsPath
+    });
+
+    return this;
+  }
+
+  /**
+   * Load skills from a specific path
+   * @param {string} basePath - Base directory to scan
+   * @param {string} scope - Scope identifier ('global' or 'local')
+   * @private
+   */
+  _loadFromPath(basePath, scope) {
+    if (!fs.existsSync(basePath)) {
+      this.logger.debug('Skills path does not exist', { basePath });
+      return;
+    }
+
+    // Read category directories
+    const categories = ['stack', 'architecture', 'domain', 'operational', 'governance'];
+
+    for (const category of categories) {
+      const categoryPath = path.join(basePath, category);
+      if (!fs.existsSync(categoryPath)) continue;
+
+      // Get skill group directories (e.g., 'laravel', 'react', etc.)
+      const skillGroups = fs.readdirSync(categoryPath, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+
+      for (const group of skillGroups) {
+        const groupPath = path.join(categoryPath, group);
+        
+        // Check for versioned skill directories within the group
+        const skillVersions = fs.readdirSync(groupPath, { withFileTypes: true })
+          .filter(d => d.isDirectory())
+          .map(d => d.name);
+
+        for (const versionDir of skillVersions) {
+          const skillPath = path.join(groupPath, versionDir, 'SKILL.md');
+          if (fs.existsSync(skillPath)) {
+            try {
+              const content = fs.readFileSync(skillPath, 'utf8');
+              const skill = this._parseSkill(skillPath, content, scope);
+              // Local skills override global skills with same name
+              this.skills.set(skill.name, skill);
+            } catch (err) {
+              this.logger.error('Failed to load skill', {
+                skillPath,
+                error: err.message
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Parse skill metadata from SKILL.md content
+   * @param {string} filePath - Path to SKILL.md file
+   * @param {string} content - File content
+   * @param {string} scope - Scope identifier
+   * @returns {Object} Parsed skill object
+   * @private
+   */
+  _parseSkill(filePath, content, scope) {
+    const frontmatter = extractFrontmatter(content);
+    const body = content.replace(/^---[\s\S]+?\n---/, '').trim();
+
+    return {
+      name: frontmatter.name,
+      description: frontmatter.description,
+      version: frontmatter.version || '1.0.0',
+      tags: frontmatter.tags || [],
+      stack: frontmatter.stack,
+      category: frontmatter.category,
+      triggers: frontmatter.triggers,
+      prerequisites: frontmatter.prerequisites || [],
+      recommended_structure: frontmatter.recommended_structure,
+      workflow: frontmatter.workflow,
+      best_practices: frontmatter.best_practices || [],
+      anti_patterns: frontmatter.anti_patterns || [],
+      scaling_notes: frontmatter.scaling_notes,
+      when_not_to_use: frontmatter.when_not_to_use,
+      output_template: frontmatter.output_template,
+      dependencies: frontmatter.dependencies,
+      scope,
+      path: filePath,
+      body
+    };
+  }
+
+  /**
+   * Get a skill by name
+   * @param {string} name - Skill name
+   * @returns {Object|undefined} Skill object or undefined
+   */
+  get(name) {
+    return this.skills.get(name);
+  }
+
+  /**
+   * Get all skills
+   * @returns {Object[]} Array of all skill objects
+   */
+  getAll() {
+    return Array.from(this.skills.values());
+  }
+
+  /**
+   * Find skills by tag
+   * @param {string} tag - Tag to filter by
+   * @returns {Object[]} Array of matching skills
+   */
+  findByTag(tag) {
+    return this.getAll().filter(s => s.tags?.includes(tag));
+  }
+
+  /**
+   * Find skills by category
+   * @param {string} category - Category to filter by
+   * @returns {Object[]} Array of matching skills
+   */
+  findByCategory(category) {
+    return this.getAll().filter(s => s.category === category);
+  }
+
+  /**
+   * Find skills by stack identifier
+   * @param {string|Object} stack - Stack identifier (string or object with language/framework)
+   * @returns {Object[]} Array of matching skills
+   */
+  findByStack(stack) {
+    return this.getAll().filter(s => {
+      if (!s.stack) return false;
+
+      if (typeof stack === 'string') {
+        return s.stack === stack;
+      }
+
+      if (typeof stack === 'object') {
+        // Support object format: { language: 'php', framework: 'laravel' }
+        const stackStr = `${stack.language}/${stack.framework}`;
+        return s.stack.includes(stackStr);
+      }
+
+      return false;
+    });
+  }
+
+  /**
+   * Search skills by keyword
+   * @param {string} query - Search query
+   * @returns {Object[]} Array of matching skills
+   */
+  search(query) {
+    const q = query.toLowerCase();
+    return this.getAll().filter(s =>
+      s.name.toLowerCase().includes(q) ||
+      s.description.toLowerCase().includes(q) ||
+      s.tags?.some(t => t.toLowerCase().includes(q))
+    );
+  }
+
+  /**
+   * Clear all loaded skills
+   */
+  clear() {
+    this.skills.clear();
+    this.loaded = false;
+  }
+}
+
+/**
+ * Lazy Skill Registry with caching
+ * Extends SkillRegistry with TTL-based caching for better performance
+ */
+class LazySkillRegistry extends SkillRegistry {
+  /**
+   * Create a LazySkillRegistry instance
+   * @param {Object} options - Registry options
+   * @param {number} options.cacheTTL - Cache TTL in milliseconds (default: 5 minutes)
+   */
+  constructor(options = {}) {
+    super(options);
+    this.cache = new Map();
+    this.cacheTTL = options.cacheTTL || 5 * 60 * 1000; // 5 minutes
+    this.cacheTimestamps = new Map();
+  }
+
+  /**
+   * Get a skill by name with caching
+   * @param {string} name - Skill name
+   * @returns {Object|undefined} Skill object or undefined
+   */
+  get(name) {
+    // Check cache first
+    const cached = this._getFromCache(name);
+    if (cached) {
+      return cached;
+    }
+
+    // Load from parent if not in cache
+    const skill = super.get(name);
+    if (skill) {
+      this._setInCache(name, skill);
+    }
+
+    return skill;
+  }
+
+  /**
+   * Get all skills with caching
+   * @returns {Object[]} Array of all skill objects
+   */
+  getAll() {
+    const cached = this._getFromCache('__all__');
+    if (cached) {
+      return cached;
+    }
+
+    const skills = super.getAll();
+    this._setInCache('__all__', skills);
+    return skills;
+  }
+
+  /**
+   * Get item from cache with TTL check
+   * @param {string} key - Cache key
+   * @returns {any|null} Cached value or null if expired/missing
+   * @private
+   */
+  _getFromCache(key) {
+    const timestamp = this.cacheTimestamps.get(key);
+    if (!timestamp) return null;
+
+    const age = Date.now() - timestamp;
+    if (age > this.cacheTTL) {
+      // Cache expired
+      this.cache.delete(key);
+      this.cacheTimestamps.delete(key);
+      return null;
+    }
+
+    return this.cache.get(key);
+  }
+
+  /**
+   * Set item in cache with timestamp
+   * @param {string} key - Cache key
+   * @param {any} value - Value to cache
+   * @private
+   */
+  _setInCache(key, value) {
+    this.cache.set(key, value);
+    this.cacheTimestamps.set(key, Date.now());
+  }
+
+  /**
+   * Clear cache
+   */
+  clearCache() {
+    this.cache.clear();
+    this.cacheTimestamps.clear();
+  }
+
+  /**
+   * Clear all skills and cache
+   */
+  clear() {
+    super.clear();
+    this.clearCache();
+  }
+}
+
+module.exports = {
+  SkillRegistry,
+  LazySkillRegistry
+};