AGENTS.md — Rails app with Hotwire

A server-rendered Ruby on Rails app using Turbo and Stimulus for interactivity, with design tokens as CSS variables and no separate front-end build.

Setup and commands

• dev: bin/dev
• e2e: bin/rails test:system
• lint: bin/rubocop && bin/brakeman --no-pager
• test: bin/rails test
• build: bin/rails assets:precompile
• deploy: bin/kamal deploy
• install: bundle install && bin/rails db:prepare

Project structure

• app/models/ — Active Record models and concerns; domain logic lives here or in plain Ruby objects under app/models
• app/controllers/ — RESTful controllers, one per resource
• app/views/ — ERB templates and partials, one folder per controller
• app/views/components/ — Design-skill components as partials (_button, _field, _card)
• app/javascript/controllers/ — Stimulus controllers, one behaviour each
• app/assets/stylesheets/tokens.css — CSS variables written from the design skill, light and dark
• test/system/ — One system test per experience-skill journey

Code style

• Files: snake_case.rb; Stimulus controllers kebab-case_controller.js
• Tests: test/<type>/<name>_test.rb; test/system/<journey_id>_test.rb
• Branches: type/short-description, e.g. feat/team-invites
• Components: Partials named after the design-skill component, e.g. components/_button.html.erb

Code

• Prefer small, pure functions and explicit types at module boundaries. (Easier to test, review and change.)
• Stick to the seven RESTful actions; add a new resource controller instead of custom actions. (Routes stay predictable and controllers stay small.)

Components

• Components read design tokens; no raw hex values, pixel sizes or font names in component code. (One token change restyles the product.)

Data

• Analytics events are object_action in snake_case and come from the experience skill’s measures. (Names stay consistent across teams and tools.)
• Use strict loading or includes on every collection rendered in a view, and add database constraints for every validation that matters. (Prevents N+1 queries and data that bypasses model validations.)

Errors

• Every async action has loading, empty, error and success states, matching the experience skill. (Unhandled states are where users get stuck.)

Security

• Secrets never live in the repository; read them from the environment or a secret store. (A leaked key outlives the commit that removed it.)
• Validate every input on the server, even when the client already did. (Clients can be bypassed.)
• Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. (Cheap protection against the most common attacks.)
• Permit parameters explicitly and scope finds through the current user, e.g. Current.user.projects.find(params[:id]). (Blocks mass assignment and access to other users’ records.)
• Keep credentials in encrypted credentials or environment variables, and run Brakeman on every pull request. (Static checks catch injection and unsafe redirects early.)

Performance

• Fragment-cache expensive partials with cache keys from the record, and move work over 100ms into Active Job. (Keeps responses fast without hand-rolled invalidation.)

Accessibility

• Use native elements first; add ARIA only when no native element fits. (Native controls bring keyboard and screen-reader support for free.)
• When a Turbo Stream replaces content, announce it in an aria-live region or move focus to the new heading. (Partial updates are silent to screen readers by default.)

Design and journeys

When a Celestial design skill is in use, write its tokens as CSS custom properties in app/assets/stylesheets/tokens.css, and build its components in app/views/components with the same names and variants. Components read tokens only — no raw colours, sizes or font names.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events object_action from its measures.

Testing and checks (must pass before a pull request)

Pull requests

• Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

Review checklist

• Correctness: does it do what the issue asks, including edge cases?
• Readability: could a new teammate change it safely?
• Architecture: is it in the right place, with the right boundaries?
• Security: inputs, secrets, permissions, dependencies
• Performance: budgets, queries, bundle size
• Tests fail when the code is broken (flip a condition and re-run)
• One approving review; two for auth, billing, migrations or data deletion
• Reviewer clicks through the journey on the preview, with Turbo and with a hard reload

Definition of done

• Acceptance criteria met and demoed on the preview link
• Tests added for new behaviour and every state
• Accessibility and performance gates green
• Analytics events named from the experience skill
• Docs or changelog updated when behaviour changes

Release

• Small pull requests (aim for under 400 changed lines)
• CI green before review
• Squash-merge to main; main is always deployable
• Every release has a written rollback path
• Merge to main deploys with Kamal; migrations run before the new containers take traffic
• Migrations are safe to run while the old release is live

Incidents

• Roll back with kamal rollback to the previous version
• Blameless note within 48 hours

Generated from the Celestial engineering skill “Rails app with Hotwire” (engineering core v1.0, checked 2026-10-26).