# Architecture and development principles (/dev/development)



This document owns what the code must be. How people and agents work day to day lives in
[how we work](./how-we-work.md). What the auth service owns, and its storage direction, live in
[the auth service plan](https://github.com/joeblew999/remy-auth/blob/main/.plans/auth-service.md).

## Development principles [#development-principles]

* Prefer maintained upstream tools, official integrations and existing libraries.
  Check what already exists before writing custom code. Keep wrappers thin; add
  custom behavior only for a concrete unmet requirement and document the gap.
* Keep behaviour local to its owner and visible at the entry point.
* `package.json` is the entry: its scripts run every project command; Node is pinned by
  `.node-version`, every tool is a dependency. Do not import the retired `joeblew999/.github` task
  library or control other repos through shared scripts.
* Development uses local storage. Startup must not provision production identities,
  import sample data or silently change app registrations.
* Keep one Worker implementation and one source Wrangler configuration for local
  and deployed execution. Test the production artifact locally and reuse the same
  acceptance suite against deployed URLs. Environment differences belong in
  bindings and secrets, not duplicate code. See [the runtime workflow](./gui.md).
* Apps integrate through a versioned protocol/contract, never direct access to this
  service's database. App data and auth provisioning are separate operations.
* Failures remain visible. Never grant access because auth is unavailable.
* Keep credentials out of code, plans, logs and commits.
* Give each fact one home. Link to the owning document, config or generated source
  instead of restating it; change the owner, then update links.
* Tests and audits are acceptance gates. Never skip, exempt, loosen or delete a check,
  including individual Lighthouse audits, to make a run pass. Fix the cause, or stop
  and ask the owner.
* Change generated code at its source: shadcn components and theme tokens through
  shadcn, translations in `packages/ui/messages/`, and Wrangler/TanStack Router output
  (including `src/routeTree.gen.ts`) by regenerating. Do not hand-edit or override generated output elsewhere.
* Decisions that plans leave open, or fixes that conflict with a plan, belong to the
  owner. Ask; do not choose, unless the owner has delegated them
  ([how we work](./how-we-work.md#when-the-owner-delegates-decisions)). Production (`dev:promote`), a release
  (`dev:release`), provisioning and filing upstream issues also wait for the owner's explicit request.
  Landing (`dev:land`, staging included) does not: it is the step every finished change takes, by
  whoever made it ([the flow](./how-we-work.md#the-flow-four-steps-and-a-guard-that-refuses-the-rest)).
* Do not mock Better Auth, D1 or the Workers runtime. Development conveniences (seeded people,
  a sign-in picker for them, a fixed sign-in code, captured mail) are allowed only behind one
  per-environment policy table ([remy-auth's](./auth.md#environments-one-table)) whose default, and whose value for any unknown environment, is
  production with everything off; they never create sessions outside Better Auth, never exist
  in production, require authentication outside local development, and are listed in the
  owning plan. No other test-only routes, flags or bypasses.

## Plans and roles [#plans-and-roles]

Plans live in `.plans/`; [.plans/now.md](https://github.com/joeblew999/remy-auth/blob/main/.plans/now.md) is the one list of what is open and
where it stands. Read the plan covering your task before changing anything. Every plan works with two roles: the Reviewer
defines acceptance, and the Executor implements and verifies a bounded milestone, then reports the
exact checks run, the files changed and the limitations. A plan moves to `.plans/done/` only after
implementation, its required checks and the Reviewer's acceptance.