aidp 0.15.2 → 0.16.0

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.2"
+  VERSION = "0.16.0"
 end

data/lib/aidp/watch/build_processor.rb

@@ -6,6 +6,7 @@ require "time"
 require_relative "../message_display"
 require_relative "../execute/prompt_manager"
 require_relative "../harness/runner"
+require_relative "../worktree"
 
 module Aidp
   module Watch
@@ -17,10 +18,11 @@ module Aidp
       BUILD_LABEL = "aidp-build"
       IMPLEMENTATION_STEP = "16_IMPLEMENTATION"
 
-      def initialize(repository_client:, state_store:, project_dir: Dir.pwd)
+      def initialize(repository_client:, state_store:, project_dir: Dir.pwd, use_workstreams: true)
         @repository_client = repository_client
         @state_store = state_store
         @project_dir = project_dir
+        @use_workstreams = use_workstreams
       end
 
       def process(issue)
@@ -30,27 +32,36 @@ module Aidp
         plan_data = ensure_plan_data(number)
         return unless plan_data
 
+        slug = workstream_slug_for(issue)
         branch_name = branch_name_for(issue)
-        @state_store.record_build_status(number, status: "running", details: {branch: branch_name, started_at: Time.now.utc.iso8601})
+        @state_store.record_build_status(number, status: "running", details: {branch: branch_name, workstream: slug, started_at: Time.now.utc.iso8601})
 
         ensure_git_repo!
         base_branch = detect_base_branch
 
-        checkout_branch(base_branch, branch_name)
+        if @use_workstreams
+          workstream_path = setup_workstream(slug: slug, branch_name: branch_name, base_branch: base_branch)
+          working_dir = workstream_path
+        else
+          checkout_branch(base_branch, branch_name)
+          working_dir = @project_dir
+        end
+
         prompt_content = build_prompt(issue: issue, plan_data: plan_data)
-        write_prompt(prompt_content)
+        write_prompt(prompt_content, working_dir: working_dir)
 
         user_input = build_user_input(issue: issue, plan_data: plan_data)
-        result = run_harness(user_input: user_input)
+        result = run_harness(user_input: user_input, working_dir: working_dir)
 
         if result[:status] == "completed"
-          handle_success(issue: issue, branch_name: branch_name, base_branch: base_branch, plan_data: plan_data)
+          handle_success(issue: issue, slug: slug, branch_name: branch_name, base_branch: base_branch, plan_data: plan_data, working_dir: working_dir)
         else
-          handle_failure(issue: issue, result: result)
+          handle_failure(issue: issue, slug: slug, result: result)
         end
       rescue => e
         display_message("❌ Implementation failed: #{e.message}", type: :error)
         @state_store.record_build_status(issue[:number], status: "failed", details: {error: e.message})
+        cleanup_workstream(slug) if @use_workstreams && slug
         raise
       end
 
@@ -96,9 +107,56 @@ module Aidp
         display_message("🌿 Checked out #{branch_name}", type: :info)
       end
 
-      def branch_name_for(issue)
+      def workstream_slug_for(issue)
         slug = issue[:title].to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")
-        "aidp/issue-#{issue[:number]}-#{slug[0, 32]}"
+        "issue-#{issue[:number]}-#{slug[0, 32]}"
+      end
+
+      def branch_name_for(issue)
+        "aidp/#{workstream_slug_for(issue)}"
+      end
+
+      def setup_workstream(slug:, branch_name:, base_branch:)
+        # Check if workstream already exists
+        existing = Aidp::Worktree.info(slug: slug, project_dir: @project_dir)
+        if existing
+          display_message("🔄 Reusing existing workstream: #{slug}", type: :info)
+          Dir.chdir(existing[:path]) do
+            run_git(["checkout", existing[:branch]])
+            run_git(%w[pull --ff-only], allow_failure: true)
+          end
+          return existing[:path]
+        end
+
+        # Create new workstream
+        display_message("🌿 Creating workstream: #{slug}", type: :info)
+        result = Aidp::Worktree.create(
+          slug: slug,
+          project_dir: @project_dir,
+          branch: branch_name,
+          base_branch: base_branch
+        )
+
+        if result[:success]
+          display_message("✅ Workstream created at #{result[:path]}", type: :success)
+          result[:path]
+        else
+          raise "Failed to create workstream: #{result[:message]}"
+        end
+      end
+
+      def cleanup_workstream(slug)
+        return unless slug
+
+        display_message("🧹 Cleaning up workstream: #{slug}", type: :info)
+        result = Aidp::Worktree.remove(slug: slug, project_dir: @project_dir, force: true)
+        if result[:success]
+          display_message("✅ Workstream removed", type: :success)
+        else
+          display_message("⚠️  Failed to remove workstream: #{result[:message]}", type: :warn)
+        end
+      rescue => e
+        display_message("⚠️  Error cleaning up workstream: #{e.message}", type: :warn)
       end
 
       def build_prompt(issue:, plan_data:)
@@ -141,8 +199,8 @@ module Aidp
         "_Unable to parse comment thread._"
       end
 
-      def write_prompt(content)
-        prompt_manager = Aidp::Execute::PromptManager.new(@project_dir)
+      def write_prompt(content, working_dir: @project_dir)
+        prompt_manager = Aidp::Execute::PromptManager.new(working_dir)
         prompt_manager.write(content)
         display_message("📝 Wrote PROMPT.md with implementation contract", type: :info)
       end
@@ -156,23 +214,24 @@ module Aidp
         }.delete_if { |_k, v| v.nil? || v.empty? }
       end
 
-      def run_harness(user_input:)
+      def run_harness(user_input:, working_dir: @project_dir)
         options = {
           selected_steps: [IMPLEMENTATION_STEP],
           workflow_type: :watch_mode,
           user_input: user_input
         }
-        runner = Aidp::Harness::Runner.new(@project_dir, :execute, options)
+        runner = Aidp::Harness::Runner.new(working_dir, :execute, options)
         runner.run
       end
 
-      def handle_success(issue:, branch_name:, base_branch:, plan_data:)
-        stage_and_commit(issue)
-        pr_url = create_pull_request(issue: issue, branch_name: branch_name, base_branch: base_branch)
+      def handle_success(issue:, slug:, branch_name:, base_branch:, plan_data:, working_dir:)
+        stage_and_commit(issue, working_dir: working_dir)
+        pr_url = create_pull_request(issue: issue, branch_name: branch_name, base_branch: base_branch, working_dir: working_dir)
 
+        workstream_note = @use_workstreams ? "\n- Workstream: `#{slug}`" : ""
         comment = <<~COMMENT
           ✅ Implementation complete for ##{issue[:number]}.
-          - Branch: `#{branch_name}`
+          - Branch: `#{branch_name}`#{workstream_note}
           - Pull Request: #{pr_url}
 
           Summary:
@@ -183,32 +242,38 @@ module Aidp
         @state_store.record_build_status(
           issue[:number],
           status: "completed",
-          details: {branch: branch_name, pr_url: pr_url}
+          details: {branch: branch_name, workstream: slug, pr_url: pr_url}
         )
         display_message("🎉 Posted completion comment for issue ##{issue[:number]}", type: :success)
+
+        # Keep workstream for review - don't auto-cleanup on success
+        if @use_workstreams
+          display_message("ℹ️  Workstream #{slug} preserved for review. Remove with: aidp ws rm #{slug}", type: :muted)
+        end
       end
 
-      def handle_failure(issue:, result:)
+      def handle_failure(issue:, slug:, result:)
         message = result[:message] || "Unknown failure"
+        workstream_note = @use_workstreams ? " The workstream `#{slug}` has been left intact for debugging." : " The branch has been left intact for debugging."
         comment = <<~COMMENT
           ❌ Implementation attempt for ##{issue[:number]} failed.
 
           Status: #{result[:status]}
           Details: #{message}
 
-          Please review the repository for partial changes. The branch has been left intact for debugging.
+          Please review the repository for partial changes.#{workstream_note}
         COMMENT
         @repository_client.post_comment(issue[:number], comment)
         @state_store.record_build_status(
           issue[:number],
           status: "failed",
-          details: {message: message}
+          details: {message: message, workstream: slug}
         )
         display_message("⚠️  Build failure recorded for issue ##{issue[:number]}", type: :warn)
       end
 
-      def stage_and_commit(issue)
-        Dir.chdir(@project_dir) do
+      def stage_and_commit(issue, working_dir: @project_dir)
+        Dir.chdir(working_dir) do
           status_output = run_git(%w[status --porcelain])
           if status_output.strip.empty?
             display_message("ℹ️  No file changes detected after work loop.", type: :muted)
@@ -222,9 +287,9 @@ module Aidp
         end
       end
 
-      def create_pull_request(issue:, branch_name:, base_branch:)
+      def create_pull_request(issue:, branch_name:, base_branch:, working_dir: @project_dir)
         title = "aidp: Resolve ##{issue[:number]} - #{issue[:title]}"
-        test_summary = gather_test_summary
+        test_summary = gather_test_summary(working_dir: working_dir)
         body = <<~BODY
           ## Summary
           - Automated resolution for ##{issue[:number]}
@@ -244,8 +309,8 @@ module Aidp
         extract_pr_url(output)
       end
 
-      def gather_test_summary
-        Dir.chdir(@project_dir) do
+      def gather_test_summary(working_dir: @project_dir)
+        Dir.chdir(working_dir) do
           log_path = File.join(".aidp", "logs", "test_runner.log")
           return "- Fix-forward harness executed; refer to #{log_path}" unless File.exist?(log_path)
 
@@ -257,7 +322,7 @@ module Aidp
           end
         end
       rescue
-        "- Fix-forward harness executed successfully."
+        "- Fix-forward harness extracted successfully."
       end
 
       def extract_pr_url(output)

data/lib/aidp/watch/runner.rb

@@ -18,7 +18,7 @@ module Aidp
 
       DEFAULT_INTERVAL = 30
 
-      def initialize(issues_url:, interval: DEFAULT_INTERVAL, provider_name: nil, gh_available: nil, project_dir: Dir.pwd, once: false, prompt: TTY::Prompt.new)
+      def initialize(issues_url:, interval: DEFAULT_INTERVAL, provider_name: nil, gh_available: nil, project_dir: Dir.pwd, once: false, use_workstreams: true, prompt: TTY::Prompt.new)
         @prompt = prompt
         @interval = interval
         @once = once
@@ -35,7 +35,8 @@ module Aidp
         @build_processor = BuildProcessor.new(
           repository_client: @repository_client,
           state_store: @state_store,
-          project_dir: project_dir
+          project_dir: project_dir,
+          use_workstreams: use_workstreams
         )
       end