x_aeon_agents 1.0.28

data/lib/x_aeon_agents/agents/readme_generator_agent.rb

@@ -0,0 +1,438 @@
+require 'commonmarker'
+require 'fileutils'
+
+module XAeonAgents
+  module Agents
+    # Agent responsible for writing the README.md file of a project.
+    class ReadmeGeneratorAgent < ComposableAgents::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        {
+          readme_file_path: {
+            description: 'The full path to the README file',
+            optional: true
+          },
+          gen_about: 'The option to generate the about/header section (name, description, badges, TOC)',
+          gen_quick_start: 'The option to generate the "Quick start" section',
+          gen_requirements: 'The option to generate the "Requirements" section',
+          gen_features: 'The option to generate the "Features" section',
+          gen_public_api: 'The option to generate the "Public API" section',
+          gen_documentation: 'The option to generate the "Documentation" section',
+          gen_how_it_works: 'The option to generate the "How it works" section',
+          gen_development: 'The option to generate the "Development" section',
+          gen_contributing: 'The option to generate the "Contributing" section',
+          gen_license: 'The option to generate the "License" section'
+        }
+      end
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      #
+      # @param readme_file_path [String] Path to the README file.
+      # @param gen_about [Boolean] Generate the about/header section (name, description, badges, TOC).
+      #   Setting this to false will keep the existing header untouched in the README while allowing
+      #   other sections to be updated.
+      # @param gen_quick_start [Boolean] Generate the "Quick start" section
+      # @param gen_requirements [Boolean] Generate the "Requirements" section
+      # @param gen_features [Boolean] Generate the "Features" section
+      # @param gen_public_api [Boolean] Generate the "Public API" section
+      # @param gen_documentation [Boolean] Generate the "Documentation" section
+      # @param gen_how_it_works [Boolean] Generate the "How it works" section
+      # @param gen_development [Boolean] Generate the "Development" section
+      # @param gen_contributing [Boolean] Generate the "Contributing" section
+      # @param gen_license [Boolean] Generate the "License" section
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run(
+        readme_file_path: File.expand_path('README.md'),
+        gen_about: true,
+        gen_quick_start: true,
+        gen_requirements: true,
+        gen_features: true,
+        gen_public_api: true,
+        gen_documentation: true,
+        gen_how_it_works: true,
+        gen_development: true,
+        gen_contributing: true,
+        gen_license: true
+      )
+        # Each section of the README has a dedicated agent who generates its content in an artifact.
+        if gen_about
+          about_analyzer_agent = new_agent(Readme::AboutAnalyzerAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            about_analyzer_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's code, features and layout.
+              Devise the goal of this project, what problem it solves, and using which interface (CLI, library, web app...).
+              Create an artifact named `#{about_analyzer_agent.artifact_ref(:name)}` with the name of this project.
+              Create an artifact named `#{about_analyzer_agent.artifact_ref(:description)}` with a 1-line high-level description of this project
+                using Markdown format, compatible with Github flavor.
+              Create an artifact named `#{about_analyzer_agent.artifact_ref(:about)}` with an engaging high-level description/overview of this project
+                using Markdown format, compatible with Github flavor.
+              The description should be concise, in 1 small section and will serve as a the first paragraph of a README file.
+              The description is intended to be for end-users and should be simple and easy to understand.
+              Use emphasis, bullet points and small emojis to illustrate in a readable way the description.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_quick_start
+          quick_start_agent = new_agent(Readme::QuickStartAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            quick_start_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's installation and usage patterns.
+              Create an artifact named `#{quick_start_agent.artifact_ref(:quick_start)}` with quick installation and usage instructions
+                using Markdown format, compatible with Github flavor.
+              These instructions should cover the installation and basic usage of this project, with simple examples.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_requirements
+          requirements_agent = new_agent(Readme::RequirementsAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            requirements_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's dependencies, runtime environment, and prerequisites.
+              Create an artifact named `#{requirements_agent.artifact_ref(:requirements)}` listing all prerequisites needed to use or run the project
+                using Markdown format, compatible with Github flavor.
+              Those prerequisites should be given as a short list of technical points (for example OS, languages and versions, needed libraries...).
+              Only list prerequisites that are needed by the users of the project, and not provided by the installation steps.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_features
+          features_agent = new_agent(Readme::FeaturesAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            features_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's codebase and capabilities to identify all key features.
+              Create an artifact named `#{features_agent.artifact_ref(:features)}` listing the main features of the project
+                using Markdown format, compatible with Github flavor.
+              Those features should be summarized in a simple paragraph.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_public_api
+          public_api_agent = new_agent(Readme::PublicApiAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            public_api_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's codebase to identify all public APIs, classes, methods, and interfaces exposed to users.
+              Create an artifact named `#{public_api_agent.artifact_ref(:public_api)}` documenting the public API surface
+                using Markdown format, compatible with Github flavor.
+              The public API description should only contain public entry points of the project. Those entry points can be:
+              - Executables from the `bin` directory, if any.
+              - Any public method (part of yard's group `Public API` only).
+              Try to document 1 simple usecase with an example for each public API you find, without getting into details.
+              Provide links to more complete documentation next to the usecase example so that users can refer to more details about this specific public API.
+              Links can be (by order of preference):
+              - Links to the RubyDoc.info documentation for a Ruby public method (for example `https://www.rubydoc.info/gems/x-aeon_agents/XAeonAgents/Agents#config-class_method`).
+              - Links to the Github pages (for example `https://github.com/Muriel-Salvan/x_aeon_agents/blob/main/bin/xaa`).
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_documentation
+          documentation_agent = new_agent(Readme::DocumentationAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            documentation_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Explore this project's documentation files and resources to identify all available documentation.
+              Create an artifact named `#{documentation_agent.artifact_ref(:documentation)}` providing links to documentation resources
+                using Markdown format, compatible with Github flavor.
+              Links can be:
+              - Link to the RubyDoc.info documentation for a Ruby public method (for example `https://www.rubydoc.info/gems/x_aeon_agents`).
+              - Link to the main Github page (for example `https://github.com/Muriel-Salvan/x_aeon_agents`).
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_how_it_works
+          how_it_works_agent = new_agent(Readme::HowItWorksAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            how_it_works_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's architecture, design patterns, and internal workings.
+              Create an artifact named `#{how_it_works_agent.artifact_ref(:how_it_works)}` explaining the internal architecture and working principles
+                using Markdown format, compatible with Github flavor.
+              This should be summarized as a small section, not an architecture document.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_development
+          development_agent = new_agent(Readme::DevelopmentAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            development_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's development setup, build system, testing framework, and development workflows.
+              Create an artifact named `#{development_agent.artifact_ref(:development)}` explaining how to set up a development environment to code for this project
+                using Markdown format, compatible with Github flavor.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_contributing
+          contributing_agent = new_agent(Readme::ContributingAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            contributing_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's CONTRIBUTING guidelines, issue templates, pull request templates, and any community guidelines.
+              Create an artifact named `#{contributing_agent.artifact_ref(:contributing)}` explaining how users can contribute to the project
+                using Markdown format, compatible with Github flavor.
+              This should be done in 1 paragraph showing how to install or setup test dependencies and how to run tests, as a whole or individually.
+              Use simple examples to illustrate it.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        if gen_license
+          license_agent = new_agent(Readme::LicenseAgent, **Config.agent_options['free_complex_planning'])
+          step_agent(
+            license_agent,
+            user_instructions: <<~EO_INSTRUCTIONS
+              Analyze this project's LICENSE file to identify the license type and terms.
+              Create an artifact named `#{license_agent.artifact_ref(:license)}` describing the project license
+                using Markdown format, compatible with Github flavor.
+              If there is already a LICENSE file in this project, just provide a link to this license file.
+            EO_INSTRUCTIONS
+          )
+        end
+
+        # Assemble README.md from all section artifacts
+        step(:assemble_readme) do
+          sections = File.exist?(readme_file_path) ? parse_sections(File.read(readme_file_path)) : []
+          header_content = nil
+
+          # We expect the first 2 sections to be of level 0 or 1, and they both correspond to the about top section.
+          # Treat them as a header if that's the case.
+          2.times do
+            if !sections.empty? && sections.first[:level] < 2
+              section = sections.shift
+              header_content = ([header_content] + [section[:body]]).compact.join("\n\n")
+            end
+          end
+
+          # Remove the eventual Table of contents section as we will always regenerate it.
+          sections.delete_if { |section| section[:title] == 'Table of contents' }
+
+          # Replace or insert sections in the order they are expected
+
+          if gen_about
+            header_content = <<~EO_HEADER.strip
+              <div align="center">
+
+              # #{@artifacts[:name]}
+
+              #{@artifacts[:description]}
+
+              #{build_badges.join("\n")}
+
+              </div>
+
+              #{ComposableAgents::Utils::Markdown.align_markdown_headers(@artifacts[:about], level: 3).strip}
+            EO_HEADER
+          end
+
+          ordered_sections = [
+            ['Quick start', :quick_start],
+            ['Requirements', :requirements],
+            ['Features', :features],
+            ['Public API', :public_api],
+            ['Documentation', :documentation],
+            ['How it works', :how_it_works],
+            ['Development', :development],
+            ['Contributing', :contributing],
+            ['License', :license]
+          ]
+          ordered_sections.each.with_index do |(section_title, art_name), idx_section|
+            next unless @artifacts[art_name]
+
+            content = <<~EO_CONTENT.strip
+              ## #{section_title}
+
+              #{ComposableAgents::Utils::Markdown.align_markdown_headers(strip_grouping_header(@artifacts[art_name]), level: 3).strip}
+            EO_CONTENT
+            # Find the section of this title if any
+            existing_idx = sections.index { |section| section[:title] == section_title }
+            if existing_idx
+              sections[existing_idx][:body] = content
+            else
+              # Look for the first previous section.
+              # The we insert our section just after.
+              found_previous_section_index = nil
+              previous_section_index = idx_section - 1
+              while found_previous_section_index.nil?
+                if previous_section_index == -1
+                  # We didn't find any previous section.
+                  # Insert it at the top.
+                  found_previous_section_index = -1
+                else
+                  previous_section_title = ordered_sections[previous_section_index][0]
+                  found_previous_section_index = sections.index { |section| section[:title] == previous_section_title }
+                end
+                previous_section_index -= 1
+              end
+              # Insert just after found_previous_section_index
+              sections.insert(
+                found_previous_section_index + 1,
+                {
+                  level: 2,
+                  title: section_title,
+                  body: content
+                }
+              )
+            end
+          end
+
+          sections_content = sections.map { |section| section[:body] }.join("\n\n").strip
+          File.write(
+            readme_file_path,
+            <<~EO_README
+              #{header_content}
+
+              ## Table of contents
+
+              #{generate_table_of_contents(sections_content).strip}
+
+              #{sections_content}
+            EO_README
+          )
+        end
+
+        puts "#{readme_file_path} has been generated successfully."
+
+        @artifacts
+      end
+
+      private
+
+      # Build the badges array for the README header.
+      #
+      # @return [Array<String>]
+      def build_badges
+        badges = []
+        if Helpers.github_repo
+          badges.push(
+            "[![Build](https://github.com/#{Helpers.github_repo}/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/#{Helpers.github_repo}/actions/workflows/continuous_integration.yml)",
+            "[![Test Coverage](https://img.shields.io/codecov/c/gh/#{Helpers.github_repo})](https://codecov.io/gh/#{Helpers.github_repo})",
+            "[![GitHub stars](https://img.shields.io/github/stars/#{Helpers.github_repo})](https://github.com/#{Helpers.github_repo}/stargazers)",
+            "[![License](https://img.shields.io/github/license/#{Helpers.github_repo})](LICENSE)"
+          )
+        end
+        if Helpers.gem_name
+          badges.push(
+            "[![Gem Version](https://img.shields.io/gem/v/#{Helpers.gem_name})](https://rubygems.org/gems/#{Helpers.gem_name})",
+            "[![Gem Total Downloads](https://img.shields.io/gem/dt/#{Helpers.gem_name})](https://rubygems.org/gems/#{Helpers.gem_name})"
+          )
+        end
+        badges
+      end
+
+      # Parse an existing README content into an array of section hashes using CommonMarker.
+      #
+      # Each section hash has:
+      #   :level - heading level (1 or 2, or 0 for the leading header block before any heading)
+      #   :title - heading text (nil for the leading header block)
+      #   :body  - raw markdown body (includes the heading line itself for level>=1 sections)
+      #
+      # @param readme_content [String] Full README markdown content
+      # @return [Array<Hash{Symbol => Object}>]
+      def parse_sections(readme_content)
+        sections = []
+        # Track (1-indexed) source line of the last heading we encountered
+        last_heading_line = nil
+        lines = readme_content.lines.map(&:chomp)
+        Commonmarker.parse(readme_content, options: { sourcepos_chars: true }).walk do |node|
+          next unless node.type == :heading && node.header_level <= 2
+
+          heading_line = node.source_position[:start_line] # 1-indexed
+          if last_heading_line
+            # Body is lines from last heading up to (not including) this heading
+            sections.last[:body] = lines[(last_heading_line - 1)...(heading_line - 1)].join("\n").strip
+          elsif heading_line > 1
+            # Capture the leading header (lines before the first heading)
+            sections << {
+              level: 0,
+              title: nil,
+              body: lines[0...(heading_line - 1)].join("\n").strip
+            }
+          end
+          text_node = node.each.find { |c| c.type == :text }
+          sections << {
+            level: node.header_level,
+            title: text_node ? text_node.string_content : '',
+            body: nil # placeholder, will be filled by the next heading
+          }
+          last_heading_line = heading_line
+        end
+        # Capture the body of the last section (from its heading to end of file)
+        if last_heading_line
+          sections.last[:body] = lines[(last_heading_line - 1)..].join("\n").strip
+        else
+          # No headings at all — entire content is one header block
+          sections << {
+            level: 0,
+            title: nil,
+            body: readme_content.strip
+          }
+        end
+        sections
+      end
+
+      # If the markdown content has exactly 1 heading at the smallest level present,
+      # remove it. This strips the "grouping" header that AI-generated sections
+      # sometimes produce (e.g. a single `#` or `##` wrapping the rest of the content).
+      #
+      # @param markdown [String] The markdown content to process.
+      # @return [String] The markdown content with the grouping header removed,
+      #   or the original if there are 0 or 2+ headings at the smallest level.
+      def strip_grouping_header(markdown)
+        # Collect all heading nodes with their levels
+        heading_nodes = []
+        min_level = nil
+        Commonmarker.parse(markdown).walk do |node|
+          next unless node.type == :heading
+
+          heading_nodes << node
+          min_level = node.header_level if min_level.nil? || node.header_level < min_level
+        end
+        # No headings at all — nothing to strip
+        return markdown if heading_nodes.empty? || min_level.nil?
+
+        # Find headings at the minimum level
+        min_level_nodes = heading_nodes.select { |node| node.header_level == min_level }
+        # Only strip when there is exactly 1 heading at the minimum level
+        return markdown unless min_level_nodes.size == 1
+
+        heading_node = min_level_nodes.first
+        start_line = heading_node.source_position[:start_line] # 1-indexed
+        # Only strip if it is on the top of the document
+        return markdown unless start_line == 1
+
+        end_line = heading_node.source_position[:end_line] # 1-indexed
+        lines = markdown.lines.map(&:chomp)
+        # Remove the heading lines (only the heading, not trailing blank lines that belong to content)
+        (lines[0...(start_line - 1)] + lines[end_line..]).join("\n").strip
+      end
+
+      # Generate a Table of Contents (String) from a Markdown document string.
+      #
+      # @param markdown [String] The full Markdown document content.
+      # @return [String] The generated Table of Contents as a Markdown list.
+      def generate_table_of_contents(markdown)
+        temp_file = "#{@session_dir}/tmp/content_to_be_toced.md"
+        FileUtils.mkdir_p File.dirname(temp_file)
+        File.write(temp_file, markdown)
+        log_debug 'Generating Table of Contents using doctoc...'
+        Helpers.run_cmd("npx doctoc --github --notitle --stdout #{temp_file}")[:stdout].gsub(/==================\n.+$/m, '').strip
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/review_resolver_agent.rb

@@ -0,0 +1,236 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for addressing Pull Request review comments directed at X-Aeon Agents
+    class ReviewResolverAgent < ComposableAgents::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        { pull_request_number: 'The Pull Request number to address comments for' }
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(name: 'ReviewResolver', **agent_params)
+      end
+
+      # Execute the agent to address Pull Request review comments
+      #
+      # @param pull_request_number [Integer, nil] The Pull Request number to address comments for.
+      #   When nil, the Pull Request is auto-detected from the current git branch.
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run(pull_request_number: nil)
+        raise 'Unable to find the Github repository' unless Helpers.github_repo
+
+        pull_request_number = resolve_pull_request_number(pull_request_number)
+
+        # Gather comments is always executed (never cached) so that new comments are detected on
+        # every run, even when resuming a session where development/replies are cached.
+        @artifacts[:conversations] = gather_comments(pull_request_number)
+
+        if @artifacts[:conversations].empty?
+          log_debug "No PR reviews conversations found that need X-Aeon Agents input for PR ##{pull_request_number}"
+        else
+          log_debug "Found #{@artifacts[:conversations].size} PR reviews conversations that need X-Aeon Agents input for PR ##{pull_request_number}"
+          @artifacts[:open_comments_to_agents] = @artifacts[:conversations].map do |conversation|
+            conversation.select { |comment| comment['need_ai_reply'] }
+          end.flatten(1)
+          log_debug "Found #{@artifacts[:open_comments_to_agents].size} PR review comments that need X-Aeon Agents to reply for PR ##{pull_request_number}"
+
+          step(:extract_requirements) do
+            pr = Helpers.github.pull_request(Helpers.github_repo, pull_request_number)
+            feedback_analyst_agent = new_agent(FeedbackAnalystAgent, **Config.agent_options['free_complex_planning'])
+            step_agent(
+              feedback_analyst_agent,
+              pr_description: <<~EO_DESCRIPTION.strip,
+                # #{pr.title}
+
+                #{ComposableAgents::Utils::Markdown.align_markdown_headers(pr.body, level: 2)}
+              EO_DESCRIPTION
+              pr_files_diffs: Helpers.git.diff("#{pr.base.sha}...#{pr.head.sha}").to_s,
+              user_instructions: {
+                ordered_list: [
+                  <<~EO_INSTRUCTION,
+                    Read the `#{feedback_analyst_agent.artifact_ref(:description)}` artifact to understand the purpose of this Pull Request
+
+                    - This gives you context on what is the purpose of this Pull Request.
+                  EO_INSTRUCTION
+                  <<~EO_INSTRUCTION,
+                    Read the `#{feedback_analyst_agent.artifact_ref(:pr_files_diffs)}` artifact to understand all changes made by this Pull Request
+
+                    - This gives you context on how has this Pull Request been implemented.
+                  EO_INSTRUCTION
+                  <<~EO_INSTRUCTION,
+                    Read the `#{feedback_analyst_agent.artifact_ref(:conversations)}` artifact to understand the full context of the PR conversations
+
+                    - This gives you context on the discussions around this Pull Request.
+                  EO_INSTRUCTION
+                  <<~EO_INSTRUCTION,
+                    Read the `#{feedback_analyst_agent.artifact_ref(:open_comments_to_agents)}` artifact to focus on agent-directed comments
+
+                    - You must devise requirements that will address those exact comments.
+                  EO_INSTRUCTION
+                  <<~EO_INSTRUCTION,
+                    Analyze agent-directed comments to identify specific requirements or tasks that need implementation
+                  EO_INSTRUCTION
+                  <<~EO_INSTRUCTION
+                    Extract clear, actionable requirements from the comments in an artifact named `#{feedback_analyst_agent.artifact_ref(:requirements)}`
+
+                    - If no implementation is required (e.g., comments are just questions), output "No requirements"
+                  EO_INSTRUCTION
+                ]
+              }
+            )
+            @artifacts[:requirements] = 'No requirements' if @artifacts[:requirements].strip.downcase == 'no requirements'
+          end
+
+          if @artifacts[:requirements] == 'No requirements'
+            @artifacts[:plan] = 'No implementation plan'
+            @artifacts[:files_diffs] = 'No changes'
+          else
+            step_agent(new_agent(DeveloperAgent, commit: true, pull_request: true))
+          end
+
+          @artifacts[:open_comments_to_agents].each.with_index do |comment, comment_idx|
+            step(:"reply_to_comment_#{comment_idx}") do
+              review_responder_agent = new_agent(ReviewResponderAgent, **Config.agent_options['free_complex_planning'])
+              step_agent(
+                review_responder_agent,
+                open_comment_for_reply: comment,
+                user_instructions: {
+                  ordered_list: [
+                    <<~EO_INSTRUCTION,
+                      Read the `#{review_responder_agent.artifact_ref(:conversations)}` artifact to understand the full context of the PR conversations
+
+                      - This gives you context on the discussions around this Pull Request.
+                    EO_INSTRUCTION
+                    <<~EO_INSTRUCTION,
+                      Read the `#{review_responder_agent.artifact_ref(:requirements)}` artifact to understand what was implemented
+
+                      - This gives you context on what has been implemented by other agents.
+                    EO_INSTRUCTION
+                    <<~EO_INSTRUCTION,
+                      Read the `#{review_responder_agent.artifact_ref(:plan)}` artifact to understand the implementation approach
+
+                      - This gives you context on how other agents implemented the requirements.
+                    EO_INSTRUCTION
+                    <<~EO_INSTRUCTION,
+                      Read the `#{review_responder_agent.artifact_ref(:files_diffs)}` artifact to understand the specific code changes made
+
+                      - This gives you context on what files have been modified.
+                    EO_INSTRUCTION
+                    <<~EO_INSTRUCTION,
+                      Read the `#{review_responder_agent.artifact_ref(:open_comment_for_reply)}` artifact to understand the specific comment to respond to
+
+                      - This is the EXACT comment that you should reply to.
+                    EO_INSTRUCTION
+                    <<~EO_INSTRUCTION
+                      Generate a professional, helpful reply that addresses the comment appropriately, in the artifact named `#{review_responder_agent.artifact_ref(:reply)}`
+
+                      - If requirements were implemented, explain what was done and how it addresses the comment.
+                      - If no requirements existed, provide a helpful response explaining the situation.
+                    EO_INSTRUCTION
+                  ]
+                }
+              )
+              full_reply = "[X-Aeon Agent #{review_responder_agent.full_name}] - #{@artifacts[:reply]}"
+              @artifacts[:replies] ||= []
+              @artifacts[:replies] << { 'comment_id' => comment['comment_id'], 'reply' => full_reply }
+              Helpers.github.create_pull_request_comment_reply(Helpers.github_repo, pull_request_number, full_reply, comment['comment_id'])
+            end
+          end
+        end
+
+        @artifacts
+      end
+
+      private
+
+      # Resolve the Pull Request number to process.
+      # When no number is given, auto-detects the Pull Request matching the current git branch.
+      #
+      # @param pull_request_number [Integer, nil] The explicit Pull Request number, or nil to auto-detect
+      # @return [Integer] The resolved Pull Request number
+      def resolve_pull_request_number(pull_request_number)
+        return pull_request_number if pull_request_number
+
+        current_branch = Helpers.git.current_branch
+        # TODO: Move this logic in a helper that is also used by PullRequestCreatorAgent, and remove this method.
+        pr = Helpers.github.pull_requests(Helpers.github_repo).find { |candidate| candidate.head.ref == current_branch }
+        raise "Unable to find a Pull Request for the current branch #{current_branch}" unless pr
+
+        pr.number
+      end
+
+      # Fetch and filter the Pull Request review comments that need an X-Aeon Agent reply.
+      #
+      # @param pull_request_number [Integer] The Pull Request number to address comments for
+      # @return [Array<Array<Hash{String => Object}>>] List of conversations (each a list of comments)
+      def gather_comments(pull_request_number)
+        owner, repo = Helpers.github_repo.split('/')
+        pr_json = Helpers.github.post(
+          '/graphql',
+          JSON.dump(
+            {
+              query: File.read("#{__dir__}/gh_comments.gql"),
+              variables: {
+                owner:,
+                repo:,
+                pr: pull_request_number
+              }
+            }
+          )
+        )[:data][:repository][:pullRequest]
+        pr_json[:reviewThreads][:edges].select do |review_thread|
+          !review_thread[:node][:isResolved] &&
+            review_thread[:node][:comments][:nodes].any? do |comment|
+              comment[:needAIReply] = comment[:body].start_with?('/agent') &&
+                comment_replies(review_thread[:node][:comments][:nodes], comment).none? { |reply| reply[:body].match(/^\[X-Aeon Agent [^\]]+?\]/) }
+              comment[:needAIReply]
+            end
+        end.map do |review_thread|
+          review_thread[:node][:comments][:nodes].sort_by { |comment| comment[:createdAt] }.map do |comment|
+            {
+              'comment_id' => comment[:databaseId],
+              'created_at' => comment[:createdAt],
+              'reply_to_comment_id' => comment.dig(:replyTo, :databaseId),
+              'author' => comment[:author][:login],
+              'body' => comment[:body],
+              'path' => comment[:path],
+              'need_ai_reply' => comment[:needAIReply]
+            }
+          end
+        end
+      end
+
+      # Get all the replies of a given comment.
+      # Replies are:
+      # - all the comments that have this comment as a direct reply,
+      # - plus the next (closest next creation date) comment that replied to the parent of the given comment,
+      # - plus all the replies of those replies (recursively).
+      #
+      # @param comments [Array<Hash>] All comments in the thread
+      # @param comment [Hash] The comment to check for replies
+      # @return [Array<Hash>] List of all the replies
+      def comment_replies(comments, comment)
+        comment_id = comment[:databaseId]
+        # All direct replies
+        replies = comments.select { |c| c.dig(:replyTo, :databaseId) == comment_id }
+        # All replies to the same parent, sorted by creation date
+        parent_comment_id = comment.dig(:replyTo, :databaseId)
+        unless parent_comment_id.nil?
+          created_at = Time.parse(comment[:createdAt])
+          next_parent_reply = comments
+            .select { |c| c.dig(:replyTo, :databaseId) == parent_comment_id && Time.parse(c[:createdAt]) > created_at }
+            .min_by { |c| c[:created_at] }
+          replies << next_parent_reply unless next_parent_reply.nil?
+        end
+        replies.map { |c| [c] + comment_replies(comments, c) }.flatten(1)
+      end
+    end
+  end
+end