igmarin Phase 1: Engine Authoring
- skills/create-engine (sub-skill — invoke separately) — Design and scaffold namespace isolation, directory structure, and gemspec configuration
Kickoff command:
rails plugin new my_engine --mountable --test-framework=rspec
Key files to verify after scaffolding:
lib/my_engine/engine.rb— must containisolate_namespace MyEnginelib/my_engine/version.rbmy_engine.gemspec— must passgem specificationvalidationtest/dummy/— dummy app present
HARD GATE — Engine Structure Check:
grep -r 'module MyEngine' lib/my_engine/engine.rb
ruby -e "require 'rubygems'; spec = Gem::Specification.load('my_engine.gemspec'); puts spec.validate"
grep 'isolate_namespace\|engine.config.isolate_namespace' lib/my_engine/engine.rb
If structure check FAILS: Return to create-engine and fix.
Phase 2: Testing Setup
skills/test-engine (sub-skill — invoke separately) — Set up dummy app, spec helpers, factory isolation, and test database
Write initial characterization tests:
- Test engine mounting
- Test generators if any
- Test core functionality
Run tests from engine root:
cd my_engine && bundle exec rspec
HARD GATE — Tests Run:
bundle exec rspec --format progress 2>&1 | tail -5
Must show no load errors and exit 0.
If load errors appear: Consult the test-engine sub-skill for ordered troubleshooting steps.
HARD GATE — Isolation Before Integration:
NEVER integrate engine into host app before:
- Engine tests pass standalone
- Namespace properly isolated
- Migrations won't conflict
- Dependencies clearly declared
Phase 3: Implementation & Review
Implement features using:
- tdd agent for complex features
- Individual skills for simple additions
skills/review-engine (sub-skill — invoke separately)
skills/upgrade-engine (sub-skill — invoke separately)
Check gem dependencies:
bundle exec rake dependencies
bundle exec bundler-audit check --update
Phase 4: Documentation & Release
skills/document-engine (sub-skill — invoke separately) — Installation, configuration, usage examples, changelog
skills/release-engine (sub-skill — invoke separately) — Version bump (SemVer), changelog, upgrade notes, git tag
Release commands:
gem build my_engine.gemspec
gem push my_engine-1.0.0.gem
git tag v1.0.0 && git push origin v1.0.0
Optional:
3. skills/create-engine-installer — Idempotent rails g my_engine:install generator for host app configuration
Output: Published gem or releasable GitHub repository.
Quick Reference
New engine? → create-engine → test-engine
Extract from app? → extract-engine → create-engine
Release engine? → review-engine → release-engine
Not sure? → skill-router
Common Anti-Patterns
| Anti-Pattern | Fix |
|---|---|
Namespace leakage — ::MyEngine instead of MyEngine:: |
Verify isolate_namespace MyEngine in engine.rb |
| Migration conflicts — Migrations outside engine dir or missing path config | Run engine migrations in isolation via dummy app |
Missing gemspec dependencies — Runtime gems in Gemfile but not in .gemspec |
Run bundle exec rake dependencies and bundler-audit check at Phase 3 end |
Dummy app load errors — Missing require or incorrect spec_helper |
Use test-engine sub-skill diagnostic steps |