@mkappelhof/agent-instructions 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @mkappelhof/agent-instructions

package/README.md

@@ -1,3 +1,34 @@
-# 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. Pair them with the `AGENTS.md` files shipped by the config packages in
+this repo, which describe the tool rules.
+
+| File | For |
+| --- | --- |
+| `base.md` | Every project: 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) |
+
+`react.md` and `astro.md` both tell agents to read `base.md` first, so you only need to reference
+the file for your project type.
+
+## 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,80 @@
+# Base — agent instructions
+
+Conventions that apply to every project type. `react.md` and `astro.md` build on this file. Where
+the project's own `AGENTS.md` says something different, the project wins.
+
+Tool rules (TypeScript, Biome, Stylelint) are described in the `AGENTS.md` of the matching
+`@mkappelhof/*` config package. Follow those as well.
+
+## 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/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@mkappelhof/agent-instructions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Shared instructions for AI coding agents working on React/Next.js and Astro projects",
+  "exports": {
+    "./base.md": "./base.md",
+    "./react.md": "./react.md",
+    "./astro.md": "./astro.md",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "base.md",
+    "react.md",
+    "astro.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"
+  ]
 }

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.