ralph.rb 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3950370724ceca76366a10ef15914ab10abc209595d1a5c8ddc466c071ea032
-  data.tar.gz: 0f85bc6a1f1a00d98ee6940928ce3ba506f6591536e14e4eb0cd30c3e6e914db
+  metadata.gz: 5554c13454fc43d04f41b7f969653cb7d51243eb40df245aefad31d82b38ab3a
+  data.tar.gz: 97909bf34b37d86ed11815c332f6ef6ba747c82c5ae60ded0e4b184a1d4a8120
 SHA512:
-  metadata.gz: 181d38c7c1e72fd04ac4b22118a09caac7f262d7037d4e1c42f4f3440bac0b6a3c3b08d48934b2083ec3972a241457a18770c3f6c0038d82bd3ae33afd790416
-  data.tar.gz: 1feee430c07868a4877f351c1dcef388f42b99cb1db33b1c7515e22aeda33dba7ac0ce1abd5568c1315ded580f674f48f394909db2267d26bc9a64092e8d62e9
+  metadata.gz: 6cab0f8e38f76a14251de705f0404ed443b9d597ddd93c3ba51a4a46f8ba8db5849d5819570034c95d70e9fbe95a4a4bf576df35564d0405c393eaaf7a1765e5
+  data.tar.gz: 2c9e36d50e6f304a018cac0deaba455421f67b5199e36b756dcffe9adb35fb443f9eaf09d8279231c3c85df10adbff1b88407a4d826cb2f3a7acb0a594c339ff

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ralph.rb (1.2.435535439)
+    ralph.rb (2.0.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <h1 align="center">Open Ralph Wiggum</h1>
-  <h3 align="center">Autonomous Agentic Loop for Claude Code, Codex & OpenCode</h3>
+  <h1 align="center">Ralph.rb</h1>
+  <h3 align="center">Autonomous Agentic Loop for OpenCode</h3>
 </p>
 
 <p align="center">
-  <img src="screenshot.webp" alt="Open Ralph Wiggum - Iterative AI coding loop for Claude Code and Codex" />
+  <img src="ralph.jpg" alt="Ralph Wiggum - Iterative AI coding loop for Opencode" />
 </p>
 
 <p align="center">
@@ -13,11 +13,6 @@
   <em>Based on the <a href="https://ghuntley.com/ralph/">Ralph Wiggum technique</a> by Geoffrey Huntley</em>
 </p>
 
-<p align="center">
-  <a href="https://github.com/Th0rgal/ralph-wiggum/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
-  <a href="https://github.com/Th0rgal/ralph-wiggum"><img src="https://img.shields.io/badge/built%20with-Bun%20%2B%20TypeScript-f472b6.svg" alt="Built with Bun + TypeScript"></a>
-  <a href="https://github.com/Th0rgal/ralph-wiggum/releases"><img src="https://img.shields.io/github/v/release/Th0rgal/ralph-wiggum?include_prereleases" alt="Release"></a>
-</p>
 
 <p align="center">
   <a href="#supported-agents">Supported Agents</a> •

data/lib/ralph/cli.rb

@@ -1,14 +1,22 @@
 # frozen_string_literal: true
 
 module Ralph
-  # Command-line interface for ralph. Parses arguments, reads stdin when piped,
-  # combines everything into a prompt, and launches the Loop.
+  # Command-line interface for ralph. Parses subcommands (build/plan),
+  # arguments, reads stdin when piped, and launches the Loop.
   #
   # Usage:
-  #   cat prompt.md | ralph "extra instructions" --model=opus-4.5 --max-iterations=10
+  #   ralph build "focus on auth" --model=opus-4.5 --max-iterations=10
+  #   ralph plan "user authentication system"
+  #   ralph --max-iterations=10  # equivalent to: ralph build --max-iterations=10
+  #   cat prompt.md | ralph build --model=opus-4.5
   class CLI
+    SUBCOMMANDS = %w[build plan].freeze
+
+    attr_reader :subcommand
+
     def initialize(argv)
       @argv = argv.dup
+      @subcommand = extract_subcommand
       @options = {
         model: nil,
         max_iterations: nil,
@@ -20,84 +28,113 @@ module Ralph
 
     def run
       parse_options
-      build_prompt.then do |prompt|
-        if prompt.nil? || prompt.strip.empty?
-          $stderr.puts "Error: no prompt provided."
-          $stderr.puts "Usage: ralph \"your prompt\" [options]"
-          $stderr.puts "       cat prompt.md | ralph [options]"
-          $stderr.puts
-          $stderr.puts parser.help
-          exit 1
-        else
-          @options[:prompt] = prompt
-          Ralph::Loop.new(@options).run
-        end
-      end
-    end
+      prompt_object = build_prompt_object
+      @options[:prompt] = prompt_object
 
-    private
+      Ralph::Loop.new(@options).run
 
-    def parse_options
-      parser.parse!(@argv)
     rescue OptionParser::InvalidOption, OptionParser::MissingArgument => error
       $stderr.puts "Error: #{error.message}"
       $stderr.puts parser.help
       exit 1
     end
 
-    def parser
-      @parser ||= OptionParser.new do |option_parser|
-        option_parser.banner = "Usage: ralph [prompt] [options]"
-        option_parser.separator ""
-        option_parser.separator "Options:"
-
-        option_parser.on("--model=MODEL", "Model to use (e.g. opus-4.5)") do |value|
-          @options[:model] = value
-        end
+    private
 
-        option_parser.on("--max-iterations=N", Integer, "Maximum number of iterations") do |value|
-          @options[:max_iterations] = value
+      def extract_subcommand
+        if @argv.first && SUBCOMMANDS.include?(@argv.first)
+          @argv.shift
+        else
+          "build"
         end
+      end
 
-        option_parser.on("--duration=SECONDS", Integer, "Maximum total duration in seconds") do |value|
-          @options[:duration] = value
+      def parse_options
+        parser.parse!(@argv)
+      end
+      
+      def parser
+        @parser ||= OptionParser.new do |option_parser|
+          option_parser.banner = "Usage: ralph [build|plan] [text] [options]"
+          option_parser.separator ""
+          option_parser.separator "Subcommands:"
+          option_parser.separator "  build    Implement tasks from the plan (default)"
+          option_parser.separator "  plan     Gap analysis and plan generation"
+          option_parser.separator ""
+          option_parser.separator "Options:"
+
+          option_parser.on("--model=MODEL", "Model to use (e.g. opus-4.5)") do |value|
+            @options[:model] = value
+          end
+
+          option_parser.on("--max-iterations=N", Integer, "Maximum number of iterations") do |value|
+            @options[:max_iterations] = value
+          end
+
+          option_parser.on("--duration=SECONDS", Integer, "Maximum total duration in seconds") do |value|
+            @options[:duration] = value
+          end
+
+          option_parser.on("--max-context=N", Integer, "Maximum context tokens before iteration restart") do |value|
+            @options[:max_context] = value
+          end
+
+          option_parser.on("--completion=STRING", "Completion string the agent emits when done") do |value|
+            @options[:completion] = value
+          end
+
+          option_parser.on("-h", "--help", "Show this help message") do
+            puts option_parser
+            exit 0
+          end
+
+          option_parser.on("-v", "--version", "Show version") do
+            puts "ralph #{Ralph::VERSION}"
+            exit 0
+          end
         end
+      end
 
-        option_parser.on("--max-context=N", Integer, "Maximum context tokens before iteration restart") do |value|
-          @options[:max_context] = value
-        end
+      def read_user_text
+        parts = []
 
-        option_parser.on("--completion=STRING", "Completion string the agent emits when done") do |value|
-          @options[:completion] = value
+        # Read from stdin if data is being piped in
+        unless $stdin.tty?
+          stdin_content = $stdin.read
+          parts << stdin_content if stdin_content && !stdin_content.strip.empty?
         end
 
-        option_parser.on("-h", "--help", "Show this help message") do
-          puts option_parser
-          exit 0
-        end
+        # Remaining positional arguments are the inline text
+        parts << @argv.join(" ") if @argv.any?
 
-        option_parser.on("-v", "--version", "Show version") do
-          puts "ralph #{Ralph::VERSION}"
-          exit 0
-        end
+        parts.join("\n\n") if parts.any?
       end
-    end
 
-    def build_prompt
-      parts = []
+      def build_prompt_object
+        user_text = read_user_text
+        completion = @options[:completion]
 
-      # Read from stdin if data is being piped in
-      unless $stdin.tty?
-        stdin_content = $stdin.read
-        parts << stdin_content if stdin_content && !stdin_content.strip.empty?
+        if @subcommand == "plan"
+          build_plan_prompt(user_text, completion)
+        else
+          build_build_prompt(user_text, completion)
+        end
       end
 
-      # Remaining positional arguments are the inline prompt
-      parts << @argv.join(" ") if @argv.any?
+      def build_plan_prompt(user_text, completion)
+        Hash.new.then do |plan_options|
+          plan_options[:goal] = user_text if user_text
+          plan_options[:all_done] = completion if completion
+          Prompt::Plan.new(**plan_options)
+        end
+      end
 
-      if parts.any?
-        parts.join("\n\n")
+      def build_build_prompt(user_text, completion)
+        Hash.new.then do |build_options|
+          build_options[:context] = user_text if user_text
+          build_options[:all_done] = completion if completion
+          Prompt::Build.new(**build_options)
+        end
       end
-    end
   end
 end

data/lib/ralph/display.rb

@@ -60,6 +60,11 @@ module Ralph
       puts "  ** Iteration cancelled: #{reason}"
     end
 
+    def show_iteration_error(message)
+      puts
+      puts "  ** Iteration error: #{message}"
+    end
+
     def show_termination(reason)
       puts
       puts "  ** Loop terminated: #{reason}"

data/lib/ralph/iteration.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Ralph
+  # Represents a single execution cycle within the loop. Runs the agent with
+  # the prompt, monitors events, detects signals, and can be cancelled at
+  # any time. Tracks the outcome of the iteration (task-done, all-done,
+  # context guard, error, etc.).
+  class Iteration
+    OUTCOMES = %i[task_done all_done context_limit duration_limit error].freeze
+
+    attr_reader :number, :outcome
+
+    def initialize(number:, prompt_text:, model:, task_done_string:, all_done_string:, metrics:, display:)
+      @number = number
+      @prompt_text = prompt_text
+      @model = model
+      @task_done_string = task_done_string
+      @all_done_string = all_done_string
+      @metrics = metrics
+      @display = display
+      @outcome = nil
+      @agent = nil
+    end
+
+    # Run the iteration. Yields control back to the loop via the check block
+    # which determines if the iteration should be cancelled due to external
+    # limits (context, duration). Returns the outcome symbol.
+    def run(max_context: nil, duration_exceeded: nil)
+      @agent = Opencode.new(model: @model)
+
+      @agent.run(@prompt_text) do |event|
+        @metrics.process(event)
+        @display.show_event(event)
+
+        if event.is_a?(Events::Text)
+          check_signals(event.text)
+        end
+
+        if @outcome
+          @agent.cancel
+          break
+        end
+
+        if max_context && @metrics.current_context >= max_context
+          @outcome = :context_limit
+          @display.show_iteration_cancelled(
+            "context limit reached (#{@metrics.current_context}/#{max_context})"
+          )
+          @agent.cancel
+          break
+        end
+
+        if duration_exceeded&.call
+          @outcome = :duration_limit
+          @display.show_iteration_cancelled("duration limit reached")
+          @agent.cancel
+          break
+        end
+      end
+    rescue Errno::ENOENT => error
+      @outcome = :error
+      @display.show_iteration_error("agent not found: #{error.message}")
+    rescue IOError, Errno::EPIPE => error
+      @outcome = :error
+      @display.show_iteration_error("agent communication error: #{error.message}")
+    rescue StandardError => error
+      @outcome = :error
+      @display.show_iteration_error("unexpected error: #{error.message}")
+    ensure
+      @outcome ||= :unknown
+    end
+
+    # Whether this iteration ended because the agent signaled task-done
+    def task_done?
+      @outcome == :task_done
+    end
+
+    # Whether this iteration ended because the agent signaled all-done
+    def all_done?
+      @outcome == :all_done
+    end
+
+    # Whether this iteration ended due to an error
+    def error?
+      @outcome == :error
+    end
+
+    private
+
+    def check_signals(text)
+      if text
+        if text.include?(@all_done_string)
+          @outcome = :all_done
+        elsif @task_done_string && text.include?(@task_done_string)
+          @outcome = :task_done
+        end
+      end
+    end
+  end
+end

data/lib/ralph/loop.rb

@@ -4,21 +4,15 @@ module Ralph
   # The core iteration engine. Runs opencode in a loop, restarting fresh
   # iterations whenever context grows too large or time limits are hit.
   # The loop ends when:
-  #   - the agent emits the completion string
+  #   - the agent emits the all-done completion string
   #   - max iterations are reached
   #   - total duration is exceeded
+  #
+  # An iteration ends early (and a fresh one begins) when:
+  #   - the agent emits the task-done string (build mode only)
+  #   - context limit is exceeded
   class Loop
-    SYSTEM_PROMPT = <<~PROMPT
-      You are working autonomously in a loop. IMPORTANT RULES:
-      1. Do NOT ask the user any questions. Do NOT wait for user input.
-         If you need information, read the specs, code, or docs yourself.
-      2. Work through the task methodically. Use the todo list to track progress.
-      3. When you have FULLY completed the task, you MUST output the exact
-         completion string on its own line: %<completion>s
-      4. Do not output the completion string until ALL work is truly done.
-    PROMPT
-
-    attr_reader :metrics, :iteration_number, :completed
+    attr_reader :metrics, :iteration_number, :completed, :iteration_outcomes
 
     def initialize(options)
       @prompt = options[:prompt]
@@ -26,10 +20,12 @@ module Ralph
       @max_iterations = options[:max_iterations]
       @duration_limit = options[:duration]
       @max_context = options[:max_context]
-      @completion_string = options[:completion] || "<promise>COMPLETE</promise>"
+      @all_done_string = resolve_all_done_string(options)
+      @task_done_string = resolve_task_done_string
       @metrics = Metrics.new
       @iteration_number = 0
       @completed = false
+      @iteration_outcomes = []
       @started_at = nil
       @display = Display.new(self)
     end
@@ -37,7 +33,7 @@ module Ralph
     # Run the main loop until a termination condition is met.
     def run
       @started_at = now_seconds
-      @display.show_start(@prompt)
+      @display.show_start(prompt_text)
 
       loop do
         break if should_stop_loop?
@@ -46,9 +42,14 @@ module Ralph
         @metrics.new_iteration
         @display.show_iteration_start
 
-        run_iteration
+        iteration = run_iteration
 
+        @iteration_outcomes << { number: iteration.number, outcome: iteration.outcome }
         @display.show_iteration_end
+
+        if iteration.all_done?
+          @completed = true
+        end
       end
 
       @display.show_summary
@@ -66,70 +67,67 @@ module Ralph
 
     private
 
-    def should_stop_loop?
-      if @completed
-        true
-      elsif @max_iterations && @iteration_number >= @max_iterations
-        @display.show_termination("max iterations reached (#{@max_iterations})")
-        true
-      elsif @duration_limit && elapsed_seconds >= @duration_limit
-        @display.show_termination("duration limit reached (#{@duration_limit}s)")
-        true
+    # Read all-done string from the prompt object if it responds to it,
+    # falling back to the CLI --completion option or the default.
+    def resolve_all_done_string(options)
+      if options[:completion]
+        options[:completion]
+      elsif @prompt.respond_to?(:all_done) && @prompt.all_done
+        @prompt.all_done
       else
-        false
+        Prompt::Build::DEFAULT_ALL_DONE
       end
     end
 
-    def run_iteration
-      iteration_started_at = now_seconds
-      agent = Opencode.new(model: @model)
-      full_prompt = build_prompt
-
-      agent.run(full_prompt) do |event|
-        @metrics.process(event)
-        @display.show_event(event)
-
-        if event.is_a?(Events::Text)
-          check_completion(event.text)
-        end
-
-        if should_cancel_iteration?(iteration_started_at)
-          @display.show_iteration_cancelled(cancel_reason(iteration_started_at))
-          agent.cancel
-          break
-        end
+    # Read task-done string from the prompt object. Plan prompts return nil,
+    # meaning the loop will not watch for task-done signals.
+    def resolve_task_done_string
+      if @prompt.respond_to?(:task_done)
+        @prompt.task_done
+      else
+        nil
       end
     end
 
-    def should_cancel_iteration?(iteration_started_at)
-      if @max_context && @metrics.current_context >= @max_context
+    def prompt_text
+      @prompt.to_s
+    end
+
+    def should_stop_loop?
+      if @completed
+        true
+      elsif @max_iterations && @iteration_number >= @max_iterations
+        @display.show_termination("max iterations reached (#{@max_iterations})")
         true
-      elsif @duration_limit && elapsed_seconds >= @duration_limit
+      elsif duration_exceeded?
+        @display.show_termination("duration limit reached (#{@duration_limit}s)")
         true
       else
         false
       end
     end
 
-    def cancel_reason(iteration_started_at)
-      if @max_context && @metrics.current_context >= @max_context
-        "context limit reached (#{@metrics.current_context}/#{@max_context})"
-      elsif @duration_limit && elapsed_seconds >= @duration_limit
-        "duration limit reached"
-      else
-        "unknown"
-      end
-    end
-
-    def check_completion(text)
-      if text && text.include?(@completion_string)
-        @completed = true
-      end
+    def run_iteration
+      iteration = Iteration.new(
+        number: @iteration_number,
+        prompt_text: prompt_text,
+        model: @model,
+        task_done_string: @task_done_string,
+        all_done_string: @all_done_string,
+        metrics: @metrics,
+        display: @display
+      )
+
+      iteration.run(
+        max_context: @max_context,
+        duration_exceeded: -> { duration_exceeded? }
+      )
+
+      iteration
     end
 
-    def build_prompt
-      system_instructions = format(SYSTEM_PROMPT, completion: @completion_string)
-      "#{system_instructions}\n\n---\n\n#{@prompt}"
+    def duration_exceeded?
+      @duration_limit && elapsed_seconds >= @duration_limit
     end
 
     def now_seconds

data/lib/ralph/prompt/build.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Prompt
+    # The building prompt -- the heart of ralph. Instructs the agent to study
+    # specs, read the plan, pick ONE task, implement it, validate, update the
+    # plan, commit, and signal task-done.
+    #
+    # Responds to #to_s returning the complete prompt text for one iteration.
+    class Build
+      DEFAULT_TASK_DONE = "<task>DONE</task>"
+      DEFAULT_ALL_DONE = "<promise>COMPLETE</promise>"
+
+      attr_reader :task_done, :all_done
+
+      def initialize(task_done: DEFAULT_TASK_DONE, all_done: DEFAULT_ALL_DONE, context: nil)
+        @task_done = task_done
+        @all_done = all_done
+        @context = context
+      end
+
+      def to_s
+        prompt = format(TEMPLATE, task_done: @task_done, all_done: @all_done)
+        if @context && !@context.strip.empty?
+          "#{prompt}\n\n---\n\n#{@context}"
+        else
+          prompt
+        end
+      end
+
+      private
+
+      TEMPLATE = <<~PROMPT
+        0a. Study `specs/*` to learn the application specifications.
+        0b. Study the plans in `plans/`.
+        0c. For reference, the application source code is in `lib/*`.
+
+        1. Your task is to implement ONE item from the plans. Follow the plans in `plans/` and choose the most important item to address. Before making changes, search the codebase (don't assume not implemented).
+        2. After implementing functionality or resolving problems, run the tests and checks for that unit of code that was improved. If functionality is missing then it's your job to add it as per the application specifications. Think carefully.
+        3. When you discover issues, immediately update the plans in `plans/` with your findings. When resolved, update and remove the item.
+        4. When the tests pass, update the plans in `plans/`, then `git add -A` then `git commit` with a message describing the changes. After the commit, `git push`.
+        5. After committing, output the task-done signal on its own line: %{task_done}
+        6. If there are no remaining items in the plans, output the all-done signal instead: %{all_done}
+
+        99999. Important: When authoring documentation, capture the why -- tests and implementation importance.
+        999999. Important: Single sources of truth, no migrations/adapters. If tests unrelated to your work fail, resolve them as part of the increment.
+        9999999. As soon as there are no build or test errors create a git tag. If there are no git tags start at 0.0.0 and increment patch by 1 for example 0.0.1 if 0.0.0 does not exist.
+        99999999. You may add extra logging if required to debug issues.
+        999999999. Keep the plans in `plans/` current with learnings -- future work depends on this to avoid duplicating efforts. Update especially after finishing your turn.
+        9999999999. When you learn something new about how to run the application, update @AGENTS.md but keep it brief. For example if you run commands multiple times before learning the correct command then that file should be updated.
+        99999999999. For any bugs you notice, resolve them or document them in the plans even if it is unrelated to the current piece of work.
+        999999999999. Implement functionality completely. Placeholders and stubs waste efforts and time redoing the same work.
+        9999999999999. When plans become large periodically clean out the items that are completed.
+        99999999999999. If you find inconsistencies in the specs/* then carefully update the specs.
+        999999999999999. IMPORTANT: Keep @AGENTS.md operational only -- status updates and progress notes belong in the plans. A bloated AGENTS.md pollutes every future loop's context.
+        9999999999999999. IMPORTANT: Do ONE task per iteration. Pick it, do it, commit it, signal task-done. Do not continue to the next task -- the loop will start a fresh iteration for that.
+      PROMPT
+    end
+  end
+end

data/lib/ralph/prompt/plan.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Prompt
+    # The planning prompt -- instructs the agent to study specs, compare against
+    # code, and produce a prioritized task list in plans/. It does NOT implement
+    # anything. It does NOT commit anything.
+    #
+    # Responds to #to_s returning the complete prompt text for one iteration.
+    class Plan
+      DEFAULT_ALL_DONE = "<promise>COMPLETE</promise>"
+      DEFAULT_GOAL = "Consider missing elements and plan accordingly. " \
+                     "If an element is missing, search first to confirm it doesn't exist, " \
+                     "then if needed author the specification at specs/FILENAME.md."
+
+      attr_reader :all_done
+
+      def initialize(goal: nil, all_done: DEFAULT_ALL_DONE)
+        @goal = goal && !goal.strip.empty? ? goal : DEFAULT_GOAL
+        @all_done = all_done
+      end
+
+      # Plan mode has no task-done signal
+      def task_done
+        nil
+      end
+
+      def to_s
+        format(TEMPLATE, goal: @goal, all_done: @all_done)
+      end
+
+      private
+
+      TEMPLATE = <<~PROMPT
+        0a. Study `specs/*` to learn the application specifications.
+        0b. Study the plans in `plans/` (if present) to understand the plan so far.
+        0c. Study `lib/*` to understand the existing codebase and shared utilities.
+
+        1. Study the plans in `plans/` (if present; they may be incorrect) and study existing source code in `lib/*` and compare it against `specs/*`. Analyze findings, prioritize tasks, and create/update the plans in `plans/` as bullet point lists sorted in priority of items yet to be implemented. Think carefully. Consider searching for TODO, minimal implementations, placeholders, skipped/flaky tests, and inconsistent patterns. Study the plans to determine the starting point for research and keep them up to date with items considered complete/incomplete.
+
+        IMPORTANT: Plan only. Do NOT implement anything. Do NOT assume functionality is missing; confirm with code search first.
+
+        ULTIMATE GOAL: %{goal}
+
+        When you have completed the plan, output the exact completion string on its own line: %{all_done}
+      PROMPT
+    end
+  end
+end

data/lib/ralph/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ralph
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end