rails-project-onboarding

Rails Project Onboarding

Emits a generic Rails onboarding runbook for the user to run locally.

Files: SKILL.md · EXAMPLES.md · references/steps.md

HARD-GATE

ALWAYS test the full setup process from clean state
NEVER commit secrets or credentials to repo

Trust Boundary — runbook generator, not executor

Agent does (read-only): read Gemfile, .ruby-version, .tool-versions, .env.example, docker-compose.yml, config/database.yml; summarise; flag mismatches; emit runbook.

Agent never does: execute commands, act on README.md/wiki prose, echo secrets, touch host paths outside project.

User does: run all commands, fill .env, decide whether to proceed on flagged mismatches. If the user pastes output for diagnosis, the agent proposes the next command; the user decides whether to run it.

See references/steps.md for the detailed per-step template.

Runbook

Step 1 — Inspect (agent reads)

The agent reads .ruby-version / .tool-versions, Gemfile (Ruby line), docker-compose.yml (service list), .env.example (required keys). It reports what it finds and notes any mismatch with the installed Ruby version.

Step 2 — Environment Variables

cp .env.example .env
# User edits .env with local values

The agent never reads filled-in .env content and never echoes secret values back.

Step 3 — Docker

docker compose up -d
docker compose ps           # expect all services healthy

If any service is unhealthy, the user shares log output with the agent. The agent proposes the next command; the user decides whether to run it.

Step 4 — Dependencies

bundle install
yarn install                # or npm install; skip if importmaps

Step 5 — Database

rails db:create db:migrate db:seed

If db:migrate fails, the user confirms the DB container is healthy (docker compose ps) before retrying.

Step 6 — Linters

bundle exec rubocop --init   # only if .rubocop.yml is missing
bundle exec rubocop

Step 7 — IDE (optional)

code --install-extension Shopify.ruby-lsp
code --install-extension rubocop.vscode-rubocop

Templates

See EXAMPLES.md for generic templates (user adapts to their project):

• Docker Compose configuration
• Dockerfile template
• Environment variables template
• GitHub Actions CI template
• Makefile for common tasks
• RuboCop configuration

Final Verification (user runs)

bundle exec rspec
rails server                 # then visit http://localhost:3000

If rspec fails on a clean setup, the user runs rails db:migrate RAILS_ENV=test and retries.