solid_agents 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f47eb3e38b46a127496f51a08a4a9613becb2abc109922b1ad4f5f2b203c89a2
-  data.tar.gz: ad064cee60b057a8eb9dc3baccf5f06c48411550f91f984a35ff8a32fca51d5e
+  metadata.gz: e4096d5a7518890d89a9ab5ef5583e1828f9457abe69f536c2e7042c05e9288a
+  data.tar.gz: f466a2d473053692596c5c70f43530df1e77e474c10622084ef6f3431d4b36b3
 SHA512:
-  metadata.gz: fd4fe012fb44f5f2707152fae422cbc0a4a63b2342e3fac2e485231808d46c460c8465642fa747f37e7aa14820763f8a1bc9a722c65e1734b76db14c1153892f
-  data.tar.gz: 31a7f4a1ecc53a08710c656b7c7009d118e01de305f273d112984d460e1a826a0f5b4c14edbe5833bcb4589ffd1b6fa620346b8b23f61b52f265c3afd49eaf4b
+  metadata.gz: c1833f9334bf37f89c13d473154ef428240b87772fbedac727daa369f6cda15906ab93225fee8c3471f0d523794a5e9efa489d2e8c443f8e097518c12c23535d
+  data.tar.gz: 887265f38a7cdb95a05f15ab8a0919af5d1e9039de54a2f01e2507fecd75c6aa53cc5c52acf983f715c885950c2b158323a4969f4e3b9f962eea0245132301cd

data/CHANGELOG.md

@@ -2,13 +2,44 @@
 
 All notable changes to `solid_agents` will be documented in this file.
 
+## [v0.2.1] - 2026-03-23
+
+Follow-up release for RubyLLM runtime and path conventions.
+
+- Moved agent classes and prompt templates to `app/solid_agents/agents` and `app/solid_agents/prompts`.
+- Added VCR-backed live RubyLLM integration coverage with secret filtering and record-once behavior.
+- Standardized LLM credential loading to environment variables only and added `.env.sample`.
+- Updated installer and docs to reflect ENV-first configuration and current runtime defaults.
+
+Status notes:
+
+- This release is still WIP and not production-ready.
+- Breaking changes are expected before `1.0`.
+
+## [v0.2.0] - 2026-03-23
+
+Major architecture reset delivered as a minor release for rapid iteration.
+
+- Replaced runtime adapters with a single RubyLLM-first execution path.
+- Rebuilt the run model into an event-driven staged workflow.
+- Added work-item board tracking and explicit inter-agent handoff records.
+- Introduced stage ownership with alphabetical agents: alex, betty, chad, david, eddy.
+- Updated installer schema and initializer templates for the new workflow primitives.
+- Reworked run UI to expose stage, owner, events, and artifacts in clean columns.
+- Expanded Minitest coverage and moved to YAML fixtures for deterministic test data.
+
+Status notes:
+
+- This release is still WIP and not production-ready.
+- Breaking changes are expected before `1.0`.
+
 ## [v0.1.0] - 2026-03-22
 
 Initial public release (WIP).
 
 - Introduced `solid_agents` Rails engine for database-backed agent run orchestration.
 - Added run lifecycle models and persistence for runs, events, artifacts, agents, and config.
-- Added dispatch and execution flow with runtime adapters for TinyClaw and OpenClaw.
+- Added dispatch and execution flow with runtime adapters for OpenAI RubyLLM runtime and OpenAI RubyLLM runtime.
 - Added built-in UI/controllers for managing agents and inspecting runs.
 - Added installer generator, schema template, and base configuration defaults.
 

data/README.md

@@ -1,6 +1,6 @@
 # SolidAgents
 
-**Automation workflows for Rails apps, powered by agent runtimes.**
+**Event-driven error fixing workflow for Rails apps, powered by RubyLLM agents.**
 
 > [!WARNING]
 > `solid_agents` is an early release and still a work in progress.
@@ -8,26 +8,30 @@
 > Expect breaking changes before `1.0`.
 > Not production-ready yet.
 
-`solid_agents` is a Rails engine that consumes observability/incident APIs (for example from `solid_events`), stores automation run state, dispatches work to runtime executors (TinyClaw in development, OpenClaw in production), and provides a built-in dashboard for operations.
+`solid_agents` is a Rails engine focused on a single pipeline:
+
+`error received -> staged agent workflow -> code fix attempt -> PR/CI stage tracking`
 
 ## Scope
 
-`solid_agents` is strictly for automation and execution:
+`solid_agents` is for automation orchestration and execution only:
 
-- Consume incident/trace APIs and operator instructions
-- Plan/execute workflows (triage, patch, test, PR, QA, review loops)
-- Track run lifecycle, artifacts, and runtime outputs
-- Route tasks to runtime adapters (TinyClaw/OpenClaw)
+- Consume error-like events from source adapters (starting with `solid_errors` style payloads)
+- Track runs in an event-driven stage machine
+- Enforce non-overlapping stage ownership (`alex`, `betty`, `chad`, `david`, `eddy`)
+- Persist handoffs, notes, and artifacts for each stage
+- Execute stage tasks through the RubyLLM runtime adapter
 
-It does **not** own observability storage or incident detection/state as a source of truth. That belongs in `solid_events`.
+It does **not** own observability storage or incident detection as a source of truth.
 
 ## Features
 
-- DB-backed run lifecycle (`queued`, `running`, `succeeded`, `failed`)
-- Separate agent profiles per environment
-- Runtime adapters for TinyClaw and OpenClaw
-- Built-in UI for runs, events, artifacts, and agent configuration
-- Install generator and schema template aligned with Solid gem conventions
+- DB-backed run lifecycle and stage workflow
+- Append-only run events with actor attribution
+- Work-item board columns driven by stage transitions
+- Handoff records between stage owners
+- Built-in UI for runs, events, and artifacts
+- Installer generator and schema template
 
 ## Installation
 
@@ -43,25 +47,12 @@ Run installer:
 rails generate solid_agents:install
 ```
 
-Add a dedicated database in `config/database.yml` (recommended):
-
-```yaml
-production:
-  primary: &primary
-    <<: *default
-    database: app_production
-  solid_agents:
-    <<: *primary
-    database: app_production_solid_agents
-    migrations_paths: db/agent_migrate
-```
-
-Configure engine DB connection:
+Configure engine DB connection if desired:
 
 ```ruby
 # config/environments/production.rb
 config.solid_agents.connects_to = { database: { writing: :solid_agents } }
-config.solid_agents.default_runtime = :openclaw
+config.solid_agents.default_runtime = :ruby_llm
 ```
 
 Mount the UI:
@@ -75,30 +66,36 @@ end
 
 ## Usage
 
-Create an agent profile:
+Create pipeline agents:
 
 ```ruby
-SolidAgents::Agent.create!(
-  key: "fixer",
-  name: "Bug Fixer",
-  role: "fixer",
-  runtime: Rails.env.production? ? "openclaw" : "tinyclaw",
-  working_directory: Rails.root.to_s,
-  capabilities_json: {"allow_pr" => Rails.env.production?}
-)
+%w[alex betty chad david eddy].each do |key|
+  SolidAgents::Agent.find_or_create_by!(key: key, environment: Rails.env) do |agent|
+    agent.name = key.capitalize
+    agent.role = key
+    agent.runtime = "ruby_llm"
+    agent.working_directory = Rails.root.to_s
+    agent.enabled = true
+  end
+end
 ```
 
 Dispatch from a job:
 
 ```ruby
-SolidAgents.dispatch_error(source: solid_error_record, agent_key: "fixer")
+SolidAgents.dispatch_error(source: solid_error_record, agent_key: "alex")
 ```
 
+## RubyLLM Conventions
+
+- Agent classes live in `app/solid_agents/agents`.
+- Prompt instructions live in `app/solid_agents/prompts/.../instructions.txt.erb`.
+- Stage owners map directly to RubyLLM agent classes.
+
 ## Configuration
 
 ```ruby
-config.solid_agents.tinyclaw_command = "tinyclaw"
-config.solid_agents.openclaw_command = "openclaw"
+config.solid_agents.default_model = "minimax/minimax-m2.7"
 config.solid_agents.default_test_command = "bin/rails test"
 config.solid_agents.max_iterations = 8
 ```
@@ -108,4 +105,19 @@ config.solid_agents.max_iterations = 8
 ```bash
 bundle install
 bundle exec rake test
+gem build solid_agents.gemspec
 ```
+
+## Secrets And Testing
+
+- Runtime credentials are loaded from environment variables only: `OPENROUTER_API_KEY` and optional `OPENROUTER_API_BASE`.
+- Keep real keys out of committed files and never commit `.env`.
+- Live LLM tests use VCR with `record: :once` and secret filtering.
+- Record cassettes intentionally with:
+
+```bash
+LIVE_LLM=1 OPENROUTER_API_KEY=... bundle exec rake test TEST=test/integration/solid_agents/ruby_llm_live_flow_test.rb
+```
+
+- To re-record a live interaction, delete the cassette file first and run the command again.
+- You can create a local `.env` from `.env.sample` and load it with `set -a; source .env; set +a`.

data/app/controllers/solid_agents/runs_controller.rb

@@ -17,13 +17,16 @@ module SolidAgents
     def retry
       duplicated = @run.dup
       duplicated.status = :queued
+      duplicated.stage = "received"
+      duplicated.stage_owner = "alex"
       duplicated.started_at = nil
       duplicated.finished_at = nil
       duplicated.error_payload = nil
       duplicated.result_payload = nil
       duplicated.external_key = "retry-#{@run.id}-#{Time.current.to_i}"
       duplicated.save!
-      duplicated.append_event!("retried", message: "Run created from retry", payload: {original_run_id: @run.id})
+      duplicated.create_work_item!(column_key: duplicated.stage, title: @run.work_item&.title || "Retry ##{@run.id}", summary: "Retry workflow run", metadata_json: {"original_run_id" => @run.id})
+      duplicated.append_event!("retried", message: "Run created from retry", payload: {"original_run_id" => @run.id}, actor: "alex")
       SolidAgents::ExecuteRunJob.perform_later(duplicated.id)
 
       redirect_to run_path(duplicated), notice: "Run retried."

data/app/jobs/solid_agents/execute_run_job.rb

@@ -6,6 +6,8 @@ module SolidAgents
 
     def perform(run_id)
       run = SolidAgents::Run.find(run_id)
+      return if SolidAgents::Workflow.final_stage?(run.stage) || run.failed? || run.succeeded?
+
       SolidAgents::Runs::Executor.call(run)
     end
   end

data/app/models/solid_agents/agent.rb

@@ -4,7 +4,7 @@ module SolidAgents
   class Agent < Record
     self.table_name = "solid_agents_agents"
 
-    ROLES = %w[fixer reviewer qa custom].freeze
+    ROLES = %w[alex betty chad david eddy].freeze
 
     has_many :runs, class_name: "SolidAgents::Run", dependent: :nullify
 

data/app/models/solid_agents/handoff.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  class Handoff < Record
+    self.table_name = "solid_agents_handoffs"
+
+    belongs_to :run, class_name: "SolidAgents::Run"
+
+    validates :from_agent, :to_agent, :stage, presence: true
+  end
+end

data/app/models/solid_agents/run.rb

@@ -7,6 +7,7 @@ module SolidAgents
     STATUSES = {
       queued: "queued",
       running: "running",
+      blocked: "blocked",
       pr_opened: "pr_opened",
       succeeded: "succeeded",
       failed: "failed",
@@ -16,23 +17,57 @@ module SolidAgents
     belongs_to :agent, class_name: "SolidAgents::Agent"
     has_many :events, class_name: "SolidAgents::RunEvent", foreign_key: :run_id, dependent: :delete_all
     has_many :artifacts, class_name: "SolidAgents::Artifact", foreign_key: :run_id, dependent: :delete_all
+    has_many :handoffs, class_name: "SolidAgents::Handoff", foreign_key: :run_id, dependent: :delete_all
+    has_one :work_item, class_name: "SolidAgents::WorkItem", foreign_key: :run_id, dependent: :delete
 
     enum :status, STATUSES
 
-    validates :runtime, :environment, :status, :source_type, presence: true
+    validates :runtime, :environment, :status, :source_type, :stage, presence: true
     validates :external_key, uniqueness: true, allow_nil: true
 
     before_validation :set_defaults, on: :create
 
-    def append_event!(event_type, message:, payload: nil)
+    def append_event!(event_type, message:, payload: nil, actor: nil)
       next_sequence = (events.maximum(:sequence) || 0) + 1
-      events.create!(event_type: event_type, message: message, payload: payload || {}, event_time: Time.current, sequence: next_sequence)
+      events.create!(
+        event_type: event_type,
+        message: message,
+        payload: payload || {},
+        actor: actor || stage_owner,
+        event_time: Time.current,
+        sequence: next_sequence
+      )
+    end
+
+    def transition_to!(next_stage, actor:, message:, payload: {})
+      update!(stage: next_stage, stage_owner: SolidAgents::Workflow.stage_agent(next_stage))
+      work_item&.update!(column_key: next_stage)
+      append_event!("stage_transitioned", message: message, payload: payload.merge("next_stage" => next_stage), actor: actor)
+    end
+
+    def start_stage!(actor:)
+      update!(status: :running, started_at: (started_at || Time.current))
+      append_event!("stage_started", message: "Stage #{stage} started", payload: {"stage" => stage}, actor: actor)
+    end
+
+    def complete!(result_payload:, actor:)
+      update!(status: :succeeded, stage: "done", stage_owner: SolidAgents::Workflow.stage_agent("done"), finished_at: Time.current, result_payload: result_payload)
+      work_item&.update!(column_key: "done")
+      append_event!("run_completed", message: "Run completed successfully", payload: result_payload, actor: actor)
+    end
+
+    def fail!(error_payload:, actor:)
+      update!(status: :failed, finished_at: Time.current, error_payload: error_payload)
+      work_item&.update!(column_key: "failed")
+      append_event!("run_failed", message: "Run failed", payload: error_payload, actor: actor)
     end
 
     private
 
     def set_defaults
       self.status ||= :queued
+      self.stage ||= "received"
+      self.stage_owner ||= SolidAgents::Workflow.stage_agent(stage)
       self.runtime ||= agent&.runtime || SolidAgents.default_runtime.to_s
       self.environment ||= Rails.env
       self.test_command ||= SolidAgents.default_test_command

data/app/models/solid_agents/work_item.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  class WorkItem < Record
+    self.table_name = "solid_agents_work_items"
+
+    belongs_to :run, class_name: "SolidAgents::Run"
+
+    validates :column_key, :title, presence: true
+  end
+end

data/app/services/solid_agents/runs/dispatch.rb

@@ -16,12 +16,15 @@ module SolidAgents
           external_key: "#{source.class.name}-#{source.respond_to?(:id) ? source.id : source.object_id}-#{Time.current.to_i}",
           repo_path: agent.working_directory,
           base_branch: "main",
-          max_iterations: agent.max_iterations
+          max_iterations: agent.max_iterations,
+          stage: "received",
+          stage_owner: "alex"
         )
 
         context = ContextBuilder.call(source: source)
         run.update!(prompt_payload: context)
-        run.append_event!("dispatched", message: "Run dispatched from source", payload: {agent_key: agent.key})
+        run.append_event!("run_received", message: "Run received from source", payload: {"agent_key" => agent.key, "source_type" => run.source_type}, actor: "alex")
+        run.create_work_item!(column_key: run.stage, title: "Fix #{run.source_type}##{run.source_id || "n/a"}", summary: "Automated error-fixing pipeline", metadata_json: {"agent_key" => agent.key})
 
         SolidAgents::ExecuteRunJob.perform_later(run.id)
         run

data/app/services/solid_agents/runs/executor.rb

@@ -4,24 +4,56 @@ module SolidAgents
   module Runs
     class Executor
       def self.call(run)
-        run.update!(status: :running, started_at: Time.current)
-        run.append_event!("runtime_started", message: "Runtime execution started")
+        stage = run.stage
+        owner = SolidAgents::Workflow.stage_agent(stage)
+
+        run.start_stage!(actor: owner)
 
         prompt = PromptBuilder.call(run: run, context: run.prompt_payload || {})
         adapter = SolidAgents.runtime_adapter(run.runtime)
         result = adapter.execute(run: run, prompt: prompt)
 
-        run.artifacts.create!(kind: "log", label: "runtime_output", storage_type: "inline", content_text: result.output.to_s)
+        run.artifacts.create!(
+          kind: "log",
+          label: "#{stage}_runtime_output",
+          storage_type: "inline",
+          content_text: result.output.to_s,
+          content_json: {"metadata" => result.metadata.to_h}
+        )
+
+        unless result.ok
+          run.fail!(error_payload: {"stage" => stage, "stderr" => result.error.to_s, "metadata" => result.metadata.to_h}, actor: owner)
+          return run
+        end
+
+        next_stage = SolidAgents::Workflow.next_stage(stage)
+        next_owner = SolidAgents::Workflow.stage_agent(next_stage)
 
-        if result.ok
-          metadata = result.metadata.to_h
-          run.update!(status: :succeeded, finished_at: Time.current, result_payload: {output: result.output, metadata: metadata})
-          run.append_event!("runtime_succeeded", message: "Runtime execution finished", payload: metadata)
+        run.handoffs.create!(
+          stage: stage,
+          from_agent: owner,
+          to_agent: next_owner,
+          note: "#{owner} completed #{stage} and handed off to #{next_owner}",
+          payload: {"output_excerpt" => result.output.to_s.slice(0, 500)}
+        )
+
+        run.append_event!(
+          "stage_completed",
+          message: "#{owner} completed #{stage}",
+          payload: {"stage" => stage, "next_stage" => next_stage, "next_owner" => next_owner},
+          actor: owner
+        )
+
+        if next_stage == "done"
+          run.complete!(result_payload: {"final_stage" => stage, "metadata" => result.metadata.to_h, "output" => result.output.to_s}, actor: next_owner)
         else
-          run.update!(status: :failed, finished_at: Time.current, error_payload: {stderr: result.error, metadata: result.metadata})
-          run.append_event!("runtime_failed", message: "Runtime execution failed", payload: result.metadata.to_h.merge("stderr" => result.error.to_s))
+          run.transition_to!(next_stage, actor: owner, message: "Transitioned from #{stage} to #{next_stage}", payload: {"next_owner" => next_owner})
+          SolidAgents::ExecuteRunJob.perform_later(run.id)
         end
 
+        run
+      rescue StandardError => e
+        run.fail!(error_payload: {"stage" => run.stage, "exception" => e.class.name, "message" => e.message}, actor: SolidAgents::Workflow.stage_agent(run.stage))
         run
       end
     end

data/app/services/solid_agents/runs/prompt_builder.rb

@@ -7,25 +7,19 @@ module SolidAgents
     class PromptBuilder
       def self.call(run:, context:)
         <<~PROMPT
-          You are #{run.agent.name} (#{run.agent.role}).
-          Goal: fix the reported Rails issue end-to-end.
+          Stage owner: #{run.stage_owner}
+          Stage: #{run.stage}
+          Run id: #{run.id}
 
           Constraints:
-          - Work in repository: #{run.repo_path}
+          - Repository path: #{run.repo_path}
           - Base branch: #{run.base_branch}
           - Test command: #{run.test_command}
+          - Runtime: #{run.runtime}
           - Max iterations: #{run.max_iterations || SolidAgents.max_iterations}
-          - Open PR allowed: #{run.agent.capability?("allow_pr")}
 
           Context JSON:
           #{JSON.pretty_generate(context)}
-
-          Definition of done:
-          1) Root cause identified.
-          2) Code fix applied.
-          3) Tests added or updated.
-          4) Tests executed and passing.
-          5) Return final JSON with keys: status, branch_name, test_summary, pr_url, notes.
         PROMPT
       end
     end

data/app/solid_agents/agents/alex.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Alex < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "alex")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Base < RubyLLM::Agent
+      model SolidAgents.default_model, provider: SolidAgents.default_provider
+      tools SolidAgents::Tools::WorkflowGuideTool.new
+
+      attr_reader :run, :context, :owner
+
+      def initialize(run:, context:, owner:)
+        @run = run
+        @context = context
+        @owner = owner.to_s
+        super()
+      end
+
+      def call(prompt)
+        ask(prompt)
+      end
+
+      def instructions
+        template_path = File.expand_path("../prompts/#{owner}/instructions.txt.erb", __dir__)
+        ERB.new(File.read(template_path)).result(binding)
+      end
+    end
+  end
+end

data/app/solid_agents/agents/betty.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Betty < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "betty")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/chad.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Chad < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "chad")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/david.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class David < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "david")
+      end
+    end
+  end
+end

data/app/solid_agents/agents/eddy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Agents
+    class Eddy < Base
+      def initialize(run:, context:)
+        super(run: run, context: context, owner: "eddy")
+      end
+    end
+  end
+end

data/app/solid_agents/agents.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "agents/base"
+require_relative "agents/alex"
+require_relative "agents/betty"
+require_relative "agents/chad"
+require_relative "agents/david"
+require_relative "agents/eddy"
+
+module SolidAgents
+  module Agents
+    AGENT_CLASSES = {
+      "alex" => SolidAgents::Agents::Alex,
+      "betty" => SolidAgents::Agents::Betty,
+      "chad" => SolidAgents::Agents::Chad,
+      "david" => SolidAgents::Agents::David,
+      "eddy" => SolidAgents::Agents::Eddy
+    }.freeze
+
+    module_function
+
+    def for_owner(owner)
+      AGENT_CLASSES.fetch(owner.to_s, SolidAgents::Agents::Alex)
+    end
+  end
+end

data/app/solid_agents/prompts/alex/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Alex, the intake and triage agent for SolidAgents.
+Work stage: <%= run.stage %>
+Produce structured triage notes and a clean handoff summary for Betty.

data/app/solid_agents/prompts/betty/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Betty, the reproduction agent for SolidAgents.
+Work stage: <%= run.stage %>
+Prioritize failing automated reproduction and provide reproducible evidence.

data/app/solid_agents/prompts/chad/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Chad, the code fix implementation agent for SolidAgents.
+Work stage: <%= run.stage %>
+Apply minimal safe fixes and prepare concise rationale for David.

data/app/solid_agents/prompts/david/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are David, the verification agent for SolidAgents.
+Work stage: <%= run.stage %>
+Validate automated and manual verification evidence before handoff.

data/app/solid_agents/prompts/eddy/instructions.txt.erb

@@ -0,0 +1,3 @@
+You are Eddy, the PR and CI shepherd agent for SolidAgents.
+Work stage: <%= run.stage %>
+Ensure PR quality, CI follow-through, and clear closure notes.

data/app/tools/solid_agents/tools/workflow_guide_tool.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Tools
+    class WorkflowGuideTool < RubyLLM::Tool
+      description "Returns workflow guidance for a given stage owner pair"
+
+      param :stage, type: "string", desc: "Current workflow stage"
+      param :owner, type: "string", desc: "Current stage owner"
+
+      def execute(stage:, owner:)
+        {
+          stage: stage,
+          owner: owner,
+          guidance: "Produce concise evidence, then hand off cleanly to the next stage owner.",
+          required_outputs: ["notes", "artifacts", "handoff_summary"]
+        }
+      end
+    end
+  end
+end

data/app/views/solid_agents/agents/edit.html.erb

@@ -1,17 +1,14 @@
 <div class="card">
-  <h2>Edit Agent <%= @agent.key %></h2>
-
+  <h2>Edit Agent</h2>
   <%= form_with model: @agent, url: agent_path(@agent), method: :patch do |f| %>
     <p><%= f.label :name %><br><%= f.text_field :name %></p>
     <p><%= f.label :role %><br><%= f.select :role, SolidAgents::Agent::ROLES %></p>
-    <p><%= f.label :runtime %><br><%= f.select :runtime, %w[tinyclaw openclaw] %></p>
+    <p><%= f.label :runtime %><br><%= f.select :runtime, %w[pi] %></p>
     <p><%= f.label :environment %><br><%= f.text_field :environment %></p>
-    <p><%= f.label :model %><br><%= f.text_field :model %></p>
     <p><%= f.label :working_directory %><br><%= f.text_field :working_directory %></p>
     <p><%= f.label :timeout_seconds %><br><%= f.number_field :timeout_seconds %></p>
     <p><%= f.label :max_iterations %><br><%= f.number_field :max_iterations %></p>
-    <p><%= f.label :system_prompt %><br><%= f.text_area :system_prompt, rows: 8, cols: 80 %></p>
-    <p><%= f.label :enabled %> <%= f.check_box :enabled %></p>
-    <p><%= f.submit "Save", class: "btn primary" %></p>
+    <p><%= f.label :enabled %><br><%= f.check_box :enabled %></p>
+    <%= f.submit "Save", class: "btn primary" %>
   <% end %>
 </div>

data/app/views/solid_agents/runs/index.html.erb

@@ -6,9 +6,10 @@
         <th>ID</th>
         <th>Agent</th>
         <th>Status</th>
+        <th>Stage</th>
+        <th>Owner</th>
         <th>Runtime</th>
         <th>Source</th>
-        <th>Started</th>
       </tr>
     </thead>
     <tbody>
@@ -17,9 +18,10 @@
           <td><%= link_to "##{run.id}", run_path(run) %></td>
           <td><%= run.agent&.key %></td>
           <td><span class="badge <%= status_badge_class(run.status) %>"><%= run.status %></span></td>
+          <td><%= run.stage %></td>
+          <td><%= run.stage_owner %></td>
           <td><%= run.runtime %></td>
           <td><%= [run.source_type, run.source_id].compact.join("#") %></td>
-          <td><%= run.started_at || run.created_at %></td>
         </tr>
       <% end %>
     </tbody>

data/app/views/solid_agents/runs/show.html.erb

@@ -5,6 +5,11 @@
     Runtime: <strong><%= @run.runtime %></strong> |
     Status: <span class="badge <%= status_badge_class(@run.status) %>"><%= @run.status %></span>
   </p>
+  <p>
+    Stage: <strong><%= @run.stage %></strong> |
+    Owner: <strong><%= @run.stage_owner %></strong> |
+    Board Column: <strong><%= @run.work_item&.column_key || @run.stage %></strong>
+  </p>
   <p>
     Source: <%= [@run.source_type, @run.source_id].compact.join("#") %>
   </p>
@@ -19,6 +24,7 @@
         <tr>
           <th>#</th>
           <th>Type</th>
+          <th>Actor</th>
           <th>Message</th>
         </tr>
       </thead>
@@ -27,6 +33,7 @@
           <tr>
             <td><%= event.sequence %></td>
             <td><%= event.event_type %></td>
+            <td><%= event.actor %></td>
             <td><%= event.message %></td>
           </tr>
         <% end %>

data/lib/generators/solid_agents/install/install_generator.rb

@@ -18,7 +18,8 @@ module SolidAgents
           "",
           '\\1# Configure Solid Agent',
           '\\1config.solid_agents.connects_to = { database: { writing: :solid_agents } }',
-          '\\1config.solid_agents.default_runtime = :openclaw'
+          '\\1config.solid_agents.default_runtime = :ruby_llm',
+          '\\1config.solid_agents.default_provider = :openrouter'
         ].join("\n")
       end
     end

data/lib/generators/solid_agents/install/templates/config/initializers/solid_agents.rb

@@ -4,8 +4,12 @@ Rails.application.configure do
   # Optional: override in specific environments.
   # config.solid_agents.connects_to = { database: { writing: :solid_agents } }
 
-  config.solid_agents.tinyclaw_command = ENV.fetch("SOLID_AGENTS_TINYCLAW_COMMAND", "tinyclaw")
-  config.solid_agents.openclaw_command = ENV.fetch("SOLID_AGENTS_OPENCLAW_COMMAND", "openclaw")
+  # Configure LLM access with environment variables:
+  # OPENROUTER_API_KEY="..."
+  # OPENROUTER_API_BASE="https://openrouter.ai/api/v1" # optional
+
+  config.solid_agents.default_model = ENV.fetch("SOLID_AGENTS_DEFAULT_MODEL", "minimax/minimax-m2.7")
+  config.solid_agents.default_provider = :openrouter
   config.solid_agents.default_test_command = ENV.fetch("SOLID_AGENTS_TEST_COMMAND", "bin/rails test")
   config.solid_agents.max_iterations = ENV.fetch("SOLID_AGENTS_MAX_ITERATIONS", 8).to_i
 end

data/lib/generators/solid_agents/install/templates/db/agent_schema.rb

@@ -4,8 +4,8 @@ ActiveRecord::Schema[6.1].define do
   create_table :solid_agents_agents, force: :cascade do |t|
     t.string :key, null: false
     t.string :name, null: false
-    t.string :role, null: false, default: "fixer"
-    t.string :runtime, null: false, default: "tinyclaw"
+    t.string :role, null: false, default: "alex"
+    t.string :runtime, null: false, default: "ruby_llm"
     t.boolean :enabled, null: false, default: true
     t.string :environment
     t.string :model
@@ -26,7 +26,9 @@ ActiveRecord::Schema[6.1].define do
     t.bigint :source_id
     t.string :error_fingerprint
     t.string :status, null: false, default: "queued"
-    t.string :runtime, null: false
+    t.string :stage, null: false, default: "received"
+    t.string :stage_owner, null: false, default: "alex"
+    t.string :runtime, null: false, default: "ruby_llm"
     t.string :environment, null: false
     t.string :repo_path
     t.string :base_branch
@@ -47,14 +49,39 @@ ActiveRecord::Schema[6.1].define do
 
   add_index :solid_agents_runs, :external_key, unique: true
   add_index :solid_agents_runs, :status
+  add_index :solid_agents_runs, :stage
   add_index :solid_agents_runs, :error_fingerprint
   add_index :solid_agents_runs, [:source_type, :source_id]
 
+  create_table :solid_agents_work_items, force: :cascade do |t|
+    t.references :run, null: false, foreign_key: {to_table: :solid_agents_runs}
+    t.string :column_key, null: false, default: "received"
+    t.string :title, null: false
+    t.text :summary
+    t.json :metadata_json, default: {}
+    t.timestamps
+  end
+
+  add_index :solid_agents_work_items, :column_key
+
+  create_table :solid_agents_handoffs, force: :cascade do |t|
+    t.references :run, null: false, foreign_key: {to_table: :solid_agents_runs}
+    t.string :stage, null: false
+    t.string :from_agent, null: false
+    t.string :to_agent, null: false
+    t.text :note
+    t.json :payload, default: {}
+    t.timestamps
+  end
+
+  add_index :solid_agents_handoffs, [:run_id, :stage]
+
   create_table :solid_agents_run_events, force: :cascade do |t|
     t.references :run, null: false, foreign_key: {to_table: :solid_agents_runs}
     t.string :event_type, null: false
     t.datetime :event_time, null: false
     t.text :message, null: false
+    t.string :actor
     t.json :payload, default: {}
     t.integer :sequence, null: false
     t.timestamps

data/lib/solid_agents/engine.rb

@@ -4,6 +4,7 @@ module SolidAgents
   class Engine < ::Rails::Engine
     config.root = File.expand_path("../..", __dir__)
     isolate_namespace SolidAgents
+    paths.add "app/solid_agents", eager_load: true
 
     config.solid_agents = ActiveSupport::OrderedOptions.new
 
@@ -12,5 +13,15 @@ module SolidAgents
         SolidAgents.public_send(:"#{name}=", value)
       end
     end
+
+    initializer "solid_agents.ruby_llm" do
+      SolidAgents.openrouter_api_key ||= ENV["OPENROUTER_API_KEY"]
+      SolidAgents.openrouter_api_base ||= ENV["OPENROUTER_API_BASE"]
+
+      RubyLLM.configure do |config|
+        config.openrouter_api_key = SolidAgents.openrouter_api_key if SolidAgents.openrouter_api_key.present?
+        config.openrouter_api_base = SolidAgents.openrouter_api_base if SolidAgents.openrouter_api_base.present?
+      end
+    end
   end
 end

data/lib/solid_agents/runtime/ruby_llm_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module SolidAgents
+  module Runtime
+    class RubyLlmAdapter < Adapter
+      def execute(run:, prompt:)
+        agent_class = SolidAgents::Agents.for_owner(run.stage_owner)
+        agent = agent_class.new(run: run, context: run.prompt_payload || {})
+        response = agent.call(prompt)
+        output = response.respond_to?(:content) ? response.content.to_s : response.to_s
+
+        Result.new(ok: true, output: output, error: nil, metadata: {agent_class: agent_class.name, stage: run.stage, owner: run.stage_owner})
+      rescue StandardError => e
+        Result.new(ok: false, output: nil, error: e.message, metadata: {agent_class: agent_class&.name, stage: run.stage, owner: run.stage_owner, exception: e.class.name})
+      end
+    end
+  end
+end

data/lib/solid_agents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidAgents
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/solid_agents/workflow.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SolidAgents
+  module Workflow
+    STAGES = [
+      "received",
+      "triaged",
+      "repro_test",
+      "repro_manual",
+      "fixing",
+      "verifying",
+      "pr_opened",
+      "ci_wait",
+      "done"
+    ].freeze
+
+    STAGE_TO_AGENT = {
+      "received" => "alex",
+      "triaged" => "alex",
+      "repro_test" => "betty",
+      "repro_manual" => "betty",
+      "fixing" => "chad",
+      "verifying" => "david",
+      "pr_opened" => "eddy",
+      "ci_wait" => "eddy",
+      "done" => "eddy"
+    }.freeze
+
+    FINAL_STAGES = ["done", "failed"].freeze
+
+    module_function
+
+    def next_stage(current_stage)
+      index = STAGES.index(current_stage)
+      return "done" if index.nil? || index == STAGES.length - 1
+
+      STAGES[index + 1]
+    end
+
+    def stage_agent(stage)
+      STAGE_TO_AGENT.fetch(stage.to_s, "alex")
+    end
+
+    def final_stage?(stage)
+      FINAL_STAGES.include?(stage.to_s)
+    end
+  end
+end

data/lib/solid_agents.rb

@@ -1,32 +1,36 @@
 # frozen_string_literal: true
 
 require_relative "solid_agents/version"
+require_relative "solid_agents/workflow"
 require_relative "solid_agents/runtime/adapter"
-require_relative "solid_agents/runtime/tinyclaw_adapter"
-require_relative "solid_agents/runtime/openclaw_adapter"
+require_relative "solid_agents/runtime/ruby_llm_adapter"
 require_relative "solid_agents/engine"
 
 module SolidAgents
   mattr_accessor :connects_to
   mattr_accessor :base_controller_class, default: "::ActionController::Base"
-  mattr_accessor :default_runtime, default: :tinyclaw
-  mattr_accessor :tinyclaw_command, default: "tinyclaw"
-  mattr_accessor :openclaw_command, default: "openclaw"
+  mattr_accessor :default_runtime, default: :ruby_llm
+  mattr_accessor :default_model, default: "minimax/minimax-m2.7"
+  mattr_accessor :default_provider, default: :openrouter
+  mattr_accessor :openrouter_api_key
+  mattr_accessor :openrouter_api_base
   mattr_accessor :default_test_command, default: "bin/rails test"
   mattr_accessor :max_iterations, default: 8
 
   class << self
     def runtime_adapter(runtime)
       case runtime.to_sym
-      when :tinyclaw then SolidAgents::Runtime::TinyclawAdapter.new
-      when :openclaw then SolidAgents::Runtime::OpenclawAdapter.new
+      when :ruby_llm then SolidAgents::Runtime::RubyLlmAdapter.new
       else
         raise ArgumentError, "Unsupported runtime: #{runtime.inspect}"
       end
     end
 
-    def dispatch_error(source:, agent_key: "fixer")
+    def dispatch_error(source:, agent_key: "alex")
       SolidAgents::Runs::Dispatch.call(source: source, agent_key: agent_key)
     end
   end
 end
+
+require_relative "../app/tools/solid_agents/tools/workflow_guide_tool"
+require_relative "../app/solid_agents/agents"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_agents
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -107,8 +121,36 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
-description: Solid Agent stores agent runs in its own database and dispatches work
-  to tinyclaw/openclaw runtimes with a built-in Rails UI.
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Solid Agent stores agent runs in its own database and dispatches staged
+  workflow tasks to the RubyLLM runtime with a built-in Rails UI.
 email:
 - kr@kakaruto.com
 executables: []
@@ -127,13 +169,28 @@ files:
 - app/models/solid_agents/agent.rb
 - app/models/solid_agents/artifact.rb
 - app/models/solid_agents/config.rb
+- app/models/solid_agents/handoff.rb
 - app/models/solid_agents/record.rb
 - app/models/solid_agents/run.rb
 - app/models/solid_agents/run_event.rb
+- app/models/solid_agents/work_item.rb
 - app/services/solid_agents/runs/context_builder.rb
 - app/services/solid_agents/runs/dispatch.rb
 - app/services/solid_agents/runs/executor.rb
 - app/services/solid_agents/runs/prompt_builder.rb
+- app/solid_agents/agents.rb
+- app/solid_agents/agents/alex.rb
+- app/solid_agents/agents/base.rb
+- app/solid_agents/agents/betty.rb
+- app/solid_agents/agents/chad.rb
+- app/solid_agents/agents/david.rb
+- app/solid_agents/agents/eddy.rb
+- app/solid_agents/prompts/alex/instructions.txt.erb
+- app/solid_agents/prompts/betty/instructions.txt.erb
+- app/solid_agents/prompts/chad/instructions.txt.erb
+- app/solid_agents/prompts/david/instructions.txt.erb
+- app/solid_agents/prompts/eddy/instructions.txt.erb
+- app/tools/solid_agents/tools/workflow_guide_tool.rb
 - app/views/layouts/solid_agents/_style.html.erb
 - app/views/layouts/solid_agents/application.html.erb
 - app/views/solid_agents/agents/edit.html.erb
@@ -150,9 +207,9 @@ files:
 - lib/solid_agents.rb
 - lib/solid_agents/engine.rb
 - lib/solid_agents/runtime/adapter.rb
-- lib/solid_agents/runtime/openclaw_adapter.rb
-- lib/solid_agents/runtime/tinyclaw_adapter.rb
+- lib/solid_agents/runtime/ruby_llm_adapter.rb
 - lib/solid_agents/version.rb
+- lib/solid_agents/workflow.rb
 homepage: https://github.com/kaka-ruto/solid_agents
 licenses:
 - MIT

data/lib/solid_agents/runtime/openclaw_adapter.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module SolidAgents
-  module Runtime
-    class OpenclawAdapter < Adapter
-      def execute(run:, prompt:)
-        command = [SolidAgents.openclaw_command.to_s, "agent", "--message", prompt, "--thinking", "high"]
-        run_command(*command)
-      end
-    end
-  end
-end

data/lib/solid_agents/runtime/tinyclaw_adapter.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module SolidAgents
-  module Runtime
-    class TinyclawAdapter < Adapter
-      def execute(run:, prompt:)
-        command = [SolidAgents.tinyclaw_command.to_s, "send", "@#{run.agent.key} #{prompt}"]
-        run_command(*command)
-      end
-    end
-  end
-end