x_aeon_agents 2.7.0 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17ea16b7502ea3f029d3f10317a721b9ec8a2b55da0540749d4c7fd08e7e64f5
-  data.tar.gz: db8b870acc507c95aedeb5152fd5ca53edc3ab50003723497a5f68f297f9d3e3
+  metadata.gz: c02e664b325a3265a1397697d4730f7e95901db60483db4b3961851d7f92085d
+  data.tar.gz: 9ab1c4fbd0deb3313b55f82cd08dcf66f1bab8ff7c89f0f03a0c93e4d595fe0d
 SHA512:
-  metadata.gz: 3ffdf73d0e11122362a1e1191a60f9f8e3ec63def613de184f3a3b9986673b803c7cefe144873c77eb3b846656a668e43c7934a6f14ee8d96a2752bb0068c5ab
-  data.tar.gz: a657201ab6d6037e33db7b332ac470e84f67a9eeb038cf011543e208b9d898848ab76f3612a2543ebd51f8acc6fecbc2257b12ae064f5e395d8010ac2b5b116a
+  metadata.gz: 724e0edba6d234a943beb21d3be41f4407582d4f43efd97a1fceb096c353b8f52f34801facf88257872592bd7f23bd540c078d08745eee6d3b6066fe9ab5c934
+  data.tar.gz: 753db34710e6a78dd2f6c53fadd14fbc1086b684a1a451b8b2326375173008cafe5743d778d7ce36432f71d1c3ef726f53b2a3e16b5b7b643187982a704631a7

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [v2.7.1](https://github.com/Muriel-Salvan/x_aeon_agents/compare/v2.7.0...v2.7.1) (2026-11-12 15:59:52)
+
+## Global changes
+### Patches
+
+* [fix(agents): improve prompts, isolate artifacts per run and declare plan type](https://github.com/Muriel-Salvan/x_aeon_agents/commit/b7f9dab265b908514b646b61c6ebc5f74fd1d4b6)
+
+## Changes for agent_defaults
+### Patches
+
+* [fix(agents): improve prompts, isolate artifacts per run and declare plan type](https://github.com/Muriel-Salvan/x_aeon_agents/commit/b7f9dab265b908514b646b61c6ebc5f74fd1d4b6)
+
+## Changes for agents
+### Patches
+
+* [fix(agents): improve prompts, isolate artifacts per run and declare plan type](https://github.com/Muriel-Salvan/x_aeon_agents/commit/b7f9dab265b908514b646b61c6ebc5f74fd1d4b6)
+
 # [v2.7.0](https://github.com/Muriel-Salvan/x_aeon_agents/compare/v2.6.2...v2.7.0) (2026-11-12 13:45:26)
 
 ## Global changes

data/lib/x_aeon_agents/agent_defaults.rb

@@ -86,12 +86,24 @@ module XAeonAgents
             end
             @session_id = session_id || AgentDefaults.singleton_session_id
             @session_dir = "#{Config.data_dir}/sessions/#{@session_id}"
+            run_id = "#{@session_id}-#{kwargs[:name] || self.class.name.split('::').last}"
+            agent_kwargs = kwargs_from_config.merge(kwargs)
+            # TODO: Redesign how prompt rendering strategies are initialized with regard to the constructors and remove
+            #   this code smell.
+            # The prompt rendering strategy is included in the agent's singleton class by PromptDrivenAgent's
+            # constructor, which runs after the agent's own constructor: include it here first so that the agent's
+            # constructor and mixins can use the strategy's accessors (e.g. #artifact_ref) while being initialized.
+            singleton_class.include(agent_kwargs[:strategy]) if agent_kwargs[:strategy]
+            # File-based artifact strategies persist artifacts as files: give each agent run its own artifacts
+            # directory so that agents of the same session don't share artifact files.
+            self.artifacts_directory = "#{@session_dir}/composable_agents/runs/#{run_id}/artifacts" \
+              if respond_to?(:artifacts_directory=)
             super(
               *args,
               composable_agents_dir: "#{@session_dir}/composable_agents",
-              run_id: "#{@session_id}-#{kwargs[:name] || self.class.name.split('::').last}",
+              run_id:,
               logger: Config.logger,
-              **kwargs_from_config.merge(kwargs)
+              **agent_kwargs
             )
           end
 

data/lib/x_aeon_agents/agents/coder_agent.rb

@@ -9,7 +9,12 @@ module XAeonAgents
       #
       # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
       def input_artifacts_contracts
-        super.merge(plan: 'The implementation plan that you must follow')
+        super.merge(
+          plan: {
+            description: 'The implementation plan that you must follow',
+            type: :markdown
+          }
+        )
       end
 
       # Constructor

data/lib/x_aeon_agents/agents/developer_agent.rb

@@ -48,7 +48,7 @@ module XAeonAgents
         task(
           coder_agent,
           intent: 'Implement the requirements following the implementation plan',
-          user_instructions: "Follow all the steps of the implementation plan described in the artifact named `#{coder_agent.artifact_ref(:plan)}`."
+          user_instructions: "Read the implementation plan file `#{coder_agent.artifact_ref(:plan)}` and follow all its steps."
         )
         logger.info "Coder changes: #{Helpers.git.status_info.changed.keys.join(', ')}"
 
@@ -81,32 +81,38 @@ module XAeonAgents
                 user_instructions: {
                   ordered_list: [
                     <<~EO_STEP,
-                      Understand the initial requirements from the artifact named `#{tester_agent.artifact_ref(:requirements)}`
+                      Understand the initial requirements from the file `#{tester_agent.artifact_ref(:requirements)}`
 
                       - Understand those requirements and their intent.
                     EO_STEP
                     <<~EO_STEP,
-                      Understand the implementation plan from the artifact named `#{tester_agent.artifact_ref(:plan)}`
+                      Understand the implementation plan from the file `#{tester_agent.artifact_ref(:plan)}`
 
                       - Understand all the steps of the implementation plan.
                     EO_STEP
                     <<~EO_STEP,
-                      Understand the file changes from the artifact named `#{tester_agent.artifact_ref(:files_diffs)}`
+                      Understand the file changes from the file `#{tester_agent.artifact_ref(:files_diffs)}`
 
                       - Understand what was the intent of the developer implementing the requirements.
                     EO_STEP
                     <<~EO_STEP,
-                      Analyze the full output of unit tests run from the artifact named `#{tester_agent.artifact_ref(:tests_output)}`
+                      Read and analyze the full output of unit tests from the file `#{tester_agent.artifact_ref(:tests_output)}`
 
                       - Check every error reported in the output.
                     EO_STEP
                     'Fix any issue that unit tests are surfacing, while keeping the original intent of the requirements',
                     'Remember any inconsistency and modification you need to make to the implementation plan ' \
                       'so that your fixes are in-line with a better implementation plan',
-                    <<~EO_STEP
+                    <<~EO_STEP,
                       Make sure all tests are running without issue after your fixes
 
-                      - You can run tests again using the provided tests command from the artifact named `#{tester_agent.artifact_ref(:tests_cmd)}` to test your own fixes.
+                      - You can run tests again using the tests command given in the file `#{tester_agent.artifact_ref(:tests_cmd)}` to test your own fixes.
+                    EO_STEP
+                    <<~EO_STEP
+                      Write your modifications of the implementation plan, if any, to the file `#{tester_agent.artifact_ref(:plan_modifications)}`
+
+                      - Only write this file if your fixes required diverging from the implementation plan.
+                      - Do not write this file if the implementation plan did not change.
                     EO_STEP
                   ]
                 }
@@ -141,17 +147,17 @@ module XAeonAgents
           user_instructions: {
             ordered_list: [
               <<~EO_STEP,
-                Analyze the initial requirements from the artifact named `#{documenter_agent.artifact_ref(:requirements)}`
+                Read and analyze the initial requirements from the file `#{documenter_agent.artifact_ref(:requirements)}`
 
                 - Those give you information about the requirements you should be documenting.
               EO_STEP
               <<~EO_STEP,
-                Analyze all the steps of the implementation plan from the artifact named `#{documenter_agent.artifact_ref(:plan)}`
+                Read and analyze all the steps of the implementation plan from the file `#{documenter_agent.artifact_ref(:plan)}`
 
                 - Those give you every step that should have been followed for this new development.
               EO_STEP
               <<~EO_STEP,
-                Analyze the concrete changes from the artifact named `#{documenter_agent.artifact_ref(:files_diffs)}`
+                Read and analyze the concrete changes from the file `#{documenter_agent.artifact_ref(:files_diffs)}`
 
                 - Understand what was the intent of the developer implementing those requirements.
               EO_STEP
@@ -194,7 +200,7 @@ module XAeonAgents
                 Update the relevant documentation files
 
                 - Only perform this step if you think documentation is required.
-                - Use artifacts as the source of truth for understanding the changes to be documented.
+                - Use the artifact files as the source of truth for understanding the changes to be documented.
                 - Use the filesystem to locate where documentation should be updated.
                 - After exploring the filesystem, if relevant documentation files are found: update them.
 

data/lib/x_aeon_agents/agents/documenter_agent.rb

@@ -9,9 +9,19 @@ module XAeonAgents
       # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
       def input_artifacts_contracts
         super.merge(
-          requirements: 'The initial requirements',
-          plan: 'Implementation plan that introduced features and fixes to be documented',
-          files_diffs: 'Full list of files changes and differences that have been done to implement the initial requirements following the implementation plan'
+          requirements: {
+            description: 'The initial requirements',
+            type: :markdown
+          },
+          plan: {
+            description: 'Implementation plan that introduced features and fixes to be documented',
+            type: :markdown
+          },
+          files_diffs: {
+            description: 'Full list of files changes and differences that have been done to implement the initial ' \
+              'requirements following the implementation plan',
+            type: :text
+          }
         )
       end
 

data/lib/x_aeon_agents/agents/feedback_analyst_agent.rb

@@ -58,15 +58,16 @@ module XAeonAgents
             If you need more information, use one of the available tools or ask for clarification instead of making assumptions or lies.
             Do not indicate that you will perform an action without actually doing it.
           EO_INSTRUCTIONS
-          constraints: <<~EO_CONSTRAINTS,
-            - You are in read-only mode.
-            - Do NOT modify or write any file.
-            - Focus only on agent-directed comments (/agent) for requirement extraction.
-            - Output clear, actionable requirements or "No requirements" if none exist.
-            - #{Helpers.repository_access_constraint}
-          EO_CONSTRAINTS
           **agent_params
         )
+        self.constraints = <<~EO_CONSTRAINTS
+          - You are in read-only mode for the repository: do NOT modify any file of it.
+          - Focus only on agent-directed comments (/agent) for requirement extraction.
+          - Write the extracted requirements to the output artifact file given in this prompt.
+          - If no implementation is required, write exactly `No requirements` in this file.
+          - #{Helpers.repository_access_constraint}
+          - #{Helpers.artifacts_access_constraint(artifact_ref(:requirements))}
+        EO_CONSTRAINTS
       end
     end
   end

data/lib/x_aeon_agents/agents/plan_generator_agent.rb

@@ -8,7 +8,12 @@ module XAeonAgents
       #
       # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
       def input_artifacts_contracts
-        super.merge(requirements: 'The initial requirements for which you need to devise an implementation plan')
+        super.merge(
+          requirements: {
+            description: 'The initial requirements for which you need to devise an implementation plan',
+            type: :markdown
+          }
+        )
       end
 
       # Define output artifacts contracts
@@ -18,7 +23,7 @@ module XAeonAgents
         super.merge(
           plan: {
             description: 'The full and detailed implementation plan in Markdown format, ' \
-              "that should implement the requirements given by the artifact named `#{artifact_ref(:requirements)}`",
+              "that should implement the requirements given in the file `#{artifact_ref(:requirements)}`",
             type: :markdown
           }
         )
@@ -41,16 +46,15 @@ module XAeonAgents
             If you need more information, use one of the available tools or ask for clarification instead of making assumptions or lies.
             Do not indicate that you will perform an action without actually doing it.
           EO_INSTRUCTIONS
-          constraints: <<~EO_CONSTRAINTS,
-            - You are in read-only mode.
-            - Do NOT modify or write any file.
-            - You may only analyze and propose plans.
-            - Do NOT execute the plan yourself.
-            - #{Helpers.repository_access_constraint}
-            - Never create files (`ARTIFACT_*`, `/tmp/*`) to hold artifacts. Put the fenced ` ```json output_artifact=… ` block in your final message and end the turn with __no tool call__.
-          EO_CONSTRAINTS
           **agent_params
         )
+        self.constraints = <<~EO_CONSTRAINTS
+          - You are in read-only mode for the repository: do NOT modify any file of it.
+          - You may only analyze and propose plans.
+          - Do NOT execute the plan yourself.
+          - #{Helpers.repository_access_constraint}
+          - #{Helpers.artifacts_access_constraint(artifact_ref(:plan))}
+        EO_CONSTRAINTS
       end
     end
   end

data/lib/x_aeon_agents/agents/planner_agent.rb

@@ -18,7 +18,7 @@ module XAeonAgents
         {
           plan: {
             description: 'The full and detailed implementation plan in Markdown format, ' \
-              "that should implement the requirements given by the artifact named `#{plan_generator_agent.artifact_ref(:requirements)}`",
+              "that should implement the requirements given in the file `#{plan_generator_agent.artifact_ref(:requirements)}`",
             type: :markdown
           }
         }
@@ -39,10 +39,10 @@ module XAeonAgents
         super
         user_instructions = {
           ordered_list: [
-            "Read the initial requirements from the artifact named `#{plan_generator_agent.artifact_ref(:requirements)}`",
+            "Read the initial requirements from the file `#{plan_generator_agent.artifact_ref(:requirements)}`",
             'Analyze the project files',
-            "Create an artifact named `#{plan_generator_agent.artifact_ref(:plan)}` with a complete and detailed " \
-              'step-by-step implementation plan in Markdown format'
+            'Write a complete and detailed step-by-step implementation plan in Markdown format to the file ' \
+              "`#{plan_generator_agent.artifact_ref(:plan)}`"
           ]
         }
         loop.with_index do |plan_idx|
@@ -75,7 +75,7 @@ module XAeonAgents
           user_instructions = <<~EO_INSTRUCTIONS
             #{@artifacts[:user_prompt]}
 
-            Re-create the artifact named `#{plan_generator_agent.artifact_ref(:plan)}` with a revised implementation plan, taking the above user guidance into account.
+            Rewrite the file `#{plan_generator_agent.artifact_ref(:plan)}` with a revised implementation plan, taking the above user guidance into account.
           EO_INSTRUCTIONS
           user_instructions << <<~EO_INSTRUCTIONS if @artifacts[:diffs]
 

data/lib/x_aeon_agents/agents/readme/about_analyzer_agent.rb

@@ -34,7 +34,7 @@ module XAeonAgents
             name: 'About section generator',
             objective: <<~EO_OBJECTIVE,
               Analyze the project's code, features and layout to understand its purpose and interface.
-              Provide the following information:
+              Write the following information to the corresponding output artifact files:
               - The project's name (for example Rubygem's name, released package name, repository's name...).
               - The 1-line description of the project, using Markdown.
               - A high-level overview (about section) of the project in Markdown format, compatible with Github flavor.
@@ -46,16 +46,17 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifacts content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact contents: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact files, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact files: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:about), artifact_ref(:name), artifact_ref(:description))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/contributing_agent.rb

@@ -36,18 +36,19 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - Do not describe the technical setup or prequisites, as they are already covered by other sections.
-              - Do not cover how to develop in this project: it is already covered in other sections.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - Do not describe the technical setup or prequisites, as they are already covered by other sections.
+            - Do not cover how to develop in this project: it is already covered in other sections.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:contributing))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/development_agent.rb

@@ -43,18 +43,19 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - Do not cover the end-user main requirements and prerequisites: they are already covered in other sections.
-              - Do not cover the contribution workflow (pull requests, CI, issues...): this is already covered in other sections.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - Do not cover the end-user main requirements and prerequisites: they are already covered in other sections.
+            - Do not cover the contribution workflow (pull requests, CI, issues...): this is already covered in other sections.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:development))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/documentation_agent.rb

@@ -34,16 +34,17 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:documentation))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/features_agent.rb

@@ -36,16 +36,17 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:features))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/how_it_works_agent.rb

@@ -37,17 +37,18 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - Do not provide long paragraphs: focus on readability by splitting long paragraphs into several short ones.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - Do not provide long paragraphs: focus on readability by splitting long paragraphs into several short ones.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:how_it_works))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/license_agent.rb

@@ -34,16 +34,17 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:license))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/public_api_agent.rb

@@ -34,17 +34,18 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - Only document public API entry points: executables and library public methods belonging to yarn `Public API` group.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - Only document public API entry points: executables and library public methods belonging to yarn `Public API` group.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:public_api))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/quick_start_agent.rb

@@ -40,17 +40,18 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - This section is not meant for developers: don't describe how to develop, test, document, package or contribute to this project.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - This section is not meant for developers: don't describe how to develop, test, document, package or contribute to this project.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:quick_start))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme/requirements_agent.rb

@@ -34,16 +34,17 @@ module XAeonAgents
               If you need more information, use one of the available tools instead of making assumptions.
               Do not indicate that you will perform an action without actually doing it.
             EO_INSTRUCTIONS
-            constraints: <<~EO_CONSTRAINTS,
-              - The required output artifact content should only contain the required content, without additional header or title.
-              - Do not explain or describe the artifact content: only provide the content as required.
-              - Only focus on the specific scope of the required documentation required.
-                Other agents will generate other sections of the README.
-                Do not try to document other parts.
-              - #{Helpers.repository_access_constraint}
-            EO_CONSTRAINTS
             **agent_params
           )
+          self.constraints = <<~EO_CONSTRAINTS
+            - Write only the required content to the output artifact file, without any additional header or title.
+            - Do NOT write any explanation or description in the artifact file: write only the required content.
+            - Only focus on the specific scope of the required documentation required.
+              Other agents will generate other sections of the README.
+              Do not try to document other parts.
+            - #{Helpers.repository_access_constraint}
+            - #{Helpers.artifacts_access_constraint(artifact_ref(:requirements))}
+          EO_CONSTRAINTS
         end
       end
     end

data/lib/x_aeon_agents/agents/readme_generator_agent.rb

@@ -75,10 +75,10 @@ module XAeonAgents
             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
+              Write the name of this project to the file `#{about_analyzer_agent.artifact_ref(:name)}`.
+              Write a 1-line high-level description of this project to the file `#{about_analyzer_agent.artifact_ref(:description)}`
                 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
+              Write an engaging high-level description/overview of this project to the file `#{about_analyzer_agent.artifact_ref(:about)}`
                 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.
@@ -94,7 +94,7 @@ module XAeonAgents
             intent: 'Generate README Quick Start section',
             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
+              Write quick installation and usage instructions to the file `#{quick_start_agent.artifact_ref(:quick_start)}`
                 using Markdown format, compatible with Github flavor.
               These instructions should cover the installation and basic usage of this project, with simple examples.
             EO_INSTRUCTIONS
@@ -108,7 +108,7 @@ module XAeonAgents
             intent: 'Generate README Requirements section',
             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
+              Write the list of all prerequisites needed to use or run the project to the file `#{requirements_agent.artifact_ref(:requirements)}`
                 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.
@@ -123,7 +123,7 @@ module XAeonAgents
             intent: 'Generate README Features section',
             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
+              Write the list of the main features of the project to the file `#{features_agent.artifact_ref(:features)}`
                 using Markdown format, compatible with Github flavor.
               Those features should be summarized in a simple paragraph.
             EO_INSTRUCTIONS
@@ -137,7 +137,7 @@ module XAeonAgents
             intent: 'Generate README Public API section',
             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
+              Write the documentation of the public API surface to the file `#{public_api_agent.artifact_ref(:public_api)}`
                 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.
@@ -158,7 +158,7 @@ module XAeonAgents
             intent: 'Generate README Documentation section',
             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
+              Write links to documentation resources to the file `#{documentation_agent.artifact_ref(:documentation)}`
                 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`).
@@ -174,7 +174,7 @@ module XAeonAgents
             intent: 'Generate README "How does it work" section',
             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
+              Write an explanation of the internal architecture and working principles to the file `#{how_it_works_agent.artifact_ref(:how_it_works)}`
                 using Markdown format, compatible with Github flavor.
               This should be summarized as a small section, not an architecture document.
             EO_INSTRUCTIONS
@@ -188,7 +188,7 @@ module XAeonAgents
             intent: 'Generate README Development section',
             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
+              Write how to set up a development environment for this project to the file `#{development_agent.artifact_ref(:development)}`
                 using Markdown format, compatible with Github flavor.
             EO_INSTRUCTIONS
           )
@@ -201,7 +201,7 @@ module XAeonAgents
             intent: 'Generate README Contributing section',
             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
+              Write how users can contribute to the project to the file `#{contributing_agent.artifact_ref(:contributing)}`
                 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.
@@ -216,7 +216,7 @@ module XAeonAgents
             intent: 'Generate README License section',
             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
+              Write the description of the project license to the file `#{license_agent.artifact_ref(: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

data/lib/x_aeon_agents/agents/review_resolver_agent.rb

@@ -63,22 +63,22 @@ module XAeonAgents
               user_instructions: {
                 ordered_list: [
                   <<~EO_INSTRUCTION,
-                    Read the `#{feedback_analyst_agent.artifact_ref(:pr_description)}` artifact to understand the purpose of this Pull Request
+                    Read the file `#{feedback_analyst_agent.artifact_ref(:pr_description)}` 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
+                    Read the file `#{feedback_analyst_agent.artifact_ref(:pr_files_diffs)}` 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
+                    Read the file `#{feedback_analyst_agent.artifact_ref(:conversations)}` 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
+                    Read the file `#{feedback_analyst_agent.artifact_ref(:open_comments_to_agents)}` to focus on agent-directed comments
 
                     - You must devise requirements that will address those exact comments.
                   EO_INSTRUCTION
@@ -86,9 +86,9 @@ module XAeonAgents
                     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)}`
+                    Write clear, actionable requirements extracted from the comments to the file `#{feedback_analyst_agent.artifact_ref(:requirements)}`
 
-                    - If no implementation is required (e.g., comments are just questions), output "No requirements"
+                    - If no implementation is required (e.g., comments are just questions), write exactly `No requirements` in this file
                   EO_INSTRUCTION
                 ]
               }
@@ -120,32 +120,32 @@ module XAeonAgents
               user_instructions: {
                 ordered_list: [
                   <<~EO_INSTRUCTION,
-                    Read the `#{review_responder_agent.artifact_ref(:conversations)}` artifact to understand the full context of the PR conversations
+                    Read the file `#{review_responder_agent.artifact_ref(:conversations)}` 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
+                    Read the file `#{review_responder_agent.artifact_ref(:requirements)}` 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
+                    Read the file `#{review_responder_agent.artifact_ref(:plan)}` 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
+                    Read the file `#{review_responder_agent.artifact_ref(:files_diffs)}` 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
+                    Read the file `#{review_responder_agent.artifact_ref(:open_comment_for_reply)}` 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)}`
+                    Write a professional, helpful reply that addresses the comment appropriately to the file `#{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.

data/lib/x_aeon_agents/agents/review_responder_agent.rb

@@ -18,9 +18,18 @@ module XAeonAgents
               description: 'The exact comment to be replied to',
               type: :json
             },
-            requirements: 'The requirements that have been implemented (or "No requirements")',
-            plan: 'The implementation plan that was used to implement those requirements (or "No implementation plan")',
-            files_diffs: 'The code changes from implement_requirements workflow (or "No changes")'
+            requirements: {
+              description: 'The requirements that have been implemented (or "No requirements")',
+              type: :markdown
+            },
+            plan: {
+              description: 'The implementation plan that was used to implement those requirements (or "No implementation plan")',
+              type: :markdown
+            },
+            files_diffs: {
+              description: 'The code changes from implement_requirements workflow (or "No changes")',
+              type: :text
+            }
           }
         )
       end
@@ -46,17 +55,25 @@ module XAeonAgents
           role: 'You are a review responder agent. Your role is to reply to feedback, ' \
             'taking into account the feedback itself, and the work that has been done because of this feedback.',
           objective: 'Generate a reply to a review comment',
+          system_instructions: <<~EO_INSTRUCTIONS,
+            #{Helpers.repository_access_system_instructions}
+
+            Always base your reply on the input artifacts given to you: they contain the full context of the Pull Request.
+            Do not indicate that you will perform an action without actually doing it.
+          EO_INSTRUCTIONS
           **agent_params
         )
         self.constraints = <<~EO_CONSTRAINTS
-          - You are in read-only mode.
-          - Do NOT modify or write any file.
-          - The implementation work is already complete (captured in the artifacts).
-          - ONLY focus on addressing the specific comment of the `#{artifact_ref(:open_comment_for_reply)}` artifact appropriately.
+          - You are in read-only mode for the repository: do NOT modify any file of it.
+          - The implementation work is already complete (captured in the input artifacts).
+          - ONLY focus on addressing the specific comment described in the file `#{artifact_ref(:open_comment_for_reply)}`.
           - Do NOT answer or reply to any other comment.
           - You already have ALL the information required.
           - You MUST NOT ask follow-up questions.
           - You MUST NOT ask for user confirmation.
+          - Write the reply text to the output artifact file `#{artifact_ref(:reply)}`.
+          - #{Helpers.repository_access_constraint}
+          - #{Helpers.artifacts_access_constraint(artifact_ref(:reply))}
         EO_CONSTRAINTS
       end
     end

data/lib/x_aeon_agents/agents/tester_agent.rb

@@ -10,12 +10,27 @@ module XAeonAgents
       # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
       def input_artifacts_contracts
         super.merge(
-          requirements: 'The initial requirements',
-          plan: 'The implementation plan devised from the requirements',
-          files_diffs: 'The full list of files changes and differences that have been done to implement the initial ' \
-            'requirements following the implementation plan',
-          tests_output: 'The output of running the whole tests suite',
-          tests_cmd: 'The command line to be used to run the whole tests suite'
+          requirements: {
+            description: 'The initial requirements',
+            type: :markdown
+          },
+          plan: {
+            description: 'The implementation plan devised from the requirements',
+            type: :markdown
+          },
+          files_diffs: {
+            description: 'The full list of files changes and differences that have been done to implement the initial ' \
+              'requirements following the implementation plan',
+            type: :text
+          },
+          tests_output: {
+            description: 'The output of running the whole tests suite',
+            type: :text
+          },
+          tests_cmd: {
+            description: 'The command line to be used to run the whole tests suite',
+            type: :text
+          }
         )
       end
 
@@ -42,12 +57,12 @@ module XAeonAgents
             Fix any regression that has been induced by new features or fixes, while keeping the initial requirements and implementation plan in mind.
             If the decisions taken in the implementation plan prevent you from fixing regressions, modify the implementation plan and report those modifications to the user.
           EO_OBJECTIVE
-          constraints: <<~EO_CONSTRAINTS,
-            - #{Helpers.repository_access_constraint(writable: true)}
-            - Never create files (`ARTIFACT_*`, `/tmp/*`) to hold artifacts. Put the fenced ` ```json output_artifact=… ` block in your final message and end the turn with __no tool call__.
-          EO_CONSTRAINTS
           **agent_params
         )
+        self.constraints = <<~EO_CONSTRAINTS
+          - #{Helpers.repository_access_constraint(writable: true)}
+          - #{Helpers.artifacts_access_constraint(artifact_ref(:plan_modifications))}
+        EO_CONSTRAINTS
         self.system_instructions = <<~EO_INSTRUCTIONS
           #{Helpers.repository_access_system_instructions}
 
@@ -62,7 +77,7 @@ module XAeonAgents
 
           If you need more information, use one of the available tools or ask for clarification instead of making assumptions or lies.
 
-          Fix __all__ issues reported in the `#{artifact_ref(:tests_output)}` artifact in this iteration (not a subset).
+          Fix __all__ issues reported in the tests output file `#{artifact_ref(:tests_output)}` in this iteration (not a subset).
           Identify the exact failing spec file(s) and run __those__, then a final full run. __Never__ conclude success from a partial run.
           Quote the final summary line of your verification run in your answer.
 

data/lib/x_aeon_agents/helpers.rb

@@ -168,6 +168,19 @@ module XAeonAgents
         "You should only #{writable ? 'read and write' : 'read'} files that are part of the current repository: `#{Dir.pwd}`"
       end
 
+      # Get the constraint allowing agents to access their artifact files, which can be located outside of the
+      # current repository.
+      # This constraint is format-agnostic: it does not include any formatting (bullet, header...) so that it can be
+      # included in any constraints section.
+      #
+      # @param artifact_paths [Array<String>] Absolute paths of the artifact files the agent is allowed to access
+      # @return [String] The constraint about artifact files access
+      def artifacts_access_constraint(*artifact_paths)
+        'You are allowed to read and write the artifact files at ' \
+          "#{artifact_paths.map { |artifact_path| "`#{artifact_path}`" }.join(', ')}, " \
+          'even if they are not part of the current repository'
+      end
+
       # Allow user to review and edit content before using it
       #
       # When the interactive mode is disabled (Config.interactive), no review file

data/lib/x_aeon_agents/version.rb

@@ -2,5 +2,5 @@ module XAeonAgents
   # @!group Global API
 
   # Gem version
-  VERSION = '2.7.0'
+  VERSION = '2.7.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: x_aeon_agents
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.7.1
 platform: ruby
 authors:
 - Muriel Salvan