@activatus/code-standards 3.1.0 → 3.2.0

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.
Files changed (44) hide show
  1. package/docs/Guides/migrating.md +93 -50
  2. package/docs/Guides/regression-checks.md +72 -0
  3. package/docs/Guides/setup.md +89 -21
  4. package/docs/Standards/documentation.md +54 -7
  5. package/docs/Standards/eslint.md +60 -18
  6. package/docs/Standards/lint-errors.md +4 -4
  7. package/docs/Standards/readable-code.md +4 -1
  8. package/docs/Standards/stylelint.md +9 -3
  9. package/docs/Standards/styling.md +5 -1
  10. package/docs/Standards/working-with-agents.md +5 -5
  11. package/docs/Structure/component-organization.md +30 -26
  12. package/docs/Structure/folder-structure.md +85 -32
  13. package/docs/Structure/import-organization.md +4 -4
  14. package/docs/design-system-components.md +16 -12
  15. package/docs/ontology.md +1 -1
  16. package/docs/templates.mdx +12 -4
  17. package/docs/version-history.md +61 -6
  18. package/package.json +6 -2
  19. package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
  20. package/scripts/verifyStandards/checkComponents.mjs +129 -0
  21. package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
  22. package/scripts/verifyStandards/checkDocs.mjs +86 -0
  23. package/scripts/verifyStandards/checkRequiredFiles.mjs +96 -0
  24. package/scripts/verifyStandards/formatReport.mjs +76 -0
  25. package/scripts/verifyStandards/projectFiles.mjs +109 -0
  26. package/scripts/verifyStandards/runChecks.mjs +62 -0
  27. package/scripts/verifyStandards/verifyStandards.mjs +22 -0
  28. package/static/templates/AGENTS.md +19 -10
  29. package/static/templates/docs/design/design-system.md +6 -0
  30. package/static/templates/docs/development/coding-standards.md +10 -2
  31. package/static/templates/docs/overview/how-it-works.md +1 -1
  32. package/static/templates/docs/overview/writing-docs.md +4 -0
  33. package/static/templates/docs/product/ontology.md +32 -0
  34. package/static/templates/eslint/base/eslint.config.mjs +9 -0
  35. package/static/templates/eslint/nextjs/eslint.config.mjs +11 -1
  36. package/static/templates/eslint/react/eslint.config.mjs +11 -1
  37. package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
  38. package/static/templates/eslint.overrides.mjs +18 -0
  39. package/static/templates/skills/codeReview.md +2 -1
  40. package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
  41. package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
  42. package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
  43. package/static/templates/tests/visual/playwright.config.mjs +65 -0
  44. package/static/templates/tests/visual/visualPages.mjs +3 -0
@@ -4,9 +4,40 @@ sidebar_position: 3
4
4
 
5
5
  # Migrating an Existing Project
6
6
 
7
- Migrating an established codebase to the shared standards is best done in stages, so each change stays small enough to check properly.
7
+ Moving an established codebase onto the standards is done in stages, so each change stays small enough to check properly. This is the order that worked on a real 600-file project.
8
8
 
9
- **Already following the standards, and just updating to a newer version?** You don't need this whole guide. Read the [Version History](/docs/version-history) from your project's version onward, and do only what it lists.
9
+ **Already following the standards, and just updating to a newer version?** You don't need this guide. Read the [Version History](/docs/version-history) from your project's version onward, and do only what it lists.
10
+
11
+ **Agree the standards first.** Print the list in [Setup, step 3](/docs/Guides/setup#3-agree-the-standards), and ask the [step 4](/docs/Guides/setup#4-working-with-the-agent) questions. Skip any stage for a standard the person turned down.
12
+
13
+ ## The stages
14
+
15
+ | Stage | What | Setup standard | Why this order |
16
+ | ----- | ---------------------------------------------------------------------- | -------------- | --------------------------------------------------------- |
17
+ | 0 | [Regression check](#stage-0--regression-check) | — | Every later stage is measured against it |
18
+ | 1 | [Formatting](#stage-1--formatting) | 7, 9, 10 | The reformat touches every file, so it goes first, alone |
19
+ | 2 | [ESLint](#stage-2--eslint) | 6 | Fix the code, never the rules |
20
+ | 3 | [Names](#stage-3--names) | 1 | The lint errors show most of the names to change |
21
+ | 4 | [Constants](#stage-4--constants) | 12.1 | Components move next, and will import these |
22
+ | 5 | [Components](#stage-5--components) | 12, 13, 14 | Pure moves first, then shared code, which needs the paths |
23
+ | 6 | [Docs](#stage-6--docs) | 18 | The mechanical copy first, then the rewrite |
24
+ | 7 | [AGENTS.md, skills and version](#stage-7--agentsmd-skills-and-version) | 21 | Describes the final layout, so it goes last |
25
+
26
+ ## How to work through the stages
27
+
28
+ - **One branch per stage, stacked.** Each stage branches from the one before it. Stop after each stage for the person to review and commit. This is what keeps a large migration reviewable.
29
+ - **Each stage changes one kind of thing.** A stage that moves files does not also change what they do.
30
+ - **Run `pnpm lint`, `pnpm format:check`, the tests and the build at the end of every stage**, and the regression check from Stage 0 if the project has one.
31
+ - **Record anything left for later** under "Unfinished changes" in `docs/development/coding-standards.md`. See [Finishing a change later](/docs/Guides/setup#finishing-a-change-later).
32
+
33
+ :::warning[Squash merges lose the reformat commit]
34
+
35
+ If the project squash-merges pull requests, the reformat commit's hash disappears from `main` when the stack is merged, and `.git-blame-ignore-revs` stops working. Decide before starting:
36
+
37
+ - **Land Stages 0 and 1 on `main` by themselves first**, with a merge that keeps the commits, so the reformat survives as its own commit. Then stack the rest on top. Recommended.
38
+ - **Or accept losing blame-ignore**, and squash everything.
39
+
40
+ :::
10
41
 
11
42
  ## Before you start: third-party code is exempt
12
43
 
@@ -17,62 +48,54 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
17
48
  - Add `vendor/` to `.prettierignore` too.
18
49
  - **shadcn components are not third-party.** They are our code: convert them to the standards rather than moving them to `vendor/`. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
19
50
 
20
- ## Stage 1 — Prettier (formatting only)
51
+ ## Stage 0 — Regression check
21
52
 
22
- Formatting changes are safe to make all at once because they don't change behaviour.
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.
23
54
 
24
- ```bash
25
- pnpm add -D prettier prettier-plugin-tailwindcss
26
- ```
55
+ ## Stage 1 — Formatting
27
56
 
28
- Add `prettier.config.mjs` — see the [Prettier page](/docs/Standards/prettier) for the full file contents.
57
+ Applies setup standards 7, 9 and 10. Three commits, in this order:
29
58
 
30
- Format everything at once:
59
+ 1. **The config files.** Rename every config to `.mjs` ([why](/docs/Guides/setup#5-apply-the-standards)). Add `prettier.config.mjs` from the [Prettier page](/docs/Standards/prettier), with its `format` and `format:check` scripts, `.editorconfig`, `.nvmrc` and `.envrc`. Do not reformat anything yet.
31
60
 
32
- ```bash
33
- pnpm format
34
- ```
35
-
36
- Keep the reformat apart from any other change, so the formatting is easy to tell apart from real changes later.
61
+ ```bash
62
+ pnpm add -D prettier prettier-plugin-tailwindcss
63
+ ```
37
64
 
38
- Add a `.prettierignore` if you have generated files you don't want touched:
65
+ 2. **The reformat, on its own.** Run `pnpm format` and commit the result with nothing else in it. Every file changes, and none of it changes behaviour.
66
+ 3. **`.git-blame-ignore-revs`.** Create it with the reformat commit's full hash and a comment saying what it was. GitHub reads it automatically. For local `git blame`, each person runs once:
39
67
 
40
- ```text
41
- dist/
42
- build/
43
- coverage/
44
- vendor/
45
- *.generated.ts
46
- ```
68
+ ```bash
69
+ git config blame.ignoreRevsFile .git-blame-ignore-revs
70
+ ```
47
71
 
48
- ## Stage 2 — EditorConfig
72
+ Add a `.prettierignore` for generated files and anything Prettier must not format. See [What Prettier skips](/docs/Standards/prettier#what-prettier-skips).
49
73
 
50
- Add the `.editorconfig` file. No code changes needed — your editor will handle it on next save.
74
+ ## Stage 2 — ESLint
51
75
 
52
- ## Stage 3 — ESLint
76
+ Applies setup standard 6.
53
77
 
54
- Add the [standard config](/docs/Standards/eslint) for your project type, then start in warn-only mode to see what you're dealing with. Add a block before `prettier`:
78
+ Copy the [standard config](/docs/Standards/eslint) for the project's framework to `eslint.config.mjs`, unchanged, and `eslint.overrides.mjs` beside it. To see the size of the job first, turn the noisiest rules down to warnings **in `eslint.overrides.mjs`**, never in `eslint.config.mjs`:
55
79
 
56
- ```js
57
- const config = [
58
- // ...
59
- {
60
- rules: {
61
- // temporarily downgrade errors to warnings during migration
62
- "@typescript-eslint/no-explicit-any": "warn",
63
- "unicorn/filename-case": "warn",
64
- "unicorn/name-replacements": "warn",
65
- },
66
- },
67
- prettier,
80
+ ```js title="eslint.overrides.mjs"
81
+ // Temporary, while migrating: see Unfinished changes in
82
+ // docs/development/coding-standards.md.
83
+ export const projectOverrides = [
84
+ {
85
+ rules: {
86
+ "@typescript-eslint/no-explicit-any": "warn",
87
+ "unicorn/filename-case": "warn",
88
+ "unicorn/name-replacements": "warn",
89
+ },
90
+ },
68
91
  ];
69
-
70
- export default config;
71
92
  ```
72
93
 
73
- Run `pnpm lint` and triage the output. Fix them one kind at a time (for example, all `any` removals together). Once clean, remove the overrides.
94
+ Record the temporary warnings under "Unfinished changes". Run `pnpm lint`, and fix one kind of error at a time, such as every `any`. **Fix the code, not the rules.** When the warnings are gone, empty `eslint.overrides.mjs` again.
95
+
96
+ ## Stage 3 — Names
74
97
 
75
- ## Stage 4 — Names
98
+ Applies setup standard 1. Its own branch, after ESLint: the lint errors show most of the names to change.
76
99
 
77
100
  Renaming is the biggest job in most migrations, and the easiest place to get confused. Every name we write becomes [Human-Readable Names](/docs/Standards/human-readable-names). Work through it in this order.
78
101
 
@@ -152,20 +175,40 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
152
175
  - **It cannot reach keys in plain object literals that aren't typed**, such as the expected value in a test's `toEqual({ properties: … })`. Search the tests for the old name and fix those keys by hand.
153
176
  - **Run the type check and tests after each batch** of renames.
154
177
 
155
- ## Stage 5 — AGENTS.md
178
+ ## Stage 4 — Constants
179
+
180
+ Applies setup standard 12.1. Move every link into `r`, every piece of text into `s`, and every number into `numbers.ts`, all in `lib/constants/`. See [Constants](/docs/Structure/folder-structure#constants).
181
+
182
+ - **Move the values, nothing else.** The page must look and work exactly as before.
183
+ - **No component-level `constants.ts` survives this stage.**
184
+ - **A list of items with links** keeps its words in `s` and its links in `r` under the same keys: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links).
185
+ - **Shared types move to `lib/types/`.** `lib/constants/` never imports from `lib/types/`.
186
+
187
+ ## Stage 5 — Components
188
+
189
+ Applies setup standards 12, 13 and 14. Two branches:
190
+
191
+ 1. **5a: move the component folders, and nothing else.** Use `git mv` so the history follows, and rewrite the import paths. No code inside a file changes. Pure moves are quick to review. Follow [Where components live](/docs/Structure/folder-structure#-where-components-live): the homepage in `app/(homepage)/`, the site frame in `components/layout/`, and no `components/features/`.
192
+ 2. **5b: move the code several components share** to its standard home, now that the final paths are known: a shared component up one level, a hook beside the component that owns it, and sort, find, get, filter and format functions into `utils/`. Sub-components sit flat in their parent's `components/` folder.
193
+
194
+ ## Stage 6 — Docs
156
195
 
157
- Copy the [AGENTS.md template](/docs/templates#agents) to the project root and replace every `[placeholder]`. Agree the standards with the person first ([Setup, step 3](/docs/Guides/setup#3-agree-the-standards)), and set the code standards version from the [Version History](/docs/version-history).
196
+ Applies setup standard 18. Two branches:
158
197
 
159
- ## Stage 6 — Agent skills
198
+ 1. **6a: the mechanical part.** Copy the [doc templates](/docs/templates#document-templates) and the [`docsSite/` viewer](/docs/Standards/documentation#-setting-it-up), move images into `docs/assets/`, and delete the old viewer's leftovers.
199
+ 2. **6b: rewrite the content as Decision Docs.** This is the part that needs judgement, so it is reviewed on its own. Follow [Converting existing docs](/docs/Standards/documentation#-converting-existing-docs).
160
200
 
161
- Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
201
+ ## Stage 7 — AGENTS.md, skills and version
162
202
 
163
- ## Stage 7 — Docs
203
+ Applies setup standard 21.
164
204
 
165
- Move the project's existing documentation into the standard [`docs/` folders](/docs/Standards/documentation#-the-folders), rewriting each as a [Decision Doc](/docs/Standards/documentation#-the-doc-format), then add the [`docsSite/` viewer](/docs/Standards/documentation#-setting-it-up) so it shows at `/docs`.
205
+ 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.
206
+ 2. Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
207
+ 3. Set `**Code standards version:**` from the [Version History](/docs/version-history).
208
+ 4. Run the [standards check](/docs/Guides/setup#checking-a-project), and fix what it finds.
166
209
 
167
210
  ## Tips
168
211
 
169
212
  - **Don't mix formatting and logic changes.** Reformat on its own, then change the code.
170
- - **Exclude generated files** from ESLint with `// eslint-disable-file` or `.eslintignore`-equivalent glob ignores in the config.
171
- - **Fix new-file compliance first**: agree that all _new_ files must pass the full ruleset even before the migration is complete.
213
+ - **Generated files** are ignored with an entry in `eslint.overrides.mjs`, such as `{ ignores: ["generated/**"] }`, and a line in `.prettierignore`. Record the reason in `coding-standards.md`.
214
+ - **New files follow the full standards from day one**, even before the migration is finished.
@@ -0,0 +1,72 @@
1
+ ---
2
+ sidebar_position: 4
3
+ ---
4
+
5
+ # Regression Checks for Refactors
6
+
7
+ A refactor that moves code around should change nothing a visitor can see. The regression check proves it: it measures every page before and after, and fails on any difference.
8
+
9
+ **It is optional.** Use it for large refactors that are meant to change nothing visible, such as Stages 4 to 6 of [Migrating an Existing Project](/docs/Guides/migrating). A normal feature change does not need it.
10
+
11
+ ## What it checks
12
+
13
+ On each page in `tests/visual/visualPages.mjs`, at every half-screen scroll stop, in four sizes (desktop 1440×900, tablet 768×1024, mobile 390×844, and desktop with reduced motion):
14
+
15
+ | Measurement | Must match the baseline to |
16
+ | ------------------------ | -------------------------- |
17
+ | Every element's box | 1 pixel |
18
+ | Every element's opacity | 0.02 |
19
+ | The number of elements | Exactly |
20
+ | The page height | Exactly |
21
+ | A screenshot of the stop | 0.5% of pixels |
22
+
23
+ So every run sees the same thing, the page clock is frozen and moved on by hand, finite CSS animations are finished, and images are decoded before measuring.
24
+
25
+ ## Setting it up
26
+
27
+ 1. **Install Playwright:**
28
+
29
+ ```bash
30
+ pnpm add -D @playwright/test
31
+ pnpm exec playwright install chromium
32
+ ```
33
+
34
+ 2. **Copy `static/templates/tests/visual/`** to `tests/visual/` in the project, and list the pages to check in `visualPages.mjs`.
35
+ 3. **Add the scripts** to `package.json`:
36
+
37
+ ```json
38
+ {
39
+ "scripts": {
40
+ "test:visual": "playwright test --config tests/visual/playwright.config.mjs",
41
+ "test:visual:update": "VISUAL_UPDATE=true playwright test --config tests/visual/playwright.config.mjs --update-snapshots"
42
+ }
43
+ }
44
+ ```
45
+
46
+ 4. **Freeze the test files.** Add `tests/visual/` to `.prettierignore`, and add this line to the project's `AGENTS.md`, outside the code standards section: "Never edit `tests/visual/` or update its baseline without the person's yes."
47
+ 5. **Take the baseline from the live production site**, before the refactor starts:
48
+
49
+ ```bash
50
+ VISUAL_PRODUCTION_URL=https://example.com pnpm test:visual:update
51
+ ```
52
+
53
+ Commit `tests/visual/baseline/`.
54
+
55
+ ## Running it
56
+
57
+ ```bash
58
+ pnpm test:visual
59
+ ```
60
+
61
+ It builds the project and starts the production build on port 3100, then measures it against the baseline. **It rebuilds on every run**, so a stale build is never measured. Run it at the end of every refactor stage.
62
+
63
+ ## Rules
64
+
65
+ - **The baseline comes from the live production site**, never from the branch being tested. A baseline taken from the branch would only prove the branch matches itself.
66
+ - **It runs against a production build**, on its own port, never against `pnpm dev`.
67
+ - **An agent never updates the baseline without the person's yes.** A failing check means something visible changed. Find out what, and fix the code. Updating the baseline to make it pass hides the change.
68
+ - **The test files are frozen** for the whole refactor: an agent never edits them to make a check pass.
69
+
70
+ ## The blind spot
71
+
72
+ **A frozen clock only samples fixed moments.** The check measures each scroll stop after moving the clock on by the same amount every time. A change to the timing between those moments, such as an animation that now runs slower but ends in the same place, passes. When a refactor touches animation timing, check those parts by eye as well.
@@ -9,7 +9,16 @@ sidebar_label: "Setup"
9
9
 
10
10
  The person creates the app themselves — with `create-next-app`, Expo or anything else — and tells you to follow the standards. **Do not ask which framework the project uses.** Look at the project: its `package.json` and files tell you. The person only answers the questions below and checks your work. They never run a command.
11
11
 
12
- **These standards are the base for code, plus how agents link and report the project's work.** A project builds on top of them: it can add its own folders and conventions, and it makes its own project-management decisions (tickets, releases, branches, commit messages, who commits). Those go in the project's own docs, not here. Step 3 records the project's GitHub repo and Linear project, and offers the optional [status circles](/docs/Standards/working-with-agents#status-circles).
12
+ **These standards are the base for code, plus how agents link and report the project's work.** A project builds on top of them: it can add its own folders and conventions, and it makes its own project-management decisions (tickets, releases, branches, commit messages, who commits). Those go in the project's own docs, not here. Step 4 records the project's GitHub repo and Linear project, and offers the optional [status circles](/docs/Standards/working-with-agents#status-circles).
13
+
14
+ **Setup asks the person two sets of questions. Ask both, every time:**
15
+
16
+ 1. **The standards list** ([step 3](#3-agree-the-standards)).
17
+ 2. **Working with the agent** ([step 4](#4-working-with-the-agent)): the GitHub repo, the Linear project, the status circles, and whether AI asks before every commit and push.
18
+
19
+ A person saying "all good" to the standards list has not answered step 4. Ask it next.
20
+
21
+ **The standards are the project's base.** After setup, never skip, loosen or change a standard on your own: ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details", then make the change. ESLint changes go in `eslint.overrides.mjs`, never in `eslint.config.mjs`. See [Project-specific overrides](/docs/Standards/eslint#project-specific-overrides).
13
22
 
14
23
  ## 1. Install the standards
15
24
 
@@ -52,7 +61,7 @@ Open the project's `AGENTS.md` and look for `**Code standards version:**`.
52
61
  | -------------------------------------------- | ------------------------------------ | ----------------------------------------------------------- |
53
62
  | No `AGENTS.md`, or no code standards version | The standards have never been set up | [3. Agree the standards](#3-agree-the-standards) |
54
63
  | A version lower than the installed package | The project follows an older version | [Updating to a newer version](#updating-to-a-newer-version) |
55
- | The same version as the installed package | Already up to date | Nothing to do. Tell the person |
64
+ | The same version as the installed package | Already on this version | [Already on this version](#already-on-this-version) |
56
65
 
57
66
  ## 3. Agree the standards
58
67
 
@@ -74,7 +83,7 @@ Tell me the numbers to skip or change, or say "all good".
74
83
  10. Node version set by .nvmrc and direnv
75
84
  11. Styling: Tailwind, flexbox first, colours only from the global palette
76
85
  12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
77
- 12.1. Constants: r for every link, s for every piece of text, noData for local stand-in data, shared numbers by topic, all in lib/constants/
86
+ 12.1. Constants: r for every link, s for every piece of text, every number in numbers.ts, noData for stand-in data, all in lib/constants/
78
87
  13. Components live where they are used: components/ui/, components/shared/, or beside their page
79
88
  14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
80
89
  15. Design System Components: every project builds the standard components with the same props
@@ -108,14 +117,16 @@ Then wait for the answer.
108
117
 
109
118
  The list has nothing about branches or commit messages. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/docs/Standards/agent-specs#project-workflow).
110
119
 
111
- ### Working with the agent
120
+ **Then go straight to step 4.** Setup is not finished until the person has answered it.
112
121
 
113
- 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.
122
+ ## 4. Working with the agent
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.
114
125
 
115
126
  First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
116
127
 
117
128
  - **GitHub repo:** read it with `git remote get-url origin`. If there is no remote, ask for it.
118
- - **Linear project:** read it from the project's own docs if they name it: the workspace, the project and the ticket prefix. If they do not, ask. Never copy it from another project.
129
+ - **Linear project:** read it from the project's own docs if they name it: the workspace, the team (its key is the ticket prefix, such as `ACT`) and the project. If they do not, ask. Never copy it from another project.
119
130
 
120
131
  Then the **status circles**. **Print this to the person exactly as it is written**:
121
132
 
@@ -139,7 +150,7 @@ to git? Yes or no?
139
150
 
140
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", so a later update knows not to ask again. See [Working with Agents](/docs/Standards/working-with-agents).
141
152
 
142
- ## 4. Apply the standards
153
+ ## 5. Apply the standards
143
154
 
144
155
  Do only the standards the person agreed to. Copy every file from `node_modules/@activatus/code-standards/static/templates/` — never write a config file from scratch.
145
156
 
@@ -147,25 +158,49 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
147
158
 
148
159
  **An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/docs/Guides/migrating), one stage at a time, after the config files below are in place.
149
160
 
150
- | Standard | What to set up |
151
- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152
- | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
153
- | 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
154
- | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
155
- | 9. EditorConfig | Copy `static/templates/.editorconfig` |
156
- | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
157
- | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
158
- | 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `noData.ts` and an `index.ts` that exports them. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
159
- | 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up) |
160
- | 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/` |
161
+ | Standard | What to set up |
162
+ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
163
+ | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
164
+ | 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
165
+ | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
166
+ | 9. EditorConfig | Copy `static/templates/.editorconfig` |
167
+ | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
168
+ | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
169
+ | 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `numbers.ts` and an `index.ts` that exports them. Create `noData.ts` later, once the data's shape is decided. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
170
+ | 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up) |
171
+ | 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/`. Add the `standards:check` script: see [Checking a project](#checking-a-project) |
161
172
 
162
173
  The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
163
174
 
164
175
  **Finish by:**
165
176
 
166
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.
167
- 2. Running `pnpm lint`, `pnpm format:check` and the tests.
168
- 3. Telling the person what you set up, which standards they skipped, and anything only they can do, such as filling in a secret in `.env.local`.
178
+ 2. Running `pnpm lint`, `pnpm format:check`, the tests and the [standards check](#checking-a-project), and fixing what they find.
179
+ 3. **Printing this to the person**, filled in, so every project's handover reads the same:
180
+
181
+ ```text
182
+ Code standards set up: version [N] ([package version]).
183
+
184
+ Set up: [the standards applied, by number]
185
+ Skipped: [numbers and reasons, or "None"]
186
+ Left to do: [unfinished changes, or "None"]
187
+ Only you can: [secrets in .env.local and the like, or "Nothing"]
188
+
189
+ Before we start: please review docs/product/ontology.md,
190
+ the product's words and how it speaks. Ask me to change
191
+ anything that is wrong.
192
+ ```
193
+
194
+ ---
195
+
196
+ ## Already on this version
197
+
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.
199
+
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.
169
204
 
170
205
  ---
171
206
 
@@ -187,12 +222,45 @@ The project already follows the standards, and a newer version is out.
187
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.
188
223
  4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
189
224
  5. **Do every other change** as its "What to do" says, and run its "How to check" search.
190
- 6. **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).
225
+ 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
+ 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).
191
228
 
192
229
  See the [Version History](/docs/version-history) for the full update rules.
193
230
 
194
231
  ---
195
232
 
233
+ ## Checking a project
234
+
235
+ The package ships a script that checks the project against the standards. Add it to the project's `package.json` during setup:
236
+
237
+ ```json
238
+ {
239
+ "scripts": {
240
+ "standards:check": "node node_modules/@activatus/code-standards/scripts/verifyStandards/verifyStandards.mjs"
241
+ }
242
+ }
243
+ ```
244
+
245
+ ```bash
246
+ pnpm standards:check
247
+ ```
248
+
249
+ It reports, and never changes a file. Each finding gives the standard's number and the page to read. It checks:
250
+
251
+ | Standard | What it checks |
252
+ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
253
+ | 21 | `AGENTS.md` has the code standards version and an unchanged Code standards section; the skills match the templates |
254
+ | 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
+ | 12.1 | `lib/constants/` has `index.ts`, `routes.ts`, `strings.ts` and `numbers.ts`, and no component has its own `constants.ts` |
256
+ | 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
257
+ | 4 | Every file that exports a function or component has a test file beside it |
258
+ | 18 | Every doc template is in place, and every doc has one "Group — Menu item" title matching its file name, a Status line, and Decision, Why and Related sections |
259
+
260
+ **It follows the project's own rules, not only the standard ones.** A finding for a standard recorded as skipped or changed in `docs/development/coding-standards.md` is listed as a recorded exception to check by hand, and does not fail the check. The project's ESLint changes live in `eslint.overrides.mjs`, which it never compares. It also lists any Unfinished changes.
261
+
262
+ **The check is a helper, not the standard.** Passing it does not mean every rule is followed: names, the order inside a component and much more still need reading. And a finding that is wrong for the project is not fixed by bending the code to the script: record the exception in `coding-standards.md`, with the person's yes.
263
+
196
264
  ## Finishing a change later
197
265
 
198
266
  Sometimes a change is too big for the update, such as switching on the standard ESLint config in a project that never had it. It can be finished later, but **the version number must stay honest**.
@@ -67,12 +67,12 @@ These are the same in every project:
67
67
 
68
68
  Decisions that only make sense for this one product go in their own folders:
69
69
 
70
- | Folder | Holds |
71
- | ---------------------------------------- | ---------------------------------------------------- |
72
- | `product/` | What this product is and how its main parts work |
73
- | `integrations/` | One file per outside service the product connects to |
74
- | `user-flows/` | One file per User Flow |
75
- | _A folder for the product's own subject_ | For example, Launchpad has `tickets/` |
70
+ | Folder | Holds |
71
+ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
72
+ | `product/` | What this product is and how its main parts work. Starts with `ontology.md`: the product's words and how it speaks |
73
+ | `integrations/` | One file per outside service the product connects to |
74
+ | `user-flows/` | One file per User Flow |
75
+ | _A folder for the product's own subject_ | For example, Launchpad has `tickets/` |
76
76
 
77
77
  ### Which folder?
78
78
 
@@ -95,6 +95,12 @@ Keep these pairs distinct:
95
95
 
96
96
  A `Not started` file is a visible gap: it shows a decision that has not been made yet.
97
97
 
98
+ **Keep every folder and file, even ones that do not apply yet.** They keep every project's docs laid out the same way, and a small project such as a one-page site grows into them. Never delete one to tidy the menu.
99
+
100
+ ### Decision Docs belong to the person
101
+
102
+ **Confirm with the person before creating, changing or deleting a Decision Doc**, including deleting a folder. A decision is theirs to make, not the agent's. The exception is a project whose `AGENTS.md` names an agent that manages the docs, such as a planning agent: that agent follows its own instructions.
103
+
98
104
  ---
99
105
 
100
106
  ## 📄 The doc format
@@ -150,6 +156,8 @@ Every doc has the same shape:
150
156
 
151
157
  Update the doc, change the **Updated** date, and add a `## History` entry: what changed, why, when, and which work was affected. Keep the original decision and its reason in the history.
152
158
 
159
+ **The Updated date tracks the decision, not the file.** Moving, renaming, reformatting or converting a doc to this format, with no decision changed, leaves the date as it is.
160
+
153
161
  ---
154
162
 
155
163
  ## 🧭 One file, one menu item, one route
@@ -260,9 +268,46 @@ export default nextConfig;
260
268
 
261
269
  ---
262
270
 
271
+ ## 🔄 Converting existing docs
272
+
273
+ How to turn a project's existing documentation into Decision Docs. **Every word is kept**: converting changes where things live and how they are laid out, never what they say. Confirm the plan with the person before starting.
274
+
275
+ ### Outside material, such as client briefs
276
+
277
+ A brief says what to build rather than recording a decision, but it is still a decision: to build what the brief says.
278
+
279
+ 1. **Give the product its own folder**, such as `docs/homepage/`, with one doc per part of the product.
280
+ 2. **Decision:** "Build it as the brief below says."
281
+ 3. **Why:** the client's reason, and which brief wins where two disagree.
282
+ 4. **Details:** the brief's full text, unchanged.
283
+ 5. **A superseded brief** goes under `## History`, marked "Reference only".
284
+ 6. **The table of which brief wins** goes in `scope/core.md`.
285
+
286
+ ### Build decisions made along the way
287
+
288
+ **One decision per file.** A decision made while building a part, such as "the hero cards become the rail's cards", gets its own doc beside that part's doc, in the same product folder. It is never folded into the part's doc.
289
+
290
+ ### Headings
291
+
292
+ A doc has one `#` heading, its title. Push every heading in the old content down by the **smallest step that frees `#`**: if the old doc's top level is `#`, every heading moves down one level. Skip headings inside code blocks. **If that pushes any heading past `######`, split the doc** into one doc per top-level part instead. The site's menu on the right shows levels 2 and 3 only, so keep the important structure there.
293
+
294
+ ### Images
295
+
296
+ **Images go in `docs/assets/`, in a folder per product area**, such as `docs/assets/homepage/`. Link each image from the doc that uses it, with a relative path. **Refer to a folder of images as a code path, `docs/assets/homepage/`, never a link**: the docs site cannot open a folder, so the link breaks the build.
297
+
298
+ ### Old viewer leftovers
299
+
300
+ Delete every `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md` once its content has moved to `overview/`.
301
+
302
+ ### The Updated date
303
+
304
+ Converting a doc does not change its decision, so the **Updated** date stays as it was. Use the date of the last real decision, from the old doc or the git history.
305
+
306
+ ---
307
+
263
308
  ## 🚀 Setting it up
264
309
 
265
- 1. **Copy the docs.** Copy the [`docs/` templates](/docs/templates#document-templates) into the project's `docs/` folder. Rename `overview/what-is-it.md` after the project (`what-is-launchpad.md`) and update its title.
310
+ 1. **Copy the docs.** Copy the [`docs/` templates](/docs/templates#document-templates) into the project's `docs/` folder. Converting docs from version 2 or earlier? Delete the old viewer's leftovers: every `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md` once its content has moved to `overview/`. Rename `overview/what-is-it.md` after the project (`what-is-launchpad.md`), update its title, and update the link to it in `overview/writing-docs.md`. The docs build fails on a broken link.
266
311
 
267
312
  2. **Copy the viewer.** Copy the [`docsSite/` template](/docs/templates#docs-site) into the project root. Rename `package.json.txt` to `package.json` and `gitignore.txt` to `.gitignore`, set `PROJECT_NAME` in `docusaurus.config.mjs`, and point the home redirect in `src/pages/index.tsx` at the renamed overview file.
268
313
 
@@ -296,6 +341,8 @@ export default nextConfig;
296
341
 
297
342
  Open `http://localhost:3000/docs`.
298
343
 
344
+ 7. **Ask the person to review `docs/product/ontology.md`** before work starts: the product's words and how it speaks. Every agent reads it, so a wrong word spreads. Tell them to ask their AI to make any changes.
345
+
299
346
  :::caution[Do not name the script `docs`]
300
347
 
301
348
  `pnpm docs` is a built-in pnpm command, so a script called `docs` never runs. Use `docs:dev`.