brute 0.1.7 → 0.1.9

data/lib/brute/skill.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Brute
+  # Discovers and loads SKILL.md files from standard directories.
+  #
+  # A skill is a markdown file with YAML frontmatter:
+  #
+  #   ---
+  #   name: debugging
+  #   description: Systematic debugging workflow for isolating and fixing bugs
+  #   ---
+  #
+  #   When debugging, follow these steps...
+  #
+  # Skills are scanned from (in order):
+  #   1. .brute/skills/**/SKILL.md   (project-local)
+  #   2. ~/.config/brute/skills/**/SKILL.md (global)
+  #
+  # The directory name containing SKILL.md becomes the skill name if frontmatter
+  # doesn't specify one.
+  #
+  module Skill
+    Info = Struct.new(:name, :description, :location, :content, keyword_init: true)
+
+    FILENAME = "SKILL.md"
+
+    # Scan all skill directories and return an array of Info structs.
+    def self.all(cwd: Dir.pwd)
+      skills = {}
+
+      scan_dirs(cwd).each do |dir|
+        Dir.glob(File.join(dir, "**", FILENAME)).sort.each do |path|
+          info = load(path)
+          next unless info
+          # First found wins (project-local overrides global)
+          skills[info.name] ||= info
+        end
+      end
+
+      skills.values.sort_by(&:name)
+    end
+
+    # Get a single skill by name.
+    def self.get(name, cwd: Dir.pwd)
+      all(cwd: cwd).detect { |s| s.name == name }
+    end
+
+    # Format skills as XML for the system prompt.
+    def self.fmt(skills)
+      return nil if skills.empty?
+
+      lines = ["<available_skills>"]
+      skills.each do |skill|
+        lines << "  <skill>"
+        lines << "    <name>#{skill.name}</name>"
+        lines << "    <description>#{skill.description}</description>"
+        lines << "  </skill>"
+      end
+      lines << "</available_skills>"
+      lines.join("\n")
+    end
+
+    # Parse a SKILL.md file into an Info struct.
+    # Returns nil if the file is invalid or missing required fields.
+    def self.load(path)
+      raw = File.read(path)
+      frontmatter, content = parse_frontmatter(raw)
+      return nil unless frontmatter
+
+      name = frontmatter["name"] || File.basename(File.dirname(path))
+      description = frontmatter["description"]
+      return nil unless description && !description.strip.empty?
+
+      Info.new(
+        name: name.to_s.strip,
+        description: description.to_s.strip,
+        location: path,
+        content: content.to_s.strip,
+      )
+    rescue => e
+      warn "Failed to load skill #{path}: #{e.message}"
+      nil
+    end
+
+    # Directories to scan for skills, in priority order.
+    def self.scan_dirs(cwd)
+      dirs = []
+
+      # Project-local
+      project = File.join(cwd, ".brute", "skills")
+      dirs << project if File.directory?(project)
+
+      # Global
+      global = File.join(Dir.home, ".config", "brute", "skills")
+      dirs << global if File.directory?(global)
+
+      dirs
+    end
+
+    # Split YAML frontmatter from markdown body.
+    # Returns [hash, string] or [nil, nil].
+    def self.parse_frontmatter(raw)
+      return [nil, nil] unless raw.start_with?("---")
+
+      parts = raw.split(/^---\s*$/, 3)
+      return [nil, nil] if parts.length < 3
+
+      frontmatter = YAML.safe_load(parts[1])
+      return [nil, nil] unless frontmatter.is_a?(Hash)
+
+      [frontmatter, parts[2]]
+    end
+
+    private_class_method :scan_dirs, :parse_frontmatter
+  end
+end

data/lib/brute/system_prompt.rb

@@ -1,88 +1,143 @@
 # frozen_string_literal: true
 
 module Brute
-  # Builds the system prompt dynamically based on available tools, environment,
-  # custom rules, and working directory context.
+  # Deferred system prompt builder.
+  #
+  # The block passed to +build+ is stored — not executed — until +prepare+
+  # is called with a runtime context hash (provider_name, model_name, cwd, etc).
+  #
+  #   sp = Brute::SystemPrompt.build do |prompt, ctx|
+  #     prompt << Brute::Prompts::Identity.call(ctx)
+  #     prompt << Brute::Prompts::ToneAndStyle.call(ctx)
+  #     prompt << Brute::Prompts::Environment.call(ctx)
+  #   end
+  #
+  #   result = sp.prepare(provider_name: "anthropic", model_name: "claude-sonnet-4-20250514", cwd: Dir.pwd)
+  #   result.to_s       # single joined string
+  #   result.sections   # array of strings (one per p.system call)
   #
-  # Modeled after forgecode's SystemPrompt which composes a static agent
-  # personality block with dynamic environment/tool information.
   class SystemPrompt
-    def initialize(cwd: Dir.pwd, tools: [], custom_rules: nil)
-      @cwd = cwd
-      @tools = tools
-      @custom_rules = custom_rules
+    # Build a deferred system prompt. The block is stored and called later by +prepare+.
+    def self.build(&block)
+      new(block)
     end
 
-    def build
-      sections = []
-      sections << identity_section
-      sections << tools_section
-      sections << guidelines_section
-      sections << environment_section
-      sections << custom_rules_section if @custom_rules
-      sections.compact.join("\n\n")
-    end
+    # Return the default system prompt. Selects the right provider stack at
+    # prepare-time, then appends conditional sections based on runtime state.
+    def self.default
+      build do |prompt, ctx|
+        # Provider-specific base stack
+        provider = ctx[:provider_name].to_s
+        STACKS.fetch(provider, STACKS["default"]).each do |mod|
+          prompt << mod.call(ctx)
+        end
 
-    private
+        # Conditional: agent-specific reminders
+        if ctx[:agent] == "plan"
+          prompt << Prompts::PlanReminder.call(ctx)
+        end
 
-    def identity_section
-      <<~SECTION
-        # Identity
+        if ctx[:agent_switched] == "build"
+          prompt << Prompts::BuildSwitch.call(ctx)
+        end
 
-        You are Brute, an expert software engineering agent. You help users with coding tasks
-        by reading, writing, and editing files, running shell commands, and searching codebases.
-        You are methodical, precise, and always verify your work.
-      SECTION
+        if ctx[:max_steps_reached]
+          prompt << Prompts::MaxSteps.call(ctx)
+        end
+      end
     end
 
-    def tools_section
-      tool_list = LLM::Function.registry.filter_map { |fn|
-        "- **#{fn.name}**: #{fn.description.to_s.split(". ").first}."
-      }.join("\n")
+    # Pre-configured prompt stacks per provider.
+    # Each maps a provider name to an ordered list of prompt modules.
+    STACKS = {
+      # Claude — full-featured with task management and detailed tool policy
+      "anthropic" => [
+        Prompts::Identity,
+        Prompts::ToneAndStyle,
+        Prompts::Objectivity,
+        Prompts::TaskManagement,
+        Prompts::DoingTasks,
+        Prompts::ToolUsage,
+        Prompts::Conventions,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
 
-      <<~SECTION
-        # Available Tools
+      # GPT-4 / o1 / o3 — pragmatic engineer persona, editing focus, autonomy
+      "openai" => [
+        Prompts::Identity,
+        Prompts::EditingApproach,
+        Prompts::Autonomy,
+        Prompts::EditingConstraints,
+        Prompts::FrontendTasks,
+        Prompts::ToneAndStyle,
+        Prompts::Conventions,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
 
-        #{tool_list}
-      SECTION
-    end
+      # Gemini — formal/structured, explicit workflows, security focus
+      "google" => [
+        Prompts::Identity,
+        Prompts::Conventions,
+        Prompts::DoingTasks,
+        Prompts::ToneAndStyle,
+        Prompts::SecurityAndSafety,
+        Prompts::ToolUsage,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
 
-    def guidelines_section
-      <<~SECTION
-        # Guidelines
+      # Fallback — conservative, concise, fewer than 4 lines
+      "default" => [
+        Prompts::Identity,
+        Prompts::ToneAndStyle,
+        Prompts::Proactiveness,
+        Prompts::Conventions,
+        Prompts::CodeStyle,
+        Prompts::DoingTasks,
+        Prompts::ToolUsage,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
+    }.freeze
 
-        - **Always read before editing**: Use `read` to examine a file before using `patch` or `write` to modify it.
-        - **Verify your changes**: After editing, re-read the file or run tests to confirm correctness.
-        - **Use todo_write for multi-step tasks**: Break complex work into steps and track progress.
-        - **Use fs_search to find code**: Don't guess file locations — search first.
-        - **Use shell for git, tests, builds**: Run `git diff`, `git status`, test suites, etc.
-        - **Be precise with patch**: The `old_string` must match the file content exactly, including whitespace.
-        - **Prefer patch over write**: For existing files, use `patch` to change specific sections rather than rewriting the entire file.
-        - **Use undo to recover**: If a write or patch goes wrong, use `undo` to restore the previous version.
-        - **Delegate research**: Use `delegate` for complex analysis that needs focused investigation.
-      SECTION
+    def initialize(block)
+      @block = block
     end
 
-    def environment_section
-      files = Dir.entries(@cwd).reject { |f| f.start_with?(".") }.sort.first(50)
-
-      <<~SECTION
-        # Environment
-
-        - **Working directory**: #{@cwd}
-        - **OS**: #{RUBY_PLATFORM}
-        - **Ruby**: #{RUBY_VERSION}
-        - **Date**: #{Time.now.strftime("%Y-%m-%d")}
-        - **Files in cwd**: #{files.join(", ")}
-      SECTION
+    # Execute the stored block with the given context and return a Result.
+    def prepare(ctx)
+      sections = []
+      @block.call(sections, ctx)
+      Result.new(sections.compact.reject { |s| s.respond_to?(:empty?) && s.empty? })
     end
 
-    def custom_rules_section
-      <<~SECTION
-        # Project-Specific Rules
+    # Immutable result of a prepared system prompt.
+    Result = Struct.new(:sections) do
+      def to_s
+        sections.join("\n\n")
+      end
+
+      def each(&block)
+        sections.each(&block)
+      end
 
-        #{@custom_rules}
-      SECTION
+      def empty?
+        sections.empty?
+      end
     end
   end
 end

data/lib/brute/tools/question.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class Question < LLM::Tool
+      name "question"
+      description "Ask the user questions during execution. Use this to gather preferences, " \
+                  "clarify ambiguous instructions, get decisions on implementation choices, or " \
+                  "offer choices about direction. Users can always select \"Other\" to provide " \
+                  "custom text input. Answers are returned as arrays of labels; set multiple: true " \
+                  "to allow selecting more than one. If you recommend a specific option, make it " \
+                  "the first option and add \"(Recommended)\" at the end of the label."
+
+      params do |s|
+        s.object(
+          questions: s.array(
+            s.object(
+              question: s.string.required,
+              header: s.string.required,
+              options: s.array(
+                s.object(
+                  label: s.string.required,
+                  description: s.string.required,
+                )
+              ).required,
+              multiple: s.boolean,
+            )
+          ).required
+        )
+      end
+
+      def call(questions:)
+        handler = Thread.current[:on_question]
+        unless handler
+          return { error: true, message: "Cannot ask questions in non-interactive mode" }
+        end
+
+        queue = Queue.new
+        handler.call(questions, queue)
+        answers = queue.pop
+
+        format_answers(questions, answers)
+      end
+
+      private
+
+      def format_answers(questions, answers)
+        pairs = questions.each_with_index.map do |q, i|
+          q = q.transform_keys(&:to_s) if q.is_a?(Hash)
+          header = q["header"]
+          answer = answers[i] || []
+          "\"#{header}\" = #{answer.join(', ')}"
+        end
+
+        { response: "User answered: #{pairs.join('; ')}" }
+      end
+    end
+  end
+end

data/lib/brute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brute
-  VERSION = "0.1.7"
+  VERSION = "0.1.9"
 end

data/lib/brute.rb

@@ -27,7 +27,32 @@ require_relative 'brute/file_mutation_queue'
 require_relative 'brute/doom_loop'
 require_relative 'brute/hooks'
 require_relative 'brute/compactor'
+require_relative 'brute/prompts/base'
+require_relative 'brute/prompts/identity'
+require_relative 'brute/prompts/tone_and_style'
+require_relative 'brute/prompts/objectivity'
+require_relative 'brute/prompts/task_management'
+require_relative 'brute/prompts/doing_tasks'
+require_relative 'brute/prompts/tool_usage'
+require_relative 'brute/prompts/conventions'
+require_relative 'brute/prompts/git_safety'
+require_relative 'brute/prompts/code_references'
+require_relative 'brute/prompts/environment'
+require_relative 'brute/prompts/instructions'
+require_relative 'brute/prompts/editing_approach'
+require_relative 'brute/prompts/autonomy'
+require_relative 'brute/prompts/editing_constraints'
+require_relative 'brute/prompts/frontend_tasks'
+require_relative 'brute/prompts/proactiveness'
+require_relative 'brute/prompts/code_style'
+require_relative 'brute/prompts/security_and_safety'
+require_relative 'brute/prompts/skills'
+require_relative 'brute/prompts/plan_reminder'
+require_relative 'brute/prompts/max_steps'
+require_relative 'brute/prompts/build_switch'
+require_relative 'brute/skill'
 require_relative 'brute/system_prompt'
+require_relative 'brute/message_store'
 require_relative 'brute/session'
 require_relative 'brute/pipeline'
 require_relative 'brute/agent_stream'
@@ -44,10 +69,12 @@ require_relative 'brute/middleware/doom_loop_detection'
 require_relative 'brute/middleware/token_tracking'
 require_relative 'brute/middleware/compaction_check'
 require_relative 'brute/middleware/session_persistence'
+require_relative 'brute/middleware/message_tracking'
 require_relative 'brute/middleware/tracing'
 require_relative 'brute/middleware/tool_error_tracking'
 require_relative 'brute/middleware/reasoning_normalizer'
 require_relative "brute/middleware/tool_use_guard"
+require_relative "brute/middleware/otel"
 
 # Tools
 require_relative 'brute/tools/fs_read'
@@ -61,6 +88,7 @@ require_relative 'brute/tools/net_fetch'
 require_relative 'brute/tools/todo_write'
 require_relative 'brute/tools/todo_read'
 require_relative 'brute/tools/delegate'
+require_relative 'brute/tools/question'
 
 # Orchestrator (depends on tools, middleware, and infrastructure)
 require_relative 'brute/orchestrator'
@@ -78,7 +106,8 @@ module Brute
     Tools::NetFetch,
     Tools::TodoWrite,
     Tools::TodoRead,
-    Tools::Delegate
+    Tools::Delegate,
+    Tools::Question
   ].freeze
 
   # Default provider, resolved from environment.
@@ -91,13 +120,15 @@ module Brute
   end
 
   # Create a new orchestrator with sensible defaults.
-  def self.agent(cwd: Dir.pwd, tools: TOOLS, session: nil, reasoning: {}, **callbacks)
+  def self.agent(cwd: Dir.pwd, model: nil, tools: TOOLS, session: nil, reasoning: {}, agent_name: nil, **callbacks)
     Orchestrator.new(
       provider: provider,
+      model: model,
       tools: tools,
       cwd: cwd,
       session: session,
       reasoning: reasoning,
+      agent_name: agent_name,
       **callbacks
     )
   end
@@ -111,6 +142,35 @@ module Brute
     'xai' => ->(key) { LLM.xai(key: key) }
   }.freeze
 
+  # List provider names that have API keys configured in the environment.
+  def self.configured_providers
+    PROVIDERS.keys.select { |name| api_key_for(name) }
+  end
+
+  # Build a provider instance for the given name using available API keys.
+  # Returns nil if no key is found.
+  def self.provider_for(name)
+    key = api_key_for(name)
+    return nil unless key
+
+    factory = PROVIDERS[name]
+    return nil unless factory
+
+    factory.call(key)
+  end
+
+  # Look up the API key for a given provider name.
+  def self.api_key_for(name)
+    # Explicit generic key always works
+    return ENV["LLM_API_KEY"] if ENV["LLM_API_KEY"]
+
+    case name
+    when "anthropic" then ENV["ANTHROPIC_API_KEY"]
+    when "openai"    then ENV["OPENAI_API_KEY"]
+    when "google"    then ENV["GOOGLE_API_KEY"]
+    end
+  end
+
   # Resolve the LLM provider from environment variables.
   #
   # Checks in order:

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - Brute Contributors
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -92,10 +92,17 @@ files:
 - lib/brute/doom_loop.rb
 - lib/brute/file_mutation_queue.rb
 - lib/brute/hooks.rb
+- lib/brute/message_store.rb
 - lib/brute/middleware/base.rb
 - lib/brute/middleware/compaction_check.rb
 - lib/brute/middleware/doom_loop_detection.rb
 - lib/brute/middleware/llm_call.rb
+- lib/brute/middleware/message_tracking.rb
+- lib/brute/middleware/otel.rb
+- lib/brute/middleware/otel/span.rb
+- lib/brute/middleware/otel/token_usage.rb
+- lib/brute/middleware/otel/tool_calls.rb
+- lib/brute/middleware/otel/tool_results.rb
 - lib/brute/middleware/reasoning_normalizer.rb
 - lib/brute/middleware/retry.rb
 - lib/brute/middleware/session_persistence.rb
@@ -107,7 +114,49 @@ files:
 - lib/brute/patches/anthropic_tool_role.rb
 - lib/brute/patches/buffer_nil_guard.rb
 - lib/brute/pipeline.rb
+- lib/brute/prompts/autonomy.rb
+- lib/brute/prompts/base.rb
+- lib/brute/prompts/build_switch.rb
+- lib/brute/prompts/code_references.rb
+- lib/brute/prompts/code_style.rb
+- lib/brute/prompts/conventions.rb
+- lib/brute/prompts/doing_tasks.rb
+- lib/brute/prompts/editing_approach.rb
+- lib/brute/prompts/editing_constraints.rb
+- lib/brute/prompts/environment.rb
+- lib/brute/prompts/frontend_tasks.rb
+- lib/brute/prompts/git_safety.rb
+- lib/brute/prompts/identity.rb
+- lib/brute/prompts/instructions.rb
+- lib/brute/prompts/max_steps.rb
+- lib/brute/prompts/objectivity.rb
+- lib/brute/prompts/plan_reminder.rb
+- lib/brute/prompts/proactiveness.rb
+- lib/brute/prompts/security_and_safety.rb
+- lib/brute/prompts/skills.rb
+- lib/brute/prompts/task_management.rb
+- lib/brute/prompts/text/agents/compaction.txt
+- lib/brute/prompts/text/agents/explore.txt
+- lib/brute/prompts/text/agents/summary.txt
+- lib/brute/prompts/text/agents/title.txt
+- lib/brute/prompts/text/doing_tasks/anthropic.txt
+- lib/brute/prompts/text/doing_tasks/default.txt
+- lib/brute/prompts/text/doing_tasks/google.txt
+- lib/brute/prompts/text/identity/anthropic.txt
+- lib/brute/prompts/text/identity/default.txt
+- lib/brute/prompts/text/identity/google.txt
+- lib/brute/prompts/text/identity/openai.txt
+- lib/brute/prompts/text/tone_and_style/anthropic.txt
+- lib/brute/prompts/text/tone_and_style/default.txt
+- lib/brute/prompts/text/tone_and_style/google.txt
+- lib/brute/prompts/text/tone_and_style/openai.txt
+- lib/brute/prompts/text/tool_usage/anthropic.txt
+- lib/brute/prompts/text/tool_usage/default.txt
+- lib/brute/prompts/text/tool_usage/google.txt
+- lib/brute/prompts/tone_and_style.rb
+- lib/brute/prompts/tool_usage.rb
 - lib/brute/session.rb
+- lib/brute/skill.rb
 - lib/brute/snapshot_store.rb
 - lib/brute/system_prompt.rb
 - lib/brute/todo_store.rb
@@ -119,6 +168,7 @@ files:
 - lib/brute/tools/fs_undo.rb
 - lib/brute/tools/fs_write.rb
 - lib/brute/tools/net_fetch.rb
+- lib/brute/tools/question.rb
 - lib/brute/tools/shell.rb
 - lib/brute/tools/todo_read.rb
 - lib/brute/tools/todo_write.rb