For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/CONTRIBUTING.md.

Contributing

Use British English. Read AGENTS.md, ARCHITECTURE.md, DDD.md, CLIENT-SUBSCRIPTIONS.md and TESTING.md before architectural changes.

Identify the owner, aggregate and command/query before editing. Keep business policy inside its context, inward dependencies explicit, and each service's source independent. Use native types and typed outcomes; generated contracts remain outside domain/application packages.

Create reviewable branches from the selected baseline. Use Conventional Commits, for example feat(metallo): add a context command. Record notable changes in a PR changelog fragment. Release-preparation PRs assemble CHANGELOG.md. Follow the documentation scope when updating guides or recording architectural decisions. Number a new decision after the highest number on main and in open pull requests. Paginate the complete changed-file lists of open pull requests; large infrastructure changes can place decisions beyond the first page. pnpm check:architecture rejects two decisions with the same number; whichever change reaches main second takes the next free number. The exact historical 0000 and 0007 pairs listed in the ADR catalogue retain their original identifiers and are the only exceptions.

Before hand-off, select checks using Choosing checks. Documentation- and instruction-only edits use the focused documentation lane. Other changes require pnpm verify and the applicable real infrastructure lane. Use the configured dev box for infrastructure-dependent checks; follow the dev-box testing workflow. Report omitted PostgreSQL, browser, UAT, Minikube/k3s and deployment checks. Review generated diffs after pnpm generate:contracts and keep dependency locks committed. Generated credentials, tool caches and build outputs stay ignored.

Checked-in generated web clients and schemas live beneath generated/ directories in their owning package. Update generators and imports when moving their outputs. Next.js requires each project's next-env.d.ts bootstrap at the project root; its transient route types and build output remain in ignored .next/ directories.

Large-file reviews

Review responsibilities before handwritten source or configuration exceeds 450 lines. This includes YAML, source schemas and deployment templates. Split only at a clear capability/workflow boundary. Record each justified exception once in docs/large-file-review.json, using its repository-relative path and a reason for keeping its responsibilities together.

Markdown (.md and .markdown), dependency lockfiles and the frozen legacy/ archive are exempt from the size rule. Generated and vendored files are exempt when Git attributes set linguist-generated or linguist-vendored to true or the bare attribute. Register output paths or patterns in .gitattributes; keep their source contracts, templates and generators subject to review. Recognised lockfile names are listed in scripts/large_file_review.py.

pnpm check:large-file-review rejects missing reviews, duplicate entries and obsolete entries. Remove an entry when its file disappears, becomes exempt or shrinks to 450 lines or fewer. Size exemptions leave architecture, security, generated-file drift and archive integrity checks in place. The JSON register uses ordinary merge conflict resolution so each path retains one reviewed reason.

Documentation site

Run pnpm docs:check for the root documentation site and pnpm docs:preview to inspect it locally. Edit authoritative source documents; the site assembles them into ignored build output. See the maintenance guide. Preserve the exact relocation commit when merging documentation history.

Documentation scope

Update the smallest set of documents whose purpose is affected by the change. Keep each fact in one authoritative place and use links when another document needs that information.

DocumentResponsibility
Root and scoped AGENTS.md filesDurable working rules for coding agents, limited to their directory scope.
Root CLAUDE.mdA one-line @AGENTS.md import of the shared root instructions.
ARCHITECTURE.mdService boundaries, shared architectural patterns and the context ownership map, with links to context documentation.
DDD.mdShared modelling principles and conventions.
TESTING.md and CLIENT-SUBSCRIPTIONS.mdShared testing and browser-delivery policies and workflows.
Context READMEsCommands, queries, behaviour, adaptor choices, mock limitations, implementation status and feature-specific verification.
Contract documentationPublished payloads, wire formats and compatibility requirements.
docs/decisions/Architectural decisions, their rationale and consequences.
changelog.d/Pending release notes, with one fragment per notable PR.
CHANGELOG.mdAssembled release notes and earlier change history.

Record service-to-context ownership in ARCHITECTURE.md; link to the owning context for its operations and implementation details. Keep top-level guides focused on their shared responsibilities as contexts grow.

Service teams own their scoped agent guidance. Keep shared rules in the root instructions and link to authoritative service documentation for local details. Keep temporary rollout status and issue-specific gates in the owning operational guide or issue, with an explicit removal condition. Preserve frozen instruction files under legacy/.

Create or amend an architectural decision when a boundary, policy or shared pattern changes intentionally. Adding a use case within an existing decision belongs in its context and contract documentation. Update an operational guide when its actual workflow changes.

Page source

Source snapshot ยท Revision f928834c8.