aidp 0.15.2 → 0.17.0

data/lib/aidp/skills/registry.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Aidp
+  module Skills
+    # Registry for managing available skills
+    #
+    # The Registry loads skills from multiple search paths and provides
+    # lookup, filtering, and management capabilities.
+    #
+    # Skills are loaded from:
+    # 1. Template skills directory (gem templates/skills/) - built-in templates
+    # 2. Project skills directory (.aidp/skills/) - project-specific skills
+    #
+    # Project skills with matching IDs override template skills.
+    #
+    # @example Basic usage
+    #   registry = Registry.new(project_dir: "/path/to/project")
+    #   registry.load_skills
+    #   skill = registry.find("repository_analyst")
+    #
+    # @example With provider filtering
+    #   registry = Registry.new(project_dir: "/path/to/project", provider: "anthropic")
+    #   registry.load_skills
+    #   skills = registry.all # Only anthropic-compatible skills
+    class Registry
+      attr_reader :project_dir, :provider
+
+      # Initialize a new skills registry
+      #
+      # @param project_dir [String] Root directory of the project
+      # @param provider [String, nil] Optional provider name for filtering
+      def initialize(project_dir:, provider: nil)
+        @project_dir = project_dir
+        @provider = provider
+        @skills = {}
+        @loaded = false
+      end
+
+      # Load skills from all search paths
+      #
+      # Skills are loaded in order:
+      # 1. Template skills (gem templates/skills/) - built-in templates
+      # 2. Project skills (.aidp/skills/) - override templates
+      #
+      # @return [Integer] Number of skills loaded
+      def load_skills
+        Aidp.log_debug("skills", "Loading skills", project_dir: project_dir, provider: provider)
+
+        @skills = {}
+
+        # Load template skills first
+        template_skills = load_from_path(template_skills_path)
+        template_skills.each { |skill| register_skill(skill, source: :template) }
+
+        # Load project skills (override templates if IDs match)
+        project_skills = load_from_path(project_skills_path)
+        project_skills.each { |skill| register_skill(skill, source: :project) }
+
+        @loaded = true
+
+        Aidp.log_info("skills", "Loaded skills", count: @skills.size, provider: provider)
+        @skills.size
+      end
+
+      # Find a skill by ID
+      #
+      # @param skill_id [String] Skill identifier
+      # @return [Skill, nil] Skill if found, nil otherwise
+      def find(skill_id)
+        load_skills unless loaded?
+        @skills[skill_id.to_s]
+      end
+
+      # Get all registered skills
+      #
+      # @return [Array<Skill>] Array of all skills
+      def all
+        load_skills unless loaded?
+        @skills.values
+      end
+
+      # Get skills matching a search query
+      #
+      # @param query [String] Search query (searches id, name, description, keywords, expertise)
+      # @return [Array<Skill>] Matching skills
+      def search(query)
+        load_skills unless loaded?
+        all.select { |skill| skill.matches?(query) }
+      end
+
+      # Get skills by keyword
+      #
+      # @param keyword [String] Keyword to match
+      # @return [Array<Skill>] Skills with matching keyword
+      def by_keyword(keyword)
+        load_skills unless loaded?
+        all.select { |skill| skill.keywords.include?(keyword) }
+      end
+
+      # Get skills compatible with a specific provider
+      #
+      # @param provider_name [String] Provider name
+      # @return [Array<Skill>] Compatible skills
+      def compatible_with(provider_name)
+        load_skills unless loaded?
+        all.select { |skill| skill.compatible_with?(provider_name) }
+      end
+
+      # Check if a skill exists
+      #
+      # @param skill_id [String] Skill identifier
+      # @return [Boolean] True if skill exists
+      def exists?(skill_id)
+        find(skill_id) != nil
+      end
+
+      # Check if skills have been loaded
+      #
+      # @return [Boolean] True if loaded
+      def loaded?
+        @loaded
+      end
+
+      # Get count of registered skills
+      #
+      # @return [Integer] Number of skills
+      def count
+        load_skills unless loaded?
+        @skills.size
+      end
+
+      # Reload skills from disk
+      #
+      # @return [Integer] Number of skills loaded
+      def reload
+        @loaded = false
+        load_skills
+      end
+
+      # Get skill IDs grouped by source
+      #
+      # @return [Hash] Hash with :template and :project arrays
+      def by_source
+        load_skills unless loaded?
+
+        {
+          template: @skills.values.select { |s| template_skill?(s) }.map(&:id),
+          project: @skills.values.select { |s| project_skill?(s) }.map(&:id)
+        }
+      end
+
+      private
+
+      # Register a skill in the registry
+      #
+      # @param skill [Skill] Skill to register
+      # @param source [Symbol] Source type (:builtin or :custom)
+      def register_skill(skill, source:)
+        if @skills.key?(skill.id)
+          Aidp.log_debug(
+            "skills",
+            "Overriding skill",
+            skill_id: skill.id,
+            old_source: @skills[skill.id].source_path,
+            new_source: skill.source_path
+          )
+        end
+
+        @skills[skill.id] = skill
+
+        Aidp.log_debug(
+          "skills",
+          "Registered skill",
+          skill_id: skill.id,
+          source: source,
+          version: skill.version
+        )
+      end
+
+      # Load skills from a directory path
+      #
+      # @param path [String] Directory path
+      # @return [Array<Skill>] Loaded skills
+      def load_from_path(path)
+        return [] unless Dir.exist?(path)
+        Loader.load_from_directory(path, provider: provider)
+      end
+
+      # Get template skills path (from gem)
+      #
+      # @return [String] Path to template skills directory
+      def template_skills_path
+        # Get the gem root directory (go up from lib/aidp/skills/registry.rb)
+        gem_root = File.expand_path("../../../..", __dir__)
+        File.join(gem_root, "templates", "skills")
+      end
+
+      # Get project skills path
+      #
+      # @return [String] Path to project-specific skills directory
+      def project_skills_path
+        File.join(project_dir, ".aidp", "skills")
+      end
+
+      # Check if skill is from template directory
+      #
+      # @param skill [Skill] Skill to check
+      # @return [Boolean] True if template
+      def template_skill?(skill)
+        skill.source_path.start_with?(template_skills_path)
+      end
+
+      # Check if skill is from project directory
+      #
+      # @param skill [Skill] Skill to check
+      # @return [Boolean] True if project
+      def project_skill?(skill)
+        skill.source_path.start_with?(project_skills_path)
+      end
+    end
+  end
+end

data/lib/aidp/skills/router.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Aidp
+  module Skills
+    # Routes file paths and tasks to appropriate skills based on routing rules
+    #
+    # The Router reads routing configuration from aidp.yml and matches:
+    # - File paths against glob patterns (path_rules)
+    # - Task descriptions against keywords (task_rules)
+    # - Combined path + task rules (combined_rules)
+    #
+    # @example Basic usage
+    #   router = Router.new(project_dir: Dir.pwd)
+    #   skill_id = router.route_by_path("app/controllers/users_controller.rb")
+    #   # => "rails_expert"
+    #
+    # @example Task-based routing
+    #   router = Router.new(project_dir: Dir.pwd)
+    #   skill_id = router.route_by_task("Add API endpoint")
+    #   # => "backend_developer"
+    #
+    # @example Combined routing
+    #   router = Router.new(project_dir: Dir.pwd)
+    #   skill_id = router.route(path: "lib/cli.rb", task: "Add command")
+    #   # => "cli_expert"
+    class Router
+      attr_reader :config, :project_dir
+
+      # Initialize router with project directory
+      #
+      # @param project_dir [String] Path to project directory
+      def initialize(project_dir:)
+        @project_dir = project_dir
+        @config = load_config
+      end
+
+      # Route based on both path and task (highest priority)
+      #
+      # @param path [String, nil] File path to route
+      # @param task [String, nil] Task description to route
+      # @return [String, nil] Matched skill ID or nil
+      def route(path: nil, task: nil)
+        # Priority 1: Combined rules (path AND task)
+        if path && task
+          combined_match = match_combined_rules(path, task)
+          return combined_match if combined_match
+        end
+
+        # Priority 2: Path rules
+        path_match = route_by_path(path) if path
+        return path_match if path_match
+
+        # Priority 3: Task rules
+        task_match = route_by_task(task) if task
+        return task_match if task_match
+
+        # Priority 4: Default skill
+        config.dig("skills", "routing", "default")
+      end
+
+      # Route based on file path
+      #
+      # @param path [String] File path to match against patterns
+      # @return [String, nil] Matched skill ID or nil
+      def route_by_path(path)
+        return nil unless path
+
+        path_rules = config.dig("skills", "routing", "path_rules") || {}
+
+        path_rules.each do |skill_id, patterns|
+          patterns = [patterns] unless patterns.is_a?(Array)
+          patterns.each do |pattern|
+            return skill_id if File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+        end
+
+        nil
+      end
+
+      # Route based on task description
+      #
+      # @param task [String] Task description to match against keywords
+      # @return [String, nil] Matched skill ID or nil
+      def route_by_task(task)
+        return nil unless task
+
+        task_rules = config.dig("skills", "routing", "task_rules") || {}
+        task_lower = task.downcase
+
+        task_rules.each do |skill_id, keywords|
+          keywords = [keywords] unless keywords.is_a?(Array)
+          keywords.each do |keyword|
+            return skill_id if task_lower.include?(keyword.downcase)
+          end
+        end
+
+        nil
+      end
+
+      # Check if routing is enabled
+      #
+      # @return [Boolean] true if routing is configured
+      def routing_enabled?
+        config.dig("skills", "routing", "enabled") == true
+      end
+
+      # Get default skill
+      #
+      # @return [String, nil] Default skill ID or nil
+      def default_skill
+        config.dig("skills", "routing", "default")
+      end
+
+      # Get all routing rules
+      #
+      # @return [Hash] Hash containing path_rules, task_rules, and combined_rules
+      def rules
+        {
+          path_rules: config.dig("skills", "routing", "path_rules") || {},
+          task_rules: config.dig("skills", "routing", "task_rules") || {},
+          combined_rules: config.dig("skills", "routing", "combined_rules") || {}
+        }
+      end
+
+      private
+
+      # Match combined rules (path AND task must both match)
+      #
+      # @param path [String] File path
+      # @param task [String] Task description
+      # @return [String, nil] Matched skill ID or nil
+      def match_combined_rules(path, task)
+        combined_rules = config.dig("skills", "routing", "combined_rules") || {}
+        task_lower = task.downcase
+
+        combined_rules.each do |skill_id, rule|
+          path_patterns = rule["paths"] || []
+          task_keywords = rule["tasks"] || []
+
+          path_patterns = [path_patterns] unless path_patterns.is_a?(Array)
+          task_keywords = [task_keywords] unless task_keywords.is_a?(Array)
+
+          # Check if path matches any pattern
+          path_match = path_patterns.any? do |pattern|
+            File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+
+          # Check if task matches any keyword
+          task_match = task_keywords.any? do |keyword|
+            task_lower.include?(keyword.downcase)
+          end
+
+          return skill_id if path_match && task_match
+        end
+
+        nil
+      end
+
+      # Load routing configuration from aidp.yml
+      #
+      # @return [Hash] Configuration hash
+      def load_config
+        config_path = File.join(project_dir, ".aidp", "aidp.yml")
+
+        if File.exist?(config_path)
+          YAML.safe_load_file(config_path, permitted_classes: [Date, Time, Symbol], aliases: true) || {}
+        else
+          {}
+        end
+      rescue => e
+        Aidp.log_error("skills", "Failed to load routing config", error: e.message)
+        {}
+      end
+    end
+  end
+end

data/lib/aidp/skills/skill.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Aidp
+  module Skills
+    # Represents a skill/persona with metadata and content
+    #
+    # A Skill encapsulates an agent's persona, expertise, and capabilities.
+    # Skills are loaded from SKILL.md files with YAML frontmatter.
+    #
+    # @example Creating a skill
+    #   skill = Skill.new(
+    #     id: "repository_analyst",
+    #     name: "Repository Analyst",
+    #     description: "Expert in version control analysis",
+    #     version: "1.0.0",
+    #     expertise: ["git analysis", "code metrics"],
+    #     keywords: ["git", "metrics"],
+    #     when_to_use: ["Analyzing repository history"],
+    #     when_not_to_use: ["Writing new code"],
+    #     compatible_providers: ["anthropic", "openai"],
+    #     content: "You are a Repository Analyst...",
+    #     source_path: "/path/to/SKILL.md"
+    #   )
+    class Skill
+      attr_reader :id, :name, :description, :version, :expertise, :keywords,
+        :when_to_use, :when_not_to_use, :compatible_providers,
+        :content, :source_path
+
+      # Initialize a new Skill
+      #
+      # @param id [String] Unique identifier for the skill
+      # @param name [String] Human-readable name
+      # @param description [String] Brief one-line description
+      # @param version [String] Semantic version (e.g., "1.0.0")
+      # @param expertise [Array<String>] List of expertise areas
+      # @param keywords [Array<String>] Search/filter keywords
+      # @param when_to_use [Array<String>] Guidance for when to use this skill
+      # @param when_not_to_use [Array<String>] Guidance for when NOT to use
+      # @param compatible_providers [Array<String>] Compatible provider names
+      # @param content [String] The skill content (markdown)
+      # @param source_path [String] Path to source SKILL.md file
+      def initialize(
+        id:,
+        name:,
+        description:,
+        version:,
+        content:, source_path:, expertise: [],
+        keywords: [],
+        when_to_use: [],
+        when_not_to_use: [],
+        compatible_providers: []
+      )
+        @id = id
+        @name = name
+        @description = description
+        @version = version
+        @expertise = Array(expertise)
+        @keywords = Array(keywords)
+        @when_to_use = Array(when_to_use)
+        @when_not_to_use = Array(when_not_to_use)
+        @compatible_providers = Array(compatible_providers)
+        @content = content
+        @source_path = source_path
+
+        validate!
+      end
+
+      # Check if this skill is compatible with a given provider
+      #
+      # @param provider_name [String] Provider name (e.g., "anthropic")
+      # @return [Boolean] True if compatible or no restrictions defined
+      def compatible_with?(provider_name)
+        return true if compatible_providers.empty?
+        compatible_providers.include?(provider_name.to_s.downcase)
+      end
+
+      # Check if this skill matches a search query
+      #
+      # Searches across: id, name, description, expertise, keywords
+      #
+      # @param query [String] Search query (case-insensitive)
+      # @return [Boolean] True if skill matches the query
+      def matches?(query)
+        return true if query.nil? || query.strip.empty?
+
+        query_lower = query.downcase
+        searchable_text = [
+          id,
+          name,
+          description,
+          expertise,
+          keywords
+        ].flatten.join(" ").downcase
+
+        searchable_text.include?(query_lower)
+      end
+
+      # Get a summary of this skill for display
+      #
+      # @return [Hash] Summary with key skill metadata
+      def summary
+        {
+          id: id,
+          name: name,
+          description: description,
+          version: version,
+          expertise_areas: expertise.size,
+          keywords: keywords,
+          providers: compatible_providers.empty? ? "all" : compatible_providers.join(", ")
+        }
+      end
+
+      # Get full details of this skill for display
+      #
+      # @return [Hash] Detailed skill information
+      def details
+        {
+          id: id,
+          name: name,
+          description: description,
+          version: version,
+          expertise: expertise,
+          keywords: keywords,
+          when_to_use: when_to_use,
+          when_not_to_use: when_not_to_use,
+          compatible_providers: compatible_providers,
+          source: source_path,
+          content_length: content.length
+        }
+      end
+
+      # Return string representation
+      #
+      # @return [String] Skill representation
+      def to_s
+        "Skill[#{id}](#{name} v#{version})"
+      end
+
+      # Return inspection string
+      #
+      # @return [String] Detailed inspection
+      def inspect
+        "#<Aidp::Skills::Skill id=#{id} name=\"#{name}\" version=#{version} " \
+          "source=#{source_path}>"
+      end
+
+      private
+
+      # Validate required fields
+      #
+      # @raise [Aidp::Errors::ValidationError] if validation fails
+      def validate!
+        raise Aidp::Errors::ValidationError, "Skill id is required" if id.nil? || id.strip.empty?
+        raise Aidp::Errors::ValidationError, "Skill name is required" if name.nil? || name.strip.empty?
+        raise Aidp::Errors::ValidationError, "Skill description is required" if description.nil? || description.strip.empty?
+        raise Aidp::Errors::ValidationError, "Skill version is required" if version.nil? || version.strip.empty?
+        raise Aidp::Errors::ValidationError, "Skill content is required" if content.nil? || content.strip.empty?
+        raise Aidp::Errors::ValidationError, "Skill source_path is required" if source_path.nil? || source_path.strip.empty?
+
+        # Validate version format (simple semantic version check)
+        unless version.match?(/^\d+\.\d+\.\d+/)
+          raise Aidp::Errors::ValidationError, "Skill version must be in format X.Y.Z (e.g., 1.0.0)"
+        end
+
+        # Validate id format (lowercase, alphanumeric, underscores only)
+        unless id.match?(/^[a-z0-9_]+$/)
+          raise Aidp::Errors::ValidationError, "Skill id must be lowercase alphanumeric with underscores only"
+        end
+      end
+    end
+  end
+end