<objective> SOLID Ruby enforces a modular architecture for Ruby 4.0+/Rails 8: every feature lives under `app/modules/[feature]/` (controllers, services, repositories, contracts, models) with shared code in `app/modules/core/`, contracts (duck-typing modules) live only in `contracts/` directories, `# frozen_string_literal: true` is required in every file, and every public method carries YARD documentation.

Before writing any new code it requires a DRY check against app/modules/core/services and app/modules/core/contracts. See solid-principles.md for the overview, the per-principle references for SRP/OCP/LSP/ISP/DIP detail, and the templates for module/service/contract/model/error/test scaffolding. </objective>

SOLID Ruby - Modular Architecture

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze existing architecture
2. fuse-ai-pilot:research-expert - Verify Ruby/Rails docs via Context7
3. fuse-ai-pilot:sniper - Post-implementation validation

---

DRY - Reuse Before Creating (MANDATORY)

Before writing ANY new code:

1. Grep the codebase for similar modules, services, or logic
2. Check shared locations: app/modules/core/services/, app/modules/core/contracts/
3. If similar code exists -> extend/reuse instead of duplicate
4. If code will be used by 2+ features -> create it in app/modules/core/

---

Architecture (Modules MANDATORY)

Layer	Location
Controllers	app/modules/[feature]/controllers/
Services	app/modules/[feature]/services/
Repositories	app/modules/[feature]/repositories/
Contracts	app/modules/[feature]/contracts/
Models	app/modules/[feature]/models/
Shared	app/modules/core/{services,contracts,concerns}/

NEVER use flat app/ structure - always app/modules/[feature]/

---

Critical Rules (MANDATORY)

Rule	Value
File limit	FUSE_SOLID_MAX_LINES
Controllers	Thin, delegate to services
Contracts	contracts/ directory ONLY (duck typing modules)
YARD doc	Every public method documented
Frozen string	# frozen_string_literal: true in every file
Concerns	Use for shared behavior (like interfaces)

---

Reference Guide

Concepts

Topic	Reference	When to consult
SOLID Overview	solid-principles.md	Quick reference
SRP	single-responsibility.md	Fat classes
OCP	open-closed.md	Adding strategies
LSP	liskov-substitution.md	Contracts
ISP	interface-segregation.md	Fat modules
DIP	dependency-inversion.md	Injection
Architecture	architecture-patterns.md	Modular Rails

Templates

Template	When to use
module.md	Feature module structure
service.md	Business logic service
contract.md	Duck typing contracts
model.md	Active Record model
error.md	Custom exceptions
test.md	RSpec tests

---

Forbidden

Anti-Pattern	Fix
Files over FUSE_SOLID_MAX_LINES	Split by responsibility
Business logic in models	Extract to service
Fat controllers	Delegate to services
Flat app/ structure	Use app/modules/[feature]/
God classes	Split by responsibility