@mkappelhof/agent-instructions 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @mkappelhof/agent-instructions
+
+## 1.1.0
+
+### Minor Changes
+
+- 3c4c6b4: Add `nest.md` with general best-practice conventions for NestJS services (project structure, DI, DTOs/validation, error handling, config/logging, testing).
+
+### Patch Changes
+
+- 3c4c6b4: Make `base.md` a generic, standalone baseline instead of assuming it's always paired with this repo's other `@mkappelhof/*` config packages. Following a matching config package's `AGENTS.md` is now framed as conditional on the project actually using it, not assumed.
+
+## 1.0.1
+
+### Patch Changes
+
+- eb2577f: Add new configs

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# Shared agent instructions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Project-level instructions for AI coding agents, covering code structure and conventions rather
+than tool configuration. If the project also uses one of this repo's config packages (TypeScript,
+Biome, ESLint, Stylelint), pair these with the `AGENTS.md` it ships, which describes that tool's
+rules — but these files don't assume that pairing, and `base.md` works as generic baseline
+instructions on its own for a project that doesn't match any of the more specific files below.
+
+| File       | For                                                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| `base.md`  | Any project, any stack: verifying instead of assuming, workflow, git, imports, TypeScript, design tokens, versioning |
+| `react.md` | React and Next.js projects (components, contexts, i18next, SCSS modules, Vitest)                                     |
+| `astro.md` | Static Astro sites (rendering, styling, data, images)                                                                |
+| `nest.md`  | NestJS services (modules, DI, DTOs/validation, error handling, testing)                                              |
+
+`react.md`, `astro.md` and `nest.md` all tell agents to read `base.md` first, so you only need to
+reference the file for your project type. For a project that's none of these (a plain script,
+a different framework, etc.), reference `base.md` directly.
+
+## Installation
+
+```sh
+pnpm add -D @mkappelhof/agent-instructions
+```
+
+Reference the file for your project type from the `AGENTS.md` at the root of your project:
+
+```md
+# AGENTS.md
+
+## Conventions
+
+- Follow `node_modules/@mkappelhof/agent-instructions/react.md`
+```
+
+Put anything project-specific (architecture, extra commands, exceptions to the shared conventions)
+in your own `AGENTS.md`. The shared files tell agents that the project's own instructions take
+precedence.

package/astro.md

@@ -0,0 +1,34 @@
+# Astro — agent instructions
+
+Conventions for static Astro sites written in TypeScript and styled with SCSS. Everything in
+[`base.md`](./base.md) applies as well; read it first.
+
+The site ships static HTML/CSS with no client-side framework. Use small inline `<script>` tags only
+where genuinely needed (e.g. a mobile nav toggle).
+
+## Rendering
+
+- Keep `output: 'static'` in `astro.config.mjs`: no server rendering and no framework islands
+  (`@astrojs/react` etc.). Reach for an inline `<script>` before adding a framework.
+
+## Styling
+
+- Write styles in component-scoped `<style lang="scss">` blocks.
+- Import the design token stylesheet (see `base.md`) once, in the base layout.
+
+## Data
+
+- Keep content data in `src/data/` as typed TypeScript modules. Each data set (features, pricing,
+  FAQ, etc.) has a single source of truth there; pages render from it instead of repeating it.
+- Generate derived output such as `llms.txt` and JSON-LD structured data from the same data
+  modules, so they can't drift from what the pages show.
+- Values that come from outside the site (e.g. a product version or description from another
+  `package.json`) are read once in `astro.config.mjs` and exposed through `vite.define` constants.
+  Read them in the config file, because its `import.meta.url` stays reliable while app modules get
+  bundled and relocated. Never hardcode such values elsewhere.
+
+## Images
+
+- Keep images in `src/assets/` and render them with Astro's `<Image>` (or `<Picture>`) component
+  from `astro:assets` so they're optimized at build time. Never reference them as raw
+  `<img src>` paths.

package/base.md

@@ -0,0 +1,88 @@
+# Base — agent instructions
+
+My personal baseline conventions for any project I work on, regardless of stack and regardless of
+whether the project uses any other `@mkappelhof/*` package. `react.md`, `astro.md` and `nest.md`
+build on this file for their respective project types, but this file is also meant to stand alone
+as generic `AGENTS.md` content for projects that don't match one of those.
+
+This file is a starting point, not a mandate: where the project's own `AGENTS.md` (or anything the
+user says) differs from what's here, that project-specific instruction wins.
+
+If the project happens to use one of my shared `@mkappelhof/*` config packages (for TypeScript,
+linting, formatting, etc.), that package's own `AGENTS.md` describes the rules its tool enforces —
+follow those too. Don't assume one is in use, though; check the project's `package.json` and
+config files (`tsconfig.json`, `.eslintrc*`, `biome.json`, `.stylelintrc*`, ...) to see what
+tooling is actually there before applying tool-specific conventions from anywhere.
+
+## Don't assume, verify or ask
+
+- Base every claim and every change on what you have actually read: the code, the config, the
+  installed packages' docs, or the user's instructions. Do not invent files, functions, props,
+  scripts, config options, package APIs or CLI flags.
+- Before you use an API, component, helper or token, check that it exists and how it is used in
+  this project (search the codebase, read the type definitions or the package's docs in
+  `node_modules`). Your training data may describe a different version.
+- When the request is ambiguous, information is missing, or several reasonable interpretations
+  lead to different results, stop and ask the user a clarifying question instead of guessing.
+  Don't ask about things you can find out yourself by reading the code.
+- If you make an assumption anyway (e.g. for a small detail that doesn't block the work), state it
+  explicitly in your reply so the user can correct it.
+- Say "I don't know" or "I couldn't verify this" rather than presenting a guess as fact. Report
+  results honestly: if a check fails or a step was skipped, say so.
+- Stay within the scope of the request. Don't add features, refactors or dependencies that weren't
+  asked for; suggest them instead.
+
+## Working on a task
+
+- Check the project's `package.json` for the available scripts (`dev`, `build`, `test`, lint and
+  type-check scripts) instead of guessing commands.
+- A change is done when the type check, tests and linters pass for the files you changed.
+- Never run `git commit`, create a branch, or push, unless you are explicitly asked to. Leave
+  changes as uncommitted working-tree edits and let the user commit, branch and push themselves.
+
+## Imports
+
+- Use **path aliases** for cross-directory imports, never relative `../../` paths. Check
+  `compilerOptions.paths` in the project's `tsconfig.json` for the available aliases (e.g.
+  `@components/*`, `@helpers/*`, or `@/*`).
+
+## TypeScript
+
+- Declare all types with `type`; do not use `interface`. Export a type when it is shared.
+- Do not use double casts (`as unknown as T`) to silence TypeScript errors; narrow values to the
+  required type instead.
+- Constants belong in `src/constants/`, never inline in components. Define sets of options as a
+  `SCREAMING_SNAKE_CASE` object with `as const` and derive the type from it:
+
+  ```ts
+  // src/constants/sizes.ts
+  export const SIZES = {
+    SMALL: 'small',
+    MEDIUM: 'medium',
+    LARGE: 'large',
+  } as const;
+
+  export type Size = (typeof SIZES)[keyof typeof SIZES];
+  ```
+
+## Design tokens
+
+- Design tokens are CSS custom properties, defined once in a global stylesheet. Reference them with
+  `var()`:
+
+  ```scss
+  .root {
+    padding: var(--spacing-md);
+    color: var(--color-text-primary);
+    border-radius: var(--border-radius-sm);
+  }
+  ```
+
+- Do not use Sass variables (`$color-*`) or a `@use`d tokens module for design tokens.
+- Never hardcode colors or spacing values; always use a design token. If a token is missing, add it
+  to the token stylesheet instead of inlining a value.
+
+## Versioning
+
+- If the project uses [Changesets](https://github.com/changesets/changesets) (a `.changeset/`
+  folder exists), every PR must include a changeset describing the change and its semver bump.

package/nest.md

@@ -0,0 +1,53 @@
+# NestJS — agent instructions
+
+Conventions for NestJS services written in TypeScript. Everything in [`base.md`](./base.md)
+applies as well (its CSS/design-token sections just won't come up in a backend service); read it
+first.
+
+## Project structure
+
+- Organize by feature module under `src/<feature>/`, each with its own controller, service,
+  module and DTOs — the shape `nest g resource` / `nest g module|controller|service` produces.
+- One class per file, named `<name>.<type>.ts` (`users.controller.ts`, `users.service.ts`,
+  `users.module.ts`).
+- DTOs live in a `dto/` folder inside the feature module, one class per file
+  (`dto/create-user.dto.ts`).
+
+## Modules & dependency injection
+
+- Keep controllers thin: parse input, delegate to a service, shape the response. Business logic
+  belongs in services, not controllers.
+- Inject dependencies through constructor parameter properties
+  (`constructor(private readonly usersService: UsersService) {}`), not property injection or
+  manual `new`.
+- Depend on Nest's DI container for anything registered as a provider; don't import a service and
+  instantiate it yourself.
+
+## DTOs & validation
+
+- Validate every request body/query/param with a DTO class using `class-validator` decorators
+  (`@IsString()`, `@IsOptional()`, etc.), not manual checks in the controller.
+- Enable a global `ValidationPipe` (with `whitelist: true`) in `main.ts` instead of adding it
+  per-route.
+- Shape what a controller returns with a response DTO or `class-transformer`'s
+  `@Expose()`/`@Exclude()`, instead of returning entity/ORM objects straight to the client.
+
+## Error handling
+
+- Throw Nest's built-in HTTP exceptions (`NotFoundException`, `BadRequestException`, etc.) instead
+  of returning error objects or throwing a plain `Error`.
+- For error formatting that applies across many routes, use an `ExceptionFilter` instead of
+  repeating try/catch in every controller.
+
+## Configuration & logging
+
+- Read environment values through `@nestjs/config`'s `ConfigService`, not `process.env` scattered
+  through the codebase.
+- Log through Nest's built-in `Logger`, not `console.log`.
+
+## Testing
+
+- Build tests with `Test.createTestingModule` and override providers with mocks, rather than
+  instantiating classes by hand.
+- Co-locate unit tests with their source as `*.spec.ts`. Keep end-to-end tests that exercise the
+  HTTP layer in `test/` as `*.e2e-spec.ts`.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@mkappelhof/agent-instructions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Shared instructions for AI coding agents working on React/Next.js, Astro and NestJS projects",
+  "exports": {
+    "./base.md": "./base.md",
+    "./react.md": "./react.md",
+    "./astro.md": "./astro.md",
+    "./nest.md": "./nest.md",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "base.md",
+    "react.md",
+    "astro.md",
+    "nest.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "repository": "git@github.com:mkappelhof/frontend-tools.git",
+  "author": "Maurice Kappelhof <maurice@mauricekappelhof.nl>",
+  "scripts": {
+    "test": "echo 'no test step'"
+  },
+  "keywords": [
+    "agents",
+    "agents.md",
+    "ai",
+    "react",
+    "nextjs",
+    "astro",
+    "nestjs"
+  ]
 }

package/react.md

@@ -0,0 +1,131 @@
+# React / Next.js — agent instructions
+
+Conventions for React projects (Vite, Next.js or another bundler) written in TypeScript and styled
+with SCSS modules. Everything in [`base.md`](./base.md) applies as well; read it first.
+
+## Project structure
+
+- **`src/components/`** — Feature components, each co-located with its `.module.scss`.
+- **`src/helpers/`** — Pure utility functions. Every function lives in its own dedicated helper file.
+- **`src/contexts/`** — React context providers (`*.context.tsx`).
+- **`src/constants/`** — Constants and option sets.
+- **`src/interfaces/`** — Shared TypeScript types.
+- **`src/i18n/`** — Localization: `config.ts` initializes i18next, `locales/<locale>.json` holds
+  the nested translation keys.
+
+In a Next.js project the routes live in `src/app/`; keep route files thin and put reusable UI in
+`src/components/`.
+
+## Components
+
+- Components are named arrow-function exports typed as `FC<Props>`, never `function` declarations.
+- **One component per file.** Subcomponents get their own file.
+- Type DOM-wrapping components with `ComponentPropsWithoutRef<'element'>` and wrappers with
+  `PropsWithChildren<Props>`.
+- Destructure props in the parameter list instead of using `props.x`. Use default parameter values,
+  not `defaultProps` or `propTypes`.
+- Always render text through the project's `Text` component (e.g. `@components/text/text`); never
+  place raw strings in bare DOM elements such as `<span>` or `<p>`.
+- **Composition over configuration**: pass content as `children` rather than through content props
+  (`label`, `icon`, `text`).
+- **Compound components**: build multi-part components using composition, not props. Keep
+  subcomponents in an `elements/` folder and re-export them from the parent module (no
+  `elements/index.ts` barrel). The parent manages state and shares it with its subcomponents
+  through a context.
+
+  ```tsx
+  // Usage of src/components/tabs/tabs.tsx
+  <Tabs defaultValue="account">
+    <Tabs.List>
+      <Tabs.Tab value="account">{t('settings.account')}</Tabs.Tab>
+      <Tabs.Tab value="billing">{t('settings.billing')}</Tabs.Tab>
+    </Tabs.List>
+    <Tabs.Panel value="account">...</Tabs.Panel>
+    <Tabs.Panel value="billing">...</Tabs.Panel>
+  </Tabs>
+  ```
+
+### Naming
+
+- Boolean props start with `is` or `has`: `isOpen`, `hasError`.
+- `useState` pairs are named `[value, setValue]`.
+- Event handler props are named `onX`, and the handlers you pass are named `handleX`:
+  `onClick={handleClick}`.
+
+### JSX
+
+- Import `clsx` as `classnames`: `import classnames from 'clsx'`. Compose class names as
+  `classnames(css.root, className)`.
+- No useless braces: `variant="primary"`, not `variant={'primary'}`.
+- Self-close elements without children: `<Icon />`, `<div />`.
+- Only use a fragment (`<>…</>`) when you need to wrap several children.
+- Every element in a list needs a stable `key`. Do not use the array index if items can reorder.
+- Keep JSX nesting to 4 levels or fewer. Extract a component when it gets deeper.
+
+## Contexts
+
+Create all contexts in `src/contexts/` named `*.context.tsx`. A context file exports the context
+value type, the context, a dedicated provider component, and a `use*Context` consumer hook that
+throws when used outside its provider. Always consume a context through its hook, never with
+`useContext` directly. Memoize the value you pass to a provider with `useMemo`; never pass a new
+object or array literal.
+
+```tsx
+// src/contexts/tabs.context.tsx
+export type TabsContextValue = {
+  activeValue: string;
+  setActiveValue: (value: string) => void;
+};
+
+export const TabsContext = createContext<TabsContextValue | undefined>(undefined);
+
+export const TabsProvider: FC<PropsWithChildren<{ value: TabsContextValue }>> = ({ value, children }) => (
+  <TabsContext.Provider value={value}>{children}</TabsContext.Provider>
+);
+
+export const useTabsContext = (): TabsContextValue => {
+  const context = useContext(TabsContext);
+
+  if (!context) throw new Error('useTabsContext must be used within a TabsProvider');
+
+  return context;
+};
+```
+
+## Next.js
+
+- Components in `app/` are Server Components by default. Add `'use client'` only to the components
+  that need state, effects, browser APIs or context, and keep that boundary as low in the tree as
+  possible.
+- Context providers are client components; wrap them in a small `'use client'` providers component
+  and render it from the layout.
+- Use `next/link` for internal navigation, not a plain `<a href="/…">`.
+- Use `next/image` instead of `<img>`, and `next/script` instead of a raw `<script>` tag.
+- Load fonts with `next/font`, not `<link>` tags to font CDNs.
+- Set page metadata with the Metadata API (`export const metadata` / `generateMetadata`). Do not
+  import `next/head` or `next/document` in `app/`.
+
+## Localization
+
+- Never hardcode user-facing text (labels, placeholders, aria-labels, messages). Add a key to the
+  matching group in the locale file (e.g. `src/i18n/locales/en-US.json`) and render it with
+  `const { t } = useTranslation()` from `react-i18next`.
+- Interpolate values with `t('group.key', { name })`, matching `{{name}}` in the translation. Use
+  i18next `_one` / `_other` suffixed keys with `{ count }` for plurals.
+- Non-component code (helpers, constants) returns a `TranslationKey` instead of translated text, so
+  the component can translate it.
+
+## Styling
+
+- Use SCSS modules (`.module.scss`) co-located with each component.
+- Import the design token stylesheet (see `base.md`) once at the app root, e.g. in `main.tsx` or
+  the root `layout.tsx`.
+
+## Testing
+
+- Use **Vitest** with the JSDOM environment for unit tests.
+- Co-locate tests with their source as `*.spec.ts` or `*.spec.tsx`.
+- Every helper must have a unit test. Add or update the co-located `*.spec.ts` whenever you add or
+  change one.
+- Test pure helpers directly. Mock browser APIs and external dependencies at module boundaries with
+  Vitest mocks.