rails-specialist

Rails console helper for debugging and exploration

Run the Rails generator for the specified type.

Inspect and analyze Rails routes

Run and analyze Rails tests

Use this agent when working with Rails API controllers, implementing RESTful endpoints, designing API responses, handling API authentication/authorization, creating serializers, implementing API versioning, or optimizing API performance. This includes: - Creating API controllers in app/controllers/api/ - Designing JSON responses and serializers - Implementing API authentication (JWT, tokens) - Adding API versioning - Handling pagination and filtering - Documenting API endpoints Examples: <example> Context: User has just created a new API endpoint. user: "I've created a new products API endpoint that returns all products" assistant: "Let me review that API implementation using the rails-api-pro agent to ensure it follows RESTful best practices, includes proper pagination, error handling, and serialization." <commentary> API review requires expertise in REST conventions, pagination, and response formatting. </commentary> </example> <example> Context: User is implementing authentication for their API. user: "Can you help me add JWT authentication to my API controllers?" assistant: "I'll use the rails-api-pro agent to implement JWT authentication following Rails API best practices." <commentary> API authentication requires understanding of token-based auth and Rails security patterns. </commentary> </example> <example> Context: User is creating a new API version. user: "I need to create a v2 of the products API with a different response structure" assistant: "I'll use the rails-api-pro agent to help design and implement the v2 API with proper versioning strategy." <commentary> API versioning requires careful planning for backward compatibility. </commentary> </example> <example> Context: User needs help with API serialization. user: "How should I structure the JSON response for my orders endpoint?" assistant: "Let me use the rails-api-pro agent to design an efficient, consistent JSON response structure for your orders API." <commentary> API response design requires understanding of JSON:API, serialization patterns, and consistency. </commentary> </example>

Use this agent when you need to coordinate Rails application development, plan feature implementations, or orchestrate work across multiple Rails stack layers. This agent excels at breaking down complex requirements into actionable tasks and delegating to appropriate specialists while maintaining architectural coherence. <example> Context: The user needs to implement a new feature in their Rails application. user: "I need to add a commenting system to my blog posts" assistant: "I'll use the rails-architect agent to plan and coordinate the implementation of your commenting system." <commentary> Since this involves multiple layers of the Rails stack (models, controllers, views, tests), the rails-architect agent should coordinate the implementation. </commentary> </example> <example> Context: The user wants to refactor existing Rails code. user: "Can you help me refactor this fat controller into proper service objects?" assistant: "Let me engage the rails-architect agent to analyze your controller and coordinate the refactoring into service objects." <commentary> The rails-architect agent will analyze the controller, plan the service object extraction, and coordinate with specialists to implement the refactoring. </commentary> </example> <example> Context: The user needs architectural guidance for their Rails app. user: "What's the best way to structure background jobs for sending emails in my Rails app?" assistant: "I'll consult the rails-architect agent to provide architectural guidance on structuring your background email jobs." <commentary> The rails-architect agent can provide architectural decisions and coordinate implementation using Rails best practices. </commentary> </example>

Use this agent when you need to create, modify, or review background job implementations, mailers, or async processing. This includes: - Creating ActiveJob classes for async processing - Implementing retry strategies and error handling - Optimizing job performance and queue management - Setting up Action Mailer for email delivery - Implementing scheduled jobs and cron-like tasks - Working with Sidekiq, Solid Queue, or other backends - Debugging job failures Examples: <example> Context: User needs to send emails asynchronously. user: "I need to send confirmation emails after order creation without blocking the request" assistant: "I'll use the rails-background-pro agent to create an efficient background job for async email delivery." <commentary> Async email delivery via background jobs is core expertise of rails-background-pro. </commentary> </example> <example> Context: User has a job that keeps failing. user: "My ProcessPaymentJob keeps failing with timeout errors" assistant: "Let me use the rails-background-pro agent to analyze the job failures and implement proper retry strategies." <commentary> Job failure debugging and retry logic requires deep understanding of ActiveJob patterns. </commentary> </example> <example> Context: User needs to process a large dataset. user: "I need to import 100,000 records from a CSV file without blocking the server" assistant: "I'll use the rails-background-pro agent to design a batch processing strategy using background jobs." <commentary> Large dataset processing requires batch job patterns and queue management. </commentary> </example> <example> Context: User needs to set up scheduled tasks. user: "I want to send a daily digest email to all users at 9am" assistant: "Let me use the rails-background-pro agent to set up a scheduled job for the daily digest." <commentary> Scheduled/recurring jobs require cron setup and job scheduling patterns. </commentary> </example>

Use this agent when working with Rails controllers, routes, or request/response handling. This includes: - Creating new controllers in app/controllers/ - Implementing RESTful actions (index, show, new, create, edit, update, destroy) - Configuring routes in config/routes.rb - Adding before_action filters and authentication - Handling strong parameters - Implementing error handling and rescue_from - Working with concerns and shared controller logic Examples: <example> Context: User needs to create a new controller for managing blog posts. user: "I need to create a controller for blog posts with standard CRUD operations" assistant: "I'll use the rails-controller-pro agent to create a properly structured RESTful controller for blog posts." <commentary> Creating RESTful controllers with CRUD operations is a core responsibility of rails-controller-pro. </commentary> </example> <example> Context: User is refactoring a controller that has grown too large. user: "This UsersController has gotten really bloated. Can you help clean it up?" assistant: "I'll use the rails-controller-pro agent to refactor this controller following Rails best practices and extract business logic to appropriate service objects." <commentary> Controller refactoring and keeping controllers thin is within rails-controller-pro expertise. </commentary> </example> <example> Context: User needs to add authentication and authorization to a controller. user: "How do I add authentication to my ArticlesController?" assistant: "I'll use the rails-controller-pro agent to implement proper authentication and authorization patterns for your ArticlesController." <commentary> Authentication and authorization in controllers requires expertise in before_actions and filters. </commentary> </example> <example> Context: User needs help with routing configuration. user: "I want to add nested routes for comments under posts" assistant: "I'll use the rails-controller-pro agent to design and implement the appropriate routing configuration." <commentary> Routing design and nested resources are core controller responsibilities. </commentary> </example>

Use this agent when debugging Rails application issues, performance problems, or unexpected behavior. This includes: - Debugging runtime errors and exceptions - Identifying and fixing N+1 query problems - Analyzing slow database queries - Troubleshooting routing issues - Debugging authentication/authorization problems - Investigating memory leaks or performance issues - Analyzing production errors and stack traces - Debugging background job failures Examples: <example> Context: User is seeing an error in their Rails application. user: "I'm getting a NoMethodError: undefined method 'name' for nil:NilClass in my view" assistant: "Let me use the rails-debugger agent to analyze this error and identify where the nil value is coming from." <commentary> NoMethodError on nil is a common Rails debugging scenario requiring systematic analysis. </commentary> </example> <example> Context: User notices their page is slow. user: "My users index page takes 5 seconds to load, it used to be fast" assistant: "I'll use the rails-debugger agent to identify performance bottlenecks, check for N+1 queries, and analyze the slow queries." <commentary> Performance debugging requires query analysis and N+1 detection expertise. </commentary> </example> <example> Context: User's background job keeps failing. user: "My SendEmailJob keeps failing with a strange error" assistant: "Let me use the rails-debugger agent to analyze the job failures and identify the root cause." <commentary> Background job debugging requires understanding of job queuing and error handling. </commentary> </example> <example> Context: User has a routing issue. user: "I keep getting a routing error even though I defined the route" assistant: "I'll use the rails-debugger agent to analyze your routes configuration and identify the conflict." <commentary> Routing issues require systematic analysis of route precedence and conflicts. </commentary> </example>

Use this agent when working specifically with database migrations, schema changes, or data migrations. This includes: - Creating new migration files in db/migrate/ - Adding, removing, or modifying columns - Creating or dropping tables - Adding indexes, foreign keys, or constraints - Writing data migrations for existing records - Handling complex schema changes safely - Rolling back or fixing problematic migrations Examples: <example> Context: User needs to add a new column to an existing table. user: "I need to add an 'archived' boolean column to the posts table" assistant: "I'll use the rails-migration-pro agent to create a safe migration for adding the archived column with the appropriate default and index." <commentary> Adding columns requires careful consideration of defaults, nullability, and indexes. </commentary> </example> <example> Context: User needs to rename a column without losing data. user: "I need to rename the 'name' column to 'title' in the articles table" assistant: "Let me use the rails-migration-pro agent to create a safe, reversible migration for renaming this column." <commentary> Column renames need to be handled carefully to avoid downtime and data loss. </commentary> </example> <example> Context: User needs to perform a data migration. user: "I need to migrate all existing users' full_name into separate first_name and last_name columns" assistant: "I'll use the rails-migration-pro agent to design a safe data migration strategy that handles the transformation." <commentary> Data migrations require careful planning to avoid data loss and handle edge cases. </commentary> </example> <example> Context: User has a migration that failed and needs help fixing it. user: "My migration failed halfway through and now the database is in a bad state" assistant: "Let me use the rails-migration-pro agent to analyze the situation and create a recovery strategy." <commentary> Migration recovery requires understanding of Rails migration internals and database state. </commentary> </example>

Use this agent when working with ActiveRecord models, database migrations, model associations, validations, or database schema design. This includes: - Creating or modifying models in app/models/ - Writing database migrations in db/migrate/ - Defining or refactoring model associations (has_many, belongs_to, etc.) - Adding or updating model validations - Implementing scopes and query methods - Optimizing database queries and addressing N+1 issues - Adding database indexes or constraints - Designing database schema changes - Implementing callbacks or model concerns Examples: <example> Context: User has just created a new model and wants it reviewed for best practices. user: "I've created a new Notification model. Can you review it?" assistant: "Let me use the rails-model-pro agent to review your Notification model for Rails best practices, proper associations, validations, and potential optimizations." <commentary> The user has added a new model that needs review. Use the rails-model-pro agent to ensure it follows Rails conventions. </commentary> </example> <example> Context: User is working on a feature that requires a new database table. user: "I need to add a feature for tracking user preferences. What's the best way to model this?" assistant: "I'll use the rails-model-pro agent to help design the database schema and create the appropriate model with validations and associations." <commentary> Database schema design and model creation is core expertise of rails-model-pro. </commentary> </example> <example> Context: User has performance issues with a model query. user: "The Product.with_recent_orders query is really slow. Can you help optimize it?" assistant: "Let me engage the rails-model-pro agent to analyze the query, identify N+1 issues or missing indexes, and suggest optimizations." <commentary> Query optimization and N+1 detection require deep ActiveRecord expertise. </commentary> </example> <example> Context: User is adding a new association between existing models. user: "I need to add a many-to-many relationship between Users and Projects" assistant: "I'll use the rails-model-pro agent to implement the association properly, including the join table migration, model associations, and any necessary indexes." <commentary> Complex associations with join tables require careful implementation. </commentary> </example>

Use this agent when you need to write, review, or improve tests for Rails code. This includes: - Writing model specs (validations, associations, methods) - Creating request/controller specs - Implementing system/feature specs with Capybara - Writing job and mailer specs - Setting up factories with FactoryBot - Implementing fixtures for Minitest - Reviewing test quality and coverage - Debugging failing tests **Proactive Usage Examples:** <example> Context: User has just written a new model method user: "I've added a full_name method to the User model that combines first_name and last_name" assistant: "Let me use the rails-test-pro agent to write comprehensive tests for this new method." <commentary> The user has added new functionality that needs test coverage. Proactively use rails-test-pro. </commentary> </example> <example> Context: User has created a new controller action user: "I've implemented the create action in UsersController" assistant: "I'll use the rails-test-pro agent to write request specs for this new endpoint." <commentary> New controller action requires request specs. Use rails-test-pro for proper coverage. </commentary> </example> <example> Context: User explicitly requests test writing user: "Can you write tests for the User model?" assistant: "I'll use the rails-test-pro agent to write comprehensive tests for the User model." <commentary> Direct request for test writing. Use rails-test-pro. </commentary> </example> <example> Context: User has failing tests user: "My user_spec.rb tests are failing and I don't understand why" assistant: "Let me use the rails-test-pro agent to analyze the failing tests and help debug the issue." <commentary> Test debugging requires deep understanding of Rails testing patterns. </commentary> </example>

Use this agent when you need to work with Rails views, templates, partials, layouts, or frontend components. This includes: - Creating or modifying ERB/HAML templates - Implementing view helpers - Organizing partials and layouts - Handling forms with form_with - Optimizing view performance with caching - Ensuring accessibility - Integrating Hotwire (Turbo/Stimulus) - Working with ViewComponents Examples: <example> Context: The user needs help creating or modifying views in their Rails application. user: "I need to create a new user profile page with a form to edit user details" assistant: "I'll use the rails-view-pro agent to help create the profile view with an edit form." <commentary> Since the user needs to create views and forms, use the rails-view-pro agent. </commentary> </example> <example> Context: The user wants to improve the frontend of their Rails app. user: "Can you help me refactor this view to use partials and add caching?" assistant: "Let me use the rails-view-pro agent to refactor your view with partials and implement fragment caching." <commentary> The user needs view refactoring and caching implementation. </commentary> </example> <example> Context: The user needs help with Hotwire integration. user: "I want to add live updates to my comments section using Turbo Streams" assistant: "I'll use the rails-view-pro agent to implement Turbo Streams for real-time comment updates." <commentary> Hotwire/Turbo integration is core expertise of rails-view-pro. </commentary> </example> <example> Context: The user needs help with view helpers. user: "I want to add a custom helper method for formatting dates across all my views" assistant: "I'll use the rails-view-pro agent to create a date formatting helper method." <commentary> Creating view helpers is a core responsibility of rails-view-pro. </commentary> </example>

Use when building or refactoring Rails controllers — structuring actions, defining routes, whitelisting parameters, or responding in multiple formats. Also applies when sharing logic across controllers with concerns, handling errors consistently, or adding Turbo Stream responses alongside HTML. Covers Rails 7+ patterns including params.expect.

Use when designing model associations, adding validations, writing complex queries, or organizing model code. Also applies when choosing between has_many :through and HABTM, optimizing queries with eager loading, or setting up callbacks and scopes. Covers associations, validations, query optimization, and model organization.

Use when adding interactive UI to a Rails application without custom JavaScript — inline editing, live updates, real-time notifications, or partial page navigation. Also applies when choosing between Turbo Frames, Turbo Streams, and Stimulus, or reviewing Hotwire implementation for correctness.

Use when needing to analyze a Rails codebase programmatically — inspecting models, schemas, routes, or controllers. Also applies when looking up library documentation or tracing method definitions across files. Covers Rails MCP Server tools, Context7 documentation queries, and Ruby LSP code intelligence.

Use when reviewing Rails code for quality issues, refactoring problematic code, or encountering symptoms like fat controllers, god models, callback chains with side effects, N+1 queries, logic-heavy views, or non-idempotent background jobs. Covers controller, model, query, view, job, and migration anti-patterns with bad/good examples and fixes.

Use when creating new Rails files, naming models/controllers/views, organizing directories, or when unsure about Rails naming conventions. Also applies when reviewing code for convention violations like incorrect pluralization, wrong file locations, or non-standard naming. Covers file structure, naming patterns for models, controllers, views, routes, jobs, mailers, and migrations.

Use when encountering slow page loads, high database query counts, memory bloat, or when optimizing a Rails application. Also applies when choosing a caching strategy, adding database indexes, or deciding what to move to background jobs. Covers N+1 prevention, eager loading, indexing, caching, pagination, and profiling tools.

Use when implementing authentication, authorization, or hardening a Rails application against vulnerabilities. Also applies before deployment to verify security posture, or when reviewing code for mass assignment, XSS, SQL injection, or CSRF risks. Covers strong parameters, Devise, Pundit, security scanning, and deployment checklists.

Use when writing or debugging tests in a Rails application, setting up test infrastructure, or choosing between RSpec and Minitest patterns. Also applies when creating factories, fixtures, shared examples, or mocking external services. Covers test strategy, framework detection, directory structure, and common patterns for all test types.

Use when controller actions grow beyond simple CRUD, business logic spans multiple models, or operations involve external APIs or multi-step transactions. Also applies when deciding whether to extract a service object, form object, or query object. Covers the Callable concern, Result objects, and file organization patterns.

1 hook across 1 event