# Rules

- **Public by design.** Never commit e-mails, personal or company names, internal domains, tenant ids, account ids or tokens: the whole history becomes public. Examples use `example.com`, `maria@example.com`, `123456789012`.
- **No personal data in a command or a log** (owner's pillar, 2026-11-16, [vision](../vision.md)), a direction until Nereus has an audit trail: prefer the design below in new work, but do not stop a change or rewrite an existing command for it (owner, 2026-11-16). The direction: no command option, argument or path takes an e-mail, a phone number, a document or a person's name; a person is a `User` or a team, named by its name or id. A log line, an event, an error message or an audit record carries ids, never personal data. Personal data a feature needs goes in a request body, from a form, kept in one place the person can delete.
- **A check's exceptions live in a ratchet** (owner, 2026-11-16, [vision](../vision.md)): when a new check finds what exists today, its exceptions go to an allowlist that only shrinks (the check fails on a new line or a higher count, compared with `origin/main`), and the change that fixes one lowers it in the same PR. Never add an exception to get a change through; fix it or ask the owner. The personal-data check (#1680) is the exception: its ratchet only warns until there is an audit trail (owner, 2026-11-16). Credit: [Ratchets in software development](https://qntm.org/ratchet) (qntm, 2021).
- **A public doc never names where a secret file is saved** (owner, 2026-11-07, #1143): a script that writes one (a password, a token) takes the path as an option, with an env var, keeps a default in its code and prints where it wrote it (#1145). The doc names the option, never the default path.
- **Sensitive data goes to the private repository** (`getnereus/internal`): figures, contracts, investors, legal strategy, anything personal. Here, only the method (what is measured, how, where), never the values.
- **The names:** the project is **Nereus** (repository `getnereus/nereus`), the CLI binary is `nereus` (formerly `platform`), and the MCP tools agents use to reach the platform (#137, #214) are served by the Nereus API at `/mcp`, its tokens for the audience `nereus-mcp` (formerly `platform-mcp`; ADR 0029). Each kept in one place (`cli/src/nereus/names.py`, one build setting) so renaming is cheap. Do not spend time on naming. Two things are never both called "catalog" (owner's backlog review, 2026-10-31, #699): the **catalog** is the catalog reef, Nereus's own Workloads and Packages (`nereus catalog`, ADR 0016); the public site listing Nereids and their install commands is the **Nereid registry** (#22), and a Nereid listed there reads `status.source: registry` (spec 0003).
- **The model's words, exactly** ([The CLI design](cli.md), ADR 0002, ADR 0011): reef (the capability, an API group `<reef>.getnereus.dev/v1alpha1`; formerly Interface), Nereid (a controller installed, top-level, global name, may serve many reefs; formerly Implementation), Mandate (binds one reef to one Nereid; formerly Class), Instance, Tool, Vendor as an attribute. **Controller** is the mechanism (`<reef>-<tool>-controller`); people type the Nereid's name. Never "driver", "plugin" or "provider".
- **Reference and fake are different words** (owner, 2026-11-13, #486, #1422): a **reference Nereid** (`reference-release`, `reference-secrets`, `controllers/reference/`) stands in for a reef with no tool and is the everyday check of the CLI, the API and their contracts; a **fake** stands in only for an external tool's API (`test/fake-github`, `controllers/openbao/contract/fakebao.py`), in a test of a real Nereid that runs on demand (`make contract`), never in `make test` or `make checks`. Never call a Nereid a fake.
- **One writer per field** (ADR 0005): the API (or the CLI before it) writes `spec`; the Nereid (its controller) writes `status`.
- **A kind keeps a field while stored objects use it** (owner, 2026-11-05, #1045): a chart upgrade replaces a kind's schema (Flux's `crds: CreateReplace`), and a field the new version drops no longer shows on a stored object, with no error. Add the new field, move the objects to it, then drop the old one. #1058 checks it in `make test`, #1059 in the cluster.
- **The API never names a Nereid:** no `if controller == "auth0"`, no Nereid's name or tool inside a reef's objects.
- **What a Nereid publishes is untrusted input:** its commands description, image labels and `/contract` answer are validated before the CLI renders or routes them; no shell command built from them, no path out of the work directory.
- **Every command follows ADR 0013** (command conventions): the verbs are kubectl's: `create` builds from flags, fails when the thing exists and lists the commands to run; `apply` creates or updates (every former `add`) from files or folders of `.yaml` only (`--from-file`, `--path`; installing by name waits for #487); `delete` deletes (`add` and `remove` are not verbs); `nereus <reef> <verb>` is the reef's default kind; output lines name the object by its full path, `<reef>/<kinds>/<name>[/<kinds>/<name>...] created|configured|unchanged|deleted` (`secrets/vaults/default/secrets/google-oauth created`, `core/reefs/secrets created`); `--dry-run` on every command that changes something, no exception, `--examples` on every command; errors follow ADR 0012; every output ends with `Next steps:` ([The CLI design](cli.md)); `--reef` and `--nereid` are the flags everywhere.
- **Names are validated with `re.fullmatch`**, never `re.match` with `$` (it accepts a trailing `\n`).
- **A CLI message says what is wrong and what to do in the person's terms**, never a library exception's text (`{error}`, `str(error)`, `shown(error)` in a `ClusterError`, `AuthError`, `fail` or other `*Error`); `{error.status}` is fine. `cli/tests/test_messages.py` enforces it with `ast`, and its `OFFENDERS` list only shrinks (#1301).
- **The CLI's code never imports `click`:** Typer vendors its own copy (`typer._click`), so `isinstance(command, click.Group)` is false for every command of the CLI. Test `TyperGroup` and `TyperCommand` (`typer.core`) and build a context with `typer.Context` (#674).
- **Test runs never touch the person's own config:** own `XDG_CONFIG_HOME` and cache, and the CLI of the checkout (as `test/scene` does).
- **The Nereus API is the one door between the platform and the world** (owner's pillar, 2026-11-02, ADR 0018): whatever is new reaches the cluster through it, never through a kube context, and it cannot lie, as Nereus, who knows everything and never lies: a check that did not run says so, never `pass`. Commands not yet moved keep the kubeconfig, a stand-in ADR 0018 names; `make kubeconfig-ban` (one of `make checks`, #1529) refuses any kubeconfig access in the CLI outside `nereus init`, the bootstrap and the machine's own settings, and its allowlist (`scripts/checks/kubeconfig-allowlist`) only shrinks: a migration lowers its file's count in the same change. A new feature never adds a line to it: it reaches the platform through an API route from its first slice (ADR 0018, "For a new feature").
- **A person or an agent reaches the platform through the CLI, which calls the API; `kubectl` is the last resort** (owner, 2026-11-03, #874): a new step, in a scene or by hand, uses `nereus`, or the CLI's own client when it has to skip a command on purpose; `kubectl` only when neither can do it. The `kubectl` lines scenes already have stay until they are rewritten.
- **What every client must do alike lives behind the API, in a Nereid, never in the CLI:** the CLI is today's client and a portal will call the same API (owner, 2026-11-03, ADR 0020: the Nereid, not the CLI, resolves an image's tag to a digest).
- **Simple on the surface, consistent underneath** (owner's pillar, 2026-11-03, first said 2026-10-25, spec 0007): when designing a command, give a person the familiar, welcoming form first, and let it reach the same verbs, output and errors as every other noun (ADR 0013).
- **The same quality for fewer tokens** (owner's pillar, 2026-11-02, #809): before an activity, weigh whether it can be done as well for less, through smaller answers, the way subagents are called or the models chosen for them; do it that way, or suggest it when the choice is the owner's.
- **Production may break; when it does, stop the line** (owner, 2026-11-04, #946): the owner is the only user of the kept cluster, so a deploy goes there on the owner's go even when it may break it. When it breaks, everything else stops until it is fixed and back; then what let it break becomes an issue, because the goal is a better deploy, with fewer and fewer incidents. The fix goes to the system, never to a person. This is about deploying: tests stay on the throwaway clusters (next rule). Learn more: [jidoka](https://global.toyota/en/company/vision-and-philosophy/production-system/) (Sakichi Toyoda, Toyota) and [andon](https://mag.toyota.co.uk/andon-toyota-production-system/), where any team member may stop the line; [If it hurts, do it more often](https://martinfowler.com/bliki/FrequencyReducesDifficulty.html) (Martin Fowler, 2011); [the error budget policy](https://sre.google/workbook/error-budget-policy/) (Steven Thurgood, Google), which halts changes until the service is back and is no punishment; [blameless postmortems](https://sre.google/sre-book/postmortem-culture/) (John Lunney and Sue Lueder, Google).
- **One throwaway k3d cluster per agent, three at most** (owner, 2026-10-30, #628; it was two clusters in all, #556): one kept cluster, `k3d-nereus`, runs Triton and is used as production, the dogfood and inception of Nereus (Nereus runs on Nereus): never delete it, recreate it or run a test in it (`.claude/hooks/guard-kept-cluster` refuses an agent's `nereus init` that would land on it, #822: `--create-cluster` with no `--name`, `--name nereus`, or the current context; the owner's own terminal has no hook). Beside it, each agent may hold one throwaway cluster for tests (`make scene`, `make scene-release`, `make scene-environment`), named by `test/scene-cluster` (#883) `nereus-scn-<id>-<six characters of a UUID>`, with the whole id of its worktree (`nereus-scn-883-a3f9c2` from `../nereus-883-<slug>`, `nereus-scn-20261103-1450-a3f9c2` from an order's worktree, `nereus-scn-main-a3f9c2` from the main clone); `.scene-clusters/<scene>`, which git ignores, keeps the name for a re-run and says which scene a cluster is for; `--name` overrides it. The scene deletes the cluster when it ends; three throwaway clusters at most at a time: before anything else, a scene that would make a fourth refuses with a line naming the three and exits non-zero. A scene exports a kubeconfig of its own, in a private folder (`mktemp`, mode 0700) deleted when it ends, and fails when the shared current-context moved (#626); any command on the kept cluster names it (`--context k3d-nereus`). Never delete a cluster you did not create; with three running, show them (`k3d cluster list`) and wait. The scenes' pull-through caches (`test/scene-cache`, #563) are k3d registries, not clusters: three containers (`k3d-nereus-cache-docker`, `-quay`, `-ghcr`) on `127.0.0.1` that the scenes keep between runs, so a second run pulls nothing from the internet.
- **Pillars** ([`docs/vision.md`](../vision.md) holds the one full list and why they exist): know them, value them and register the ideas they suggest during your work. The working rules that follow from them:
  - **Walking skeleton first:** a thin end-to-end slice a person can run from the CLI, then widen it. A new slice gets its spec in `docs/specs/`.
  - **CLI examples first:** plan every new feature, Nereid or reef from the commands a person types and what they print: the contract and the experience, written as examples in the issue or spec before any implementation. Every command, built or imagined, goes first into its reef's deck in `docs/specs/cli/` (#477, [The CLI design](cli.md)).
  - **Test-first, adjusted to agents** (owner, 2026-11-07, #1153): what TDD gives an agent is a definition of done it cannot invent and proof that the test can fail; the micro-cycle that keeps a person on track costs an agent turns and tokens (#809). So:
    - **The contract first:** the behaviour is written before the code, as the scene, the CLI examples or a test of the behaviour.
    - **Red proven:** a bug is reproduced in a test that fails before the fix; a new test is seen failing once before the implementation, and the PR says so.
    - **The test frozen during the implementation:** once committed, the agent that implements does not change it without saying why in the PR. Better, one subagent writes the test from the issue and another implements without having written it, so the test does not mirror the code.
    - **The micro-cycle is optional:** once the behaviour's test exists and has failed, the unit may be written straight away; no red-green-refactor on every function, no triangulation, no "fake it till you make it".
    - **Out of the rule:** exploratory spikes, documentation only, configuration only.
    - Learn more: Kent Beck, *Test-Driven Development: By Example* (2002); Anthropic, [*Best practices for Claude Code*](https://code.claude.com/docs/en/best-practices), which asks the agent to "write a failing test that reproduces it, then fix it" and to know what done looks like through "a failing test it has to turn green". Freezing the test is the project's own choice.
  - **Small:** issues that close in hours, PRs merged as soon as the local checks and review pass; a long branch is a signal to cut again.
  - **Every fix gets an issue**, even a small one found mid-task: its own `bug` issue, closed by its PR. Left untracked, "workarounds multiply, exceptions harden, and over time the platform turns back into the accidental system it replaced" (Kaspar von Grünberg and Luca Galante, *Thinking in Platforms*, p. 28; [Thinking in platforms](../thinking-in-platforms.md)).
  - **Eat your own dog food:** what the project needs for itself is built as a capability of the platform as soon as it can be.
  - **An experience that works becomes an exploration of a possible feature** (owner, 2026-11-04, #957): when something done by hand works, open an issue asking whether it could be a Nereus feature, with what happened and what it taught; the owner's triage decides whether it goes on (#956 is the first).
  - **Open source first, native first, build last:** before designing any feature, look for a native resource or an existing tool that fulfills it while integrating with the model of reefs and Nereids (for example `nereus-mcp` as a connector of the Claude app, instead of an app of our own). Build only when none fits, and the issue says which ones were evaluated and why each falls short. Time, tokens and money are not spent rebuilding what a tool already does.
  - **Courtesy and respect** in every exchange; disagreement goes to the idea, and a review names what to change and why.
  - **Security from the first slice:** auditing, authorisation and secrets are designed into a feature from its first slice; every spec's security section names the OWASP categories its slice touches (#237), existing designs are reviewed against them (#235), and compliance (SOX, GDPR, LGPD) and DevSecOps are prepared the same way (#238).
  - **Credit what we use** (#332): every technique, practice or pattern the docs use is named, credited and linked: an ADR gets `## Prior art` before Consequences (ADR 0012 is the model), a spec or page a "Learn more". A claim of effect cites its evidence or says it is the project's own observation; cite only what you opened, never guess an author or year. An accepted ADR may receive `## Prior art` as an editorial addition, its Context, Decision and Consequences untouched.
  - **What an attempt teaches is kept** as an issue, a rule, an ADR or a measurement; a dropped idea closes with what it taught.
  - **Where a new pillar goes** (#873), when the owner asks for one: a section and a bullet in `docs/vision.md` (with its source, when it is a known technique) and the announced count; the working rule here when it changes how an agent works; `README.md` when it is a highlight; `CLAUDE.md` when it holds in every session. No other page states a count. `make docs-lint` fails on a wrong count, a stray count or a `README.md` pillar with no section.
  - **A phrase of the owner about practices or methodology does not pass by** (#873): find the pillar or practice it belongs to, then propose where it goes: a line in that section of `docs/vision.md`, a working rule, a credit in `docs/references.md` when it quotes someone, or a new pillar when the owner says so.
- **Every workaround is a feature waiting for the platform** (#269): every PR and issue says which stand-in it creates (and the feature that replaces it) or retires, or "none", in a "Stand-in" line (`gh pr create --body-file` skips the PR template, so write it in the body). The list lives in `docs/project/stand-ins.md`, updated in the same PR.
- **Conventional Commits:** `<type>(<scope>)!: <description>`, type one of `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `build`, `perf`, `style`, `revert`, `bump`; checked by `scripts/check-commit-message` in `.githooks/commit-msg` and in CI.
- **Decisions go to `docs/adr/`**, Nygard format, `NNNN-short-title.md`, the number valid only once merged into `main`; until v1.0.0 a changed decision rewrites its ADR in place (ADR 0001); from v1.0.0 on an accepted ADR is immutable, superseded by a new one. ADRs stay `Proposed` until the owner reviews them.
- **Commit only on a branch**, never on `main`; every change reaches `main` through a PR. Guards: `.claude/hooks/guard-main` and `.githooks/` (`make hooks`, once per clone). Branches: `feat/<issue>-<desc>`, `fix/<issue>-<desc>`, `docs/<topic>`.
- **`README.md` follows the behaviour:** a PR that changes what Nereus does (a command, a profile, a Nereid, a reef, how we work) updates `README.md` in the same PR; a new Nereid gets its row. No status badges while the repository is private (#438): they come back when it is public or a paid plan makes them render.
- **Docs go straight to the point** (owner, 2026-10-31, #658): every doc (`README.md`, walkthroughs, guides, specs, `docs/agent/`) opens with the answer, keeps prose short and favours commands: what a person types and what it prints, in a code block, with one line of text only where the command does not say it. Cut background, history and repetition; link the issue or ADR instead. `make docs-lint` (run by `make docs-build`) checks what a script can: prose paragraphs of at most 80 words, a command in every walkthrough section (#680).
- **Which test level runs when** (owner, 2026-11-12 and 2026-11-13, #1420, #1424): installing the real tools makes a check slow, so the everyday checks use none.

  | Level | What it proves | Command | When |
  |---|---|---|---|
  | Unit | functions, CLI parsing, the reference Nereids' code | `make checks` | before every PR |
  | Core | the API, the reefs, the Mandates, thetis, the CLI, conformance, with a reference Nereid in place of every tool, and the reefs no tool serves (catalog, tenancy) | `make scene-core` (about 6 minutes) | before a PR that touches a cluster |
  | Contract | a tool's Nereid against a fake of its tool's API, no cluster | `make contract NEREID=<name>` (`openbao` today, #1422) | only when the owner asks |
  | Integration | the real tools together: `make scene`, `make scene-idp`, `make scene-helm`, each reef's scene (`make help` marks them) | `make scene-<name>` | only on the owner's word |

  A reef a tool serves joins the core once it has a reference Nereid (#1502); until then its scene stays whole as integration. A release branch runs `make scene-core FROM=ghcr` (#1464).
- **Before a PR:** `make checks` (lint, test, deck-test, docs-build, shellcheck and kubeconfig-ban; each check and scene writes `docs/checks/<name>.json` and renders the README's badges and table, so the PR carries its times: commit them, #1093), `make scene-core` when the change touches a cluster, and `make catalog-check` when it touches `catalog/`, `reefs/catalog/` or the tenancy, all run locally. **CI is off** (owner, 2026-10-29, for cost): every workflow in `.github/workflows/` (`ci.yaml`, `fake-controller.yaml`) is disabled on GitHub (re-enable one with `gh workflow enable <name>`), so a PR shows no checks and nobody waits for them; the PR's test plan says what ran locally.
- **Relay each test run's comparison** (owner, 2026-11-14, #1513): every run through `scripts/checks/checks record` (each check of `make checks`, each scene) ends with two lines: `checks: <name> <result> in <s>s (<m>), N passed, N failed`, then how it compares with the earlier runs (the median of the last five passing runs, "slower" or "faster" only beyond 10% and 5 s, the failures against the run before). Relay both lines as printed; never compute or estimate a comparison yourself. The history lives outside git, one `<name>.jsonl` per check under `~/.local/state/nereus/checks/`: `scripts/checks/checks history <name> --last 5` shows it, `scripts/checks/checks import` seeds it from the records git holds. A run outside `record` (a contract) reports only its time.
- **Durable decisions of the owner:** the repository stays private until a first version of the product exists (#9); CLI first, the portal after; at the end of each MVP wave, the `panel` skill convenes a stakeholder panel that proposes improvements as `proposed-by-agent` issues.
- **Every session records its metrics** in the private repository before it ends (the log of #113), summed from its transcript by `scripts/metrics/session`, never by an agent.
- **Every order records its evaluation** in the private repository, by `scripts/metrics/order` (#803): performance from the pull request, tokens and the estimated cost from `ccusage`. Its reply ends with the block of `docs/agent/beach.md`, and the agent never asks the owner for a rating.
