rubyn-code 0.1.0 → 0.2.0

data/lib/rubyn_code/permissions/prompter.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "tty-prompt"
-require "pastel"
-require "json"
+require 'tty-prompt'
+require 'pastel'
+require 'json'
 
 module RubynCode
   module Permissions
@@ -19,7 +19,7 @@ module RubynCode
         display_tool_summary(pastel, tool_name, tool_input)
 
         prompt.yes?(
-          pastel.yellow("Allow this tool call?"),
+          pastel.yellow('Allow this tool call?'),
           default: true
         )
       rescue TTY::Prompt::Reader::InputInterrupt
@@ -36,16 +36,16 @@ module RubynCode
         prompt = build_prompt
         pastel = Pastel.new
 
-        $stdout.puts pastel.red.bold("WARNING: Destructive operation requested")
-        $stdout.puts pastel.red("=" * 50)
+        $stdout.puts pastel.red.bold('WARNING: Destructive operation requested')
+        $stdout.puts pastel.red('=' * 50)
         display_tool_summary(pastel, tool_name, tool_input)
-        $stdout.puts pastel.red("=" * 50)
+        $stdout.puts pastel.red('=' * 50)
 
         answer = prompt.ask(
           pastel.red.bold('Type "yes" to confirm this destructive action:')
         )
 
-        answer&.strip&.downcase == "yes"
+        answer&.strip&.downcase == 'yes'
       rescue TTY::Prompt::Reader::InputInterrupt
         false
       end

data/lib/rubyn_code/protocols/RUBYN.md

@@ -0,0 +1,14 @@
+# Layer 10: Protocols
+
+Safety and coordination protocols for agent lifecycle.
+
+## Classes
+
+- **`ShutdownHandshake`** — Graceful shutdown. Waits for the current tool call to complete,
+  saves conversation state, and cleans up resources.
+
+- **`PlanApproval`** — When the agent proposes a multi-step plan, this prompts the user
+  for approval before execution. Shows the plan, waits for yes/no/edit.
+
+- **`InterruptHandler`** — Traps SIGINT (Ctrl+C). First interrupt cancels the current
+  operation. Second interrupt within 2 seconds triggers shutdown.

data/lib/rubyn_code/protocols/interrupt_handler.rb

@@ -23,7 +23,7 @@ module RubynCode
             @last_interrupt_at = nil
           end
 
-          trap("INT") do
+          trap('INT') do
             handle_interrupt
           end
         end

data/lib/rubyn_code/protocols/plan_approval.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "tty-prompt"
-require "tty-reader"
-require "pastel"
+require 'tty-prompt'
+require 'tty-reader'
+require 'pastel'
 
 module RubynCode
   module Protocols
@@ -25,10 +25,10 @@ module RubynCode
           tty = build_prompt
 
           $stdout.puts
-          $stdout.puts pastel.cyan.bold("Proposed Plan")
-          $stdout.puts pastel.cyan("=" * 60)
+          $stdout.puts pastel.cyan.bold('Proposed Plan')
+          $stdout.puts pastel.cyan('=' * 60)
           $stdout.puts plan_text
-          $stdout.puts pastel.cyan("=" * 60)
+          $stdout.puts pastel.cyan('=' * 60)
           $stdout.puts
 
           if prompt
@@ -37,15 +37,15 @@ module RubynCode
           end
 
           approved = tty.yes?(
-            pastel.yellow.bold("Do you approve this plan?"),
+            pastel.yellow.bold('Do you approve this plan?'),
             default: false
           )
 
           if approved
-            $stdout.puts pastel.green("Plan approved.")
+            $stdout.puts pastel.green('Plan approved.')
             APPROVED
           else
-            $stdout.puts pastel.red("Plan rejected.")
+            $stdout.puts pastel.red('Plan rejected.')
             REJECTED
           end
         rescue TTY::Reader::InputInterrupt

data/lib/rubyn_code/protocols/shutdown_handshake.rb

@@ -22,8 +22,8 @@ module RubynCode
           mailbox.send(
             from: from,
             to: to,
-            content: "shutdown_request",
-            message_type: "shutdown_request"
+            content: 'shutdown_request',
+            message_type: 'shutdown_request'
           )
 
           deadline = Time.now + timeout
@@ -31,7 +31,7 @@ module RubynCode
           loop do
             messages = mailbox.read_inbox(from)
             response = messages.find do |msg|
-              msg[:from] == to && msg[:message_type] == "shutdown_response"
+              msg[:from] == to && msg[:message_type] == 'shutdown_response'
             end
 
             return :acknowledged if response
@@ -50,13 +50,13 @@ module RubynCode
         # @param approve [Boolean] whether to approve the shutdown (default: true)
         # @return [String] the message id
         def respond(mailbox:, from:, to:, approve: true)
-          content = approve ? "shutdown_approved" : "shutdown_denied"
+          content = approve ? 'shutdown_approved' : 'shutdown_denied'
 
           mailbox.send(
             from: from,
             to: to,
             content: content,
-            message_type: "shutdown_response"
+            message_type: 'shutdown_response'
           )
         end
 
@@ -74,16 +74,14 @@ module RubynCode
           save_state(agent_name, session_persistence, conversation)
 
           # Step 2: Send shutdown acknowledgement if there is a requester
-          if requester
-            respond(mailbox: mailbox, from: agent_name, to: requester, approve: true)
-          end
+          respond(mailbox: mailbox, from: agent_name, to: requester, approve: true) if requester
 
           # Step 3: Broadcast offline status to all listeners
           mailbox.send(
             from: agent_name,
-            to: "_system",
+            to: '_system',
             content: "#{agent_name} is now offline",
-            message_type: "status_change"
+            message_type: 'status_change'
           )
         end
 
@@ -101,7 +99,7 @@ module RubynCode
             messages: conversation.messages
           )
         rescue StandardError => e
-          $stderr.puts "[ShutdownHandshake] Warning: failed to save state for '#{agent_name}': #{e.message}"
+          warn "[ShutdownHandshake] Warning: failed to save state for '#{agent_name}': #{e.message}"
         end
       end
     end

data/lib/rubyn_code/skills/RUBYN.md

@@ -0,0 +1,19 @@
+# Layer 5: Skills
+
+112 curated markdown skill documents loaded on demand.
+
+## Classes
+
+- **`Catalog`** — Discovers all skill files under `skills/` and builds a searchable index.
+  Maps slash-names (`/factory-bot`) to file paths. No registration needed — drop a `.md`
+  file in the right category directory and it's discoverable.
+
+- **`Loader`** — Loads a skill document by name, returns its content. Caches loaded skills
+  in the `skills_cache` SQLite table to avoid repeated file reads.
+
+- **`Document`** — Value object representing a loaded skill: name, category, content, path.
+
+## Adding a Skill
+
+1. Create `skills/<category>/my-skill.md`
+2. It auto-discovers. That's it.

data/lib/rubyn_code/skills/catalog.rb

@@ -3,7 +3,7 @@
 module RubynCode
   module Skills
     class Catalog
-      SKILL_GLOB = "**/*.md"
+      SKILL_GLOB = '**/*.md'
 
       attr_reader :skills_dirs
 
@@ -14,7 +14,7 @@ module RubynCode
 
       def descriptions
         entries = available
-        return "" if entries.empty?
+        return '' if entries.empty?
 
         entries.map { |entry| "- /#{entry[:name]}: #{entry[:description]}" }.join("\n")
       end
@@ -37,7 +37,7 @@ module RubynCode
         skills_dirs.each do |dir|
           next unless File.directory?(dir)
 
-          Dir.glob(File.join(dir, SKILL_GLOB)).sort.each do |path|
+          Dir.glob(File.join(dir, SKILL_GLOB)).each do |path|
             entry = extract_metadata(path)
             @index << entry if entry
           end
@@ -47,12 +47,12 @@ module RubynCode
       end
 
       def extract_metadata(path)
-        header = File.read(path, 1024, encoding: "UTF-8")
-                     .encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+        header = File.read(path, 1024, encoding: 'UTF-8')
+                     .encode('UTF-8', invalid: :replace, undef: :replace, replace: '')
         doc = Document.parse(header, filename: path)
 
-        name = if doc.name.empty? || doc.name == "unknown"
-                 File.basename(path, ".md")
+        name = if doc.name.empty? || doc.name == 'unknown'
+                 File.basename(path, '.md')
                else
                  doc.name
                end

data/lib/rubyn_code/skills/document.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "yaml"
+require 'yaml'
 
 module RubynCode
   module Skills
@@ -25,15 +25,15 @@ module RubynCode
             body = match[2].to_s.strip
 
             new(
-              name: frontmatter["name"].to_s,
-              description: frontmatter["description"].to_s,
-              tags: Array(frontmatter["tags"]),
+              name: frontmatter['name'].to_s,
+              description: frontmatter['description'].to_s,
+              tags: Array(frontmatter['tags']),
               body: body
             )
           else
             body = content.to_s.strip
             title = extract_title(body)
-            derived_name = filename ? File.basename(filename, ".*").tr("_", "-") : title_to_name(title)
+            derived_name = filename ? File.basename(filename, '.*').tr('_', '-') : title_to_name(title)
             tags = derive_tags(derived_name, body)
 
             new(
@@ -49,29 +49,29 @@ module RubynCode
           raise Error, "Skill file not found: #{path}" unless File.exist?(path)
           raise Error, "Not a file: #{path}" unless File.file?(path)
 
-          content = File.read(path, encoding: "UTF-8")
+          content = File.read(path, encoding: 'UTF-8')
           parse(content, filename: path)
         end
 
         private
 
         def extract_title(body)
-          first_line = body.lines.first&.strip || ""
-          first_line.start_with?("#") ? first_line.sub(/^#+\s*/, "") : first_line[0..80]
+          first_line = body.lines.first&.strip || ''
+          first_line.start_with?('#') ? first_line.sub(/^#+\s*/, '') : first_line[0..80]
         end
 
         def title_to_name(title)
-          title.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")[0..40]
+          title.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/^-|-$/, '')[0..40]
         end
 
         def derive_tags(name, body)
           tags = []
-          tags << "ruby" if body.match?(/\bruby\b/i) || name.include?("ruby")
-          tags << "rails" if body.match?(/\brails\b/i) || name.include?("rails")
-          tags << "rspec" if body.match?(/\brspec\b/i) || name.include?("rspec")
-          tags << "testing" if body.match?(/\b(test|spec|minitest)\b/i)
-          tags << "patterns" if body.match?(/\b(pattern|design|solid)\b/i)
-          tags << "refactoring" if body.match?(/\brefactor/i)
+          tags << 'ruby' if body.match?(/\bruby\b/i) || name.include?('ruby')
+          tags << 'rails' if body.match?(/\brails\b/i) || name.include?('rails')
+          tags << 'rspec' if body.match?(/\brspec\b/i) || name.include?('rspec')
+          tags << 'testing' if body.match?(/\b(test|spec|minitest)\b/i)
+          tags << 'patterns' if body.match?(/\b(pattern|design|solid)\b/i)
+          tags << 'refactoring' if body.match?(/\brefactor/i)
           tags.uniq
         end
       end

data/lib/rubyn_code/skills/loader.rb

@@ -13,9 +13,7 @@ module RubynCode
       def load(name)
         name = name.to_s
 
-        if @loaded.key?(name)
-          return @loaded[name]
-        end
+        return @loaded[name] if @loaded.key?(name)
 
         path = catalog.find(name)
         raise Error, "Skill not found: #{name}" unless path
@@ -41,16 +39,16 @@ module RubynCode
         parts = []
         parts << "<skill name=\"#{escape_xml(doc.name)}\">"
         parts << doc.body unless doc.body.empty?
-        parts << "</skill>"
+        parts << '</skill>'
         parts.join("\n")
       end
 
       def escape_xml(text)
         text.to_s
-            .gsub("&", "&amp;")
-            .gsub("<", "&lt;")
-            .gsub(">", "&gt;")
-            .gsub("\"", "&quot;")
+            .gsub('&', '&amp;')
+            .gsub('<', '&lt;')
+            .gsub('>', '&gt;')
+            .gsub('"', '&quot;')
       end
     end
   end

data/lib/rubyn_code/sub_agents/RUBYN.md

@@ -0,0 +1,12 @@
+# Layer 6: Sub-Agents
+
+Isolated agents spawned for specific tasks, scoped to read-only or full access.
+
+## Classes
+
+- **`Runner`** — Spawns a sub-agent with its own fresh conversation context. Two types:
+  `explore` (read-only tools) and `worker` (full write access). The sub-agent runs
+  its own `Agent::Loop`, completes its task, and returns only a summary.
+
+- **`Summarizer`** — Compresses a sub-agent's full conversation into a concise summary
+  for the parent agent. Keeps the parent's context clean.

data/lib/rubyn_code/sub_agents/runner.rb

@@ -37,7 +37,7 @@ module RubynCode
         tool_defs = build_tool_definitions
 
         iteration = 0
-        final_text = ""
+        final_text = ''
 
         loop do
           break if iteration >= @max_iterations
@@ -53,10 +53,10 @@ module RubynCode
             break
           end
 
-          conversation << { role: "assistant", content: response }
+          conversation << { role: 'assistant', content: response }
 
           tool_results = execute_tools(executor, tool_calls)
-          conversation << { role: "user", content: tool_results }
+          conversation << { role: 'user', content: tool_results }
 
           final_text = text_content unless text_content.empty?
         end
@@ -68,7 +68,7 @@ module RubynCode
 
       def build_conversation
         [
-          { role: "user", content: @prompt }
+          { role: 'user', content: @prompt }
         ]
       end
 
@@ -108,7 +108,7 @@ module RubynCode
         when String
           response
         when Hash
-          content = response[:content] || response["content"]
+          content = response[:content] || response['content']
           extract_text_from_content(content)
         when Array
           extract_text_from_content(response)
@@ -121,43 +121,43 @@ module RubynCode
         return content.to_s unless content.is_a?(Array)
 
         content
-          .select { |block| block_type(block) == "text" }
-          .map { |block| block[:text] || block["text"] }
+          .select { |block| block_type(block) == 'text' }
+          .map { |block| block[:text] || block['text'] }
           .compact
           .join("\n")
       end
 
       def extract_tool_calls(response)
         content = case response
-                  when Hash then response[:content] || response["content"]
+                  when Hash then response[:content] || response['content']
                   when Array then response
                   else return []
                   end
 
         return [] unless content.is_a?(Array)
 
-        content.select { |block| block_type(block) == "tool_use" }
+        content.select { |block| block_type(block) == 'tool_use' }
       end
 
       def block_type(block)
-        (block[:type] || block["type"]).to_s
+        (block[:type] || block['type']).to_s
       end
 
       def execute_tools(executor, tool_calls)
         tool_calls.map do |call|
-          tool_name = call[:name] || call["name"]
-          tool_input = call[:input] || call["input"] || {}
-          tool_id = call[:id] || call["id"]
+          tool_name = call[:name] || call['name']
+          tool_input = call[:input] || call['input'] || {}
+          tool_id = call[:id] || call['id']
 
           # Prevent recursive sub-agent spawning
           result = if SUB_AGENT_TOOLS.include?(tool_name)
-                     "Error: Sub-agents cannot spawn other sub-agents."
+                     'Error: Sub-agents cannot spawn other sub-agents.'
                    else
                      executor.execute(tool_name, tool_input)
                    end
 
           {
-            type: "tool_result",
+            type: 'tool_result',
             tool_use_id: tool_id,
             content: result.to_s
           }

data/lib/rubyn_code/sub_agents/summarizer.rb

@@ -8,7 +8,7 @@ module RubynCode
 
       class << self
         def call(text, max_length: DEFAULT_MAX_LENGTH)
-          return "" if text.nil? || text.empty?
+          return '' if text.nil? || text.empty?
 
           text = text.to_s.strip
 

data/lib/rubyn_code/tasks/RUBYN.md

@@ -0,0 +1,13 @@
+# Layer 7: Tasks
+
+Task tracking with DAG-based dependency management.
+
+## Classes
+
+- **`Manager`** — CRUD operations for tasks. Persists to the `tasks` SQLite table.
+  Supports status tracking, priority, ownership, and dependency resolution.
+
+- **`DAG`** — Directed acyclic graph for task dependencies. Determines which tasks are
+  ready to run (all dependencies met), detects cycles, and computes execution order.
+
+- **`Models`** — Data objects for tasks and dependencies. Maps to/from SQLite rows.

data/lib/rubyn_code/tasks/dag.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "set"
-
 module RubynCode
   module Tasks
     # Directed acyclic graph tracking task dependencies.
@@ -24,13 +22,13 @@ module RubynCode
       # @raise [ArgumentError] if this would create a cycle
       # @return [void]
       def add_dependency(task_id, depends_on_id)
-        raise ArgumentError, "A task cannot depend on itself" if task_id == depends_on_id
-        raise ArgumentError, "Cycle detected" if reachable?(depends_on_id, task_id)
+        raise ArgumentError, 'A task cannot depend on itself' if task_id == depends_on_id
+        raise ArgumentError, 'Cycle detected' if reachable?(depends_on_id, task_id)
 
         return if @forward[task_id].include?(depends_on_id)
 
         @db.execute(
-          "INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_id) VALUES (?, ?)",
+          'INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_id) VALUES (?, ?)',
           [task_id, depends_on_id]
         )
         @forward[task_id].add(depends_on_id)
@@ -44,7 +42,7 @@ module RubynCode
       # @return [void]
       def remove_dependency(task_id, depends_on_id)
         @db.execute(
-          "DELETE FROM task_dependencies WHERE task_id = ? AND depends_on_id = ?",
+          'DELETE FROM task_dependencies WHERE task_id = ? AND depends_on_id = ?',
           [task_id, depends_on_id]
         )
         @forward[task_id].delete(depends_on_id)
@@ -94,11 +92,11 @@ module RubynCode
         dependents_of(completed_task_id).each do |dep_id|
           next if blocked?(dep_id)
 
-          rows = @db.query("SELECT status FROM tasks WHERE id = ?", [dep_id]).to_a
+          rows = @db.query('SELECT status FROM tasks WHERE id = ?', [dep_id]).to_a
           next if rows.empty?
 
-          current_status = rows.first["status"]
-          next unless current_status == "blocked"
+          current_status = rows.first['status']
+          next unless current_status == 'blocked'
 
           @db.execute(
             "UPDATE tasks SET status = 'pending', updated_at = datetime('now') WHERE id = ?",
@@ -151,9 +149,7 @@ module RubynCode
           end
         end
 
-        if sorted.size != all_nodes.size
-          raise "Cycle detected in task dependency graph"
-        end
+        raise 'Cycle detected in task dependency graph' if sorted.size != all_nodes.size
 
         sorted
       end
@@ -173,10 +169,10 @@ module RubynCode
       end
 
       def load_from_db
-        rows = @db.query("SELECT task_id, depends_on_id FROM task_dependencies").to_a
+        rows = @db.query('SELECT task_id, depends_on_id FROM task_dependencies').to_a
         rows.each do |row|
-          tid = row["task_id"]
-          did = row["depends_on_id"]
+          tid = row['task_id']
+          did = row['depends_on_id']
           @forward[tid].add(did)
           @reverse[did].add(tid)
         end
@@ -201,7 +197,7 @@ module RubynCode
       end
 
       def placeholders(count)
-        (["?"] * count).join(", ")
+        (['?'] * count).join(', ')
       end
     end
   end