Create Engine

Use this skill when the task is to create, scaffold, or refactor a Rails engine.

A good engine has a narrow purpose, a clear host-app integration story, and a small public API. Keep this skill focused on structure and design. Use adjacent skills for installer details, deep test coverage, release workflow, or documentation work.

Quick Reference

HARD-GATE

Before engine work is complete, confirm all of the following:

STRUCTURE & CONTRACT:
1. Root file requires only version, configuration, and engine.
2. Public engines use isolate_namespace; configuration exposes .configure block.
3. Host model references are configurable strings (e.g., "User"), never hard-coded ::User.
4. Host-app contract is documented (see Host App Contract section).

SAFETY CHECKS:
5. Engine code never auto-applies migrations at boot (no db:migrate, ActiveRecord::Migrator, or config.paths['db/migrate'] in initializers).
6. Initializers are idempotent and safe in development reloads.
7. Assets and generators are namespaced and idempotent.

VERIFICATION COMMANDS:
8. Dummy app exists: `ls spec/dummy` or `ls test/dummy` should return the app directory.
9. Integration tests pass: `bundle exec rspec` or `bundle exec rake test` exits 0.
10. Routes load correctly: `bundle exec rails routes` inside dummy app shows engine routes.
11. No hard-coded host constants: `grep -r "::User\|::Employee" lib/ app/` returns nothing.
12. No migration auto-apply patterns: `grep -r "db:migrate\|ActiveRecord::Migrator\|config.paths\['db/migrate'\]" lib/` returns nothing.

Core Process

1. Identify the engine type before writing code. Scaffold with the correct generator:

   rails plugin new my_engine --mountable   # mountable engine
   rails plugin new my_engine --full        # full engine (non-isolated)
   rails plugin new my_engine               # plain Railtie/gem

2. Define the host-app contract.
3. Create the minimal engine structure. Checkpoint: bundle exec rake inside the engine must pass.
4. Implement features behind the namespace. Checkpoint: mount engine in dummy app routes and verify with bundle exec rails routes.
5. Plan and write minimum integration coverage through the dummy app.
6. Document the host-app contract clearly enough for follow-on work.

If the user does not specify the engine type, infer it from the requested behavior and say which type you chose.

Extended Resources

Recommended Structure Use a structure close to this:

my_engine/
  lib/
    my_engine.rb
    my_engine/version.rb
    my_engine/engine.rb
    generators/
  app/
    controllers/
    models/
    jobs/
    views/
  config/
    routes.rb
    locales/
  db/
    migrate/
  spec/ or test/
    dummy/

Keep the root module small.

Host App Contract Define it before implementation and keep it updated throughout.

• What the host app must add: mount route, initializer, migrations, credentials, background jobs, or assets.
• What the engine exposes: models, controllers, helpers, configuration, rake tasks, generators, middleware, or events.
• Which extension points are supported: config block, adapter interface, callbacks, or service objects.

Prefer one explicit configuration surface, for example:

MyEngine.configure do |config|
  config.user_class = "User"
  config.audit_events = true
end

Testing Expectations Minimum coverage through the dummy app (not just isolated classes):

• Engine integration tests through the mounted dummy app.
• Routing/request tests for all mountable engine endpoints.
• Configuration tests for each supported host customization option.
• Generator tests when install/setup generators exist.

Examples Minimal root module:

# lib/my_engine.rb
require "my_engine/version"
require "my_engine/configuration"
require "my_engine/engine"

module MyEngine
  class << self
    def configuration
      @configuration ||= Configuration.new
    end

    def configure
      yield(configuration)
    end
  end
end

Minimal mountable engine class:

# lib/my_engine/engine.rb
module MyEngine
  class Engine < ::Rails::Engine
    isolate_namespace MyEngine

    config.generators do |g|
      g.test_framework :rspec
      g.fixture_replacement :factory_bot
    end
  end
end

Routes namespaced under engine:

# config/routes.rb
MyEngine::Engine.routes.draw do
  root to: 'dashboard#index'
  resources :widgets, only: %i[index show]
end

• reference.md
• EXAMPLES.md
• TESTING.md
• assets/examples.md
• assets/release-checklist.md

Output Style

1. Narrow purpose — State the engine's narrow purpose, chosen engine type, and small public API before listing files.
2. Structure — Use idiomatic Rails engine patterns and include the recommended lib/, app/, config/, db/, and spec/dummy or test/dummy shape.
3. Host-app contract — Outline mount route, initializer, migrations, credentials, background jobs, and assets. Mark any item "not applicable" instead of omitting it.
4. Configuration surface — Ensure configuration points are documented and centralized in one .configure block or equivalent adapter surface.
5. Verification checkpoints — Include ls spec/dummy or ls test/dummy, bundle exec rake inside the engine, integration specs, routes check inside the dummy app, and grep checks for hard-coded host constants and migration auto-apply patterns.
6. Language — Must be in English unless explicitly requested otherwise.

Integration