igmarin/rails-engine-extraction

Rails Engine Extraction

Use this skill when the task is to move existing code out of a Rails app and into an engine.

Prefer incremental extraction over big-bang rewrites. Preserve behavior first, then improve design.

HARD-GATE

DO NOT extract and change behavior in the same step. Extraction must preserve existing behavior; refactoring and improvements belong in a separate step after the move is complete and verified.

Extraction Order

1. Identify the bounded feature to extract — one coherent responsibility.
2. List hard dependencies on the host app (models, services, config).
3. Define the future engine boundary and host contract.
4. Move stable domain logic first: POROs, services, value objects, policies, query objects. Delay direct host model references, authentication, route ownership, and asset integration.
5. Add adapters or configuration seams for host-owned dependencies. Replace hardcoded host references with config values, adapter objects, or service interfaces.
6. Move controllers, routes, views, or jobs only after seams are clear.
7. Keep regression coverage green throughout each slice.

Each slice must have: one coherent responsibility, minimal new public API, passing regression tests, and a clear next step.

Pitfalls

| Pitfall | What to do | |---------|------------| | Extracting too much at once | One bounded slice per step; large extractions hide bugs and are hard to revert | | Direct host references in engine | Use adapters or config; direct constants couple engine to host internals | | Behavior changes mixed with extraction | Preserve behavior first; refactor only after the move is verified | | Circular dependencies introduced | Verify import graph before moving each slice | | Dummy app passes but host contract is implicit | Explicitly document and test the host app contract |

Examples

First slice (move PORO, no host model yet):

# Move the file into the engine and adjust the namespace
mkdir -p my_engine/app/services/my_engine
mv app/services/pricing/calculator.rb my_engine/app/services/my_engine/pricing_calculator.rb

# Before (in host app): module Pricing; class Calculator
# After (in engine):
module MyEngine
  class PricingCalculator
    def initialize(line_items)
      @line_items = line_items
    end

    def total
      @line_items.sum { |item| item.price * item.quantity }
    end
  end
end

Verify regression coverage still passes before proceeding to the next slice:

bundle exec rspec spec/services/pricing/ spec/requests/orders/

Move engine-local models in the same slice, or keep host models and inject via an adapter in a later slice.

Adapter for host dependency (compact):

# config seam (compact)
module MyEngine
  def self.current_user_for(request)
    config.current_user_provider.call(request)
  end
end

# usage
OrderCreator.for_request(request) # resolves via MyEngine.current_user_for(request)

See references/adapter_examples.md for the full adapter example. Compact examples and the per-slice checklist are available at rails-engine-extraction/assets/examples.md and rails-engine-extraction/assets/checklist.json.

Integration

| Skill | When to chain | |-------|----------------| | rails-engine-author | Engine structure, host contract, namespace design after extraction | | rails-engine-testing | Dummy app, regression tests, integration verification | | refactor-safely | Behavior-preserving refactors before or after extraction slices |

Assets

• assets/examples.md
• references/adapter_examples.md