boilerplate

When changing API routes, auth, or env-dependent behavior, add or update the corresponding integration tests and keep the test file layout consistent.

When adding or changing files under infra/k8s/ or sync targets for k8s, know what Argo CD syncs and remind the user to push to Git so the cluster can sync.

Keeps tools/generate-data seeders and docs in sync when main or management DB schema or ORM entities change. Use when adding or changing tables/entities in packages/orm, packages/management-orm, or infra database migrations.

When changing DB schema or permission dimensions, consider predefined roles and bucket_role / role-related code.

Use when adding or changing environment variables, infra/env/classification YAML, scripts/env-classification, K8s env render, or local env generation.

Common patterns for the Boilerplate HTTP API (Express)

When adding or changing preconditions, cleanup steps, or env usage for local Docker Compose or local k3d, keep both in sync where they share resources (e.g. infra/config/local/*.env).

Documentation file naming for the Boilerplate repo. Use when creating or modifying docs, README, or markdown.

Where and how to save LLM plan files locally. Use when creating, saving, or completing plan sets (e.g. multi-phase plans). Aligns with Podverse monorepo convention.

The Boilerplate monorepo has exactly one README.md (at repo root). Use when adding index/overview docs or creating new directories so you do not add a second README.

How i18n translations work in the Boilerplate repo. Use when adding or editing translation keys, adding locales, or generating translations so you can do it reliably.

End implementation responses with scoped make-based screenshot report commands for web and management-web verification.

Global patterns for the Boilerplate repo (API + Next.js app). Use when starting work in the repo or when applying repo-wide code quality, structure, or plan/history conventions.

Keep import path casing identical to file/directory names so builds pass on Linux and in CI. Use when adding or changing relative imports, or when CI fails with "Cannot find module" for paths that work locally.

When layout, functionality, or conditions change in apps/web or apps/management-web, add or update the corresponding E2E (Playwright) test so page behavior stays covered.

E2E specs use verbose complete sentences and explicit post-navigation verification; report keeps redirect-to-login summary-only and hides only non-validating navigation screenshots.

Maintain E2E spec order for full reports and respect parameter order for specified runs.

Adds authorization matrix coverage to Playwright specs. Use when testing pages with role or ownership rules so tests assert visible, hidden, disabled, and forbidden action states.

Apply the thorough CRUD permission permutation test process to E2E specs. Use when adding or aligning tests for permission-gated pages (edit/detail/settings) so all actor × outcome permutations and key flows are covered.

When an E2E test verifies a specific element, pass it to the capture helper so the step screenshot is taken with that element vertically centered.

Enforces URL-state contract tests for sortable/filterable pages in Playwright. Use when pages support search, sort, filters, pagination, or tab query params.

When creating or implementing plans for features that touch api, management-api, web, or management-web, include the corresponding tests—integration tests for api/management-api and E2E tests for web/management-web.

LLM history tracking guidelines. Use when updating history files or starting new feature work.

Use a consistent tabbed layout on management-web edit pages when there are multiple distinct forms (e.g. profile vs password).

Use parent-prefix naming for nested resources so the schema and API make hierarchy explicit (e.g. bucket_messages_crud). Use when adding or naming DB columns, tables, permission fields, API/ORM types, or request/response fields for resources that are children of another resource.

Persist sort preferences in a cookie keyed by path (not resource ID); restore when URL has no sort params.

Ensure Tabs active state works with and without URL params by passing the canonical tab href as activeHref, not a URL with extra query params.

Default sort order by column type for sortable tables; use when adding or changing sortable tables or backend list endpoints.

Ensure tables that display list data support sortable columns; use TableWithSort or Table.SortableHeaderCell and follow table-sort-defaults.

Enforces a strict CRUD and UI-state matrix for Playwright tests in apps/web and apps/management-web. Use when adding or reviewing E2E specs for create/read/update/delete, validation, show/hide, enable/disable, and empty/loading/error branches.

Prefer reusable components and keep globals minimal. Use when adding layout, form, or UI that could be reused, or when adding styles to globals.scss.

Never use raw `<form>` in app code. Use Form or FormContainer from @boilerplate/ui.

On every page where a password can be set or updated, include the PasswordStrengthMeter component.

New and Edit pages in management-web should use breadcrumbs so users can see where they are and navigate back.

Do not keep unused props or variables. Remove them from types and call sites (or delete the variable) instead of using _unused or "intentionally unused" patterns. Use when adding or refactoring component props, function parameters, or local variables.

Ensure the entire focus indicator is visible for buttons and button-like focusable elements; use padding + reverse margin when layout must stay unchanged.

Use exactly one visible focus indicator per focusable element; when using the focus-ring mixin, do not also change border or add a second outline.

Avoid div and other element wrappers within pages that exist only to apply styles. Use when adding or reviewing page layout, spacing, or wrapper markup in apps (e.g. Next.js pages, React components).

Always show a loading spinner in a button when it triggers an async action (submit, save, delete, etc.).

In TypeORM query builder use entity property names (camelCase) for orderBy, not database column names (snake_case). Use when writing or editing createQueryBuilder().orderBy() in packages/orm or apps that use TypeORM.