brute 0.1.8 → 0.2.0

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,166 @@
 # 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.
+        # For gateway providers (opencode_zen, opencode_go), infer the
+        # upstream model family from the model name so we use the most
+        # appropriate prompt stack (e.g., anthropic stack for claude-*).
+        provider = ctx[:provider_name].to_s
+        stack_key = if provider.start_with?("opencode")
+                      infer_stack_from_model(ctx[:model_name].to_s)
+                    else
+                      provider
+                    end
+        STACKS.fetch(stack_key, 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
+    # Infer the best prompt stack from a model name.
+    # Used for gateway providers that route to multiple upstream model families.
+    def self.infer_stack_from_model(model_name)
+      case model_name
+      when /\bclaude\b/i, /\bbig.?pickle\b/i
+        "anthropic"
+      when /\bgpt\b/i, /\bo[134]\b/i, /\bcodex\b/i
+        "openai"
+      when /\bgemini\b/i, /\bgemma\b/i
+        "google"
+      else
+        "default"
+      end
     end
 
-    def environment_section
-      files = Dir.entries(@cwd).reject { |f| f.start_with?(".") }.sort.first(50)
-
-      <<~SECTION
-        # Environment
+    def initialize(block)
+      @block = block
+    end
 
-        - **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/delegate.rb

@@ -28,7 +28,31 @@ module Brute
           rounds += 1
         end
 
-        {result: res.content}
+        {result: extract_content(res, sub)}
+      end
+
+      private
+
+      # Safely extract text content from the sub-agent response.
+      #
+      # When the LLM returns only tool calls (no text content block),
+      # res.content raises NoMethodError because the response adapter's
+      # choices array is empty (it only maps over text blocks), or
+      # returns nil when the response has no text. Fall back to the
+      # last assistant text in the conversation history.
+      def extract_content(res, context)
+        text = begin
+          res.content
+        rescue NoMethodError
+          nil
+        end
+        return text if text.is_a?(::String) && !text.empty?
+
+        last_assistant = context.messages.to_a
+          .select(&:assistant?)
+          .reverse
+          .find { |m| m.content.is_a?(::String) && !m.content.empty? }
+        last_assistant&.content || "(sub-agent completed but produced no text response)"
       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.8"
+  VERSION = "0.2.0"
 end

data/lib/brute.rb

@@ -27,6 +27,30 @@ 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'
@@ -64,6 +88,14 @@ 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'
+
+# Providers
+require_relative 'brute/providers/shell_response'
+require_relative 'brute/providers/shell'
+require_relative 'brute/providers/models_dev'
+require_relative 'brute/providers/opencode_zen'
+require_relative 'brute/providers/opencode_go'
 
 # Orchestrator (depends on tools, middleware, and infrastructure)
 require_relative 'brute/orchestrator'
@@ -81,7 +113,8 @@ module Brute
     Tools::NetFetch,
     Tools::TodoWrite,
     Tools::TodoRead,
-    Tools::Delegate
+    Tools::Delegate,
+    Tools::Question
   ].freeze
 
   # Default provider, resolved from environment.
@@ -94,13 +127,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,9 +146,50 @@ module Brute
     'google' => ->(key) { LLM.google(key: key) },
     'deepseek' => ->(key) { LLM.deepseek(key: key) },
     'ollama' => ->(key) { LLM.ollama(key: key) },
-    'xai' => ->(key) { LLM.xai(key: key) }
+    'xai' => ->(key) { LLM.xai(key: key) },
+    'opencode_zen' => ->(key) { LLM::OpencodeZen.new(key: key) },
+    'opencode_go' => ->(key) { LLM::OpencodeGo.new(key: key) },
+    'shell' => ->(_key) { Providers::Shell.new },
   }.freeze
 
+  # List provider names that have API keys configured in the environment.
+  # The shell provider is always available (no key needed).
+  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)
+    # Shell provider needs no key.
+    return "none" if name == "shell"
+
+    # OpenCode providers: check OPENCODE_API_KEY, fall back to "public" for anonymous access.
+    if name == "opencode_zen" || name == "opencode_go"
+      return ENV["OPENCODE_API_KEY"] || "public"
+    end
+
+    # 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:
@@ -121,6 +197,7 @@ module Brute
   #   2. ANTHROPIC_API_KEY (implicit: provider = anthropic)
   #   3. OPENAI_API_KEY   (implicit: provider = openai)
   #   4. GOOGLE_API_KEY   (implicit: provider = google)
+  #   5. OPENCODE_API_KEY  (implicit: provider = opencode_zen)
   #
   # Returns nil if no key is found. Error is deferred to Orchestrator#run.
   def self.resolve_provider
@@ -136,6 +213,9 @@ module Brute
     elsif ENV['GOOGLE_API_KEY']
       key = ENV['GOOGLE_API_KEY']
       name = 'google'
+    elsif ENV['OPENCODE_API_KEY']
+      key = ENV['OPENCODE_API_KEY']
+      name = 'opencode_zen'
     else
       return nil
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - Brute Contributors
@@ -114,7 +114,54 @@ 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/providers/models_dev.rb
+- lib/brute/providers/opencode_go.rb
+- lib/brute/providers/opencode_zen.rb
+- lib/brute/providers/shell.rb
+- lib/brute/providers/shell_response.rb
 - lib/brute/session.rb
+- lib/brute/skill.rb
 - lib/brute/snapshot_store.rb
 - lib/brute/system_prompt.rb
 - lib/brute/todo_store.rb
@@ -126,6 +173,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