aidp 0.15.1 → 0.16.0

data/lib/aidp/skills/loader.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../errors"
+
+module Aidp
+  module Skills
+    # Loads skills from SKILL.md files with YAML frontmatter
+    #
+    # Parses skill files in the format:
+    #   ---
+    #   id: skill_id
+    #   name: Skill Name
+    #   ...
+    #   ---
+    #   # Skill content in markdown
+    #
+    # @example Loading a skill
+    #   skill = Loader.load_from_file("/path/to/SKILL.md")
+    #
+    # @example Loading a skill with provider filtering
+    #   skill = Loader.load_from_file("/path/to/SKILL.md", provider: "anthropic")
+    class Loader
+      # Load a skill from a file path
+      #
+      # @param file_path [String] Path to SKILL.md file
+      # @param provider [String, nil] Optional provider name for compatibility check
+      # @return [Skill, nil] Loaded skill or nil if incompatible with provider
+      # @raise [Aidp::Errors::ValidationError] if file format is invalid
+      def self.load_from_file(file_path, provider: nil)
+        Aidp.log_debug("skills", "Loading skill from file", file: file_path, provider: provider)
+
+        unless File.exist?(file_path)
+          raise Aidp::Errors::ValidationError, "Skill file not found: #{file_path}"
+        end
+
+        content = File.read(file_path)
+        load_from_string(content, source_path: file_path, provider: provider)
+      end
+
+      # Load a skill from a string
+      #
+      # @param content [String] SKILL.md file content
+      # @param source_path [String] Source file path for reference
+      # @param provider [String, nil] Optional provider name for compatibility check
+      # @return [Skill, nil] Loaded skill or nil if incompatible with provider
+      # @raise [Aidp::Errors::ValidationError] if format is invalid
+      def self.load_from_string(content, source_path:, provider: nil)
+        metadata, markdown = parse_frontmatter(content, source_path: source_path)
+
+        skill = Skill.new(
+          id: metadata["id"],
+          name: metadata["name"],
+          description: metadata["description"],
+          version: metadata["version"],
+          expertise: metadata["expertise"] || [],
+          keywords: metadata["keywords"] || [],
+          when_to_use: metadata["when_to_use"] || [],
+          when_not_to_use: metadata["when_not_to_use"] || [],
+          compatible_providers: metadata["compatible_providers"] || [],
+          content: markdown,
+          source_path: source_path
+        )
+
+        # Filter by provider compatibility if specified
+        if provider && !skill.compatible_with?(provider)
+          Aidp.log_debug(
+            "skills",
+            "Skipping incompatible skill",
+            skill_id: skill.id,
+            provider: provider,
+            compatible: skill.compatible_providers
+          )
+          return nil
+        end
+
+        Aidp.log_debug(
+          "skills",
+          "Loaded skill",
+          skill_id: skill.id,
+          version: skill.version,
+          source: source_path
+        )
+
+        skill
+      rescue Aidp::Errors::ValidationError => e
+        Aidp.log_error("skills", "Skill validation failed", error: e.message, file: source_path)
+        raise
+      end
+
+      # Load all skills from a directory
+      #
+      # @param directory [String] Path to directory containing skill subdirectories
+      # @param provider [String, nil] Optional provider name for compatibility check
+      # @return [Array<Skill>] Array of loaded skills (excludes incompatible)
+      def self.load_from_directory(directory, provider: nil)
+        Aidp.log_debug("skills", "Loading skills from directory", directory: directory, provider: provider)
+
+        unless Dir.exist?(directory)
+          Aidp.log_warn("skills", "Skills directory not found", directory: directory)
+          return []
+        end
+
+        skills = []
+        skill_dirs = Dir.glob(File.join(directory, "*")).select { |path| File.directory?(path) }
+
+        skill_dirs.each do |skill_dir|
+          skill_file = File.join(skill_dir, "SKILL.md")
+          next unless File.exist?(skill_file)
+
+          begin
+            skill = load_from_file(skill_file, provider: provider)
+            skills << skill if skill # nil if incompatible with provider
+          rescue Aidp::Errors::ValidationError => e
+            Aidp.log_warn(
+              "skills",
+              "Failed to load skill",
+              file: skill_file,
+              error: e.message
+            )
+            # Continue loading other skills even if one fails
+          end
+        end
+
+        Aidp.log_info(
+          "skills",
+          "Loaded skills from directory",
+          directory: directory,
+          count: skills.size
+        )
+
+        skills
+      end
+
+      # Parse YAML frontmatter from content
+      #
+      # @param content [String] File content with frontmatter
+      # @param source_path [String] Source path for error messages
+      # @return [Array(Hash, String)] Tuple of [metadata, markdown_content]
+      # @raise [Aidp::Errors::ValidationError] if frontmatter is missing or invalid
+      def self.parse_frontmatter(content, source_path:)
+        lines = content.lines
+
+        unless lines.first&.strip == "---"
+          raise Aidp::Errors::ValidationError,
+            "Invalid SKILL.md format: missing YAML frontmatter in #{source_path}"
+        end
+
+        frontmatter_lines = []
+        body_start_index = nil
+
+        lines[1..].each_with_index do |line, index|
+          if line.strip == "---"
+            body_start_index = index + 2
+            break
+          end
+
+          frontmatter_lines << line
+        end
+
+        unless body_start_index
+          raise Aidp::Errors::ValidationError,
+            "Invalid SKILL.md format: missing closing frontmatter delimiter in #{source_path}"
+        end
+
+        markdown_content = lines[body_start_index..]&.join.to_s.strip
+        frontmatter_yaml = frontmatter_lines.join
+
+        begin
+          metadata = YAML.safe_load(frontmatter_yaml, permitted_classes: [Symbol])
+        rescue Psych::SyntaxError => e
+          raise Aidp::Errors::ValidationError,
+            "Invalid YAML frontmatter in #{source_path}: #{e.message}"
+        end
+
+        unless metadata.is_a?(Hash)
+          raise Aidp::Errors::ValidationError,
+            "YAML frontmatter must be a hash in #{source_path}"
+        end
+
+        validate_required_fields(metadata, source_path: source_path)
+
+        [metadata, markdown_content]
+      end
+
+      # Validate required frontmatter fields
+      #
+      # @param metadata [Hash] Parsed YAML metadata
+      # @param source_path [String] Source path for error messages
+      # @raise [Aidp::Errors::ValidationError] if required fields are missing
+      def self.validate_required_fields(metadata, source_path:)
+        required_fields = %w[id name description version]
+
+        required_fields.each do |field|
+          next if metadata[field] && !metadata[field].to_s.strip.empty?
+
+          raise Aidp::Errors::ValidationError,
+            "Missing required field '#{field}' in #{source_path}"
+        end
+      end
+
+      private_class_method :parse_frontmatter, :validate_required_fields
+    end
+  end
+end

data/lib/aidp/skills/registry.rb

@@ -0,0 +1,220 @@
+# 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. Built-in skills directory (project_root/skills/)
+    # 2. Custom skills directory (.aidp/skills/)
+    #
+    # Custom skills with matching IDs override built-in 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. Built-in skills (project_root/skills/)
+      # 2. Custom skills (.aidp/skills/) - override built-in
+      #
+      # @return [Integer] Number of skills loaded
+      def load_skills
+        Aidp.log_debug("skills", "Loading skills", project_dir: project_dir, provider: provider)
+
+        @skills = {}
+
+        # Load built-in skills first
+        builtin_skills = load_from_path(builtin_skills_path)
+        builtin_skills.each { |skill| register_skill(skill, source: :builtin) }
+
+        # Load custom skills (override built-in if IDs match)
+        custom_skills = load_from_path(custom_skills_path)
+        custom_skills.each { |skill| register_skill(skill, source: :custom) }
+
+        @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 :builtin and :custom arrays
+      def by_source
+        load_skills unless loaded?
+
+        {
+          builtin: @skills.values.select { |s| builtin_skill?(s) }.map(&:id),
+          custom: @skills.values.select { |s| custom_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 built-in skills path
+      #
+      # @return [String] Path to built-in skills directory
+      def builtin_skills_path
+        File.join(project_dir, "skills")
+      end
+
+      # Get custom skills path
+      #
+      # @return [String] Path to custom skills directory
+      def custom_skills_path
+        File.join(project_dir, ".aidp", "skills")
+      end
+
+      # Check if skill is from built-in directory
+      #
+      # @param skill [Skill] Skill to check
+      # @return [Boolean] True if built-in
+      def builtin_skill?(skill)
+        skill.source_path.start_with?(builtin_skills_path)
+      end
+
+      # Check if skill is from custom directory
+      #
+      # @param skill [Skill] Skill to check
+      # @return [Boolean] True if custom
+      def custom_skill?(skill)
+        skill.source_path.start_with?(custom_skills_path)
+      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

data/lib/aidp/skills.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "skills/skill"
+require_relative "skills/loader"
+require_relative "skills/registry"
+require_relative "skills/composer"
+
+module Aidp
+  # Skills subsystem for managing agent personas and capabilities
+  #
+  # Skills define WHO the agent is (persona) and WHAT capabilities they have.
+  # This is separate from templates/procedures which define WHEN and HOW
+  # to execute specific tasks.
+  #
+  # @example Loading and using skills
+  #   registry = Aidp::Skills::Registry.new(project_dir: Dir.pwd)
+  #   registry.load_skills
+  #
+  #   skill = registry.find("repository_analyst")
+  #   composer = Aidp::Skills::Composer.new
+  #   prompt = composer.compose(skill: skill, template: "Analyze the repo...")
+  #
+  # @example Creating a custom skill
+  #   # Create .aidp/skills/my_skill/SKILL.md with YAML frontmatter
+  #   # It will automatically override built-in skills with matching ID
+  module Skills
+    # Error raised when a skill is not found
+    class SkillNotFoundError < StandardError; end
+  end
+end

data/lib/aidp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aidp
-  VERSION = "0.15.1"
+  VERSION = "0.16.0"
 end