@activatus/code-standards 3.3.5 → 3.3.7

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.
@@ -131,7 +131,7 @@ The list has nothing about branches or commit messages. Those are the project's
131
131
 
132
132
  ## 4. Working with the agent
133
133
 
134
- 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.
134
+ Do this step every time, straight after step 3. Once the standards are agreed, offer the seven [Working with Agents](/docs/Standards/working-with-agents) options. All seven are optional: offer every one, every time, so the person can fill them in quickly and keep going.
135
135
 
136
136
  First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
137
137
 
@@ -165,7 +165,24 @@ Would you like AI to tell you about each coding decision
165
165
  it makes that the code standards do not cover? Yes or no?
166
166
  ```
167
167
 
168
- **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).
168
+ Then **ship**. **Print this to the person exactly as it is written**:
169
+
170
+ ```text
171
+ When you say "ship", should AI commit the change, push it and
172
+ open a Pull Request that describes what changed and why?
173
+ Yes or no?
174
+ ```
175
+
176
+ Then the **response format**. **Print this to the person exactly as it is written**:
177
+
178
+ ```text
179
+ Response format (optional). Want the agent to answer with a
180
+ clear structure — a short overview of the problem, results
181
+ in tables, numbered action steps, and what it needs from
182
+ you next? Yes or no?
183
+ ```
184
+
185
+ **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. If they said yes to ship, write under **Ship**: "When the person says 'ship', commit the current change, push it, and open a Pull Request. 'Ship' is the yes for those three steps, for that change only. The Pull Request description says why the change was made, what changed, how it was checked, with the results, and what the reviewer should look at closely, and links the ticket." If they said no, delete the Ship line. If they said yes to the response format, write the **Response format** section from the template's Project workflow into `AGENTS.md`, under Project workflow, after the Status circles section, or at the end of Project workflow if there is none. If they said no, write nothing about it. Write all seven 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]; ship [yes or no]; response format [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
169
186
 
170
187
  ## 5. Apply the standards
171
188
 
@@ -214,7 +231,7 @@ anything that is wrong.
214
231
 
215
232
  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.
216
233
 
217
- 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.
234
+ 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, being told about decisions, ship and the response format. Ask the person any that are not recorded, and record them as step 4 says.
218
235
  2. **Run the [standards check](#checking-a-project)**, and fix what it finds.
219
236
  3. **Tell the person** what you changed, or that the project was already up to date.
220
237
 
@@ -270,7 +287,7 @@ It reports, and never changes a file. Each finding gives the standard's number a
270
287
  | 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 |
271
288
  | 12.1 | `lib/constants/` has `index.ts`, `routes.ts` and `strings.ts`, and no `unsortedValues.ts` is left waiting |
272
289
  | 13 | `components/` holds only `ui/`, `layout/` and `shared/`, every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
273
- | 21 | `docs/development/coding-standards.md` records the five agent answers under "Details", and every numbered line there is a well-formed exception |
290
+ | 21 | `docs/development/coding-standards.md` records the seven agent answers under "Details", and every numbered line there is a well-formed exception |
274
291
  | 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
275
292
  | 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
276
293
  | 4 | Every file that exports a function or component has a test file beside it |
@@ -73,8 +73,8 @@ Create `eslint.config.mjs` in your project root. Each config passes its own rule
73
73
  ### Base (JavaScript / Node.js)
74
74
 
75
75
  ```js title="eslint.config.mjs"
76
- import js from "@eslint/js";
77
76
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
77
+ import js from "@eslint/js";
78
78
  import prettier from "eslint-config-prettier";
79
79
  import { flatConfigs as importX } from "eslint-plugin-import-x";
80
80
  import unicorn from "eslint-plugin-unicorn";
@@ -215,8 +215,8 @@ export default config;
215
215
  ### TypeScript
216
216
 
217
217
  ```js title="eslint.config.mjs"
218
- import js from "@eslint/js";
219
218
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
219
+ import js from "@eslint/js";
220
220
  import prettier from "eslint-config-prettier";
221
221
  import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
222
222
  import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -440,8 +440,8 @@ TypeScript files are checked by the compiler, so `no-undef` is off for them. The
440
440
  Start from the [TypeScript](#typescript) config and make five changes:
441
441
 
442
442
  ```js title="eslint.config.mjs"
443
- import js from "@eslint/js";
444
443
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
444
+ import js from "@eslint/js";
445
445
  import prettier from "eslint-config-prettier";
446
446
  import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
447
447
  import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -690,10 +690,10 @@ Keep `settings.react.version` set rather than `"detect"`; change the number in `
690
690
 
691
691
  ```js title="eslint.config.mjs"
692
692
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
693
- import prettier from "eslint-config-prettier";
694
- import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
695
693
  import nextVitals from "eslint-config-next/core-web-vitals";
696
694
  import nextTypescript from "eslint-config-next/typescript";
695
+ import prettier from "eslint-config-prettier";
696
+ import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
697
697
  import { flatConfigs as importX } from "eslint-plugin-import-x";
698
698
  import unicorn from "eslint-plugin-unicorn";
699
699
  import globals from "globals";
@@ -1000,24 +1000,30 @@ Add scripts to `package.json`:
1000
1000
 
1001
1001
  ## Third-party code is exempt
1002
1002
 
1003
- **The standards apply to code we write. They do not apply to packages we pull in.**
1003
+ **The standards apply to code we write. They do not apply to packages we pull in, or to files a tool generates and replaces wholesale.**
1004
1004
 
1005
- | Code | Linted? |
1006
- | ------------------------------------------------- | ------------------------------------ |
1007
- | Our own code | ✅ Yes — every rule applies |
1008
- | `node_modules/` | ❌ No — ESLint ignores it by default |
1009
- | `vendor/` (third-party code copied into the repo) | ❌ No — ignored by the config |
1010
- | Build output (`dist/`, `build/`, `.next/`) | ❌ No — ignored by the config |
1005
+ | Code | Linted? |
1006
+ | ------------------------------------------------------- | ------------------------------------ |
1007
+ | Our own code | ✅ Yes — every rule applies |
1008
+ | `node_modules/` | ❌ No — ESLint ignores it by default |
1009
+ | `vendor/` (third-party or generated code we never edit) | ❌ No — ignored by the config |
1010
+ | Build output (`dist/`, `build/`, `.next/`) | ❌ No — ignored by the config |
1011
1011
 
1012
1012
  Third-party code that is copied into the repository lives in a `vendor/` folder, at any level. The configs ignore `**/vendor/**`, so it is never linted.
1013
1013
 
1014
- - **Do not fix lint errors in third-party code.** It is not ours, and the fix would be lost on the next update.
1014
+ **Generated code lives in `vendor/` too.** A file a tool writes and rewrites is not ours any more than a copied-in package: nobody hand-edits it, and it is replaced wholesale each time it changes. The main case is **database types a CLI regenerates**, such as the Supabase types rewritten after every migration. They live in `vendor/`, at any level, and are never linted.
1015
+
1016
+ - **Do not fix lint errors in third-party or generated code.** It is not ours, and the fix would be lost the next time the tool runs.
1015
1017
  - **Do not rename or restructure it** to match our naming or folder rules.
1016
1018
  - **Do not add `eslint-disable` comments to it.** Put it in `vendor/` instead.
1017
1019
 
1020
+ ### Code an AI agent writes is ours
1021
+
1022
+ **Who wrote the code does not matter — whether they edit it does.** Code an AI agent generates is our code, and every standard applies to it. The same goes for a script we write to drive a tool, such as a database migration or a seed script: we write it, we read it, we maintain it, so it is linted and held to the standards like any other file.
1023
+
1018
1024
  ### Copied-in code we maintain is ours
1019
1025
 
1020
- `vendor/` is only for third-party code we **do not change** — code that is replaced wholesale when the package updates.
1026
+ `vendor/` is only for code we **do not change** — third-party code copied in, and generated files the tool replaces wholesale.
1021
1027
 
1022
1028
  Code that is copied into the project and then **owned and edited by us** is our code, and every standard applies to it. The main case is **shadcn/ui**: the CLI copies component source into the project, and from then on it is ours. It is converted to our standards and lives in `components/ui/`, never in `vendor/`. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
1023
1029
 
@@ -1025,6 +1031,9 @@ Code that is copied into the project and then **owned and edited by us** is our
1025
1031
  | --------------------------------------------------------- | ------- | ------------------------------------------ |
1026
1032
  | A package installed with `pnpm add` | No | No |
1027
1033
  | Third-party code copied in and left untouched (`vendor/`) | No | No |
1034
+ | Files a tool regenerates (`vendor/`) | No | No |
1035
+ | Code an AI agent writes | **Yes** | **Yes** |
1036
+ | A script we write to drive a tool | **Yes** | **Yes** |
1028
1037
  | shadcn components added with the CLI | **Yes** | **Yes — convert them when they are added** |
1029
1038
  | Code generated once and then edited by us | **Yes** | **Yes** |
1030
1039
 
@@ -35,7 +35,16 @@ Create `stylelint.config.mjs` in your project root:
35
35
  @type {import("stylelint").Config}
36
36
  */
37
37
  const config = {
38
- ignoreFiles: ["**/vendor/**"],
38
+ // Generated CSS, and the docs viewer, which is the standard template
39
+ // with its own build. Only the project's hand-written CSS is linted.
40
+ ignoreFiles: [
41
+ ".next/**",
42
+ "out/**",
43
+ "build/**",
44
+ "coverage/**",
45
+ "docsSite/**",
46
+ "**/vendor/**",
47
+ ],
39
48
  extends: [
40
49
  "stylelint-config-standard",
41
50
  "stylelint-config-recess-order",
@@ -84,7 +93,16 @@ export default config;
84
93
  @type {import("stylelint").Config}
85
94
  */
86
95
  const config = {
87
- ignoreFiles: ["**/vendor/**"],
96
+ // Generated CSS, and the docs viewer, which is the standard template
97
+ // with its own build. Only the project's hand-written CSS is linted.
98
+ ignoreFiles: [
99
+ ".next/**",
100
+ "out/**",
101
+ "build/**",
102
+ "coverage/**",
103
+ "docsSite/**",
104
+ "**/vendor/**",
105
+ ],
88
106
  extends: [
89
107
  "stylelint-config-standard-scss",
90
108
  "stylelint-config-recess-order",
@@ -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, 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`.
8
+ > How an AI agent links a project's work, reports on it, asks before committing, tells the person about its decisions, ships a change and answers in a readable shape. The GitHub repo, the Linear project, the status circles, asking before every commit and push, being told about decisions, ship and the response format are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all seven 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
 
@@ -49,3 +49,52 @@ Optional. Setup asks: "Would you like AI to ask you before every commit and push
49
49
  ## Told about decisions
50
50
 
51
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.
52
+
53
+ ## Ship
54
+
55
+ Optional. Setup asks: "When you say 'ship', should AI commit the change, push it and open a Pull Request that describes what changed and why?" It is a project workflow choice, not a code standard. A yes is written under **Ship** in Project workflow. When the person says "ship", the agent:
56
+
57
+ 1. **Commits the current change**, with the project's commit message format.
58
+ 2. **Pushes it** to its branch.
59
+ 3. **Opens a Pull Request** whose description a reviewer can work from without asking:
60
+ - **Why:** the problem or ticket the change answers.
61
+ - **What changed:** each change, by area or file, in plain words.
62
+ - **How it was checked:** the commands run and their results, and anything tested by hand.
63
+ - **Look closely at:** anything risky, unfinished or worth a second opinion. "Nothing" if there is nothing.
64
+ - **The ticket**, linked, when there is one.
65
+
66
+ **"Ship" is the yes for those three steps, for the change in hand only.** It never carries over to the next change. A project that asks before every commit and push still does: "ship" is that yes. A no means the Ship line is deleted, and the person asks for each step themselves.
67
+
68
+ ## Response format
69
+
70
+ Optional. Setup asks: "Want the agent to answer with a clear structure — a short overview of the problem, results in tables, numbered action steps, and what it needs from you next?" A yes is written as the **Response format** section in Project workflow. Then every substantive reply — anything with findings, results, options or a plan — follows the same shape, and a plain yes or no stays plain:
71
+
72
+ 1. **The status line first**, when status circles are on: where the work is up to.
73
+ 2. **An overview** — what happened or what was found, in a line or two.
74
+ 3. **Each problem plainly** — what is wrong and why it matters.
75
+ 4. **Results in tables** — one row per item.
76
+ 5. **"How to fix it" as numbered steps.**
77
+ 6. **The next action as a question.**
78
+
79
+ Emojis are welcome where they make the reply quicker to read — a ✅/❌ per row in a results table, 🎉 when something lands. The seven status circles appear only on a status line, never as decoration: a ✅/❌ tick in a results table marks pass and fail, not the circle's status meaning.
80
+
81
+ ```md title="A reply in the response format"
82
+ 🟣 Response format: template, setup and docs done; the checker is left.
83
+
84
+ I added the response format as a setup choice, like status circles. One problem: the recorded-answers check only knows six answers, so `standards:check` would pass a project that said yes without the answer recorded.
85
+
86
+ | File | Result |
87
+ | --- | --- |
88
+ | AGENTS.md template | ✅ Response format section added |
89
+ | Setup step 4 | ✅ Seventh offer added |
90
+ | working-with-agents.md | ✅ This section |
91
+ | checkRecordedAnswers.mjs | ❌ Missing the seventh answer |
92
+
93
+ How to fix it:
94
+
95
+ 1. Add the response format to the checker's list of answers.
96
+ 2. Update the checker's test to expect seven answers.
97
+ 3. Run the tests and `pnpm standards:check`.
98
+
99
+ Want me to finish the checker now?
100
+ ```
@@ -100,6 +100,31 @@ app/api/
100
100
 
101
101
  ---
102
102
 
103
+ ## 🚪 Route handlers outside `app/api/`
104
+
105
+ **A `route.ts` anywhere in `app/` is a route handler**, not just under `app/api/`. Next.js gives every `route.ts` the URL its folder path describes, so a handler lives outside `app/api/` when its URL is not an API endpoint but a page-shaped stop on the way somewhere else. The main case is an **auth callback**: a URL the identity provider sends the browser back to, which reads the result and redirects on, like `app/sign-in/confirm/route.ts` serving `/sign-in/confirm`.
106
+
107
+ **The same rules apply outside `app/api/`**: kebab-case folders, the file is `route.ts`, and every other standard holds. A handler that returns JSON belongs under `app/api/`; a handler that redirects or rewrites belongs at the URL the outside world already expects, which is usually not under `app/api/`.
108
+
109
+ ### Named exports
110
+
111
+ **Handlers are exported as named functions, never a default export.** Next.js wires the HTTP method by the export's name:
112
+
113
+ ```typescript
114
+ // ✅ Correct — named export per HTTP method
115
+ export async function GET(request: Request) { … }
116
+ export async function POST(request: Request) { … }
117
+
118
+ // ❌ Incorrect — a default export does nothing
119
+ export default async function handler(request: Request) { … }
120
+ ```
121
+
122
+ ### Where a handler's helpers go
123
+
124
+ Functions written for one route handler follow the [utils ladder](/docs/Structure/folder-structure#-utils): a helper only this handler uses goes in that section's `utils/` folder, and a helper used across the app goes in the global `utils/`. Code that talks to an outside service goes in `lib/integrations/`, never in the handler file itself.
125
+
126
+ ---
127
+
103
128
  ## 🔒 Security Best Practices
104
129
 
105
130
  - **Validate input** - Use Zod schemas
@@ -87,7 +87,7 @@ project-root/
87
87
  │ │ ├── formatDate.test.ts
88
88
  │ │ └── index.ts
89
89
  │ └── index.ts # Exports every function
90
- ├── hooks/ # Custom React hooks
90
+ ├── hooks/ # Custom React hooks used across the app
91
91
  ├── services/ # Business logic: what the app does
92
92
  ├── stores/ # State management stores
93
93
  ├── styles/ # Global styles
@@ -296,6 +296,18 @@ Add the export to `utils/index.ts` whenever you add a function.
296
296
  - **Import from the `utils` folder**, never from the files inside it.
297
297
  - **Keep UI files clean.** If a function could be written in another file, it does not belong in the component file. See [Writing a component](/docs/Structure/component-organization#-writing-a-component).
298
298
 
299
+ ### Hooks live the same way {#hooks-live-the-same-way}
300
+
301
+ **A custom hook follows the same ladder as a util.** It starts in the component's `hooks/`, moves to the section's `hooks/` when another component in the section needs it, and moves to the global `hooks/` folder at the project root when anything outside the section needs it:
302
+
303
+ | Used by | Location | Example |
304
+ | ------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
305
+ | The whole app | Global `hooks/` folder at the project root | `hooks/useMediaQuery/` |
306
+ | One section | A `hooks/` folder in that section's route group | `app/(billing)/hooks/useInvoiceTotals/` |
307
+ | One component | A `hooks/` folder inside that component's folder | `app/(billing)/components/invoiceTable/hooks/useSortedInvoices/` |
308
+
309
+ The folder shape is the same too: **one folder per hook**, named after it (`useUserData/useUserData.ts`), with the hook, its test file and an `index.ts`, and an `index.ts` in the `hooks/` folder that exports them all. A hook used by more than one component, or that wraps stateful logic a component should not hold itself, goes in a `hooks/` folder from the start, never inside the component file.
310
+
299
311
  ---
300
312
 
301
313
  ## 🔤 Constants: `r`, `s` and shared values {#constants}
@@ -100,6 +100,8 @@ This applies to everyone building components, **including AI agents**.
100
100
  | 54 | **Button** | primary, secondary, ghost | link<br />size (small/medium/large)<br />icon<br />iconPosition<br />fullWidth (boolean) |
101
101
  | 55 | **Cookie Banner** | — | text (richtext)<br />acceptLabel<br />rejectLabel<br />policyLink |
102
102
 
103
+ **There is no Select component.** A field where the person picks one option from a list is an **Input with `type: select`** (or `type: dropdown` or `type: auto-select`), with the choices passed through its `options` prop. Build it as an Input, never as a standalone component — a separate Select would duplicate Input's name, label, help text, validation and error states.
104
+
103
105
  ## Utility (low-level primitives)
104
106
 
105
107
  | # | Component | Variants | Key props |
package/docs/ontology.md CHANGED
@@ -60,17 +60,18 @@ The words stay the same everywhere. Only the casing changes, to match where the
60
60
 
61
61
  ### People and agents
62
62
 
63
- | Term | Means |
64
- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
65
- | `human` | A person, as opposed to an agent |
66
- | `developer` | A human who writes code |
67
- | `agent` | An AI that writes or checks code, such as Claude Code. It follows every standard a developer does |
68
- | `agent_spec` | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/docs/Standards/agent-specs) |
69
- | `agent_harness` | Everything around an agent that runs it: the program it runs in (such as Claude Code), its instructions, the tools and permissions it has, and the rules it follows. The ontology says what words mean; the harness says how an agent behaves |
70
- | `context` | Everything an agent is given to read for its task: the agent spec, the docs and the code it is working on |
71
- | `tool` | One action an agent is allowed to take, such as editing a file or running the tests. Tools come from the agent harness or an MCP server |
72
- | `model` | The AI model an agent thinks with |
73
- | `mcp` | Model Context Protocol: the standard way to connect an agent to outside tools and data, such as Linear or GitHub. An MCP server offers tools, and the agent calls them |
63
+ | Term | Means |
64
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
65
+ | `human` | A person, as opposed to an agent |
66
+ | `developer` | A human who writes code |
67
+ | `agent` | An AI that writes or checks code, such as Claude Code. It follows every standard a developer does |
68
+ | `agent_spec` | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/docs/Standards/agent-specs) |
69
+ | `agent_harness` | Everything around an agent that runs it: the program it runs in (such as Claude Code), its instructions, the tools and permissions it has, and the rules it follows. The ontology says what words mean; the harness says how an agent behaves |
70
+ | `context` | Everything an agent is given to read for its task: the agent spec, the docs and the code it is working on |
71
+ | `tool` | One action an agent is allowed to take, such as editing a file or running the tests. Tools come from the agent harness or an MCP server |
72
+ | `model` | The AI model an agent thinks with |
73
+ | `ship` | To commit the current change, push it, and open a Pull Request that says why the change was made, what changed, how it was checked and what to look at closely. Only in a project that said yes to it during setup, and only for that one change. See [Ship](/docs/Standards/working-with-agents#ship) |
74
+ | `mcp` | Model Context Protocol: the standard way to connect an agent to outside tools and data, such as Linear or GitHub. An MCP server offers tools, and the agent calls them |
74
75
 
75
76
  ### Code
76
77
 
@@ -0,0 +1,373 @@
1
+ # Agent Response Format Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Add an optional "Response format" setup choice so every dev agent answers with a structured reply — status line first, overview, problems plainly, tables, numbered steps, closing question.
6
+
7
+ **Architecture:** A new `### Response format` subsection in the AGENTS.md template's Project workflow (outside the managed markers), offered by setup step 4 as the seventh question, recorded like the other six answers, and validated by the recorded-answers checker. No version bump: the repo stays on 3.3.7.
8
+
9
+ **Tech Stack:** Markdown docs and templates, plain Node ESM scripts, `node --test`, Prettier.
10
+
11
+ **Standing rule for every commit step:** ask Tom "Ready to commit and push — want me to?" and wait for a clear yes to that specific action. Never commit without it.
12
+
13
+ **Spec:** `docs/superpowers/specs/2026-11-17-agent-response-format-design.md`
14
+
15
+ ---
16
+
17
+ ### Task 1: The `### Response format` section in the AGENTS.md template
18
+
19
+ **Files:**
20
+
21
+ - Modify: `static/templates/AGENTS.md` (insert after the Status circles section, which ends at line 76 with the "- Only what the person needs to act on..." list; before `## Environment variables` at line 78)
22
+
23
+ - [ ] **Step 1: Insert the section**
24
+
25
+ Between the end of `### Status circles` (after the line `- Only what the person needs to act on. Leave out what they already know.`) and `## Environment variables`, insert:
26
+
27
+ ```markdown
28
+ ### Response format
29
+
30
+ [Only if the person chose the response format during setup. Otherwise delete this section.]
31
+
32
+ Answer every substantive reply — anything with findings, results, options or a plan — in this shape. A plain acknowledgement of a yes or no stays plain.
33
+
34
+ 1. **The status line first**, when status circles are on: where the work is up to, before anything else, in the format the Status circles section defines.
35
+ 2. **An overview** — one or two lines: what happened or what was found, before any detail.
36
+ 3. **Each problem named plainly** — what is wrong and why it matters, one per item, not buried in prose.
37
+ 4. **Results and comparisons in tables** — check results, before and after, options — one row per item.
38
+ 5. **"How to fix it" as numbered steps**, each concrete enough to action on its own.
39
+ 6. **The next action as a question**, so the person only has to answer it.
40
+
41
+ **Emojis where they help, not everywhere.** Use them when they make the reply quicker to read than a slab of text — ✅/❌ per row in a results table, 🎉 when something lands, 🔧 for work in progress. The whole range is welcome; not every reply needs them. **Traffic-light circles are the exception:** the seven status circles (✅ 🟢 🟣 🟡 🟠 🔴 ⚪) carry one meaning each from the Status circles section and appear only on a status line. For flavour use other symbols. A ✅/❌ tick in a results table marks pass and fail, which is fine.
42
+ ```
43
+
44
+ - [ ] **Step 2: Check formatting and the agent-files check**
45
+
46
+ Run: `pnpm format:check` and `node --test scripts/verifyStandards/checkAgentFiles.test.mjs`
47
+ Expected: both pass. The new section sits outside the `<!-- code-standards:start/end -->` markers, so `checkAgentFiles` must not report a template difference.
48
+
49
+ - [ ] **Step 3: Commit** (ask Tom first — see the standing rule)
50
+
51
+ ```bash
52
+ git add static/templates/AGENTS.md
53
+ git commit -m "feat: response format section in the AGENTS.md template"
54
+ ```
55
+
56
+ ---
57
+
58
+ ### Task 2: The seventh slot in the template's answers line
59
+
60
+ **Files:**
61
+
62
+ - Modify: `static/templates/docs/development/coding-standards.md:19`
63
+
64
+ - [ ] **Step 1: Extend the unfilled answers line**
65
+
66
+ Change line 19 from:
67
+
68
+ ```markdown
69
+ - 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]; ship [yes or no] ([YYYY-MM-DD]).
70
+ ```
71
+
72
+ to:
73
+
74
+ ```markdown
75
+ - 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]; ship [yes or no]; response format [yes or no] ([YYYY-MM-DD]).
76
+ ```
77
+
78
+ - [ ] **Step 2: Check formatting**
79
+
80
+ Run: `pnpm format:check`
81
+ Expected: passes
82
+
83
+ - [ ] **Step 3: Commit** (ask Tom first)
84
+
85
+ ```bash
86
+ git add static/templates/docs/development/coding-standards.md
87
+ git commit -m "feat: response format slot in the template's recorded answers"
88
+ ```
89
+
90
+ ---
91
+
92
+ ### Task 3: The checker learns the seventh answer (TDD)
93
+
94
+ **Files:**
95
+
96
+ - Modify: `scripts/verifyStandards/checkRecordedAnswers.test.mjs`
97
+ - Modify: `scripts/verifyStandards/checkRecordedAnswers.mjs`
98
+
99
+ - [ ] **Step 1: Update the failing test**
100
+
101
+ In `checkRecordedAnswers.test.mjs`, make these changes:
102
+
103
+ a. The `ALL_ANSWERS` constant becomes (the recorded line gains `; response format yes`):
104
+
105
+ ```js
106
+ const ALL_ANSWERS = `## Details
107
+
108
+ - Working with the agent: GitHub repo https://github.com/example/site; Linear project None; status circles yes; ask before every commit and push yes; told about decisions no; ship yes; response format yes (2026-10-23).
109
+
110
+ ## Related
111
+ `;
112
+ ```
113
+
114
+ b. The test named `"passes all six answers and a filled-in palette"` is renamed to `"passes all seven answers and a filled-in palette"` (assert stays `[]`).
115
+
116
+ c. The template's unfilled answers line in `"flags the template's unfilled answers line"` gains the seventh slot, and the expected count goes from 6 to 7:
117
+
118
+ ```js
119
+ const findings = check({
120
+ "docs/development/coding-standards.md":
121
+ "## Details\n\n- 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]; ship [yes or no]; response format [yes or no] ([YYYY-MM-DD]).\n",
122
+ "docs/design/design-system.md": PALETTE,
123
+ });
124
+ assert.equal(findings.length, 7);
125
+ ```
126
+
127
+ d. The test named `"flags each missing agent answer"` expects one more finding (GitHub recorded, the other six missing), and the first finding's message stays the Linear project:
128
+
129
+ ```js
130
+ assert.equal(findings.length, 6);
131
+ assert.match(findings[0].message, /the Linear project/);
132
+ ```
133
+
134
+ e. Add a new test after `"flags a project set up before ship was asked"`:
135
+
136
+ ```js
137
+ it("flags a project set up before the response format was asked", () => {
138
+ const findings = check({
139
+ "docs/development/coding-standards.md": ALL_ANSWERS.replace(
140
+ "; response format yes",
141
+ "",
142
+ ),
143
+ "docs/design/design-system.md": PALETTE,
144
+ });
145
+ assert.equal(findings.length, 1);
146
+ assert.match(findings[0].message, /does not record the response format/);
147
+ });
148
+ ```
149
+
150
+ - [ ] **Step 2: Run the test to verify it fails**
151
+
152
+ Run: `node --test scripts/verifyStandards/checkRecordedAnswers.test.mjs`
153
+ Expected: FAIL — the new test fails because the checker does not know the response format yet
154
+
155
+ - [ ] **Step 3: Implement the seventh answer**
156
+
157
+ In `checkRecordedAnswers.mjs`, change the header comment from "the six agent answers" to "the seven agent answers", and add the seventh entry to `AGENT_ANSWERS` after the ship entry:
158
+
159
+ ```js
160
+ // What setup asks the person and writes down: the seven agent answers
161
+ // (standard 21) and the colour palette (standard 11).
162
+ ```
163
+
164
+ ```js
165
+ { name: "ship", pattern: /\bship\b/i },
166
+ { name: "the response format", pattern: /response format/i },
167
+ ];
168
+ ```
169
+
170
+ - [ ] **Step 4: Run the test to verify it passes**
171
+
172
+ Run: `node --test scripts/verifyStandards/checkRecordedAnswers.test.mjs`
173
+ Expected: PASS, all tests green
174
+
175
+ - [ ] **Step 5: Run the whole test suite**
176
+
177
+ Run: `pnpm test`
178
+ Expected: passes
179
+
180
+ - [ ] **Step 6: Commit** (ask Tom first)
181
+
182
+ ```bash
183
+ git add scripts/verifyStandards/checkRecordedAnswers.mjs scripts/verifyStandards/checkRecordedAnswers.test.mjs
184
+ git commit -m "feat: recorded-answers check learns the response format"
185
+ ```
186
+
187
+ ---
188
+
189
+ ### Task 4: Setup offers the seventh question
190
+
191
+ **Files:**
192
+
193
+ - Modify: `docs/Guides/setup.md` (lines 134, 168–176, 225, 281)
194
+
195
+ - [ ] **Step 1: Update the section count at line 134**
196
+
197
+ Change:
198
+
199
+ ```markdown
200
+ Do this step every time, straight after step 3. Once the standards are agreed, offer the six [Working with Agents](/docs/Standards/working-with-agents) options. All six are optional: offer every one, every time, so the person can fill them in quickly and keep going.
201
+ ```
202
+
203
+ to:
204
+
205
+ ```markdown
206
+ Do this step every time, straight after step 3. Once the standards are agreed, offer the seven [Working with Agents](/docs/Standards/working-with-agents) options. All seven are optional: offer every one, every time, so the person can fill them in quickly and keep going.
207
+ ```
208
+
209
+ - [ ] **Step 2: Add the printed offer after the ship offer**
210
+
211
+ After the ship offer's code block (which ends with `Yes or no?` and the closing fence, before the "Record the answers" paragraph), insert:
212
+
213
+ ````markdown
214
+ Then the **response format**. **Print this to the person exactly as it is written**:
215
+
216
+ ```text
217
+ Response format (optional). Want the agent to answer with a
218
+ clear structure — a short overview of the problem, results
219
+ in tables, numbered action steps, and what it needs from
220
+ you next? Yes or no?
221
+ ```
222
+ ````
223
+
224
+ - [ ] **Step 3: Extend the "Record the answers" paragraph**
225
+
226
+ Two changes in the paragraph at line 176:
227
+
228
+ a. After the sentence about ship ("If they said no, delete the Ship line."), insert:
229
+
230
+ ```markdown
231
+ If they said yes to the response format, write the **Response format** section from the template's Project workflow into `AGENTS.md`, under Project workflow, after the Status circles section. If they said no, write nothing about it.
232
+ ```
233
+
234
+ b. Change `Write all six answers` to `Write all seven answers`, and extend the recorded line:
235
+
236
+ ```markdown
237
+ `- 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]; ship [yes or no]; response format [yes or no] ([date]).`
238
+ ```
239
+
240
+ - [ ] **Step 4: Update "Already on this version" step 1 (line 225)**
241
+
242
+ Change the answer list to include the new one:
243
+
244
+ ```markdown
245
+ 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, being told about decisions, ship and the response format. Ask the person any that are not recorded, and record them as step 4 says.
246
+ ```
247
+
248
+ - [ ] **Step 5: Update the check table row (line 281)**
249
+
250
+ Change `records the six agent answers` to `records the seven agent answers`.
251
+
252
+ - [ ] **Step 6: Check formatting**
253
+
254
+ Run: `pnpm format:check`
255
+ Expected: passes
256
+
257
+ - [ ] **Step 7: Commit** (ask Tom first)
258
+
259
+ ```bash
260
+ git add docs/Guides/setup.md
261
+ git commit -m "docs: setup offers the response format as the seventh question"
262
+ ```
263
+
264
+ ---
265
+
266
+ ### Task 5: The Working with Agents docs section
267
+
268
+ **Files:**
269
+
270
+ - Modify: `docs/Standards/working-with-agents.md` (intro at line 8, new section after Ship)
271
+
272
+ - [ ] **Step 1: Update the intro**
273
+
274
+ Change line 8 from:
275
+
276
+ ```markdown
277
+ > How an AI agent links a project's work, reports on it, asks before committing, tells the person about its decisions and ships a change. The GitHub repo, the Linear project, the status circles, asking before every commit and push, being told about decisions and ship are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all six 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`.
278
+ ```
279
+
280
+ to:
281
+
282
+ ```markdown
283
+ > How an AI agent links a project's work, reports on it, asks before committing, tells the person about its decisions, ships a change and answers in a readable shape. The GitHub repo, the Linear project, the status circles, asking before every commit and push, being told about decisions, ship and the response format are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all seven 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`.
284
+ ```
285
+
286
+ - [ ] **Step 2: Add the Response format section at the end of the file**
287
+
288
+ After the Ship section (end of file), append:
289
+
290
+ ````markdown
291
+ ## Response format
292
+
293
+ Optional. Setup asks: "Would you like the agent to answer with a clear structure — a short overview of the problem, results in tables, numbered action steps, and what it needs from you next?" A yes is written as the **Response format** section in Project workflow. Then every substantive reply — anything with findings, results, options or a plan — follows the same shape, and a plain acknowledgement of a yes or no stays plain:
294
+
295
+ 1. **The status line first**, when status circles are on: where the work is up to.
296
+ 2. **An overview** — what happened or what was found, in a line or two.
297
+ 3. **Each problem plainly** — what is wrong and why it matters.
298
+ 4. **Results in tables** — one row per item.
299
+ 5. **"How to fix it" as numbered steps.**
300
+ 6. **The next action as a question.**
301
+
302
+ Emojis are welcome where they make the reply quicker to read — a ✅/❌ per row in a results table, 🎉 when something lands. The seven status circles appear only on a status line, never as decoration.
303
+
304
+ ```md title="A reply in the response format"
305
+ 🟣 Response format: template, setup and docs done; the checker is left.
306
+
307
+ I added the response format as a setup choice, like status circles. One problem: the recorded-answers check only knows six answers, so `standards:check` would pass a project that said yes without the answer recorded.
308
+
309
+ | File | Result |
310
+ | --- | --- |
311
+ | AGENTS.md template | ✅ Response format section added |
312
+ | Setup step 4 | ✅ Seventh offer added |
313
+ | working-with-agents.md | ✅ This section |
314
+ | checkRecordedAnswers.mjs | ❌ Missing the seventh answer |
315
+
316
+ How to fix it:
317
+
318
+ 1. Add the response format to the checker's list of answers.
319
+ 2. Update the checker's test to expect seven answers.
320
+ 3. Run the tests and `pnpm standards:check`.
321
+
322
+ Want me to finish the checker now?
323
+ ```
324
+ ````
325
+
326
+ - [ ] **Step 3: Check formatting**
327
+
328
+ Run: `pnpm format:check`
329
+ Expected: passes
330
+
331
+ - [ ] **Step 4: Commit** (ask Tom first)
332
+
333
+ ```bash
334
+ git add docs/Standards/working-with-agents.md
335
+ git commit -m "docs: response format in Working with Agents, with a worked example"
336
+ ```
337
+
338
+ ---
339
+
340
+ ### Task 6: Full verification and the left-to-do note
341
+
342
+ **Files:**
343
+
344
+ - Modify: `docs/superpowers/specs/2026-11-17-agent-response-format-design.md` (no change expected — this task only verifies it matches what was built)
345
+
346
+ - [ ] **Step 1: Run the repo checks**
347
+
348
+ ```bash
349
+ pnpm test
350
+ pnpm format:check
351
+ pnpm typecheck
352
+ ```
353
+
354
+ Expected: all pass
355
+
356
+ - [ ] **Step 2: Run `pnpm devtest`** (the standards are not ready until it passes)
357
+
358
+ Run: `pnpm devtest`
359
+ Expected: passes — it lints and formats every template the way a project does
360
+
361
+ - [ ] **Step 3: Self-review against the spec**
362
+
363
+ Read the spec's Changes table row by row and point at the change in the working tree for each. Confirm:
364
+
365
+ - The template section sits outside the managed markers and `checkAgentFiles` still passes.
366
+ - "six" appears nowhere in the step-4 flow except the historical version-history entry (line 79 of `docs/version-history.md`, which stays untouched).
367
+ - The worked example's status line comes first and uses no traffic-light circle beyond the status line.
368
+
369
+ - [ ] **Step 4: Leave a note for the release**
370
+
371
+ The next version release (3.3.8 or later, whichever ships first) must add a version-history entry, same shape as ship's at `docs/version-history.md:79`: "A seventh setup question, the response format…", plus "records the seven agent answers" in its era of the check table. Record this as a leftover in the handover summary to Tom, not in a released version entry — the repo stays on 3.3.7.
372
+
373
+ - [ ] **Step 5: Commit anything left** (ask Tom first, per the standing rule)
@@ -0,0 +1,48 @@
1
+ # Agent Response Format — Design
2
+
3
+ **Status:** Decided · **Updated:** 2026-11-17
4
+
5
+ ## Decision
6
+
7
+ Add an optional **Response format** choice to project setup, recorded in each project's `AGENTS.md` so every dev agent (Claude Code, Codex, ChatGPT, any agent that reads `AGENTS.md`) answers with the same clear structure Claude gives: an overview of the problem, results in tables, numbered action steps, a status line, and a closing question.
8
+
9
+ The choice works like status circles: setup offers it, and only a yes writes the section. It is a project-workflow choice, not a numbered code standard, so it never sits inside the managed code-standards markers. The repo stays on version 3.3.7 for now: the version-history entry (same shape as ship's "sixth setup question" entry) is written when the next version goes out, and that release is also what asks existing projects the seventh question.
10
+
11
+ ## The format
12
+
13
+ When the section is present, every **substantive reply** uses it — anything with findings, results, options or a plan. A plain acknowledgement of a yes/no stays plain. The reply:
14
+
15
+ 1. **Opens with the status line** when status circles are on — "here's where we're up to" comes before anything else.
16
+ 2. **Then an overview** — one or two lines saying what happened or what was found, before any detail.
17
+ 3. **Names each problem plainly** — what is wrong and why it matters, one per item, not buried in prose.
18
+ 4. **Puts results and comparisons in tables** — check results, before/after, options — one row per item.
19
+ 5. **Gives "how to fix it" as numbered steps**, each concrete enough to action on its own.
20
+ 6. **Closes with the next action as a question**, such as "Want me to build it on a new branch?"
21
+
22
+ **Emojis where they help, not everywhere.** Use them when they make a response quicker to read than a slab of text — ✅/❌ per row in a results table, 🎉 when something lands, 🔧 for work in progress. The whole range is welcome; not every response needs them. They are seasoning, never decoration.
23
+
24
+ **Traffic-light circles belong to the status line only.** The seven status circles (✅ 🟢 🟣 🟡 🟠 🔴 ⚪) each carry one meaning from the Status circles system, and they appear only on a status line, in the format that section defines. For general flavour, use other symbols — 🎉, 🔧, 🚀 — never a bare traffic-light circle. A plain ✅/❌ tick in a results table is fine: it marks pass/fail, which reads unambiguously. Where a response reports ticket status, it does it through a status line at the start, not circles scattered through the prose; the two systems never blend.
25
+
26
+ ## Changes
27
+
28
+ | File | Change |
29
+ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `static/templates/AGENTS.md` | New `### Response format` subsection under Project workflow, after `### Status circles`, with the standard "only if chosen during setup, otherwise delete" placeholder and the rules above. Outside the managed markers |
31
+ | `static/templates/docs/development/coding-standards.md` | The template's unfilled answers line gains `; response format [yes or no]` |
32
+ | `docs/Guides/setup.md` | Step 4 gains a seventh printed offer: "Response format (optional). Want the agent to answer with a clear structure — a short overview of the problem, results in tables, numbered action steps, and what it needs from you next?" A yes writes the section; a no writes nothing. The recorded-answers one-liner gains `response format [yes or no]`, and "all six answers" becomes seven |
33
+ | `docs/Standards/working-with-agents.md` | New "Response format" section documenting the choice, with a worked example response (genericised from the ESLint check-results example: status line first, overview, results table with ✅/❌, "how to fix it" steps, closing question) |
34
+ | `scripts/verifyStandards/checkRecordedAnswers.mjs` (+ test) | Learns the seventh answer, `response format`, so `standards:check` validates it like the other six |
35
+
36
+ ## Rollout for existing projects
37
+
38
+ No migration work in this change, and no version bump: the repo stays on 3.3.7. New projects get the choice straight away, because setup and the templates change immediately. Existing projects run `standards:check` from their installed package version, so nothing changes for them until the next version goes out — its release adds the version-history entry (like ship's), and the update flow's standing step, "ask any Working with the agent question whose answer is not recorded", then asks them the seventh question.
39
+
40
+ ## Why
41
+
42
+ Claude's structured answers make results readable at a glance; other dev agents answer in terse slabs, and the person re-reads everything to find what needs action. Encoding the format in `AGENTS.md` reaches every agent, since `AGENTS.md` is the one file they all read — Codex reads it natively. Making it a setup choice keeps the rollout gentle: no project has the section forced on it by a version bump.
43
+
44
+ ## Related
45
+
46
+ - [Working with Agents](../../Standards/working-with-agents.md)
47
+ - [Setup — step 4](../../Guides/setup.md)
48
+ - [AGENTS.md template](https://github.com/activatus-life/code-standards/blob/main/static/templates/AGENTS.md)
@@ -61,7 +61,7 @@ Anyone changing the standards adds a version, alongside the change:
61
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
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
63
  - **Anything a version can change in the `AGENTS.md` template lives between the `code-standards` markers.** A project copies only that section on an update, and `pnpm standards:check` compares only that section, so a rule outside the markers never reaches a project that is already set up.
64
- - **`pnpm devtest` must pass before publishing.** Run it, then `pnpm publish`. It checks the lint packages are the latest a project would install, then runs the tests, lints every template the way a project does, and checks formatting, types and the site build.
64
+ - **`pnpm devtest` must pass before publishing.** Run it, then `pnpm publish`. It checks the lint packages are the latest a project would install, then runs the tests, lints and formats every template the way a project does, and checks formatting, types and the site build.
65
65
  - **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.
66
66
  - **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.
67
67
  - **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.
@@ -70,10 +70,74 @@ Anyone changing the standards adds a version, alongside the change:
70
70
 
71
71
  ## Version 3
72
72
 
73
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.5
73
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.7
74
74
 
75
75
  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.
76
76
 
77
+ **Fixes in 3.3.7.** If the project already applied 3.3.6, check these:
78
+
79
+ - **A new word, "ship", and a sixth setup question.** "Ship" means: commit the current change, push it, and open a Pull Request whose description says why the change was made, what changed, how it was checked, with the results, and what the reviewer should look at closely, and links the ticket. It is the yes for those three steps, for that one change only. It is a project workflow choice, not a code standard, so setup now asks it in [step 4](/docs/Guides/setup#4-working-with-the-agent) beside the other five, and `pnpm standards:check` reports a project whose answers do not include it. See [Ship](/docs/Standards/working-with-agents#ship) and the [ontology](/docs/ontology).
80
+
81
+ **What to do:**
82
+
83
+ 1. **Print this to the person exactly as it is written**:
84
+
85
+ ```text
86
+ When you say "ship", should AI commit the change, push it and
87
+ open a Pull Request that describes what changed and why?
88
+ Yes or no?
89
+ ```
90
+
91
+ 2. If they say yes, add the **Ship** line from the `AGENTS.md` template to the project's Project workflow section, filled in as setup step 4 says.
92
+ 3. Add `ship [yes or no]` to the "Working with the agent" line under "Details" in `docs/development/coding-standards.md`, before the date.
93
+
94
+ - **Generated code has a home in `vendor/`, and AI-written code is ours.** `vendor/` was described as only for third-party code. A file a tool generates and replaces wholesale — such as the database types the Supabase CLI rewrites after every migration — is not ours either: nobody hand-edits it, and the next run of the tool replaces it. It now lives in `vendor/`, at any level, and is never linted, by the same `**/vendor/**` ignore that was already in every config. The other side is now written down too: **code an AI agent writes is our code**, and so is a script we write to drive a tool, such as a database migration — every standard applies to both. See [Third-party code is exempt](/docs/Standards/eslint#third-party-code-is-exempt).
95
+
96
+ **What to do:** find files a tool generates that the project keeps outside `vendor/` (search for the file the project's tool rewrites, such as a `database.types.ts`), move them into `vendor/`, and fix their imports. Check nothing hand-written went with them: a file with our edits in it is ours and comes back out. Then copy the `AGENTS.md` template over the project's `AGENTS.md`, keeping the project's own sections, and re-record any answers in the Project workflow section.
97
+
98
+ - **Custom hooks follow the utils ladder.** The standards said where utils live at every level — global, section, component — and where components live, but never said where hooks go beyond a root `hooks/` folder, so every hook placement was a guess. Now said: **a hook follows the same ladder as a util.** It starts in the component's `hooks/`, moves to the section's `hooks/` when another component in the section needs it, and moves to the global `hooks/` when anything outside the section needs it. One folder per hook, named after it, with its test and an `index.ts`. See [Hooks live the same way](/docs/Structure/folder-structure#hooks-live-the-same-way).
99
+
100
+ **What to do:** if the project already keeps hooks at section or component level, nothing — that placement is now the rule, not an accident. Record nothing. A hook sitting loose in a component file or in a guessed folder moves to the ladder spot its users say. The `AGENTS.md` copy from the previous change carries the rule into the project.
101
+
102
+ - **Route handlers outside `app/api/` are covered.** The standards only described handlers under `app/api/`, but Next.js gives every `route.ts` in `app/` a URL, so a project's auth callback — a URL the identity provider sends the browser back to, which reads the result and redirects on — was uncharted. Now said: a handler that returns JSON belongs under `app/api/`; a handler that redirects belongs at the URL the outside world already expects. Same rules apply there, handlers are **named exports** (`export async function GET`), never a default export, and their helpers follow the utils ladder. See [Route handlers outside `app/api/`](/docs/Structure/api-routes#-route-handlers-outside-appapi).
103
+
104
+ **What to do:** nothing, if the project's handlers already use named exports. Check any handler outside `app/api/` for a default export and convert it. Check its helpers are not sitting in the handler file itself.
105
+
106
+ - **There is no Select component.** The Design System Components list has Input with `type: select` in its variants, but nothing said so in words, and a project built Select as its own component, duplicating Input's name, label, help text, validation and error states. Now said in words under the list: **a field where the person picks one option from a list is an Input with `type: select`** (or `dropdown` or `auto-select`), with the choices passed through its `options` prop. Never a standalone component.
107
+
108
+ **What to do:** if the project built a standalone Select, rebuild it as an Input type, or record it as a deliberate exception in `docs/development/coding-standards.md` under "Details". The `AGENTS.md` copy from the previous change carries the rule into the project.
109
+
110
+ - **A seventh, optional question: the response format.** Like ship, this is a project workflow choice, not a code standard, so setup asks it in [step 4](/docs/Guides/setup#4-working-with-the-agent) beside the other six. A yes writes a **Response format** section into the project's `AGENTS.md`: every substantive reply — anything with findings, results, options or a plan — opens with the status line, then an overview, names each problem plainly, puts results in tables, gives fixes as numbered steps, and closes with the next action as a question. A plain yes or no stays plain. `pnpm standards:check` reports a project whose recorded answers do not include it, and the setup guide's update flow asks any answer that is not recorded. See [Setup, step 4](/docs/Guides/setup#4-working-with-the-agent).
111
+
112
+ **What to do:**
113
+
114
+ 1. Copy the `AGENTS.md` template over the project's `AGENTS.md`, keeping the project's own sections.
115
+ 2. **Print this to the person exactly as it is written**:
116
+
117
+ ```text
118
+ Response format (optional). Want the agent to answer with a
119
+ status line, an overview, problems named, results in tables,
120
+ numbered fixes, and the next action as a question?
121
+ Yes or no?
122
+ ```
123
+
124
+ 3. If they say yes, add the **Response format** section from the template to the project's Project workflow section, filled in as setup step 4 says.
125
+ 4. Add `response format [yes or no]` to the "Working with the agent" line under "Details" in `docs/development/coding-standards.md`, before the date.
126
+
127
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; the "Working with the agent" line records ship and the response format; if the answer was yes, `AGENTS.md` has a Ship line and a Response format section under Project workflow; generated files live in `vendor/` and their imports work; every hook sits at its ladder spot; every handler is a named export; any standalone Select is rebuilt or recorded.
128
+
129
+ **Fixes in 3.3.6.** If the project already applied 3.3.5, check these:
130
+
131
+ - **The templates are now formatted with the template Prettier config.** The import sorting added in 3.3.3 reordered the imports in the four `eslint.config.mjs` templates, so after `pnpm format` a project's copy no longer matched the template, and `pnpm standards:check` failed standard 6. `pageLayout.visual.ts`, the docs site's `index.tsx`, and the tables in the `ontology.md` and `design-system.md` templates changed the same way. Every template is now already formatted, and the code standards check this before each release, so `pnpm format` leaves a copied template as it is.
132
+
133
+ **What to do:** copy the project's ESLint template over `eslint.config.mjs` again, and, if the project has a regression check, `tests/visual/pageLayout.visual.ts`. Run `pnpm format`: neither should change. If the project recorded a standard 6 exception or an unfinished change only because the copied ESLint config was reformatted, remove it.
134
+
135
+ - **The Stylelint templates ignore generated CSS.** They only ignored `vendor/`, so `pnpm lint:css` also linted `.next/`, `out/`, `build/`, `coverage/` and `docsSite/`, and reported errors in CSS nobody wrote. They now ignore the same folders as the ESLint templates.
136
+
137
+ **What to do:** copy the Stylelint template over `stylelint.config.mjs` again. If the project added a `.stylelintignore` for those folders, delete it, and remove its line from "Unfinished changes" in `docs/development/coding-standards.md`.
138
+
139
+ **How to check:** `pnpm format` changes no copied template; `pnpm standards:check` passes, or lists only recorded exceptions; `pnpm lint:css` passes with no `.stylelintignore`.
140
+
77
141
  **Fixes in 3.3.5.** If the project already applied 3.3.4, check these:
78
142
 
79
143
  - **`pnpm standards:check` now reports a missing Stylelint config.** Standard 8 covers all hand-written CSS, and a Tailwind `globals.css` is hand-written CSS, but the check only looked at `stylelint.config.mjs` when there was one. A project with a `.css` or `.scss` file outside `vendor/` and `docsSite/`, and no `stylelint.config.mjs`, now fails standard 8. See [Stylelint](/docs/Standards/stylelint).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.3.5",
3
+ "version": "3.3.7",
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",
@@ -31,26 +31,29 @@
31
31
  "@eslint/js": "^10.0.1",
32
32
  "@getcanary/docusaurus-theme-search-pagefind": "1.0.2",
33
33
  "@getcanary/web": "^1.0.0",
34
+ "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
34
35
  "@mdx-js/react": "^3.0.0",
35
36
  "clsx": "^2.0.0",
36
- "eslint": "^10.13.0",
37
- "eslint-config-next": "^16.4.3",
37
+ "eslint": "^10.15.0",
38
+ "eslint-config-next": "^16.4.6",
38
39
  "eslint-config-prettier": "^10.1.8",
39
40
  "eslint-import-resolver-typescript": "^4.4.5",
40
- "eslint-plugin-import-x": "^4.17.1",
41
+ "eslint-plugin-import-x": "^4.18.1",
41
42
  "eslint-plugin-react": "^7.37.5",
42
43
  "eslint-plugin-react-hooks": "^7.1.1",
43
- "eslint-plugin-unicorn": "^79.0.0",
44
- "globals": "^17.13.0",
44
+ "eslint-plugin-unicorn": "^80.0.0",
45
+ "globals": "^17.14.0",
45
46
  "next": "^16.4.2",
46
47
  "pagefind": "^1.3.0",
47
48
  "prettier": "^3.9.10",
49
+ "prettier-plugin-tailwindcss": "^0.8.1",
48
50
  "prism-react-renderer": "^2.3.0",
49
51
  "raw-loader": "^4.0.2",
50
52
  "react": "^18.3.1",
51
53
  "react-dom": "^18.3.1",
54
+ "tailwindcss": "^4.3.3",
52
55
  "typescript": "~5.6.2",
53
- "typescript-eslint": "^8.72.1"
56
+ "typescript-eslint": "^8.72.2"
54
57
  },
55
58
  "browserslist": {
56
59
  "production": [
@@ -77,6 +80,7 @@
77
80
  "format": "prettier --write .",
78
81
  "format:check": "prettier --check .",
79
82
  "check:eslint-templates": "node scripts/checkEslintTemplates.mjs",
83
+ "check:template-formatting": "node scripts/checkTemplateFormatting.mjs",
80
84
  "devtest": "node scripts/developmentTest.mjs",
81
85
  "test": "node --test \"scripts/verifyStandards/*.test.mjs\""
82
86
  }
@@ -1,4 +1,4 @@
1
- // What setup asks the person and writes down: the five agent answers
1
+ // What setup asks the person and writes down: the seven agent answers
2
2
  // (standard 21) and the colour palette (standard 11).
3
3
  import {
4
4
  CODING_STANDARDS_PATH,
@@ -16,6 +16,8 @@ const AGENT_ANSWERS = [
16
16
  name: "being told about decisions",
17
17
  pattern: /told about decisions/i,
18
18
  },
19
+ { name: "ship", pattern: /\bship\b/i },
20
+ { name: "the response format", pattern: /response format/i },
19
21
  ];
20
22
  // The template's unfilled line: "[link or None]", "[yes or no]".
21
23
  const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
@@ -43,6 +43,7 @@
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
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]
46
+ - **Ship**: [Optional. If the person said yes to ship during setup: "When the person says 'ship', commit the current change, push it, and open a Pull Request. 'Ship' is the yes for those three steps, for that change only. The Pull Request description says why the change was made, what changed, how it was checked, with the results, and what the reviewer should look at closely, and links the ticket." Delete this line if they said no]
46
47
  - **Branches**: [how branches are named]
47
48
  - **Commit messages**: [the commit message format]
48
49
  - **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
@@ -74,6 +75,21 @@ Example: `🟢 [ABC-12](https://linear.app/[workspace]/issue/ABC-12) Short title
74
75
  - Work with no ticket is just the circle and a short title.
75
76
  - Only what the person needs to act on. Leave out what they already know.
76
77
 
78
+ ### Response format
79
+
80
+ [Only if the person chose the response format during setup. Otherwise delete this section.]
81
+
82
+ Answer every substantive reply — anything with findings, results, options or a plan — in this shape. A plain yes or no stays plain.
83
+
84
+ 1. **The status line first**, when status circles are on: where the work is up to, before anything else, in the format the Status circles section defines.
85
+ 2. **An overview** — one or two lines: what happened or what was found, before any detail.
86
+ 3. **Each problem named plainly** — what is wrong and why it matters, one per item, not buried in prose.
87
+ 4. **Results and comparisons in tables** — check results, before and after, options — one row per item.
88
+ 5. **"How to fix it" as numbered steps**, each concrete enough to action on its own.
89
+ 6. **The next action as a question**, so the person only has to answer it.
90
+
91
+ **Emojis where they help, not everywhere.** Use them when they make the reply quicker to read than a slab of text — ✅/❌ per row in a results table, 🎉 when something lands, 🔧 for work in progress. The whole range is welcome; not every reply needs them. **Traffic-light circles are the exception:** the seven status circles (✅ 🟢 🟣 🟡 🟠 🔴 ⚪) carry one meaning each from the Status circles section and appear only on a status line. For flavour use other symbols. A ✅/❌ tick in a results table marks pass and fail, not the circle's status meaning — that is fine.
92
+
77
93
  ## Environment variables
78
94
 
79
95
  | Variable | Required | Description |
@@ -138,6 +154,7 @@ Follow these rules in every change:
138
154
  - **A component's children sit flat in its own `components/` folder**, `accordion/components/item/` and `accordion/components/ctaArrow/`, even when one child is only used by another. Never a `components/` folder inside a child: two levels at most.
139
155
  - **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
140
156
  - **Reusable functions live in a `utils/` folder** — global, section or component level — one folder per function, with an `index.ts`. A function that sorts, finds, gets, filters or formats the data passed to it goes in a `utils/` folder the first time it is written. Move a function up a level when a second user needs it.
157
+ - **Custom hooks live in a `hooks/` folder the same way** — global, section or component level — one folder per hook, named after it, with its test and an `index.ts`. Move a hook up a level when a second user needs it. Never a hook inside the component file.
141
158
  - **Components live where they are used:** Design System Components in `components/ui/`, plus any props-only component not on the list yet, recorded under "Components for the standards" in `docs/development/coding-standards.md`; the site frame (navigation, header, footer) in `components/layout/`; the homepage's components in `app/(homepage)/components/`; components used on three or more pages in `components/shared/`; components used by three or more pages in one section in that section's route group (`app/(billing)/components/`); everything else in its page's `components/` folder. Start a new component beside its page. When a second page needs it, copy it there: one copy only, and each copy has a comment naming the other. When a third page needs it, merge the copies into one shared component, with props designed from all three uses. No `components/features/` folder.
142
159
  - **Code file names are camelCase**; component files are PascalCase. **Anything that becomes a URL is kebab-case**: route folders and documentation folders and files (`docs/architecture/background-jobs.md`). CSS variables are kebab-case too.
143
160
  - **Lay out with flexbox first**, and split layouts into child components. Only use CSS grid when specifically asked.
@@ -145,9 +162,9 @@ Follow these rules in every change:
145
162
  - **Comments explain why, not what.** Never leave commented-out code. Mark unfinished work with `// TODO: Message` (`{/* TODO: Message */}` in JSX).
146
163
  - **Error messages say what happened and what to do.**
147
164
 
148
- **Third-party code is exempt.** Code in `node_modules/` and `vendor/` belongs to someone else: do not lint it, do not reformat it, do not edit it to meet these rules.
165
+ **Third-party and generated code is exempt.** Code in `node_modules/` and `vendor/` belongs to someone else: do not lint it, do not reformat it, do not edit it to meet these rules. **Files a tool generates and replaces wholesale** — such as database types the Supabase CLI rewrites after every migration — belong in `vendor/` too, never hand-edited. **Code an AI agent writes is ours**, and so is a script we write to drive a tool, such as a migration: every standard applies.
149
166
 
150
- **shadcn components are not third-party.** Code the shadcn CLI copies into the project is ours. Convert it to these standards in the same change that adds it — its own camelCase folder, one component per file, `types.ts`, `index.ts` and a test — keep only the parts that are used, and never put it in `vendor/`. **Do not change a component's props or behaviour** — only its styling. Components work identically in every Activatus project.
167
+ **shadcn components are not third-party.** Code the shadcn CLI copies into the project is ours. Convert it to these standards in the same change that adds it — its own camelCase folder, one component per file, `types.ts`, `index.ts` and a test — keep only the parts that are used, and never put it in `vendor/`. **Do not change a component's props or behaviour** — only its styling. Components work identically in every Activatus project. **There is no Select component**: a pick-one-option field is an Input with `type: select`, through its `options` prop.
151
168
 
152
169
  **Look before you build a component.** Check the project's `components/ui/`, then the Design System Components in the code standards, then other Activatus projects, then shadcn. Build to the props listed in the Design System Components; never invent new prop names for a component that is already listed. A component in `components/ui/` takes everything through props and never imports from features, services, stores or `app/`.
153
170
 
@@ -10,8 +10,8 @@
10
10
 
11
11
  ## Colour palette
12
12
 
13
- | Colour | Value | Class names | Use for |
14
- | --- | --- | --- | --- |
13
+ | Colour | Value | Class names | Use for |
14
+ | --------------- | ----------------------------------------------------- | ------------------------------------------ | ------------------- |
15
15
  | [Brand primary] | [`#3b82f6`, or a Tailwind colour such as `slate-900`] | [`bg-brand-primary`, `text-brand-primary`] | [Buttons and links] |
16
16
 
17
17
  ## Why
@@ -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, one line: its number and name from the setup list, "skipped" or "changed", why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." An exception for only some files names them in backticks after "for": "4. Every function and component has a test file — changed for `app/api/**`: legacy routes, tested when replaced (2026-10-27)." Start no other line here with a number: `pnpm standards:check` reads every numbered line as an exception. 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]; told about decisions [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]; ship [yes or no]; response format [yes or no] ([YYYY-MM-DD]).
20
20
 
21
21
  ## Components for the standards
22
22
 
@@ -10,18 +10,18 @@ These are this product's words. Code, docs, tickets and copy all use them exactl
10
10
 
11
11
  ## Product words
12
12
 
13
- | Word | What it means | Not to be confused with |
14
- | --- | --- | --- |
13
+ | Word | What it means | Not to be confused with |
14
+ | ------ | ------------------------------- | --------------------------------------------------- |
15
15
  | [Word] | [What it means in this product] | [A word that sounds close but means something else] |
16
16
 
17
17
  ## How we speak
18
18
 
19
- | | |
20
- | --- | --- |
21
- | **Tone** | [How the product sounds, such as "plain, warm and direct"] |
22
- | **Words we use** | [Words that fit, such as "start" rather than "commence"] |
23
- | **Words we avoid** | [Words that do not fit, and what to say instead] |
24
- | **Audience** | [Who reads the copy, and what they already know] |
19
+ | | |
20
+ | ------------------ | ---------------------------------------------------------- |
21
+ | **Tone** | [How the product sounds, such as "plain, warm and direct"] |
22
+ | **Words we use** | [Words that fit, such as "start" rather than "commence"] |
23
+ | **Words we avoid** | [Words that do not fit, and what to say instead] |
24
+ | **Audience** | [Who reads the copy, and what they already know] |
25
25
 
26
26
  ## Why
27
27
 
@@ -1,9 +1,9 @@
1
- import {Redirect} from '@docusaurus/router';
2
- import useBaseUrl from '@docusaurus/useBaseUrl';
1
+ import { Redirect } from "@docusaurus/router";
2
+ import useBaseUrl from "@docusaurus/useBaseUrl";
3
3
 
4
4
  // The docs have no home page of their own: /docs opens the first Overview doc.
5
5
  const Home = () => {
6
- return <Redirect to={useBaseUrl('/overview/what-is-it')} />;
6
+ return <Redirect to={useBaseUrl("/overview/what-is-it")} />;
7
7
  };
8
8
 
9
9
  export default Home;
@@ -1,5 +1,5 @@
1
- import js from "@eslint/js";
2
1
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
2
+ import js from "@eslint/js";
3
3
  import prettier from "eslint-config-prettier";
4
4
  import { flatConfigs as importX } from "eslint-plugin-import-x";
5
5
  import unicorn from "eslint-plugin-unicorn";
@@ -1,8 +1,8 @@
1
1
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
2
- import prettier from "eslint-config-prettier";
3
- import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
4
2
  import nextVitals from "eslint-config-next/core-web-vitals";
5
3
  import nextTypescript from "eslint-config-next/typescript";
4
+ import prettier from "eslint-config-prettier";
5
+ import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
6
6
  import { flatConfigs as importX } from "eslint-plugin-import-x";
7
7
  import unicorn from "eslint-plugin-unicorn";
8
8
  import globals from "globals";
@@ -1,5 +1,5 @@
1
- import js from "@eslint/js";
2
1
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
2
+ import js from "@eslint/js";
3
3
  import prettier from "eslint-config-prettier";
4
4
  import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
5
5
  import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -1,5 +1,5 @@
1
- import js from "@eslint/js";
2
1
  import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";
2
+ import js from "@eslint/js";
3
3
  import prettier from "eslint-config-prettier";
4
4
  import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
5
5
  import { flatConfigs as importX } from "eslint-plugin-import-x";
@@ -2,7 +2,16 @@
2
2
  @type {import("stylelint").Config}
3
3
  */
4
4
  const config = {
5
- ignoreFiles: ["**/vendor/**"],
5
+ // Generated CSS, and the docs viewer, which is the standard template
6
+ // with its own build. Only the project's hand-written CSS is linted.
7
+ ignoreFiles: [
8
+ ".next/**",
9
+ "out/**",
10
+ "build/**",
11
+ "coverage/**",
12
+ "docsSite/**",
13
+ "**/vendor/**",
14
+ ],
6
15
  extends: [
7
16
  "stylelint-config-standard",
8
17
  "stylelint-config-recess-order",
@@ -2,7 +2,16 @@
2
2
  @type {import("stylelint").Config}
3
3
  */
4
4
  const config = {
5
- ignoreFiles: ["**/vendor/**"],
5
+ // Generated CSS, and the docs viewer, which is the standard template
6
+ // with its own build. Only the project's hand-written CSS is linted.
7
+ ignoreFiles: [
8
+ ".next/**",
9
+ "out/**",
10
+ "build/**",
11
+ "coverage/**",
12
+ "docsSite/**",
13
+ "**/vendor/**",
14
+ ],
6
15
  extends: [
7
16
  "stylelint-config-standard-scss",
8
17
  "stylelint-config-recess-order",
@@ -1,10 +1,11 @@
1
1
  // Measures every page at every half-screen scroll stop: each element's
2
2
  // box and opacity, the element count, the page height and a screenshot.
3
3
  // A refactor passes only when every measurement matches the baseline.
4
- import { expect, type Page, test } from "@playwright/test";
5
4
  import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
6
5
  import path from "node:path";
7
6
 
7
+ import { expect, test, type Page } from "@playwright/test";
8
+
8
9
  import { VISUAL_PAGES } from "./visualPages.mjs";
9
10
 
10
11
  const BOX_TOLERANCE_PIXELS = 1;
@@ -138,7 +139,9 @@ const describeDifferences = ({
138
139
  };
139
140
 
140
141
  const toFileName = (pagePath: string) =>
141
- pagePath === "/" ? "home" : pagePath.replaceAll(/[^a-z0-9]+/gi, "-");
142
+ pagePath === "/"
143
+ ? "home"
144
+ : pagePath.replaceAll(/[^a-z0-9]+/gi, "-");
142
145
 
143
146
  for (const pagePath of VISUAL_PAGES) {
144
147
  test(`${pagePath} looks exactly as before`, async ({