@activatus/code-standards 0.0.0-stage → 2.0.0

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@activatus/code-standards",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.0",
+  "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.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/activatus-life/code-standards.git"
+  },
+  "homepage": "https://activatus-code-standards.vercel.app",
+  "files": [
+    "docs",
+    "static/templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@docusaurus/core": "3.10.2",
+    "@docusaurus/module-type-aliases": "3.10.2",
+    "@docusaurus/preset-classic": "3.10.2",
+    "@docusaurus/theme-mermaid": "3.10.2",
+    "@docusaurus/tsconfig": "3.10.2",
+    "@docusaurus/types": "3.10.2",
+    "@getcanary/docusaurus-theme-search-pagefind": "1.0.2",
+    "@getcanary/web": "^1.0.0",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "pagefind": "^1.3.0",
+    "prism-react-renderer": "^2.3.0",
+    "raw-loader": "^4.0.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "~5.6.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0"
+  },
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "serve": "docusaurus serve",
+    "clear": "docusaurus clear",
+    "typecheck": "tsc"
+  }
 }

package/static/templates/.commitlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@commitlint/config-conventional"]
+}

package/static/templates/.editorconfig

@@ -0,0 +1,28 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = off
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.json]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.go]
+indent_style = tab
+
+[*.py]
+indent_size = 4

package/static/templates/.envrc

@@ -0,0 +1,25 @@
+export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+
+# Source the nvm shell function.
+# Handles: manual install ($HOME/.nvm), Homebrew on macOS, and WSL.
+# On Windows with nvm-windows, nvm is already an executable in PATH — no sourcing needed.
+if [ -s "$NVM_DIR/nvm.sh" ]; then
+  . "$NVM_DIR/nvm.sh"
+elif [ "$(uname -s 2>/dev/null)" = "Darwin" ] && command -v brew &>/dev/null; then
+  _nvm_sh="$(brew --prefix nvm 2>/dev/null)/nvm.sh"
+  [ -s "$_nvm_sh" ] && . "$_nvm_sh"
+  unset _nvm_sh
+fi
+
+if [ -f ".nvmrc" ]; then
+  _node_version="$(tr -d '[:space:]' < .nvmrc)"
+  nvm install "$_node_version"
+  nvm use "$_node_version"
+  unset _node_version
+fi
+
+# Ensure the pnpm shim declared in package.json#packageManager is active via Corepack.
+# `corepack enable` is idempotent — safe to run on every cd.
+if command -v corepack &>/dev/null; then
+  corepack enable pnpm
+fi

package/static/templates/.nvmrc

@@ -0,0 +1 @@
+20

package/static/templates/AGENTS.md

@@ -0,0 +1,160 @@
+# [Project Name]
+
+> **NEVER COMMIT CODE.** Do not run `git commit`, `git push`, `git merge`, `git rebase` or `git stash`, and do not create, switch or delete branches. Make the changes, leave them uncommitted in the working tree, and tell the person what you changed. A person reviews and commits every change.
+
+## Project overview
+
+[One paragraph: what this project does, who uses it, and why it exists.]
+
+## Repository layout
+
+```text
+[Directory tree at depth 2. Regenerate it after structural changes.]
+```
+
+## Tech stack
+
+| Layer | Technology | Version |
+| --- | --- | --- |
+| Framework | [e.g. Next.js (App Router)] | [version] |
+| Language | [e.g. TypeScript] | [version] |
+| Styling | [e.g. Tailwind CSS] | [version] |
+| Database | [database] | [version] |
+| Hosting | [hosting platform] | — |
+
+## Essential commands
+
+| Task | Command |
+| --- | --- |
+| Install | `pnpm install` |
+| Develop | `pnpm dev` |
+| Build | `pnpm build` |
+| Test | `pnpm test` |
+| Lint | `pnpm lint` |
+| Format | `pnpm format` |
+| Type-check | `pnpm typecheck` |
+| Docs site | `pnpm docs:dev` (then open `/docs`) |
+
+## Development workflow
+
+- **Branches**: `<type>/<short-description>` in kebab-case, e.g. `feat/invoice-export`, `fix/login-redirect-loop`. Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`. Never work directly on `main`.
+- **Commits**: Conventional Commits (`feat: add invoice export`). **People commit — AI agents never do.**
+- **Pull requests**: [review and CI requirements]
+- **Merging**: [merge strategy, e.g. squash and merge]
+
+## Environment variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `[VARIABLE_NAME]` | [Yes / No] | [What it is for] |
+
+## Ontology
+
+Activatus uses a fixed vocabulary, the ontology, in two parts:
+
+- **Code words** — component, utils, Decision Doc and the rest — are defined in the code standards: https://activatus-code-standards.vercel.app/ontology
+- **Product words** — what this project builds and how its work is planned — are defined in `docs/product/ontology.md`.
+
+- **Read both before starting work.** If the project's ontology gives a code word a different meaning, the code standards win — point the difference out.
+- **Use their terms** in code, docs, database names and messages — never a synonym. It is `utils`, not `helpers` or `utilities`.
+- **Never use a term either ontology has removed.**
+- If a person uses a word loosely, work out which ontology term they mean and use that term. **If you are not sure what a term means, ask.** Do not guess and do not invent a new term.
+
+## Documentation
+
+The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc**: it states one decision and why it was made.
+
+- **Read them before starting work** — the three docs in `docs/overview/` first, then the docs for the area being changed. Read the files directly; do not start the docs site to read them.
+- **Check each doc's Status.** `Decided` is settled. `Current plan` may change. `Under evaluation` and `Not started` are **not decisions** — do not treat them as one and do not invent one. Ask.
+- **Never invent a product decision to unblock yourself.** If the docs do not answer it, stop and ask.
+- **Update the docs in the same change.** If a change makes a doc wrong, fix the doc and change its Updated date.
+- Do not edit `docsSite/` unless the task is about the docs viewer itself.
+
+## Code standards
+
+This project follows the Activatus Code Standards. They are installed as the `@activatus/code-standards` dev dependency: **read them in `node_modules/@activatus/code-standards/docs/`**, which is the exact version this project uses. The same pages are at https://activatus-code-standards.vercel.app for people.
+
+**Code standards version:** [the major version of the installed `@activatus/code-standards` package when the standards were last applied]
+
+This is the version the code follows. When the package is updated, read only the newer versions in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
+
+**Standards this project skips or changes** are listed, by number, in `docs/development/coding-standards.md`. Follow every other standard.
+
+Follow these rules in every change:
+
+- **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
+- **No file longer than 300 lines** (test files are exempt).
+- **Every name is made of whole, human-readable words.** Variables, parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters, no numbered names, not even for a loop counter or an event handler. Full rule: Human-Readable Names in the code standards (https://activatus-code-standards.vercel.app/Standards/human-readable-names).
+
+  | Never | Always |
+  | --- | --- |
+  | `btn`, `msg`, `val`, `(e) =>`, `(item, i) =>` | `button`, `message`, `value`, `(event) =>`, `(item, index) =>` |
+  | `inputRef` | `inputReference` |
+  | `deps`, `repo`, `env`, `timeoutMs`, `MAX_` | `dependencies`, `repository`, `environment`, `timeoutMilliseconds`, `MAXIMUM_` |
+  | `<T>`, `"sm" \| "lg"` | `<ItemType>`, `"small" \| "large"` |
+  | `name="email1"` | `name="emailAddress"` |
+  | `lib/`, `helpers/`, `utilities/`, `helpers.ts` | `library/`, `utils/`, a file named after what it does |
+
+- **`id` is a word.** Write `id`, `userId`, `user_id` — never `identifier` and never `userID`. `identifier` is only for an outside system's separate field of that name (Linear's readable `ACT-73`).
+- **Dictionary words stay short:** `id`, `docs`, `props`, `utils`, `app`, `url`, `api`, `uat`, `pdf`, `html`, `css`, `json`, `readme`. Case them as words: `imageUrl`, not `imageURL`. Any other short name is written in full. A new dictionary word is added to the Dictionary in the Human-Readable Names standard first (https://activatus-code-standards.vercel.app/Standards/human-readable-names#dictionary), never just used.
+- **Names owned by someone else stay exactly as they are** — Linear's `id` and `pageInfo`, Node's `cwd` option and `process.env`, React's `ref` and `children`, shadcn/ui's `cn` helper, Next.js's `params`, `searchParams` and `LayoutProps`, HTML attributes, Tailwind classes. The rule is for names we write, not names from someone else's code. Renaming them breaks the code. Give the value a full-word name as soon as it comes into our code: `const workingDirectory = process.cwd();`, then pass `{ cwd: workingDirectory }`.
+- **Form fields especially.** A field has one name everywhere it goes: the input's `name` and `id`, the form schema, the API request, the type and the database column (`emailAddress` / `email_address`). Every field has a visible `<label>` in plain English — never a placeholder instead. Option values are words (`"monthly"`), not numbers. Validation messages name the field and say what to do.
+- **The linter only checks some names.** Folders, props, form fields, database columns, routes and environment variables are not linted — check every one of them yourself.
+- **Always `const`.** Never `var`. Use `let` only when a value must be reassigned, with `// eslint-disable-next-line no-restricted-syntax -- <reason>` on the line above.
+- **Arrow functions everywhere.** Never use the `function` keyword: `export const Button = () => {}`, not `export function Button() {}`.
+- **No circular imports, ever.** A file never imports a file that imports it back. Inside a folder, import files directly — never through the folder's own `index.ts` — and never import a parent component from its sub-component.
+- **Define before use.** A function or variable is written above the code that uses it.
+- **A function does one thing.**
+- **Functions, never classes.**
+- **One parameter per function.** Use a single object when more than one value is needed.
+- **Return early.** Never nest more than three levels deep.
+- **No magic numbers or strings.** Use named constants.
+- **No nested ternaries. No boolean flag parameters.**
+- **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
+- **Named exports only**, except where a tool requires a default export.
+- **Type names end in `Props` or `Type`.**
+- **One component per file.** Server and client components live in separate files.
+- **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
+- **Reusable functions live in a `utils/` folder** — global, section or component level — one folder per function, with an `index.ts`.
+- **Components live where they are used:** Design System Components in `components/ui/`; components used on more than one page in `components/shared/`; components used by a few pages in one section in that section's route group (`app/(billing)/components/`); components used by one page in that page's `components/` folder. Start a new component beside its page, and move it up when a second page needs it. No `components/features/` folder.
+- **Code file names are camelCase**; component files are PascalCase. **Anything that becomes a URL is kebab-case**: route folders and documentation folders and files (`docs/architecture/background-jobs.md`). CSS variables are kebab-case too.
+- **Lay out with flexbox first**, and split layouts into child components. Only use CSS grid when specifically asked.
+- **Style with Tailwind.** Colours come from the global colour palette in `app/globals.css` only — never a hard-coded or arbitrary colour. The design decisions are in `docs/design/design-system.md`.
+- **Comments explain why, not what.** Never leave commented-out code.
+- **Error messages say what happened and what to do.**
+
+**Third-party code is exempt.** Code in `node_modules/` and `vendor/` belongs to someone else: do not lint it, do not reformat it, do not edit it to meet these rules.
+
+**shadcn components are not third-party.** Code the shadcn CLI copies into the project is ours. Convert it to these standards in the same change that adds it — its own camelCase folder, one component per file, `types.ts`, `index.ts` and a test — keep only the parts that are used, and never put it in `vendor/`. **Do not change a component's props or behaviour** — only its styling. Components work identically in every Activatus project.
+
+**Look before you build a component.** Check the project's `components/ui/`, then the Design System Components in the code standards, then other Activatus projects, then shadcn. Build to the props listed in the Design System Components; never invent new prop names for a component that is already listed. A component in `components/ui/` takes everything through props and never imports from features, services, stores or `app/`.
+
+**Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code.
+
+**Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit the ESLint config, or move files to hide them. The only exceptions are `let` and a type cast, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
+
+When you report a lint error to the person, explain it in plain English: what is wrong, why it matters, and what you did to fix it.
+
+## Available skills
+
+Skill files live in `.agents/skills/`, mirrored to `.claude/commands/`.
+
+| Skill | Invocation | What it does |
+| --- | --- | --- |
+| Lint | `/lint [path]` | Runs the linters in check-only mode and reports issues |
+| Lint & fix | `/lintFix [path]` | Auto-fixes lint and formatting issues, then reports |
+| Format | `/format [path]` | Formats files with Prettier |
+| Code review | `/codeReview [branch, commit or path]` | Reviews changes for bugs and standards compliance |
+| Update layout | `/updateLayout` | Regenerates the "Repository layout" section of this file |
+| Security audit | `/securityAudit [path]` | Audits the code for common security problems |
+| TypeScript | `/typescript [path]` | Tightens loose types and removes unsafe assertions |
+| Test | `/test [path]` | Runs the tests and reports failures and missing tests |
+
+## Out of scope for AI agents
+
+- **Never commit code.** No `git commit`, `git push`, `git merge`, `git rebase` or `git stash`. Leave every change uncommitted for a person to review.
+- Do not create, switch or delete branches.
+- Do not write secrets, tokens or `.env` values into any file.
+- Do not change dependencies or lockfiles unless the task requires it.
+- Do not edit generated files, or third-party code in `node_modules/` or `vendor/`.
+- [Add any other forbidden actions.]

package/static/templates/decision-doc.md

@@ -0,0 +1,19 @@
+# <Group> — <Menu item>
+
+> One line: what this doc decides.
+
+**Status:** Not started | Under evaluation | Current plan | Decided · **Updated:** YYYY-MM-DD
+
+## Decision
+
+## Why
+
+## Details
+
+## Alternatives considered
+
+## Current implementation
+
+## Related
+
+## Retro Feedback

package/static/templates/docs/ai/agent-harness.md

@@ -0,0 +1,17 @@
+# AI — Agent Harness
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/ai/agents.md

@@ -0,0 +1,17 @@
+# AI — Agents
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/ai/architecture.md

@@ -0,0 +1,17 @@
+# AI — Architecture
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/ai/context.md

@@ -0,0 +1,17 @@
+# AI — Context
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/ai/model-routing.md

@@ -0,0 +1,17 @@
+# AI — Model Routing
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/ai/models.md

@@ -0,0 +1,17 @@
+# AI — Models
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/ai/retrieval.md

@@ -0,0 +1,17 @@
+# AI — Retrieval
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/ai/tools.md

@@ -0,0 +1,17 @@
+# AI — Tools
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/authentication.md

@@ -0,0 +1,17 @@
+# Architecture — Authentication
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/backend.md

@@ -0,0 +1,17 @@
+# Architecture — Backend
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/background-jobs.md

@@ -0,0 +1,17 @@
+# Architecture — Background Jobs
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/backups.md

@@ -0,0 +1,17 @@
+# Architecture — Backups
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/caching.md

@@ -0,0 +1,17 @@
+# Architecture — Caching
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/ci-cd.md

@@ -0,0 +1,17 @@
+# Architecture — CI/CD
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/disaster-recovery.md

@@ -0,0 +1,17 @@
+# Architecture — Disaster Recovery
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/environments.md

@@ -0,0 +1,17 @@
+# Architecture — Environments
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/frontend.md

@@ -0,0 +1,17 @@
+# Architecture — Frontend
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/hosting.md

@@ -0,0 +1,17 @@
+# Architecture — Hosting
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]

package/static/templates/docs/architecture/observability.md

@@ -0,0 +1,17 @@
+# Architecture — Observability
+
+> [One line: what this doc decides.]
+
+**Status:** Not started · **Updated:** [YYYY-MM-DD]
+
+## Decision
+
+[What was decided.]
+
+## Why
+
+[The reasons.]
+
+## Related
+
+- [Link to related docs with a relative path, e.g. `[Future](../scope/future.md)`]