phronomy 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bb874213c4687c9021be3c78d8972218ed56980cfff777a624311ce476d7314
-  data.tar.gz: ab3017e56357b057943d31a557e9e1cd12555ec13924fbee92c6f0f7791c9bd1
+  metadata.gz: a5d8907f1d87037c09f78f63dd8ddbd21605536b1aa53c2d43e52be4a6ab6791
+  data.tar.gz: 37260258f4ece53e6e5b748cb2236f9c99f6f7e5c754fb0c2d72c415b0137386
 SHA512:
-  metadata.gz: e3d71a750858fda7910addd2ea8de1a3b907e746a247635d0b7467b4ffb5cf1ca970e74a08118b58e950c5843f756462d87a324331d23f50720067a83bb87590
-  data.tar.gz: 5ce1868de692cd6807c910f3d4669791307564c5f3dc58055c82c4c0737e3696c0d5b1050e7b85f1aba30b1e6309c11e66fcbf7ffc4f9f6c63f3970b5bce2d52
+  metadata.gz: 1533e2e0d82283066bab5f80b6583497330b274396640b91a6b27b1706533e4d25842600eb023c0fd469c8da076101f43e5691218703faedce194cd74476c590
+  data.tar.gz: af0513115bfcd23f786dfbedb7bfa7947346bb36168cc62175bd900f8536d984789469afc1fd929de90fca9a6b8cd8496451a054ea3ca86af401ef142b1c3e95

data/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.4.0] - 2026-05-19
+
+### Removed
+
+- **`Phronomy::TrustPipeline` removed**: The `TrustPipeline` class and its inner
+  `TrustResult` value object have been deleted. Use `Phronomy::GeneratorVerifier`
+  instead, which provides the same generator-verifier pattern with a cleaner,
+  fully injectable API.
+
+### Added
+
+- **`Phronomy::GeneratorVerifier`** — Generator-Verifier coordination loop
+  (Anthropic blog, Pattern 1). Wraps a generator agent and a verifier agent with
+  fully injectable prompt builders, response parsers, a configurable iteration
+  limit, and an approval-outcome raise policy.
+- **`Phronomy::Agent::Orchestrator`** — Base class for orchestrator agents
+  (Anthropic blog, Pattern 2). Extends `Agent::Base` with a `subagent` DSL for
+  declarative subagent registration as LLM-callable tools, plus `dispatch_parallel`
+  and `fan_out` for programmatic parallel invocation.
+- **`Phronomy::Agent::TeamCoordinator`** — Agent teams coordination pattern
+  (Anthropic blog, Pattern 3). An LLM-powered coordinator with a shared task
+  queue and a pool of worker agents that carry conversation history across task
+  assignments. Adds `coordinator_provider` DSL for independent LLM routing.
+- **`Phronomy::Agent::SharedState`** — Shared-state coordination pattern
+  (Anthropic blog, Pattern 5). Peer agents collaborate via a `KnowledgeStore`;
+  the `member` DSL registers agents with per-agent instructions; `coordination`
+  sets the team protocol; `build_prompt` injects a tool-usage guide automatically.
+- **`Phronomy::LowConfidenceError`** — Exception raised by `GeneratorVerifier`
+  when `raise_policy: :raise` and verification fails after exhausting the
+  iteration limit.
+
+### Changed
+
+- **`Phronomy::Graph::StateGraph` event system refactored**: Per-node `advance`
+  events replaced with a unified `node_completed` event queue, reducing
+  event-handler registration overhead and simplifying listener registration.
+
+---
+
 ## [0.3.0] - 2026-05-18
 
 ### Removed

data/README.md

@@ -18,7 +18,10 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Context Management** — Token budget calculation, estimation, and pruning | Stable |
 | **Knowledge/RAG** — Retrieval sources with pluggable loaders, splitters, and vector stores | Beta |
 | **Multi-agent** — Agent-as-Tool pattern and hub-and-spoke handoff routing | Beta |
-| **TrustPipeline** — Self-review loop and confidence gate (citations are LLM-self-reported) | Experimental |
+| **GeneratorVerifier** — Generator-Verifier loop with injectable prompt builders/parsers | Beta |
+| **Agent::Orchestrator** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
+| **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + persistent worker pool with task queue | Beta |
+| **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
 | **Guardrails** — Input/output validation; built-in PII and prompt-injection detectors | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
@@ -226,23 +229,88 @@ end
 
 Hooks are called in order — global → class → instance — and deep-merged.
 
-### TrustPipeline — Trustworthy outputs with citations and review
+### GeneratorVerifier — Generator-Verifier loop with custom prompt builders
 
 ```ruby
-pipeline = Phronomy::TrustPipeline.new(
-  draft_agent:          PolicyDraftAgent,
-  review_agent:         PolicyReviewAgent,
+pipeline = Phronomy::GeneratorVerifier.new(
+  draft_agent:  PolicyDraftAgent,
+  review_agent: PolicyReviewAgent,
+
+  # Full control over the LLM dialogue — supply your own prompts.
+  draft_prompt_builder: ->(input, feedback) {
+    base = "Answer precisely: #{input}"
+    feedback ? "#{base}\n\nPrevious feedback: #{feedback}" : base
+  },
+  review_prompt_builder: ->(input, draft, citations) {
+    "Is this draft accurate? Draft: #{draft}"
+  },
+
   confidence_threshold: 0.7,
-  max_iterations:       3
+  max_iterations:       3,
+  raise_if_untrusted:   false   # set true to raise LowConfidenceError
 )
 
 result = pipeline.invoke("What is the refund policy?")
-puts result.output             # final answer
-puts result.trusted?           # true when confidence >= 0.7
-puts result.confidence         # Float 0.0–1.0
+puts result.output      # final answer
+puts result.trusted?    # true when confidence >= 0.7
+puts result.confidence  # Float 0.0–1.0
+result.citations.each { |c| puts "#{c[:source]}: #{c[:excerpt]}" }
+```
+
+Optionally inject a custom result parser to decode non-JSON LLM output:
+
+```ruby
+pipeline = Phronomy::GeneratorVerifier.new(
+  # ... (required params as shown above)
+  draft_result_parser:  ->(text) { my_custom_draft_parser(text) },
+  review_result_parser: ->(text) { my_custom_review_parser(text) }
+)
+```
 
-result.citations.each do |c|
-  puts "#{c[:source]}: #{c[:excerpt]}"
+Raise on low confidence:
+
+```ruby
+begin
+  result = pipeline.invoke("question")
+rescue Phronomy::LowConfidenceError => e
+  puts "Untrusted (confidence #{e.result.confidence}): #{e.result.output}"
+end
+```
+
+### Agent::Orchestrator — Parallel subagent dispatch
+
+```ruby
+class ResearchOrchestrator < Phronomy::Agent::Orchestrator
+  model "gpt-4o"
+  instructions "Coordinate research tasks by dispatching to specialised agents."
+
+  # Each subagent is automatically exposed as an LLM-callable tool.
+  subagent :searcher,   SearchAgent
+  subagent :summarizer, SummaryAgent, on_error: :skip
+end
+
+result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
+```
+
+Programmatic parallel dispatch (no LLM loop):
+
+```ruby
+class MyOrchestrator < Phronomy::Agent::Orchestrator
+  model "gpt-4o"
+  instructions "Orchestrate."
+
+  def run(query)
+    # Heterogeneous agents in parallel
+    results = dispatch_parallel(
+      {agent: SearchAgent,   input: "topic A"},
+      {agent: AnalysisAgent, input: query}
+    )
+
+    # Fan-out — same agent, multiple inputs
+    translations = fan_out(agent: TranslationAgent, inputs: %w[Hello World])
+
+    results.map { |r| r[:output] }.join("\n")
+  end
 end
 ```
 
@@ -432,7 +500,7 @@ bundle exec ruby NN_example_name/run.rb
 | 16 | `16_before_completion_hook/` | Global/class/instance before_completion hooks |
 | 17 | `17_multi_agent_handoff/` | Hub-and-spoke agent routing via Runner |
 | 18 | `18_rails_agent_job/` | Rails app with AgentJob + ActionCable streaming |
-| 19 | `19_trust_pipeline/` | Trustworthy output via Citation Tracking + Self-Review + Confidence Gate |
+| 19 | `19_trust_pipeline/` | Generator-Verifier pattern with citation tracking, self-review loop and confidence gate |
 
 ## Development
 

data/lib/phronomy/agent/base.rb

@@ -66,7 +66,8 @@ module Phronomy
           if text || block_given?
             @instructions = text || block
           else
-            @instructions
+            return @instructions if instance_variable_defined?(:@instructions)
+            superclass.respond_to?(:instructions) ? superclass.instructions : nil
           end
         end
 
@@ -88,7 +89,10 @@ module Phronomy
         #   )
         def tools(*args)
           if args.empty?
-            return @tools || []
+            if instance_variable_defined?(:@tools)
+              return @tools
+            end
+            return superclass.respond_to?(:tools) ? superclass.tools : []
           end
 
           if args.length == 1 && args.first.is_a?(Hash)
@@ -122,7 +126,8 @@ module Phronomy
           if name
             @provider = name
           else
-            @provider
+            return @provider if instance_variable_defined?(:@provider)
+            superclass.respond_to?(:provider) ? superclass.provider : nil
           end
         end
 

data/lib/phronomy/agent/orchestrator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Base class for orchestrator agents that coordinate multiple subagents.
+    # Implements the Orchestrator-Subagent multi-agent coordination pattern
+    # (Anthropic blog, Pattern 2).
+    #
+    # @see https://claude.com/blog/multi-agent-coordination-patterns
+    #
+    # Extends {Phronomy::Agent::Base} with:
+    # - A +subagent+ class-level DSL for declarative subagent registration. Each
+    #   declared subagent is automatically exposed as an LLM-callable tool.
+    # - +dispatch_parallel+ for programmatic parallel invocation of heterogeneous
+    #   agents.
+    # - +fan_out+ for parallel invocation of the same agent across multiple inputs.
+    #
+    # @example Declarative DSL
+    #   class ResearchOrchestrator < Phronomy::Agent::Orchestrator
+    #     model "gpt-4o"
+    #     instructions "You coordinate research tasks."
+    #     subagent :searcher,   SearchAgent
+    #     subagent :summarizer, SummaryAgent
+    #   end
+    #
+    #   result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
+    #
+    # @example Programmatic parallel dispatch
+    #   class MyOrchestrator < Phronomy::Agent::Orchestrator
+    #     model "gpt-4o"
+    #     instructions "Dispatch tasks in parallel."
+    #
+    #     def run(input)
+    #       results = dispatch_parallel(
+    #         { agent: SearchAgent,   input: "topic A" },
+    #         { agent: AnalysisAgent, input: input }
+    #       )
+    #       results.map { |r| r[:output] }.join("\n")
+    #     end
+    #   end
+    #
+    # @example Fan-out (same agent, multiple inputs)
+    #   results = fan_out(agent: TranslationAgent, inputs: ["Hello", "World"])
+    class Orchestrator < Base
+      # Declares a named subagent and registers it as a tool accessible to the
+      # LLM during an +invoke+ call.
+      #
+      # Each call appends a new tool to this class's tool list.  The generated
+      # tool's function name is +dispatch_to_<name>+.  When the LLM calls the
+      # tool, a fresh instance of +agent_class+ is created and +invoke+ is called
+      # with the provided input string.
+      #
+      # @param name        [Symbol] logical name that identifies the subagent
+      # @param agent_class [Class]  subclass of {Phronomy::Agent::Base}
+      # @param on_error    [Symbol] +:raise+ (default) re-raises any exception
+      #   from the subagent; +:skip+ returns +nil+ so the LLM can decide how to
+      #   proceed
+      def self.subagent(name, agent_class, on_error: :raise)
+        tool_class = Class.new(Phronomy::Tool::Base) do
+          tool_name "dispatch_to_#{name}"
+          description "Dispatch work to the #{name} subagent (#{agent_class.name})"
+          param :input, type: :string, desc: "The task or question for the subagent"
+
+          define_method(:execute) do |input:|
+            result = agent_class.new.invoke(input)
+            result[:output]
+          rescue
+            raise if on_error == :raise
+            nil
+          end
+        end
+
+        # Append without clobbering previously registered tools or aliases.
+        @tools = (@tools || []) + [tool_class]
+        @tool_aliases ||= {}
+
+        registered_subagents[name] = {agent_class: agent_class, on_error: on_error}
+      end
+
+      # Returns the subagent registry for this specific class (not inherited).
+      #
+      # @return [Hash{Symbol => Hash}]
+      def self.registered_subagents
+        @registered_subagents ||= {}
+      end
+
+      # Dispatches multiple heterogeneous agent tasks in parallel using Ruby
+      # threads. Each task is a Hash describing one agent invocation.
+      #
+      # Results are returned in the same order as the input +tasks+ array.
+      # If any thread raises an exception, the exception is re-raised in the
+      # calling thread after all threads have completed (via +Thread#value+).
+      #
+      # @param tasks [Array<Hash>]
+      # @option task [Class]  :agent  agent class to invoke (required)
+      # @option task [String] :input  input string for the agent (required)
+      # @option task [Hash]   :config forwarded to +agent#invoke+ (default: +{}+)
+      # @return [Array<Hash>] agent results in the same order as +tasks+
+      def dispatch_parallel(*tasks)
+        threads = tasks.map do |task|
+          Thread.new do
+            task[:agent].new.invoke(task[:input], config: task.fetch(:config, {}))
+          end
+        end
+        threads.map(&:value)
+      end
+
+      # Runs the same agent against multiple inputs in parallel (fan-out pattern).
+      #
+      # @param agent  [Class]         agent class to invoke for every input
+      # @param inputs [Array<String>] list of input strings
+      # @param config [Hash]          forwarded to every +agent#invoke+ call
+      # @return [Array<Hash>] results in the same order as +inputs+
+      def fan_out(agent:, inputs:, config: {})
+        dispatch_parallel(*inputs.map { |input| {agent: agent, input: input, config: config} })
+      end
+    end
+  end
+end

data/lib/phronomy/agent/shared_state.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Implements the "Shared state" coordination pattern (Anthropic blog, Pattern 5).
+    #
+    # @see https://claude.com/blog/multi-agent-coordination-patterns
+    #
+    # Multiple peer agents collaborate through a shared {KnowledgeStore}.
+    # There is no central coordinator. Each agent reads the store, acts on what it
+    # finds, and writes new findings back. Later agents in a cycle immediately see
+    # findings written by earlier agents in the same cycle.
+    #
+    # Two tools are automatically injected into every member agent at runtime:
+    # - +read_store+    — returns all current findings as a JSON string
+    # - +write_finding+ — appends a Hash finding to the store
+    #
+    # Use +member+ to register agents and optionally provide per-agent coordination
+    # instructions. Use +coordination+ to define the team-level protocol that all
+    # members receive instead of the built-in default guide.
+    #
+    # @example Basic usage with per-agent instructions
+    #   class CodeReviewTeam < Phronomy::Agent::SharedState
+    #     member StructureAnalyst
+    #     member SecurityAuditor, instruction: "Focus on authentication and injection risks."
+    #     member QualityReviewer,  instruction: "Flag methods longer than 10 lines."
+    #     max_cycles  3
+    #     aggregate   { |store| { findings: store.read_all, total: store.size } }
+    #   end
+    #
+    #   result = CodeReviewTeam.new.invoke("Review the files in ./src")
+    #   # => { output: { findings: [...], total: N }, cycles: 3, terminated_by: :max_cycles }
+    #
+    # @example With custom team-level coordination protocol
+    #   class ResearchTeam < Phronomy::Agent::SharedState
+    #     coordination <<~TEXT
+    #       Shared store tools: read_store (no params), write_finding(content:).
+    #       Workflow: read first, then write one finding per insight.
+    #     TEXT
+    #     member LiteratureAgent
+    #     member IndustryAgent
+    #     max_cycles  10
+    #     terminate_when { |store| store.size >= 20 }
+    #   end
+    class SharedState
+      # Thread-safe (serialised by sequential execution) knowledge store shared
+      # across all researcher agents within a single {SharedState#invoke} call.
+      #
+      # Each finding is stored as a Hash with the keys:
+      #   :agent   — Symbol derived from the researcher class name
+      #   :content — String written by the researcher
+      #   :cycle   — Integer cycle number in which the finding was recorded
+      class KnowledgeStore
+        def initialize
+          @findings = []
+        end
+
+        # Returns a shallow copy of all findings in insertion order.
+        # @return [Array<Hash>]
+        def read_all
+          @findings.dup
+        end
+
+        # Appends a new finding to the store.
+        # @param agent   [Symbol]  researcher identifier
+        # @param content [String]  the finding text
+        # @param cycle   [Integer] the current cycle number
+        # @return [nil]
+        def write(agent:, content:, cycle:)
+          @findings << {agent: agent, content: content, cycle: cycle}
+          nil
+        end
+
+        # Returns the number of findings recorded so far.
+        # @return [Integer]
+        def size
+          @findings.size
+        end
+      end
+
+      class << self
+        # Registers a member agent class that will collaborate via the shared store.
+        # Members are invoked sequentially within each cycle in declaration order.
+        #
+        # @param klass [Class] an Agent::Base subclass
+        # @param instruction [String, nil] optional per-agent coordination instruction
+        #   appended to the team coordination text in this agent's prompt
+        def member(klass, instruction: nil)
+          @members ||= []
+          @members << {klass: klass, instruction: instruction}
+        end
+
+        # Backward-compatible alias. Registers each class as a member without a
+        # per-agent instruction. Prefer {.member} for new code.
+        #
+        # @param classes [Array<Class>] Agent::Base subclasses
+        def researchers(*classes)
+          classes.flatten.each { |klass| member(klass) }
+        end
+
+        # Defines the team-level coordination protocol text injected into every
+        # member's prompt. When omitted the built-in default guide is used, which
+        # explains +read_store+ / +write_finding+ usage and enforces the standard
+        # workflow. Override this when you need a different protocol or tone.
+        #
+        # @param text [String, nil] the coordination instructions
+        def coordination(text = nil)
+          text ? @coordination = text : @coordination
+        end
+
+        # Sets the maximum number of cycles to run.
+        # At least one of +max_cycles+ or +timeout+ must be configured.
+        #
+        # @param value [Integer, nil]
+        def max_cycles(value = nil)
+          value ? @max_cycles = Integer(value) : @max_cycles
+        end
+
+        # Sets the maximum wall-clock seconds for the entire invocation.
+        # At least one of +max_cycles+ or +timeout+ must be configured.
+        #
+        # @param value [Numeric, nil]
+        def timeout(value = nil)
+          value ? @timeout = value.to_f : @timeout
+        end
+
+        # Registers an optional convergence block. Evaluated after each completed
+        # cycle; when it returns +true+ the loop terminates early.
+        #
+        # @yield [KnowledgeStore] receives the store; return +true+ to stop
+        def terminate_when(&block)
+          block ? @terminate_when = block : @terminate_when
+        end
+
+        # Defines how the final store is converted into the +:output+ of the result.
+        # When omitted, +store.read_all+ is used as-is.
+        #
+        # @yield [KnowledgeStore] receives the final store; return value becomes +:output+
+        def aggregate(&block)
+          block ? @aggregator = block : @aggregator
+        end
+
+        # @!visibility private
+        def _members = Array(@members)
+        # @!visibility private — derives class list from _members for backward compat
+        def _researchers = _members.map { |m| m[:klass] }
+        # @!visibility private
+        def _coordination = @coordination
+        # @!visibility private
+        def _max_cycles = @max_cycles
+        # @!visibility private
+        def _timeout = @timeout
+        # @!visibility private
+        def _terminate_when = @terminate_when
+        # @!visibility private
+        def _aggregator = @aggregator
+      end
+
+      # Runs the shared-state coordination loop.
+      #
+      # @param input  [String] the seed question or task description
+      # @param config [Hash]   reserved for future use
+      # @return [Hash] +:output+, +:cycles+, +:terminated_by+
+      # @raise [ArgumentError] when neither +max_cycles+ nor +timeout+ is configured
+      def invoke(input, config: {})
+        validate_termination!
+
+        store = KnowledgeStore.new
+        max_cycles = self.class._max_cycles
+        deadline = self.class._timeout ? Time.now + self.class._timeout : nil
+        terminated_by = :max_cycles
+        completed_cycles = 0
+
+        cycle_limit = max_cycles || Float::INFINITY
+
+        (1..cycle_limit).each do |cycle|
+          self.class._members.each do |member_config|
+            invoke_researcher(member_config[:klass], store, cycle, input, member_config[:instruction])
+          end
+          completed_cycles = cycle
+
+          if self.class._terminate_when&.call(store)
+            terminated_by = :terminate_when
+            break
+          end
+
+          if deadline && Time.now >= deadline
+            terminated_by = :timeout
+            break
+          end
+
+          terminated_by = :max_cycles
+        end
+
+        output = if self.class._aggregator
+          self.class._aggregator.call(store)
+        else
+          store.read_all
+        end
+
+        {output: output, cycles: completed_cycles, terminated_by: terminated_by}
+      end
+
+      private
+
+      def validate_termination!
+        return if self.class._max_cycles || self.class._timeout
+        raise ArgumentError,
+          "max_cycles or timeout must be configured before invoking SharedState"
+      end
+
+      # Invokes a single member agent for one cycle.
+      # Builds an anonymous subclass with +read_store+ and +write_finding+ injected,
+      # then calls +invoke+ with a prompt that includes the coordination guide,
+      # any per-agent instruction, and the current store contents.
+      def invoke_researcher(researcher_class, store, cycle, original_input, per_agent_instruction = nil)
+        instrumented = build_instrumented_researcher(researcher_class, store, cycle)
+        extra_tools = researcher_class.tools
+        prompt = build_prompt(original_input, store, cycle,
+          extra_tools: extra_tools,
+          per_agent_instruction: per_agent_instruction)
+        instrumented.new.invoke(prompt)
+      end
+
+      # Builds an anonymous subclass of +researcher_class+ with two store tools
+      # injected. The tools close over the +store+ instance so that writes and
+      # reads are reflected in the live store.
+      def build_instrumented_researcher(researcher_class, store, cycle)
+        agent_key = researcher_class.name&.to_sym || researcher_class.object_id.to_s.to_sym
+
+        read_tool = Class.new(Phronomy::Tool::Base) do
+          tool_name "read_store"
+          description "Read all current findings from the shared knowledge store. " \
+                      "Call this to see what other researchers have discovered."
+
+          define_method(:execute) { store.read_all.to_json }
+        end
+
+        write_tool = Class.new(Phronomy::Tool::Base) do
+          tool_name "write_finding"
+          description "Record a new finding into the shared knowledge store so " \
+                      "that other researchers can build on your discovery."
+          param :content, type: :string, desc: "The finding to record"
+
+          define_method(:execute) do |content:|
+            store.write(agent: agent_key, content: content, cycle: cycle)
+            "Finding recorded."
+          end
+        end
+
+        parent_tools = researcher_class.tools
+        Class.new(researcher_class) { tools(*parent_tools, read_tool, write_tool) }
+      end
+
+      # Builds the invocation prompt for a member agent.
+      # Uses the team-level coordination text when defined via {.coordination},
+      # otherwise falls back to the built-in default guide. Appends any per-agent
+      # instruction after the coordination text. Subsequent cycles also include
+      # the current store contents so agents can build on prior findings.
+      def build_prompt(original_input, store, cycle, extra_tools: [], per_agent_instruction: nil)
+        guide = self.class._coordination || default_coordination_guide(extra_tools)
+
+        prompt_parts = [guide]
+        if per_agent_instruction
+          prompt_parts << "\nYour specific focus for this session: #{per_agent_instruction}"
+        end
+        header = prompt_parts.join
+
+        base = "#{header}\n\nTask: #{original_input}"
+        return base if store.size == 0
+
+        findings_text = store.read_all
+          .map { |f| "- [#{f[:agent]} / cycle #{f[:cycle]}] #{f[:content]}" }
+          .join("\n")
+
+        "#{header}\n\nTask: #{original_input}\n\nFindings so far:\n#{findings_text}"
+      end
+
+      # Builds the default tool-usage guide for member agents.
+      # Describes +read_store+ / +write_finding+ and the required workflow.
+      # When extra_tools are present, lists their names so the agent knows
+      # what additional tools are available.
+      def default_coordination_guide(extra_tools)
+        extra_line = if extra_tools.any?
+          tool_names = extra_tools.map { |t| t.respond_to?(:tool_name) ? t.tool_name : t.name.to_s }.join(", ")
+          "  You also have access to additional tools (#{tool_names}) — use them to gather information before writing findings.\n"
+        else
+          ""
+        end
+
+        <<~TEXT.chomp
+          You have access to a shared knowledge store via two tools:
+            read_store     — returns all current findings as JSON (no parameters)
+            write_finding  — records one finding to the store (param: content)
+          #{extra_line}Required workflow: first call read_store, then call write_finding once per insight.
+          Each call to write_finding must contain exactly one unique insight — do not call it twice with the same content.
+          If you have no new insights to contribute, call write_finding exactly once with: "No new findings in this cycle."
+          Do not output plain text — every insight must be submitted via write_finding.
+        TEXT
+      end
+    end
+  end
+end