From 92066cd6645688ff9f5d727a773e4b112c7ac77b Mon Sep 17 00:00:00 2001 From: Kenneth Gallego Date: Fri, 19 Dec 2025 13:32:28 +0100 Subject: [PATCH] Add agent.md file --- AGENT.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 AGENT.md diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..d158c7e --- /dev/null +++ b/AGENT.md @@ -0,0 +1,32 @@ +# Agent Guide + +Essence is a Rails 8 engine that ships Beyond UI as ViewComponents with Stimulus/Turbo; Lookbook preview lives in `site/`. + +Stack quickref +- Ruby >= 3.3 with Bundler +- ViewComponent + SimpleForm; importmap + Propshaft assets; Stimulus controllers in `app/javascript/essence/controllers` +- Components in `app/components/essence`; styles/images under `app/assets/essence` + +Setup +- `bundle install` +- Preview app: `cd site && bin/setup --skip-server` to install deps and prep the sqlite DB +- Start Lookbook: `cd site && bin/rails server` (or run `site/bin/setup` without `--skip-server` to boot via `bin/dev`) + +Everyday dev +- Subclass `Essence::ApplicationComponent`; pair `*_component.rb` with `*_component.html.erb` +- JS entry: `app/javascript/essence/application.js`; register controllers via `controllers/index.js`; add importmap pins in `config/importmap.rb` when needed +- CSS/design tokens in `app/assets/stylesheets/essence`; images in `app/assets/images/essence` +- Previews/examples live in `site/app/previews/**`; mirror new props and states there +- Shared helpers and form inputs are under `app/helpers` and `app/inputs`; reuse existing utilities before adding new ones + +Quality gates +- Specs: `bundle exec rspec` +- Lint: `bundle exec rubocop` +- Security: `bundle exec brakeman` +- Gem sanity: `bundle exec rake build` (bundler gem tasks) + +Notes for changes +- Keep HTML semantics and ARIA intact; components are consumed by storefront apps +- Avoid bundling external JS/CSS; rely on importmap + Stimulus +- Preserve backward compatibility; prefer deprecations to breaking changes +- Update previews and documentation when behaviour or UI shifts