rubycode 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00132f001573596d0454dcb6765fc7c5fab4118e99d8755b67d0c7ff9140af81
-  data.tar.gz: 9f30d9d75328c0cfab381a02b1d457aaa67eef4f81cc5e535b8df25aae06e05a
+  metadata.gz: e4bc11cde6a1cf792d500338c15529b2d9599a9c79d917aba62b548ec67a234e
+  data.tar.gz: e221bd379bec42cac844889163a58d7f9bc2d3592453617884ea44cd0ab46211
 SHA512:
-  metadata.gz: 432f02b74ee9bdb44ddddc1d6aa5d8862eb7914081850e393775470dc79fa20d395a8b32d89539f3a280cb5c3c6e03221d75b5b4a266b4ac1ce033eddc1593b0
-  data.tar.gz: 35983e256acdd200562446e929f93217dcc9b6bbee6484043bba42ac227ee0e5e382aff1159c3921cb88e6387d89be7521d69d8c6bf4514c89b25fe2b5d29190
+  metadata.gz: f8f83579fbbff76245c88310f9cfe35977ab2dbd762c151aaaac0ffafbb4679dd44f7518e5c7e8f62b8f4b32bfa17bb5eefc2de1cfb32eec4122aed16b17d75f
+  data.tar.gz: bd9316933c2f74cbf8da7c345b8cea7c90224cc490bc67a9297346c128c5396bbf6ca0a410231625cbf2c95b6c66c7ec060e1a4b36d08e14342894d41acbc06b

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.1.7] - 2026-03-08
+
+### Fixed
+- **Plan Mode Workflow**: Removed redundant "Describe what you want to implement" prompt
+  - Now uses original user input for both exploration and implementation
+  - User only describes task once, not twice
+  - Clearer approval prompt: "Do you accept this exploration and want to proceed?"
+- **Exploration Behavior**: Enhanced to prevent hitting max iterations
+  - Exploration prompt now emphasizes MUST use `done` tool
+  - Added "When to Call done" section with clear guidance (8-10 iterations)
+  - Added example `done` call format
+  - Updated critical rules to prevent iteration loops
+
+### Changed
+- **CLI Messages**: Improved clarity throughout plan mode workflow
+  - Plan mode entry shows 4-step process
+  - Status message during exploration: "🔍 Exploring codebase for: {task}"
+  - Implementation message: "✓ Plan accepted. Proceeding with implementation (auto-approve enabled)..."
+
 ## [0.1.6] - 2026-03-08
 
 ### Added

data/README.md

@@ -18,12 +18,18 @@ A Ruby-native AI coding assistant with pluggable LLM adapters. RubyCode provides
 - **AI Agent Loop**: Autonomous task execution with tool calling
 - **Multiple Cloud LLM Adapters**: Support for Ollama Cloud, DeepSeek, Gemini, OpenAI, and OpenRouter
 - **Interactive Setup Wizard**: First-time configuration with provider selection and API key management
+- **Plan Mode**: Interactive planning workflow with autonomous codebase exploration
+  - Enter with `plan mode` command
+  - AI explores codebase and presents findings
+  - User approves plan before implementation
+  - Auto-approve enabled during implementation
 - **Built-in Tools**:
   - `bash`: Execute safe bash commands for filesystem exploration
   - `search`: Search file contents using grep with regex support
   - `read`: Read files and directories with line numbers
   - `write`: Create new files with user approval
   - `update`: Edit existing files with user approval
+  - `explore`: Autonomous codebase exploration agent (read-only)
   - `web_search`: Search the internet with automatic provider fallback (DuckDuckGo/Brave/Exa)
   - `fetch`: Fetch content from URLs
   - `done`: Signal task completion with final answer
@@ -76,6 +82,49 @@ The first time you run it, an interactive setup wizard will guide you through:
 
 Your configuration is automatically saved and reloaded on subsequent runs.
 
+#### CLI Commands
+
+Once running, you have access to these special commands:
+
+- `plan mode` or `plan` - Enter plan mode for guided exploration and implementation
+- `auto-approve on` - Enable auto-approval for write operations
+- `auto-approve off` - Disable auto-approval
+- `auto-approve status` - Check auto-approval status
+- `config` - View/reconfigure settings
+- `clear` - Clear conversation history
+- `exit` or `quit` - Exit the CLI
+
+#### Using Plan Mode
+
+Plan mode provides a structured workflow for complex tasks:
+
+1. Type `plan mode` to enter
+2. Describe what you want to explore/implement (e.g., "add user authentication")
+3. AI autonomously explores the codebase using the explore tool
+4. Review the exploration findings and plan
+5. Accept or reject the plan
+6. If accepted, describe the implementation and AI proceeds with auto-approve enabled
+
+Example session:
+```
+You: plan mode
+📋 Entering Plan Mode
+Next: Describe what you want to explore and implement.
+
+You: add JWT authentication to the API
+
+🔍 Exploring codebase...
+[AI explores and presents findings]
+
+Do you accept this plan? (Y/n) y
+
+✓ Plan accepted. Auto-approve enabled for implementation.
+
+Describe what you want to implement: add JWT token generation to User model
+
+[AI implements changes without requiring approval for each file]
+```
+
 ### Programmatic Usage
 
 You can also use RubyCode in your Ruby projects:
@@ -161,12 +210,17 @@ The agent has access to several built-in tools:
 3. **read**: Read files with line numbers or list directory contents
 4. **write**: Create new files (requires user approval)
 5. **update**: Edit existing files with exact string replacement (requires user approval)
-6. **web_search**: Search the internet with automatic provider fallback (requires user approval):
+6. **explore**: Autonomous codebase exploration agent (read-only):
+   - Spawns sub-agent with constrained tools (bash, read, search, web_search, fetch, done)
+   - Configurable max iterations (default: 10, max: 15)
+   - Returns structured findings with summary, key files, and code flow
+   - Used automatically in plan mode
+7. **web_search**: Search the internet with automatic provider fallback (requires user approval):
    - Primary: Exa.ai (AI-native search, optional with API key)
    - Fallback 1: DuckDuckGo Instant Answer API (free, no API key)
    - Fallback 2: Brave Search API (optional, for better results)
-7. **fetch**: Fetch and extract text content from URLs (requires user approval)
-8. **done**: Signal completion and provide the final answer
+8. **fetch**: Fetch and extract text content from URLs (requires user approval)
+9. **done**: Signal completion and provide the final answer
 
 **Note**: Tool schemas are externalized in `config/tools/*.json` for easy customization.
 
@@ -188,6 +242,19 @@ export EXA_API_KEY=your_api_key_here
 export BRAVE_API_KEY=your_api_key_here
 ```
 
+### New in 0.1.6
+
+- **Plan Mode**: Interactive planning workflow with autonomous codebase exploration
+  - Enter with `plan mode` or `plan` command
+  - AI explores and presents findings for user approval
+  - Auto-approve enabled for implementation after plan acceptance
+- **Auto-Approve Commands**: Manual control over write operation approvals
+  - `auto-approve on/off/status` for toggling and checking approval mode
+- **Explore Tool**: Autonomous read-only codebase exploration agent
+  - Constrained sub-agent with dedicated exploration prompt
+  - Structured output with summary, key files, and code flow
+  - Configurable iteration limits (10 default, 15 max)
+
 ### New in 0.1.5
 
 - **CLI Executable**: `rubycode_client` command for interactive chat after gem installation

data/config/exploration_prompt.md

@@ -2,7 +2,10 @@
 
 You are an expert codebase explorer. Your goal is to thoroughly explore the codebase to answer the user's question.
 
-**IMPORTANT: This is READ-ONLY exploration. You cannot modify any files.**
+**CRITICAL RULES:**
+1. This is READ-ONLY exploration. You cannot modify any files.
+2. You MUST call the `done` tool when you have findings to present.
+3. Do NOT exceed 10-15 iterations. Explore efficiently and present findings promptly.
 
 ## Available Tools
 
@@ -49,8 +52,26 @@ When you finish exploring, use the 'done' tool with this structured format:
 ## Important Reminders
 
 - **READ-ONLY MODE**: You cannot write, update, or modify any files
+- **MUST USE `done` TOOL**: Always call `done` with your findings (typically after 5-10 iterations)
 - Be thorough but efficient with your iterations
 - Actually read the files you identify as important
 - If stuck, try web search for documentation
 - Focus on answering the user's specific question, not general exploration
 - Your findings will help the user plan their implementation
+
+## When to Call `done`
+
+Call `done` after you have:
+- Identified the key files relevant to the query
+- Understood the current implementation or architecture
+- Found enough information to answer the user's question
+- Reached 8-10 iterations (don't wait for max iterations!)
+
+**Example `done` call:**
+```
+Use the done tool with a structured markdown summary of your findings including:
+- Summary of what you found
+- Key files and their purposes
+- Code flow or architecture notes
+- Recommendations for implementation
+```

data/exe/rubycode_client

@@ -285,22 +285,22 @@ end
 
 def process_user_message(client, user_input, context)
   if context.plan_mode
-    # In plan mode - use explore tool then ask for approval
+    # In plan mode - explore codebase first
+    puts "\n🔍 Exploring codebase for: #{user_input}\n"
     response = client.ask(prompt: "Use the explore tool with this query: #{user_input}")
     puts RubyCode::Views::Cli::ResponseBox.build(response: response)
 
     # Ask user if they accept the plan
-    accept_plan = context.prompt.yes?("\nDo you accept this plan and want to proceed with implementation?",
+    accept_plan = context.prompt.yes?("\n📋 Do you accept this exploration and want to proceed with implementation?",
                                       default: true)
 
     if accept_plan
-      puts "\n✓ Plan accepted. Auto-approve enabled for implementation.\n"
+      puts "\n✓ Plan accepted. Proceeding with implementation (auto-approve enabled)...\n"
       # Enable auto-approve for implementation
       client.approval_handler.enable_auto_approve_write
 
-      # Ask for implementation prompt
-      impl_prompt = context.prompt.ask("Describe what you want to implement:")
-      response = client.ask(prompt: impl_prompt)
+      # Use the ORIGINAL user input as the implementation task
+      response = client.ask(prompt: user_input)
       puts RubyCode::Views::Cli::ResponseBox.build(response: response)
 
       # Disable auto-approve after implementation

data/lib/rubycode/version.rb

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

data/lib/rubycode/views/cli/plan_mode_enter.rb

@@ -10,8 +10,8 @@ module RubyCode
         def self.build
           pastel = Pastel.new
           "\n#{pastel.cyan("📋")} Entering Plan Mode\n" \
-            "Next: Describe what you want to explore and implement.\n" \
-            "The AI will explore the codebase, present a plan, and ask for your approval.\n\n"
+            "Next: Describe your task (e.g., 'add user authentication').\n" \
+            "AI will: 1) Explore codebase  2) Show findings  3) Ask approval  4) Implement if approved\n\n"
         end
       end
     end

data/rubycode_cli.rb

@@ -285,22 +285,22 @@ end
 
 def process_user_message(client, user_input, context)
   if context.plan_mode
-    # In plan mode - use explore tool then ask for approval
+    # In plan mode - explore codebase first
+    puts "\n🔍 Exploring codebase for: #{user_input}\n"
     response = client.ask(prompt: "Use the explore tool with this query: #{user_input}")
     puts RubyCode::Views::Cli::ResponseBox.build(response: response)
 
     # Ask user if they accept the plan
-    accept_plan = context.prompt.yes?("\nDo you accept this plan and want to proceed with implementation?",
+    accept_plan = context.prompt.yes?("\n📋 Do you accept this exploration and want to proceed with implementation?",
                                       default: true)
 
     if accept_plan
-      puts "\n✓ Plan accepted. Auto-approve enabled for implementation.\n"
+      puts "\n✓ Plan accepted. Proceeding with implementation (auto-approve enabled)...\n"
       # Enable auto-approve for implementation
       client.approval_handler.enable_auto_approve_write
 
-      # Ask for implementation prompt
-      impl_prompt = context.prompt.ask("Describe what you want to implement:")
-      response = client.ask(prompt: impl_prompt)
+      # Use the ORIGINAL user input as the implementation task
+      response = client.ask(prompt: user_input)
       puts RubyCode::Views::Cli::ResponseBox.build(response: response)
 
       # Disable auto-approve after implementation

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubycode
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Jonas Medeiros
@@ -232,7 +232,6 @@ files:
 - ".env.example"
 - ".rubocop.yml"
 - CHANGELOG.md
-- EXPLORE_TOOL_DESIGN.md
 - LICENSE.txt
 - README.md
 - Rakefile

data/EXPLORE_TOOL_DESIGN.md

@@ -1,375 +0,0 @@
-# Explore Tool Design for RubyCode
-
-## Overview
-An intelligent codebase exploration tool that combines file discovery, content search, and automatic summarization.
-
-## How Claude Code's Explore Works
-
-Claude Code's Explore agent:
-1. Takes a natural language query (e.g., "how does authentication work?")
-2. Automatically uses multiple tools (Glob, Grep, Read) in sequence
-3. Follows breadcrumbs and references
-4. Builds a mental map of the codebase
-5. Returns a comprehensive answer
-
-## Implementation Approach for RubyCode
-
-### Option 1: Single Explore Tool (Recommended)
-Create a new `explore` tool that acts as an intelligent wrapper.
-
-**Tool Definition** (`config/tools/explore.json`):
-```json
-{
-  "type": "function",
-  "function": {
-    "name": "explore",
-    "description": "Intelligently explore the codebase to answer questions. Automatically finds relevant files, searches content, and builds context. Use this for questions like 'how does X work?', 'where is Y implemented?', 'what files handle Z?'",
-    "parameters": {
-      "type": "object",
-      "properties": {
-        "query": {
-          "type": "string",
-          "description": "Natural language question or exploration goal (e.g., 'how does user authentication work?')"
-        },
-        "thoroughness": {
-          "type": "string",
-          "enum": ["quick", "medium", "thorough"],
-          "description": "How deep to explore. 'quick' = 1-2 passes, 'medium' = 3-5 passes, 'thorough' = 5-10 passes. Default: 'medium'"
-        },
-        "focus_paths": {
-          "type": "array",
-          "items": {"type": "string"},
-          "description": "Optional array of directory paths to focus on (e.g., ['app/models', 'lib/auth'])"
-        }
-      },
-      "required": ["query"]
-    }
-  }
-}
-```
-
-**Implementation** (`lib/rubycode/tools/explore.rb`):
-```ruby
-module RubyCode
-  module Tools
-    class Explore < Base
-      def execute(params)
-        query = params["query"]
-        thoroughness = params["thoroughness"] || "medium"
-        focus_paths = params["focus_paths"] || ["."]
-
-        # Create a mini-agent that explores
-        explorer = Explorer.new(
-          root_path: context[:root_path],
-          query: query,
-          thoroughness: thoroughness,
-          focus_paths: focus_paths
-        )
-
-        result = explorer.run
-
-        CommandResult.new(
-          success: true,
-          output: result.summary,
-          metadata: {
-            files_examined: result.files_examined,
-            patterns_found: result.patterns_found
-          }
-        )
-      end
-    end
-  end
-end
-```
-
-**Explorer Engine** (`lib/rubycode/explorer.rb`):
-```ruby
-module RubyCode
-  class Explorer
-    MAX_ITERATIONS = {
-      "quick" => 3,
-      "medium" => 7,
-      "thorough" => 15
-    }.freeze
-
-    def initialize(root_path:, query:, thoroughness:, focus_paths:)
-      @root_path = root_path
-      @query = query
-      @max_iterations = MAX_ITERATIONS[thoroughness]
-      @focus_paths = focus_paths
-      @examined_files = []
-      @findings = []
-    end
-
-    def run
-      # Phase 1: Keyword extraction
-      keywords = extract_keywords(@query)
-
-      # Phase 2: File discovery
-      candidate_files = discover_files(keywords)
-
-      # Phase 3: Content analysis
-      analyze_content(candidate_files, keywords)
-
-      # Phase 4: Follow references
-      follow_references(keywords)
-
-      # Phase 5: Summarize findings
-      summarize
-    end
-
-    private
-
-    def extract_keywords(query)
-      # Extract relevant keywords from query
-      # Remove stop words, extract technical terms
-      words = query.downcase.split(/\s+/)
-      stop_words = %w[how does what where is the a an in on at to for of with]
-      words - stop_words
-    end
-
-    def discover_files(keywords)
-      files = []
-
-      # Try file name patterns
-      keywords.each do |keyword|
-        # Try exact match
-        files += glob_search("**/*#{keyword}*")
-
-        # Try snake_case variant
-        snake = keyword.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '')
-        files += glob_search("**/*#{snake}*")
-
-        # Try camel_case variant
-        camel = keyword.split('_').map(&:capitalize).join
-        files += glob_search("**/*#{camel}*")
-      end
-
-      files.uniq
-    end
-
-    def analyze_content(files, keywords)
-      files.first(20).each do |file|
-        next if @examined_files.include?(file)
-
-        content = read_file(file)
-        next unless content
-
-        # Check if file is relevant
-        relevance_score = calculate_relevance(content, keywords)
-
-        if relevance_score > 0.3
-          @findings << {
-            file: file,
-            score: relevance_score,
-            snippets: extract_relevant_snippets(content, keywords)
-          }
-        end
-
-        @examined_files << file
-      end
-    end
-
-    def follow_references(keywords)
-      # Look for requires, includes, imports
-      @findings.each do |finding|
-        content = read_file(finding[:file])
-
-        # Extract references (require, include, etc.)
-        references = extract_references(content)
-
-        # Recursively explore referenced files
-        references.each do |ref|
-          ref_file = resolve_reference(ref)
-          next unless ref_file
-
-          analyze_content([ref_file], keywords)
-        end
-      end
-    end
-
-    def summarize
-      # Build a structured summary
-      summary = "# Exploration Results for: #{@query}\n\n"
-      summary += "Examined #{@examined_files.length} files\n\n"
-
-      # Group findings by relevance
-      top_findings = @findings.sort_by { |f| -f[:score] }.first(10)
-
-      summary += "## Most Relevant Files:\n\n"
-      top_findings.each do |finding|
-        summary += "**#{finding[:file]}** (relevance: #{(finding[:score] * 100).round}%)\n"
-        finding[:snippets].each do |snippet|
-          summary += "  - Line #{snippet[:line]}: #{snippet[:text]}\n"
-        end
-        summary += "\n"
-      end
-
-      ExplorerResult.new(
-        summary: summary,
-        files_examined: @examined_files.length,
-        patterns_found: @findings.length
-      )
-    end
-
-    # Helper methods
-    def glob_search(pattern)
-      Dir.glob(File.join(@root_path, pattern)).select { |f| File.file?(f) }
-    end
-
-    def read_file(path)
-      File.read(path) rescue nil
-    end
-
-    def calculate_relevance(content, keywords)
-      matches = keywords.sum { |kw| content.scan(/#{Regexp.escape(kw)}/i).length }
-      matches.to_f / (content.length / 100.0)
-    end
-
-    def extract_relevant_snippets(content, keywords)
-      snippets = []
-      content.lines.each_with_index do |line, idx|
-        if keywords.any? { |kw| line.match?(/#{Regexp.escape(kw)}/i) }
-          snippets << { line: idx + 1, text: line.strip }
-        end
-      end
-      snippets.first(5)
-    end
-
-    def extract_references(content)
-      references = []
-
-      # Ruby requires
-      content.scan(/require\s+['"](.+?)['"]/) { references << $1 }
-      content.scan(/require_relative\s+['"](.+?)['"]/) { references << $1 }
-
-      references
-    end
-
-    def resolve_reference(ref)
-      # Try to find the actual file
-      possible_paths = [
-        "#{ref}.rb",
-        "lib/#{ref}.rb",
-        "app/#{ref}.rb"
-      ]
-
-      possible_paths.find { |p| File.exist?(File.join(@root_path, p)) }
-    end
-  end
-
-  ExplorerResult = Struct.new(:summary, :files_examined, :patterns_found, keyword_init: true)
-end
-```
-
-### Option 2: Sub-Agent Approach (More Advanced)
-
-Create a separate mini-agent that has access to a limited set of tools and runs autonomously:
-
-```ruby
-class ExploreAgent
-  def initialize(query:, root_path:, thoroughness:)
-    @query = query
-    @root_path = root_path
-    @memory = Memory.new
-    @adapter = RubyCode.configuration.adapter
-    @max_iterations = thoroughness_to_iterations(thoroughness)
-  end
-
-  def run
-    # Give the sub-agent a focused prompt
-    prompt = build_exploration_prompt(@query)
-    @memory.add_message(role: "user", content: prompt)
-
-    # Run mini agent loop with limited tools
-    agent_loop = AgentLoop.new(
-      adapter: @adapter,
-      memory: @memory,
-      config: exploration_config,
-      system_prompt: exploration_system_prompt,
-      max_iterations: @max_iterations
-    )
-
-    agent_loop.run
-  end
-
-  private
-
-  def exploration_config
-    # Limited config for sub-agent
-    config = RubyCode::Configuration.new
-    config.root_path = @root_path
-    config.memory_window = 5 # Smaller window
-    config
-  end
-
-  def exploration_system_prompt
-    <<~PROMPT
-      You are an expert codebase explorer. Your goal is to thoroughly explore
-      the codebase to answer the user's question. You have access to these tools:
-
-      - bash: Run ls, find, tree commands to discover files
-      - search: Search file contents for patterns
-      - read: Read specific files
-      - done: Finish with your findings
-
-      Be thorough but efficient. Follow these steps:
-      1. Identify key terms from the question
-      2. Search for relevant files and code
-      3. Read the most promising files
-      4. Follow references and imports
-      5. Summarize your findings
-
-      Use 'done' when you have a comprehensive answer.
-    PROMPT
-  end
-
-  def build_exploration_prompt(query)
-    "Explore the codebase to answer this question: #{query}\n\n" \
-    "Provide a comprehensive answer with file references and code snippets."
-  end
-end
-```
-
-## Comparison
-
-| Approach | Pros | Cons |
-|----------|------|------|
-| **Single Tool** | Simple, fast, deterministic | Less flexible, hardcoded logic |
-| **Sub-Agent** | Intelligent, adaptable, can reason | Higher token cost, slower |
-
-## Recommendation
-
-**Start with Option 1 (Single Tool)**, then evolve to Option 2 if needed:
-
-1. **Phase 1**: Implement basic explore tool with keyword extraction
-2. **Phase 2**: Add pattern matching and file scoring
-3. **Phase 3**: Add reference following
-4. **Phase 4**: Consider sub-agent for complex queries
-
-## Token Efficiency
-
-The sub-agent approach uses more tokens but provides better results:
-
-- **Single tool**: ~500-1000 tokens per exploration
-- **Sub-agent**: ~5000-15000 tokens per exploration
-
-You could make it configurable:
-
-```ruby
-# Quick exploration (single tool)
-explore(query: "find authentication", mode: "fast")
-
-# Deep exploration (sub-agent)
-explore(query: "how does authentication work?", mode: "deep")
-```
-
-## Next Steps
-
-1. Create `lib/rubycode/tools/explore.rb`
-2. Create `lib/rubycode/explorer.rb`
-3. Create `config/tools/explore.json`
-4. Add tests in `test/test_explore_tool.rb`
-5. Update README with explore tool documentation
-
-Would you like me to implement the basic version (Option 1)?