my-ruby-coding-agents 0.1.0

data/doc/README.md

@@ -0,0 +1,178 @@
+# my-ruby-coding-agents
+
+Install a shared set of Ruby and Rails coding agents into a project for Codex and
+Claude Code. The gem keeps each agent's instructions in one Markdown template
+and renders the tool-specific files for you.
+
+The installer also adds a short delegation guide to `AGENTS.md` and
+`CLAUDE.md`. It uses marker comments so later runs update the guide instead of
+adding duplicates.
+
+## Installation
+
+Requires Ruby 4.0 or newer.
+
+```sh
+gem install my-ruby-coding-agents
+```
+
+Or add it to a bundle:
+
+```sh
+bundle add my-ruby-coding-agents
+```
+
+## Usage
+
+Install both Codex and Claude Code agents into the current directory:
+
+```sh
+my-ruby-coding-agents install
+```
+
+Pass a project directory, choose one target, or preview the changes:
+
+```sh
+my-ruby-coding-agents install ./my-app --codex
+my-ruby-coding-agents install ./my-app --claude
+my-ruby-coding-agents install ./my-app --dry-run
+```
+
+`install` writes `.codex/agents/*.toml` and `.claude/agents/*.md`, plus the
+delegation section in `AGENTS.md` and `CLAUDE.md`. The directory defaults to
+`.`. `--codex` and `--claude` limit which tool's files are installed; with
+neither flag, both targets are installed.
+
+### Refreshing after a gem upgrade
+
+Each generated agent file has a marker line with a hash of its content: a
+`# my-ruby-coding-agents: <hash>` comment on the first line of the TOML file,
+and an `<!-- my-ruby-coding-agents: <hash> -->` comment right after the
+frontmatter of the Markdown file. Codex and Claude Code ignore these comments.
+The installer uses the hash to tell a file nobody edited from an edited one.
+
+Running `install` again applies these rules to each agent file:
+
+| File state | Action |
+| --- | --- |
+| Missing | `write` |
+| Generated, not edited, same as the gem | `skip ... (up to date)` |
+| Generated, not edited, gem has a newer version | `update` |
+| Edited by hand, or no marker | `skip ... (edited; use --force to overwrite)` |
+
+So after a gem upgrade, a plain `install` refreshes every agent file you did
+not edit and keeps your edits. Use `--force` to overwrite all agent files,
+including edited ones:
+
+```sh
+my-ruby-coding-agents install ./my-app --force
+```
+
+Agent files installed by a version without markers count as edited. Run
+`install --force` once to replace them with marked files.
+
+`--dry-run` prints the same lines with a `would ` prefix (`would write`,
+`would update`, `would overwrite`) and writes nothing.
+
+The delegation section in `AGENTS.md` and `CLAUDE.md` sits between marker
+comments. `install` adds it when missing and replaces only that block when it
+is out of date; the rest of the file stays as is.
+
+### Checking a project
+
+`status` prints one line per file that `install` would manage, with its state:
+
+```sh
+my-ruby-coding-agents status ./my-app
+my-ruby-coding-agents status ./my-app --codex
+```
+
+```text
+up to date    .codex/agents/rails_explorer.toml
+outdated      .codex/agents/test_designer.toml
+edited        .claude/agents/rails_explorer.md
+missing       .claude/agents/ui_implementer.md
+missing block CLAUDE.md
+```
+
+Agent files are `missing`, `up to date`, `outdated` (not edited, but the gem
+has a newer version), or `edited` (edited by hand or without a marker).
+`AGENTS.md` and `CLAUDE.md` are `missing block`, `up to date`, or `outdated`.
+`status` exits with 0 when everything is up to date and 1 otherwise, so you
+can use it in CI.
+
+### CLAUDE.md that imports AGENTS.md
+
+Claude Code reads a line `@AGENTS.md` in `CLAUDE.md` as an import of
+`AGENTS.md`. When `CLAUDE.md` has a line that is exactly `@AGENTS.md`
+(surrounding spaces are fine), the installer does not add the block to
+`CLAUDE.md`, since Claude Code already gets it through the import:
+
+- With both targets (or with `--codex` too), it writes the block to
+  `AGENTS.md` and reports `skip CLAUDE.md (imports AGENTS.md)`.
+- With only `--claude`, it writes the block to `AGENTS.md` instead and
+  reports `write AGENTS.md (imported by CLAUDE.md)`.
+
+A linked `CLAUDE.md` that points to `AGENTS.md` is also written only once.
+
+List the included agents with their tier, models, and efforts:
+
+```sh
+my-ruby-coding-agents list
+```
+
+Each line shows the agent name, tier, Codex model and effort, Claude model and
+effort, and description:
+
+```text
+rails_explorer | fast | Codex: gpt-6-luna (low) | Claude: sonnet (low) | Trace a Ruby workflow ...
+```
+
+The twelve agents are `rails_explorer`, `contract_mapper`, `test_designer`,
+`rails_implementer`, `api_cli_implementer`, `evidence_reviewer`,
+`quality_investigator`, `ui_implementer`, `security_mapper`,
+`security_reviewer`, `code_archaeologist`, and `pr_readiness_checker`.
+
+`code_archaeologist` researches how and why part of the code works and writes
+what it finds into `docs/archaeology/`, one note per topic plus an index. On
+later runs it re-checks existing notes against the code and updates or marks
+them stale instead of adding duplicates. Its tool list includes `Write` and
+`Edit`, so the folder limit is an instruction, not a fence. Add a permission
+rule in your tool's settings if you want to enforce it.
+
+`pr_readiness_checker` uses the `gh` CLI to read open pull requests on a public
+repository and reports which are ready to merge, which need changes from the
+contributor, and which need a decision from you. It never merges, labels, or
+posts comments. Run it from a checkout where `gh auth status` succeeds.
+
+Use the generated delegation guide to choose a focused agent for independent
+work. Handle small, coupled tasks yourself; parallelize independent bounded
+tasks when the benefit outweighs coordination and token costs. Implementers
+may add tests for their changes, with independent review for consequential
+work. The names `rails_explorer` and `rails_implementer` also cover standalone
+Ruby projects; the fleet keeps the same names across projects.
+
+Models come from a tier table in `templates/models.yml`. Each tier (`fast`,
+`investigate`, `implement`, `strong`, `review`) sets a model and reasoning effort for
+Codex and for Claude, and each agent template names one tier with `tier:`.
+Edit `templates/models.yml` to change routing; it is the one place model names
+live. The installer builds the model sentence in the delegation guide from the
+same table, so the guide, the agent files, and `list` always agree.
+
+Model assignments are starting points, not benchmark-proven rankings. The lead
+narrows ambiguous or unsuccessful tasks or uses a stronger available model;
+there is no automatic model router.
+
+## Development
+
+After checking out the repository, run `bin/setup`, then `bundle exec rake` to
+run the tests and RuboCop. `bundle exec rake docs` regenerates the Markdown API
+docs in `doc/` and `llms.txt`; both ship inside the gem, so commit them.
+`bin/prepare_release` runs the whole gate and builds the gem into `pkg/`.
+`bundle exec rake branchproof` runs the tests under
+[Branchproof](https://github.com/lucianghinda/branchproof) and lists decisions
+in `lib/` that the tests do not fully exercise. CI runs the same analysis.
+
+## License
+
+Released under the MIT License. See [LICENSE.txt](LICENSE.txt).

data/exe/my-ruby-coding-agents

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "my_ruby_coding_agents"
+
+exit(MyRubyCodingAgents::CLI.run(ARGV))

data/lib/my_ruby_coding_agents/agent.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MyRubyCodingAgents
+  # Parsed metadata and shared instruction body for one agent template.
+  # Models and efforts come from the agent's tier in the Models table.
+  class Agent
+    FIELDS = %w[name description tier tools].freeze
+    REQUIRED_FIELDS = %w[name description tier].freeze
+
+    attr_reader :name, :description, :tier, :tools, :body
+
+    # tier is a Models::Tier.
+    def initialize(name:, description:, tier:, tools:, body:)
+      @name = name
+      @description = description
+      @tier = tier
+      @tools = Array(tools).flat_map { |tool| tool.to_s.split(/\s*,\s*/) }.freeze if tools
+      @body = body.to_s.strip.freeze
+      freeze
+    end
+
+    def codex_model = tier.codex_model
+    def codex_effort = tier.codex_effort
+    def claude_model = tier.claude_model
+    def claude_effort = tier.claude_effort
+
+    def self.parse(source, models:)
+      metadata, body = split(source)
+      check_fields(metadata.keys.map(&:to_s))
+      new(name: metadata["name"], description: metadata["description"], tier: models.fetch(metadata["tier"]),
+          tools: metadata["tools"], body:)
+    end
+
+    # Returns the frontmatter mapping and the body text.
+    def self.split(source)
+      match = source.match(/\A---\s*\r?\n(.*?)\r?\n---\s*\r?\n(.*)\z/m)
+      raise ArgumentError, "agent template must begin with YAML frontmatter" unless match
+
+      metadata = YAML.safe_load(match[1], permitted_classes: [], aliases: false)
+      raise ArgumentError, "agent frontmatter must be a mapping" unless metadata.is_a?(Hash)
+
+      [metadata, match[2]]
+    rescue Psych::Exception => e
+      raise ArgumentError, "invalid agent frontmatter: #{e.message}"
+    end
+    private_class_method :split
+
+    def self.check_fields(keys)
+      unknown = keys - FIELDS
+      raise ArgumentError, "unknown agent fields: #{unknown.join(", ")}" unless unknown.empty?
+
+      missing = REQUIRED_FIELDS - keys
+      raise ArgumentError, "missing agent fields: #{missing.join(", ")}" unless missing.empty?
+    end
+    private_class_method :check_fields
+
+    def self.load(path, models:)
+      parse(File.read(path), models:)
+    rescue ArgumentError => e
+      raise ArgumentError, "#{File.basename(path)}: #{e.message}"
+    end
+  end
+end

data/lib/my_ruby_coding_agents/cli.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module MyRubyCodingAgents
+  # Handles the command line interface for installing, checking, and listing agents.
+  class CLI
+    def self.run(argv, out: $stdout, err: $stderr)
+      new(argv, out:, err:).run
+    end
+
+    def initialize(argv, out:, err:)
+      @argv = argv.dup
+      @out = out
+      @err = err
+    end
+
+    def run
+      dispatch(@argv.shift) || 0
+    rescue OptionParser::ParseError, ArgumentError => e
+      @err.puts(e.message)
+      2
+    end
+
+    private
+
+    def dispatch(command)
+      case command
+      when "install" then install
+      when "status" then status
+      when "list" then list
+      when "--version", "-v" then @out.puts(MyRubyCodingAgents::VERSION)
+      when "--help", "-h", nil then @out.puts(help)
+      else unknown_command(command)
+      end
+    end
+
+    def unknown_command(command)
+      @err.puts("Unknown command: #{command}")
+      @err.puts(help)
+      2
+    end
+
+    def install
+      options = parse_options("install")
+      return 0 if options[:help]
+
+      installer(options).install(force: options[:force], dry_run: options[:dry_run], out: @out)
+      0
+    end
+
+    # Exit 0 when every planned file is up to date, 1 otherwise.
+    def status
+      options = parse_options("status")
+      return 0 if options[:help]
+
+      installer(options).status(out: @out) ? 0 : 1
+    end
+
+    def parse_options(command)
+      options = { targets: [], force: false, dry_run: false, help: false }
+      option_parser(command, options).parse!(@argv)
+      raise OptionParser::InvalidArgument, "expected at most one target directory" if @argv.length > 1
+
+      options[:targets] = %i[codex claude] if options[:targets].empty?
+      options
+    end
+
+    def option_parser(command, options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: my-ruby-coding-agents #{command} [DIR] [options]"
+        opts.on("--codex", "Use Codex agents and AGENTS.md") { options[:targets] << :codex }
+        opts.on("--claude", "Use Claude agents and CLAUDE.md") { options[:targets] << :claude }
+        add_install_options(opts, options) if command == "install"
+        opts.on("-h", "--help", "Show this help") { show_help(opts, options) }
+      end
+    end
+
+    def add_install_options(opts, options)
+      opts.on("--force", "Overwrite agent files, including edited ones") { options[:force] = true }
+      opts.on("--dry-run", "Show planned writes without changing files") { options[:dry_run] = true }
+    end
+
+    def show_help(opts, options)
+      @out.puts(opts)
+      options[:help] = true
+    end
+
+    def installer(options)
+      models = Templates.models
+      agents = Templates.agents(models)
+      Installer.new(dir: @argv.first || ".", agents:, instructions: Templates.instructions(models, agents),
+                    targets: options[:targets])
+    end
+
+    def list
+      Templates.agents(Templates.models).each { |agent| @out.puts(list_line(agent)) }
+      0
+    end
+
+    def list_line(agent)
+      [agent.name, agent.tier.name, "Codex: #{agent.codex_model} (#{agent.codex_effort})",
+       "Claude: #{agent.claude_model} (#{agent.claude_effort})", agent.description].join(" | ")
+    end
+
+    def help
+      <<~HELP
+        Usage: my-ruby-coding-agents <command> [options]
+
+        Commands:
+          install [DIR]  Install or refresh agents and delegation instructions (default DIR: .)
+          status [DIR]   Show which files are missing, outdated, edited, or up to date
+          list           List bundled agents
+
+        Options:
+          --codex        Use Codex files only
+          --claude       Use Claude Code files only
+          --force        install: overwrite agent files, including edited ones
+          --dry-run      install: show planned writes without changing files
+          -v, --version  Show version
+          -h, --help     Show this help
+
+        install writes missing files and refreshes generated agent files nobody
+        edited. It skips edited agent files unless --force is given.
+        status exits 0 when everything is up to date and 1 otherwise.
+      HELP
+    end
+  end
+end

data/lib/my_ruby_coding_agents/generated.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module MyRubyCodingAgents
+  # Marks rendered agent files with a hash of their content, so a later
+  # install can tell an untouched generated file from one a person edited.
+  module Generated
+    NAME = "my-ruby-coding-agents"
+    MARKER = /^(?:# #{NAME}: (?<hash>[0-9a-f]{16})|<!-- #{NAME}: (?<hash>[0-9a-f]{16}) -->)\r?\n/
+    FRONTMATTER = /\A---\r?\n.*?\r?\n---\r?\n/m
+
+    module_function
+
+    # Adds the marker line. style is :toml (first line) or :markdown
+    # (right after the frontmatter). The hash covers the content without
+    # the marker line.
+    def stamp(content, style:)
+      hash = digest(content)
+      case style
+      when :toml then "# #{NAME}: #{hash}\n#{content}"
+      when :markdown then stamp_markdown(content, hash)
+      else raise ArgumentError, "unknown marker style: #{style.inspect}"
+      end
+    end
+
+    # :unmodified when the marker hash matches the rest of the file,
+    # :modified when it does not, :foreign when there is no marker.
+    def status(existing_content)
+      match = existing_content.match(MARKER)
+      return :foreign unless match
+
+      rest = match.pre_match + match.post_match
+      match[:hash] == digest(rest) ? :unmodified : :modified
+    end
+
+    def digest(content)
+      Digest::SHA256.hexdigest(content)[0, 16]
+    end
+
+    def stamp_markdown(content, hash)
+      match = content.match(FRONTMATTER)
+      raise ArgumentError, "Markdown content must begin with frontmatter" unless match
+
+      "#{match[0]}<!-- #{NAME}: #{hash} -->\n#{match.post_match}"
+    end
+    private_class_method :stamp_markdown
+  end
+end

data/lib/my_ruby_coding_agents/installer.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module MyRubyCodingAgents
+  # Writes planned files and reports the state of each one.
+  class Installer
+    START_MARKER = InstructionFile::START_MARKER
+    END_MARKER = InstructionFile::END_MARKER
+
+    WRITE_VERBS = { missing: "write", missing_block: "write", outdated: "update", edited: "overwrite" }.freeze
+    SKIP_REASONS = { up_to_date: "up to date", edited: "edited; use --force to overwrite",
+                     imported: "imports AGENTS.md" }.freeze
+    STATUS_LABELS = { missing: "missing", missing_block: "missing block", up_to_date: "up to date",
+                      outdated: "outdated", edited: "edited", imported: "skipped" }.freeze
+    CLEAN_STATES = %i[up_to_date imported].freeze
+
+    def initialize(dir:, agents:, instructions:, targets:)
+      @root = File.expand_path(dir)
+      @planner = Planner.new(root: @root, agents:, instructions:, targets:)
+    end
+
+    # Writes missing and outdated files. Edited agent files are kept unless
+    # force is true. Returns the number of planned files.
+    def install(out:, force: false, dry_run: false)
+      entries = @planner.entries
+      entries.each { |entry| apply(entry, force:, dry_run:, out:) }
+      entries.length
+    end
+
+    # Prints one state line per planned file. Returns true when nothing needs
+    # an install.
+    def status(out:)
+      entries = @planner.entries
+      entries.each { |entry| out.puts("#{STATUS_LABELS.fetch(entry.state).ljust(13)} #{describe(entry)}") }
+      entries.all? { |entry| CLEAN_STATES.include?(entry.state) }
+    end
+
+    private
+
+    def apply(entry, force:, dry_run:, out:)
+      if skip?(entry, force)
+        out.puts("skip #{relative(entry.path)} (#{SKIP_REASONS.fetch(entry.state)})")
+        return
+      end
+
+      out.puts("#{"would " if dry_run}#{WRITE_VERBS.fetch(entry.state)} #{describe(entry)}")
+      write(entry) unless dry_run
+    end
+
+    def skip?(entry, force)
+      CLEAN_STATES.include?(entry.state) || (entry.state == :edited && !force)
+    end
+
+    def write(entry)
+      FileUtils.mkdir_p(File.dirname(entry.path))
+      File.write(entry.path, entry.content)
+    end
+
+    def describe(entry)
+      entry.note ? "#{relative(entry.path)} (#{entry.note})" : relative(entry.path)
+    end
+
+    def relative(path)
+      path.delete_prefix("#{@root}/")
+    end
+  end
+end

data/lib/my_ruby_coding_agents/instruction_file.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module MyRubyCodingAgents
+  # Builds AGENTS.md and CLAUDE.md content with the managed delegation block.
+  module InstructionFile
+    START_MARKER = "<!-- my-ruby-coding-agents:start -->"
+    END_MARKER = "<!-- my-ruby-coding-agents:end -->"
+    BLOCK = /#{Regexp.escape(START_MARKER)}.*?#{Regexp.escape(END_MARKER)}/m
+    # A CLAUDE.md line that imports AGENTS.md in Claude Code.
+    IMPORT = /^[ \t]*@AGENTS\.md[ \t]*\r?$/
+
+    module_function
+
+    # Replaces the block in existing content, or appends it. existing may be nil.
+    def render(existing, instructions)
+      block = "#{START_MARKER}\n#{instructions.to_s.strip}\n#{END_MARKER}"
+      existing = existing.to_s
+      return existing.sub(BLOCK) { block } if block?(existing)
+
+      "#{[existing.rstrip, block].reject(&:empty?).join("\n\n")}\n"
+    end
+
+    def block?(content)
+      content.to_s.match?(BLOCK)
+    end
+
+    def imports_agents?(path)
+      File.file?(path) && File.read(path).match?(IMPORT)
+    end
+  end
+end

data/lib/my_ruby_coding_agents/models.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MyRubyCodingAgents
+  # Model tier table loaded from models.yml. Maps a tier name to the model
+  # and reasoning effort each tool uses.
+  class Models
+    TIER_KEYS = %w[summary codex claude].freeze
+    TOOL_KEYS = %w[model effort].freeze
+
+    # One resolved tier.
+    Tier = Data.define(:name, :summary, :codex_model, :codex_effort, :claude_model, :claude_effort)
+
+    def self.load(path)
+      parse(File.read(path))
+    end
+
+    def self.parse(source)
+      new(YAML.safe_load(source, permitted_classes: [], aliases: false))
+    rescue Psych::Exception => e
+      raise ArgumentError, "invalid models.yml: #{e.message}"
+    end
+
+    def initialize(table)
+      raise ArgumentError, "models.yml must map tier names to settings" unless table.is_a?(Hash) && !table.empty?
+
+      @tiers = table.to_h { |name, settings| [name.to_s, build_tier(name.to_s, settings)] }.freeze
+      freeze
+    end
+
+    # Tier names in file order.
+    def names
+      @tiers.keys
+    end
+
+    def fetch(name)
+      @tiers.fetch(name.to_s) do
+        raise ArgumentError, "unknown model tier: #{name.inspect} (known tiers: #{names.join(", ")})"
+      end
+    end
+
+    # One sentence per used tier: its purpose, models, and agents.
+    # Tiers keep file order and agents are sorted by name, so output is stable.
+    def routing(agents)
+      groups = agents.group_by { |agent| agent.tier.name }
+      parts = names.filter_map do |name|
+        next unless groups.key?(name)
+
+        "#{describe(fetch(name))}: #{groups[name].map { |agent| "`#{agent.name}`" }.sort.join(", ")}."
+      end
+      "Model tiers: #{parts.join(" ")}"
+    end
+
+    private
+
+    def describe(tier)
+      "`#{tier.name}` for #{tier.summary} (Codex #{tier.codex_model} #{tier.codex_effort}, " \
+        "Claude #{tier.claude_model} #{tier.claude_effort})"
+    end
+
+    def build_tier(name, settings)
+      check_keys(settings, TIER_KEYS, "tier #{name}")
+      check_string(settings["summary"], "tier #{name} summary")
+      codex = tool_settings(name, settings, "codex")
+      claude = tool_settings(name, settings, "claude")
+      Tier.new(name:, summary: settings["summary"].strip,
+               codex_model: codex["model"], codex_effort: codex["effort"],
+               claude_model: claude["model"], claude_effort: claude["effort"])
+    end
+
+    def tool_settings(name, settings, tool)
+      value = settings[tool]
+      check_keys(value, TOOL_KEYS, "tier #{name} #{tool}")
+      TOOL_KEYS.each { |key| check_string(value[key], "tier #{name} #{tool} #{key}") }
+      value
+    end
+
+    def check_keys(value, keys, label)
+      raise ArgumentError, "#{label} must be a mapping" unless value.is_a?(Hash)
+
+      unknown = value.keys.map(&:to_s) - keys
+      raise ArgumentError, "unknown keys in #{label}: #{unknown.join(", ")}" unless unknown.empty?
+
+      missing = keys - value.keys
+      raise ArgumentError, "missing keys in #{label}: #{missing.join(", ")}" unless missing.empty?
+    end
+
+    def check_string(value, label)
+      return if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, "#{label} must be a non-empty string"
+    end
+  end
+end