Agent Notes

Project Shape

Rails 8.1 app (CarTracker) on Ruby 4.0.6; .ruby-version includes the ruby- prefix, while the Dockerfile uses ARG RUBY_VERSION=4.0.6.
The app is still mostly generated Rails skeleton. Treat DESIGN.md as product direction, not proof of implemented models/routes.
Database is SQLite under storage/. Production is configured with separate SQLite databases for primary, Solid Cache, Solid Queue, and Solid Cable.
JavaScript uses importmap + Turbo + Stimulus; there is no package.json or npm install step. Pin JS dependencies with bin/importmap, not npm/yarn.

Commands

Setup/update dependencies and DB: bin/setup --skip-server. Omit --skip-server only when you want it to start bin/dev afterward.
Run the app: bin/dev (it just execs bin/rails server).
Repo CI script: bin/ci runs setup, RSpec, RuboCop, bundler-audit, importmap audit, and strict Brakeman.
GitHub CI also runs the repo CI script; do not assume tests ran unless bin/ci completed successfully.
Style check: bin/rubocop (rubocop-rails-omakase via .rubocop.yml).
Security checks: bin/bundler-audit, bin/importmap audit, bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error.

Tests

RSpec is installed; run specs with bundle exec rspec, not bin/rails test.
Run a focused spec with bundle exec rspec spec/path/to/file_spec.rb:LINE.
.rspec only requires spec_helper; Rails specs need require "rails_helper" explicitly.
DESIGN.md says to develop features test-first. Add specs for new behavior even though current CI does not run them.

Rails/Runtime Gotchas

config/application.rb disables Rails system test generation and does not load rails/test_unit/railtie.
ApplicationController rejects non-modern browsers with allow_browser versions: :modern and uses stale_when_importmap_changes.
Solid Queue jobs can run with bin/jobs; Kamal production config currently runs Solid Queue inside Puma via SOLID_QUEUE_IN_PUMA: true.
Production Docker is intended for Kamal/production, not local development; the entrypoint runs bin/rails db:prepare before starting the server.

Instructions

If you are implimenting a phase eg phaseXXX ensure that while you are modifying files you write a file in teh executions/ folder matching using executionXXX.md for the filename. This is all replacing the XXX with the phase number you are on.

2.4 KiB Raw Blame History