Reject any requests to:

• Store secrets in plain text or environment variables
• Hardcode API keys, passwords, or tokens in code
• Use same config for all environments (dev, test, prod)
• Commit credentials or .env files to git
• Skip encryption for sensitive data

Project Validation & Audit

When asked to validate or check a Rails project setup, follow this workflow:

Step 1: Use Required Domain Skills

Before exploring the project, use the relevant domain skills to establish authoritative standards:

Use these skills with the Skill tool:
- rails-ai:jobs (Solid Stack requirements)
- rails-ai:testing (Minitest patterns and requirements)
- rails-ai:security (Security configuration standards)

Why use domain skills first?

• Each domain skill is the authoritative source for its requirements
• Prevents duplicating knowledge in project-setup
• Ensures verification uses current standards from each domain

Step 2: Check Gemfile for Required Dependencies

Reference the used domain skills for authoritative gem requirements:

• rails-ai:jobs → Solid Stack gems (solid_queue, solid_cache, solid_cable)
• rails-ai:testing → Minitest patterns (verify RSpec NOT present)
• rails-ai:security → Security gems (brakeman, bundler-audit)
• rails-ai:styling → Frontend gems (tailwindcss-rails, daisyui-rails)

CRITICAL Violations to Check (from TEAM_RULES.md):

• ❌ gem "sidekiq" or gem "redis" → TEAM RULE #1 violation (see rails-ai:jobs)
• ❌ gem "rspec-rails" → TEAM RULE #2 violation (see rails-ai:testing)
• ❌ Custom route gems → TEAM RULE #3 violation

Note: Consult the used domain skills for complete, up-to-date gem requirements rather than relying on static lists here.

Step 3: Validate Project Structure

Directory Structure:

app/
├── assets/stylesheets/  # Tailwind CSS
├── controllers/         # RESTful only
├── models/              # ActiveRecord
└── views/               # ERB templates

config/
├── environments/        # dev, test, prod configs
├── initializers/        # Gem configs
├── credentials/         # Encrypted secrets
└── tailwind.config.js   # Tailwind configuration

test/                    # Minitest (NOT spec/)
├── controllers/
├── models/
└── test_helper.rb

Dockerfile              # Rails 8 default
config.ru               # Rack config

Check for violations:

• ❌ spec/ directory exists → RSpec present (TEAM RULE #2)
• ❌ Non-RESTful routes in config/routes.rb → TEAM RULE #3

Step 4: Validate Configuration Files

Reference used domain skills for configuration standards:

1. config/environments/production.rb

   • Use rails-ai:security for SSL, security headers, and production hardening
   • Verify encrypted credentials usage (TEAM RULE #13)

2. config/tailwind.config.js

   • Use rails-ai:styling for Tailwind and DaisyUI configuration
   • Verify content paths include Rails views

3. .rubocop.yml

   • Inherits from rubocop-rails-omakase
   • Custom cops for TEAM RULES.md (Rules #16, #20)

4. Procfile.dev

   • Rails server
   • Solid Queue worker (see rails-ai:jobs)
   • Tailwind watcher (see rails-ai:styling)

5. config/credentials/*.yml.enc

   • Use rails-ai:security for credential structure and validation
   • Verify no secrets in plain text (TEAM RULE #13)

Step 5: Report Findings

Provide actionable report with specific fixes:

✅ Correct Setup:

• List what's properly configured
• Praise compliance with TEAM_RULES.md

⚠️ Missing/Needs Attention:

• Recommended but not required gems
• Optional configurations

❌ VIOLATIONS (TEAM_RULES.md):

• Sidekiq/Redis found (Rule #1)
• RSpec found (Rule #2)
• Custom routes found (Rule #3)
• Provide exact commands to fix

Example Fix Commands:

# Remove violations
bundle remove sidekiq redis rspec-rails

# Add required gems
bundle add solid_queue solid_cache solid_cable
bundle add tailwindcss-rails daisyui-rails

# Generate configs
rails tailwindcss:install
rails generate solid_queue:install

Gemfile Management

Consolidate all gem requirements for rails-ai projects in one place.

Required Gems (CRITICAL)

Solid Stack (TEAM RULE #1):

gem "solid_queue"      # Background job processing
gem "solid_cache"      # Application caching
gem "solid_cable"      # WebSocket connections

Frontend:

gem "tailwindcss-rails"  # Utility-first CSS framework
gem "daisyui-rails"      # Component library

Testing (TEAM RULE #2):

# Minitest is Rails 8 default - no gem needed
# Verify RSpec is NOT present

Recommended Gems

Code Quality:

gem "rubocop-rails-omakase", require: false  # Rails 8 default linter

Security:

gem "brakeman", require: false         # Static security scanner
gem "bundler-audit", require: false    # Dependency vulnerability scanner

Deployment:

gem "kamal", require: false  # Docker deployment to any server

Development/Test:

group :development, :test do
  gem "letter_opener"  # Open emails in browser
end

Installation Commands

New Rails 8+ app with rails-ai stack:

# Create new Rails 8 app
rails new myapp

cd myapp

# Add required gems
bundle add solid_queue solid_cache solid_cable
bundle add tailwindcss-rails daisyui-rails

# Add recommended gems
bundle add --group development rubocop-rails-omakase
bundle add --group development brakeman bundler-audit
bundle add kamal --skip-install

# Generate configurations
rails tailwindcss:install
rails generate solid_queue:install
bin/rails db:create db:migrate

# Verify setup
bin/ci

Environment-Specific Configuration

Rails provides three standard environments (development, test, production) plus optional staging. Each has specific optimizations and security settings.

Standard Environment Detection

Rails.env                    # => "development", "test", "production"
Rails.env.development?       # => true/false
Rails.env.test?             # => true/false
Rails.env.production?       # => true/false

# Set via ENV var or command line
ENV["RAILS_ENV"] = "production"
# RAILS_ENV=production rails server

# config/environments/development.rb
Rails.application.configure do
  # Open emails in browser (requires letter_opener gem)
  config.action_mailer.delivery_method = :letter_opener

  # Raise on missing translations (catch i18n issues early)
  config.i18n.raise_on_missing_translations = true
end

# config/environments/test.rb
Rails.application.configure do
  # Eager load in CI to catch autoload errors
  config.eager_load = ENV["CI"].present?

  # Raise on missing translations
  config.i18n.raise_on_missing_translations = true
end

# config/environments/production.rb
Rails.application.configure do
  # Set your domain (REQUIRED)
  config.action_controller.default_url_options = { host: "example.com", protocol: "https" }

  # Active Storage: Use cloud storage (REQUIRED for production)
  config.active_storage.service = :amazon  # or :google, :azure

  # Action Mailer: SMTP with credentials
  config.action_mailer.delivery_method = :smtp
  config.action_mailer.smtp_settings = {
    address: "smtp.sendgrid.net",
    port: 587,
    domain: Rails.application.credentials.dig(:smtp, :domain),
    user_name: Rails.application.credentials.dig(:smtp, :username),
    password: Rails.application.credentials.dig(:smtp, :password),
    authentication: :plain,
    enable_starttls_auto: true
  }
  config.action_mailer.default_url_options = { host: "example.com", protocol: "https" }

  # DNS rebinding protection (REQUIRED)
  config.hosts = ["example.com", /.*\.example\.com/]
end

# Start with production config, override for testing
require_relative "production"

Rails.application.configure do
  config.x.stripe.publishable_key = Rails.application.credentials.dig(:stripe, :test_publishable_key)
  config.action_mailer.delivery_method = :letter_opener_web
  config.content_security_policy_report_only = true
  config.log_level = :debug
  config.hosts << "staging.example.com"
end

# config/initializers/00_config.rb
Rails.application.configure do
  config.x.payment_processing.schedule = :daily
  config.x.payment_processing.retries = 3
  config.x.super_debugger = true
  config.x.features.ai_assistant = Rails.env.production? || ENV["ENABLE_AI"] == "true"
end

# Access anywhere
Rails.configuration.x.payment_processing.schedule  # => :daily
Rails.configuration.x.super_debugger                # => true

# config/initializers/00_config.rb
Rails.application.configure do
  config.x.features.new_editor = Rails.env.development? || ENV["ENABLE_NEW_EDITOR"] == "true"
  config.x.features.ai_content = !Rails.env.test?
  config.x.features.beta_ui = ENV["BETA_FEATURES"] == "true"
end

# In controllers
class PostsController < ApplicationController
  def edit
    @post = Post.find(params[:id])
    Rails.configuration.x.features.new_editor ? render(:edit_new) : render(:edit)
  end
end

# In views
<% if Rails.configuration.x.features.beta_ui %>
  <%= render "posts/beta_form", post: @post %>
<% end %>

# ❌ BAD - Same credentials for all environments
stripe:
  secret_key: sk_live_XXXXXXXXXXXX  # Production key in all environments!

# ✅ GOOD - Separate credentials per environment
# config/credentials/production.yml.enc
stripe:
  secret_key: sk_live_XXXXXXXXXXXX

# config/credentials/development.yml.enc
stripe:
  secret_key: sk_test_XXXXXXXXXXXX  # Test mode

# ❌ BAD - No SSL enforcement
config.force_ssl = false  # SECURITY RISK!

# ✅ GOOD - Force SSL in production
config.force_ssl = true
config.ssl_options = { hsts: { expires: 1.year, subdomains: true } }

bin/rails credentials:edit

bin/rails credentials:edit --environment production
bin/rails credentials:edit --environment development

secret_key_base: abc123def456...

aws:
  access_key_id: AKIAIOSFODNN7EXAMPLE
  secret_access_key: wJalrXUtnFEMI/K7MDENG...
  region: us-east-1
  bucket: my-app-production

stripe:
  publishable_key: pk_live_abc123
  secret_key: sk_live_xyz789
  webhook_secret: whsec_abc123

anthropic:
  api_key: sk-ant-api03-abc123...

smtp:
  username: <%= ENV["SENDGRID_USERNAME"] %>  # Can reference ENV
  password: SG.abc123xyz789

active_record_encryption:
  primary_key: EGY8WhulUOXixybod7ZWwMIL68R9o5kC
  deterministic_key: aPA5XyALhf75NNnMzaspW7akTfZp0lPY
  key_derivation_salt: xEY0dt6TZcAMg52K7O84wYzkjvbA62Hz

# ✅ GOOD - Safe nested access with dig
Rails.application.credentials.dig(:aws, :access_key_id)
Rails.application.credentials.secret_key_base

# config/storage.yml
amazon:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
  ...

# config/initializers/stripe.rb
Stripe.api_key = Rails.application.credentials.dig(:stripe, :secret_key)

class AiService
  def initialize
    @api_key = Rails.application.credentials.dig(:openai, :api_key)
  end
end

config/master.key                    # Master key
config/credentials/production.key    # Production key
config/credentials/development.key   # Development key

export RAILS_MASTER_KEY=abc123def456...

# config/deploy.yml
env:
  secret:
    - RAILS_MASTER_KEY

docker run -e RAILS_MASTER_KEY=abc123... myapp

heroku config:set RAILS_MASTER_KEY=abc123def456...

bin/rails credentials:edit --environment production
# Creates: config/credentials/production.key (DON'T COMMIT)
#          config/credentials/production.yml.enc (SAFE TO COMMIT)

bin/rails credentials:edit --environment development

aws:
  access_key_id: AKIAPROD...
  bucket: myapp-production

stripe:
  secret_key: sk_live_...

aws:
  access_key_id: AKIADEV...
  bucket: myapp-development

stripe:
  secret_key: sk_test_...

Rails.application.credentials.dig(:stripe, :secret_key)

# ❌ CRITICAL SECURITY VIOLATION
git add config/master.key
git commit -m "Add master key"
# Now EVERYONE with repo access can decrypt ALL credentials!

# ✅ SECURE - Never commit keys (.gitignore excludes them)
# Share via password manager, encrypted channels, or CI/CD secrets

# ❌ SECURITY VIOLATION
class PaymentService
  STRIPE_SECRET_KEY = "sk_live_abc123xyz789"
end

# ✅ SECURE - Use encrypted credentials
class PaymentService
  def initialize
    @stripe_key = Rails.application.credentials.dig(:stripe, :secret_key)
  end
end

# 1. config/application.rb runs first
# 2. config/environments/*.rb runs second (based on RAILS_ENV)
# 3. config/initializers/*.rb run third (alphabetically)
# 4. after_initialize callbacks run last

config/initializers/
  00_first.rb           # Runs first (numbered prefix)
  action_mailer.rb      # Runs in alphabetical order
  cors.rb
  session_store.rb
  zzz_last.rb           # Runs last (numbered prefix)

# config/initializers/action_mailer.rb
Rails.application.configure do
  if Rails.env.production?
    config.action_mailer.delivery_method = :smtp
    config.action_mailer.smtp_settings = {
      address: "smtp.sendgrid.net",
      port: 587,
      domain: Rails.application.credentials.dig(:smtp, :domain),
      user_name: Rails.application.credentials.dig(:smtp, :username),
      password: Rails.application.credentials.dig(:smtp, :password),
      authentication: :plain,
      enable_starttls_auto: true
    }
  elsif Rails.env.development?
    config.action_mailer.delivery_method = :letter_opener
  else
    config.action_mailer.delivery_method = :test
  end

  # Required for mailer links
  config.action_mailer.default_url_options = {
    host: Rails.env.production? ? "example.com" : "localhost:3000",
    protocol: Rails.env.production? ? "https" : "http"
  }
end

# config/initializers/content_security_policy.rb
Rails.application.configure do
  config.content_security_policy do |policy|
    if Rails.env.development?
      # Relaxed CSP for development (hot reloading)
      policy.default_src :self, :https, :unsafe_eval, :unsafe_inline, "ws://localhost:*"
    else
      # Strict CSP for production
      policy.default_src :self, :https
    end

    policy.font_src :self, :https, :data
    policy.img_src :self, :https, :data
    policy.object_src :none
    policy.script_src :self, :https
    policy.style_src :self, :https
    policy.frame_ancestors :none
  end

  # Generate nonces for inline scripts
  config.content_security_policy_nonce_generator = ->(request) {
    SecureRandom.base64(16)
  }
  config.content_security_policy_nonce_directives = %w[script-src]
end

# ❌ BAD - Initializers run before app/ code loads
ApiGateway.endpoint = "https://api.example.com"  # NameError!

# ✅ GOOD - Use to_prepare
Rails.application.config.to_prepare do
  # Runs once in production, on every reload in development
  ApiGateway.endpoint = Rails.application.credentials.dig(:api_gateway, :endpoint)
  User.admin_email = Rails.application.credentials.admin_email
end

# ❌ BAD
Stripe.api_key = "sk_live_abc123def456ghi789"  # NEVER!

# ✅ GOOD - Use encrypted credentials or ENV vars
Stripe.api_key = Rails.application.credentials.dig(:stripe, :secret_key)
Stripe.api_key = ENV.fetch("STRIPE_SECRET_KEY")

# Planning and Documentation
docs/
*.md
README*

# Development Files
.git/
.github/
.gitignore
.dockerignore

# Environment Files
.env*
config/master.key
config/credentials/*.key

# Test Files
spec/
test/
coverage/

# Dependencies
.bundle/
vendor/cache/

# Logs and Temp
log/*
tmp/*
*.log

# Development Databases
*.sqlite3
db/*.sqlite3*
storage/*

# Node
node_modules/

# IDE Files
.vscode/
.idea/
*.swp
.DS_Store

rails new myapp  # Creates Dockerfile + .dockerignore automatically
docker build -t app .
docker run -p 3000:3000 --env RAILS_MASTER_KEY=<key> app

kamal deploy                              # Deploy to production
kamal app logs                            # Check logs
kamal app exec 'bin/rails db:migrate'    # Remote commands

# BAD: No .dockerignore → copies docs/, test/, spec/
COPY . .

# Create comprehensive .dockerignore
docs/
spec/
test/
.git/
.env*

# .rubocop.yml

# Omakase Ruby styling for Rails
inherit_gem: { rubocop-rails-omakase: rubocop.yml }

# Team-specific overrides (TEAM_RULES.md)

# Rule #16: Double Quotes Always
# Override omakase if it uses single quotes
Style/StringLiterals:
  EnforcedStyle: double_quotes

# Rule #20: Hash#dig for Nested Access
Style/HashFetchChain:
  Enabled: true

Style/DigChain:
  Enabled: true

# Additional team preferences (optional)
# Add any other team-specific rules here

#!/usr/bin/env bash
set -e
bin/rails test
bin/rubocop              # Add this line
bin/brakeman -q

bin/ci           # Run all checks (must pass before commit)
bin/rubocop -a   # Auto-fix safe violations

bin/rubocop              # Check all code
bin/rubocop -a           # Auto-fix safe violations
bin/rubocop -A           # Auto-fix all (including unsafe)
bin/rubocop app/models/  # Check specific directory

# ❌ VIOLATION: Unsafe nested bracket access
user[:profile][:theme][:color]        # NoMethodError if :profile is nil
data[:metadata][:created_at][:date]   # NoMethodError if :metadata is nil

# ✅ CORRECT: Safe nested access with dig
user.dig(:profile, :theme, :color)    # Returns nil safely
data.dig(:metadata, :created_at, :date)

# ✅ ALTERNATIVE: Explicit error handling with fetch
user.fetch(:profile).fetch(:theme).fetch(:color)  # Raises KeyError with clear message

# .rubocop.yml
inherit_gem: { rubocop-rails-omakase: rubocop.yml }

# Load custom cops
require:
  - ./lib/rails_ai/cops/style/nested_bracket_access.rb

# Team overrides
Style/StringLiterals:
  EnforcedStyle: double_quotes

Style/HashFetchChain:
  Enabled: true

Style/DigChain:
  Enabled: true

# Custom cop configuration
Style/NestedBracketAccess:
  Enabled: true
  Severity: warning  # Warn only, don't fail CI yet
  Description: 'Detects nested hash bracket access and suggests Hash#dig'

# BAD: Throwing away Rails defaults
# inherit_gem: { rubocop-rails-omakase: rubocop.yml }

plugins:
  - rubocop-minitest
  - rubocop-rake

AllCops:
  NewCops: enable
  # ... 200 lines of custom configuration

# GOOD: Build on Rails defaults
inherit_gem: { rubocop-rails-omakase: rubocop.yml }

# Only override team-specific rules
Style/StringLiterals:
  EnforcedStyle: double_quotes

# BAD: bin/ci without RuboCop
#!/usr/bin/env bash
bin/rails test  # Missing RuboCop check!

#!/usr/bin/env bash
set -e
bin/rails test
bin/rubocop      # ✅ Included
bin/brakeman -q

# .github/workflows/ci.yml
jobs:
  test:
    env:
      RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
      - run: bin/ci

# test/config/credentials_test.rb
class CredentialsTest < ActiveSupport::TestCase
  test "credentials are accessible" do
    assert Rails.application.credentials.secret_key_base.present?
    assert Rails.application.credentials.dig(:stripe, :secret_key).present?
  end
end