Skip to content

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), 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): 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 (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, 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); --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 (Sakichi Toyoda, Toyota) and andon, where any team member may stop the line; If it hurts, do it more often (Martin Fowler, 2011); the error budget policy (Steven Thurgood, Google), which halts changes until the service is back and is no punishment; blameless postmortems (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 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).
  • 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, 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).
  • 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.