@activatus/code-standards 3.0.9 → 3.1.1
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.
- package/README.md +2 -2
- package/docs/Guides/migrating.md +14 -0
- package/docs/Guides/setup.md +70 -26
- package/docs/Standards/agent-specs.md +1 -1
- package/docs/Standards/documentation.md +17 -7
- package/docs/Standards/eslint.md +54 -14
- package/docs/Standards/lint-errors.md +4 -4
- package/docs/Standards/readable-code.md +4 -1
- package/docs/Standards/stylelint.md +9 -3
- package/docs/Standards/styling.md +5 -1
- package/docs/Standards/working-with-agents.md +8 -6
- package/docs/Structure/component-organization.md +30 -26
- package/docs/Structure/folder-structure.md +85 -32
- package/docs/Structure/import-organization.md +4 -4
- package/docs/design-system-components.md +16 -12
- package/docs/intro.md +1 -1
- package/docs/ontology.md +1 -1
- package/docs/templates.mdx +2 -2
- package/docs/version-history.md +58 -6
- package/package.json +1 -1
- package/static/templates/AGENTS.md +19 -10
- package/static/templates/docs/design/design-system.md +6 -0
- package/static/templates/docs/development/coding-standards.md +6 -2
- package/static/templates/docs/overview/how-it-works.md +1 -1
- package/static/templates/docs/product/ontology.md +32 -0
- package/static/templates/eslint/base/eslint.config.mjs +9 -0
- package/static/templates/eslint/nextjs/eslint.config.mjs +9 -0
- package/static/templates/eslint/react/eslint.config.mjs +9 -0
- package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
- package/static/templates/eslint.overrides.mjs +18 -0
- package/static/templates/skills/codeReview.md +2 -1
- package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
- package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
package/docs/version-history.md
CHANGED
|
@@ -18,14 +18,15 @@ sidebar_label: "Version History"
|
|
|
18
18
|
**Read only the versions newer than the project's.** A project on version 1 that is updating to version 3 reads version 2 and version 3 on this page, and nothing else. Do not re-read every standard or check the whole codebase: each version lists every change that matters, and how to find the code it affects.
|
|
19
19
|
|
|
20
20
|
1. **Find the project's version** in its `AGENTS.md`. If there is none, the project has never followed the standards: follow [Setup](/docs/Guides/setup) instead.
|
|
21
|
-
2. **Update the package:** `pnpm
|
|
21
|
+
2. **Update the package:** `pnpm add -D @activatus/code-standards@latest`, never a typed version number. If pnpm refuses because the version is too new, add the package to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`, as in [Setup](/docs/Guides/setup#1-install-the-standards). The entry is the plain package name, with no version. If pnpm wrote one with versions in it, such as `'@activatus/code-standards@3.0.4 || 3.0.5'`, replace it with the plain name: otherwise pnpm adds another version to it on every update. Then read this page from `node_modules/@activatus/code-standards/docs/version-history.md`.
|
|
22
22
|
3. **Read each version newer than the project's**, oldest first. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
|
|
23
23
|
4. **For each change, do the "What to do" steps**, then run the "How to check" searches. A search that still finds something means the change is not finished. When a change says to copy a line from the `AGENTS.md` template, and the project's `AGENTS.md` records the standards in its own words instead, write the updated rule there in the project's own shape.
|
|
24
24
|
5. **Strike out what the standard now covers.** After the changes, re-read the project's list of opted-out and changed standards in `docs/development/coding-standards.md`. Take off the list any exception the new version has made part of the standard, and update any rule it records for an old shape of the standard. A differences list that still describes the old standard sends the next agent wrong.
|
|
25
25
|
6. **Run `pnpm lint`, `pnpm format:check`, `pnpm test` and the build** after each change. `format:check` checks every file git does not ignore; never narrow it to changed files.
|
|
26
|
-
7. **
|
|
26
|
+
7. **Ask any [Working with the agent](/docs/Guides/setup#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
|
|
27
|
+
8. **Update the version number** in `AGENTS.md` once every change is done.
|
|
27
28
|
|
|
28
|
-
**A patch keeps the same version number.** When only the last number changes, such as 3.0.0 → 3.0.1, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed.
|
|
29
|
+
**A patch keeps the same version number.** When only the last or middle number changes, such as 3.0.0 → 3.0.1 or 3.0.9 → 3.1.0, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed. A project already on the installed major version is never "nothing to do": follow [Already on this version](/docs/Guides/setup#already-on-this-version).
|
|
29
30
|
|
|
30
31
|
**When a change does not fit the project**, for example it renames a folder the project does not have, skip it. If you are not sure, ask; do not guess.
|
|
31
32
|
|
|
@@ -41,6 +42,7 @@ Anyone changing the standards adds a version, alongside the change:
|
|
|
41
42
|
- **Work in progress goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: pilot it (below), drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
|
|
42
43
|
- **Pilot a version in a real project before releasing it.** Once the work-in-progress version is written, have one real project apply it exactly as written, reading only what the page says. Every judgement call the agent has to make, and every instruction that does not fit the project, is a missing sentence: fold it back into the version before publishing. Release only when the pilot runs without the agent asking a question the page does not answer.
|
|
43
44
|
- **Fixing a released version** bumps only the last number: `3.0.0` → `3.0.1`. Update the version's changes in place, and list what was fixed under its **Fixes**. Projects keep the same version number in `AGENTS.md`. Write each fix so a project already on that version knows what to do.
|
|
45
|
+
- **Adding something optional** to a released version, such as a new setup question, bumps the middle number: `3.0.9` → `3.1.0`. It is written up the same way as a fix, and projects keep the same version number in `AGENTS.md`.
|
|
44
46
|
- **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.0.9 — optional project links`, so releases are easy to find in the git log.
|
|
45
47
|
- **Every patch number is published.** Publish each patch to npm as soon as its Fixes are written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
|
|
46
48
|
- **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.
|
|
@@ -49,9 +51,59 @@ Anyone changing the standards adds a version, alongside the change:
|
|
|
49
51
|
|
|
50
52
|
## Version 3
|
|
51
53
|
|
|
52
|
-
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.
|
|
54
|
+
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.1.1
|
|
53
55
|
|
|
54
|
-
Install it with `pnpm add -D @activatus/code-standards@
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
**Fixes in 3.1.1.** If the project already applied 3.1.0, check these:
|
|
59
|
+
|
|
60
|
+
- **`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` can run past 300 lines.** They hold data only, so `max-lines` no longer applies to them. Splitting `r` or `s` across files to stay under 300 lines only made labels harder to find. In `eslint.config.mjs`, add this block straight after the test-file block:
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
{
|
|
64
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
65
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
66
|
+
rules: { "max-lines": "off" },
|
|
67
|
+
},
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
In a JavaScript project, the file pattern ends `.{js,mjs}` instead of `.ts`. If the project already split `r` or `s` into several files only to get under 300 lines, put each back into one file. Update the 300-line rule in `AGENTS.md` from the template.
|
|
71
|
+
|
|
72
|
+
- **Setup's agent questions are now their own step**, [step 4](/docs/Guides/setup#4-working-with-the-agent), and every setup and update asks them. Agents were skipping them after the standards list. If `docs/development/coding-standards.md` does not record all four answers (the GitHub repo, the Linear project, the status circles and asking before committing), ask the person the missing ones and record them.
|
|
73
|
+
|
|
74
|
+
- **The standards are the project's base, and changing one needs the person's yes.** An agent never skips, loosens or changes a standard on its own. It asks first, records the change in `docs/development/coding-standards.md`, under "Details" (number, name, what is different, why, and the date), then makes it. Copy the new rule into `AGENTS.md` from the template, under Code standards.
|
|
75
|
+
- **ESLint changes live in `eslint.overrides.mjs`.** `eslint.config.mjs` is now an unchanged copy of the template, so an update can copy it straight over. Copy `static/templates/eslint.overrides.mjs` to the project root. Move every rule the project added or changed in `eslint.config.mjs` into it, each with a comment naming the standard's number, and check each has an entry in `coding-standards.md`. Ask the person about any that do not. Then copy the project's template from `static/templates/eslint/` over `eslint.config.mjs`. See [Project-specific overrides](/docs/Standards/eslint#project-specific-overrides).
|
|
76
|
+
- **Components are shared on the third use, not the second.** On the second use, copy the component into the second page's `components/` folder, with a comment in each copy naming the other. On the third use, merge them into the section's `components/` folder or `components/shared/`, with props designed from all three uses. Nothing to move in the project: components already shared stay where they are. Update the components rule in `AGENTS.md` from the template. See [Where components live](/docs/Structure/folder-structure#rules).
|
|
77
|
+
- **Sort, find, get, filter and format functions go in `utils/` from the start**, even with one user. Move any such function written inside a component into that component's `utils/` folder.
|
|
78
|
+
- **The codeReview skill checks for these.** Copy `static/templates/skills/codeReview.md` into `.agents/skills/` and `.claude/commands/` again.
|
|
79
|
+
|
|
80
|
+
- **The homepage is a route group, `app/(homepage)/`.** It holds the homepage's `page.tsx` and its own `components/` and `utils/`, and is still served at `/`. Move `app/page.tsx` there, and move the homepage's components out of `app/components/` into `app/(homepage)/components/`. See [Where components live](/docs/Structure/folder-structure#-where-components-live).
|
|
81
|
+
- **The site frame lives in `components/layout/`**: navigation, header, footer and anything else that frames the pages. It may read `r` and `s`. Move those components there from `components/shared/` or `app/components/`. Layout primitives such as Duplex stay in `components/ui/`.
|
|
82
|
+
- **A props-only component that is not on the Design System Components list stays in `components/ui/`.** Record it, with its props, in `docs/development/coding-standards.md`, under a new "Components for the standards" heading (copy it from the template), and tell the person. Move back into `components/ui/` any such component that was moved out only because it was not listed.
|
|
83
|
+
- **Four components joined the list:** Brand Logo, Notification Card, Scroll Cue and Dropdown Menu. If the project has them, check their props match the [list](/docs/design-system-components).
|
|
84
|
+
- **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. Config files and scripts outside the app keep theirs at the top.
|
|
85
|
+
- **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`.
|
|
86
|
+
- **Write `r` and `s` keys out by name**, `r.plans.starter`, never `r.plans[planId]`. A list of items keeps its words in `s` and its links in `r` under the same keys. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
|
|
87
|
+
- **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
|
|
88
|
+
- **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant.
|
|
89
|
+
- **Create `noData.ts` only once the data's shape is decided.** An empty `noData.ts` can be deleted. Stand-in data asked for earlier carries the comment `// Not the real schema: a basic shape to finish the task.`
|
|
90
|
+
- **A component's sub-components sit flat in its one `components/` folder**, two levels at most. Move any sub-component folder sitting directly in its parent, or nested inside another sub-component, into the parent's `components/` folder.
|
|
91
|
+
- **The palette is listed in `docs/design/design-system.md`**: each colour's name, value, class names and use. `globals.css` holds only colours Tailwind does not have. Copy the Colour palette section from the template and fill it in.
|
|
92
|
+
- **AGENTS.md: the Code standards section sits between `<!-- code-standards:start -->` and `<!-- code-standards:end -->`**, and an update replaces everything between them. Copy the section from the template, markers included. Move any project exception written into it into `docs/development/coding-standards.md`, and anything else the project added, such as a framework's block, outside the markers.
|
|
93
|
+
- **Docs:** copy the new `docs/product/ontology.md` template if the project has none, and ask the person to review it. Fix the link in `overview/writing-docs.md` if `what-is-it.md` was renamed. Retitle `how-it-works.md` "Overview — How It Works". Delete any version 2 leftovers: `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md`.
|
|
94
|
+
- **Decision Docs are confirmed with the person** before an agent creates, changes or deletes one, unless `AGENTS.md` names an agent that manages them. A folder that cannot apply may be deleted with the person's yes, recorded in `coding-standards.md`. Moving or reformatting a doc does not change its Updated date.
|
|
95
|
+
- **Stylelint configs name their export:** `const config = { … }; export default config;`. Change the project's `stylelint.config.mjs` to match.
|
|
96
|
+
- **The Linear ticket prefix is the team's, not the project's.** In `AGENTS.md`, Project workflow, write the Linear workspace, team and project, such as `activatus-life`, team `ACT`, project Launchpad.
|
|
97
|
+
|
|
98
|
+
**How to check:** `pnpm lint` passes with `routes.ts`, `strings.ts`, `numbers.ts` or `noData.ts` over 300 lines; `app/page.tsx` has moved to `app/(homepage)/page.tsx`; `lib/constants/` has `numbers.ts` and no component has its own `constants.ts`; `AGENTS.md` has the code-standards markers; the navigation, header and footer are in `components/layout/`; `eslint.config.mjs` matches the template exactly, with `eslint.overrides.mjs` beside it; every rule in `eslint.overrides.mjs` has an entry in `coding-standards.md`; `lib/constants/` has no `strings/` or `routes/` folder made only to stay under the limit; `docs/development/coding-standards.md` records all four agent answers.
|
|
99
|
+
|
|
100
|
+
**Fixes in 3.1.0.** If the project already applied 3.0.9, check these:
|
|
101
|
+
|
|
102
|
+
- **Install and update with `@latest`.** Use `pnpm add -D @activatus/code-standards@latest`, never a typed version number. `package.json` keeps whatever version pnpm writes. Nothing to change in the project.
|
|
103
|
+
- **`minimumReleaseAgeExclude` is the plain package name.** In `pnpm-workspace.yaml`, the entry is `"@activatus/code-standards"`, with no version. If it has versions in it, such as `'@activatus/code-standards@3.0.4 || 3.0.5'`, replace it with the plain name. Otherwise pnpm adds another version on every update.
|
|
104
|
+
- **Setup asks whether AI should ask before every commit and push.** It is optional, a yes or no, recorded under **Who commits** in Project workflow. Ask the person the [question](/docs/Guides/setup#4-working-with-the-agent). A yes is written under Who commits; a no writes nothing, and the agent uses its own judgement. Write their answer in `docs/development/coding-standards.md`, under "Details".
|
|
105
|
+
|
|
106
|
+
**How to check:** `minimumReleaseAgeExclude` lists `"@activatus/code-standards"` with no version, running `pnpm add -D @activatus/code-standards@latest` again leaves `pnpm-workspace.yaml` unchanged, and if the person said yes, Who commits in `AGENTS.md` has the asking rule.
|
|
55
107
|
|
|
56
108
|
**Fixes in 3.0.9.** If the project already applied 3.0.8, check these:
|
|
57
109
|
|
|
@@ -84,7 +136,7 @@ Install it with `pnpm add -D @activatus/code-standards@3.0.9`. Do change 1 first
|
|
|
84
136
|
**Fixes in 3.0.7.** New, optional: [Working with Agents](/docs/Standards/working-with-agents). Setup now asks for the project's GitHub repo and Linear project, and offers status circles. (3.0.7 also offered asking before every commit and push. 3.0.8 removed it.) If the project already applied 3.0.5:
|
|
85
137
|
|
|
86
138
|
- Offer the **GitHub repo** and the **Linear project**, both optional, and add each one the person confirms to the Project workflow section of `AGENTS.md`, from the [template](/docs/templates#agents). Read the repo from `git remote get-url origin` and confirm it with the person. Read the Linear project from the project's own docs if they name it, and confirm it; otherwise ask. Never copy it from another project.
|
|
87
|
-
- Print the [status circles](/docs/Guides/setup#working-with-the-agent) question to the person. If they say yes, copy the Status circles section from the template into Project workflow. Write their answer in `docs/development/coding-standards.md`, under "Details". If `AGENTS.md` already has status circles in the project's own words, keep that.
|
|
139
|
+
- Print the [status circles](/docs/Guides/setup#4-working-with-the-agent) question to the person. If they say yes, copy the Status circles section from the template into Project workflow. Write their answer in `docs/development/coding-standards.md`, under "Details". If `AGENTS.md` already has status circles in the project's own words, keep that.
|
|
88
140
|
|
|
89
141
|
**How to check:** Project workflow in `AGENTS.md` names each link the person confirmed, and `docs/development/coding-standards.md` records the answer for each option.
|
|
90
142
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@activatus/code-standards",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.1.1",
|
|
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",
|
|
@@ -41,13 +41,13 @@
|
|
|
41
41
|
|
|
42
42
|
[How this project runs its work. These are the project's own decisions, not part of the code standards. Say where they are written up (usually `docs/development/`), then list the rules an agent must follow:]
|
|
43
43
|
|
|
44
|
-
- **Who commits**: [whether AI agents may commit, push or make branches, and when]
|
|
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
|
- **Branches**: [how branches are named]
|
|
46
46
|
- **Commit messages**: [the commit message format]
|
|
47
47
|
- **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
|
|
48
48
|
- **Merging and releases**: [merge strategy, and how work reaches production]
|
|
49
49
|
- **GitHub repo**: [Optional. https://github.com/organisation/repo, read from the git remote and confirmed with the person. Delete this line if the project does not use it]
|
|
50
|
-
- **Linear project**: [Optional. Workspace,
|
|
50
|
+
- **Linear project**: [Optional. Workspace, team and project, such as `activatus-life`, team `ACT`, project Launchpad. The ticket prefix is the team's key, shared by every project in that team. Read it from the project's docs or asked for, and confirmed with the person. Delete this line if the project does not use Linear]
|
|
51
51
|
|
|
52
52
|
**Never copy a Linear workspace or ticket prefix from another project.** If the Linear project above is missing, ask before creating, linking or citing any ticket.
|
|
53
53
|
|
|
@@ -101,20 +101,26 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
|
|
|
101
101
|
- **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
|
|
102
102
|
- Do not edit `docsSite/` unless the task is about the docs viewer itself.
|
|
103
103
|
|
|
104
|
+
<!-- code-standards:start -->
|
|
105
|
+
|
|
104
106
|
## Code standards
|
|
105
107
|
|
|
108
|
+
**This section is copied from the code standards and replaced on every update.** Never edit it to describe a project exception: record exceptions in `docs/development/coding-standards.md`. Anything else the project adds, such as the block a framework writes, goes outside this section.
|
|
109
|
+
|
|
106
110
|
This project follows the Activatus Code Standards. They are installed as the `@activatus/code-standards` dev dependency: **read them in `node_modules/@activatus/code-standards/docs/`**, which is the exact version this project uses. The same pages are at https://activatus-code-standards.vercel.app for people.
|
|
107
111
|
|
|
108
112
|
**Code standards version:** [the major version of the installed `@activatus/code-standards` package when the standards were last applied]
|
|
109
113
|
|
|
110
|
-
This is the version the code follows. When the package is updated, read only the newer versions in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
|
|
114
|
+
This is the version the code follows. It is the major version only: fixes such as 3.1.1 keep it at 3, but can still ask for changes, so read the Fixes for the installed version on every update. When the package is updated, read only the newer versions in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
|
|
111
115
|
|
|
112
116
|
**Standards this project skips or changes** are listed, by number, in `docs/development/coding-standards.md`. Follow every other standard.
|
|
113
117
|
|
|
118
|
+
**The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
|
|
119
|
+
|
|
114
120
|
Follow these rules in every change:
|
|
115
121
|
|
|
116
122
|
- **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
|
|
117
|
-
- **No file longer than 300 lines
|
|
123
|
+
- **No file longer than 300 lines.** Test files are exempt, and so are `routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/`, which hold data only.
|
|
118
124
|
- **Every name is made of whole, human-readable words.** Variables, parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters (except `r` and `s`, below), no numbered names, not even for a loop counter or an event handler. Full rule: Human-Readable Names in the code standards (https://activatus-code-standards.vercel.app/docs/Standards/human-readable-names).
|
|
119
125
|
|
|
120
126
|
| Never | Always |
|
|
@@ -139,20 +145,21 @@ Follow these rules in every change:
|
|
|
139
145
|
- **Functions, never classes.**
|
|
140
146
|
- **One parameter per function.** Use a single object when more than one value is needed.
|
|
141
147
|
- **Return early.** Never nest more than three levels deep.
|
|
142
|
-
- **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare.
|
|
143
|
-
- **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
|
|
148
|
+
- **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
|
|
149
|
+
- **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. There is no component-level `constants.ts`: every link, piece of text and number goes in `lib/constants/`, even if one file uses it. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
|
|
144
150
|
- **No nested ternaries. No boolean flag parameters.**
|
|
145
151
|
- **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
|
|
146
152
|
- **Named exports only**, except where a tool requires a default export.
|
|
147
153
|
- **Type names end in `Props` or `Type`**, and say what the thing is, not the job it does. A type that only describes one field of a function's props is written inside the `Props`: `StartAgentRunProps` holds its `dependencies`, with no separate `StartAgentRunDependenciesType`. Every function still has its own `Props` for its single object parameter, such as `LaunchSessionProps` for `launchSession`, used wherever that function is written: `async ({ worktreePath }: LaunchSessionProps) =>`. Type a value where it is declared, never afterwards with `satisfies`. The one exception is Storybook story files, which follow Storybook's docs: `satisfies Meta<typeof Component>`.
|
|
148
154
|
- **One component per file.** Server and client components live in separate files.
|
|
155
|
+
- **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.
|
|
149
156
|
- **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
|
|
150
|
-
- **Reusable functions live in a `utils/` folder** — global, section or component level — one folder per function, with an `index.ts`.
|
|
151
|
-
- **Components live where they are used:** Design System Components in `components/ui/`; components used on
|
|
157
|
+
- **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.
|
|
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.
|
|
152
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.
|
|
153
160
|
- **Lay out with flexbox first**, and split layouts into child components. Only use CSS grid when specifically asked.
|
|
154
161
|
- **Style with Tailwind.** Colours come from the global colour palette in `app/globals.css` only — never a hard-coded or arbitrary colour. The design decisions are in `docs/design/design-system.md`.
|
|
155
|
-
- **Comments explain why, not what.** Never leave commented-out code.
|
|
162
|
+
- **Comments explain why, not what.** Never leave commented-out code. Mark unfinished work with `// TODO: Message` (`{/* TODO: Message */}` in JSX).
|
|
156
163
|
- **Error messages say what happened and what to do.**
|
|
157
164
|
|
|
158
165
|
**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.
|
|
@@ -163,10 +170,12 @@ Follow these rules in every change:
|
|
|
163
170
|
|
|
164
171
|
**Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code.
|
|
165
172
|
|
|
166
|
-
**Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit
|
|
173
|
+
**Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit `eslint.config.mjs` or `eslint.overrides.mjs`, or move files to hide them. The only exceptions are `let` and a type cast, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
|
|
167
174
|
|
|
168
175
|
When you report a lint error to the person, explain it in plain English: what is wrong, why it matters, and what you did to fix it.
|
|
169
176
|
|
|
177
|
+
<!-- code-standards:end -->
|
|
178
|
+
|
|
170
179
|
## Available skills
|
|
171
180
|
|
|
172
181
|
Skill files live in `.agents/skills/`, mirrored to `.claude/commands/`.
|
|
@@ -8,6 +8,12 @@
|
|
|
8
8
|
|
|
9
9
|
[What was decided.]
|
|
10
10
|
|
|
11
|
+
## Colour palette
|
|
12
|
+
|
|
13
|
+
| Colour | Value | Class names | Use for |
|
|
14
|
+
| --- | --- | --- | --- |
|
|
15
|
+
| [Brand primary] | [`#3b82f6`, or a Tailwind colour such as `slate-900`] | [`bg-brand-primary`, `text-brand-primary`] | [Buttons and links] |
|
|
16
|
+
|
|
11
17
|
## Why
|
|
12
18
|
|
|
13
19
|
[The reasons.]
|
|
@@ -6,11 +6,15 @@
|
|
|
6
6
|
|
|
7
7
|
## Decision
|
|
8
8
|
|
|
9
|
-
This project follows the Activatus Code Standards, installed as the `@activatus/code-standards` package. The person agreed which standards apply during setup (
|
|
9
|
+
This project follows the Activatus Code Standards, installed as the `@activatus/code-standards` package. The person agreed which standards apply during setup (steps 3 and 4 of `docs/Guides/setup.md` in the package).
|
|
10
10
|
|
|
11
11
|
## Details
|
|
12
12
|
|
|
13
|
-
[For each standard this project skips or changes: its number and name from the setup list, what is different, and
|
|
13
|
+
[For each standard this project skips or changes, at setup or later: its number and name from the setup list, what is different, why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
|
|
14
|
+
|
|
15
|
+
## Components for the standards
|
|
16
|
+
|
|
17
|
+
[Props-only components this project keeps in `components/ui/` that are not in the Design System Components list yet, each with its props, to be added in the next release of the standards. If there are none, write "None".]
|
|
14
18
|
|
|
15
19
|
## Unfinished changes
|
|
16
20
|
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Product — Ontology
|
|
2
|
+
|
|
3
|
+
> The words this product uses, what each one means, and how it speaks.
|
|
4
|
+
|
|
5
|
+
**Status:** Not started · **Updated:** [YYYY-MM-DD]
|
|
6
|
+
|
|
7
|
+
## Decision
|
|
8
|
+
|
|
9
|
+
These are this product's words. Code, docs, tickets and copy all use them exactly as written here. The shared words for code are in the code standards' Ontology; this file is for the product's own.
|
|
10
|
+
|
|
11
|
+
## Product words
|
|
12
|
+
|
|
13
|
+
| Word | What it means | Not to be confused with |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| [Word] | [What it means in this product] | [A word that sounds close but means something else] |
|
|
16
|
+
|
|
17
|
+
## How we speak
|
|
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] |
|
|
25
|
+
|
|
26
|
+
## Why
|
|
27
|
+
|
|
28
|
+
[Why these words and this voice.]
|
|
29
|
+
|
|
30
|
+
## Related
|
|
31
|
+
|
|
32
|
+
- [What Is It](../overview/what-is-it.md)
|
|
@@ -5,6 +5,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
|
|
|
5
5
|
import unicorn from "eslint-plugin-unicorn";
|
|
6
6
|
import globals from "globals";
|
|
7
7
|
|
|
8
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
9
|
+
|
|
8
10
|
// Code patterns that are errors in every file.
|
|
9
11
|
const RESTRICTED_SYNTAX = [
|
|
10
12
|
{
|
|
@@ -118,10 +120,17 @@ const config = [
|
|
|
118
120
|
files: ["**/*.test.{js,mjs}"],
|
|
119
121
|
rules: { "max-lines": "off", "no-magic-numbers": "off" },
|
|
120
122
|
},
|
|
123
|
+
{
|
|
124
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
125
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
|
|
126
|
+
rules: { "max-lines": "off" },
|
|
127
|
+
},
|
|
121
128
|
{
|
|
122
129
|
files: ["**/*.config.{js,mjs}"],
|
|
123
130
|
rules: { "import-x/no-default-export": "off" },
|
|
124
131
|
},
|
|
132
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
133
|
+
...projectOverrides,
|
|
125
134
|
prettier,
|
|
126
135
|
];
|
|
127
136
|
|
|
@@ -7,6 +7,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
|
|
|
7
7
|
import unicorn from "eslint-plugin-unicorn";
|
|
8
8
|
import globals from "globals";
|
|
9
9
|
|
|
10
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
11
|
+
|
|
10
12
|
// Code patterns that are errors in every file.
|
|
11
13
|
const RESTRICTED_SYNTAX = [
|
|
12
14
|
{
|
|
@@ -189,6 +191,11 @@ const config = [
|
|
|
189
191
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
190
192
|
},
|
|
191
193
|
},
|
|
194
|
+
{
|
|
195
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
196
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
197
|
+
rules: { "max-lines": "off" },
|
|
198
|
+
},
|
|
192
199
|
{
|
|
193
200
|
files: [
|
|
194
201
|
"**/*.config.{js,mjs,ts}",
|
|
@@ -223,6 +230,8 @@ const config = [
|
|
|
223
230
|
],
|
|
224
231
|
},
|
|
225
232
|
},
|
|
233
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
234
|
+
...projectOverrides,
|
|
226
235
|
prettier,
|
|
227
236
|
];
|
|
228
237
|
|
|
@@ -9,6 +9,8 @@ import unicorn from "eslint-plugin-unicorn";
|
|
|
9
9
|
import globals from "globals";
|
|
10
10
|
import { configs as typescript } from "typescript-eslint";
|
|
11
11
|
|
|
12
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
13
|
+
|
|
12
14
|
// Code patterns that are errors in every file.
|
|
13
15
|
const RESTRICTED_SYNTAX = [
|
|
14
16
|
{
|
|
@@ -191,6 +193,11 @@ const config = [
|
|
|
191
193
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
192
194
|
},
|
|
193
195
|
},
|
|
196
|
+
{
|
|
197
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
198
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
199
|
+
rules: { "max-lines": "off" },
|
|
200
|
+
},
|
|
194
201
|
{
|
|
195
202
|
files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
|
|
196
203
|
rules: { "import-x/no-default-export": "off" },
|
|
@@ -210,6 +217,8 @@ const config = [
|
|
|
210
217
|
],
|
|
211
218
|
},
|
|
212
219
|
},
|
|
220
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
221
|
+
...projectOverrides,
|
|
213
222
|
prettier,
|
|
214
223
|
];
|
|
215
224
|
|
|
@@ -7,6 +7,8 @@ import unicorn from "eslint-plugin-unicorn";
|
|
|
7
7
|
import globals from "globals";
|
|
8
8
|
import { configs as typescript } from "typescript-eslint";
|
|
9
9
|
|
|
10
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
11
|
+
|
|
10
12
|
// Code patterns that are errors in every file.
|
|
11
13
|
const RESTRICTED_SYNTAX = [
|
|
12
14
|
{
|
|
@@ -172,6 +174,11 @@ const config = [
|
|
|
172
174
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
173
175
|
},
|
|
174
176
|
},
|
|
177
|
+
{
|
|
178
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
179
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
180
|
+
rules: { "max-lines": "off" },
|
|
181
|
+
},
|
|
175
182
|
{
|
|
176
183
|
files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
|
|
177
184
|
rules: { "import-x/no-default-export": "off" },
|
|
@@ -191,6 +198,8 @@ const config = [
|
|
|
191
198
|
],
|
|
192
199
|
},
|
|
193
200
|
},
|
|
201
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
202
|
+
...projectOverrides,
|
|
194
203
|
prettier,
|
|
195
204
|
];
|
|
196
205
|
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// This project's changes to the Activatus ESLint config.
|
|
2
|
+
// eslint.config.mjs is copied from the code standards unchanged, so an
|
|
3
|
+
// update can copy it again. Every change to a lint rule goes here.
|
|
4
|
+
//
|
|
5
|
+
// Add a change only after the person agrees to it, and record it in
|
|
6
|
+
// docs/development/coding-standards.md, under "Details", with the
|
|
7
|
+
// standard's number and the reason. Name that number in a comment on
|
|
8
|
+
// each rule:
|
|
9
|
+
//
|
|
10
|
+
// {
|
|
11
|
+
// files: ["scripts/**/*.mjs"],
|
|
12
|
+
// rules: {
|
|
13
|
+
// // Standard 6: scripts print to the terminal.
|
|
14
|
+
// "no-console": "off",
|
|
15
|
+
// },
|
|
16
|
+
// },
|
|
17
|
+
|
|
18
|
+
export const projectOverrides = [];
|
|
@@ -19,7 +19,8 @@ Review the changes and report problems. Do NOT modify any files.
|
|
|
19
19
|
- **Types** — `any`, non-null `!`, and `as` casts without a comment saying why
|
|
20
20
|
- **Tests** — every new or changed function and component has a test file
|
|
21
21
|
- **Readable code** — files over 300 lines, any name that is not human-readable (folders, files, props, form field `name`s and labels, types, union values, database columns, routes, environment variables and test names as well as variables), functions doing more than one thing, more than one parameter, nesting deeper than three levels, magic numbers
|
|
22
|
-
- **Structure** — reusable functions outside a `utils/` folder, server and client code in one file, inline functions in render
|
|
22
|
+
- **Structure** — reusable functions outside a `utils/` folder (a sort, find, get, filter or format function inside a component), server and client code in one file, inline functions in render, a component copied a third time instead of merged, a copied component without a comment naming its other copy
|
|
23
|
+
- **Changed standards** — any change to `eslint.config.mjs`, and any rule in `eslint.overrides.mjs` or other change to a standard with no matching entry in `docs/development/coding-standards.md`
|
|
23
24
|
- **Styling** — hard-coded colours, CSS grid that was not asked for
|
|
24
25
|
5. Report the findings in order of severity: **Must fix**, **Should fix**, **Consider**. For each one give the file and line, what is wrong, and how to fix it.
|
|
25
26
|
6. Finish with a one-line verdict: ready to commit, or not.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** @type {import("stylelint").Config} */
|
|
2
|
-
|
|
2
|
+
const config = {
|
|
3
3
|
ignoreFiles: ["**/vendor/**"],
|
|
4
4
|
extends: [
|
|
5
5
|
"stylelint-config-standard-scss",
|
|
@@ -11,3 +11,5 @@ export default {
|
|
|
11
11
|
"color-function-notation": "modern",
|
|
12
12
|
},
|
|
13
13
|
};
|
|
14
|
+
|
|
15
|
+
export default config;
|