agent-skills AGENTS.md

Spree Commerce — Agent Guidance

This file follows the agents.md cross-tool standard. It's a portable summary of how to be effective on a Spree Commerce codebase, written for any agentic CLI (Codex, Cursor, Copilot, Aider, Windsurf, Zed, Amp, etc.) that reads AGENTS.md.

If you're running in Claude Code, install this package as a plugin and you'll get the 26 SKILL.md files under skills/ as on-demand context, the spree-expert subagent, and two safety hooks. See README.md for install instructions.

If you're running in any other tool: read this file, then dive into the relevant skills/<name>/SKILL.md when the task matches its domain.

---

What Spree is

Spree Commerce is an open-source, self-hosted commerce platform built on Ruby on Rails. The thing people choose it for is the ability to customize and extend it without forking. Architecture in three layers:

1. Backend (Ruby gems) — spree_core (models, services, business logic), spree_api (Store + Admin REST APIs under /api/v3/), spree_admin (Rails admin UI), optional payment/integration gems (spree_stripe, spree_adyen, spree_paypal_checkout, spree_i18n).
2. Frontend SDKs (TypeScript) — @spree/sdk (Store API client), @spree/admin-sdk (Admin API client).
3. Admin UI — spree_admin (the Rails/Turbo admin).

Users run Spree in their own infrastructure — there's no Spree cloud. Everything is opt-in customization.

Core conventions (don't violate these without a reason)

Ruby / Rails

• All Spree code is namespaced under Spree::.
• All models inherit from Spree.base_class — not ApplicationRecord directly.
• Use Spree.user_class and Spree.admin_user_class instead of Spree::User so apps can swap the user model.
• Always scope queries through current_store (e.g. current_store.orders, not Spree::Order.all). Multi-store apps share a database; un-scoped queries leak data across stores.
• State/status fields on state-machine models (Order, Payment, Shipment) are string columns — don't convert them to Rails enums. (Core does use integer enums for a few non-workflow fields like Promotion#kind; string + state machine is still the default for anything with transitions.)
• IDs are treated as strings (Stripe-style prefixed IDs at the API surface; integer PKs internally — never .to_i an ID).
• State machines use the state_machines-activerecord gem.
• Uniqueness validations use scope: spree_base_uniqueness_scope plus a DB index.
• Always pass class_name and dependent on associations.
• Use the events system (publish_event + subscribers) for side effects — not after_* callbacks.