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

1 hook across 1 event

Ruby Language Server Protocol (LSP) for code analysis, autocompletion, and error checking.