@activatus/code-standards 3.0.9 โ†’ 3.1.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.
package/README.md CHANGED
@@ -27,14 +27,14 @@ Ours live here. If it's not in this repo, it's not a standard, it's an opinion.
27
27
  The standards ship as an npm package, published on npm (npmjs.com) and installed with pnpm, so an AI agent reads the exact version a project uses, straight from `node_modules`:
28
28
 
29
29
  ```bash
30
- pnpm add -D @activatus/code-standards
30
+ pnpm add -D @activatus/code-standards@latest
31
31
  ```
32
32
 
33
33
  Then tell your agent: **"Follow the Activatus Code Standards. Start with `node_modules/@activatus/code-standards/docs/Guides/setup.md`."** It prints a numbered list of the standards, you say which ones you don't want, and it sets up the rest. You never touch the terminal.
34
34
 
35
35
  The package version is the standards version: `3.0.0` is version 3.
36
36
 
37
- > ๐Ÿ”ข **Updating a project to newer standards?** Run `pnpm update @activatus/code-standards --latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the versions newer than the project's, does exactly what each one says, and bumps the number. Cheaper than shouting the whole pub a round.
37
+ > ๐Ÿ”ข **Updating a project to newer standards?** Run `pnpm add -D @activatus/code-standards@latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the versions newer than the project's, does exactly what each one says, and bumps the number. Cheaper than shouting the whole pub a round.
38
38
 
39
39
  ---
40
40
 
@@ -14,9 +14,11 @@ The person creates the app themselves โ€” with `create-next-app`, Expo or anythi
14
14
  ## 1. Install the standards
15
15
 
16
16
  ```bash
17
- pnpm add -D @activatus/code-standards
17
+ pnpm add -D @activatus/code-standards@latest
18
18
  ```
19
19
 
20
+ **Always install with `@latest`, never a typed version number.** `package.json` keeps whatever version pnpm writes.
21
+
20
22
  **If pnpm refuses because the version is too new**, that is pnpm's `minimumReleaseAge` setting: by default it will not install a version published less than a day ago. The standards come from us, so add the package to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`:
21
23
 
22
24
  ```yaml title="pnpm-workspace.yaml"
@@ -24,7 +26,7 @@ minimumReleaseAgeExclude:
24
26
  - "@activatus/code-standards"
25
27
  ```
26
28
 
27
- Newer pnpm versions may add this exclusion for you when you run `pnpm add`. Check the file either way, and add it if it is not there: `pnpm update` hits the same check when a new version of the standards has only just been published.
29
+ Newer pnpm versions may add this exclusion for you when you run `pnpm add`. Check the file either way, and add it if it is not there: an update hits the same check when a new version of the standards has only just been published. 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.
28
30
 
29
31
  **pnpm owns `pnpm-workspace.yaml`** and rewrites it on every install, with single quotes, so `pnpm format:check` would fail after every update. Add the file to `.prettierignore`:
30
32
 
@@ -108,7 +110,7 @@ The list has nothing about branches or commit messages. Those are the project's
108
110
 
109
111
  ### Working with the agent
110
112
 
111
- Once the standards are agreed, offer the three [Working with Agents](/docs/Standards/working-with-agents) options. All three are optional: offer every one, every time, so the person can fill them in quickly and keep going.
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.
112
114
 
113
115
  First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
114
116
 
@@ -128,7 +130,14 @@ ticket as one line, with a circle that says if you need to act?
128
130
  Yes or no?
129
131
  ```
130
132
 
131
- **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. Write all three 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).
133
+ Then **ask before committing**. **Print this to the person exactly as it is written**:
134
+
135
+ ```text
136
+ Would you like AI to ask you before every commit and push
137
+ to git? Yes or no?
138
+ ```
139
+
140
+ **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).
132
141
 
133
142
  ## 4. Apply the standards
134
143
 
@@ -164,16 +173,16 @@ The other standards are rules for how code is written. There is nothing to insta
164
173
 
165
174
  The project already follows the standards, and a newer version is out.
166
175
 
167
- **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.
176
+ **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.
168
177
 
169
178
  1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code follows.
170
179
  2. **Update the package:**
171
180
 
172
181
  ```bash
173
- pnpm update @activatus/code-standards --latest
182
+ pnpm add -D @activatus/code-standards@latest
174
183
  ```
175
184
 
176
- Its major version is now the newest version. If pnpm refuses because the version is too new, or `pnpm format:check` now fails on `pnpm-workspace.yaml`, see [1. Install the standards](#1-install-the-standards).
185
+ Its major version is now the newest version. If pnpm refuses because the version is too new, or `pnpm format:check` now fails on `pnpm-workspace.yaml`, see [1. Install the standards](#1-install-the-standards). Check `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` is the plain name, `"@activatus/code-standards"`, with no version in it.
177
186
 
178
187
  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.
179
188
  4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
@@ -13,7 +13,7 @@ Every Activatus repository must have an `AGENTS.md` in its root. This file gives
13
13
 
14
14
  Each project writes them up in its own docs, usually in `docs/development/`, and its `AGENTS.md` has a **Project workflow** section that points to them and states the rules an agent must follow. The most important one goes first: whether an agent may commit.
15
15
 
16
- Project workflow also records whichever [Working with Agents](/docs/Standards/working-with-agents) options the project chose during setup: its **GitHub repo**, its **Linear project** and the **status circles**. All three are optional; delete the line or section for any the project does not use.
16
+ Project workflow also records whichever [Working with Agents](/docs/Standards/working-with-agents) options the project chose during setup: its **GitHub repo**, its **Linear project**, the **status circles**, and whether agents **ask before every commit and push** (written under Who commits). All four are optional; delete the line or section for any the project does not use.
17
17
 
18
18
  ## Template
19
19
 
@@ -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 and reports on it. The GitHub repo, the Linear project and the status circles are all optional. [Setup](/docs/Guides/setup#working-with-the-agent) offers all three 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#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
 
@@ -42,4 +42,6 @@ Optional. An agent reports the state of every ticket or piece of work as one lin
42
42
  - **No ticket is fine.** Work without one is just the circle and a short title.
43
43
  - **Only what the person needs.** Leave out anything they already know.
44
44
 
45
- Whether and when agents commit is not part of this. It is the project's own workflow, under **Who commits** in Project workflow.
45
+ ## Ask before committing
46
+
47
+ Optional. Setup asks: "Would you like AI to ask you before every commit and push to git?" A yes is written under **Who commits** in Project workflow: ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only. A no means nothing is written, and the agent uses its own judgement.
package/docs/intro.md CHANGED
@@ -22,7 +22,7 @@ This site documents the shared code standards used across all Activatus projects
22
22
  | EditorConfig | [`.editorconfig`](/docs/Standards/editorconfig) | Editor-level whitespace rules |
23
23
  | direnv + nvm | [`.envrc` / `.nvmrc`](/docs/Standards/direnv) | Automatic Node version switching on `cd` |
24
24
  | AGENTS.md | [`AGENTS.md`](/docs/Standards/agent-specs) | AI agent context and agent skills |
25
- | Working with Agents | [Optional](/docs/Standards/working-with-agents) | GitHub repo, Linear project and status circles: all optional, offered during setup |
25
+ | Working with Agents | [Optional](/docs/Standards/working-with-agents) | GitHub repo, Linear project, status circles and asking before commits: all optional |
26
26
  | CSS Styling | [Styling guide](/docs/Standards/styling) | Tailwind CSS, flexbox-first layout and global colour variables |
27
27
  | Tech Stack | [Tech stack](/docs/Standards/tech-stack) | The frameworks, libraries and versions we build on |
28
28
 
@@ -18,14 +18,14 @@ 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 update @activatus/code-standards --latest`. 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). Then read this page from `node_modules/@activatus/code-standards/docs/version-history.md`.
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
26
  7. **Update the version number** in `AGENTS.md` once every change is done.
27
27
 
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.
28
+ **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.
29
29
 
30
30
  **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
31
 
@@ -41,6 +41,7 @@ Anyone changing the standards adds a version, alongside the change:
41
41
  - **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
42
  - **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
43
  - **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.
44
+ - **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
45
  - **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
46
  - **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
47
  - **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 +50,17 @@ Anyone changing the standards adds a version, alongside the change:
49
50
 
50
51
  ## Version 3
51
52
 
52
- **Released:** 2026-10-17 ยท **Updates from:** version 2 ยท **Latest fix:** 3.0.9
53
+ **Released:** 2026-10-17 ยท **Updates from:** version 2 ยท **Latest fix:** 3.1.0
53
54
 
54
- Install it with `pnpm add -D @activatus/code-standards@3.0.9`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
55
+ 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.
56
+
57
+ **Fixes in 3.1.0.** If the project already applied 3.0.9, check these:
58
+
59
+ - **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.
60
+ - **`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.
61
+ - **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#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".
62
+
63
+ **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
64
 
56
65
  **Fixes in 3.0.9.** If the project already applied 3.0.8, check these:
57
66
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.0.9",
3
+ "version": "3.1.0",
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,7 +41,7 @@
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]