@activatus/code-standards 3.2.1 → 3.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -52,6 +52,8 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
52
52
 
53
53
  Optional, and recommended when Stages 4 to 6 will move a lot of code. Set up the [regression check](/docs/Guides/regression-checks) and take its baseline from the **live production site**, before anything changes. Every later stage must pass it unchanged.
54
54
 
55
+ **Take the baseline first, then move one kind of thing at a time.** The constants moves (Stage 4) and the folder moves (Stage 5a) are separate steps, each followed by a full regression run. When a run fails, only one kind of move can have caused it.
56
+
55
57
  ## Stage 1 — Formatting
56
58
 
57
59
  Applies setup standards 7, 9 and 10. Three commits, in this order:
@@ -181,8 +183,11 @@ Applies setup standard 12.1. Move every link into `r`, every piece of text into
181
183
 
182
184
  - **Move the values, nothing else.** The page must look and work exactly as before.
183
185
  - **No component-level `constants.ts` survives this stage.**
184
- - **Move motion and artwork objects whole.** Never pull their numbers out into `numbers.ts`. A topic file such as `motion.ts` or `durations.ts` is renamed or folded into the matching standard file.
185
- - **A list of items with links** keeps its words in `s` and its links in `r` under the same keys, and a loop looks each one up by its id: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete lookup objects such as `PLAN_ROUTES`.
186
+ - **Move animation and artwork objects whole.** Never pull their numbers out into `numbers.ts`. Any other file in `lib/constants/` is folded into the standard file that fits.
187
+ - **Where each value goes is the project's call.** Read the [Constants table](/docs/Structure/folder-structure#constants) and decide. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
188
+ - **An id moves into the object that uses it.** **CSS written as a string moves to `globals.css`**, never into a constants file. A media query the code reads stays in its object in `animation.ts`.
189
+ - **Only text people see or hear goes in `s`.** Internal strings, such as ids, keys and log messages, stay where they are used: a key in the object that uses them, or a named constant at the top of the file.
190
+ - **A list of items with links** keeps its words in `s` and its links in `r` under the same keys, and a loop looks each one up by its key: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete any separate lookup object that maps a key to its link.
186
191
  - **Shared types move to `lib/types/`.** `lib/constants/` never imports from `lib/types/`.
187
192
 
188
193
  ## Stage 5 — Components
@@ -207,7 +212,7 @@ Applies setup standard 21.
207
212
 
208
213
  1. Copy the [AGENTS.md template](/docs/templates#agents) to the project root and replace every `[placeholder]`. It describes the final layout, so it goes last.
209
214
  2. Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
210
- 3. Set `**Code standards version:**` from the [Version History](/docs/version-history).
215
+ 3. Set `**Code standards version:**` to the installed package's full version, such as `3.2.2`.
211
216
  4. Run the [standards check](/docs/Guides/setup#checking-a-project), and fix what it finds.
212
217
 
213
218
  ## Tips
@@ -51,7 +51,7 @@ The standards are now in `node_modules/@activatus/code-standards/`:
51
51
  | `docs/version-history.md` | What changed in each version, and what a project has to do about it |
52
52
  | `static/templates/` | The config files to copy: `AGENTS.md`, ESLint, Prettier, Stylelint and the rest |
53
53
 
54
- **Read the standards from `node_modules`, not the website.** The installed package is the exact version the project uses. The package version is the standards version: `2.0.0` is version 2.
54
+ **Read the standards from `node_modules`, not the website.** The installed package is the exact version the project uses. The package version is the standards version, and a project records it in full: `3.2.2`.
55
55
 
56
56
  ## 2. Work out where the project is
57
57
 
@@ -121,7 +121,7 @@ The list has nothing about branches or commit messages. Those are the project's
121
121
 
122
122
  ## 4. Working with the agent
123
123
 
124
- Do this step every time, straight after step 3. Once the standards are agreed, offer the four [Working with Agents](/docs/Standards/working-with-agents) options. All four are optional: offer every one, every time, so the person can fill them in quickly and keep going.
124
+ Do this step every time, straight after step 3. Once the standards are agreed, offer the five [Working with Agents](/docs/Standards/working-with-agents) options. All five are optional: offer every one, every time, so the person can fill them in quickly and keep going.
125
125
 
126
126
  First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
127
127
 
@@ -148,7 +148,14 @@ Would you like AI to ask you before every commit and push
148
148
  to git? Yes or no?
149
149
  ```
150
150
 
151
- **Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, write nothing about it: the agent uses its own judgement. Write all four answers in `docs/development/coding-standards.md`, under "Details", on one line, so a later update knows not to ask again: `- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
151
+ Then **told about decisions**. **Print this to the person exactly as it is written**:
152
+
153
+ ```text
154
+ Would you like AI to tell you about each coding decision
155
+ it makes that the code standards do not cover? Yes or no?
156
+ ```
157
+
158
+ **Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, write nothing about it: the agent uses its own judgement. If they said yes to being told about decisions, write under **Decisions**: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." If they said no, delete the Decisions line. Write all five answers in `docs/development/coding-standards.md`, under "Details", on one line, so a later update knows not to ask again: `- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
152
159
 
153
160
  ## 5. Apply the standards
154
161
 
@@ -174,12 +181,12 @@ The other standards are rules for how code is written. There is nothing to insta
174
181
 
175
182
  **Finish by:**
176
183
 
177
- 1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's major version. See [Finishing a change later](#finishing-a-change-later) if anything is left to do.
184
+ 1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's full version, such as `3.2.2`. See [Finishing a change later](#finishing-a-change-later) if anything is left to do.
178
185
  2. Running `pnpm lint`, `pnpm format:check`, the tests and the [standards check](#checking-a-project), and fixing what they find.
179
186
  3. **Printing this to the person**, filled in, so every project's handover reads the same:
180
187
 
181
188
  ```text
182
- Code standards set up: version [N] ([package version]).
189
+ Code standards set up: version [full package version].
183
190
 
184
191
  Set up: [the standards applied, by number]
185
192
  Skipped: [numbers and reasons, or "None"]
@@ -195,12 +202,11 @@ anything that is wrong.
195
202
 
196
203
  ## Already on this version
197
204
 
198
- The project's `AGENTS.md` has the same major version as the installed package, such as 3. That does not mean there is nothing to do: a newer patch, such as 3.1.1, can still ask for changes.
205
+ The project's `AGENTS.md` has the same full version as the installed package, such as 3.2.2. There are no version changes to make.
199
206
 
200
- 1. **Read the version's Fixes** in `node_modules/@activatus/code-standards/docs/version-history.md`, and do anything they ask.
201
- 2. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles and asking before committing. Ask the person any that are not recorded, and record them as step 4 says.
202
- 3. **Run the [standards check](#checking-a-project)**, and fix what it finds.
203
- 4. **Tell the person** what you changed, or that the project was already up to date.
207
+ 1. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles, asking before committing and being told about decisions. Ask the person any that are not recorded, and record them as step 4 says.
208
+ 2. **Run the [standards check](#checking-a-project)**, and fix what it finds.
209
+ 3. **Tell the person** what you changed, or that the project was already up to date.
204
210
 
205
211
  ---
206
212
 
@@ -208,23 +214,23 @@ The project's `AGENTS.md` has the same major version as the installed package, s
208
214
 
209
215
  The project already follows the standards, and a newer version is out.
210
216
 
211
- **A fix or a minor version keeps the same version number.** When only the last number changes (a fix, such as 3.0.0 → 3.0.1) or the middle number changes (a minor version, such as 3.0.9 → 3.1.0), the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed.
217
+ **Every new number can ask for work**, whichever part changed. What each part means is in [How versions are numbered](/docs/version-history#how-versions-are-numbered).
212
218
 
213
- 1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code follows.
219
+ 1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code last applied. If it is only a major number, such as `3`, find the full version first: see [Updating a project to a new version](/docs/version-history#updating-a-project-to-a-new-version).
214
220
  2. **Update the package:**
215
221
 
216
222
  ```bash
217
223
  pnpm add -D @activatus/code-standards@latest
218
224
  ```
219
225
 
220
- Its major version is now the newest version. If pnpm refuses because the version is too new, or `pnpm format:check` now fails on `pnpm-workspace.yaml`, see [1. Install the standards](#1-install-the-standards). Check `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` is the plain name, `"@activatus/code-standards"`, with no version in it.
226
+ Its version is now the newest. If pnpm refuses because the version is too new, or `pnpm format:check` now fails on `pnpm-workspace.yaml`, see [1. Install the standards](#1-install-the-standards). Check `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` is the plain name, `"@activatus/code-standards"`, with no version in it.
221
227
 
222
- 3. **Read `node_modules/@activatus/code-standards/docs/version-history.md`**, but only the versions newer than the project's. Do not re-read the rest of the standards.
228
+ 3. **Read `node_modules/@activatus/code-standards/docs/version-history.md`**, but only the entries newer than the project's version. Do not re-read the rest of the standards.
223
229
  4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
224
230
  5. **Do every other change** as its "What to do" says, and run its "How to check" search.
225
231
  6. **Ask any [step 4](#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
226
232
  7. **Run the [standards check](#checking-a-project)**, and fix what it finds.
227
- 8. **Set `**Code standards version:**`** in `AGENTS.md` to the new version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
233
+ 8. **Set `**Code standards version:**`** in `AGENTS.md` to the installed package's full version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
228
234
 
229
235
  See the [Version History](/docs/version-history) for the full update rules.
230
236
 
@@ -254,7 +260,7 @@ It reports, and never changes a file. Each finding gives the standard's number a
254
260
  | 6 to 10 | `eslint.config.mjs`, `prettier.config.mjs`, `stylelint.config.mjs`, `.editorconfig` and `.envrc` match the templates; `eslint.overrides.mjs`, `.nvmrc` and the format scripts are in place |
255
261
  | 12.1 | `lib/constants/` has `index.ts`, `routes.ts`, `strings.ts` and `numbers.ts`, no component has its own `constants.ts`, and no other file sits beside the seven standard ones |
256
262
  | 13 | Every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
257
- | 21 | `docs/development/coding-standards.md` records the four agent answers under "Details" |
263
+ | 21 | `docs/development/coding-standards.md` records the five agent answers under "Details" |
258
264
  | 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
259
265
  | 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
260
266
  | 4 | Every file that exports a function or component has a test file beside it |
@@ -5,7 +5,7 @@ sidebar_label: "Working with Agents"
5
5
 
6
6
  # Working with Agents
7
7
 
8
- > How an AI agent links a project's work, reports on it and asks before committing. The GitHub repo, the Linear project, the status circles and asking before every commit and push are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all four every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
8
+ > How an AI agent links a project's work, reports on it, asks before committing and tells the person about its decisions. The GitHub repo, the Linear project, the status circles, asking before every commit and push, and being told about decisions are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all five every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
9
9
 
10
10
  Whatever the project chooses is written into the **Project workflow** section of its `AGENTS.md`, from the [template](/docs/templates#agents), so every agent in the project follows it.
11
11
 
@@ -45,3 +45,7 @@ Optional. An agent reports the state of every ticket or piece of work as one lin
45
45
  ## Ask before committing
46
46
 
47
47
  Optional. Setup asks: "Would you like AI to ask you before every commit and push to git?" A yes is written under **Who commits** in Project workflow: ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only. A no means nothing is written, and the agent uses its own judgement.
48
+
49
+ ## Told about decisions
50
+
51
+ Optional. Setup asks: "Would you like AI to tell you about each coding decision it makes that the code standards do not cover?" The code standards are the base, and the agent builds freely from them, so it makes many calls of its own. A person who reads the code may want to hear each one; a person who does not may not care. A yes is written under **Decisions** in Project workflow: the agent lists each such decision in its summary at the end of the task. A no means nothing is written, and the agent decides without reporting.
@@ -301,7 +301,7 @@ Add the export to `utils/index.ts` whenever you add a function.
301
301
 
302
302
  ## 🔤 Constants: `r`, `s`, numbers, noData, animation, artwork and class names {#constants}
303
303
 
304
- Every link, every piece of text on screen, every named number, every piece of stand-in data, and every motion, drawing and shared class name lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every project finds its values in the same seven files.
304
+ Every link, every piece of text on screen, every named number, every piece of stand-in data, and every motion, drawing and shared class name lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every project finds its values in the same seven files. Internal strings people never see are the one exception: see [`s`: strings](#s-strings).
305
305
 
306
306
  ```text
307
307
  lib/constants/
@@ -315,18 +315,20 @@ lib/constants/
315
315
  └── index.ts # Exports all of them
316
316
  ```
317
317
 
318
- **These seven files are the only ones.** Each is one file, never split by topic: no `durations.ts`, `motion.ts` or `layout.ts`. `routes.ts`, `strings.ts`, `numbers.ts` and `index.ts` exist from the start; the other four are created only once the project has something to put in them.
318
+ **These seven files are the only ones.** Each is one file, never split by topic. `routes.ts`, `strings.ts`, `numbers.ts` and `index.ts` exist from the start; the other four are created only once the project has something to put in them.
319
319
 
320
320
  | A value that is… | Goes in |
321
321
  | ----------------------------------------------------------- | ------------------- |
322
322
  | A link | `r` in `routes.ts` |
323
- | Text shown on screen | `s` in `strings.ts` |
323
+ | Text people see or hear | `s` in `strings.ts` |
324
324
  | A single number with one job | `numbers.ts` |
325
325
  | Fake data shaped like a real response | `noData.ts` |
326
326
  | A group of values that together say how something moves | `animation.ts` |
327
327
  | A group of values that together say what is drawn and where | `artwork.ts` |
328
328
  | A Tailwind class string used by more than one file | `classNames.ts` |
329
329
 
330
+ **This table is the base, and where each value goes is the project's call.** The table says what each file is for, not where every value in every project goes. The project reads its own values, decides which file each one belongs in, and keeps that choice the same across the codebase. A value that fits none of them goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, where the project records why. It is a coding decision, so the work carries on without waiting for a yes.
331
+
330
332
  A file outside the folder imports everything it needs in one line:
331
333
 
332
334
  ```tsx
@@ -355,7 +357,7 @@ export const r = {
355
357
 
356
358
  ### `s`: strings
357
359
 
358
- **`s` holds every piece of static text** shown on screen: headings, buttons, labels, aria-labels, page titles and descriptions, and longer Markdown copy.
360
+ **`s` holds every piece of text people see or hear**: headings, buttons, labels, aria-labels, page titles and descriptions, and longer Markdown copy.
359
361
 
360
362
  ```ts title="lib/constants/strings.ts"
361
363
  export const s = {
@@ -369,6 +371,7 @@ export const s = {
369
371
 
370
372
  - **The keys of `s` are the site's translation keys.** When a site gets more languages, each key is translated into each language. Name each key after what the text says or does, and never use one key for two different jobs.
371
373
  - **Only real copy goes in `s`.** Dummy text belongs in `noData.ts`.
374
+ - **Internal strings are not `s`.** Ids, keys, event names, log messages and media queries are never shown to people. Each is a key in the object that uses it, or a named constant at the top of the file that uses it, such as `const CLOSE_EVENT = "close";`. The code is never pulled apart to move them into `lib/constants/`.
372
375
 
373
376
  ### A list of items with links
374
377
 
@@ -399,24 +402,24 @@ export const r = {
399
402
 
400
403
  **Write each key out by name** when you mean one item: `r.plans.starter`, never `r.plans[planId]`. A reader can see exactly which words and which link each line uses.
401
404
 
402
- **Inside a loop over the list, look each item up by its key.** A loop cannot name its items, so it reads `r` and `s` with the item's id, typed from `r` itself:
405
+ **Inside a loop over the list, look each item up by its key.** A loop cannot name its items, so it reads `r` and `s` with the item's key, typed from `r` itself:
403
406
 
404
407
  ```ts title="lib/types/index.ts"
405
408
  import type { r } from "@/lib/constants";
406
409
 
407
- export type SourceIdType = keyof typeof r.sources;
410
+ export type PlanIdType = keyof typeof r.plans;
408
411
  ```
409
412
 
410
- ```tsx title="app/(homepage)/components/sourceList/SourceList.tsx"
411
- {sourceIds.map((sourceId) => (
412
- <Link key={sourceId} href={r.sources[sourceId]}>
413
- {s.sources[sourceId].title}
413
+ ```tsx
414
+ {planIds.map((planId) => (
415
+ <Link key={planId} href={r.plans[planId]}>
416
+ {s.plans[planId].action}
414
417
  </Link>
415
418
  ))}
416
419
  ```
417
420
 
418
- - **The type comes from `r`**, so a missing or misspelt id fails the type check.
419
- - **No separate lookup objects**, such as `SOURCE_ROUTES` or `PLAN_ROUTES` mapping an id to its link. `r.sources` already is that lookup: a second one is a copy that drifts out of step.
421
+ - **The type comes from `r`**, so a missing or misspelt key fails the type check.
422
+ - **No separate lookup objects** that map a key to its link. `r` already is that lookup: a second one is a copy that drifts out of step.
420
423
 
421
424
  ### noData: stand-in data for local development
422
425
 
@@ -460,73 +463,81 @@ const insights =
460
463
  export const COOKIE_DURATION_DAYS = 30;
461
464
  export const MAXIMUM_RETRY_ATTEMPTS = 3;
462
465
  export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
463
- export const TOOLTIP_SIDE_OFFSET_PIXELS = 8;
464
466
  ```
465
467
 
466
468
  - **One file, never split by topic.** `numbers.ts` can run past 300 lines, like `r` and `s`.
467
- - **Loose numbers only.** A number that only means something beside other values, such as one swing in a choreography, stays inside its object in `animation.ts` or `artwork.ts`. It is never lifted out into `numbers.ts`.
469
+ - **Loose numbers only.** A number that only means something beside other values stays inside its object in `animation.ts` or `artwork.ts`. It is never lifted out into `numbers.ts`.
468
470
  - **Config files and scripts outside the app**, such as `eslint.config.mjs`, keep their numbers at the top of the file: they are not part of the app and do not import from it.
469
471
  - **Put the unit in the name**: `_MILLISECONDS`, `_DAYS`, `_PIXELS`.
470
472
 
471
473
  ### Animation: how things move
472
474
 
473
- **`animation.ts` holds every object that says how something moves**: motion and choreography (`*_MOTION`), entrances, scroll stops, drift, zoom, scroll pacing, and motion media queries.
475
+ **`animation.ts` holds every object that says how and when something moves.**
474
476
 
475
477
  ```ts title="lib/constants/animation.ts"
476
- export const CONFIDENCE_MOTION = {
477
- pivot: "bearing-west",
478
- ease: "easeInOut",
479
- rounds: [
480
- { degrees: 12, seconds: 0.6 },
481
- { degrees: -8, seconds: 0.4 },
482
- ],
483
- snapSeconds: 0.2,
478
+ export const ENTRANCE_ANIMATION = {
479
+ delaySeconds: 0.1,
480
+ durationSeconds: 0.4,
481
+ offsetPixels: 24,
484
482
  };
485
-
486
- export const REDUCED_MOTION_QUERY =
487
- "(prefers-reduced-motion: reduce)";
488
483
  ```
489
484
 
490
- - **Each object stays whole.** Its numbers, part names and eases only mean something together, so they stay in one object, named by their keys (`snapSeconds`). Never lift its numbers out into `numbers.ts`: `CONFIDENCE_ROUND_ONE_SWING_ONE_DEGREES` is harder to read, and splits one movement across files.
491
- - **Part names and eases are not text on screen.** They are never shown or translated, so they stay in the object, not in `s`.
492
- - **Put the unit in the key**: `seconds`, `degrees`, `snapSeconds`.
485
+ - **Each object stays whole.** Values that only mean something together stay in one object, named by their keys. Never lift its numbers out into `numbers.ts`.
486
+ - **Values the animation library reads are not text on screen**, so they stay in the object, never in `s`.
487
+ - **Put the unit in the key**: `durationSeconds`, `offsetPixels`.
488
+ - **Media queries the animation reads stay in its object**, such as `reducedMotionQuery: "(prefers-reduced-motion: reduce)"`. They are read by code, not CSS, so they never move to `globals.css`.
493
489
 
494
490
  ### Artwork: what is drawn and where
495
491
 
496
- **`artwork.ts` holds every object that says what is drawn and where**: card layouts and pieces, backdrop tiles, canvas sizes, shape positions and image paths.
492
+ **`artwork.ts` holds every object that says what is drawn, where it ends up, and how it is grouped.** Where something ends up is artwork; how and when it gets there is animation.
497
493
 
498
494
  ```ts title="lib/constants/artwork.ts"
499
- export const HERO_CANVAS = { widthPixels: 1440, heightPixels: 900 };
500
-
501
- export const BACKDROP_TILES = [
502
- { image: "/images/backdrop/tileOne.webp", x: 0, y: 0 },
503
- { image: "/images/backdrop/tileTwo.webp", x: 480, y: 0 },
504
- ];
495
+ export const ILLUSTRATION_LAYOUT = {
496
+ heightPixels: 600,
497
+ widthPixels: 800,
498
+ };
505
499
  ```
506
500
 
507
501
  - **Each object stays whole**, the same as in `animation.ts`.
508
- - **An SVG drawing is a component or a file, never a string here.** Long SVG paths go in an `.svg` file in `public/` or in an icon component in `components/ui/`. `artwork.ts` says where a drawing goes, not what its path is.
502
+ - **Drawing data the code reads goes here.** A static drawing that nothing reads goes in an `.svg` file in `public/` or in an icon component.
509
503
 
510
504
  ### Class names shared between files
511
505
 
512
- **`classNames.ts` holds a Tailwind class string that more than one file uses**, such as the face of a card that a card and its sub-components all draw.
506
+ **`classNames.ts` holds Tailwind class names that more than one file uses**: a single class string, or a set of them keyed by variant.
513
507
 
514
508
  ```ts title="lib/constants/classNames.ts"
515
- export const CARD_FACE_CLASS_NAME =
516
- "rounded-2xl border border-border bg-card shadow-sm";
509
+ export const SURFACE_CLASS_NAME =
510
+ "rounded-2xl border border-border bg-card";
517
511
  ```
518
512
 
519
513
  - **Make a component first.** A class string repeated across files usually means a component is missing, and the component is what makes the styling reusable. Use `classNames.ts` only when a component cannot hold the classes and they still repeat, such as when they go on different elements.
520
514
  - **A class name used in one file stays inline in that file.**
521
- - **Name each export after what it styles, ending in `_CLASS_NAME`.**
515
+ - **Name each export after what it styles, ending in `_CLASS_NAME`**, or `_CLASS_NAMES` for a set keyed by variant.
522
516
 
523
- ### Rules
517
+ ### Rules {#constants-rules}
524
518
 
525
519
  - **Named exports only:** `export const r`, `export const s`. No default exports.
526
520
  - **Files outside `lib/constants/` import from `@/lib/constants`**, all in one import line.
527
521
  - **Files inside `lib/constants/` import each other directly**, `import { s } from "./strings";`, never through `index.ts`. See [Inside a folder, import files directly](/docs/Structure/import-organization#2-inside-a-folder-import-files-directly).
528
522
  - **`r` and `s` are the only single-letter names allowed anywhere.** See [Human-Readable Names](/docs/Standards/human-readable-names#r-and-s).
529
523
  - **Other constants**, such as numbers, are `SCREAMING_SNAKE_CASE`: see [Naming Conventions](/docs/Structure/naming-conventions#constants).
524
+ - **An id lives in the object that uses it.** A value that picks which item something acts on, such as which item an animation moves to, is a key inside that object, never a loose constant of its own:
525
+
526
+ ```ts
527
+ // Before
528
+ export const HIGHLIGHTED_PLAN_ID = "team";
529
+ export const HIGHLIGHT_ANIMATION = { durationSeconds: 0.3 };
530
+
531
+ // After
532
+ export const HIGHLIGHT_ANIMATION = {
533
+ durationSeconds: 0.3,
534
+ planId: "team",
535
+ };
536
+ ```
537
+
538
+ A list of keys a loop runs over, such as `planIds` in [A list of items with links](#a-list-of-items-with-links), is not a loose id: it stays a list.
539
+
540
+ - **CSS belongs in a stylesheet, never in a constant.** Styles written as a string in TypeScript move to `globals.css`. Styles for when JavaScript is off go there under `@media (scripting: none)`; a browser without that query misses the fallback, and the standard accepts that. **A media query the code reads is not CSS**, such as the one an animation library matches to switch motion off: it stays in its object in `animation.ts`.
530
541
  - **All seven files can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
531
542
  - **`lib/constants/` never imports from `lib/types/`.** `lib/types/` reads some of its types from the constants (`typeof s`), so an import the other way makes a loop. When a constant needs a type, write the type beside the constant, or read it from the constant.
532
543
 
@@ -7,27 +7,44 @@ sidebar_label: "Version History"
7
7
 
8
8
  > What changed in each version of the standards, and exactly what a project has to do about it. Written for the AI agent doing the update.
9
9
 
10
- **Every change to the standards gets a new version number.** Each project records the version it follows in its `AGENTS.md`, under "Code standards":
10
+ **Every change to the standards gets a new version number.** Each project records the full version it last applied in its `AGENTS.md`, under "Code standards", so the project pairs with the package and knows where to start:
11
11
 
12
12
  ```md
13
- **Code standards version:** 2
13
+ **Code standards version:** 3.2.2
14
14
  ```
15
15
 
16
+ ## How versions are numbered
17
+
18
+ | Part that changes | Example | Means |
19
+ | ----------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
20
+ | First | 3.2.2 → 4.0.0 | A major update: it changes how most of a project's code is written, so every project reworks it |
21
+ | Middle | 3.2.2 → 3.3.0 | Files move: the update moves or renames files in a project. Plan it, and take a regression baseline first |
22
+ | Last | 3.2.2 → 3.2.3 | Changes inside files only. Nothing moves |
23
+
24
+ **The first number goes up only when most projects must rework most of their code**, such as a new framework or a standard replaced by a different one. A rule added, changed or clarified never bumps it. Every new number can ask for work, whichever part changed. 3.1.1 and 3.2.1 came out before this rule and moved files in a last-number update; their moves are listed under **Structural changes**.
25
+
16
26
  ## Updating a project to a new version
17
27
 
18
- **Read only the versions newer than the project's.** A project on version 1 that is updating to version 3 reads version 2 and version 3 on this page, and nothing else. Do not re-read every standard or check the whole codebase: each version lists every change that matters, and how to find the code it affects.
28
+ **Read only the entries newer than the project's version.** A project on 3.2.1 updating to 3.3.0 reads the 3.2.2 and 3.3.0 entries on this page, and nothing else. **A project that recorded only a major number, such as `3`,** first finds the full version it actually applied: the `@activatus/code-standards` version in `pnpm-lock.yaml` at the last commit that changed its `**Code standards version:**` line. Record that version in `AGENTS.md` and start from there. Only when it cannot tell does it read every entry of that major version from its start:
19
29
 
20
- 1. **Find the project's version** in its `AGENTS.md`. If there is none, the project has never followed the standards: follow [Setup](/docs/Guides/setup) instead.
30
+ ```bash
31
+ git show "$(git log -1 --format=%h -G'Code standards version' -- AGENTS.md)":pnpm-lock.yaml \
32
+ | grep -o "@activatus/code-standards@[0-9.]*" | head -1
33
+ ```
34
+
35
+ Do not re-read every standard or check the whole codebase: each version lists every change that matters, and how to find the code it affects.
36
+
37
+ 1. **Find the project's version** in its `AGENTS.md`. If it is only a major number, find the full one first, as above. If there is none, the project has never followed the standards: follow [Setup](/docs/Guides/setup) instead.
21
38
  2. **Update the package:** `pnpm add -D @activatus/code-standards@latest`, never a typed version number. If pnpm refuses because the version is too new, add the package to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`, as in [Setup](/docs/Guides/setup#1-install-the-standards). The entry is the plain package name, with no version. If pnpm wrote one with versions in it, such as `'@activatus/code-standards@3.0.4 || 3.0.5'`, replace it with the plain name: otherwise pnpm adds another version to it on every update. Then read this page from `node_modules/@activatus/code-standards/docs/version-history.md`.
22
- 3. **Read each version newer than the project's**, oldest first. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
39
+ 3. **Read each entry newer than the project's version**, oldest first. For a middle-number entry, take the [regression check](/docs/Guides/regression-checks) baseline before any file moves. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
23
40
  4. **For each change, do the "What to do" steps**, then run the "How to check" searches. A search that still finds something means the change is not finished. When a change says to copy a line from the `AGENTS.md` template, and the project's `AGENTS.md` records the standards in its own words instead, write the updated rule there in the project's own shape.
24
41
  5. **Strike out what the standard now covers.** After the changes, re-read the project's list of opted-out and changed standards in `docs/development/coding-standards.md`. Take off the list any exception the new version has made part of the standard, and update any rule it records for an old shape of the standard. A differences list that still describes the old standard sends the next agent wrong.
25
42
  6. **Run `pnpm lint`, `pnpm format:check`, `pnpm test` and the build** after each change. `format:check` checks every file git does not ignore; never narrow it to changed files.
26
43
  7. **Ask any [Working with the agent](/docs/Guides/setup#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
27
44
  8. **Run `pnpm standards:check`**, and fix what it finds. See [Checking a project](/docs/Guides/setup#checking-a-project).
28
- 9. **Update the version number** in `AGENTS.md` once every change is done.
45
+ 9. **Set the version** in `AGENTS.md` to the installed package's full version once every change is done.
29
46
 
30
- **A fix or a minor version keeps the same version number.** When only the last number changes (a fix, such as 3.0.0 → 3.0.1) or the middle number changes (a minor version, such as 3.0.9 → 3.1.0), the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed. A project already on the installed major version is never "nothing to do": follow [Already on this version](/docs/Guides/setup#already-on-this-version).
47
+ **A project already on the installed full version** has no version changes to make: follow [Already on this version](/docs/Guides/setup#already-on-this-version).
31
48
 
32
49
  **When a change does not fit the project**, for example it renames a folder the project does not have, skip it. If you are not sure, ask; do not guess.
33
50
 
@@ -35,47 +52,89 @@ sidebar_label: "Version History"
35
52
 
36
53
  Anyone changing the standards adds a version, alongside the change:
37
54
 
38
- - **One version per release**, numbered one higher than the last. Whole numbers only. A version can collect several changes before it is released.
39
- - **Bump the package's major version to match** in `package.json`: version 3 is `3.0.0`. Then publish it to npm (npmjs.com) with `pnpm publish`. pnpm is the tool; npm is where the package lives, and projects install it from there with `pnpm add`.
55
+ - **Pick the number from [How versions are numbered](#how-versions-are-numbered).** A major update is `4.0.0`. An update that moves files bumps the middle number, `3.2.2` → `3.3.0`. An update that only changes the inside of files bumps the last, `3.2.2` → `3.2.3`. Set it in `package.json`, then publish it to npm (npmjs.com) with `pnpm publish`. pnpm is the tool; npm is where the package lives, and projects install it from there with `pnpm add`.
40
56
  - **For every change, write:** what changed, why, what to do in a project, and how to check it is done. Write it for an agent that has not read the rest of the standards.
41
57
  - **If a project has nothing to do, say so.**
42
58
  - **Newest version at the top.**
43
- - **Work in progress goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: pilot it (below), drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
44
- - **Pilot a version in a real project before releasing it.** Once the work-in-progress version is written, have one real project apply it exactly as written, reading only what the page says. Every judgement call the agent has to make, and every instruction that does not fit the project, is a missing sentence: fold it back into the version before publishing. Release only when the pilot runs without the agent asking a question the page does not answer.
45
- - **Fixing a released version** bumps only the last number: `3.0.0` → `3.0.1`. Update the version's changes in place, and list what was fixed under its **Fixes**. Projects keep the same version number in `AGENTS.md`. Write each fix so a project already on that version knows what to do.
46
- - **Adding something optional** to a released version, such as a new setup question, bumps the middle number: `3.0.9` → `3.1.0`. It is written up the same way as a fix, and projects keep the same version number in `AGENTS.md`.
47
- - **Changes that move files are listed under Structural changes.** At the top of the version's Fixes, list each change that moves or renames files in a project, with a rough size, such as "moves every component `constants.ts`", so a project can plan the work and run a [regression check](/docs/Guides/regression-checks) first. For now, structural changes ship in fix and minor versions; once the standards settle, they will wait for the next major version.
48
- - **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.0.9 — optional project links`, so releases are easy to find in the git log.
49
- - **Every patch number is published.** Publish each patch to npm as soon as its Fixes are written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
59
+ - **Work in progress on a major update goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
60
+ - **Changing a released major version** goes under its version, newest at the top. Update the version's changes in place where they are now wrong. Write each entry so a project already on the version before it knows what to do.
61
+ - **Every entry is headed `**Fixes in 3.2.3.**`**, with its number, followed by "If the project already applied 3.2.2, check these:".
62
+ - **A middle-number entry adds `**Structural changes in 3.3.0.**` straight under its heading**, listing each change that moves or renames files in a project, with a rough size, such as "one move per file", so a project can plan the work and take a [regression check](/docs/Guides/regression-checks) baseline first. A last-number entry never moves files.
63
+ - **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.2.2 — full version numbers`, so releases are easy to find in the git log.
64
+ - **Every number is published.** Publish each one to npm as soon as its entry is written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
50
65
  - **Judgement calls after release are fixes, not workarounds.** When a project's update needed a call the steps did not cover, add it under the version's Fixes so every other project gets it too. A project should never keep a private workaround for an unclear step.
51
66
 
52
67
  ---
53
68
 
54
69
  ## Version 3
55
70
 
56
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.2.1
71
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.2.2
57
72
 
58
73
  Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
59
74
 
75
+ **Fixes in 3.2.2.** If the project already applied 3.2.1, check these:
76
+
77
+ - **The project records the full version.** `**Code standards version:**` in `AGENTS.md` is now the full version last applied, such as `3.1.0`, not the major number alone, so the project and the package pair up and the next update knows where to start. Versions are now numbered by what they do: see [How versions are numbered](#how-versions-are-numbered). `pnpm standards:check` reads the full version, and flags a project that recorded only `3`, an older version, or a version newer than the installed package.
78
+
79
+ **What to do:** if `AGENTS.md` records only a major number, find the full version the project applied from its lockfile, as in [Updating a project to a new version](#updating-a-project-to-a-new-version), and start this update from there. Copy the Code standards section of `AGENTS.md` from the template again. When the update is done, set the version to the installed package's full version.
80
+
81
+ - **The standards are the base, and agents build freely from there.** The `AGENTS.md` template now says so: most code is something the standards never mention, and the agent decides it and keeps it the same across the codebase. Only skipping, loosening or changing a standard needs the person's yes; the agent then records it and keeps going, never stopping to wait for a new version of the standards. Copied in with the section above.
82
+
83
+ - **Where each constant goes is the project's call.** The [Constants table](/docs/Structure/folder-structure#constants) says what each file is for, not where every value in every project goes. 3.2.1's examples and check named values from one project; they are now neutral, and `pnpm standards:check` no longer guesses a value's file from its name. It lists the file, and the project decides.
84
+
85
+ **What to do:** best practice is every value in `lib/constants/` in the file the table says fits, with ids and CSS following the two rules below. Bring the project's values in line with that. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
86
+
87
+ - **An id lives in the object that uses it.** A value that picks which item something acts on is a key inside that object, never a loose constant. A list of keys a loop runs over stays a list. See the [before and after](/docs/Structure/folder-structure#constants-rules).
88
+
89
+ **What to do:** move each loose id constant into the object that uses it.
90
+
91
+ - **CSS belongs in a stylesheet, never in a constant.** Styles written as a string in TypeScript move to `globals.css`. Styles for when JavaScript is off go there under `@media (scripting: none)`. A media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`.
92
+
93
+ **What to do:** move any CSS string out of `lib/constants/` and components into `globals.css`.
94
+
95
+ - **`s` holds only text people see or hear.** Internal strings, such as ids, keys, event names and log messages, are not `s`: each is a key in the object that uses it, or a named constant at the top of the file that uses it.
96
+
97
+ **What to do:** nothing, unless the project moved internal strings into `s`. Move those back beside the code that uses them.
98
+
99
+ - **`animation.ts` and `artwork.ts` are split by one question.** Where something ends up is artwork; how and when it gets there is animation. Drawing data the code reads goes in `artwork.ts`; a static drawing nothing reads goes in an `.svg` file or an icon component. `classNames.ts` can hold a set of class names keyed by variant, named `_CLASS_NAMES`. Nothing to move unless the project placed a value by the old wording.
100
+
101
+ - **The regression baseline comes first.** Take it before any file moves, then do the constants moves and the folder moves as separate steps, with a full regression run after each. See [Stage 0](/docs/Guides/migrating#stage-0--regression-check).
102
+
103
+ - **`pnpm standards:check` reports headings for standards 11 and 13**, which 3.2.1 printed blank. Nothing to do.
104
+
105
+ - **Setup asks a fifth agent question:** does the person want to be told about coding decisions the agent makes that the code standards do not cover? Someone who reads the code may want to hear each one; someone who does not may not care. See [Told about decisions](/docs/Standards/working-with-agents#told-about-decisions).
106
+
107
+ **What to do:** ask the person the question in [setup step 4](/docs/Guides/setup#4-working-with-the-agent), and add the answer to the "Working with the agent" line under "Details" in `coding-standards.md`. If they said yes, add the rule under **Decisions** in the Project workflow section of `AGENTS.md`.
108
+
109
+ **How to check:** `AGENTS.md` records the full installed version; `pnpm standards:check` passes, or lists only recorded exceptions; these searches find nothing, or only values the project has recorded:
110
+
111
+ ```bash
112
+ # CSS written in TypeScript, however it is quoted, on one line or many
113
+ grep -rnE "@media|@keyframes|!important|[a-z-]+: *[^;,]*(px|rem|none|auto|block|flex|grid);" \
114
+ lib/constants/ app/ components/ --include='*.ts' --include='*.tsx' --exclude='*.test.*'
115
+ # A loose id constant
116
+ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
117
+ ```
118
+
60
119
  **Fixes in 3.2.1.** If the project already applied 3.2.0, check these:
61
120
 
62
121
  **Structural changes in 3.2.1.** These move files. Plan them, and run a [regression check](/docs/Guides/regression-checks) first:
63
122
 
64
- - Every component `constants.ts` and every topic file in `lib/constants/` (`motion.ts`, `durations.ts`, `cardRail.ts`) moves into the seven standard files. Large on a site with many components: the Activatus homepage has 36 component files and 3 topic files. `pnpm standards:check` names the file each export goes to.
65
- - Sub-component folders inside a grouping folder, such as `lifeActivated/outcomeArtwork/alignmentArtwork/`, move flat into the parent's `components/` folder. Small: the 3.1.1 step already moved most of them.
123
+ - Every component `constants.ts`, and every other file in `lib/constants/`, moves into the seven standard files: one move per file. `pnpm standards:check` lists them.
124
+ - Every sub-component folder that is not directly in its root component's `components/` folder moves there: one move per folder. If the project did 3.1.1's move, only folders inside a grouping folder are left. `pnpm standards:check` lists them.
66
125
 
67
126
  - **`lib/constants/` has seven standard files:** `routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, and three new ones, created only once there is something to put in them:
68
- - **`animation.ts`**: how things move. Motion and choreography objects (`*_MOTION`), entrances, scroll stops, drift, zoom, scroll pacing and motion media queries.
69
- - **`artwork.ts`**: what is drawn and where. Layouts, card pieces, backdrop tiles, canvas sizes and image paths. Long SVG paths go in an `.svg` file in `public/` or an icon component, never here.
70
- - **`classNames.ts`**: Tailwind class strings shared between files, only when a component cannot hold them and they still repeat. A class name one file uses stays inline.
127
+ - **`animation.ts`**: how and when things move.
128
+ - **`artwork.ts`**: what is drawn, where it ends up, and how it is grouped.
129
+ - **`classNames.ts`**: Tailwind class names shared between files, only when a component cannot hold them and they still repeat. A class name one file uses stays inline.
71
130
 
72
- Each animation and artwork object stays whole, its numbers named by their keys (`snapSeconds`). Never lift them out into `numbers.ts`, which keeps loose single numbers only. Lifting them out made names like `CONFIDENCE_ROUND_ONE_SWING_ONE_DEGREES` and split one movement across files; the reasons for one numbers file (translation, one place to look) do not apply to motion and drawing data. Each file is one file, never split by topic. See [Constants](/docs/Structure/folder-structure#constants).
131
+ Each animation and artwork object stays whole, its values named by their keys. Never lift them out into `numbers.ts`, which keeps loose single numbers only: lifting them out makes long names and splits one object across files. Each file is one file, never split by topic. See [Constants](/docs/Structure/folder-structure#constants).
73
132
 
74
- **What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. A topic file such as `motion.ts` is folded into `animation.ts`. Run `pnpm standards:check`: each finding names the file each export most likely belongs in; check each against the [Constants table](/docs/Structure/folder-structure#constants). In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template.
133
+ **What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. Where each value goes is the project's call: read the [Constants table](/docs/Structure/folder-structure#constants), decide each value's home. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`, and the work carries on. In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template.
75
134
 
76
- - **A loop over a list looks each item up by its id.** Write a key out by name when you mean one item, `r.plans.starter`. Inside a loop over the list, use the item's id, typed from `r`: `keyof typeof r.sources`. Delete separate lookup objects that map an id to its link, such as `SOURCE_ROUTES` or `PLAN_ROUTES`: `r` already is that lookup. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
135
+ - **A loop over a list looks each item up by its key.** Write a key out by name when you mean one item, `r.plans.starter`. Inside a loop over the list, use the item's key, typed from `r`: `keyof typeof r.plans`. Delete separate lookup objects that map a key to its link: `r` already is that lookup. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
77
136
 
78
- - **`pnpm standards:check` checks more of the How to check lists:** sub-components sit flat in their root component's `components/` folder; the homepage is in `app/(homepage)/`; `docs/development/coding-standards.md` records the four agent answers under "Details"; `docs/design/design-system.md` has a filled-in Colour palette table; and `lib/constants/` holds only the seven standard files. Fix what it finds.
137
+ - **`pnpm standards:check` checks more of the How to check lists:** sub-components sit flat in their root component's `components/` folder; the homepage is in `app/(homepage)/`; `docs/development/coding-standards.md` records the agent answers under "Details"; `docs/design/design-system.md` has a filled-in Colour palette table; and `lib/constants/` holds only the seven standard files. Fix what it finds.
79
138
 
80
139
  - **Keep every docs folder.** 3.2.0's rule is final: no docs folder is deleted, even one that does not apply yet.
81
140
 
@@ -100,8 +159,8 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
100
159
 
101
160
  - The homepage moves into `app/(homepage)/`: `app/page.tsx` and the homepage's components. Small.
102
161
  - The site frame moves into `components/layout/`: the navigation, header and footer. Small.
103
- - Every component `constants.ts` moves into `lib/constants/`. Large on a site with many components: the Activatus homepage had 36. Follow the 3.2.1 rule, not this version's.
104
- - Every nested sub-component folder moves flat into its parent's `components/` folder. Medium to large: the Activatus homepage had 28.
162
+ - Every component `constants.ts` moves into `lib/constants/`: one move per file. Follow the 3.2.1 rule, not this version's.
163
+ - Every nested sub-component folder moves flat into its parent's `components/` folder: one move per folder.
105
164
  - `r` or `s` split into several files only to stay under 300 lines goes back into one file. Small.
106
165
 
107
166
  - **`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` can run past 300 lines.** They hold data only, so `max-lines` no longer applies to them. Splitting `r` or `s` across files to stay under 300 lines only made labels harder to find. In `eslint.config.mjs`, add this block straight after the test-file block:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.2.1",
3
+ "version": "3.2.2",
4
4
  "description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -8,7 +8,9 @@ import { readTextFile } from "./projectFiles.mjs";
8
8
  const SECTION_START = "<!-- code-standards:start -->";
9
9
  const SECTION_END = "<!-- code-standards:end -->";
10
10
  const VERSION_LINE_START = "**Code standards version:**";
11
- const VERSION_PATTERN = /\*\*Code standards version:\*\*\s*(\d+)/;
11
+ const VERSION_PATTERN =
12
+ /\*\*Code standards version:\*\*\s*(\d+(?:\.\d+){0,2})/;
13
+ const VERSION_PART_COUNT = 3;
12
14
  const SKILL_FOLDERS = [".agents/skills", ".claude/commands"];
13
15
  const PAGE = "docs/Standards/agent-specs.md";
14
16
 
@@ -29,28 +31,68 @@ const readStandardsSection = (agentsText) => {
29
31
  : undefined;
30
32
  };
31
33
 
32
- const checkVersion = ({ agentsText, packageMajorVersion }) => {
34
+ const toVersionParts = (version) =>
35
+ Array.from({ length: VERSION_PART_COUNT }, (_unused, index) =>
36
+ Number(version.split(".")[index] ?? 0),
37
+ );
38
+
39
+ // Below zero when the project's version is older than the package's,
40
+ // above zero when it is newer, and zero when they match.
41
+ const compareVersions = ({ projectVersion, packageVersion }) => {
42
+ const projectParts = toVersionParts(projectVersion);
43
+ const packageParts = toVersionParts(packageVersion);
44
+ const differentIndex = projectParts.findIndex(
45
+ (part, index) => part !== packageParts[index],
46
+ );
47
+ return differentIndex === -1
48
+ ? 0
49
+ : projectParts[differentIndex] - packageParts[differentIndex];
50
+ };
51
+
52
+ const checkVersion = ({ agentsText, packageVersion }) => {
33
53
  const match = VERSION_PATTERN.exec(agentsText);
34
54
  if (!match) {
35
55
  return [
36
56
  {
37
57
  standard: "21",
38
58
  message:
39
- "AGENTS.md has no code standards version. Set **Code standards version:** to the major version the code follows",
59
+ "AGENTS.md has no code standards version. Set **Code standards version:** to the full version the code follows, such as 3.2.2",
40
60
  page: "docs/Guides/setup.md",
41
61
  },
42
62
  ];
43
63
  }
44
- const projectVersion = Number(match[1]);
45
- if (projectVersion < packageMajorVersion) {
64
+ const projectVersion = match[1];
65
+ if (projectVersion.split(".").length < VERSION_PART_COUNT) {
66
+ return [
67
+ {
68
+ standard: "21",
69
+ message: `AGENTS.md records version ${projectVersion}, not a full version. Record the full version the project last applied, such as 3.1.0: read the @activatus/code-standards version in pnpm-lock.yaml at the last commit that changed the version line, then update from there`,
70
+ page: "docs/version-history.md#updating-a-project-to-a-new-version",
71
+ },
72
+ ];
73
+ }
74
+ const comparison = compareVersions({
75
+ projectVersion,
76
+ packageVersion,
77
+ });
78
+ if (comparison < 0) {
46
79
  return [
47
80
  {
48
81
  standard: "21",
49
- message: `AGENTS.md says version ${projectVersion}, and the installed package is version ${packageMajorVersion}. Follow "Updating to a newer version"`,
82
+ message: `AGENTS.md says version ${projectVersion}, and the installed package is version ${packageVersion}. Follow "Updating to a newer version"`,
50
83
  page: "docs/Guides/setup.md#updating-to-a-newer-version",
51
84
  },
52
85
  ];
53
86
  }
87
+ if (comparison > 0) {
88
+ return [
89
+ {
90
+ standard: "21",
91
+ message: `AGENTS.md says version ${projectVersion}, newer than the installed package, version ${packageVersion}. Correct the version in AGENTS.md, or install the package with @latest`,
92
+ page: "docs/Guides/setup.md#2-work-out-where-the-project-is",
93
+ },
94
+ ];
95
+ }
54
96
  return [];
55
97
  };
56
98
 
@@ -125,7 +167,7 @@ const checkSkills = ({ projectDirectory, templatesDirectory }) => {
125
167
  export const checkAgentFiles = ({
126
168
  projectDirectory,
127
169
  templatesDirectory,
128
- packageMajorVersion,
170
+ packageVersion,
129
171
  }) => {
130
172
  const agentsText = readTextFile({
131
173
  projectDirectory,
@@ -141,7 +183,7 @@ export const checkAgentFiles = ({
141
183
  ];
142
184
  }
143
185
  return [
144
- ...checkVersion({ agentsText, packageMajorVersion }),
186
+ ...checkVersion({ agentsText, packageVersion }),
145
187
  ...checkStandardsSection({ agentsText, templatesDirectory }),
146
188
  ...checkSkills({ projectDirectory, templatesDirectory }),
147
189
  ];
@@ -1,7 +1,5 @@
1
1
  // Standard 12.1: lib/constants/ holds the seven standard files and
2
2
  // nothing else, and no component keeps its own constants file.
3
- import { readTextFile } from "./projectFiles.mjs";
4
-
5
3
  const REQUIRED_FILES = [
6
4
  "lib/constants/index.ts",
7
5
  "lib/constants/routes.ts",
@@ -18,67 +16,10 @@ const OPTIONAL_FILES = [
18
16
  const CONSTANTS_FOLDER = "lib/constants/";
19
17
  const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
20
18
  const CODE_FILE_PATTERN = /\.(?:ts|tsx|js|mjs)$/;
21
- const EXPORT_PATTERN =
22
- /^export const ([\w$]+)\s*(?::[^=]+)?=\s*(\S)/gm;
23
- const MAXIMUM_NAMES_SHOWN = 3;
24
19
  const PAGE = "docs/Structure/folder-structure.md#constants";
25
-
26
- const UNSURE_HOME = "the file the Constants table names";
27
-
28
- // The name says what most exports are; the first character of the
29
- // value settles the rest. Checked in this order.
30
- const NAME_HOMES = [
31
- { pattern: /CLASS_NAMES?$/, home: "classNames.ts" },
32
- {
33
- pattern:
34
- /MOTION|ANIMATION|ENTRANCE|SCROLL|DRIFT|ZOOM|EASE|SPRING|TRANSITION|KEYFRAME|QUERY|QUERIES/,
35
- home: "animation.ts",
36
- },
37
- {
38
- pattern:
39
- /ARTWORK|LAYOUT|SHAPE|PATH|CANVAS|TILE|IMAGE|PIECE|GEOMETRY|SVG/,
40
- home: "artwork.ts",
41
- },
42
- { pattern: /ROUTE|HREF|LINK|URL/, home: "r in routes.ts" },
43
- { pattern: /^NO_DATA_|^DUMMY_/, home: "noData.ts" },
44
- // Raw CSS is not text for s, and not a class name.
45
- { pattern: /STYLES?$/, home: UNSURE_HOME },
46
- ];
47
- const VALUE_HOMES = [
48
- { pattern: /[\d-]/, home: "numbers.ts" },
49
- { pattern: /["'`]/, home: "s in strings.ts" },
50
- ];
51
-
52
- const findHome = ({ name, valueStart }) =>
53
- NAME_HOMES.find(({ pattern }) => pattern.test(name))?.home ??
54
- VALUE_HOMES.find(({ pattern }) => pattern.test(valueStart))?.home ??
55
- UNSURE_HOME;
56
-
57
- const describeNames = (names) => {
58
- const shown = names.slice(0, MAXIMUM_NAMES_SHOWN).join(", ");
59
- const hiddenCount = names.length - MAXIMUM_NAMES_SHOWN;
60
- return hiddenCount > 0 ? `${shown} and ${hiddenCount} more` : shown;
61
- };
62
-
63
- // "Move CONFIDENCE_MOTION to animation.ts; CARD_FACE_CLASS_NAME to
64
- // classNames.ts".
65
- const suggestHomes = ({ projectDirectory, filePath }) => {
66
- const source = readTextFile({ projectDirectory, filePath }) ?? "";
67
- // Map.groupBy needs Node 21, and the package supports Node 20.
68
- const namesByHome = new Map();
69
- for (const [, name, valueStart] of source.matchAll(
70
- EXPORT_PATTERN,
71
- )) {
72
- const home = findHome({ name, valueStart });
73
- namesByHome.set(home, [...(namesByHome.get(home) ?? []), name]);
74
- }
75
- const moves = [...namesByHome].map(
76
- ([home, names]) => `${describeNames(names)} to ${home}`,
77
- );
78
- return moves.length > 0
79
- ? `Move ${moves.join("; ")}`
80
- : "Move its values into the seven files in lib/constants/";
81
- };
20
+ // Where each value goes is the project's call, made from the table.
21
+ const NEXT_STEP =
22
+ "Move each of its values into the file the Constants table says fits, and record any value that fits none in docs/development/coding-standards.md";
82
23
 
83
24
  const checkMissingFiles = ({ projectFileSet }) =>
84
25
  REQUIRED_FILES.filter(
@@ -89,7 +30,7 @@ const checkMissingFiles = ({ projectFileSet }) =>
89
30
  page: PAGE,
90
31
  }));
91
32
 
92
- const checkExtraFiles = ({ projectDirectory, projectFiles }) => {
33
+ const checkExtraFiles = ({ projectFiles }) => {
93
34
  const standardFiles = new Set([
94
35
  ...REQUIRED_FILES,
95
36
  ...OPTIONAL_FILES,
@@ -101,27 +42,24 @@ const checkExtraFiles = ({ projectDirectory, projectFiles }) => {
101
42
  .filter((filePath) => !standardFiles.has(filePath))
102
43
  .map((filePath) => ({
103
44
  standard: "12.1",
104
- message: `${filePath} is not one of the seven constants files. ${suggestHomes({ projectDirectory, filePath })}`,
45
+ message: `${filePath} is not one of the seven constants files. ${NEXT_STEP}`,
105
46
  page: PAGE,
106
47
  }));
107
48
  };
108
49
 
109
- const checkComponentFiles = ({ projectDirectory, projectFiles }) =>
50
+ const checkComponentFiles = ({ projectFiles }) =>
110
51
  projectFiles
111
52
  .filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
112
53
  .filter((filePath) => !filePath.startsWith("node_modules/"))
113
54
  .filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
114
55
  .map((filePath) => ({
115
56
  standard: "12.1",
116
- message: `${filePath}: there is no component-level constants file. ${suggestHomes({ projectDirectory, filePath })}`,
57
+ message: `${filePath}: there is no component-level constants file. ${NEXT_STEP}`,
117
58
  page: PAGE,
118
59
  }));
119
60
 
120
- export const checkConstants = ({
121
- projectDirectory,
122
- projectFiles,
123
- }) => [
61
+ export const checkConstants = ({ projectFiles }) => [
124
62
  ...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
125
- ...checkExtraFiles({ projectDirectory, projectFiles }),
126
- ...checkComponentFiles({ projectDirectory, projectFiles }),
63
+ ...checkExtraFiles({ projectFiles }),
64
+ ...checkComponentFiles({ projectFiles }),
127
65
  ];
@@ -1,4 +1,4 @@
1
- // What setup asks the person and writes down: the four agent answers
1
+ // What setup asks the person and writes down: the five agent answers
2
2
  // (standard 21) and the colour palette (standard 11).
3
3
  import {
4
4
  CODING_STANDARDS_PATH,
@@ -12,6 +12,10 @@ const AGENT_ANSWERS = [
12
12
  { name: "the Linear project", pattern: /linear/i },
13
13
  { name: "the status circles", pattern: /status circles?/i },
14
14
  { name: "asking before committing", pattern: /commit/i },
15
+ {
16
+ name: "being told about decisions",
17
+ pattern: /told about decisions/i,
18
+ },
15
19
  ];
16
20
  // The template's unfilled line: "[link or None]", "[yes or no]".
17
21
  const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
@@ -5,14 +5,16 @@ import path from "node:path";
5
5
  import { PACKAGE_DIRECTORY } from "./projectFiles.mjs";
6
6
 
7
7
  // The names from the numbered list in docs/Guides/setup.md.
8
- const STANDARD_NAMES = {
8
+ export const STANDARD_NAMES = {
9
9
  4: "Every function and component has a test file",
10
10
  6: "ESLint",
11
11
  7: "Prettier",
12
12
  8: "Stylelint",
13
13
  9: "EditorConfig",
14
14
  10: "Node version",
15
+ 11: "Styling",
15
16
  12.1: "Constants",
17
+ 13: "Components live where they are used",
16
18
  15: "Design System Components",
17
19
  18: "Docs",
18
20
  21: "AGENTS.md and the agent skills",
@@ -17,16 +17,12 @@ import {
17
17
  readRecordedExceptions,
18
18
  } from "./projectFiles.mjs";
19
19
 
20
- const readPackageMajorVersion = () => {
20
+ const readPackageVersion = () => {
21
21
  const packageText = readFileSync(
22
22
  path.join(PACKAGE_DIRECTORY, "package.json"),
23
23
  "utf8",
24
24
  );
25
- const [majorVersion] = JSON.parse(packageText).version.split(
26
- ".",
27
- 1,
28
- );
29
- return Number(majorVersion);
25
+ return JSON.parse(packageText).version;
30
26
  };
31
27
 
32
28
  export const runChecks = ({ projectDirectory }) => {
@@ -43,11 +39,11 @@ export const runChecks = ({ projectDirectory }) => {
43
39
  ...checkAgentFiles({
44
40
  projectDirectory,
45
41
  templatesDirectory,
46
- packageMajorVersion: readPackageMajorVersion(),
42
+ packageVersion: readPackageVersion(),
47
43
  }),
48
44
  ...checkConfigFiles({ projectDirectory, templatesDirectory }),
49
45
  ...checkRequiredFiles({ templatesDirectory, projectFiles }),
50
- ...checkConstants({ projectDirectory, projectFiles }),
46
+ ...checkConstants({ projectFiles }),
51
47
  ...checkStructure({ projectFiles }),
52
48
  ...checkRecordedAnswers({ projectDirectory }),
53
49
  ...checkComponents({
@@ -42,6 +42,7 @@
42
42
  [How this project runs its work. These are the project's own decisions, not part of the code standards. Say where they are written up (usually `docs/development/`), then list the rules an agent must follow:]
43
43
 
44
44
  - **Who commits**: [whether AI agents may commit, push or make branches, and when. If the person said yes to asking before committing during setup: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, leave the asking rule out]
45
+ - **Decisions**: [Optional. If the person said yes to being told about decisions during setup: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." Delete this line if they said no]
45
46
  - **Branches**: [how branches are named]
46
47
  - **Commit messages**: [the commit message format]
47
48
  - **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
@@ -109,13 +110,15 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
109
110
 
110
111
  This project follows the Activatus Code Standards. They are installed as the `@activatus/code-standards` dev dependency: **read them in `node_modules/@activatus/code-standards/docs/`**, which is the exact version this project uses. The same pages are at https://activatus-code-standards.vercel.app for people.
111
112
 
112
- **Code standards version:** [the major version of the installed `@activatus/code-standards` package when the standards were last applied]
113
+ **Code standards version:** [the full version of the installed `@activatus/code-standards` package when the standards were last applied, such as 3.2.2]
113
114
 
114
- This is the version the code follows. It is the major version only: fixes such as 3.1.1 keep it at 3, but can still ask for changes, so read the Fixes for the installed version on every update. When the package is updated, read only the newer versions in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
115
+ This is the version the code follows, written in full so it pairs with the installed package. When the package is updated, read only the entries newer than this number in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
116
+
117
+ **The standards are the base, and you build freely from there.** Most of a project's code is something the standards never mention: decide it yourself, and keep the decision the same across the codebase. This covers how the code is built: its structure, names, files and where each value goes. It never covers what the product does, says or shows: those are product decisions, and you ask. Only skipping, loosening or changing a standard needs the person's yes.
115
118
 
116
119
  **Standards this project skips or changes** are listed, by number, in `docs/development/coding-standards.md`. Follow every other standard.
117
120
 
118
- **The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
121
+ **The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change and keep going. Never stop the work to wait for a new version of the standards. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
119
122
 
120
123
  Follow these rules in every change:
121
124
 
@@ -146,7 +149,7 @@ Follow these rules in every change:
146
149
  - **One parameter per function.** Use a single object when more than one value is needed.
147
150
  - **Return early.** Never nest more than three levels deep.
148
151
  - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every loose named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
149
- - **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. `animation.ts` holds how things move and `artwork.ts` what is drawn and where, each object kept whole with its numbers named by their keys, never lifted out into `numbers.ts`. `classNames.ts` holds Tailwind class strings shared between files, only when a component cannot hold them and they still repeat; a class name one file uses stays inline. Create each of these three only once there is something to put in it. These seven files are the only ones in `lib/constants/`, each never split by topic. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`, except inside a loop over the list, which looks each item up by an id typed `keyof typeof r.plans`. No separate id-to-link lookup objects such as `PLAN_ROUTES`: `r` already is the lookup. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
152
+ - **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of text people see or hear, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. `animation.ts` holds how and when things move and `artwork.ts` what is drawn, where it ends up and how it is grouped, each object kept whole with its numbers named by their keys, never lifted out into `numbers.ts`. `classNames.ts` holds Tailwind class strings shared between files, only when a component cannot hold them and they still repeat; a class name one file uses stays inline. Create each of these three only once there is something to put in it. These seven files are the only ones in `lib/constants/`, each never split by topic. Internal strings (ids, keys, event names, log messages) are not `s`: each is a key in the object that uses it, or a named constant at the top of the file that uses it. Where each value goes is the project's call: decide from the Constants table. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, and the work carries on. An id lives in the object that uses it, never as a loose constant; a list of keys a loop runs over stays a list. CSS goes in a stylesheet, never in a constant: styles for when JavaScript is off go in `globals.css` under `@media (scripting: none)`. A media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it, except internal strings, which stay with the code that uses them. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`, except inside a loop over the list, which looks each item up by a key typed `keyof typeof r.plans`. No separate lookup objects that map a key to its link: `r` already is the lookup. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
150
153
  - **No nested ternaries. No boolean flag parameters.**
151
154
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
152
155
  - **Named exports only**, except where a tool requires a default export.
@@ -16,7 +16,7 @@ Every Activatus project follows the same standards, so people and agents can mov
16
16
 
17
17
  [For each standard this project skips or changes, at setup or later: its number and name from the setup list, what is different, why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
18
18
 
19
- - Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no] ([YYYY-MM-DD]).
19
+ - Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no] ([YYYY-MM-DD]).
20
20
 
21
21
  ## Components for the standards
22
22