@activatus/code-standards 2.0.0 → 3.0.0

package/README.md

@@ -56,6 +56,7 @@ The live site is at **[activatus-code-standards.vercel.app](https://activatus-co
 | `pnpm build`     | 📦 Builds the static site into `build/`      |
 | `pnpm serve`     | 👀 Serves the built site so you can check it |
 | `pnpm typecheck` | 🔍 Runs TypeScript over the site config      |
+| `pnpm format`    | ✨ Formats everything with Prettier          |
 
 > 🔎 **Search only works on the built site.** Run `pnpm build` then `pnpm serve` if you want to test it. It won't show up in `pnpm start`, so don't go thinking you've broken it.
 
@@ -84,7 +85,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
 ### ✍️ Writing code
 
 - 📄 **No file over 300 lines.** If it's longer, it's doing two jobs. Split it. (Test files get a leave pass.)
-- 🗣️ **Every name is real English words.** Variables, props, form fields, types, files, folders, the lot. `button`, not `btn`. `library/`, not `lib/`. We're not paying by the letter. The one exception: names someone else owns, like Linear's `id` or Node's `cwd` option.
+- 🗣️ **Every name is real English words.** Variables, props, form fields, types, files, folders, the lot. `button`, not `btn`. We're not paying by the letter. The one exception: names someone else owns, like Linear's `id` or Node's `cwd` option.
 - 🔒 **Always `const`.** Need `let`? Fine, but leave a comment saying why, or the linter knocks it back.
 - 🏹 **Arrow functions everywhere.** `const Button = () => {}`. The word `function` is clutter, so we don't use it.
 - 🔄 **No circular imports. Ever.** If two files import each other, pull the shared bit into a third file.
@@ -109,20 +110,18 @@ The full detail's on the site. This is the version you'd tell someone over a sch
 - 🔒 **`/docs` only exists when `DOCS_URL` is set.** It's never set in production, so the docs never leak onto a live site.
 - ✅ **Not finished until the docs are updated.** Change how something works, fix the doc in the same change.
 
-### 🤖 AI agents
+### 🤖 Workflow is the project's call
 
-- 🛑 **Agents never commit code.** No commits, no pushes, no branches. They make the change, leave it sitting there, and a human reviews and commits it. Every time.
+- 🧭 **Branches, commit messages, Pull Requests and whether AI agents may commit are up to each project.** Every team runs its work differently, so it goes in the project's own `AGENTS.md` and docs, not here. These standards are the base for the code itself.
 
-- 📦 **Third-party code is exempt.** Anything in `node_modules/` or `vendor/` isn't ours. Don't lint it, don't tidy it, leave it be.
-
-### 🌿 Branches
+### 📦 Third-party code
 
-- 🏷️ **`type/short-description`**, in kebab-case: `feat/invoice-export`, `fix/login-redirect-loop`. Never work straight on `main`.
+- 📦 **Third-party code is exempt.** Anything in `node_modules/` or `vendor/` isn't ours. Don't lint it, don't tidy it, leave it be.
 
 ### 🗂️ Structure
 
 - 🐫 **Code files are camelCase.** Components are PascalCase (`Button.tsx`) inside a camelCase folder (`button/`).
-- 🔗 **If it becomes a URL, it's kebab-case.** Route folders and doc files (`background-jobs.md`). CSS variables and branch names too.
+- 🔗 **If it becomes a URL, it's kebab-case.** Route folders and doc files (`background-jobs.md`). CSS variables too.
 - 🧰 **Reusable functions live in `utils/`.** Global, section or component level, one folder per function, with an `index.ts` so imports stay tidy.
 - 📍 **Components live where they're used.** Design System Components in `components/ui/`, anything used on more than one page in `components/shared/`, and one-page components in that page's own `components/` folder. No feature folders.
 - 🧱 **Components follow the same order every time.** Imports, component, variables, state, effects, render. No inline functions in the render.
@@ -142,11 +141,11 @@ static/templates/
 ├── docsSite/               # 🌐 Docusaurus viewer that shows docs/ at /docs
 ├── eslint/                 # 🚨 Four flavours: base, typescript, react, nextjs
 ├── stylelint/              # 💅 CSS and SCSS
-├── prettier.config.js      # ✨ Formatting
+├── prettier.config.mjs     # ✨ Formatting
 ├── globals.css             # 🎨 Tailwind + starter colour palette
 ├── .editorconfig           # ⌨️ Editor whitespace rules
 ├── .nvmrc / .envrc         # 🟢 Node version switching
-└── .commitlintrc.json      # 📝 Commit message rules
+└── husky/pre-commit        # 🚦 Lint before every commit
 ```
 
 Copy them. Don't retype them. The ESLint ones have been run against real code, so they actually work, which is more than you can say for most configs floating around the internet.
@@ -165,8 +164,8 @@ Copy them. Don't retype them. The ESLint ones have been run against real code, s
 │   ├── images/             # 🖼️ Logo and favicon
 │   └── templates/          # 📋 The copy-paste files
 ├── src/css/custom.css      # 🎨 Site theme overrides
-├── docusaurus.config.ts    # ⚙️ Site config
-└── sidebars.ts             # 📑 Sidebar (builds itself from docs/)
+├── docusaurus.config.mjs   # ⚙️ Site config
+└── sidebars.mjs            # 📑 Sidebar (builds itself from docs/)
 ```
 
 Built with [Docusaurus](https://docusaurus.io). The sidebar generates itself from the folders, so there's no menu file to forget about.
@@ -177,7 +176,7 @@ Built with [Docusaurus](https://docusaurus.io). The sidebar generates itself fro
 
 Reckon a rule's wrong, or there's one missing? Good. Standards that never change are standards nobody reads.
 
-1. 🌿 **Branch off `main`**, named `type/short-description` (`docs/add-branch-naming`).
+1. 🌿 **Branch off `main`**, named after the ticket (`ACT-14-update-eslint-page`), or `type/short-description` if there's no ticket (`docs/update-eslint-page`).
 2. 📝 **Edit or add a Markdown file in `docs/`.** Name it in kebab-case (`naming-conventions.md`, not `namingConventions.md`), because the file name becomes the page's URL. Yes, we follow our own rules here.
 3. 📋 **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart.
 4. 🔢 **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump the major version in `package.json` to match (version 3 is `3.0.0`), and publish it to npm (npmjs.com) once it's merged. We use pnpm for everything, so that's `pnpm publish`, which lands in the same npm registry as `npm publish`. Projects read only the new versions, so if it's not in there, nobody hears about it.

package/docs/Guides/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "Guides",
-  "position": 5
+	"label": "Guides",
+	"position": 5
 }

package/docs/Guides/migrating.md

@@ -25,7 +25,7 @@ Formatting changes are safe to land in one big PR because they don't change beha
 pnpm add -D prettier prettier-plugin-tailwindcss
 ```
 
-Add `prettier.config.js` — see the [Prettier page](/Standards/prettier) for the full file contents.
+Add `prettier.config.mjs` — see the [Prettier page](/Standards/prettier) for the full file contents.
 
 Format everything at once:
 
@@ -33,7 +33,7 @@ Format everything at once:
 pnpm prettier --write .
 ```
 
-Commit with message `chore: apply prettier formatting`. This keeps the formatting diff isolated, making future `git blame` useful.
+Commit it on its own, following the project's commit message format. This keeps the formatting diff isolated, making future `git blame` useful.
 
 Add a `.prettierignore` if you have generated files you don't want touched:
 
@@ -82,7 +82,7 @@ Before renaming anything, sort the short names into three piles:
 | ---------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
 | **A dictionary word** — `id`, `docs`, `app`, `url`, `api`                                                              | Leave it                  | [Dictionary](/Standards/human-readable-names#dictionary)                  |
 | **A third-party name** — React's `ref`, Next.js's `params`, shadcn/ui's `cn`, Linear's `pageInfo`, Node's `cwd` option | Leave it exactly as it is | [Third-party names](/Standards/human-readable-names#third-party-names)    |
-| **Our own shorthand** — `btn`, `props`, `lib/`, `utils/`, `inputRef`                                                   | Rename it                 | The [Never / Always](/Standards/human-readable-names#never--always) table |
+| **Our own shorthand** — `btn`, `lib/`, `helpers/`, `utilities/`                                                        | Rename it                 | The [Never / Always](/Standards/human-readable-names#never--always) table |
 
 **Not sure which pile?** Don't guess and don't rename it. Ask, and if it is a dictionary word, [add it to the dictionary](/Standards/human-readable-names#adding-a-word-to-the-dictionary) first. Everyone then makes the same call.
 
@@ -90,16 +90,14 @@ Before renaming anything, sort the short names into three piles:
 
 These come up in nearly every project:
 
-| Before                                 | After                                                 |
-| -------------------------------------- | ----------------------------------------------------- |
-| `lib/`                                 | `library/`                                            |
-| `utilities/`, `helpers/`, `helpers.ts` | `utils/`, or a file named after what it does          |
-| `ButtonProperties`, `properties`       | `ButtonProps`, `props`                                |
-| `inputRef`                             | `inputReference` (React's own `ref` prop stays `ref`) |
-| `MAX_`, `MIN_`                         | `MAXIMUM_`, `MINIMUM_`                                |
-| `"sm" \| "md" \| "lg"`                 | `"small" \| "medium" \| "large"`                      |
-| `auth`, `useAuth`                      | `authentication`, `useAuthentication`                 |
-| `(e) =>`, `(i) =>`                     | `(event) =>`, `(index) =>`                            |
+| Before                                 | After                                        |
+| -------------------------------------- | -------------------------------------------- |
+| `utilities/`, `helpers/`, `helpers.ts` | `utils/`, or a file named after what it does |
+| `ButtonProperties`, `properties`       | `ButtonProps`, `props`                       |
+| `MAX_`, `MIN_`                         | `MAXIMUM_`, `MINIMUM_`                       |
+| `"sm" \| "md" \| "lg"`                 | `"small" \| "medium" \| "large"`             |
+| `auth`, `useAuth`                      | `authentication`, `useAuthentication`        |
+| `(e) =>`, `(i) =>`                     | `(event) =>`, `(index) =>`                   |
 
 `docs/`, `docsSite/`, `DOCS_URL` and `pnpm docs:dev` already follow the standard. Leave them.
 
@@ -107,7 +105,7 @@ These come up in nearly every project:
 
 1. **Folders**, with `git mv` so the history follows the files. Fix the imports in the same pull request.
 2. **Types**, so the `@typescript-eslint/naming-convention` errors clear.
-3. **Variables, functions and properties.** Use your editor's **Rename Symbol** (F2), not find-and-replace: it renames every use and nothing else.
+3. **Variables, functions and properties.** Use your editor's **Rename Symbol** (F2), not find-and-replace: it renames every use and nothing else. An agent working from the command line has no editor, so it uses the [rename script](#renaming-from-the-command-line) instead.
 4. **Everything the linter can't see** — form fields, union values, routes, scripts, environment variables. Search for each one by hand.
 
 ### 4. Names that leave the codebase
@@ -121,6 +119,25 @@ Some names are used outside the code. Renaming them needs more than a code chang
 
 Write each of these up in the pull request so nobody gets caught out.
 
+### Renaming from the command line
+
+An AI agent working in a terminal has no editor, so it cannot press F2. The package ships a script that does the same job, using the project's own TypeScript and the same rename engine as the editor:
+
+```bash
+node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <currentName> <newName>
+```
+
+```bash
+# Rename a type everywhere it is used
+node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs components/ui/button/types.ts ButtonProperties ButtonProps
+```
+
+- **Give it the file where the name is declared.** It renames that symbol and every use of it, across the whole project, and leaves anything else with the same name alone.
+- **Shorthand stays correct.** `{ properties }` becomes `{ properties: props }`, so objects keep their shape.
+- **It only renames TypeScript and JavaScript names.** Folders, files, form fields, routes and environment variables still need renaming by hand.
+- **It cannot reach keys in plain object literals that aren't typed**, such as the expected value in a test's `toEqual({ properties: … })`. Search the tests for the old name and fix those keys by hand.
+- **Run the type check and tests after each batch** of renames.
+
 ## Stage 5 — AGENTS.md
 
 Copy the [AGENTS.md template](/templates#agents) to the project root and replace every `[placeholder]`. Agree the standards with the person first ([Setup, step 3](/Guides/setup#3-agree-the-standards)), and set the code standards version from the [Version History](/version-history).
@@ -133,9 +150,9 @@ Copy the eight [standard skill files](/templates#skills) into `.agents/skills/`,
 
 Move the project's existing documentation into the standard [`docs/` folders](/Standards/documentation#-the-folders), rewriting each as a [Decision Doc](/Standards/documentation#-the-doc-format), then add the [`docsSite/` viewer](/Standards/documentation#-setting-it-up) so it shows at `/docs`.
 
-## Stage 8 — Commit message checks
+## Stage 8 — Lint before every commit
 
-Add Commitlint and the two Husky hooks: one checks the commit message, the other runs `pnpm lint` before every commit. Add the lint hook **last**, once the project passes `pnpm lint`. See [Enforcing commit messages](/Standards/conventional-commits#enforcing-commit-messages).
+Add the Husky hook that runs `pnpm lint` before every commit. Add it **last**, once the project passes `pnpm lint`. See [Lint before every commit](/Standards/lint-errors#lint-before-every-commit).
 
 ## Tips
 

package/docs/Guides/setup.md

@@ -9,12 +9,21 @@ sidebar_label: "Setup"
 
 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.
 
+**These standards are the base, for code only.** A project builds on top of them: it can add its own folders and conventions, and it makes its own project-management decisions (tickets, statuses, releases, who commits). Those go in the project's own docs, not here.
+
 ## 1. Install the standards
 
 ```bash
 pnpm add -D @activatus/code-standards
 ```
 
+**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`:
+
+```yaml title="pnpm-workspace.yaml"
+minimumReleaseAgeExclude:
+  - "@activatus/code-standards"
+```
+
 The standards are now in `node_modules/@activatus/code-standards/`:
 
 | Folder                    | What it holds                                                                              |
@@ -54,56 +63,56 @@ Tell me the numbers to skip or change, or say "all good".
  9. EditorConfig
 10. Node version set by .nvmrc and direnv
 11. Styling: Tailwind, flexbox first, colours only from the global palette
-12. Folder structure: folders at the project root, functions in utils/
+12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
 13. Components live where they are used: components/ui/, components/shared/, or beside their page
 14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
 15. Design System Components: every project builds the standard components with the same props
 16. Imports: no circular imports, import from folders not files
 17. API routes: one folder per route, kebab-case
 18. Docs: every file in docs/ is a Decision Doc, shown at /docs by the docs site
-19. Conventional Commits, checked by Husky, with pnpm lint before every commit
-20. Branch names: type/short-description
-21. AGENTS.md and the eight agent skills
-22. AI agents never commit, push or make branches (strict no commit)
-23. The Ontology: the shared words for code
+19. Lint before every commit: a Husky hook runs pnpm lint
+20. AGENTS.md and the eight agent skills
+21. The Ontology: the shared words for code
 ```
 
 Then wait for the answer.
 
-| The person says                                           | Do                            |
-| --------------------------------------------------------- | ----------------------------- |
-| "All good"                                                | Apply every standard          |
-| "Skip 7"                                                  | Apply every standard except 7 |
-| "Change 22: agents can commit when I say I'm on my phone" | Apply 22 as they describe it  |
-| Something unclear                                         | Ask. Do not guess             |
+| The person says                         | Do                            |
+| --------------------------------------- | ----------------------------- |
+| "All good"                              | Apply every standard          |
+| "Skip 7"                                | Apply every standard except 7 |
+| "Change 7: we use Biome for formatting" | Apply 7 as they describe it   |
+| Something unclear                       | Ask. Do not guess             |
 
 **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.
 
-If standard 22 is changed, also replace the "NEVER COMMIT CODE" lines in `AGENTS.md` with the person's rule. See [A project can choose otherwise](/Standards/agent-specs#a-project-can-choose-otherwise).
+The list has nothing about branches, commit messages or whether agents may commit. 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](/Standards/agent-specs#project-workflow).
 
 ## 4. Apply the standards
 
 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.
 
+**Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. `.mjs` works in both, so every project looks the same. If the project has a config as `.js`, `.ts` or `.mts`, such as `next.config.ts` from `create-next-app` or `vitest.config.mts`, rename it to `.mjs`, removing any TypeScript-only syntax: a type annotation becomes a JSDoc comment, for example `/** @type {import("next").NextConfig} */`. A tool that cannot read `.mjs` keeps its own format.
+
 **An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/Guides/migrating), one stage per pull request, after the config files below are in place.
 
 | Standard                 | What to set up                                                                                                                                                                                                                                                                                                       |
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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](/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`                                                 |
-| 7. Prettier              | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.js`. Add the scripts `"format": "prettier --write ."` and `"format:check": "prettier --check ."`                                                                                                                          |
+| 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 ."`                                                                                                                         |
 | 8. Stylelint             | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/Standards/stylelint)                                                                                                                                                           |
 | 9. EditorConfig          | Copy `static/templates/.editorconfig`                                                                                                                                                                                                                                                                                |
 | 10. Node version         | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/Standards/direnv)                                                                                                                                                                                                                  |
 | 11. Styling              | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette                                                                                                                                                                                  |
 | 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](/Standards/documentation#-setting-it-up)                                                                                                |
-| 19. Commits              | Copy `static/templates/.commitlintrc.json` and the two hooks in `static/templates/husky/`. Add the lint hook last, once `pnpm lint` passes. See [Enforcing commit messages](/Standards/conventional-commits#enforcing-commit-messages)                                                                               |
-| 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/` |
+| 19. Lint before commit   | Copy `static/templates/husky/pre-commit` to `.husky/pre-commit`, once `pnpm lint` passes. See [Lint before every commit](/Standards/lint-errors#lint-before-every-commit)                                                                                                                                            |
+| 20. 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/` |
 
 The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
 
 **Finish by:**
 
-1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's major version.
+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.
 2. Running `pnpm lint`, `pnpm format:check` and the tests.
 3. Telling the person what you set up, which standards they skipped, and anything only they can do, such as filling in a secret in `.env.local`.
 
@@ -125,6 +134,25 @@ The project already follows the standards, and a newer version is out.
 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.
 4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
 5. **Do every other change** as its "What to do" says, and run its "How to check" search. One pull request per kind of change.
-6. **Set `**Code standards version:**`** in `AGENTS.md` to the new version, and tell the person what changed.
+6. **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).
 
 See the [Version History](/version-history) for the full update rules.
+
+---
+
+## Finishing a change later
+
+Sometimes a change is too big for the update, such as switching on the standard ESLint config in a project that never had it. It can be done later in its own Pull Request, but **the version number must stay honest**.
+
+1. Set the project's version to the new version anyway.
+2. In `docs/development/coding-standards.md`, under **Unfinished changes**, list each change that is not done yet: its version and number, what is left, and where it is being done (a ticket or a Pull Request).
+
+   ```md
+   ## Unfinished changes
+
+   - Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120.
+   ```
+
+3. When it is finished, remove it from the list.
+
+An agent updating to a later version reads this list first, and finishes or skips those changes before starting the new ones.

package/docs/Standards/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "Standards",
-  "position": 6
+	"label": "Standards",
+	"position": 6
 }

package/docs/Standards/agent-skills.md

@@ -12,10 +12,10 @@ Skills are shared, versioned, and executed with real tool access. A vague one wa
 
 One canonical copy, one mirror:
 
-| Path | Role |
-| --- | --- |
-| `.agents/skills/*.md` | **Canonical.** Portable location any compatible agent reads. The only copy you edit. |
-| `.claude/commands/*.md` | Claude Code mirror, exposed as `/name`. |
+| Path                    | Role                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| `.agents/skills/*.md`   | **Canonical.** Portable location any compatible agent reads. The only copy you edit. |
+| `.claude/commands/*.md` | Claude Code mirror, exposed as `/name`.                                              |
 
 Keep the mirror identical to the canonical copy — edit the skill in `.agents/skills/`, then copy it across.
 
@@ -40,14 +40,14 @@ allowed-tools: Read, Glob, Grep, Bash(pnpm lint:*), Bash(eslint:*)
 Run all configured linters and report issues without modifying any files.
 ```
 
-| Field | Required | Purpose |
-| --- | --- | --- |
-| `name` | Yes | The invocation name, in camelCase. Must match the filename. |
-| `description` | Yes | One line, **under 60 characters**. How an agent decides to use it. |
-| `argument-hint` | If it takes arguments | Shown during autocomplete. |
-| `allowed-tools` | Strongly encouraged | The tools the skill may use. See below. |
-| `model` | No | Pin only for genuinely mechanical skills. |
-| `disable-model-invocation` | No | Set when a skill must only ever be run by a human. |
+| Field                      | Required              | Purpose                                                            |
+| -------------------------- | --------------------- | ------------------------------------------------------------------ |
+| `name`                     | Yes                   | The invocation name, in camelCase. Must match the filename.        |
+| `description`              | Yes                   | One line, **under 60 characters**. How an agent decides to use it. |
+| `argument-hint`            | If it takes arguments | Shown during autocomplete.                                         |
+| `allowed-tools`            | Strongly encouraged   | The tools the skill may use. See below.                            |
+| `model`                    | No                    | Pin only for genuinely mechanical skills.                          |
+| `disable-model-invocation` | No                    | Set when a skill must only ever be run by a human.                 |
 
 Quote any `argument-hint` that starts with `[`, or YAML parses it as a list:
 
@@ -60,20 +60,20 @@ argument-hint: [path] # a one-element array — wrong
 
 Prose like "this skill is read-only" is a request. `allowed-tools` is the enforcement. Whatever a skill's body promises not to do, the allowlist should make impossible:
 
-| The skill says | So the allowlist omits |
-| --- | --- |
-| "Do NOT make file changes" | `Edit`, `Write` |
-| "Do NOT auto-fix" | `Edit`, `Write` |
-| "Do NOT stage or commit" | every `Bash(git …)` |
-| "Do NOT push" | `Bash(git push:*)` |
+| The skill says             | So the allowlist omits |
+| -------------------------- | ---------------------- |
+| "Do NOT make file changes" | `Edit`, `Write`        |
+| "Do NOT auto-fix"          | `Edit`, `Write`        |
+| "Do NOT stage or commit"   | every `Bash(git …)`    |
+| "Do NOT push"              | `Bash(git push:*)`     |
 
 Three rules follow from this:
 
 1. **Every command the body tells the agent to run must be allowlisted.** A body that says `eslint $ARGUMENTS` under an allowlist of only `Bash(pnpm exec eslint:*)` blocks itself halfway through. List each form the body actually uses.
 2. **Grant the narrowest set that still works.** `Bash(pnpm lint:*), Bash(eslint:*)` over a bare `Bash`.
-3. **Never grant `git commit` or `git push`.** [Agents never commit code](/Standards/agent-specs#agents-never-commit-code), so no skill is allowed to.
+3. **Never grant `git commit` or `git push`.** A skill does one job and leaves its changes for whoever ran it. Committing is the [project's workflow](/Standards/agent-specs#project-workflow), not a skill's.
 
-Be honest about the limit: patterns gate the command, not its flags. `Bash(eslint:*)` still permits `eslint --fix`. The allowlist reliably prevents a skill from reaching for a whole *category* of tool; keep the prose instruction as well for anything finer.
+Be honest about the limit: patterns gate the command, not its flags. `Bash(eslint:*)` still permits `eslint --fix`. The allowlist reliably prevents a skill from reaching for a whole _category_ of tool; keep the prose instruction as well for anything finer.
 
 ## Write for the agent, not the user
 
@@ -114,12 +114,12 @@ Respect the project's own scripts. `pnpm lint` picks up workspace configuration
 
 Before merging a skill:
 
-- [ ]  `name` matches the filename
-- [ ]  `description` is one line, under 60 characters
-- [ ]  `argument-hint` present if it takes arguments, and quoted if it starts with `[`
-- [ ]  `allowed-tools` omits everything the body promises not to do
-- [ ]  `allowed-tools` includes every command the body does invoke
-- [ ]  Body is written as instructions to the agent
-- [ ]  Sub-steps indented three spaces
-- [ ]  Prettier leaves the file unchanged
-- [ ]  `.claude/commands/` mirror matches `.agents/skills/`
+- [ ] `name` matches the filename
+- [ ] `description` is one line, under 60 characters
+- [ ] `argument-hint` present if it takes arguments, and quoted if it starts with `[`
+- [ ] `allowed-tools` omits everything the body promises not to do
+- [ ] `allowed-tools` includes every command the body does invoke
+- [ ] Body is written as instructions to the agent
+- [ ] Sub-steps indented three spaces
+- [ ] Prettier leaves the file unchanged
+- [ ] `.claude/commands/` mirror matches `.agents/skills/`

package/docs/Standards/agent-specs.md

@@ -7,26 +7,11 @@ sidebar_label: "AGENTS.md"
 
 Every Activatus repository must have an `AGENTS.md` in its root. This file gives AI coding agents (Claude Code, Copilot, Cursor, etc.) the context they need to work effectively without repeated explanation.
 
-## Agents never commit code
+## Project workflow
 
-**An AI agent never commits.** It does not run `git commit`, `git push`, `git merge`, `git rebase` or `git stash`, and it does not create, switch or delete branches.
+**How a project runs its work is not part of these standards.** Branch names, commit messages, Pull Requests, merging, releases, and whether AI agents may commit, push or make branches are all the project's own decisions. Every project makes them differently.
 
-The agent makes the changes, leaves them uncommitted in the working tree, and says what it changed. A person reviews the changes and commits them.
-
-Every `AGENTS.md` states this at the very top and again under "Out of scope for AI agents". The [template](/templates#agents) already does.
-
-### A project can choose otherwise
-
-**Strict no commit is the default.** It is standard 22 in the list the person agrees to during [Setup](/Guides/setup#3-agree-the-standards), so they can change it then. Or they can be asked directly:
-
-> Should AI agents be allowed to commit in this project, or is it strict no commit?
-
-| Answer                             | What goes in `AGENTS.md`                                                                                                                                                                                             |
-| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Strict no commit** (the default) | The template as it is                                                                                                                                                                                                |
-| **Agents may commit**              | Replace the "NEVER COMMIT CODE" lines with the project's own rule, saying exactly which agents may commit, push and open Pull Requests, and when. A tool built to ship code with AI, such as Launchpad, chooses this |
-
-A person can also allow it for one piece of work, such as when they are away from their computer. That permission lasts for that piece of work only, and never changes the project's rule.
+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.
 
 ## Template
 
@@ -36,19 +21,19 @@ Start from the [AGENTS.md template](/templates#agents) and replace every `[place
 
 Every `AGENTS.md` must include these sections. Monorepos (`pnpm-workspace.yaml`, Turborepo, Nx, etc.) also require a **Workspace packages** table listing each package, its path and a one-line description.
 
-| Section                    | Purpose                                                                                   |
-| -------------------------- | ----------------------------------------------------------------------------------------- |
-| Project overview           | One paragraph: what it does, who uses it, why it exists                                   |
-| Repository layout          | Directory tree at depth 2                                                                 |
-| Tech stack                 | Language, runtime, framework, database, infra (with versions)                             |
-| Essential commands         | Install, dev, build, test, lint, type-check                                               |
-| Development workflow       | [Branch naming](/Standards/branch-naming), commit format, PR requirements, merge strategy |
-| Environment variables      | All required and optional env vars with descriptions                                      |
-| Ontology                   | Link to the [ontology](/ontology), and the instruction to read it and use its terms       |
-| Documentation              | Where the project's docs are, and the instruction to read them before starting work       |
-| Code standards             | Link to these standards and the rules agents must follow in every change                  |
-| Available skills           | Table of the agent skills the project provides                                            |
-| Out of scope for AI agents | Explicit list of forbidden agent actions — always including "never commit code"           |
+| Section                    | Purpose                                                                                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Project overview           | One paragraph: what it does, who uses it, why it exists                                                                                      |
+| Repository layout          | Directory tree at depth 2                                                                                                                    |
+| Tech stack                 | Language, runtime, framework, database, infra (with versions)                                                                                |
+| Essential commands         | Install, dev, build, test, lint, type-check                                                                                                  |
+| Project workflow           | The project's own rules for branches, commits, Pull Requests and merging, and whether agents may commit. Points to where they are written up |
+| Environment variables      | All required and optional env vars with descriptions                                                                                         |
+| Ontology                   | Link to the [ontology](/ontology), and the instruction to read it and use its terms                                                          |
+| Documentation              | Where the project's docs are, and the instruction to read them before starting work                                                          |
+| Code standards             | Link to these standards and the rules agents must follow in every change                                                                     |
+| Available skills           | Table of the agent skills the project provides                                                                                               |
+| Out of scope for AI agents | Explicit list of what agents must not do in this project                                                                                     |
 
 ## Standard skills
 
@@ -67,7 +52,7 @@ Every project provides these eight skills. **The files are ready to copy from th
 
 Skill files are named in camelCase (`lintFix.md`), so the invocation is camelCase too (`/lintFix`). They are not documentation pages and have no URL, so the kebab-case rule for docs does not apply.
 
-No skill commits code — see [Agents never commit code](#agents-never-commit-code).
+No skill commits, pushes or makes branches. A skill does one job and leaves its changes for the agent or person who ran it. Whether those changes are then committed is the [project's workflow](#project-workflow).
 
 ### Skill locations
 

package/docs/Standards/direnv.mdx

@@ -10,9 +10,9 @@ Automatically switch to the project's Node.js version when you `cd` into the rep
 
 Two files work together:
 
-| File | Purpose |
-| --- | --- |
-| `.nvmrc` | Declares the required Node.js major version (e.g. `20`) |
+| File     | Purpose                                                                  |
+| -------- | ------------------------------------------------------------------------ |
+| `.nvmrc` | Declares the required Node.js major version (e.g. `20`)                  |
 | `.envrc` | Loaded by direnv on `cd`; sources nvm and activates the declared version |
 
 When you enter the project directory direnv runs `.envrc`, which installs the declared Node version (if missing) and activates it for your shell session. Leaving the directory restores the previous environment automatically.
@@ -207,11 +207,11 @@ fi
 
 The script handles four environments:
 
-| Environment | How nvm is loaded |
-| --- | --- |
-| macOS — manual install | `$HOME/.nvm/nvm.sh` sourced directly |
-| macOS — Homebrew | `$(brew --prefix nvm)/nvm.sh` sourced as fallback |
-| Linux / WSL 2 | `$HOME/.nvm/nvm.sh` sourced directly |
+| Environment                      | How nvm is loaded                                               |
+| -------------------------------- | --------------------------------------------------------------- |
+| macOS — manual install           | `$HOME/.nvm/nvm.sh` sourced directly                            |
+| macOS — Homebrew                 | `$(brew --prefix nvm)/nvm.sh` sourced as fallback               |
+| Linux / WSL 2                    | `$HOME/.nvm/nvm.sh` sourced directly                            |
 | Windows — Git Bash + nvm-windows | `nvm` is already in `PATH` as an executable; no sourcing needed |
 
 The version is read explicitly from `.nvmrc` (stripping whitespace) and passed to both `nvm install` and `nvm use`, making the script compatible with both nvm and nvm-windows.

package/docs/Standards/documentation.md

@@ -247,7 +247,10 @@ const nextConfig = {
 
     return [
       { source: "/docs", destination: `${DOCS_URL}/docs/` },
-      { source: "/docs/:path*", destination: `${DOCS_URL}/docs/:path*` },
+      {
+        source: "/docs/:path*",
+        destination: `${DOCS_URL}/docs/:path*`,
+      },
     ];
   },
 };
@@ -261,7 +264,7 @@ export default nextConfig;
 
 1. **Copy the docs.** Copy the [`docs/` templates](/templates#document-templates) into the project's `docs/` folder. Rename `overview/what-is-it.md` after the project (`what-is-launchpad.md`) and update its title.
 
-2. **Copy the viewer.** Copy the [`docsSite/` template](/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.ts`, and point the home redirect in `src/pages/index.tsx` at the renamed overview file.
+2. **Copy the viewer.** Copy the [`docsSite/` template](/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.
 
 3. **Add the route.** Add the rewrite above to `next.config.mjs`.