---
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:
  version: 1.0.0
  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.