| name | standards |
| description | Standard skills and patterns an agent should apply when working in this codebase |
Standards skill
Context
This document defines the standards an agent must apply when reviewing or writing code in this project.
Core principles
- Solve the problem as stated — do not over-engineer or anticipate future requirements
- Follow existing patterns in the codebase before introducing new ones
- Verify work before marking a task complete
- Run project commands in Docker (
docker compose exec dev ...) or via VS Code tasks; do not run Node/NPM commands on the host
Reading code
- Read the full function and its callers before making changes
- Check for existing utilities before writing new ones
- Use
grep / search to find all usages of a symbol before renaming or removing it
Editor config
All files must comply with .editorconfig. When creating new files, verify compliance before committing — CI will fail on violations.
Writing code
- Match the style and conventions of the surrounding code
- All internal
import paths must include the .js extension
- All
import statements must be at the top of the file, after the @module JSDoc and before any function definitions
- Arrow functions must always use braces:
const fn = () => { return x }
- No inline comments unless the why is genuinely non-obvious
- JSDoc is required on all public functions — use
@param, @returns, and a description; controllers, seeds, and routes files are exempt from @module JSDoc
- The
@module tag's description text (the comment line above it) must exactly match the first line of the default export function's own JSDoc description. This is unrelated to naming/casing — see "Naming conventions" below for how the @module value and the function name are each derived; they are independent conventions and will not always correspond
- No
console.log() or console.dir() — CI will fail on these
- No error handling for scenarios that cannot happen
- No abstractions for a single use case
- Private functions must be ordered alphabetically by name
Naming conventions
- Directories, JavaScript files, and Nunjucks templates:
kebab-case (e.g. submit-application.njk)
- JavaScript files include type in file name (e.g.
delete-session.dal.js and view-search.service.js)
- Default export functions in
dal/, presenters/, services/, and validators/: camelCase of the full file name, including the type suffix (e.g. delete-session.dal.js exports deleteSessionDal, view-search.service.js exports viewSearchService). This satisfies Sonar's S3317 (export name must match file name) and S7726 (default exports must be named) at once, and avoids naming collisions with parameters or imports that a shorter name risks
- If including the suffix collides with an existing import or identifier in the file (rare), drop back to the shorter name instead — it is still
S3317-compliant
@module JSDoc tag value: PascalCase describing the file's purpose - this is also what other files typically use as the local name when importing it (e.g. import DeleteSessionDal from '...'). Whether it includes the type suffix (...Dal, ...Service, etc.) is a judgement call for readability at the import site, not a mechanical rule, so it will not always match the PascalCase form of the default export function's name above — the two conventions are independent- Route paths (URLs): lowercase with hyphens (e.g.
/submit-application)
- Environment variables:
UPPER_SNAKE_CASE (e.g. DATABASE_HOST)
Testing
See .agents/skills/testing/SKILL.md for full testing standards.
Database
- Migrations go in
db/migrations/
- Never modify an existing migration — always add a new one
- Run
npm run migrate:test to reset the test database after schema changes
Refactoring
- Refactor in a separate commit from behaviour changes
- Do not rename or restructure things incidentally while fixing bugs
Quality gates
Before completing any task:
- Lint checks pass
- No 'alanisms' identified
- Tests pass
- No
console.log, console.dir, describe.only, or it.only present
- No commented out code
- No unintended files changed
