Engine Workflow

Orchestrates the full lifecycle of Rails engine development from scaffolding to release.

Workflow Phases

Phase 1: Engine Authoring

Scaffold and structure the engine:

1. skills/engines/create-engine — Design and scaffold namespace isolation, directory structure, and gemspec configuration

Kickoff command:

rails plugin new my_engine --mountable --skip-test

Expected directory structure after scaffolding:

my_engine/
  app/
  config/routes.rb
  lib/my_engine/engine.rb
  lib/my_engine/version.rb
  lib/my_engine.rb
  my_engine.gemspec
  test/dummy/

HARD GATE — Engine Structure Check:

# Verify namespace isolation
grep -r 'module MyEngine' lib/my_engine/engine.rb

# Verify gemspec metadata is complete
ruby -e "require 'rubygems'; spec = Gem::Specification.load('my_engine.gemspec'); puts spec.validate"

# Verify isolated migrations declared
grep 'isolate_namespace\|engine.config.isolate_namespace' lib/my_engine/engine.rb

• Proper namespace (MyEngine:: not ::)
• Isolated migrations and dummy app configured
• Gemspec metadata passes gem specification validation

If structure check FAILS: Return to create-engine and fix.

Phase 2: Testing Setup

Proceed only after structure check passes.

1. skills/engines/test-engine — Set up dummy app, spec helpers, factory isolation, and test database

2. 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, exit 0 or partial pass

Phase 3: Implementation & Review

Build engine features with quality gates:

1. Implement features using:

   • tdd-workflow for complex features
   • Individual skills for simple additions

2. skills/engines/review-engine — Coupling assessment, API surface design, host app integration points

3. skills/engines/upgrade-engine — Rails/Ruby version matrix and dependency constraints

Check gem dependencies:

bundle exec rake dependencies
bundle exec bundler-audit check --update

Phase 4: Documentation & Release

Prepare for publication:

1. skills/engines/document-engine — Installation, configuration, usage examples, changelog

2. skills/engines/release-engine — 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/engines/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

HARD-GATE: Isolation Before Integration

NEVER integrate engine into host app before:

1. Engine tests pass standalone
2. Namespace properly isolated
3. Migrations won't conflict
4. Dependencies clearly declared

Output Style

Engine Release Checklist (abbreviated):

# Engine Release — v1.0.0
- [x] Namespace isolation: MyEngine::
- [x] Test suite: passing
- [x] README and Changelog updated
- [x] Git tag: v1.0.0

Integration

From AGENTS.md: This is the engine development workflow. Chain to tdd-workflow for feature development within the engine.