rails-conventions

name	rails-conventions
description	Rails 8.x application architecture, implementation, and review guidance for production codebases. Use when building or reviewing Ruby on Rails 8 features across models, controllers, routes, Hotwire, jobs, APIs, performance, security, and testing. Trigger for requests mentioning Rails 8, Active Record, Active Job, GoodJob, Solid Queue, Turbo/Stimulus, REST resources, migrations, code quality, naming, and production readiness.
license	MIT
compatibility	Compatible with any agent runtime that supports the Agent Skills SKILL.md convention and optional references directory loading.
metadata	{"ethos_link.company":"Ethos Link","ethos_link.company_url":"https://www.ethos-link.com","ethos_link.product":"Reviato","ethos_link.product_url":"https://www.reviato.com","ethos_link.maintainer":"ethos-link","ethos_link.contact_url":"https://www.ethos-link.com/contact/"}

Rails Convention Engineer

Follow this workflow and load only the references needed for the task.

Execution Workflow

1. Inspect the codebase before proposing changes.
2. Match existing conventions unless the user requests a migration.
3. Use Rails conventions and plain Ruby first.
4. Prefer small, reversible changes with tests.
5. Report tradeoffs explicitly when choosing architecture.

Mandatory Codebase Scan

Always read these files first when available:

• Gemfile
• config/application.rb
• config/routes.rb
• config/environments/*.rb (at least current target env)
• app/models/ (2-5 representative models)
• app/controllers/ (2-5 representative controllers)
• test/ or spec/
• process/deploy entrypoints (Procfile*, bin/jobs, config/deploy*.yml, CI config)

Record and follow observed patterns:

• test framework
• authentication/authorization style
• frontend stack (Hotwire, React, hybrid)
• queue backend and runtime topology
• API conventions and serialization style

Background Job Backend Policy

Never assume Solid Queue just because the app is Rails 8.

Detect backend in this order:

1. config.active_job.queue_adapter
2. Gemfile gems (good_job, solid_queue, others)
3. worker runtime commands and deployment wiring

Apply these rules:

• If good_job is active, keep good_job conventions.
• If solid_queue is active, keep solid_queue conventions.
• If both gems exist, treat the configured adapter as authoritative.
• Do not migrate queue backend implicitly as part of unrelated tasks.
• Write backend-agnostic ApplicationJob code unless backend features are explicitly requested.

Reference Routing

Load references based on the task:

• Code style, formatting, naming conventions, and fail-fast policy: STYLE.md
• Baseline Rails 8 defaults and upgrade constraints: references/01-baseline-rails-8.md
• Naming, layering, and code organization: references/02-naming-and-structure.md
• Active Record, migrations, and data modeling: references/03-models-and-data.md
• Controllers, params, and request flow: references/04-controllers-and-params.md
• REST resources and routes: references/05-routes-rest-and-resources.md
• Hotwire, Turbo, and Stimulus patterns: references/06-hotwire-turbo-stimulus.md
• Job architecture and adapter detection: references/07-background-jobs-overview.md
• GoodJob-specific patterns: references/07a-background-jobs-good_job.md
• Solid Queue-specific patterns: references/07b-background-jobs-solid_queue.md
• Performance and caching strategy: references/08-performance-caching-and-db.md
• Security review checklist: references/09-security-checklist.md
• Test strategy and quality gates: references/10-testing-strategy.md
• API-only and mixed-mode API patterns: references/11-api-mode-and-serialization.md
• 37signals-inspired style profile: references/12-37signals-inspired-profile.md
• Code quality thresholds and detection patterns: references/13-code-quality-gates.md

Authentication Patterns

Prefer Rails 8.1 built-in authentication. When implementing custom auth:

• Use password-based authentication with bcrypt via has_secure_password.
• Use magic link codes (not full magic link URLs) for account confirmation and email verification.
• Follow 37signals naming: Identity (global email-based), User (per-account membership), Session.
• Rate limit authentication endpoints aggressively.
• Store sessions via signed cookies with httponly and same_site: :lax.

Output Contract

For implementation tasks, produce:

1. Required schema changes with migrations.
2. Model/controller/view/job code following local conventions.
3. Tests matching local framework.
4. Brief risk notes (security, performance, rollout concerns).

For review tasks, prioritize:

1. Correctness and behavioral regressions.
2. Security and data integrity.
3. Performance and operability.
4. Test gaps.