create-standards 1.0.0

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/01-project-structure.md

@@ -0,0 +1,44 @@
+# Project Structure Standards (Ruby on Rails)
+
+## Detect before you structure anything
+
+This codebase already has a structure — the job is to recognize it and extend it consistently,
+not to impose a textbook layout on top of it. Before adding a new folder or a new kind of class:
+
+1. Look at `app/` — which of these already exist: `services/`, `queries/`, `forms/`, `policies/`,
+   `serializers/`, `decorators/`? Whatever's there is the convention for this codebase.
+2. If a folder you'd normally reach for (e.g. `services/`) **doesn't exist yet** and the task is
+   small, that's a signal — either this codebase keeps that logic somewhere else (check a model or
+   controller for where similar logic lives), or it genuinely doesn't have this layer yet. If
+   introducing a new top-level pattern for the first time, say so plainly rather than silently
+   creating it, and ask if it's a big structural addition.
+3. Don't scan the entire `app/` tree to figure this out — `ls app/` plus opening one or two
+   existing files near where you're adding code is enough.
+
+## Common Rails layers, when they're already in use
+
+```
+app/
+  controllers/            # thin: auth -> authorize -> delegate -> render
+  models/                  # persistence + validations + associations
+  services/                # multi-step business logic, if this codebase uses the pattern
+  queries/                 # complex/reusable query objects, if in use
+  forms/                   # form objects for multi-model or non-persisted input, if in use
+  policies/                # authorization objects, matching whichever auth gem is detected
+  serializers/              # JSON shape, matching whichever serialization approach is detected
+  jobs/                    # background jobs, matching whichever adapter/gem is detected
+  lib/                      # framework-agnostic code with no Rails dependency
+```
+
+## Rules that hold regardless of which layers this codebase uses
+
+- **Controllers stay thin** no matter what: auth → authorize (if the app has an authorization
+  layer) → delegate to wherever business logic already lives → render. Multi-step business logic
+  doesn't belong inline in a controller action, whatever it's called in this codebase.
+- **Don't let one model absorb unrelated logic.** If a model file is already large and you're
+  about to add another unrelated method, look at how the codebase has handled that split before
+  (a concern? a PORO? a service?) and match it, rather than inventing a new extraction pattern.
+- **Concerns are for genuinely shared behavior** (used by 2+ classes already, or clearly about to
+  be). A concern used by exactly one class is unnecessary indirection — inline it instead.
+- **Namespace and version the API** the way the existing routes already do. If this is the first
+  API endpoint in the app, ask whether versioning is wanted before picking a scheme.

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/02-api-design-standards.md

@@ -0,0 +1,46 @@
+# REST API Design Standards (Rails)
+
+## Follow the existing convention first
+
+If the app already has API endpoints, open one and copy its shape exactly — route style,
+namespacing, response envelope, status codes, error format. Consistency with the rest of the app
+matters more than matching a generic "best practice" that conflicts with it. Only fall back to the
+generic guidance below if this is genuinely the first endpoint of its kind, and mention that
+you're establishing a new convention.
+
+## Routing
+
+- Use `resources`/`resource` with explicit `only:`/`except:` — don't leave all 7 RESTful actions
+  open if only a few are used, whether or not the rest of the app does this consistently.
+- Nest one level max: `resources :orders do resources :items, only: [:index, :create] end`.
+- Namespace + version if the app already does (`Api::V1::...`); if there's no existing API and
+  this is the first one, ask whether versioning is wanted before picking a scheme.
+
+## Controllers
+
+- Auth → authorize (using whatever authorization approach is already in the codebase — see
+  `04-security-standards.md` for how to detect it) → delegate to wherever business logic already
+  lives → render. No inline multi-step `ActiveRecord` chains in the controller action itself.
+- Strong parameters are mandatory on every write action regardless of anything else detected.
+
+## Status codes & responses
+
+- `200`/`201`/`204` success, `400`/`422` validation, `401`/`403` auth, `404` not found, `429` rate
+  limited, `500` unhandled — these are stable regardless of gem choices.
+- **Response shape**: detect what the app already returns (check an existing controller/serializer).
+  If it already uses Blueprinter, `ActiveModel::Serializer`, `jsonapi-rb`, Jbuilder, or plain
+  `as_json`/`render json:` with a hand-built hash — match that, don't introduce a second approach.
+  If there's genuinely no existing pattern, ask which the team prefers before picking one; don't
+  assume a specific serializer gem.
+- Never call `.to_json` on a raw ActiveRecord object/relation regardless of which serialization
+  approach is chosen — that leaks DB columns either way.
+
+## Other requirements
+
+- **Pagination**: match the existing approach if list endpoints already paginate (Kaminari, Pagy,
+  will_paginate, manual). If there's no existing list endpoint to reference, ask before adding a
+  pagination gem — a small internal API may not need one.
+- **Filtering/sorting** via an explicit allow-listed param set — never pass raw `params` into
+  `.where`/`.order`, independent of which query pattern the app uses.
+- **API docs**: match whatever the app already uses (rswag/OpenAPI annotations, a hand-maintained
+  file, or none). If none exists, flag that rather than silently skipping documentation.

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/03-error-handling-validation.md

@@ -0,0 +1,35 @@
+# Error Handling & Validation Standards (Rails)
+
+## Detect the existing pattern
+
+Check `ApplicationController` (or the relevant base controller) for existing `rescue_from`
+declarations, and check one or two model/service files for how validation failures are currently
+surfaced. Match that pattern. Only introduce a new centralized `rescue_from` chain if none exists
+— and note that you're adding a new cross-cutting pattern, since it affects every controller.
+
+## If there's an existing pattern, extend it
+
+```ruby
+# Example shape — only use this if the codebase doesn't already have something similar
+class Api::BaseController < ActionController::API
+  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+  rescue_from ActiveRecord::RecordInvalid,  with: :render_unprocessable
+end
+```
+
+- If custom domain error classes already exist (`ApplicationError` or similar), follow that
+  hierarchy for new errors. If none exist yet, a base `ApplicationError < StandardError` with
+  domain subclasses is a reasonable default to introduce — but call out that it's new.
+
+## Rules that hold regardless of the existing pattern
+
+- **No bare `rescue => e` that swallows errors silently.** If broad rescue is unavoidable (e.g.
+  around a third-party call), re-raise a typed error or log with full context.
+- Validation belongs on the model (persistence-level rules) or a form object (cross-model/
+  non-persisted input) — match whichever the codebase already uses for similar cases, rather than
+  hand-validating raw `params` in the controller.
+- `.save!`/`.update!` inside service-style objects so failures raise and get caught centrally,
+  matching whatever the surrounding code already does with bang vs non-bang methods.
+- Validation error responses return `422` with per-attribute detail
+  (`record.errors.full_messages` or similar) — the specific shape should match the response
+  envelope already established (see `02-api-design-standards.md`).

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/04-security-standards.md

@@ -0,0 +1,32 @@
+# Security Standards (Rails)
+
+## Detect the existing security stack before adding anything
+
+- **Authorization**: check `Gemfile` for `pundit` or `cancancan`, and check an existing
+  controller for `authorize`/`can?`/`load_and_authorize_resource`. Use whichever is already
+  present. **If neither is present and the task needs authorization, ask which the team wants**
+  (Pundit and CanCanCan solve the same problem differently — don't default to one silently).
+- **Auth (login)**: check for `devise`, `has_secure_password`, or a custom token scheme already in
+  the app, and match it. Don't introduce a second auth mechanism alongside an existing one.
+- **Rate limiting**: check for `rack-attack` in `Gemfile`/`config/initializers`. If absent and the
+  task is a new public-facing endpoint, flag that rate limiting isn't set up rather than silently
+  skipping it — whether to add it is a call worth surfacing, not assuming.
+
+## Non-negotiable regardless of which specific gems are in use
+
+- **Strong parameters** on every controller write action — no `params.permit!`, no mass-assigning
+  a raw hash to `.new`/`.update`.
+- **Secrets**: Rails encrypted credentials or ENV vars — never commit `config/master.key`, never
+  hardcode API keys, regardless of how the rest of the app manages config.
+- **SQL injection**: parameterized queries / ActiveRecord query methods always — never
+  string-interpolate user input into `.where("... #{params[...]}")` or raw `execute`.
+- **Data exposure**: whatever the serialization layer is (see `02-api-design-standards.md`), it
+  must explicitly control which columns are exposed — never render a model with sensitive columns
+  (password_digest, tokens) without an explicit allow-list.
+- **CSRF**: `protect_from_forgery` for cookie-session-based controllers; token-authenticated JSON
+  APIs (`ActionController::API`) rely on the auth token instead — know which mode the controller
+  you're editing is actually in before assuming either way.
+- **Static analysis**: if `brakeman` is already in the project's CI, keep it passing on new code.
+  If it isn't set up, that's worth flagging on a security-sensitive change, not silently skipping.
+- HTTPS/secure cookies: match `config/environments/production.rb` if it already sets
+  `force_ssl`/cookie flags; don't change security config as a side effect of an unrelated task.

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/05-database-model-standards.md

@@ -0,0 +1,25 @@
+# Database & Model Standards (Rails)
+
+- **Migrations only** — never hand-edit `schema.rb`/`structure.sql` or run destructive changes
+  directly against a shared DB, regardless of project size. Every migration reversible where
+  possible.
+- **DB-level constraints**: match how strict the existing schema already is. If existing tables
+  consistently use `null: false`/unique indexes/FK constraints, keep that standard for new tables.
+  If the existing schema is looser, still add constraints for genuinely required/unique fields —
+  this one isn't a "match the existing laxness" case, since it's a correctness/data-integrity
+  issue, not a style choice.
+- **Index every foreign key** and every column used in a frequent `WHERE`/`ORDER BY`/`JOIN`.
+- **N+1 prevention**: use `includes`/`preload`/`eager_load` for any association accessed in a loop
+  or in the serialization layer. Check whether `bullet` is already in the Gemfile — if so, its
+  warnings should be treated as real; if not, this is still worth watching for regardless.
+- **Callbacks**: check how the existing models handle side effects (email sending, external API
+  calls) — if they're already in callbacks, that's the established (if not ideal) pattern; don't
+  silently "fix" that as part of an unrelated task. For genuinely new logic, prefer keeping side
+  effects out of callbacks and explicit in a service/controller, and mention the choice.
+- **Soft delete**: check for `discard`, `paranoia`, or a manual `deleted_at` column already in use.
+  If none exists and the task needs "deletion," ask whether soft or hard delete is wanted rather
+  than assuming — this has real product/compliance implications.
+- **Transactions** (`ActiveRecord::Base.transaction`) wrap any operation writing to more than one
+  table, independent of any other convention question.
+- Prefer `find_each`/`in_batches` over `.each` on large relations to avoid loading an entire table
+  into memory.

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/06-testing-standards.md

@@ -0,0 +1,26 @@
+# Testing Standards (Rails)
+
+## Detect the test framework and match it exactly
+
+Check for `spec/` (RSpec) vs `test/` (Minitest) — usually unambiguous. If somehow both exist,
+follow whichever the file you're adding tests near already uses; don't introduce the other
+framework into a directory that's consistently using one.
+
+- Match the existing fixture strategy (FactoryBot vs fixtures) — don't introduce FactoryBot into a
+  fixtures-based test suite (or vice versa) without flagging it as a bigger change.
+- Match whether the app uses request specs, controller specs, or Minitest functional/integration
+  tests for controller-level coverage — follow the existing style for consistency, even if a newer
+  convention exists (e.g. request specs over controller specs), unless asked to modernize it.
+
+## Rules that hold regardless of framework
+
+- New model logic (validations, scopes, non-trivial methods) gets a corresponding test — don't
+  re-test what Rails/ActiveRecord already guarantees.
+- New endpoints get at least: one happy-path test, one validation/error-path test, one
+  auth-failure test if the action is protected.
+- New service/business-logic objects get their own test file covering the success path and each
+  distinct failure mode.
+- Mock/stub external services (payment gateways, third-party APIs) — tests must not hit the real
+  network, regardless of the mocking library already in use (`webmock`, `vcr`, or hand-rolled).
+- System/browser-level tests (Capybara) are for critical user flows only — don't add one for every
+  CRUD screen; match how sparingly (or not) the existing suite already uses them.

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/07-new-component-checklist.md

@@ -0,0 +1,26 @@
+# Checklist: Before Creating Any New Model, Controller, or Service (Rails)
+
+1. **Look at the codebase first** — open one existing example of the thing you're about to create
+   (a similar controller/model/service) and mirror its structure, naming, and error-handling
+   shape. Don't start from a generic template if a real example already exists to copy from.
+2. **Confirm which layer this belongs in**, based on what this codebase actually has (model,
+   service, query object, form object) — don't introduce a layer the codebase doesn't already use
+   without flagging it as a new pattern.
+3. **Check for undetected architectural choices** before writing code that depends on one:
+   authorization library, serialization approach, pagination, background jobs, soft-delete
+   strategy. If genuinely undetected and it matters for this task, ask — see
+   `00-quick-scaffold.md` for the specific list.
+4. **Write the migration** (with appropriate DB-level constraints and indexes) before the model
+   code that depends on it.
+5. **Strong parameters + validation** before writing the controller action body.
+6. **Authorization**: add/update whatever authorization mechanism the codebase already uses; if
+   none exists and this action needs to be protected, ask before picking a library.
+7. **Error handling**: match the existing error-handling pattern; don't invent a new one for this
+   feature alone.
+8. **Write tests** matching the existing framework/style: happy-path + at least one failure path.
+9. **Update API docs** if the codebase already maintains them.
+10. **Run whatever lint/static-analysis tools are already configured** — no new offenses.
+11. **No secrets, no hardcoded config.**
+12. **Minimal diff**: touch only what this task requires — see `08-code-style-general.md` for the
+    restraint principle. Don't refactor unrelated code or add scaffolding for hypothetical future
+    needs in the same change.

package/standards/rails-standards/antigravity/.agents/skills/rails-standards/references/08-code-style-general.md

@@ -0,0 +1,47 @@
+# General Code Style Standards (Rails)
+
+## Match the codebase, don't impose a preference
+
+Before writing new code, look at one or two nearby existing files and match their formatting,
+naming conventions, and idioms — even where a "more standard" alternative exists. A style
+disagreement with the existing codebase is a conversation to have with the team, not something to
+silently fix inside an unrelated task.
+
+- Check whether Rubocop (or another linter) is already configured — if so, its config IS the style
+  guide; follow it rather than a generic external standard. If none is configured, standard Ruby
+  conventions (2-space indent, snake_case methods/variables, CamelCase classes) are a reasonable
+  default, and it's worth flagging that no linter is set up rather than assuming one exists.
+- If a genuinely new project has no tooling yet: for a real greenfield build, set up
+  Rubocop as part of initial scaffolding; for a quick prototype or when explicitly told not to
+  bother, don't force tooling — just say plainly it was skipped.
+- No business logic in views/templates.
+- Structured logging matching whatever the app already uses (`Rails.logger`, `semantic_logger`,
+  etc.) — no bare `puts`/`p` left in committed code regardless.
+- Commit message style: match the existing git history's convention (Conventional Commits or
+  otherwise) rather than assuming one.
+
+## Restraint — make the smallest correct change
+
+- **For a small/targeted change, write a small/targeted diff.** Fixing one validation, one bug, or
+  one endpoint should touch the lines that fix it — not the surrounding file, not "while I'm here"
+  refactors, not unrelated files.
+- **Don't pre-build for hypothetical future requirements.** No speculative service objects, config
+  options, or abstraction layers for a feature that wasn't asked for (YAGNI) — extract an
+  abstraction only once a real second use case exists.
+- **Don't scaffold more than was asked.** "Add a `cancel` action to `OrdersController`" means one
+  action, not a re-generation of the whole controller, a new serializer, and a new policy file
+  unless the task actually needs them.
+- **Prefer editing existing code over generating new files** when a small addition to an existing
+  service/model/controller does the job.
+
+## Comments
+
+- Comments explain **why**, not **what** — a comment repeating what the code already says is
+  noise (`# increment counter` above `counter += 1` is not acceptable).
+- Keep comments **short** — one line, plain language. If a comment needs a paragraph, the method
+  is probably too complex and should be simplified or split instead.
+- Only comment: non-obvious business rules, workarounds for a specific bug/gem quirk (link the
+  issue/ticket if one exists), or intentional deviations from the codebase's usual pattern.
+- Delete commented-out code — that's what git history is for.
+- Don't add a comment/docstring to every method by default — match the existing codebase's comment
+  density; if it's sparse, stay sparse; comment the exception, not the rule.

package/standards/rails-standards/claude-code/.claude/skills/rails-standards/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: rails-standards
+description: Standards for Ruby on Rails backend work that detect and match THIS codebase's existing conventions (auth library, serialization approach, project structure, error handling, tests) rather than assuming a generic stack, and ask a clarifying question when a real architectural choice can't be detected. Use this skill whenever creating, editing, or reviewing any Rails model, controller, service, migration, or API endpoint, or before scaffolding any new module/component, even if the user doesn't explicitly ask for "standards" or "best practices."
+---
+
+# Rails Standards
+
+This skill's job is to make new code look like it was written by the same person who wrote the
+rest of the codebase — not to impose a generic "senior architect" stack on top of it. Detecting
+and matching existing conventions is the primary behavior; the reference files below are fallback
+guidance for when no existing convention is detectable.
+
+## Detect → match → ask (do this before writing code, every time)
+
+1. **Graceful search, not a full scan.** Read `Gemfile`/`Gemfile.lock` once for the relevant gem
+   category. That's it for step 1 — don't grep the whole repo.
+2. Open **one** existing file of the same kind near where you're adding code (one controller, one
+   model, one spec) and mirror its structure, naming, error handling, and comment density.
+3. If Gemfile + the example agree, use that — it's detected, not assumed.
+4. **If nothing exists to detect from and the choice materially affects the code** (authorization
+   library, serialization approach, pagination, background jobs, soft-delete strategy, test
+   framework, rate limiting, API versioning) — **ask one question with the common options** rather
+   than silently defaulting to a specific gem.
+5. Never skip step 2 when the codebase is non-empty — overlooking existing code and writing from a
+   generic template is the failure mode this skill exists to prevent.
+
+## Token discipline — read this before opening any reference file
+
+- **New model / controller / service / endpoint** → after doing the detect-match-ask steps above,
+  read **only** `references/00-quick-scaffold.md` for anything not resolved by what you found.
+- **Deep dive on one specific concern** → read the one matching full reference file, not the
+  others.
+- **Full audit / reviewing an existing large PR** → the only case that justifies reading
+  multiple/all reference files.
+
+| Task involves...                          | Read                                          |
+|--------------------------------------------|------------------------------------------------|
+| Scaffolding anything new (default case)    | `references/00-quick-scaffold.md` **(start here)** |
+| Deep dive: overall app layout               | `references/01-project-structure.md`           |
+| Deep dive: routes/controllers/serializers   | `references/02-api-design-standards.md`        |
+| Deep dive: error handling/validation        | `references/03-error-handling-validation.md`   |
+| Deep dive: auth/security                    | `references/04-security-standards.md`          |
+| Deep dive: models/migrations/query objects  | `references/05-database-model-standards.md`    |
+| Deep dive: tests                            | `references/06-testing-standards.md`           |
+| Full pre-scaffold checklist (verbose form)  | `references/07-new-component-checklist.md`     |
+| Deep dive: style/restraint/comments         | `references/08-code-style-general.md`          |
+
+## Core non-negotiables (apply even without reading further)
+
+- Detect and match existing conventions before applying any generic default; ask rather than
+  assume when a real architectural choice isn't detectable.
+- No business logic in controllers or views; strong params on every write action.
+- Every error flows through whatever centralized error-handling pattern the codebase already has
+  (or a `rescue_from` chain if none exists — flagged as new).
+- **Restraint, always**: make the smallest correct change for the task asked. No speculative
+  abstractions, no unrelated refactors, no scaffolding beyond what's needed. Comments are short,
+  explain *why* not *what*, and only appear where the code isn't already self-evident.
+
+## Workflow for a new feature (token-efficient path)
+
+1. Do the detect → match → ask steps above.
+2. Read `references/00-quick-scaffold.md` for anything the detection step didn't resolve.
+3. Only pull in a full reference file if the quick-scaffold section on that topic isn't detailed
+   enough, or the task is a deep dive on one area.
+4. Write the smallest diff that satisfies the task; run whatever lint/static-analysis tools are
+   already configured before considering it done.

package/standards/rails-standards/claude-code/.claude/skills/rails-standards/references/00-quick-scaffold.md

@@ -0,0 +1,83 @@
+# Quick Scaffold Cheat Sheet — New Model / Controller / Service (Rails)
+
+Read this file first for "create/add a new X" tasks — it's the condensed version of the full pack.
+
+## 0. Understand before you write (always — this is the point of this skill)
+
+This skill exists to match how **this specific codebase** already writes code, not to impose a
+generic opinion or assume a from-scratch build. Before writing anything:
+
+1. **Graceful search, not a full scan.** Read `Gemfile`/`Gemfile.lock` once (one file) for the
+   relevant gem category (auth, serialization, pagination, jobs, testing).
+2. Open **one** existing file of the same kind, near where you're adding code (one existing
+   controller, one existing model, one existing spec). Mimic its structure, naming, error-handling
+   shape, and comment density. One representative example is enough — don't scan the whole `app/`
+   tree.
+3. If Gemfile + the example file agree on an approach, **use it, don't ask** — that's a detected
+   convention, not a guess.
+4. **If there's no existing example and the choice materially affects the code, ask one question
+   with the common options** — don't silently default to "the popular gem" as if it were a rule.
+5. Low-stakes style details (indentation, private-method order) — just mirror the nearest file, no
+   need to ask.
+
+### Ask, don't assume, when these aren't already evident in the codebase:
+- Authorization (Pundit / CanCanCan / custom / none)
+- Response/serialization approach (Blueprinter / ActiveModel::Serializer / jsonapi-rb / Jbuilder / plain `as_json`)
+- Pagination (Kaminari / Pagy / will_paginate / none needed)
+- Background jobs (Sidekiq / plain ActiveJob / Resque / none needed)
+- Soft delete vs hard delete, and which gem if soft
+- Test framework (RSpec / Minitest) — usually obvious from `spec/` vs `test/`, confirm if not
+- Rate limiting (rack-attack / none needed)
+- API versioning scheme, if this is the first versioned endpoint
+
+## 1. Layering (holds regardless of gem choices)
+
+model (persistence/validation) → form object (if the codebase uses one) → service/business logic
+(wherever it already lives) → query object (if in use) → controller (auth → authorize → delegate
+→ render) → whatever serialization approach was detected in step 0.
+
+## 2. API shape
+
+If endpoints already exist, copy the established response envelope / status-code pattern / error
+shape exactly, even over a "more standard" alternative — consistency wins. Only fall back to
+generic REST conventions if this is genuinely the first endpoint of its kind, and say so.
+
+## 3. Validation + errors
+
+Match the existing `rescue_from`/error-class pattern if one exists. If none exists yet, a central
+`rescue_from` chain with typed errors is a reasonable default to introduce — but flag that it's a
+new cross-cutting pattern, since it affects every controller.
+
+## 4. Security (non-negotiable regardless of which gems are chosen)
+
+Strong params on every write action. Parameterized queries only, never string-interpolated SQL.
+Secrets via Rails credentials/ENV, never hardcoded. Authorization checked using whichever library
+is detected (or ask, per step 0, if none is set up).
+
+## 5. Database/model
+
+New column/table → a migration with DB-level constraints + indexes on FKs and hot query columns.
+Avoid N+1 (`includes`/`preload`) on associations touched in a loop or the serialization layer.
+Multi-table writes wrapped in a transaction.
+
+## 6. Tests
+
+Match the existing test style (framework, factories vs fixtures) exactly. Minimum bar for new
+code: one happy-path test, one validation/error-path test, one auth-failure test if protected.
+
+## 7. Restraint (applies to every task, especially small ones)
+
+Make the smallest correct change. No unrelated refactors, no speculative abstractions, no
+scaffolding beyond what was asked. Comments are short, explain *why* not *what*, and only appear
+where the code isn't already self-evident.
+
+## 8. Before you call it done
+
+Whatever lint tool the codebase already uses, run it clean → no hardcoded secrets → pagination on
+new index actions if the codebase paginates elsewhere → N+1 checked → diff scoped to exactly this
+task.
+
+---
+Need more depth? `01-project-structure.md`, `02-api-design-standards.md`,
+`03-error-handling-validation.md`, `04-security-standards.md`, `05-database-model-standards.md`,
+`06-testing-standards.md`, `07-new-component-checklist.md`, `08-code-style-general.md`.

package/standards/rails-standards/claude-code/.claude/skills/rails-standards/references/01-project-structure.md

@@ -0,0 +1,44 @@
+# Project Structure Standards (Ruby on Rails)
+
+## Detect before you structure anything
+
+This codebase already has a structure — the job is to recognize it and extend it consistently,
+not to impose a textbook layout on top of it. Before adding a new folder or a new kind of class:
+
+1. Look at `app/` — which of these already exist: `services/`, `queries/`, `forms/`, `policies/`,
+   `serializers/`, `decorators/`? Whatever's there is the convention for this codebase.
+2. If a folder you'd normally reach for (e.g. `services/`) **doesn't exist yet** and the task is
+   small, that's a signal — either this codebase keeps that logic somewhere else (check a model or
+   controller for where similar logic lives), or it genuinely doesn't have this layer yet. If
+   introducing a new top-level pattern for the first time, say so plainly rather than silently
+   creating it, and ask if it's a big structural addition.
+3. Don't scan the entire `app/` tree to figure this out — `ls app/` plus opening one or two
+   existing files near where you're adding code is enough.
+
+## Common Rails layers, when they're already in use
+
+```
+app/
+  controllers/            # thin: auth -> authorize -> delegate -> render
+  models/                  # persistence + validations + associations
+  services/                # multi-step business logic, if this codebase uses the pattern
+  queries/                 # complex/reusable query objects, if in use
+  forms/                   # form objects for multi-model or non-persisted input, if in use
+  policies/                # authorization objects, matching whichever auth gem is detected
+  serializers/              # JSON shape, matching whichever serialization approach is detected
+  jobs/                    # background jobs, matching whichever adapter/gem is detected
+  lib/                      # framework-agnostic code with no Rails dependency
+```
+
+## Rules that hold regardless of which layers this codebase uses
+
+- **Controllers stay thin** no matter what: auth → authorize (if the app has an authorization
+  layer) → delegate to wherever business logic already lives → render. Multi-step business logic
+  doesn't belong inline in a controller action, whatever it's called in this codebase.
+- **Don't let one model absorb unrelated logic.** If a model file is already large and you're
+  about to add another unrelated method, look at how the codebase has handled that split before
+  (a concern? a PORO? a service?) and match it, rather than inventing a new extraction pattern.
+- **Concerns are for genuinely shared behavior** (used by 2+ classes already, or clearly about to
+  be). A concern used by exactly one class is unnecessary indirection — inline it instead.
+- **Namespace and version the API** the way the existing routes already do. If this is the first
+  API endpoint in the app, ask whether versioning is wanted before picking a scheme.

package/standards/rails-standards/claude-code/.claude/skills/rails-standards/references/02-api-design-standards.md

@@ -0,0 +1,46 @@
+# REST API Design Standards (Rails)
+
+## Follow the existing convention first
+
+If the app already has API endpoints, open one and copy its shape exactly — route style,
+namespacing, response envelope, status codes, error format. Consistency with the rest of the app
+matters more than matching a generic "best practice" that conflicts with it. Only fall back to the
+generic guidance below if this is genuinely the first endpoint of its kind, and mention that
+you're establishing a new convention.
+
+## Routing
+
+- Use `resources`/`resource` with explicit `only:`/`except:` — don't leave all 7 RESTful actions
+  open if only a few are used, whether or not the rest of the app does this consistently.
+- Nest one level max: `resources :orders do resources :items, only: [:index, :create] end`.
+- Namespace + version if the app already does (`Api::V1::...`); if there's no existing API and
+  this is the first one, ask whether versioning is wanted before picking a scheme.
+
+## Controllers
+
+- Auth → authorize (using whatever authorization approach is already in the codebase — see
+  `04-security-standards.md` for how to detect it) → delegate to wherever business logic already
+  lives → render. No inline multi-step `ActiveRecord` chains in the controller action itself.
+- Strong parameters are mandatory on every write action regardless of anything else detected.
+
+## Status codes & responses
+
+- `200`/`201`/`204` success, `400`/`422` validation, `401`/`403` auth, `404` not found, `429` rate
+  limited, `500` unhandled — these are stable regardless of gem choices.
+- **Response shape**: detect what the app already returns (check an existing controller/serializer).
+  If it already uses Blueprinter, `ActiveModel::Serializer`, `jsonapi-rb`, Jbuilder, or plain
+  `as_json`/`render json:` with a hand-built hash — match that, don't introduce a second approach.
+  If there's genuinely no existing pattern, ask which the team prefers before picking one; don't
+  assume a specific serializer gem.
+- Never call `.to_json` on a raw ActiveRecord object/relation regardless of which serialization
+  approach is chosen — that leaks DB columns either way.
+
+## Other requirements
+
+- **Pagination**: match the existing approach if list endpoints already paginate (Kaminari, Pagy,
+  will_paginate, manual). If there's no existing list endpoint to reference, ask before adding a
+  pagination gem — a small internal API may not need one.
+- **Filtering/sorting** via an explicit allow-listed param set — never pass raw `params` into
+  `.where`/`.order`, independent of which query pattern the app uses.
+- **API docs**: match whatever the app already uses (rswag/OpenAPI annotations, a hand-maintained
+  file, or none). If none exists, flag that rather than silently skipping documentation.

package/standards/rails-standards/claude-code/.claude/skills/rails-standards/references/03-error-handling-validation.md

@@ -0,0 +1,35 @@
+# Error Handling & Validation Standards (Rails)
+
+## Detect the existing pattern
+
+Check `ApplicationController` (or the relevant base controller) for existing `rescue_from`
+declarations, and check one or two model/service files for how validation failures are currently
+surfaced. Match that pattern. Only introduce a new centralized `rescue_from` chain if none exists
+— and note that you're adding a new cross-cutting pattern, since it affects every controller.
+
+## If there's an existing pattern, extend it
+
+```ruby
+# Example shape — only use this if the codebase doesn't already have something similar
+class Api::BaseController < ActionController::API
+  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+  rescue_from ActiveRecord::RecordInvalid,  with: :render_unprocessable
+end
+```
+
+- If custom domain error classes already exist (`ApplicationError` or similar), follow that
+  hierarchy for new errors. If none exist yet, a base `ApplicationError < StandardError` with
+  domain subclasses is a reasonable default to introduce — but call out that it's new.
+
+## Rules that hold regardless of the existing pattern
+
+- **No bare `rescue => e` that swallows errors silently.** If broad rescue is unavoidable (e.g.
+  around a third-party call), re-raise a typed error or log with full context.
+- Validation belongs on the model (persistence-level rules) or a form object (cross-model/
+  non-persisted input) — match whichever the codebase already uses for similar cases, rather than
+  hand-validating raw `params` in the controller.
+- `.save!`/`.update!` inside service-style objects so failures raise and get caught centrally,
+  matching whatever the surrounding code already does with bang vs non-bang methods.
+- Validation error responses return `422` with per-attribute detail
+  (`record.errors.full_messages` or similar) — the specific shape should match the response
+  envelope already established (see `02-api-design-standards.md`).

package/standards/rails-standards/claude-code/.claude/skills/rails-standards/references/04-security-standards.md

@@ -0,0 +1,32 @@
+# Security Standards (Rails)
+
+## Detect the existing security stack before adding anything
+
+- **Authorization**: check `Gemfile` for `pundit` or `cancancan`, and check an existing
+  controller for `authorize`/`can?`/`load_and_authorize_resource`. Use whichever is already
+  present. **If neither is present and the task needs authorization, ask which the team wants**
+  (Pundit and CanCanCan solve the same problem differently — don't default to one silently).
+- **Auth (login)**: check for `devise`, `has_secure_password`, or a custom token scheme already in
+  the app, and match it. Don't introduce a second auth mechanism alongside an existing one.
+- **Rate limiting**: check for `rack-attack` in `Gemfile`/`config/initializers`. If absent and the
+  task is a new public-facing endpoint, flag that rate limiting isn't set up rather than silently
+  skipping it — whether to add it is a call worth surfacing, not assuming.
+
+## Non-negotiable regardless of which specific gems are in use
+
+- **Strong parameters** on every controller write action — no `params.permit!`, no mass-assigning
+  a raw hash to `.new`/`.update`.
+- **Secrets**: Rails encrypted credentials or ENV vars — never commit `config/master.key`, never
+  hardcode API keys, regardless of how the rest of the app manages config.
+- **SQL injection**: parameterized queries / ActiveRecord query methods always — never
+  string-interpolate user input into `.where("... #{params[...]}")` or raw `execute`.
+- **Data exposure**: whatever the serialization layer is (see `02-api-design-standards.md`), it
+  must explicitly control which columns are exposed — never render a model with sensitive columns
+  (password_digest, tokens) without an explicit allow-list.
+- **CSRF**: `protect_from_forgery` for cookie-session-based controllers; token-authenticated JSON
+  APIs (`ActionController::API`) rely on the auth token instead — know which mode the controller
+  you're editing is actually in before assuming either way.
+- **Static analysis**: if `brakeman` is already in the project's CI, keep it passing on new code.
+  If it isn't set up, that's worth flagging on a security-sensitive change, not silently skipping.
+- HTTPS/secure cookies: match `config/environments/production.rb` if it already sets
+  `force_ssl`/cookie flags; don't change security config as a side effect of an unrelated task.

package/standards/rails-standards/claude-code/.claude/skills/rails-standards/references/05-database-model-standards.md

@@ -0,0 +1,25 @@
+# Database & Model Standards (Rails)
+
+- **Migrations only** — never hand-edit `schema.rb`/`structure.sql` or run destructive changes
+  directly against a shared DB, regardless of project size. Every migration reversible where
+  possible.
+- **DB-level constraints**: match how strict the existing schema already is. If existing tables
+  consistently use `null: false`/unique indexes/FK constraints, keep that standard for new tables.
+  If the existing schema is looser, still add constraints for genuinely required/unique fields —
+  this one isn't a "match the existing laxness" case, since it's a correctness/data-integrity
+  issue, not a style choice.
+- **Index every foreign key** and every column used in a frequent `WHERE`/`ORDER BY`/`JOIN`.
+- **N+1 prevention**: use `includes`/`preload`/`eager_load` for any association accessed in a loop
+  or in the serialization layer. Check whether `bullet` is already in the Gemfile — if so, its
+  warnings should be treated as real; if not, this is still worth watching for regardless.
+- **Callbacks**: check how the existing models handle side effects (email sending, external API
+  calls) — if they're already in callbacks, that's the established (if not ideal) pattern; don't
+  silently "fix" that as part of an unrelated task. For genuinely new logic, prefer keeping side
+  effects out of callbacks and explicit in a service/controller, and mention the choice.
+- **Soft delete**: check for `discard`, `paranoia`, or a manual `deleted_at` column already in use.
+  If none exists and the task needs "deletion," ask whether soft or hard delete is wanted rather
+  than assuming — this has real product/compliance implications.
+- **Transactions** (`ActiveRecord::Base.transaction`) wrap any operation writing to more than one
+  table, independent of any other convention question.
+- Prefer `find_each`/`in_batches` over `.each` on large relations to avoid loading an entire table
+  into memory.