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.

Requires Ruby 4.0 or newer.

gem install my-ruby-coding-agents

Or add it to a bundle:

bundle add my-ruby-coding-agents

Install both Codex and Claude Code agents into the current directory:

my-ruby-coding-agents install

Pass a project directory, choose one target, or preview the changes:

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.

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:

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:

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.

status prints one line per file that install would manage, with its state:

my-ruby-coding-agents status ./my-app
my-ruby-coding-agents status ./my-app --codex

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 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:

my-ruby-coding-agents list

Each line shows the agent name, tier, Codex model and effort, Claude model and effort, and description:

rails_explorer | fast | Codex: gpt-6-luna (low) | Claude: sonnet (low) | Trace a Ruby workflow ...

The thirteen 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, pr_readiness_checker, and advisor.

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.

advisor is a read-only consultant for decisions before implementation: architecture tradeoffs, ambiguous requirements, a bug that stays unexplained after investigation, or changes that touch correctness, concurrency, or security. It uses the strongest models (Codex gpt-6-astra, Claude fable) at medium effort, so the delegation guide tells the lead not to call it for routine implementation, simple refactoring, or straightforward fixes. An advisor helps decide before the work; a reviewer judges finished work. Keep the roles separate to avoid needless calls to the expensive model.

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, advise) 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.

The existing implementation, test, quality, and security roles include focused Rails checks for query growth, stable pagination, tenant-scoped lookups, server-owned parameters, retryable jobs, external side effects, and migration rollout safety. They apply only to the changed behavior and require evidence of the project's Rails version, database, and queue adapter. The fuller checklist and official guide links are in Rails risk checks.

The Rails review pilot compares plain prompts with the role templates on three deliberately faulty Rails excerpts. It retains the tasks, scoring rubric, raw responses, and measured results. It measures static defect detection, not implementation success or general productivity; the same Luna model is used in both conditions to isolate the template content. The first results found all six seeded defects in both conditions, with no observed detection improvement.

plugins/advisor is a plugin for Claude Code and Codex that turns the advisor agent into a workflow. With /advisor on, the lead agent writes a briefing and consults the advisor at four checkpoints: before a major decision, when stuck, before declaring a change done, and on request. Hooks mark pending edits, log each consult to .advisor/log.md, and nudge once when a turn ends with edits nobody consulted on.

Install it together with the agents:

my-ruby-coding-agents install ./my-app --advisor

After the usual file writes, --advisor runs each selected tool's own plugin commands with this repository as the marketplace:

codex plugin marketplace add lucianghinda/my-ruby-coding-agents
codex plugin add advisor@my-ruby-coding-agents
claude plugin marketplace add lucianghinda/my-ruby-coding-agents
claude plugin install advisor@my-ruby-coding-agents --scope project

Both tools accept these commands again on later runs. Claude Code records the plugin in the project's .claude/settings.json; Codex enables it in ~/.codex/config.toml and caches a copy. A tool missing from PATH is skipped. A failed command stops that tool and makes install exit 1. --dry-run prints the commands without running them. Use --advisor-source to point at a checkout of this repository instead of GitHub, for example while developing the plugin.

The plugin carries the skill and the hooks. The advisor agent itself comes from the regular install, so --advisor needs the agents installed too. See plugins/advisor/README.md for the details.

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 and lists decisions in lib/ that the tests do not fully exercise. CI runs the same analysis.

Released under the MIT License. See LICENSE.txt.