create-standards 1.0.0

package/standards/rails-standards/shared-reference/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/shared-reference/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/shared-reference/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/shared-reference/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/shared-reference/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/shared-reference/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/shared-reference/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/shared-reference/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.