Engine Workflow

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

Note: Sub-skills referenced below (skills/engines/create-engine, test-engine, review-engine, etc.) are expected to exist separately in the skill bundle.

Workflow Phases

Phase 1: Engine Authoring

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

Key files to verify after scaffolding:

• lib/my_engine/engine.rb — namespace isolation declared
• lib/my_engine/version.rb — version constant present
• my_engine.gemspec — metadata complete and valid
• test/dummy/ — dummy app scaffolded

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

If load errors appear, fix in order:

• Verify spec/spec_helper.rb requires dummy app: require File.expand_path('../dummy/config/environment', __FILE__)
• Verify dummy app mounts engine in test/dummy/config/application.rb
• Run bundle install inside engine root
• Confirm Gemfile points to a valid dummy app path

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

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

Integration

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