Skip to main content

Standards

Audience: anyone writing docs or code in this repo (developers, AI agents) · Scope: how we write, structure, and maintain documentation — plus the engineering principles behind the code — and which standard to follow · Last reviewed: 2026-07-16

TL;DR — Most of these are documentation standards: we write docs for two audiences — developers & AI (the reference docs in docs/) and operators (the Admin Guide in admin-guide/) — with a base standard every doc follows plus specialised ones for feature/System docs, the operator guide, and e2e tests. Separately, a coding standard (coding.md) covers the code itself — keeping parallel things consistent, preferring a root fix over an extra layer, and writing ES2021 JavaScript. They are living standards — amend them when our practice changes.

The two audiences​

  • Reference docs (docs/) — for developers and AI: architecture, code, data model, deployment. The detail lives here, one topic per file; CLAUDE.md (repo root) is a thin, always-loaded map that points in.
  • The Admin Guide (admin-guide/) — for operators doing day-to-day data entry and settings: plain-language, task-oriented how-tos, deliberately free of code and internals, in its own Docusaurus section so admins never see the developer docs.

Keep them apart: don't leak dev internals into the Admin Guide, and don't bury an operator how-to inside a reference doc.

Which standard do I need?​

You're writing…Follow
any doc (the foundation)writing.md — the doc shape, writing principles, what not to include, the Docusaurus conventions, and a pre-commit checklist. Everything below builds on this.
a feature or System docfeatures.md — the Feature / System / Integration-layer taxonomy, the hub-and-spoke rule, the required section spine, and copy-paste skeletons.
an operator how-toadmin-guide.md — the plain-language, no-internals, task-titled Admin Guide articles.
an e2e test (Playwright)testing.md — spec grouping, Actor > Feature titles, the Setup/Action/Checks documentation, the one-row-per-test catalog, and the two-place assertion rule.
any code (not a doc)coding.md — three repo-wide engineering rules: keep parallel settings/flags/params/columns symmetric, fix the root rather than adding a compensating layer, and write ES2021 JavaScript (const/let, no var, no ES2022+).

For docs, writing.md is the base; features.md, admin-guide.md, and testing.md specialise it. New to the docs? Start with writing.md. Writing or changing code? Read coding.md — it stands on its own (it isn't a doc-writing standard).

Where these standards apply​

  • Every doc under docs/ follows writing.md.
  • A capability that spans several files gets a System folder (hub + spokes) per features.md — e.g. quote-follow-up/, pipedrive/; a small, single-doc feature lives in docs/features/.
  • Operator articles under admin-guide/ follow admin-guide.md.
  • Playwright specs under tests/specs/ follow testing.md (the Testing hub is the matching how-to).
  • All code in the repo follows coding.md — keep parallel things symmetric; fix the root, don't add a layer; JavaScript is ES2021 (const/let, async/await, ?.) with no ES2022+ syntax.