create-standards 1.0.0

package/standards/nodejs-express-standards/cursor/.cursor/rules/01-project-structure.mdc

@@ -0,0 +1,38 @@
+---
+description: Project structure and layered architecture rules for this Node/Express codebase
+globs: src/**/*.js,src/**/*.ts
+alwaysApply: false
+---
+# Project Structure Standards (Node.js + Express)
+
+## Standard folder layout
+
+```
+src/
+  config/         # env loading + validation, db config, third-party config
+  routes/         # express.Router() definitions only — no logic
+  controllers/    # HTTP layer: parse req, call service, shape res
+  services/       # business logic, orchestration — framework-agnostic
+  repositories/    # data access layer (DB queries), one per model/table
+  models/         # ORM/schema definitions
+  validators/     # request schema validation (zod/joi/celebrate)
+  middlewares/    # auth, error handler, rate limit, logging
+  utils/          # pure helper functions
+  jobs/           # cron / queue workers
+  events/         # event emitters / pub-sub handlers
+  constants/       # enums, error codes, status strings
+app.js            # express app assembly (middleware + routes), NO app.listen()
+server.js         # imports app.js, calls app.listen(), handles graceful shutdown
+tests/
+  unit/
+  integration/
+```
+
+## Rules
+
+- **Layered architecture is mandatory**: `route → controller → service → repository → model`. A controller never talks to the DB directly, and a service never touches `req`/`res`.
+- Split `app.js` (the Express app object) from `server.js` (the process/listener) so the app can be imported into supertest without binding a port.
+- Config must be loaded and **validated at startup** (e.g. with `envalid`, `zod`, or `joi`) — fail fast if a required env var is missing, don't let it fail later at runtime.
+- No business logic in `routes/`. Routes only wire `path + method → middleware chain → controller`.
+- One repository per aggregate/model. Repositories are the only files allowed to import the ORM/query builder directly.
+- Barrel files (`index.js`) per folder are optional but if used, keep them to re-exports only — no logic.

package/standards/nodejs-express-standards/cursor/.cursor/rules/02-api-design.mdc

@@ -0,0 +1,46 @@
+---
+description: REST API design conventions — use when creating or editing routes/controllers
+globs: src/routes/**/*.js,src/controllers/**/*.js
+alwaysApply: false
+---
+# REST API Design Standards
+
+## Resource naming & routing
+
+- Use plural nouns for resources: `/users`, `/orders`, not `/user` or `/getUsers`.
+- Nest resources only one level deep: `/orders/:orderId/items`, avoid deeper nesting.
+- Version the API from day one: `/api/v1/...`. Never ship an unversioned public API.
+- Use HTTP verbs correctly, never verbs in the path:
+
+| Verb   | Path              | Action                  |
+|--------|-------------------|-------------------------|
+| GET    | /users            | list                    |
+| GET    | /users/:id        | read one                |
+| POST   | /users            | create                  |
+| PUT    | /users/:id        | full replace            |
+| PATCH  | /users/:id        | partial update          |
+| DELETE | /users/:id        | delete                  |
+
+## Status codes
+
+- `200` OK (read/update), `201` Created (with `Location` header), `204` No Content (delete/no body).
+- `400` validation error, `401` unauthenticated, `403` unauthorized, `404` not found, `409` conflict, `422` semantically invalid, `429` rate-limited, `500` unhandled server error.
+- Never return `200` with an error payload — the HTTP status must reflect the outcome.
+
+## Response envelope (consistent across all endpoints)
+
+```json
+// success
+{ "success": true, "data": { }, "meta": { "page": 1, "totalPages": 4 } }
+
+// error
+{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "email is required", "details": [] } }
+```
+
+## Other requirements
+
+- **Pagination** is required on every list endpoint (`?page=&limit=` or cursor-based `?cursor=`) — never return an unbounded array.
+- **Filtering/sorting** via query params (`?status=active&sort=-createdAt`), validated against an allow-list of fields (never pass raw query straight into a DB `WHERE`/`ORDER BY`).
+- **Idempotency**: `PUT`/`DELETE` must be idempotent. For `POST` on payment/order-creation style endpoints, support an `Idempotency-Key` header.
+- **Document every endpoint** with OpenAPI/Swagger (`swagger-jsdoc` or a maintained `openapi.yaml`) — a new endpoint is not done until it's documented.
+- Never expose internal DB IDs/structure verbatim if it leaks implementation details; DTOs/serializers shape what the client sees.

package/standards/nodejs-express-standards/cursor/.cursor/rules/03-error-handling-validation.mdc

@@ -0,0 +1,32 @@
+---
+description: Error handling and request validation conventions
+globs: src/middlewares/**/*.js,src/validators/**/*.js,src/controllers/**/*.js
+alwaysApply: false
+---
+# Error Handling & Validation Standards
+
+## Custom error class
+
+```js
+class AppError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true; // distinguishes expected errors from bugs
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+## Rules
+
+- **Never use raw `try/catch` scattered in controllers.** Wrap async route handlers with a `catchAsync`/`asyncHandler` utility that forwards rejected promises to `next(err)`.
+- **One centralized error-handling middleware**, registered last in `app.js`, that:
+  - Logs the error (with request id / correlation id).
+  - Returns the standard error envelope.
+  - Hides stack traces and internal messages in production (`isOperational === false` → generic "Something went wrong").
+- **Validate every request at the boundary**, before it reaches the controller body — use a schema library (`zod`, `joi`, or `celebrate`) as route middleware, not manual `if` checks sprinkled through the controller.
+- Validation errors return `400`/`422` with a `details` array listing each failing field.
+- Distinguish **operational errors** (bad input, not found, auth failure — expected, safe to show a message) from **programmer errors** (bugs — log, alert, return generic 500).
+- Async code must never produce an unhandled promise rejection — catch at the boundary, always.

package/standards/nodejs-express-standards/cursor/.cursor/rules/04-security.mdc

@@ -0,0 +1,22 @@
+---
+description: Security defaults required on every Express service — auth, secrets, rate limiting, sanitization
+globs:
+alwaysApply: true
+---
+# Security Standards
+
+Apply all of these by default on every new Express service — don't wait to be asked:
+
+- **Helmet**: `app.use(helmet())` for secure headers (CSP, HSTS, X-Frame-Options, etc.) — configure CSP explicitly rather than leaving it wide open.
+- **CORS**: explicit origin allow-list via the `cors` package, never `origin: '*'` on an authenticated API.
+- **Rate limiting**: `express-rate-limit` (or a Redis-backed store in multi-instance deployments) on all public endpoints, stricter limits on auth endpoints (`/login`, `/register`, `/forgot-password`).
+- **Input sanitization**: strip/escape untrusted input against NoSQL/SQL injection and XSS (`express-mongo-sanitize`, parameterized queries/ORM query builders — never string-concatenate SQL).
+- **AuthN/AuthZ**:
+  - Short-lived JWT access tokens + refresh token rotation, or session cookies with `httpOnly`, `secure`, `sameSite`.
+  - Passwords hashed with `bcrypt`/`argon2`, never stored or logged in plaintext.
+  - Role/permission checks live in middleware, applied per-route, not scattered inside controller `if` statements.
+- **Secrets**: only via environment variables / a secrets manager. Never commit `.env`, never hardcode API keys or DB credentials.
+- **Request limits**: `express.json({ limit: '10kb' })` (or an appropriate cap) to prevent payload-based DoS.
+- **Dependency hygiene**: run `npm audit` (or Snyk/Dependabot) as part of CI; block merges on high/critical vulnerabilities.
+- **HTTPS only** in production; redirect HTTP → HTTPS at the load balancer/proxy layer.
+- Never leak stack traces, internal file paths, or library versions in API responses or headers.

package/standards/nodejs-express-standards/cursor/.cursor/rules/05-database-models.mdc

@@ -0,0 +1,15 @@
+---
+description: Database, ORM, and model conventions — use when creating or editing models/repositories/migrations
+globs: src/models/**/*.js,src/repositories/**/*.js,migrations/**/*.js
+alwaysApply: false
+---
+# Database & Model Standards
+
+- **Repository pattern**: all DB queries live in `repositories/`, never directly inside services or controllers. Services call repository methods; they don't know it's Postgres/Mongo/etc.
+- **Migrations are mandatory** for schema changes (e.g. `knex`, `sequelize-cli`, `prisma migrate`, `typeorm migration`). Never use `sync({ alter: true })` or manual schema edits against a shared/production DB.
+- Every table/collection gets `createdAt` and `updatedAt` timestamps by default.
+- Prefer **soft deletes** (`deletedAt` column + default query scope excluding it) over hard deletes for user-facing/business-critical records; hard-delete only where there's a clear compliance/retention reason.
+- Index every foreign key and every column used in a frequent `WHERE`/`sort` — check the query plan (`EXPLAIN`) for anything added to a hot path.
+- **Transactions** wrap any operation that writes to more than one table/collection, so a partial failure can't leave data inconsistent.
+- Naming: `snake_case` for DB columns/tables, `camelCase` in JS — handle the mapping in the ORM config, don't hand-convert per query.
+- Never return raw ORM model instances straight from a controller — map to a DTO/serializer so DB shape and API shape can evolve independently.

package/standards/nodejs-express-standards/cursor/.cursor/rules/06-testing.mdc

@@ -0,0 +1,15 @@
+---
+description: Testing requirements — use when writing or reviewing tests
+globs: tests/**/*.js,**/*.test.js,**/*.spec.js
+alwaysApply: false
+---
+# Testing Standards
+
+- **Unit tests** (Jest/Vitest) for every service function — mock the repository layer, test business logic in isolation.
+- **Integration tests** (Supertest against the exported `app.js`, not a running server) for every route — exercise the real middleware chain, validation, and error handler.
+- Use a dedicated test database (or transactional rollback per test) — tests must never touch dev/prod data, and must be safely re-runnable/parallelizable.
+- Follow **Arrange–Act–Assert** structure in every test; one logical assertion focus per test case.
+- Mock external services/network calls (payment providers, email, third-party APIs) — tests must not depend on network access.
+- Minimum coverage threshold: **80%** on services and controllers, enforced in CI (fail the build below threshold).
+- Every new endpoint or model ships with at least: one happy-path integration test, one validation-failure test, one auth-failure test (if protected).
+- CI must run lint → unit → integration → coverage gate, in that order, before a PR can merge.

package/standards/nodejs-express-standards/cursor/.cursor/rules/07-new-component-checklist.mdc

@@ -0,0 +1,21 @@
+---
+description: Manual checklist — invoke with @07-new-component-checklist before scaffolding any new model, route, or component
+globs:
+alwaysApply: false
+---
+# Checklist: Before Creating Any New Model, Route, or Component
+
+Run through this before writing code for a new feature — this is what a senior architect reviews for in a PR:
+
+1. **Check for an existing pattern first.** Look at a similar existing model/route/service in the codebase and follow its shape — don't introduce a new pattern for something that already has one.
+2. **Confirm the layer boundaries**: route (wiring only) → validator (schema) → controller (HTTP glue) → service (logic) → repository (DB) → model. No shortcuts (e.g. controller querying the DB directly).
+3. **Write the validation schema** for every input (body/params/query) before writing the controller.
+4. **Define the DB migration** (not a live schema edit) if a new table/column is needed, with indexes on any FK/frequently-queried column.
+5. **Handle errors explicitly**: use `AppError`/`catchAsync`, no bare `try/catch` with silent `console.log`.
+6. **Add authorization checks** if the resource is user/role-scoped — don't rely on the client to hide UI for unauthorized actions.
+7. **Write tests**: at minimum one integration test (happy path) and one validation/error-path test.
+8. **Update API documentation** (OpenAPI/Swagger) for any new or changed endpoint.
+9. **Run lint + format** (ESLint + Prettier) — no new lint warnings introduced.
+10. **No secrets, no hardcoded config** — anything environment-specific goes through `config/`.
+11. **Consider pagination/rate-limits** if it's a list endpoint or public-facing.
+12. Keep the diff focused — one feature/concern per PR/commit.

package/standards/nodejs-express-standards/cursor/.cursor/rules/08-code-style.mdc

@@ -0,0 +1,14 @@
+---
+description: General code style, lint, logging, and commit conventions
+globs:
+alwaysApply: true
+---
+# General Code Style Standards
+
+- ESLint (Airbnb-base or `eslint-config-standard`) + Prettier, enforced via a pre-commit hook (`husky` + `lint-staged`) and in CI — not just "run it locally sometimes."
+- `async/await` everywhere; no mixing with raw `.then()` chains or callback-style APIs in new code.
+- No `console.log` in committed code — use a structured logger (`pino` or `winston`) with log levels, and include a request/correlation id in every log line.
+- One export/responsibility per file; avoid god-files that mix routing, business logic, and DB access.
+- Environment-based configuration only (`dotenv` + a validated config schema) — never branch behavior on `NODE_ENV` scattered through business logic; centralize environment differences in `config/`.
+- Commit messages follow Conventional Commits (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`) so history and changelogs stay meaningful.
+- Prefer explicit, readable code over clever one-liners — this codebase is read far more often than it's written.

package/standards/nodejs-express-standards/shared-reference/01-project-structure.md

@@ -0,0 +1,33 @@
+# Project Structure Standards (Node.js + Express)
+
+## Standard folder layout
+
+```
+src/
+  config/         # env loading + validation, db config, third-party config
+  routes/         # express.Router() definitions only — no logic
+  controllers/    # HTTP layer: parse req, call service, shape res
+  services/       # business logic, orchestration — framework-agnostic
+  repositories/    # data access layer (DB queries), one per model/table
+  models/         # ORM/schema definitions
+  validators/     # request schema validation (zod/joi/celebrate)
+  middlewares/    # auth, error handler, rate limit, logging
+  utils/          # pure helper functions
+  jobs/           # cron / queue workers
+  events/         # event emitters / pub-sub handlers
+  constants/       # enums, error codes, status strings
+app.js            # express app assembly (middleware + routes), NO app.listen()
+server.js         # imports app.js, calls app.listen(), handles graceful shutdown
+tests/
+  unit/
+  integration/
+```
+
+## Rules
+
+- **Layered architecture is mandatory**: `route → controller → service → repository → model`. A controller never talks to the DB directly, and a service never touches `req`/`res`.
+- Split `app.js` (the Express app object) from `server.js` (the process/listener) so the app can be imported into supertest without binding a port.
+- Config must be loaded and **validated at startup** (e.g. with `envalid`, `zod`, or `joi`) — fail fast if a required env var is missing, don't let it fail later at runtime.
+- No business logic in `routes/`. Routes only wire `path + method → middleware chain → controller`.
+- One repository per aggregate/model. Repositories are the only files allowed to import the ORM/query builder directly.
+- Barrel files (`index.js`) per folder are optional but if used, keep them to re-exports only — no logic.

package/standards/nodejs-express-standards/shared-reference/02-api-design-standards.md

@@ -0,0 +1,41 @@
+# REST API Design Standards
+
+## Resource naming & routing
+
+- Use plural nouns for resources: `/users`, `/orders`, not `/user` or `/getUsers`.
+- Nest resources only one level deep: `/orders/:orderId/items`, avoid deeper nesting.
+- Version the API from day one: `/api/v1/...`. Never ship an unversioned public API.
+- Use HTTP verbs correctly, never verbs in the path:
+
+| Verb   | Path              | Action                  |
+|--------|-------------------|-------------------------|
+| GET    | /users            | list                    |
+| GET    | /users/:id        | read one                |
+| POST   | /users            | create                  |
+| PUT    | /users/:id        | full replace            |
+| PATCH  | /users/:id        | partial update          |
+| DELETE | /users/:id        | delete                  |
+
+## Status codes
+
+- `200` OK (read/update), `201` Created (with `Location` header), `204` No Content (delete/no body).
+- `400` validation error, `401` unauthenticated, `403` unauthorized, `404` not found, `409` conflict, `422` semantically invalid, `429` rate-limited, `500` unhandled server error.
+- Never return `200` with an error payload — the HTTP status must reflect the outcome.
+
+## Response envelope (consistent across all endpoints)
+
+```json
+// success
+{ "success": true, "data": { }, "meta": { "page": 1, "totalPages": 4 } }
+
+// error
+{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "email is required", "details": [] } }
+```
+
+## Other requirements
+
+- **Pagination** is required on every list endpoint (`?page=&limit=` or cursor-based `?cursor=`) — never return an unbounded array.
+- **Filtering/sorting** via query params (`?status=active&sort=-createdAt`), validated against an allow-list of fields (never pass raw query straight into a DB `WHERE`/`ORDER BY`).
+- **Idempotency**: `PUT`/`DELETE` must be idempotent. For `POST` on payment/order-creation style endpoints, support an `Idempotency-Key` header.
+- **Document every endpoint** with OpenAPI/Swagger (`swagger-jsdoc` or a maintained `openapi.yaml`) — a new endpoint is not done until it's documented.
+- Never expose internal DB IDs/structure verbatim if it leaks implementation details; DTOs/serializers shape what the client sees.

package/standards/nodejs-express-standards/shared-reference/03-error-handling-validation.md

@@ -0,0 +1,27 @@
+# Error Handling & Validation Standards
+
+## Custom error class
+
+```js
+class AppError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true; // distinguishes expected errors from bugs
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+## Rules
+
+- **Never use raw `try/catch` scattered in controllers.** Wrap async route handlers with a `catchAsync`/`asyncHandler` utility that forwards rejected promises to `next(err)`.
+- **One centralized error-handling middleware**, registered last in `app.js`, that:
+  - Logs the error (with request id / correlation id).
+  - Returns the standard error envelope.
+  - Hides stack traces and internal messages in production (`isOperational === false` → generic "Something went wrong").
+- **Validate every request at the boundary**, before it reaches the controller body — use a schema library (`zod`, `joi`, or `celebrate`) as route middleware, not manual `if` checks sprinkled through the controller.
+- Validation errors return `400`/`422` with a `details` array listing each failing field.
+- Distinguish **operational errors** (bad input, not found, auth failure — expected, safe to show a message) from **programmer errors** (bugs — log, alert, return generic 500).
+- Async code must never produce an unhandled promise rejection — catch at the boundary, always.

package/standards/nodejs-express-standards/shared-reference/04-security-standards.md

@@ -0,0 +1,17 @@
+# Security Standards
+
+Apply all of these by default on every new Express service — don't wait to be asked:
+
+- **Helmet**: `app.use(helmet())` for secure headers (CSP, HSTS, X-Frame-Options, etc.) — configure CSP explicitly rather than leaving it wide open.
+- **CORS**: explicit origin allow-list via the `cors` package, never `origin: '*'` on an authenticated API.
+- **Rate limiting**: `express-rate-limit` (or a Redis-backed store in multi-instance deployments) on all public endpoints, stricter limits on auth endpoints (`/login`, `/register`, `/forgot-password`).
+- **Input sanitization**: strip/escape untrusted input against NoSQL/SQL injection and XSS (`express-mongo-sanitize`, parameterized queries/ORM query builders — never string-concatenate SQL).
+- **AuthN/AuthZ**:
+  - Short-lived JWT access tokens + refresh token rotation, or session cookies with `httpOnly`, `secure`, `sameSite`.
+  - Passwords hashed with `bcrypt`/`argon2`, never stored or logged in plaintext.
+  - Role/permission checks live in middleware, applied per-route, not scattered inside controller `if` statements.
+- **Secrets**: only via environment variables / a secrets manager. Never commit `.env`, never hardcode API keys or DB credentials.
+- **Request limits**: `express.json({ limit: '10kb' })` (or an appropriate cap) to prevent payload-based DoS.
+- **Dependency hygiene**: run `npm audit` (or Snyk/Dependabot) as part of CI; block merges on high/critical vulnerabilities.
+- **HTTPS only** in production; redirect HTTP → HTTPS at the load balancer/proxy layer.
+- Never leak stack traces, internal file paths, or library versions in API responses or headers.

package/standards/nodejs-express-standards/shared-reference/05-database-model-standards.md

@@ -0,0 +1,10 @@
+# Database & Model Standards
+
+- **Repository pattern**: all DB queries live in `repositories/`, never directly inside services or controllers. Services call repository methods; they don't know it's Postgres/Mongo/etc.
+- **Migrations are mandatory** for schema changes (e.g. `knex`, `sequelize-cli`, `prisma migrate`, `typeorm migration`). Never use `sync({ alter: true })` or manual schema edits against a shared/production DB.
+- Every table/collection gets `createdAt` and `updatedAt` timestamps by default.
+- Prefer **soft deletes** (`deletedAt` column + default query scope excluding it) over hard deletes for user-facing/business-critical records; hard-delete only where there's a clear compliance/retention reason.
+- Index every foreign key and every column used in a frequent `WHERE`/`sort` — check the query plan (`EXPLAIN`) for anything added to a hot path.
+- **Transactions** wrap any operation that writes to more than one table/collection, so a partial failure can't leave data inconsistent.
+- Naming: `snake_case` for DB columns/tables, `camelCase` in JS — handle the mapping in the ORM config, don't hand-convert per query.
+- Never return raw ORM model instances straight from a controller — map to a DTO/serializer so DB shape and API shape can evolve independently.

package/standards/nodejs-express-standards/shared-reference/06-testing-standards.md

@@ -0,0 +1,10 @@
+# Testing Standards
+
+- **Unit tests** (Jest/Vitest) for every service function — mock the repository layer, test business logic in isolation.
+- **Integration tests** (Supertest against the exported `app.js`, not a running server) for every route — exercise the real middleware chain, validation, and error handler.
+- Use a dedicated test database (or transactional rollback per test) — tests must never touch dev/prod data, and must be safely re-runnable/parallelizable.
+- Follow **Arrange–Act–Assert** structure in every test; one logical assertion focus per test case.
+- Mock external services/network calls (payment providers, email, third-party APIs) — tests must not depend on network access.
+- Minimum coverage threshold: **80%** on services and controllers, enforced in CI (fail the build below threshold).
+- Every new endpoint or model ships with at least: one happy-path integration test, one validation-failure test, one auth-failure test (if protected).
+- CI must run lint → unit → integration → coverage gate, in that order, before a PR can merge.

package/standards/nodejs-express-standards/shared-reference/07-new-component-checklist.md

@@ -0,0 +1,16 @@
+# Checklist: Before Creating Any New Model, Route, or Component
+
+Run through this before writing code for a new feature — this is what a senior architect reviews for in a PR:
+
+1. **Check for an existing pattern first.** Look at a similar existing model/route/service in the codebase and follow its shape — don't introduce a new pattern for something that already has one.
+2. **Confirm the layer boundaries**: route (wiring only) → validator (schema) → controller (HTTP glue) → service (logic) → repository (DB) → model. No shortcuts (e.g. controller querying the DB directly).
+3. **Write the validation schema** for every input (body/params/query) before writing the controller.
+4. **Define the DB migration** (not a live schema edit) if a new table/column is needed, with indexes on any FK/frequently-queried column.
+5. **Handle errors explicitly**: use `AppError`/`catchAsync`, no bare `try/catch` with silent `console.log`.
+6. **Add authorization checks** if the resource is user/role-scoped — don't rely on the client to hide UI for unauthorized actions.
+7. **Write tests**: at minimum one integration test (happy path) and one validation/error-path test.
+8. **Update API documentation** (OpenAPI/Swagger) for any new or changed endpoint.
+9. **Run lint + format** (ESLint + Prettier) — no new lint warnings introduced.
+10. **No secrets, no hardcoded config** — anything environment-specific goes through `config/`.
+11. **Consider pagination/rate-limits** if it's a list endpoint or public-facing.
+12. Keep the diff focused — one feature/concern per PR/commit.

package/standards/nodejs-express-standards/shared-reference/08-code-style-general.md

@@ -0,0 +1,8 @@
+# General Code Style Standards
+
+- `async/await` everywhere; no mixing with raw `.then()` chains or callback-style APIs in new code.
+- No `console.log` in committed code — use a structured logger (`pino` or `winston`) with log levels, and include a request/correlation id in every log line.
+- One export/responsibility per file; avoid god-files that mix routing, business logic, and DB access.
+- Environment-based configuration only (`dotenv` + a validated config schema) — never branch behavior on `NODE_ENV` scattered through business logic; centralize environment differences in `config/`.
+- Commit messages follow Conventional Commits (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`) so history and changelogs stay meaningful.
+- Prefer explicit, readable code over clever one-liners — this codebase is read far more often than it's written.

package/standards/rails-standards/README.md

@@ -0,0 +1,86 @@
+# Ruby on Rails Standards — Skills Pack
+
+Standards for professional Rails backend work, built around one core idea: **match this specific
+codebase's existing conventions instead of assuming a generic stack.** It's designed for editing
+and extending existing Rails apps as much as for greenfield work — most real tasks are the former.
+
+## What's inside
+
+- **`shared-reference/`** — the master content: one condensed cheat sheet (`00-quick-scaffold.md`)
+  plus 8 full topic files. Source of truth; the other three folders repackage this into each
+  tool's native format.
+- **`cursor/.cursor/rules/`** — Cursor `.mdc` rule files.
+- **`claude-code/.claude/skills/rails-standards/`** — a Claude Code Skill (`SKILL.md` + `references/`).
+- **`antigravity/.agents/skills/rails-standards/`** — an Antigravity Skill, same `SKILL.md` format.
+
+## Detect → match → ask, not "use Pundit / use Blueprinter"
+
+Earlier drafts of this pack hard-coded specific gems (Pundit for auth, Blueprinter for
+serialization, etc.), which is wrong for a codebase that already made a different choice — plenty
+of real apps use CanCanCan, jsonapi-rb, Jbuilder, or something custom. This version doesn't assume:
+
+1. **Graceful search, not a full scan.** Before writing anything, read `Gemfile`/`Gemfile.lock`
+   once, and open **one** existing file of the same kind near where you're adding code (one
+   controller, one model, one spec). That's enough to detect the convention — no need to scan the
+   whole `app/` tree.
+2. **If a convention is detectable, follow it, no need to ask** — Gemfile + one real example
+   agreeing is a detected fact, not a guess.
+3. **If a real architectural choice isn't detectable and matters for the task, ask a single
+   question with the common options** instead of silently picking one. The trigger list (in
+   `00-quick-scaffold.md` and `SKILL.md`) covers: authorization library, serialization approach,
+   pagination, background jobs, soft-delete strategy, test framework, rate limiting, API
+   versioning.
+4. **Never skip looking at existing code when the codebase is non-empty.** Writing from a generic
+   template while ignoring what's already there is the specific failure mode this pack is built to
+   prevent.
+
+Every reference file (`01`–`08`) follows this same pattern: hold the things that are genuinely
+non-negotiable regardless of gem choice (strong params, parameterized queries, migrations over
+schema edits), and explicitly defer everything else to "detect it / match it / ask if it's not
+there."
+
+## Built to minimize token usage during scaffolding
+
+Same three-layer design used throughout this pack:
+
+1. **A tiny always-on baseline** (~200 words) — the detect/match/ask instruction, restraint
+   principle, and layering, present in every request.
+2. **One condensed cheat sheet** (`00-quick-scaffold.md`) — the default file for scaffolding
+   something new, instead of loading several full references.
+3. **Full topic references** (`01`–`08`), scoped to load only when actually relevant.
+
+## Built to prevent AI over-generation on small changes
+
+- No unrelated refactors "while I'm here," no speculative abstractions for requirements that
+  weren't asked for (YAGNI), no scaffolding beyond what the task needs.
+- Prefer a small edit to an existing file over generating a new file/class to avoid it.
+- **Comments**: short, explain *why* not *what*, only where the code isn't already self-evident,
+  matched to the existing codebase's comment density rather than a fixed rule of "comment
+  everything."
+
+## How to install per tool
+
+### Cursor
+Copy `cursor/.cursor/` into your project root → `your-project/.cursor/rules/*.mdc`.
+- `00-always-on.mdc` is the only always-applied rule (~200 words).
+- `01`, `02`, `03`, `05`, `06` auto-attach based on the file glob you're editing.
+- `04-security.mdc` and `08-code-style.mdc` are full detail, loaded on request.
+- `09-quick-scaffold.mdc` is the one to reach for when creating something new.
+- `07-new-component-checklist.mdc` is the fuller, manual-only checklist — `@07-new-component-checklist`.
+
+### Claude Code
+Copy `claude-code/.claude/` into your project root (or `~/.claude/` for global) →
+`your-project/.claude/skills/rails-standards/SKILL.md`. Discovered automatically, or invoke
+explicitly: *"Follow the rails-standards skill — check how we already handle authorization before
+adding this."*
+
+### Antigravity
+Copy `antigravity/.agents/` into your project root (or `~/.gemini/config/skills/` for global) →
+`your-project/.agents/skills/rails-standards/SKILL.md`. Same behavior as Claude Code above; check
+with `/skills` if unsure it loaded.
+
+## Editing the standards
+
+Treat `shared-reference/` as the source of truth. If you update a rule there, copy the change into
+the corresponding `cursor/*.mdc` file and into both `references/` copies under `claude-code/` and
+`antigravity/` so all three tools stay in sync.

package/standards/rails-standards/antigravity/.agents/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/antigravity/.agents/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`.