Rails AI Suite (Agents, Commands, Skills)

A curated collection of specialized AI agents for Rails development, organized into four complementary components:

1. 37signals Agents - Inspired by DHH's "vanilla Rails" philosophy from the Fizzy codebase
2. Standard Rails Agents - Modern Rails patterns with service objects, query objects, and presenters
3. Feature Specification Agents - High-level planning and feature management
4. Skills Library - Reusable knowledge modules for specific Rails patterns and technologies

🆕 New: Check out the Claude Code Setup Plan for a complete guide on configuring Claude Code with Rails projects, including security hooks, custom commands, and MCP servers. Based on The Complete Guide to Claude Code V4.

Built using insights from GitHub's analysis of 2,500+ agent.md files and 37signals' Fizzy codebase analysis.

Why This Exists

Most AI coding assistants lack deep Rails context. This suite provides three distinct architectural philosophies:

• 🎯 37signals Style: Rich models, concerns, CRUD-everything approach
• 🏗️ Standard Rails: Service objects, query objects, presenters, form objects
• 📋 Feature Planning: Requirements analysis and implementation orchestration
• 📚 Skills Library: Deep knowledge modules for Rails patterns and technologies

Choose the style that fits your team's philosophy, or mix and match as needed.

---

37signals Agents

Inspired by the 37signals/DHH coding style guide extracted from the Fizzy codebase. These agents follow the "vanilla Rails is plenty" philosophy.

Core Philosophy

• Rich models over service objects - Business logic lives in models
• Everything is CRUD - New resource over new action
• State as records - Not boolean columns (e.g., Closure model instead of closed: true)
• Concerns for composition - Horizontal behavior sharing (e.g., Closeable, Watchable)
• Minimal dependencies - Build it yourself before reaching for gems
• Database-backed everything - No Redis, Solid Queue/Cache/Cable

Available Agents

• @37signals/model_agent - Rich models with concerns (Closeable, Watchable, etc.)
• @37signals/crud_agent - Enforce everything-is-CRUD routing
• @37signals/concerns_agent - Model & controller concerns for composition
• @37signals/state_records_agent - State as records pattern (not booleans)
• @37signals/auth_agent - Custom passwordless authentication (~150 LOC)
• @37signals/migration_agent - Simple, pragmatic migrations
• @37signals/test_agent - Minitest with fixtures
• @37signals/turbo_agent - Hotwire/Turbo patterns
• @37signals/stimulus_agent - Focused Stimulus controllers
• @37signals/events_agent - Event tracking system
• @37signals/multi_tenant_agent - URL-based multi-tenancy
• @37signals/jobs_agent - Solid Queue background jobs
• @37signals/mailer_agent - Simple mailers
• @37signals/caching_agent - Fragment & HTTP caching
• @37signals/api_agent - REST API with JSON format
• @37signals/refactoring_agent - Incremental refactoring
• @37signals/review_agent - Code review for consistency
• @37signals/implement_agent - General implementation agent

37signals Workflow Example

1. @37signals/crud_agent design routes for card closures (resource, not boolean)

2. @37signals/state_records_agent create Closure model

3. @37signals/concerns_agent add Closeable concern to Card model

4. @37signals/test_agent write Minitest tests

5. @37signals/implement_agent implement the feature

6. @37signals/review_agent check for 37signals conventions

Key Patterns

State as Records:

# ❌ Not This
class Card < ApplicationRecord
  # closed: boolean
  scope :closed, -> { where(closed: true) }
end

# ✅ This
class Closure < ApplicationRecord
  belongs_to :card, touch: true
  belongs_to :user
end

class Card < ApplicationRecord
  include Closeable  # Concern with close/reopen methods
  has_one :closure
  scope :closed, -> { joins(:closure) }
  scope :open, -> { where.missing(:closure) }
end

Everything is CRUD:

# ❌ Not This
resources :cards do
  post :close
  post :reopen
end

# ✅ This
resources :cards do
  resource :closure  # POST to close, DELETE to reopen
end

---

Standard Rails Agents

Modern Rails architecture with clear separation of concerns, SOLID principles, and comprehensive testing.

Core Philosophy

• Thin models & controllers - Delegate to service/query/presenter objects
• Service objects - Encapsulate business logic with Result pattern
• Query objects - Complex queries in dedicated classes (prevents N+1)
• Presenters - View logic separated from models
• Form objects - Multi-model forms
• Pundit policies - Authorization (deny by default)
• ViewComponent - Tested, reusable components
• TDD workflow - RED → GREEN → REFACTOR

Available Agents

Testing & TDD

• @tdd_red_agent - Writes failing tests FIRST (RED phase)
• @rspec_agent - RSpec expert for all test types
• @tdd_refactoring_agent - Refactors while keeping tests green

Implementation

• @model_agent - Thin ActiveRecord models
• @controller_agent - Thin RESTful controllers
• @service_agent - Business logic service objects
• @query_agent - Complex query objects
• @form_agent - Multi-model form objects
• @presenter_agent - View logic presenters
• @policy_agent - Pundit authorization
• @view_component_agent - ViewComponent + Hotwire
• @job_agent - Background jobs (Solid Queue)
• @mailer_agent - Mailers with previews
• @migration_agent - Safe migrations
• @implementation_agent - General implementation

Frontend

• @stimulus_agent - Stimulus controllers
• @turbo_agent - Turbo Frames/Streams
• @tailwind_agent - Tailwind CSS styling

Quality

• @review_agent - Code quality analysis
• @lint_agent - Style fixes (no logic changes)
• @security_agent - Security audits (Brakeman)

Standard Rails Workflow Example

1. @feature_planner_agent analyze the user authentication feature

2. @tdd_red_agent write failing tests for User model

3. @model_agent implement the User model

4. @tdd_red_agent write failing tests for AuthenticationService

5. @service_agent implement AuthenticationService

6. @controller_agent create SessionsController

7. @policy_agent create authorization policies

8. @review_agent check implementation

9. @tdd_refactoring_agent improve code structure

10. @lint_agent fix style issues

Key Patterns

Service Objects:

module Users
  class CreateService < ApplicationService
    def call
      # Returns Result.new(success:, data:, error:)
    end
  end
end

Thin Controllers:

def create
  authorize User
  result = Users::CreateService.call(params: user_params)

  if result.success?
    redirect_to result.data
  else
    render :new, status: :unprocessable_entity
  end
end

Query Objects:

class Users::SearchQuery
  def call(params)
    @relation
      .then { |rel| filter_by_status(rel, params[:status]) }
      .then { |rel| search_by_name(rel, params[:q]) }
  end
end

---

Feature Specification Agents

High-level planning and orchestration for complex features.

Available Agents

• @feature_specification_agent - Writes detailed feature specifications
• @feature_planner_agent - Breaks features into tasks, recommends agents
• @feature_reviewer_agent - Reviews completed features against specs

Feature Planning Workflow

1. @feature_specification_agent write spec for blog with comments

2. @feature_planner_agent create implementation plan

3. [Use recommended agents to implement]

4. @feature_reviewer_agent verify implementation matches spec

---

Skills Library

Reusable knowledge modules that provide deep context on specific Rails patterns and technologies. Skills are referenced by agents and can be used directly to provide comprehensive guidance.

What Are Skills?

Skills are focused knowledge documents that contain:

• Patterns & best practices - Proven approaches for specific domains
• Code examples - Real-world implementations
• Reference materials - Detailed documentation for complex topics
• Decision guidance - When and how to use specific patterns

Available Skills

Architecture & Patterns

• rails-architecture - Code organization decisions, layered architecture
• rails-concern - Shared behavior with concerns
• rails-service-object - Business logic encapsulation
• rails-query-object - Complex database queries
• rails-presenter - View logic separation
• rails-controller - RESTful controller patterns
• rails-model-generator - Model creation with validations
• form-object-patterns - Multi-model forms, wizards

Frontend & Hotwire

• hotwire-patterns - Turbo Frames, Turbo Streams, Stimulus integration
• viewcomponent-patterns - Reusable UI components with ViewComponent

Authentication & Authorization

• authentication-flow - Rails 8 built-in authentication
• authorization-pundit - Pundit policies and permissions

Data & Storage

• database-migrations - Safe, reversible migrations
• active-storage-setup - File uploads and attachments
• caching-strategies - Fragment, action, and HTTP caching

Background Jobs & Real-time

• solid-queue-setup - Background job processing
• action-cable-patterns -