@activatus/code-standards 3.0.8 → 3.0.9

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.
@@ -30,7 +30,7 @@ Add `prettier.config.mjs` — see the [Prettier page](/docs/Standards/prettier)
30
30
  Format everything at once:
31
31
 
32
32
  ```bash
33
- pnpm prettier --write .
33
+ pnpm format
34
34
  ```
35
35
 
36
36
  Keep the reformat apart from any other change, so the formatting is easy to tell apart from real changes later.
@@ -108,12 +108,14 @@ The list has nothing about branches or commit messages. Those are the project's
108
108
 
109
109
  ### Working with the agent
110
110
 
111
- Once the standards are agreed, get the **project links**:
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.
112
112
 
113
- - **GitHub repo:** read it with `git remote get-url origin` and ask the person to confirm it. If there is no remote, ask for it.
114
- - **Linear project:** if the project's own docs already name it, read it from there and ask the person to confirm it. Otherwise ask. Never copy it from another project. Write the workspace, the project and the ticket prefix, or "None" if the project does not use Linear.
113
+ First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
115
114
 
116
- Then **print this to the person exactly as it is written**:
115
+ - **GitHub repo:** read it with `git remote get-url origin`. If there is no remote, ask for it.
116
+ - **Linear project:** read it from the project's own docs if they name it: the workspace, the project and the ticket prefix. If they do not, ask. Never copy it from another project.
117
+
118
+ Then the **status circles**. **Print this to the person exactly as it is written**:
117
119
 
118
120
  ```text
119
121
  Status circles (optional). Want the agent to report each
@@ -126,7 +128,7 @@ ticket as one line, with a circle that says if you need to act?
126
128
  Yes or no?
127
129
  ```
128
130
 
129
- **Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: the project links, and the status circles if they said yes. Delete the status circles section if they said no. Write the answer 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).
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).
130
132
 
131
133
  ## 4. Apply the standards
132
134
 
@@ -139,7 +141,7 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
139
141
  | Standard | What to set up |
140
142
  | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
141
143
  | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
142
- | 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the scripts `"format": "prettier --write ."` and `"format:check": "prettier --check ."` |
144
+ | 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) |
143
145
  | 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) |
144
146
  | 9. EditorConfig | Copy `static/templates/.editorconfig` |
145
147
  | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
@@ -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 the project's **GitHub repo** and **Linear project**, and the [status circles](/docs/Standards/working-with-agents#status-circles) if the project chose them during setup.
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.
17
17
 
18
18
  ## Template
19
19
 
@@ -51,12 +51,34 @@ Add scripts to `package.json`:
51
51
  ```json
52
52
  {
53
53
  "scripts": {
54
- "format": "prettier --write .",
55
- "format:check": "prettier --check ."
54
+ "format": "git ls-files -z --cached --others --exclude-standard | xargs -0 prettier --write --ignore-unknown --no-error-on-unmatched-pattern",
55
+ "format:check": "git ls-files -z --cached --others --exclude-standard | xargs -0 prettier --check --ignore-unknown --no-error-on-unmatched-pattern"
56
56
  }
57
57
  }
58
58
  ```
59
59
 
60
+ **Do not shorten these to `prettier --write .` and `prettier --check .`** The long form is deliberate: git lists the files, so every git ignore rule applies. See [What Prettier skips](#what-prettier-skips).
61
+
62
+ ## What Prettier skips
63
+
64
+ Both scripts work on the same list of files: every file git tracks, plus every new file git has not been told to ignore. **Never narrow them to changed files**: a badly formatted file nobody touched still fails CI.
65
+
66
+ **Why git lists the files.** On its own, Prettier reads only the project's `.gitignore` and `.prettierignore`. It does not read `.git/info/exclude` or a person's global git ignore, such as `~/.config/git/ignore`. Files a person keeps out of git that way, such as `.claude/settings.local.json`, would be checked by `prettier --check .` and rewritten by `prettier --write .`, so `format:check` failed on that one machine while CI passed. `git ls-files --exclude-standard` applies every git ignore rule, so those files never reach Prettier. `--no-error-on-unmatched-pattern` stops a file deleted but not yet committed from causing an error.
67
+
68
+ **Where each kind of file is ignored:**
69
+
70
+ | File | Where it goes |
71
+ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
72
+ | One person's local tool files, such as `.claude/settings.local.json` | That person's `.git/info/exclude` or global git ignore. Never `.prettierignore` |
73
+ | Files the whole project keeps out of git, such as `build/` | `.gitignore` |
74
+ | Files in git that Prettier must not format, such as `pnpm-workspace.yaml` | `.prettierignore`, shared by the whole project |
75
+
76
+ pnpm rewrites `pnpm-workspace.yaml` in its own style on every install, so it always goes in `.prettierignore`:
77
+
78
+ ```text title=".prettierignore"
79
+ pnpm-workspace.yaml
80
+ ```
81
+
60
82
  ## Tailwind class sorting
61
83
 
62
84
  The config includes [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss), the official Tailwind plugin. It sorts the classes in every `className` into one standard order when the file is formatted, so the same classes are always written the same way:
@@ -5,13 +5,13 @@ 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 project links are part of every setup; the status circles are optional, chosen during [Setup](/docs/Guides/setup#working-with-the-agent). Both 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 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`.
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
 
12
12
  ## Project links
13
13
 
14
- Every project records these two links in **Project workflow**. An agent uses them to link tickets and Pull Requests, and to know where work belongs.
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
16
  | Link | Where it comes from |
17
17
  | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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) | The project's GitHub repo and Linear project, and optional status circles |
25
+ | Working with Agents | [Optional](/docs/Standards/working-with-agents) | GitHub repo, Linear project and status circles: all optional, offered during setup |
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
 
@@ -22,7 +22,7 @@ sidebar_label: "Version History"
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
- 6. **Run `pnpm lint`, `pnpm test` and the build** after each change.
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
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.
@@ -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
+ - **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.
44
45
  - **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.
45
46
  - **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.
46
47
 
@@ -48,13 +49,31 @@ Anyone changing the standards adds a version, alongside the change:
48
49
 
49
50
  ## Version 3
50
51
 
51
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.0.8
52
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.0.9
52
53
 
53
- Install it with `pnpm add -D @activatus/code-standards@3.0.8`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
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
+
56
+ **Fixes in 3.0.9.** If the project already applied 3.0.8, check these:
57
+
58
+ - **The project links are optional, like the status circles.** The GitHub repo, the Linear project and the status circles are all optional, and setup offers all three every time. If the project does not use a link, delete its line from Project workflow in `AGENTS.md`. Record all three answers in `docs/development/coding-standards.md`, under "Details". An agent still never copies a Linear workspace or ticket prefix from another project: if `AGENTS.md` does not name the Linear project, it asks before creating, linking or citing any ticket.
59
+ - **`format` and `format:check` get their files from git.** Prettier reads the project's `.gitignore` and `.prettierignore`, but not `.git/info/exclude` or a person's global git ignore, so local tool files kept out of git that way, such as `.claude/settings.local.json`, made `pnpm format:check` fail on that machine only, and `pnpm format` rewrote them. Replace both scripts in `package.json`:
60
+
61
+ ```json
62
+ "format": "git ls-files -z --cached --others --exclude-standard | xargs -0 prettier --write --ignore-unknown --no-error-on-unmatched-pattern",
63
+ "format:check": "git ls-files -z --cached --others --exclude-standard | xargs -0 prettier --check --ignore-unknown --no-error-on-unmatched-pattern"
64
+ ```
65
+
66
+ Do not shorten them back to `prettier --write .` or `prettier --check .`. See [What Prettier skips](/docs/Standards/prettier#what-prettier-skips).
67
+
68
+ - **Take local tool files back out of `.prettierignore`.** If the project added files that are kept out of git only on someone's machine, such as `.claude/settings.local.json` or `.impeccable/*.local.json`, remove them: git's ignore rules cover them now. Keep entries for files in git that a tool rewrites, such as `pnpm-workspace.yaml`.
69
+ - **The 3.0.8 fix for option B missed a line.** If 3.0.7 also put "Ask before every commit and push" at the very top of `AGENTS.md`, remove that line too, unless the person wants to keep it as the project's own "Who commits" rule.
70
+ - Nothing to do in a project: release commits are titled `docs: version N.N.N — <what changed>`.
71
+
72
+ **How to check:** `AGENTS.md` has no line for a project link the person said "None" to, and no "Ask before every commit and push" line unless the person kept it. `docs/development/coding-standards.md` records the answer for each of the three options. Both scripts in `package.json` start with `git ls-files`, `.prettierignore` has no local tool files, and `pnpm format:check` passes.
54
73
 
55
74
  **Fixes in 3.0.8.** If the project already applied 3.0.7, check these:
56
75
 
57
- - **Ask before every commit and push (option B) is gone.** Whether agents commit is the project's own workflow, as in change 1. If the project took B in 3.0.7, the rule stays only if the person wants it: it belongs under **Who commits** in Project workflow, in the project's own words. Remove the "Ask before every commit and push" section copied from the template, and take B off `docs/development/coding-standards.md`.
76
+ - **Ask before every commit and push (option B) is gone.** Whether agents commit is the project's own workflow, as in change 1. If the project took B in 3.0.7, the rule stays only if the person wants it: it belongs under **Who commits** in Project workflow, in the project's own words. Remove the "Ask before every commit and push" section copied from the template. 3.0.7 also put the rule at the very top of `AGENTS.md`: remove that line too, unless the person wants to keep it as the project's own "Who commits" rule. Take B off `docs/development/coding-standards.md`.
58
77
  - **The Linear project can come from the project's own docs.** If they already name it, read it from there and confirm it with the person. Never copy it from another project.
59
78
  - **`pnpm-workspace.yaml` is Prettier-ignored.** pnpm rewrites it with single quotes on every install, so `pnpm format:check` failed after every update. Add `pnpm-workspace.yaml` to `.prettierignore`.
60
79
  - **The update steps cover pnpm's release-age check**: if pnpm refuses a version that has only just been published, add the package to `minimumReleaseAgeExclude`. See [Setup](/docs/Guides/setup#1-install-the-standards).
@@ -64,10 +83,10 @@ Install it with `pnpm add -D @activatus/code-standards@3.0.8`. Do change 1 first
64
83
 
65
84
  **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:
66
85
 
67
- - Add **GitHub repo** and **Linear project** 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.
86
+ - 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.
68
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.
69
88
 
70
- **How to check:** Project workflow in `AGENTS.md` names the GitHub repo and the Linear project, and `docs/development/coding-standards.md` records whether the project took the status circles.
89
+ **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.
71
90
 
72
91
  **Fixes in 3.0.6.** Never published to npm: these fixes are in 3.0.7. Nothing to do in a project. The update steps gained two rules: when the project's `AGENTS.md` records the standards in its own words, an update writes the changed line in that shape; and after an update the project's list of opted-out and changed standards is re-read, taking off it anything the new version now covers. The 3.0.5 numbers change has its check spelled out: `pnpm lint` reporting a `no-magic-numbers` finding means it is not finished. A project-specific block in an ESLint config is now defined: it is recorded in the project's `docs/development/coding-standards.md`, or `pnpm lint` fails without it.
73
92
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.0.8",
3
+ "version": "3.0.9",
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",
@@ -46,8 +46,8 @@
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
- - **GitHub repo**: [https://github.com/organisation/repo, read from the git remote and confirmed with the person]
50
- - **Linear project**: [workspace, project and ticket prefix, such as `activatus-life`, Launchpad, `ACT`, read from the project's docs or asked for, and confirmed with the person. Or "None"]
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, project and ticket prefix, such as `activatus-life`, Launchpad, `ACT`, read 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