--- name: vanilla-rails description: > Apply Vanilla Rails (37signals/Basecamp) as the default architecture when writing or changing Rails code: thin controllers, rich models, no service/query/interactor layer unless genuinely justified. Load this skill when creating or editing controllers, models, jobs, concerns, mailers, routes, or form objects; when adding a custom action versus a nested resource; when extracting a service, form, query, or interactor; or when deciding where business logic lives. Also use for Rails reviews and simplification. Do not wait for the user to say "vanilla rails" or "service object". Skip migrations, gem/dependency bumps, CSS/JS/view-only work, credentials, and non-Rails tasks. allowed-tools: - Grep - Glob - Read - Task ---

# Vanilla Rails

Default architecture when writing Rails, from the Vanilla Rails philosophy of 37signals/Basecamp. Apply it while implementing — do not wait for a review command or for the user to name the philosophy.

## Based on Fizzy

This skill is informed by [Fizzy](https://github.com/basecamp/fizzy) - a production Rails application from 37signals.

**Key Fizzy patterns:** - Controllers call Active Record directly: `@board.update!(board_params)`, `@card.comments.create!(comment_params)` - Models composed of concerns: `include Closeable, Golden, Postponable, Watchable` - State tracked with dedicated models: `has_one :closure`, `has_one :goldness` - No `app/services/` directory - Complex multi-step processes use plain objects or ActiveRecord models with state

## Quick Start

Vanilla Rails embraces Rails's built-in patterns and avoids premature abstraction:

**Core Philosophy:** Thin controllers that directly invoke a rich domain model. No service layers or other artifacts unless genuinely justified.

``` ┌─────────────────────────────────────────┐ │ CONTROLLERS │ │ (Thin - HTTP concerns only) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ MODELS │ │ (Rich - Business logic lives here) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ ACTIVE RECORD / DATABASE │ └─────────────────────────────────────────┘ ```

**Core Rule:** Don't add layers beyond what Rails provides unless you have a clear, justified reason.

## Default constraint

This skill is the house style for Rails work, not an optional review lens. When loaded during implementation, apply the principles below while writing code. Do not ask which review command to run.

**Do:** - Put domain logic on the model, or a namespaced concern of that model - Keep controllers to params + one model call - Prefer a new nested resource over a custom controller action - Keep jobs and mailers shallow: `_later` enqueues, `_now` does the work on the model

**Do not introduce** `app/services/`, `app/queries/`, interactors, managers, or handlers unless the bar in [When Services Are Actually OK](#when-services-are-actually-ok) is met — and say so in the change.

**Skip this overlay for** migrations, gem/dependency bumps, CSS/JS, view-only markup, credentials, and anything that is not Rails application code.

## Explicit commands

Use these only when the user asks to review, analyze, or plan a simplification — not as the default response to Rails implementation:

1. **Review code changes** - `/vanilla-rails:review` 2. **Analyze codebase** - `/vanilla-rails:analyze` 3. **Plan simplification** - `/vanilla-rails:simplify [goal]`

## Core Principles

### The Three Rules

1. **Thin Controllers** - Controllers only parse params and invoke model methods 2. **Rich Domain Model** - Business logic belongs in models 3. **No Premature Abstraction** - Don't create service layers by default

### Common Anti-Patterns

| Anti-Pattern | Example | Fix | |--------------|---------|-----| | Fat service | 100-line service with domain logic | Move logic to model | | Anemic model | Model with only attributes and associations | Add business methods | | Controller as orchestrator | Controller calling multiple services | Call rich model methods | | Premature service | Simple CRUD wrapped in service | Use plain Active Record | | Service explosion | DoSomethingService for every action | Most should be model methods |

See [Anti-Patterns Reference](references/anti-patterns.md) for complete list.

### When Services Are Actually OK

Services are justified when: - Coordinating multiple models (orchestration, not domain logic) - External API interactions - Multi-step workflows with transaction boundaries - Operations that don't naturally belong to any single model

**Fizzy uses plain objects for this:**

```ruby # Multi-step signup with ActiveModel::Model class Signup include ActiveModel::Model

validates :email_address, format: { with: URI::MailTo::EMAIL_REGEXP } validates :full_name, presence: true

def create_identity @identity = Identity.find_or_create_by!(email_address: email_address) @identity.send_magic_link(for: :sign_up) end

def complete # Complex account creation with rollback handling end end ```

**Fizzy uses ActiveRecord models for stateful operations:**

```ruby # Stateful import with status tracking class Account::Import < ApplicationRecord enum :status, %w[ pending processing completed failed ].index_by(&:itself), default: :pending

def process(start: nil, callback: nil) processing! # Import logic with ZIP file handling mark_completed rescue => e mark_as_failed raise e end end ```

## Style Preferences

### Conditional Returns

Prefer expanded conditionals over guard clauses (unless returning early at method start for non-trivial bodies).

```ruby # Bad - Guard clause def todos_for_new_group ids = params.require(:todolist)[:todo_ids] return [] unless ids @bucket.recordings.todos.find(ids.split(",")) end

# Good - Expanded conditional def todos_for_new_group if ids = params.require(:todolist)[:todo_ids] @bucket.recordings.todos.find(ids.split(",")) else [] end end ```

### Method Ordering

1. `class` methods 2. `public` methods (with `initialize` at top) 3. `private` methods

Order methods vertically by invocation order to help readers follow code flow.

### CRUD Controllers

Model endpoints as REST operations. Don't add custom actions - introduce new resources instead.

```ruby # Bad resources :cards do post :close post :reopen end

# Good resources :cards do resource :closure end ```

### Visibility Modifiers

No newline under visibility modifiers; indent content under them.

```ruby class SomeClass def some_method # ... end

private def some_private_method # ... end end ```

If a module only has private methods, mark `private` at top with extra newline but don't indent.

### Async Operations

Write shallow job classes that delegate to domain models: - Use `_later` suffix for methods that enqueue jobs - Use `_now` suffix for synchronous methods

```ruby # Fizzy pattern: _later enqueues, _now does the work module Event::Relaying extend ActiveSupport::Concern

included do after_create_commit :relay_later end

def relay_later Event::RelayJob.perform_later(self) end

def relay_now # actual implementation end end

class Event::RelayJob < ApplicationJob def perform(event) event.relay_now end end ```

### Bang Methods

Only use `!` for methods with a counterpart without `!`. Don't use `!` to flag destructive actions.

## Pattern Catalog

| Pattern | Use When | Reference | |---------|----------|-----------| | Plain Active Record | Simple CRUD, no coordination needed | [plain-activerecord.md](references/patterns/plain-activerecord.md) | | Rich Model API | Complex behavior single model should own | [rich-models.md](references/patterns/rich-models.md) | | Concern | Shared behavior across models, or organizing one rich model | [concerns.md](references/patterns/concerns.md) | | Delegated Type | "Is-a" relationships with shared identity | [delegated-type.md](references/patterns/delegated-type.md) | | Service/Form | Only when genuinely justified | [when-to-use-services.md](references/patterns/when-to-use-services.md) |

## Red Flags (Over-Engineering)

Run `/vanilla-rails:analyze` to detect:

- 🔴 Service objects for simple operations - 🔴 Business logic in services instead of models - 🔴 Controllers with more than 10 lines - 🔴 "Managers", "Handlers", "Processors" that are just proxies - ⚠️ Anemic models (attributes + associations only) - ⚠️ Domain logic scattered across service objects - ⚠️ Unnecessary abstraction layers

## Examples

See [examples/](examples/) directory for before/after comparisons showing the Vanilla Rails approach.

## Philosophy

> "Vanilla Rails is plenty." - DHH

Most applications don't need layers beyond what Rails provides. Embrace: - `ActiveRecord` models as the home of business logic - Controllers as thin wrappers around model calls - Callbacks and concerns for code organization - Jobs and mailers called from models when appropriate

Resist: - Service layers as default architecture - Premature extraction - "Clean Architecture" for simple CRUD - Pattern-driven development

For more depth, read the [Vanilla Rails blog post](https://dev.37signals.com/vanilla-rails-is-plenty/).

--- name: vanilla-rails description: > Apply Vanilla Rails (37signals/Basecamp) as the default architecture when writing or changing Rails code: thin controllers, rich models, no service/query/interactor layer unless genuinely justified. Load this skill when creating or editing controllers, models, jobs, concerns, mailers, routes, or form objects; when adding a custom action versus a nested resource; when extracting a service, form, query, or interactor; or when deciding where business logic lives. Also use for Rails reviews and simplification. Do not wait for the user to say "vanilla rails" or "service object". Skip migrations, gem/dependency bumps, CSS/JS/view-only work, credentials, and non-Rails tasks. allowed-tools: - Grep - Glob - Read - Task ---

# Vanilla Rails

Default architecture when writing Rails, from the Vanilla Rails philosophy of 37signals/Basecamp. Apply it while implementing — do not wait for a review command or for the user to name the philosophy.

## Based on Fizzy

This skill is informed by [Fizzy](https://github.com/basecamp/fizzy) - a production Rails application from 37signals.

**Key Fizzy patterns:** - Controllers call Active Record directly: `@board.update!(board_params)`, `@card.comments.create!(comment_params)` - Models composed of concerns: `include Closeable, Golden, Postponable, Watchable` - State tracked with dedicated models: `has_one :closure`, `has_one :goldness` - No `app/services/` directory - Complex multi-step processes use plain objects or ActiveRecord models with state

## Quick Start

Vanilla Rails embraces Rails's built-in patterns and avoids premature abstraction:

**Core Philosophy:** Thin controllers that directly invoke a rich domain model. No service layers or other artifacts unless genuinely justified.

``` ┌─────────────────────────────────────────┐ │ CONTROLLERS │ │ (Thin - HTTP concerns only) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ MODELS │ │ (Rich - Business logic lives here) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ ACTIVE RECORD / DATABASE │ └─────────────────────────────────────────┘ ```

**Core Rule:** Don't add layers beyond what Rails provides unless you have a clear, justified reason.

## Default constraint

This skill is the house style for Rails work, not an optional review lens. When loaded during implementation, apply the principles below while writing code. Do not ask which review command to run.

**Do:** - Put domain logic on the model, or a namespaced concern of that model - Keep controllers to params + one model call - Prefer a new nested resource over a custom controller action - Keep jobs and mailers shallow: `_later` enqueues, `_now` does the work on the model

**Do not introduce** `app/services/`, `app/queries/`, interactors, managers, or handlers unless the bar in [When Services Are Actually OK](#when-services-are-actually-ok) is met — and say so in the change.

**Skip this overlay for** migrations, gem/dependency bumps, CSS/JS, view-only markup, credentials, and anything that is not Rails application code.

## Explicit commands

Use these only when the user asks to review, analyze, or plan a simplification — not as the default response to Rails implementation:

1. **Review code changes** - `/vanilla-rails:review` 2. **Analyze codebase** - `/vanilla-rails:analyze` 3. **Plan simplification** - `/vanilla-rails:simplify [goal]`

## Core Principles

### The Three Rules

1. **Thin Controllers** - Controllers only parse params and invoke model methods 2. **Rich Domain Model** - Business logic belongs in models 3. **No Premature Abstraction** - Don't create service layers by default

### Common Anti-Patterns

| Anti-Pattern | Example | Fix | |--------------|---------|-----| | Fat service | 100-line service with domain logic | Move logic to model | | Anemic model | Model with only attributes and associations | Add business methods | | Controller as orchestrator | Controller calling multiple services | Call rich model methods | | Premature service | Simple CRUD wrapped in service | Use plain Active Record | | Service explosion | DoSomethingService for every action | Most should be model methods |

See [Anti-Patterns Reference](references/anti-patterns.md) for complete list.

### When Services Are Actually OK

Services are justified when: - Coordinating multiple models (orchestration, not domain logic) - External API interactions - Multi-step workflows with transaction boundaries - Operations that don't naturally belong to any single model

**Fizzy uses plain objects for this:**

```ruby # Multi-step signup with ActiveModel::Model class Signup include ActiveModel::Model

validates :email_address, format: { with: URI::MailTo::EMAIL_REGEXP } validates :full_name, presence: true

def create_identity @identity = Identity.find_or_create_by!(email_address: email_address) @identity.send_magic_link(for: :sign_up) end

def complete # Complex account creation with rollback handling end end ```

**Fizzy uses ActiveRecord models for stateful operations:**

```ruby # Stateful import with status tracking class Account::Import < ApplicationRecord enum :status, %w[ pending processing completed failed ].index_by(&:itself), default: :pending

def process(start: nil, callback: nil) processing! # Import logic with ZIP file handling mark_completed rescue => e mark_as_failed raise e end end ```

## Style Preferences

### Conditional Returns

Prefer expanded conditionals over guard clauses (unless returning early at method start for non-trivial bodies).

```ruby # Bad - Guard clause def todos_for_new_group ids = params.require(:todolist)[:todo_ids] return [] unless ids @bucket.recordings.todos.find(ids.split(",")) end

# Good - Expanded conditional def todos_for_new_group if ids = params.require(:todolist)[:todo_ids] @bucket.recordings.todos.find(ids.split(",")) else [] end end ```

### Method Ordering

1. `class` methods 2. `public` methods (with `initialize` at top) 3. `private` methods

Order methods vertically by invocation order to help readers follow code flow.

### CRUD Controllers

Model endpoints as REST operations. Don't add custom actions - introduce new resources instead.

```ruby # Bad resources :cards do post :close post :reopen end

# Good resources :cards do resource :closure end ```

### Visibility Modifiers

No newline under visibility modifiers; indent content under them.

```ruby class SomeClass def some_method # ... end

private def some_private_method # ... end end ```

If a module only has private methods, mark `private` at top with extra newline but don't indent.

### Async Operations

Write shallow job classes that delegate to domain models: - Use `_later` suffix for methods that enqueue jobs - Use `_now` suffix for synchronous methods

```ruby # Fizzy pattern: _later enqueues, _now does the work module Event::Relaying extend ActiveSupport::Concern

included do after_create_commit :relay_later end

def relay_later Event::RelayJob.perform_later(self) end

def relay_now # actual implementation end end

class Event::RelayJob < ApplicationJob def perform(event) event.relay_now end end ```

### Bang Methods

Only use `!` for methods with a counterpart without `!`. Don't use `!` to flag destructive actions.

## Pattern Catalog

| Pattern | Use When | Reference | |---------|----------|-----------| | Plain Active Record | Simple CRUD, no coordination needed | [plain-activerecord.md](references/patterns/plain-activerecord.md) | | Rich Model API | Complex behavior single model should own | [rich-models.md](references/patterns/rich-models.md) | | Concern | Shared behavior across models, or organizing one rich model | [concerns.md](references/patterns/concerns.md) | | Delegated Type | "Is-a" relationships with shared identity | [delegated-type.md](references/patterns/delegated-type.md) | | Service/Form | Only when genuinely justified | [when-to-use-services.md](references/patterns/when-to-use-services.md) |

## Red Flags (Over-Engineering)

Run `/vanilla-rails:analyze` to detect:

- 🔴 Service objects for simple operations - 🔴 Business logic in services instead of models - 🔴 Controllers with more than 10 lines - 🔴 "Managers", "Handlers", "Processors" that are just proxies - ⚠️ Anemic models (attributes + associations only) - ⚠️ Domain logic scattered across service objects - ⚠️ Unnecessary abstraction layers

## Examples

See [examples/](examples/) directory for before/after comparisons showing the Vanilla Rails approach.

## Philosophy

> "Vanilla Rails is plenty." - DHH

Most applications don't need layers beyond what Rails provides. Embrace: - `ActiveRecord` models as the home of business logic - Controllers as thin wrappers around model calls - Callbacks and concerns for code organization - Jobs and mailers called from models when appropriate

Resist: - Service layers as default architecture - Premature extraction - "Clean Architecture" for simple CRUD - Pattern-driven development

For more depth, read the [Vanilla Rails blog post](https://dev.37signals.com/vanilla-rails-is-plenty/).

--- name: vanilla-rails description: > Apply Vanilla Rails (37signals/Basecamp) as the default architecture when writing or changing Rails code: thin controllers, rich models, no service/query/interactor layer unless genuinely justified. Load this skill when creating or editing controllers, models, jobs, concerns, mailers, routes, or form objects; when adding a custom action versus a nested resource; when extracting a service, form, query, or interactor; or when deciding where business logic lives. Also use for Rails reviews and simplification. Do not wait for the user to say "vanilla rails" or "service object". Skip migrations, gem/dependency bumps, CSS/JS/view-only work, credentials, and non-Rails tasks. allowed-tools: - Grep - Glob - Read - Task ---

# Vanilla Rails

Default architecture when writing Rails, from the Vanilla Rails philosophy of 37signals/Basecamp. Apply it while implementing — do not wait for a review command or for the user to name the philosophy.

## Based on Fizzy

This skill is informed by [Fizzy](https://github.com/basecamp/fizzy) - a production Rails application from 37signals.

**Key Fizzy patterns:** - Controllers call Active Record directly: `@board.update!(board_params)`, `@card.comments.create!(comment_params)` - Models composed of concerns: `include Closeable, Golden, Postponable, Watchable` - State tracked with dedicated models: `has_one :closure`, `has_one :goldness` - No `app/services/` directory - Complex multi-step processes use plain objects or ActiveRecord models with state

## Quick Start

Vanilla Rails embraces Rails's built-in patterns and avoids premature abstraction:

**Core Philosophy:** Thin controllers that directly invoke a rich domain model. No service layers or other artifacts unless genuinely justified.

``` ┌─────────────────────────────────────────┐ │ CONTROLLERS │ │ (Thin - HTTP concerns only) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ MODELS │ │ (Rich - Business logic lives here) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ ACTIVE RECORD / DATABASE │ └─────────────────────────────────────────┘ ```

**Core Rule:** Don't add layers beyond what Rails provides unless you have a clear, justified reason.

## Default constraint

This skill is the house style for Rails work, not an optional review lens. When loaded during implementation, apply the principles below while writing code. Do not ask which review command to run.

**Do:** - Put domain logic on the model, or a namespaced concern of that model - Keep controllers to params + one model call - Prefer a new nested resource over a custom controller action - Keep jobs and mailers shallow: `_later` enqueues, `_now` does the work on the model

**Do not introduce** `app/services/`, `app/queries/`, interactors, managers, or handlers unless the bar in [When Services Are Actually OK](#when-services-are-actually-ok) is met — and say so in the change.

**Skip this overlay for** migrations, gem/dependency bumps, CSS/JS, view-only markup, credentials, and anything that is not Rails application code.

## Explicit commands

Use these only when the user asks to review, analyze, or plan a simplification — not as the default response to Rails implementation:

1. **Review code changes** - `/vanilla-rails:review` 2. **Analyze codebase** - `/vanilla-rails:analyze` 3. **Plan simplification** - `/vanilla-rails:simplify [goal]`

## Core Principles

### The Three Rules

1. **Thin Controllers** - Controllers only parse params and invoke model methods 2. **Rich Domain Model** - Business logic belongs in models 3. **No Premature Abstraction** - Don't create service layers by default

### Common Anti-Patterns

| Anti-Pattern | Example | Fix | |--------------|---------|-----| | Fat service | 100-line service with domain logic | Move logic to model | | Anemic model | Model with only attributes and associations | Add business methods | | Controller as orchestrator | Controller calling multiple services | Call rich model methods | | Premature service | Simple CRUD wrapped in service | Use plain Active Record | | Service explosion | DoSomethingService for every action | Most should be model methods |

See [Anti-Patterns Reference](references/anti-patterns.md) for complete list.

### When Services Are Actually OK

Services are justified when: - Coordinating multiple models (orchestration, not domain logic) - External API interactions - Multi-step workflows with transaction boundaries - Operations that don't naturally belong to any single model

**Fizzy uses plain objects for this:**

```ruby # Multi-step signup with ActiveModel::Model class Signup include ActiveModel::Model

validates :email_address, format: { with: URI::MailTo::EMAIL_REGEXP } validates :full_name, presence: true

def create_identity @identity = Identity.find_or_create_by!(email_address: email_address) @identity.send_magic_link(for: :sign_up) end

def complete # Complex account creation with rollback handling end end ```

**Fizzy uses ActiveRecord models for stateful operations:**

```ruby # Stateful import with status tracking class Account::Import < ApplicationRecord enum :status, %w[ pending processing completed failed ].index_by(&:itself), default: :pending

def process(start: nil, callback: nil) processing! # Import logic with ZIP file handling mark_completed rescue => e mark_as_failed raise e end end ```

## Style Preferences

### Conditional Returns

Prefer expanded conditionals over guard clauses (unless returning early at method start for non-trivial bodies).

```ruby # Bad - Guard clause def todos_for_new_group ids = params.require(:todolist)[:todo_ids] return [] unless ids @bucket.recordings.todos.find(ids.split(",")) end

# Good - Expanded conditional def todos_for_new_group if ids = params.require(:todolist)[:todo_ids] @bucket.recordings.todos.find(ids.split(",")) else [] end end ```

### Method Ordering

1. `class` methods 2. `public` methods (with `initialize` at top) 3. `private` methods

Order methods vertically by invocation order to help readers follow code flow.

### CRUD Controllers

Model endpoints as REST operations. Don't add custom actions - introduce new resources instead.

```ruby # Bad resources :cards do post :close post :reopen end

# Good resources :cards do resource :closure end ```

### Visibility Modifiers

No newline under visibility modifiers; indent content under them.

```ruby class SomeClass def some_method # ... end

private def some_private_method # ... end end ```

If a module only has private methods, mark `private` at top with extra newline but don't indent.

### Async Operations

Write shallow job classes that delegate to domain models: - Use `_later` suffix for methods that enqueue jobs - Use `_now` suffix for synchronous methods

```ruby # Fizzy pattern: _later enqueues, _now does the work module Event::Relaying extend ActiveSupport::Concern

included do after_create_commit :relay_later end

def relay_later Event::RelayJob.perform_later(self) end

def relay_now # actual implementation end end

class Event::RelayJob < ApplicationJob def perform(event) event.relay_now end end ```

### Bang Methods

Only use `!` for methods with a counterpart without `!`. Don't use `!` to flag destructive actions.

## Pattern Catalog

| Pattern | Use When | Reference | |---------|----------|-----------| | Plain Active Record | Simple CRUD, no coordination needed | [plain-activerecord.md](references/patterns/plain-activerecord.md) | | Rich Model API | Complex behavior single model should own | [rich-models.md](references/patterns/rich-models.md) | | Concern | Shared behavior across models, or organizing one rich model | [concerns.md](references/patterns/concerns.md) | | Delegated Type | "Is-a" relationships with shared identity | [delegated-type.md](references/patterns/delegated-type.md) | | Service/Form | Only when genuinely justified | [when-to-use-services.md](references/patterns/when-to-use-services.md) |

## Red Flags (Over-Engineering)

Run `/vanilla-rails:analyze` to detect:

- 🔴 Service objects for simple operations - 🔴 Business logic in services instead of models - 🔴 Controllers with more than 10 lines - 🔴 "Managers", "Handlers", "Processors" that are just proxies - ⚠️ Anemic models (attributes + associations only) - ⚠️ Domain logic scattered across service objects - ⚠️ Unnecessary abstraction layers

## Examples

See [examples/](examples/) directory for before/after comparisons showing the Vanilla Rails approach.

## Philosophy

> "Vanilla Rails is plenty." - DHH

Most applications don't need layers beyond what Rails provides. Embrace: - `ActiveRecord` models as the home of business logic - Controllers as thin wrappers around model calls - Callbacks and concerns for code organization - Jobs and mailers called from models when appropriate

Resist: - Service layers as default architecture - Premature extraction - "Clean Architecture" for simple CRUD - Pattern-driven development

For more depth, read the [Vanilla Rails blog post](https://dev.37signals.com/vanilla-rails-is-plenty/).

--- name: vanilla-rails description: > Apply Vanilla Rails (37signals/Basecamp) as the default architecture when writing or changing Rails code: thin controllers, rich models, no service/query/interactor layer unless genuinely justified. Load this skill when creating or editing controllers, models, jobs, concerns, mailers, routes, or form objects; when adding a custom action versus a nested resource; when extracting a service, form, query, or interactor; or when deciding where business logic lives. Also use for Rails reviews and simplification. Do not wait for the user to say "vanilla rails" or "service object". Skip migrations, gem/dependency bumps, CSS/JS/view-only work, credentials, and non-Rails tasks. allowed-tools: - Grep - Glob - Read - Task ---

# Vanilla Rails

Default architecture when writing Rails, from the Vanilla Rails philosophy of 37signals/Basecamp. Apply it while implementing — do not wait for a review command or for the user to name the philosophy.

## Based on Fizzy

This skill is informed by [Fizzy](https://github.com/basecamp/fizzy) - a production Rails application from 37signals.

**Key Fizzy patterns:** - Controllers call Active Record directly: `@board.update!(board_params)`, `@card.comments.create!(comment_params)` - Models composed of concerns: `include Closeable, Golden, Postponable, Watchable` - State tracked with dedicated models: `has_one :closure`, `has_one :goldness` - No `app/services/` directory - Complex multi-step processes use plain objects or ActiveRecord models with state

## Quick Start

Vanilla Rails embraces Rails's built-in patterns and avoids premature abstraction:

**Core Philosophy:** Thin controllers that directly invoke a rich domain model. No service layers or other artifacts unless genuinely justified.

``` ┌─────────────────────────────────────────┐ │ CONTROLLERS │ │ (Thin - HTTP concerns only) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ MODELS │ │ (Rich - Business logic lives here) │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ ACTIVE RECORD / DATABASE │ └─────────────────────────────────────────┘ ```

**Core Rule:** Don't add layers beyond what Rails provides unless you have a clear, justified reason.

## Default constraint

This skill is the house style for Rails work, not an optional review lens. When loaded during implementation, apply the principles below while writing code. Do not ask which review command to run.

**Do:** - Put domain logic on the model, or a namespaced concern of that model - Keep controllers to params + one model call - Prefer a new nested resource over a custom controller action - Keep jobs and mailers shallow: `_later` enqueues, `_now` does the work on the model

**Do not introduce** `app/services/`, `app/queries/`, interactors, managers, or handlers unless the bar in [When Services Are Actually OK](#when-services-are-actually-ok) is met — and say so in the change.

**Skip this overlay for** migrations, gem/dependency bumps, CSS/JS, view-only markup, credentials, and anything that is not Rails application code.

## Explicit commands

Use these only when the user asks to review, analyze, or plan a simplification — not as the default response to Rails implementation:

1. **Review code changes** - `/vanilla-rails:review` 2. **Analyze codebase** - `/vanilla-rails:analyze` 3. **Plan simplification** - `/vanilla-rails:simplify [goal]`

## Core Principles

### The Three Rules

1. **Thin Controllers** - Controllers only parse params and invoke model methods 2. **Rich Domain Model** - Business logic belongs in models 3. **No Premature Abstraction** - Don't create service layers by default

### Common Anti-Patterns

| Anti-Pattern | Example | Fix | |--------------|---------|-----| | Fat service | 100-line service with domain logic | Move logic to model | | Anemic model | Model with only attributes and associations | Add business methods | | Controller as orchestrator | Controller calling multiple services | Call rich model methods | | Premature service | Simple CRUD wrapped in service | Use plain Active Record | | Service explosion | DoSomethingService for every action | Most should be model methods |

See [Anti-Patterns Reference](references/anti-patterns.md) for complete list.

### When Services Are Actually OK

Services are justified when: - Coordinating multiple models (orchestration, not domain logic) - External API interactions - Multi-step workflows with transaction boundaries - Operations that don't naturally belong to any single model

**Fizzy uses plain objects for this:**

```ruby # Multi-step signup with ActiveModel::Model class Signup include ActiveModel::Model

validates :email_address, format: { with: URI::MailTo::EMAIL_REGEXP } validates :full_name, presence: true

def create_identity @identity = Identity.find_or_create_by!(email_address: email_address) @identity.send_magic_link(for: :sign_up) end

def complete # Complex account creation with rollback handling end end ```

**Fizzy uses ActiveRecord models for stateful operations:**

```ruby # Stateful import with status tracking class Account::Import < ApplicationRecord enum :status, %w[ pending processing completed failed ].index_by(&:itself), default: :pending

def process(start: nil, callback: nil) processing! # Import logic with ZIP file handling mark_completed rescue => e mark_as_failed raise e end end ```

## Style Preferences

### Conditional Returns

Prefer expanded conditionals over guard clauses (unless returning early at method start for non-trivial bodies).

```ruby # Bad - Guard clause def todos_for_new_group ids = params.require(:todolist)[:todo_ids] return [] unless ids @bucket.recordings.todos.find(ids.split(",")) end

# Good - Expanded conditional def todos_for_new_group if ids = params.require(:todolist)[:todo_ids] @bucket.recordings.todos.find(ids.split(",")) else [] end end ```

### Method Ordering

1. `class` methods 2. `public` methods (with `initialize` at top) 3. `private` methods

Order methods vertically by invocation order to help readers follow code flow.

### CRUD Controllers

Model endpoints as REST operations. Don't add custom actions - introduce new resources instead.

```ruby # Bad resources :cards do post :close post :reopen end

# Good resources :cards do resource :closure end ```

### Visibility Modifiers

No newline under visibility modifiers; indent content under them.

```ruby class SomeClass def some_method # ... end

private def some_private_method # ... end end ```

If a module only has private methods, mark `private` at top with extra newline but don't indent.

### Async Operations

Write shallow job classes that delegate to domain models: - Use `_later` suffix for methods that enqueue jobs - Use `_now` suffix for synchronous methods

```ruby # Fizzy pattern: _later enqueues, _now does the work module Event::Relaying extend ActiveSupport::Concern

included do after_create_commit :relay_later end

def relay_later Event::RelayJob.perform_later(self) end

def relay_now # actual implementation end end

class Event::RelayJob < ApplicationJob def perform(event) event.relay_now end end ```

### Bang Methods

Only use `!` for methods with a counterpart without `!`. Don't use `!` to flag destructive actions.

## Pattern Catalog

| Pattern | Use When | Reference | |---------|----------|-----------| | Plain Active Record | Simple CRUD, no coordination needed | [plain-activerecord.md](references/patterns/plain-activerecord.md) | | Rich Model API | Complex behavior single model should own | [rich-models.md](references/patterns/rich-models.md) | | Concern | Shared behavior across models, or organizing one rich model | [concerns.md](references/patterns/concerns.md) | | Delegated Type | "Is-a" relationships with shared identity | [delegated-type.md](references/patterns/delegated-type.md) | | Service/Form | Only when genuinely justified | [when-to-use-services.md](references/patterns/when-to-use-services.md) |

## Red Flags (Over-Engineering)

Run `/vanilla-rails:analyze` to detect:

- 🔴 Service objects for simple operations - 🔴 Business logic in services instead of models - 🔴 Controllers with more than 10 lines - 🔴 "Managers", "Handlers", "Processors" that are just proxies - ⚠️ Anemic models (attributes + associations only) - ⚠️ Domain logic scattered across service objects - ⚠️ Unnecessary abstraction layers

## Examples

See [examples/](examples/) directory for before/after comparisons showing the Vanilla Rails approach.

## Philosophy

> "Vanilla Rails is plenty." - DHH

Most applications don't need layers beyond what Rails provides. Embrace: - `ActiveRecord` models as the home of business logic - Controllers as thin wrappers around model calls - Callbacks and concerns for code organization - Jobs and mailers called from models when appropriate

Resist: - Service layers as default architecture - Premature extraction - "Clean Architecture" for simple CRUD - Pattern-driven development

For more depth, read the [Vanilla Rails blog post](https://dev.37signals.com/vanilla-rails-is-plenty/).