rails-bootstrap

name

rails-bootstrap

description

Bootstrap a new, production-leaning Ruby on Rails application on the latest Rails (8.1.x) and Ruby (4.0.x), with version pinning, sensible defaults, and verification. Use this skill whenever the user wants to start, scaffold, generate, or set up a new Rails app, mentions `rails new`, asks for a Rails project skeleton or starter, or says things like "spin up a Rails API", "create a new Rails 8 app", or "bootstrap a Rails project" — even if they don't name the skill explicitly. Do NOT use it for modifying an existing Rails app, upgrading Rails versions, or non-Rails projects. To only verify an app that already exists, use the rails-verify skill instead.

Rails Bootstrap

Generate a fresh Rails application using the current stable Rails and Ruby, wired up with the framework's modern in-box defaults and a verification pass so the user ends with an app that actually boots and passes its tests.

The goal is a reproducible, opinionated-but-configurable starting point — not a plain rails new. The hard part of bootstrapping isn't running one command; it's pinning versions so the project builds the same way next month, picking the right flags, and confirming the result works before handing it over.

Target versions

Pin these explicitly rather than relying on "latest," so the project is reproducible. The pins live in one executable place — scripts/lib/versions.sh — and are mirrored here for reference. Confirm the current patch releases with a quick web search before generating, then update versions.sh if they have moved.

• Ruby: 4.0.x (4.0.5 as of mid-2026)
• Rails: 8.1.x (~> 8.1.3 as of mid-2026)

If the user's installed Ruby is a different minor version (e.g. 3.4), tell them before proceeding — the bootstrap hard-stops in preflight, because mixing a 3.x runtime with 4.0 pinning will break the build.

Inputs to collect

Ask the user for these before generating (the script accepts them as flags). Offer the default in parentheses if they don't care.

• App name — required, lowercase, underscores or hyphens.
• Database (postgresql) — postgresql, sqlite3, or mysql.
• Mode (full) — full-stack or --api only.
• JS bundling (importmap) — importmap, esbuild, or bun. Ignored in API mode.
• CSS (tailwind) — tailwind, bootstrap, or none. Ignored in API mode.
• Test framework (minitest) — minitest (in-box, zero extra gems) or rspec.

When in doubt, the defaults above produce a modern full-stack app. Don't over-ask; if the user says "just give me a standard Rails 8 app," use the defaults and go.

Workflow

Run the bundled orchestrator — it encodes the full sequence and is more reliable than issuing the steps by hand. Read it first (and the lib/ step scripts it sources) so you understand what it does, then invoke it with the collected inputs:

scripts/bootstrap_rails.sh \
  --name myapp \
  --database postgresql \
  --css tailwind \
  --js importmap \
  --test minitest

Add --api for API-only mode. The orchestrator (scripts/bootstrap_rails.sh) calls these steps in order; each lives in its own file so it can be read and tested in isolation:

1. Preflight (lib/preflight.sh) — verifies Ruby is on the 4.0 line, Bundler is present, and the chosen database's client is installed. A missing client for the chosen DB is fatal here, not a warning, so the run stops with a clear message rather than failing halfway through a native gem build.
2. Generate (lib/generate.sh) — installs the pinned Rails gem and runs rails new with flags derived from the inputs.
3. Pin (configure::pin) — writes .ruby-version and tightens the ruby directive and the gem "rails" constraint in the Gemfile.
4. Wire defaults (configure::wire_defaults) — installs the Solid Queue / Cache / Cable schemas and, for full-stack apps, the built-in authentication generator. Failures surface as warnings, not silence.
5. Quality (configure::quality) — runs RuboCop (safe autocorrect) and Brakeman as a smoke check.
6. Database (configure::database) — db:create then db:migrate.
7. RSpec swap (configure::swap_to_rspec, only with --test rspec) — removes test/, adds rspec-rails + factory_bot + faker + capybara, runs the installer.
8. Git (configure::git_init) — git init and an initial commit.
9. Verify (verify::run, shared with the rails-verify skill) — eager-loads the app, boots a real server and waits for HTTP 200 on /up, then runs the suite. A red suite fails the bootstrap unless --allow-test-failures is set.

After bootstrapping

Report the final Ruby and Rails versions from bin/rails about, the database in use, and the path to the new app. Mention the two or three next commands the user will likely want (bin/dev or bin/rails server, where the auth routes live, how to run tests). Keep it short — they can read the generated README.

If any step fails, the orchestrator stops and surfaces the actual error (and points at the partial app directory). Do not report success on a bootstrap that didn't boot or whose tests are red — that hides the breakage, which is the one thing this skill exists to prevent.

Background

See reference/rails8-defaults.md for why each Rails 8 default is wired the way it is and the rationale behind version pinning and verification.