@activatus/code-standards 3.0.5 → 3.0.7
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/setup.md
CHANGED
|
@@ -9,7 +9,7 @@ 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
|
|
12
|
+
**These standards are the base for code, plus optional ways of working with the agent.** 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). Those go in the project's own docs, not here. The [Working with Agents](/docs/Standards/working-with-agents) options, status circles and asking before every commit, are offered in step 3, and the project takes them or leaves them.
|
|
13
13
|
|
|
14
14
|
## 1. Install the standards
|
|
15
15
|
|
|
@@ -96,7 +96,29 @@ Then wait for the answer.
|
|
|
96
96
|
|
|
97
97
|
**Record the answer** in `docs/development/coding-standards.md`, under "Details". For each skipped or changed standard, write its number, its name, what is different, and the reason the person gave. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
|
|
98
98
|
|
|
99
|
-
The list has nothing about branches
|
|
99
|
+
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).
|
|
100
|
+
|
|
101
|
+
### Working with the agent
|
|
102
|
+
|
|
103
|
+
Once the standards are agreed, **print this to the person exactly as it is written**:
|
|
104
|
+
|
|
105
|
+
```text
|
|
106
|
+
Working with the agent (optional). Want either of these?
|
|
107
|
+
Answer A, B, both or neither.
|
|
108
|
+
|
|
109
|
+
A. Status circles: report each ticket as one line
|
|
110
|
+
✅ done 🟢 Pull Request to review 🟣 working on it
|
|
111
|
+
🟡 ready to commit 🟠 waiting 🔴 blocked or you act
|
|
112
|
+
⚪ not started
|
|
113
|
+
B. Ask before every commit and push, every time
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Then ask for the **project links**, whatever the answer:
|
|
117
|
+
|
|
118
|
+
- **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.
|
|
119
|
+
- **Linear project:** always ask, never guess: the workspace, the project and the ticket prefix, or "None" if the project does not use Linear.
|
|
120
|
+
|
|
121
|
+
**Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: the project links, the status circles if they said A, and the commit rule at the top of the file and under "Who commits" if they said B. Delete the parts they did not take. Write which options they took in `docs/development/coding-standards.md`, under "Details", so a later update knows not to offer them again. See [Working with Agents](/docs/Standards/working-with-agents).
|
|
100
122
|
|
|
101
123
|
## 4. Apply the standards
|
|
102
124
|
|
|
@@ -13,6 +13,8 @@ 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 any [Working with Agents](/docs/Standards/working-with-agents) options the project chose during setup: status circles, and asking before every commit and push.
|
|
17
|
+
|
|
16
18
|
## Template
|
|
17
19
|
|
|
18
20
|
Start from the [AGENTS.md template](/docs/templates#agents) and replace every `[placeholder]`.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
sidebar_position: 7.5
|
|
3
|
+
sidebar_label: "Working with Agents"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Working with Agents
|
|
7
|
+
|
|
8
|
+
> Optional. How an AI agent reports its work and when it asks before acting. These are not code standards: each project chooses them during [Setup](/docs/Guides/setup#working-with-the-agent), and they work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
|
|
9
|
+
|
|
10
|
+
A project takes either option, both or neither. Whatever it 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
|
+
|
|
12
|
+
## Project links
|
|
13
|
+
|
|
14
|
+
Every project records these two links in **Project workflow**, whichever options it takes. An agent uses them to link tickets and Pull Requests, and to know where work belongs.
|
|
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 | **Always ask.** Write the workspace, the project and the ticket prefix, such as `activatus-life`, Launchpad, `ACT`. If the project does not use Linear, write "None" |
|
|
20
|
+
|
|
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
|
+
|
|
23
|
+
## A. Status circles
|
|
24
|
+
|
|
25
|
+
An agent reports the state of every ticket or piece of work as one line: a status circle, the ticket ID as a link, a short title and, where there is one, its Pull Request as a link. The colour alone tells the person whether they need to act.
|
|
26
|
+
|
|
27
|
+
| Circle | Means |
|
|
28
|
+
| ------ | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
29
|
+
| ✅ | Merged, In UAT or Done. Nothing to do |
|
|
30
|
+
| 🟢 | Pull Request ready for the person to review and merge. The link is the Pull Request |
|
|
31
|
+
| 🟣 | Working on it |
|
|
32
|
+
| 🟡 | Ready to commit: done, checked, left uncommitted. Say the branch and where it is. The person commits it, or tells the agent to |
|
|
33
|
+
| 🟠 | Waiting on another ticket or Pull Request first. Say which |
|
|
34
|
+
| 🔴 | Blocked, or the person has to do something. Say what, in a few words |
|
|
35
|
+
| ⚪ | Not started (Backlog or Todo) |
|
|
36
|
+
|
|
37
|
+
```md title="One line per piece of work"
|
|
38
|
+
🟢 [ABC-12](https://linear.app/<workspace>/issue/ABC-12) Short title: [#19](https://github.com/<organisation>/<repo>/pull/19)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- **Every ticket ID is a link to its ticket, and every Pull Request number is a link to the Pull Request.** Build them from the project links above.
|
|
42
|
+
- **No ticket is fine.** Work without one is just the circle and a short title.
|
|
43
|
+
- **Only what the person needs.** Leave out anything they already know.
|
|
44
|
+
|
|
45
|
+
## B. Ask before every commit and push
|
|
46
|
+
|
|
47
|
+
An agent never commits or pushes without asking first, and waits for a clear yes to that specific action.
|
|
48
|
+
|
|
49
|
+
- **A yes covers one action.** Approval to commit and push one task does not carry over to the next, even in the same session. Ask every time.
|
|
50
|
+
- **Small changes too.** Docs-only changes and version bumps need a yes like anything else.
|
|
51
|
+
- **Ask plainly**, such as "Ready to commit and push. Want me to?"
|
|
52
|
+
|
|
53
|
+
This goes at the very top of `AGENTS.md`, as the project's most important rule for agents, and in **Who commits** under Project workflow.
|
package/docs/intro.md
CHANGED
|
@@ -22,6 +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) | Status circles, asking before every commit, and the project's GitHub repo and Linear project |
|
|
25
26
|
| CSS Styling | [Styling guide](/docs/Standards/styling) | Tailwind CSS, flexbox-first layout and global colour variables |
|
|
26
27
|
| Tech Stack | [Tech stack](/docs/Standards/tech-stack) | The frameworks, libraries and versions we build on |
|
|
27
28
|
|
package/docs/version-history.md
CHANGED
|
@@ -20,9 +20,10 @@ sidebar_label: "Version History"
|
|
|
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
21
|
2. **Update the package:** `pnpm update @activatus/code-standards --latest`. 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
|
-
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.
|
|
24
|
-
5. **
|
|
25
|
-
6. **
|
|
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
|
+
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.
|
|
26
|
+
7. **Update the version number** in `AGENTS.md` once every change is done.
|
|
26
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
29
|
|
|
@@ -37,23 +38,34 @@ Anyone changing the standards adds a version, alongside the change:
|
|
|
37
38
|
- **For every change, write:** what changed, why, what to do in a project, and how to check it is done. Write it for an agent that has not read the rest of the standards.
|
|
38
39
|
- **If a project has nothing to do, say so.**
|
|
39
40
|
- **Newest version at the top.**
|
|
40
|
-
- **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: drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
|
|
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
|
+
- **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.
|
|
41
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
|
+
- **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.
|
|
42
45
|
|
|
43
46
|
---
|
|
44
47
|
|
|
45
48
|
## Version 3
|
|
46
49
|
|
|
47
|
-
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.0.
|
|
50
|
+
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.0.7
|
|
48
51
|
|
|
49
|
-
Install it with `pnpm add -D @activatus/code-standards@3.0.
|
|
52
|
+
Install it with `pnpm add -D @activatus/code-standards@3.0.7`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
|
|
50
53
|
|
|
51
|
-
**Fixes in 3.0.
|
|
54
|
+
**Fixes in 3.0.7.** New, optional: [Working with Agents](/docs/Standards/working-with-agents). Setup now offers two ways of working with the agent, A. status circles and B. ask before every commit and push, and asks for the project's GitHub repo and Linear project. If the project already applied 3.0.6:
|
|
55
|
+
|
|
56
|
+
- 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. Always ask for the Linear project; never copy it from another project.
|
|
57
|
+
- Print the [Working with the agent](/docs/Guides/setup#working-with-the-agent) question to the person. Copy the sections they choose from the template into Project workflow, and write their answer in `docs/development/coding-standards.md`, under "Details". If `AGENTS.md` already covers a choice in the project's own words, keep that and only fill in what is missing.
|
|
58
|
+
|
|
59
|
+
**How to check:** Project workflow in `AGENTS.md` names the GitHub repo and the Linear project, and `docs/development/coding-standards.md` records which options the project took.
|
|
60
|
+
|
|
61
|
+
**Fixes in 3.0.6.** 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.
|
|
62
|
+
|
|
63
|
+
**Fixes in 3.0.5.** The ESLint configs now pass their own rules. Copied in as they were, they gave three problems on the config file itself: `No magic number: 3` (`no-magic-numbers`), and in Next.js projects two warnings, `import/no-anonymous-default-export` and `import-x/no-named-as-default-member`. Copy the new [ESLint config](/docs/Standards/eslint) for the project's framework over `eslint.config.mjs`, keeping any project-specific block: one that is recorded in the project's `docs/development/coding-standards.md`, or without which `pnpm lint` fails. A block that is neither, and the lint passes without it, is a leftover: ask before removing it. Then run `pnpm lint`: the config file itself has no problems. If the project already fixed these three by hand, there is nothing to do.
|
|
52
64
|
|
|
53
65
|
- `max-depth` uses a named constant, `MAXIMUM_NESTING_DEPTH`.
|
|
54
66
|
- The array is assigned to `config` before `export default config`.
|
|
55
67
|
- The eslint-comments preset is imported by name: `import { recommended as eslintCommentsRecommended } from "@eslint-community/eslint-plugin-eslint-comments/configs";`.
|
|
56
|
-
- Numbers have a home: [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic). A number used in one file is named at the top of that file, and one shared across the app goes in `lib/constants/`, in a file named after its topic, such as `durations.ts`. There is no `n` object and no `numbers.ts`. If the project has a file of unrelated numbers, split it by topic. Copy the updated **No magic numbers** line from the [`AGENTS.md` template](/docs/templates#agents).
|
|
68
|
+
- Numbers have a home: [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic). A number used in one file is named at the top of that file, and one shared across the app goes in `lib/constants/`, in a file named after its topic, such as `durations.ts`. There is no `n` object and no `numbers.ts`. If the project has a file of unrelated numbers, split it by topic. Copy the updated **No magic numbers** line from the [`AGENTS.md` template](/docs/templates#agents). Run `pnpm lint`: a `no-magic-numbers` finding means the change is not finished.
|
|
57
69
|
- `docsSite/` is ignored. It is the standard docs viewer, with its own packages and build, and without the ignore ESLint lints its built files. If the project already ignores it, nothing changes.
|
|
58
70
|
- The one-parameter selectors moved into their own `SINGLE_OBJECT_PARAMETER` list. **Next.js:** route handlers in `app/**/route.ts` may now take `(request, context)`. If the project switched the rule off for them some other way, such as an override block or `eslint-disable` comments, remove it.
|
|
59
71
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@activatus/code-standards",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.7",
|
|
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,6 +46,38 @@
|
|
|
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`. Or "None"]
|
|
51
|
+
|
|
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
|
+
|
|
54
|
+
### Status circles
|
|
55
|
+
|
|
56
|
+
[Only if the person chose status circles during setup. Otherwise delete this section.]
|
|
57
|
+
|
|
58
|
+
Report every ticket or piece of work as one line: a status circle, the ticket ID as a link, a short title and, where there is one, its Pull Request as a link. The colour alone says whether the person needs to act.
|
|
59
|
+
|
|
60
|
+
| Circle | Means |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| ✅ | Merged, In UAT or Done. Nothing to do |
|
|
63
|
+
| 🟢 | Pull Request ready for the person to review and merge. The link is the Pull Request |
|
|
64
|
+
| 🟣 | Working on it |
|
|
65
|
+
| 🟡 | Ready to commit: done, checked, left uncommitted. Say the branch and where it is. The person commits it, or tells the agent to |
|
|
66
|
+
| 🟠 | Waiting on another ticket or Pull Request first. Say which |
|
|
67
|
+
| 🔴 | Blocked, or the person has to do something. Say what, in a few words |
|
|
68
|
+
| ⚪ | Not started (Backlog or Todo) |
|
|
69
|
+
|
|
70
|
+
Example: `🟢 [ABC-12](https://linear.app/[workspace]/issue/ABC-12) Short title: [#19](https://github.com/[organisation]/[repo]/pull/19)`
|
|
71
|
+
|
|
72
|
+
- Every ticket ID links to its ticket, and every Pull Request number links to the Pull Request.
|
|
73
|
+
- Work with no ticket is just the circle and a short title.
|
|
74
|
+
- Only what the person needs to act on. Leave out what they already know.
|
|
75
|
+
|
|
76
|
+
### Ask before every commit and push
|
|
77
|
+
|
|
78
|
+
[Only if the person chose this during setup. Otherwise delete this section. When it stays, also make it the first line of this file.]
|
|
79
|
+
|
|
80
|
+
Never commit or push without asking first, and wait for a clear yes to that specific action. A yes covers one action: approval for one task does not carry over to the next, even in the same session. Docs-only changes and version bumps need a yes too.
|
|
49
81
|
|
|
50
82
|
## Environment variables
|
|
51
83
|
|