igmarin Extract Engine
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.
Quick Reference
| Phase | Focus |
|---|---|
| Prep | Identify bounded feature and host dependencies |
| Logic | Move stable domain logic (POROs, services) first |
| Seams | Add adapters/config for host dependencies |
| Web | Move controllers, routes, views last |
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.
Core Process
- Identify the bounded feature to extract — one coherent responsibility.
- List hard dependencies on the host app (models, services, config).
- Define the future engine boundary and host contract.
- Move stable domain logic first: POROs, services, value objects, policies, query objects. Delay direct host model references, authentication, route ownership, and asset integration.
- Add adapters or configuration seams for host-owned dependencies. Replace hardcoded host references with config values, adapter objects, or service interfaces.
- Move controllers, routes, views, or jobs only after seams are clear.
- 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.
Extended Resources
Pitfalls
| Pitfall | What to do |
|---|---|
| Extracting too much at once | One bounded slice per step |
| Direct host references in engine | Use adapters or config |
| Behavior changes mixed with extraction | Preserve behavior first; refactor after |
| Circular dependencies introduced | Verify import graph before each slice |
| Implicit host contract | Explicitly document and test the host app contract |
Examples
First slice (move PORO, no host model yet):
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:
bundle exec rspec spec/services/pricing/ spec/requests/orders/
Adapter for host dependency:
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)
Output Style
- Propose one small, bounded extraction slice at a time.
- Outline the files moving, the new boundaries, and the regression tests to run.
- Language — Must be in English unless explicitly requested otherwise.
Integration
| Skill | When to chain |
|---|---|
| create-engine | Engine structure, host contract, namespace design after extraction |
| test-engine | Dummy app, regression tests, integration verification |
| refactor-code | Behavior-preserving refactors before or after extraction slices |