@activatus/code-standards 3.1.0 → 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/docs/Guides/migrating.md +14 -0
- package/docs/Guides/setup.md +55 -20
- 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 +5 -5
- 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/ontology.md +1 -1
- package/docs/templates.mdx +2 -2
- package/docs/version-history.md +48 -5
- package/package.json +1 -1
- package/static/templates/AGENTS.md +18 -9
- 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/Guides/migrating.md
CHANGED
|
@@ -19,6 +19,8 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
|
|
|
19
19
|
|
|
20
20
|
## Stage 1 — Prettier (formatting only)
|
|
21
21
|
|
|
22
|
+
Applies setup standard 7.
|
|
23
|
+
|
|
22
24
|
Formatting changes are safe to make all at once because they don't change behaviour.
|
|
23
25
|
|
|
24
26
|
```bash
|
|
@@ -47,10 +49,14 @@ vendor/
|
|
|
47
49
|
|
|
48
50
|
## Stage 2 — EditorConfig
|
|
49
51
|
|
|
52
|
+
Applies setup standard 9.
|
|
53
|
+
|
|
50
54
|
Add the `.editorconfig` file. No code changes needed — your editor will handle it on next save.
|
|
51
55
|
|
|
52
56
|
## Stage 3 — ESLint
|
|
53
57
|
|
|
58
|
+
Applies setup standard 6.
|
|
59
|
+
|
|
54
60
|
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`:
|
|
55
61
|
|
|
56
62
|
```js
|
|
@@ -74,6 +80,8 @@ Run `pnpm lint` and triage the output. Fix them one kind at a time (for example,
|
|
|
74
80
|
|
|
75
81
|
## Stage 4 — Names
|
|
76
82
|
|
|
83
|
+
Applies setup standard 1.
|
|
84
|
+
|
|
77
85
|
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
86
|
|
|
79
87
|
### 1. Decide what stays
|
|
@@ -154,14 +162,20 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
|
|
|
154
162
|
|
|
155
163
|
## Stage 5 — AGENTS.md
|
|
156
164
|
|
|
165
|
+
Applies setup standard 21.
|
|
166
|
+
|
|
157
167
|
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).
|
|
158
168
|
|
|
159
169
|
## Stage 6 — Agent skills
|
|
160
170
|
|
|
171
|
+
Applies setup standard 21.
|
|
172
|
+
|
|
161
173
|
Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
|
|
162
174
|
|
|
163
175
|
## Stage 7 — Docs
|
|
164
176
|
|
|
177
|
+
Applies setup standard 18.
|
|
178
|
+
|
|
165
179
|
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`.
|
|
166
180
|
|
|
167
181
|
## Tips
|
package/docs/Guides/setup.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
120
|
+
**Then go straight to step 4.** Setup is not finished until the person has answered it.
|
|
112
121
|
|
|
113
|
-
|
|
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
|
|
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
|
-
##
|
|
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,17 +158,17 @@ 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
|
|
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`), `
|
|
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/` |
|
|
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
|
|
|
@@ -165,7 +176,30 @@ The other standards are rules for how code is written. There is nothing to insta
|
|
|
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
178
|
2. Running `pnpm lint`, `pnpm format:check` and the tests.
|
|
168
|
-
3.
|
|
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. **Tell the person** what you changed, or that the project was already up to date.
|
|
169
203
|
|
|
170
204
|
---
|
|
171
205
|
|
|
@@ -187,7 +221,8 @@ The project already follows the standards, and a newer version is out.
|
|
|
187
221
|
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
222
|
4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
|
|
189
223
|
5. **Do every other change** as its "What to do" says, and run its "How to check" search.
|
|
190
|
-
6. **
|
|
224
|
+
6. **Ask any [step 4](#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
|
|
225
|
+
7. **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
226
|
|
|
192
227
|
See the [Version History](/docs/version-history) for the full update rules.
|
|
193
228
|
|
|
@@ -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
|
+
**A folder that cannot apply to the project may be deleted**, such as `data/` or `security/` on a marketing site with no database or accounts. Ask the person first, and record the deleted folders and the reason in `docs/development/coding-standards.md`, under "Details".
|
|
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
|
|
@@ -262,7 +270,7 @@ export default nextConfig;
|
|
|
262
270
|
|
|
263
271
|
## 🚀 Setting it up
|
|
264
272
|
|
|
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
|
|
273
|
+
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
274
|
|
|
267
275
|
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
276
|
|
|
@@ -296,6 +304,8 @@ export default nextConfig;
|
|
|
296
304
|
|
|
297
305
|
Open `http://localhost:3000/docs`.
|
|
298
306
|
|
|
307
|
+
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.
|
|
308
|
+
|
|
299
309
|
:::caution[Do not name the script `docs`]
|
|
300
310
|
|
|
301
311
|
`pnpm docs` is a built-in pnpm command, so a script called `docs` never runs. Use `docs:dev`.
|
package/docs/Standards/eslint.md
CHANGED
|
@@ -80,6 +80,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
|
|
|
80
80
|
import unicorn from "eslint-plugin-unicorn";
|
|
81
81
|
import globals from "globals";
|
|
82
82
|
|
|
83
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
84
|
+
|
|
83
85
|
// Code patterns that are errors in every file.
|
|
84
86
|
const RESTRICTED_SYNTAX = [
|
|
85
87
|
{
|
|
@@ -193,10 +195,17 @@ const config = [
|
|
|
193
195
|
files: ["**/*.test.{js,mjs}"],
|
|
194
196
|
rules: { "max-lines": "off", "no-magic-numbers": "off" },
|
|
195
197
|
},
|
|
198
|
+
{
|
|
199
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
200
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
|
|
201
|
+
rules: { "max-lines": "off" },
|
|
202
|
+
},
|
|
196
203
|
{
|
|
197
204
|
files: ["**/*.config.{js,mjs}"],
|
|
198
205
|
rules: { "import-x/no-default-export": "off" },
|
|
199
206
|
},
|
|
207
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
208
|
+
...projectOverrides,
|
|
200
209
|
prettier,
|
|
201
210
|
];
|
|
202
211
|
|
|
@@ -215,6 +224,8 @@ import unicorn from "eslint-plugin-unicorn";
|
|
|
215
224
|
import globals from "globals";
|
|
216
225
|
import { configs as typescript } from "typescript-eslint";
|
|
217
226
|
|
|
227
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
228
|
+
|
|
218
229
|
// Code patterns that are errors in every file.
|
|
219
230
|
const RESTRICTED_SYNTAX = [
|
|
220
231
|
{
|
|
@@ -380,6 +391,11 @@ const config = [
|
|
|
380
391
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
381
392
|
},
|
|
382
393
|
},
|
|
394
|
+
{
|
|
395
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
396
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
397
|
+
rules: { "max-lines": "off" },
|
|
398
|
+
},
|
|
383
399
|
{
|
|
384
400
|
files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
|
|
385
401
|
rules: { "import-x/no-default-export": "off" },
|
|
@@ -399,6 +415,8 @@ const config = [
|
|
|
399
415
|
],
|
|
400
416
|
},
|
|
401
417
|
},
|
|
418
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
419
|
+
...projectOverrides,
|
|
402
420
|
prettier,
|
|
403
421
|
];
|
|
404
422
|
|
|
@@ -423,6 +441,8 @@ import unicorn from "eslint-plugin-unicorn";
|
|
|
423
441
|
import globals from "globals";
|
|
424
442
|
import { configs as typescript } from "typescript-eslint";
|
|
425
443
|
|
|
444
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
445
|
+
|
|
426
446
|
// Code patterns that are errors in every file.
|
|
427
447
|
const RESTRICTED_SYNTAX = [
|
|
428
448
|
{
|
|
@@ -605,6 +625,11 @@ const config = [
|
|
|
605
625
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
606
626
|
},
|
|
607
627
|
},
|
|
628
|
+
{
|
|
629
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
630
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
631
|
+
rules: { "max-lines": "off" },
|
|
632
|
+
},
|
|
608
633
|
{
|
|
609
634
|
files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
|
|
610
635
|
rules: { "import-x/no-default-export": "off" },
|
|
@@ -624,6 +649,8 @@ const config = [
|
|
|
624
649
|
],
|
|
625
650
|
},
|
|
626
651
|
},
|
|
652
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
653
|
+
...projectOverrides,
|
|
627
654
|
prettier,
|
|
628
655
|
];
|
|
629
656
|
|
|
@@ -650,6 +677,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
|
|
|
650
677
|
import unicorn from "eslint-plugin-unicorn";
|
|
651
678
|
import globals from "globals";
|
|
652
679
|
|
|
680
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
681
|
+
|
|
653
682
|
// Code patterns that are errors in every file.
|
|
654
683
|
const RESTRICTED_SYNTAX = [
|
|
655
684
|
{
|
|
@@ -832,6 +861,11 @@ const config = [
|
|
|
832
861
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
833
862
|
},
|
|
834
863
|
},
|
|
864
|
+
{
|
|
865
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
866
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
867
|
+
rules: { "max-lines": "off" },
|
|
868
|
+
},
|
|
835
869
|
{
|
|
836
870
|
files: [
|
|
837
871
|
"**/*.config.{js,mjs,ts}",
|
|
@@ -866,6 +900,8 @@ const config = [
|
|
|
866
900
|
],
|
|
867
901
|
},
|
|
868
902
|
},
|
|
903
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
904
|
+
...projectOverrides,
|
|
869
905
|
prettier,
|
|
870
906
|
];
|
|
871
907
|
|
|
@@ -882,23 +918,27 @@ Use the `globals` package rather than turning `no-undef` off or hand-writing a g
|
|
|
882
918
|
|
|
883
919
|
### Project-specific overrides
|
|
884
920
|
|
|
885
|
-
|
|
921
|
+
**Never change `eslint.config.mjs`.** It is copied from the standards unchanged, so an update can copy the new version straight over it. A project's own rule changes live in `eslint.overrides.mjs`, which the config reads just before `prettier`. Copy it from `static/templates/eslint.overrides.mjs`: it starts empty.
|
|
886
922
|
|
|
887
|
-
|
|
888
|
-
const config = [
|
|
889
|
-
// ...
|
|
890
|
-
{
|
|
891
|
-
rules: {
|
|
892
|
-
// project-specific overrides
|
|
893
|
-
"no-console": "off",
|
|
894
|
-
},
|
|
895
|
-
},
|
|
896
|
-
prettier,
|
|
897
|
-
];
|
|
923
|
+
**A change needs the person's yes first.** The standards are the project's base, so an agent never switches off, loosens or changes a rule on its own. Ask, then:
|
|
898
924
|
|
|
899
|
-
|
|
925
|
+
1. Record it in `docs/development/coding-standards.md`, under "Details": the standard's number and name, what is different, why, and the date.
|
|
926
|
+
2. Add it to `eslint.overrides.mjs`, with a comment naming the standard's number.
|
|
927
|
+
|
|
928
|
+
```js title="eslint.overrides.mjs"
|
|
929
|
+
export const projectOverrides = [
|
|
930
|
+
{
|
|
931
|
+
files: ["scripts/**/*.mjs"],
|
|
932
|
+
rules: {
|
|
933
|
+
// Standard 6: scripts print to the terminal.
|
|
934
|
+
"no-console": "off",
|
|
935
|
+
},
|
|
936
|
+
},
|
|
937
|
+
];
|
|
900
938
|
```
|
|
901
939
|
|
|
940
|
+
A rule change in `eslint.overrides.mjs` with no matching entry in `coding-standards.md` is a mistake: the codeReview skill flags it. The only changes made without asking are the single-line `let` and type-cast exceptions: see [the only allowed exceptions](/docs/Standards/lint-errors#the-only-allowed-exceptions).
|
|
941
|
+
|
|
902
942
|
Keep `prettier` last — it switches off every rule that would fight the formatter.
|
|
903
943
|
|
|
904
944
|
Add scripts to `package.json`:
|
|
@@ -981,7 +1021,7 @@ Every `eslint-disable` comment must say why, after `--`. A rule is never switche
|
|
|
981
1021
|
|
|
982
1022
|
### `max-lines: 300`
|
|
983
1023
|
|
|
984
|
-
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
|
|
1024
|
+
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are `lib/constants/routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts`, which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
|
|
985
1025
|
|
|
986
1026
|
### `max-depth: 3`
|
|
987
1027
|
|
|
@@ -63,10 +63,10 @@ This applies to everyone, **including AI agents**. An agent's work is not finish
|
|
|
63
63
|
|
|
64
64
|
## Files
|
|
65
65
|
|
|
66
|
-
| Rule | What you will see | What it means | How to fix it
|
|
67
|
-
| ----------------------- | ------------------------------------------------------- | ---------------------------------- |
|
|
68
|
-
| `max-lines` | `File has too many lines (312). Maximum allowed is 300` | The file is over 300 lines | Split it: move functions to `utils/`, sub-components to their own folders, types to `types.ts` |
|
|
69
|
-
| `unicorn/filename-case` | `Filename is not in camel case or pascal case` | The file name is in the wrong case | Rename it: camelCase for code files, PascalCase for component files
|
|
66
|
+
| Rule | What you will see | What it means | How to fix it |
|
|
67
|
+
| ----------------------- | ------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
68
|
+
| `max-lines` | `File has too many lines (312). Maximum allowed is 300` | The file is over 300 lines | Split it: move functions to `utils/`, sub-components to their own folders, types to `types.ts`. `routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/` never get this error |
|
|
69
|
+
| `unicorn/filename-case` | `Filename is not in camel case or pascal case` | The file name is in the wrong case | Rename it: camelCase for code files, PascalCase for component files |
|
|
70
70
|
|
|
71
71
|
## Types
|
|
72
72
|
|
|
@@ -43,6 +43,8 @@ A file over 300 lines is doing more than one job. Split it before it gets there:
|
|
|
43
43
|
|
|
44
44
|
Blank lines and comments do not count towards the limit. **Test files are exempt** — a thorough test file can run long.
|
|
45
45
|
|
|
46
|
+
**`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/` are exempt too.** They are lists of data, not logic, and a big app has a lot of links and text. Splitting them would mean more places to look for one label. They stay data only: no functions in them. See [Constants](/docs/Structure/folder-structure#constants).
|
|
47
|
+
|
|
46
48
|
---
|
|
47
49
|
|
|
48
50
|
## Names are full English words
|
|
@@ -311,7 +313,7 @@ if (order.status === "shipped") {
|
|
|
311
313
|
|
|
312
314
|
**`-1`, `0` and `1` are allowed**, because they are part of how code works rather than a choice anyone makes: `0` is the start or nothing (`items[0]`, `length === 0`), `1` is one more or one less (`index + 1`), and `-1` is "not found" (`indexOf`). Any other number was chosen by someone, so its name says what it controls. Even `2` gets a name.
|
|
313
315
|
|
|
314
|
-
|
|
316
|
+
Every named number lives in `lib/constants/numbers.ts`, even one only one file uses. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
|
|
315
317
|
|
|
316
318
|
---
|
|
317
319
|
|
|
@@ -422,6 +424,7 @@ await waitMilliseconds(1000);
|
|
|
422
424
|
|
|
423
425
|
- If a comment describes **what** the code does, rename things until the comment is not needed.
|
|
424
426
|
- **Never leave commented-out code.** Delete it — Git remembers.
|
|
427
|
+
- **Mark unfinished work with `// TODO: Message`**, or `{/* TODO: Message */}` in JSX. Editors with the TODO Highlight extension (Wayou Liu) list them automatically. A project can also list them under "Unfinished changes" in `docs/development/coding-standards.md`.
|
|
425
428
|
|
|
426
429
|
---
|
|
427
430
|
|
|
@@ -32,7 +32,7 @@ Create `stylelint.config.mjs` in your project root:
|
|
|
32
32
|
|
|
33
33
|
```js title="stylelint.config.mjs"
|
|
34
34
|
/** @type {import("stylelint").Config} */
|
|
35
|
-
|
|
35
|
+
const config = {
|
|
36
36
|
ignoreFiles: ["**/vendor/**"],
|
|
37
37
|
extends: [
|
|
38
38
|
"stylelint-config-standard",
|
|
@@ -71,13 +71,15 @@ export default {
|
|
|
71
71
|
},
|
|
72
72
|
],
|
|
73
73
|
};
|
|
74
|
+
|
|
75
|
+
export default config;
|
|
74
76
|
```
|
|
75
77
|
|
|
76
78
|
### SCSS
|
|
77
79
|
|
|
78
80
|
```js title="stylelint.config.mjs"
|
|
79
81
|
/** @type {import("stylelint").Config} */
|
|
80
|
-
|
|
82
|
+
const config = {
|
|
81
83
|
ignoreFiles: ["**/vendor/**"],
|
|
82
84
|
extends: [
|
|
83
85
|
"stylelint-config-standard-scss",
|
|
@@ -89,6 +91,8 @@ export default {
|
|
|
89
91
|
"color-function-notation": "modern",
|
|
90
92
|
},
|
|
91
93
|
};
|
|
94
|
+
|
|
95
|
+
export default config;
|
|
92
96
|
```
|
|
93
97
|
|
|
94
98
|
### Project-specific overrides
|
|
@@ -96,7 +100,7 @@ export default {
|
|
|
96
100
|
Add to the `rules` block:
|
|
97
101
|
|
|
98
102
|
```js
|
|
99
|
-
|
|
103
|
+
const config = {
|
|
100
104
|
// ...
|
|
101
105
|
rules: {
|
|
102
106
|
// ...
|
|
@@ -104,6 +108,8 @@ export default {
|
|
|
104
108
|
"selector-max-type": 3,
|
|
105
109
|
},
|
|
106
110
|
};
|
|
111
|
+
|
|
112
|
+
export default config;
|
|
107
113
|
```
|
|
108
114
|
|
|
109
115
|
Add a lint script to `package.json`:
|
|
@@ -149,7 +149,11 @@ Each project defines its colours once, in its global stylesheet:
|
|
|
149
149
|
|
|
150
150
|
Tailwind turns every `--color-*` variable in `@theme` into utility classes: `--color-brand-primary` becomes `bg-brand-primary`, `text-brand-primary`, `border-brand-primary` and so on.
|
|
151
151
|
|
|
152
|
-
|
|
152
|
+
**`globals.css` is only for project colours.** Tailwind's built-in colours (`bg-slate-900`) need nothing there. Add a colour to `@theme` only when the design needs one Tailwind does not have, such as the brand colours.
|
|
153
|
+
|
|
154
|
+
**The palette is listed in `docs/design/design-system.md`**, so anyone can see every colour without reading CSS: each colour's name, value, class names and what it is for. The project's other design decisions, the fonts and the spacing, are recorded in the same [Decision Doc](/docs/Standards/documentation).
|
|
155
|
+
|
|
156
|
+
To see each colour in the editor, install **Tailwind CSS IntelliSense** (Tailwind Labs). It shows a swatch of the actual colour beside each class name.
|
|
153
157
|
|
|
154
158
|
### ✅ Use the colours
|
|
155
159
|
|
|
@@ -5,7 +5,7 @@ sidebar_label: "Working with Agents"
|
|
|
5
5
|
|
|
6
6
|
# Working with Agents
|
|
7
7
|
|
|
8
|
-
> How an AI agent links a project's work, reports on it and asks before committing. The GitHub repo, the Linear project, the status circles and asking before every commit and push are all optional. [Setup](/docs/Guides/setup#working-with-the-agent) offers all four every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
|
|
8
|
+
> How an AI agent links a project's work, reports on it and asks before committing. The GitHub repo, the Linear project, the status circles and asking before every commit and push are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all four every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
|
|
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
|
|
|
@@ -13,10 +13,10 @@ Whatever the project chooses is written into the **Project workflow** section of
|
|
|
13
13
|
|
|
14
14
|
Optional. A project records either link, both or neither, in **Project workflow**, and deletes the line for any link it does not use. An agent uses them to link tickets and Pull Requests, and to know where work belongs.
|
|
15
15
|
|
|
16
|
-
| Link | Where it comes from
|
|
17
|
-
| -------------- |
|
|
18
|
-
| GitHub repo | Read it from `git remote get-url origin` and confirm it with the person. If there is no remote, ask
|
|
19
|
-
| Linear project | If the project's own docs already name it, read it from there and confirm it with the person. Otherwise ask. Write the workspace, the
|
|
16
|
+
| Link | Where it comes from |
|
|
17
|
+
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
18
|
+
| GitHub repo | Read it from `git remote get-url origin` and confirm it with the person. If there is no remote, ask |
|
|
19
|
+
| Linear project | If the project's own docs already name it, read it from there and confirm it with the person. Otherwise ask. Write the workspace, the team and the project, such as `activatus-life`, team `ACT`, project Launchpad, or "None". The ticket prefix, such as `ACT`, is the team's: every project in that team shares it |
|
|
20
20
|
|
|
21
21
|
**Never copy a Linear workspace or ticket prefix from another project.** Projects under the same organisation often live in different Linear workspaces or projects, and a guessed prefix files tickets in the wrong place. If `AGENTS.md` does not name the Linear project, ask before creating, linking or citing any ticket.
|
|
22
22
|
|