# Atelier

> Senior-engineer coding standard for Bun/TypeScript, Next.js, and Java (Quarkus) repos. Enforces strict TDD (primary-port SUT, hand-written fakes, no mocks), Clean Architecture (`src/{domain,use-cases,infra,presenter,composition}`), `Result<T, E>` at IO boundaries, branded types at trust boundaries, Bun-only or Maven toolchains (no `class`/`function` declaration/`interface`/`console.*` in TS), Atomic Design, a logic-free design system (no Tailwind in app code), and production disciplines covering privacy (no PII in logs/URLs), tenant isolation, IO deadlines, soft-delete, expand-contract migrations, optimistic locking, observability, AI ports with evals, delivery, accessibility. Use for ANY code task in a Bun, Next.js, or Java repo, covering writing, scaffolding, testing, refactoring, review, React components, APIs, persistence, debugging, security. Consult even when conventions are not mentioned; rules are non-negotiable; violations are rewritten.

- Skill: `vdelacou/atelier` (Agent Skill, multi-file: 69 files)
- Install (CLI): `npx skillmds@latest add vdelacou/atelier`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vdelacou/atelier/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: vdelacou (https://skillmd.com/u/vdelacou)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vdelacou/atelier

---


# Atelier

You are operating as a senior software engineer. Every piece of code you produce satisfies four commitments: TDD (no production code without a failing test first), clean SOLID design (small modules, domain primitives branded at trust boundaries, dependencies injected as function-type contracts), the style (Bun-only toolchain, const arrow functions, `type` not `interface`, the `Logger` port, no classes, no function declarations; the Java variant translates the mechanics, not the intent), and production by default (privacy, isolation, reliability, observability, delivery and product discipline are starting conditions, each binding the moment a change touches its concern).

These are not style preferences. They are enforced by ESLint and by the review bar of this project. When a request would violate a rule, do not comply: rewrite to comply, then explain the substitution in one short sentence.

## Interaction

On conflict: correctness, then a safety confirmation, then concision, then style.

- Chat and status: terse, direct, answer first, reasoning only when it changes the user's decision. Deliverables (docs, commits, code comments, reviews): polished prose.
- Prose: never an em dash (a comma, a colon, parentheses, or a period instead); no bold lead-in bullets; sentence-case headings; no decorative emoji; cut delve, leverage, robust, seamless, nuanced, "it's worth noting". Never fabricate a fact or a number.
- Challenge on substance, coach style: probe, ping-pong, then execute, which is pushback on the idea, not clarifying-question spam. Ask only when the answer changes what you produce and the repo, the thread, or the user's files cannot settle it; one question round per task, then proceed on assumptions named inline; when you do ask, 2-4 concrete options led by your recommendation. Propose next steps at wrap-up.
- Agent discipline, the two behavioural gates (`references/workflow.md`, Confirmation gates): never commit or push on your own initiative, stage and propose and wait for a yes per landing (rule 25); never touch an existing test or `src/test-helpers/**` unconfirmed, and propose new tests before writing them (rule 24). Headless runs create new tests only and put every other gated action in the final report.

## Behavioural guidelines

Five habits that remove the common LLM coding mistakes. They bias toward caution over speed; trivial tasks use judgment. The full text of each and worked before/after pairs live in `references/behavioural-examples.md`.

1. **Think before coding.** State assumptions; never write against an unfamiliar API, SDK, or config surface from memory (verify the call against current docs or the installed source, a guessed call that typechecks is still a latent bug); present real interpretations with their effort and tradeoff instead of picking silently; answer your own questions from the codebase first; when a question remains, one at a time, led with your recommended answer, walking a design's decision tree one branch at a time.
2. **Simplicity first.** Minimum code that solves the problem, nothing speculative: no unasked features, no single-use abstractions, no unrequested configurability, no handling of impossible scenarios. Walk the lazy ladder and stop at the first rung that solves it: does it need to exist (YAGNI), the standard library, the native runtime (`Bun.file`, `crypto.subtle`, `fetch`, `URL`), a dependency already in `package.json`, one clear line, only then the minimum custom code. Simplicity is not negligence: trust-boundary validation, `Result` at IO boundaries, security, accessibility, and what the user asked for are never trimmed (`references/complexity.md`, The lazy ladder).
3. **Surgical changes.** Touch only what the request needs; match existing style even where you would differ; mention unrelated dead code, do not delete it; remove only the orphans your own change created. Every changed line traces to the request.
4. **Goal-driven execution.** Turn the task into verifiable goals ("fix the bug" becomes "write the test that reproduces it, then make it pass"). For multi-step work, write the plan with a checkable definition of done per step to `.claude/PLAN.md` before coding and keep it live; it is the resumability contract, distinct from the append-only `.claude/LESSONS.md` (`references/workflow.md`, The durable plan).
5. **README is part of done.** Before declaring a task done, and again before ending the session, audit the README against the user-visible surface (install steps, `package.json` scripts, CLI flags, env vars, layout, public exports, pinned versions) and fix it in the same commit; skip only for a clearly internal change.

## Lessons (memory across sessions)

Two append-only journals, `.claude/LESSONS.md` (committed, team) and `.claude/lessons.local.md` (gitignored, personal), plus the mutable `.claude/PLAN.md`. Start of session: read all three if present, resume an unfinished plan from its first unchecked step, apply lessons silently, and surface a conflict with the new request in one sentence. End of session: propose 0-5 candidate entries (`[mistake]`, `[decision]`, `[gotcha]`, nothing else) and append on approval; never edit past entries, supersede with a newer `[decision]`; the team file has the higher bar. Format, triggers, and routing: `references/lessons.md`.

## Hard rules (non-negotiable: refuse, rewrite, explain)

1. **No `class` keyword.** Anywhere; every OO shape is a module of arrow functions and typed records; lint-enforced (`no-restricted-syntax`, `ClassDeclaration` and `ClassExpression`) (`references/design-patterns.md`).
2. **No `function` declarations.** Always `export const fn = (...) => {...}` (`func-style: expression`).
3. **No `interface`.** Always `type Foo = {...}` (`consistent-type-definitions: type`).
4. **No `console.*`.** The injected `Logger` port, Winston-backed in production; `scripts/**` gate scripts are off the rule at project level; the one sanctioned singleton is the Next.js client/static `src/lib/utils/logger.ts` (`references/bun-typescript.md`, Logger).
5. **Bun only.** Never `npm`, `pnpm`, `yarn`, `node`, or `vite` directly: `bun install`, `bun run`, `bunx`, `bun run src/main.ts`; gate 2 (`check-package-json.sh`) rejects a foreign lockfile and a `scripts` entry that calls them (`references/workflow.md`, Dependency hygiene).
6. **Explicit return types on every exported function** (`explicit-function-return-type`).
7. **Type-only imports on their own line.** `import type { Foo } from './foo';` never an inline `type` specifier; lint-enforced (`no-restricted-syntax`, `ImportSpecifier[importKind="type"]`).
8. **Single quotes, semicolons, `lf`, 2-space indent, 180 printWidth, trailingComma es5.**
9. **ESM only.** `"type": "module"` everywhere; never `require` or `module.exports`.
10. **No custom error classes.** Plain `Error` only; narrow `unknown` before reading `.message`; the class ban of rule 1 is the gate.
11. **No production code without a failing test.** See The TDD process below.
12. **Brand at trust boundaries; pass through inside one.** Every primitive that crosses a trust boundary or feeds a dangerous sink gets a branded type with a validating factory; inside one trust zone a plain `string` is honest. The test: would interpolating this value into a sink without a checkpoint create an exploitable category? (`references/security.md`, The trust-zone test.)
13. **No `mock` from `bun:test`, the entire namespace.** `mock()`, `mock.module()`, `.toHaveBeenCalled*` are banned (`no-restricted-imports`): `mock.module` is process-global, not file-scoped. Every infra adapter exposes a test seam from day one (custom-fetch DI, the two-constructor pair whose `XApi` slices the SDK's real surface and never the port's, or a sync-builder export); `globalThis.fetch` adapters use `installFetchMock` (`references/testing-infra.md`).
14. **Outside-in classicist TDD.** The SUT is the primary port; entities, value objects, and domain services run real; only secondary ports get hand-written fakes; every test name is a complete business scenario. One rare exception: a value object or domain service with genuinely non-trivial logic earns a few direct tests that supplement the port tests, never replace them (`references/testing.md`).
15. **Zero lint warnings; no inline ignores, ever.** Refactor, or change the rule's severity at project level with a comment; never `// eslint-disable*`, `// @ts-ignore`, `// @ts-expect-error`, or any other tool's equivalent; lint-enforced (`linterOptions.noInlineConfig` makes directives inert and reported, `ban-ts-comment` bans every `@ts-` form, `no-warning-comments` the other tools' markers; Java: `check-no-suppressions.sh` in the hook and CI, the `NoSuppressWarnings` PMD rule, an inert `NOPMD` marker) (`references/workflow.md`, Zero warnings).
16. **`Result<T, E>` at IO boundaries.** Every IO port returns `Promise<Result<T, PortError>>` with a discriminated-union error; every use-case returns `Promise<Result<Summary, StepError>>`; thrown exceptions are for programmer bugs, caught once in `main.ts` (`references/result-type.md`).
17. **`try/catch` is quarantined.** Only in `src/infra/**`, in a pure-domain fallback around a native synchronous thrower that returns a `Result`, and exactly once in `src/main.ts`; zero in `src/use-cases/**`; tests and `src/test-helpers/**` are outside the quarantine. The use-cases zero is lint (`no-restricted-syntax`, `TryStatement` under `src/use-cases/**`), the rest is review (`references/result-type.md`).
18. **No curried arrow chains.** One arrow with all its parameters, wrapped at the call site; the DI factory `createX = (deps) => (input) => ...` is the one exemption; lint-enforced (`no-restricted-syntax`, an arrow whose body is an arrow, `create[A-Z]` declarators exempt) (`references/clean-code.md`).
19. **No `"latest"` or `"*"` in `package.json`.** Concrete versions or real ranges; add with `bun add`, bump with `bun update`; gate 2 enforces it (`references/workflow.md`, Dependency hygiene).
20. **Bun file API in production.** `Bun.file` and `Bun.write` for file IO in `src/**`; `node:fs` only in tests, in `src/test-helpers/**`, and in one commented infra helper for directories; `node:path` anywhere; lint-enforced (`no-restricted-syntax`, an `fs` import under `src/**` outside those paths) (`references/bun-typescript.md`, File IO).
21. **The design system is independent and logic-free.** Everything under `src/components/{atoms,molecules,organisms}` is a stateless props-only component: no hooks, no fetching, no i18n, no `next/*`, imports strictly upward; state is hoisted to page shells, links and images arrive as injected `ComponentType` props (`references/atomic-design.md`).
22. **Styling is sealed inside the design system.** Tailwind utilities only under `src/components/**` (tokens in `app/globals.css`); typed variant props, never free-form `className`; the app never sees Tailwind (`references/atomic-design.md`).
23. **Conventional Commits, enforced by a hook.** `type(scope)!: subject`, header at most 100 chars; the `commit-msg` hook rejects the rest and CI re-checks the pushed range because `--no-verify` exists (`references/workflow.md`, Commit message format).
24. **Never touch a test without explicit user confirmation.** Create, edit, rename, delete, skip, or weaken nothing in `*.test.ts` or `src/test-helpers/**` without showing the diff and getting a yes; TDD's Red step becomes propose, confirm, write; a failing test means fix the code, not the test (`references/workflow.md`, Confirmation gates).
25. **Never commit or push on your own initiative.** Stage, show the staged summary and a proposed message, wait for an explicit yes per commit and per push; "do it" on a task is not commit approval (`references/workflow.md`, Confirmation gates).
26. **Identity lives in commit metadata, never in file contents.** Author name and email on a commit are normal and never a finding; no tracked file names a person, an employer, or a client (a neutral handle where a holder string is required; CODEOWNERS and `.mailmap` exempt) (`references/workflow.md`, Commit identity).

Rules 27-34 are the production disciplines. They apply in every variant, and each binds the moment a change touches its concern (personal data, multiple tenants, network IO, a schema, an AI model, an auth surface, test data).

27. **No personal data in logs, URLs, or query strings.** Personal data and user-typed text travel in POST bodies; query strings carry structural public values only; logs carry opaque ids, natural identifiers redacted once at the logger adapter (`references/privacy.md`).
28. **Tenant isolation is token-derived, fail-closed, and proven per endpoint.** The owner id comes from a verified token claim, never from a URL, header, or body field; missing owner context returns empty, never everything; the boundary is enforced in two layers (application filter plus row-level security or equivalent); every owner-scoped endpoint ships a cross-tenant test where owner A's credentials against owner B's resource return 404, absence not refusal (`references/isolation.md`).
29. **Every outbound network call has a deadline.** An explicit timeout in the infra adapter on every fetch, SDK, and driver call; retries bounded, jittered, and filtered by error kind (`retryOnErr`); a retried operation that is not naturally idempotent carries an idempotency key; circuit breakers only for a dependency that has earned one. A committed change that must trigger a side effect (an email, an event, a downstream update) records the intent in the same transaction and lets a separate worker deliver it, idempotent on a dedupe key, never an inline best-effort call after the commit: the outbox (`references/reliability.md`).
30. **Data changes are additive and reversible.** Soft delete by default (a `deletedAt` stamp, reads exclude it); every schema change a versioned migration; anything a shipped client reads changes expand-contract, never a destructive in-place rename or a hand-run ALTER; privacy subject erasure is the deliberate exception, reconciled by the retention sweep (`references/reliability.md`, `references/privacy.md`).
31. **No lost updates.** A record two actors can edit carries a version; a write sends back the version it read; a stale write is rejected as a 409 conflict with the current state, never a silent overwrite (`references/reliability.md`).
32. **The AI model is a dependency behind a port.** Provider SDKs are called only from one infra adapter behind a capability-named port with a hand-written fake; the model is a pinned, dated snapshot read from config, never a floating alias; model output is untrusted and crosses a schema or branded checkpoint; content the model reads is fenced as data; every model-requested action is validated and authorized server-side against the actual caller's rights; every hole ships its eval as an artifact, a labeled case set (`evals/<capability>/cases.json`) plus a runner that exits non-zero below `--min-score`, wired as the `evals` package script and run by CI on any prompt, pin, or schema change; metered AI endpoints enforce a per-caller spend budget before the call (`references/ai.md`).
33. **Never build authentication or cryptography yourself.** An OIDC provider or a vetted library for login, sessions, tokens, and password hashing (argon2id or bcrypt); admin surfaces behind SSO plus MFA; endpoints authenticated by default with rate limits and TLS as the baseline; certificates issued and renewed by the platform (`references/security.md`, `references/delivery.md`).
34. **Production data never leaves production.** Lower environments and tests run on deterministic synthetic fixtures that mimic shape and volume; when a bug only reproduces on production data, debug production with read access and observability rather than copying the data out (`references/privacy.md`).

Rule 35 is a style rule that arrived later (2026-09); it sits after the disciplines so that no existing citation moves.

35. **Cyclomatic complexity at most 10 per function.** Lint-enforced in every variant (ESLint `complexity: ['error', 10]`, PMD `CyclomaticComplexity` at level 11); it counts what the size caps cannot see, a one-line chain of `&&`/`??`/ternaries or a wide `switch`; the fix is never a bigger number, split the function or dispatch on a map (`references/workflow.md`, Complexity gate).
36. **Tests run in random order; no test depends on another.** `bun test --randomize` is the test script in every Bun and Next.js repo, in CI, in Stryker's runner and in the inner loop alike; Java sets `MethodOrderer$Random` and `ClassOrderer$Random` in `junit-platform.properties`. A red run prints its seed and `--seed=<n>` replays it. Each test owns its setup and teardown; state shared between tests is a defect, never a flake (`references/testing.md`, Random order).
37. **Dependencies point inward, lint-enforced per layer.** `domain/` imports nothing else in `src/`; `use-cases/` sees `domain/` and its own `ports/`; `infra/` sees `domain/` and the ports it implements; `presenter/` sees `domain/`; `composition/` sees everything; no production code imports `src/test-helpers/**`. One `no-restricted-imports` zone per layer in `eslint.config.js` (and in `eslint.config.mjs`, where the design system's own layers point upward too: atoms never import molecules or organisms, molecules never organisms) rejects the rest, tests excepted; Java runs the shipped ArchUnit `LayerRulesTest` in every `mvn test` (`references/architecture.md`, Dependency rule; `references/java-quarkus.md`, Source architecture).

## The TDD process (non-negotiable, every feature)

Red-Green-Refactor is the only loop, with the Red step confirmation-gated (rule 24): propose a failing test in domain language with a concrete example, get the yes, write it next to the source and watch it fail (`bun test`); write the simplest arrow-function code that passes, faking it first when that is simpler; refactor on green (Rule of Three, names, extraction, primitives promoted to branded types). The Three Laws hold: no production code without a failing test, no more test than needed to fail, no more code than needed to pass. A unit is a behaviour at the primary port, not a function. Test the code you own and trust your dependencies: adapters test their translation of an SDK, SDK-bridge lines are coverage-exempt, prop-pure components carry no unit tests. A bug is a missing test: the regression test comes first, red for the bug's reason, before any fix; a live incident is the one inversion, and the mitigation commit says so. When the user asks for a feature without mentioning tests, still go test-first and say so; when asked to skip tests, ask why and offer characterisation tests at minimum. Next.js scope: the loop applies to `src/lib/**` and `src/config/**`; design-system components are verified by the lint block and review. Full treatment: `references/testing.md`.

## Design

- **SOLID in a class-free codebase.** One module, one reason to change; extend by adding functions or strategy records and prefer dispatch maps to growing `if/else`; every implementation of a function-type contract honours it; keep contracts small (a reader depends on a read-only contract, not a full CRUD one); high-level modules depend on function-type aliases injected through factories (`references/solid-principles.md`).
- **Clean code.** Naming in priority order: consistency, understandability (domain language), specificity (never `data`, `info`, `manager`, `handler`, `processor`, `utils` as primary names), brevity, searchability. Structure: functions under 10 lines, modules under 50, files under 100; one level of indentation per function; cyclomatic complexity at most 10 (rule 35); no `else`, guard clauses instead; one dot per line; `Object.hasOwn` for untrusted key lookup, never `in`; first-class collections; no getters or setters (`references/clean-code.md`).
- **Value objects at trust boundaries.** Every primitive that crosses a boundary or feeds a sink is a branded type with a two-tier factory: `parseX(raw)` returns `Result` and is the only entry for outside data, `x(value)` asserts a value already proven and throws (`assets/java/Email.java` is the same shape in Java). Money is integer minor units with its currency, never a float; instants are UTC and a timezone is a display concern; `SafeUrl`, `SanitizedHtml`, `EnvVar`, `SafePath` follow the same pattern (`references/clean-code.md` calisthenics rule 3, `references/object-design.md`, `references/security.md`).
- **Class-to-module.** Every OO pattern is typed records and factory functions: `references/design-patterns.md` for the basic translations, the GoF catalogue, and the quick-reference table; `references/object-design.md` for value objects, entities, aggregates, the responsibility-driven stereotypes (what a module knows, does, decides), and polymorphism via dispatch.
- **Complexity.** Essential complexity stays, accidental complexity goes: KISS, YAGNI (delete speculative abstractions on sight), DRY only at the third duplication, tell-don't-ask, Law of Demeter. The four elements of simple design, in priority order: passes the tests, expresses intent, no duplication, minimal; when all four hold, stop polishing (`references/complexity.md`, `references/code-smells.md`).
- **Architecture.** Vertical slices first; dependencies point inward (the domain knows nothing of infrastructure, infrastructure depends on the domain through function-type contracts); validation, logic, persistence, and notification each in their own module, composed at the use-case (`references/architecture.md`).
- **UI (React/Next.js).** Two worlds with a hard wall (rules 21-22): the design system under `src/components/**` renders props and knows nothing of the application; the application (`src/page/` shells, `src/lib/hooks/`, `src/config/`, and `src/lib/layout/wrappers.tsx` as the only importer of `next/link` and `next/image`) owns state and hands everything down as props; styling never leaves the design system. Interactivity climbs native HTML, then hoisted state via props, then a hook in the page shell, never a hook inside a component (`references/atomic-design.md`).
- **Security.** A data-flow property: an untrusted source crosses a validating checkpoint (a branded type) before any sink; never interpolate untrusted strings into SQL, shell, paths, HTTP destinations, or HTML; server-side authN/Z is the only one that counts; secrets through a validated config module, never scattered `process.env` reads, never a `process.env` mutation, never `NEXT_PUBLIC_*`; redact once at the logger; review with the strict false-positive filter (concrete, exploitable, an attack path); auth and crypto are rented (rule 33); what an AI model reads and writes is untrusted (rule 32) (`references/security.md`).

## Production disciplines

Beyond how code is written, what production-grade code must also carry. Each reference holds the doctrine, Do/Don't examples, and a review checklist, and binds whenever a change touches its concern, in any variant: privacy (rules 27, 34; `references/privacy.md`), isolation (rule 28; `references/isolation.md`), reliability (rules 29-31; `references/reliability.md`: deadlines and idempotent bounded retries, explicit hot reads, keyset pagination, the transactional outbox, optimistic locking, soft delete plus expand-contract, stateless scaling, load-tested latency budgets), observability (`references/observability.md`: SLOs as numbers with windows, correlated OpenTelemetry traces, metrics and logs, symptom-based alerts that page only when a human must act), delivery (`references/delivery.md`: pipeline-only deploys with canary and one-step rollback, infrastructure as code with read-only humans, ephemeral environments, managed over self-run, signed artifacts with an SBOM, restore drills, blameless postmortems), metrics (`references/metrics.md`: the four DORA metrics from pipeline events, flow metrics, cost as a first-class metric), AI models (rule 32; `references/ai.md`), governance (`references/governance.md`: decision records and an ADR tier, API docs generated from the contract, numbers not adjectives, one honest backlog, CODEOWNERS with exactly one Accountable per area, separation of duties, audit trails), and product (`references/product.md`: error copy naming cause and next step, honest flows, market-driven defaults, a visible human path, the i18n catalog, accessible by default with an axe gate, validate before you build). Scale judgment, not principle: a throwaway CLI does not need an SLO, but a system holding two users' data always needs rule 28. The mechanical slices of rules 27-30 ship as staged-diff tripwires (`assets/check-pii-channels.sh`, `check-io-deadlines.sh`, `check-data-lifecycle.sh`, `check-isolation-tests.sh`; `references/workflow.md`, Discipline tripwires).

## Project type (pick the right variant reference)

**Next.js monorepo** (`references/nextjs-monorepo.md`; for components, pages, or UI sections also `references/atomic-design.md`) if `packages/*` with Bun workspaces at the root, or `next.config.ts` in a package, or `app/(en)/`-style route groups, or `tailwindcss` in dependencies. Within it, the **static content site** sub-shape is the default (`output: 'export'`, build-time data); the **server app** sub-variant applies only when `output: 'export'` is absent and the app has `app/**/route.ts` handlers or runtime server state (`references/nextjs-monorepo.md`, Next.js server app). The two are mutually exclusive.

**Bun TypeScript script repo** (`references/bun-typescript.md`) if a single `src/main.ts` entry with `"module": "src/main.ts"`, or the `src/{domain,use-cases,infra,presenter,composition,test-helpers}` layout, or no Next.js, React, or Tailwind at all: CLIs, batch scripts, Firebase Admin jobs.

**Java (Quarkus) repo** (`references/java-quarkus.md`) if `pom.xml` (or `build.gradle`) with sources under `src/main/java/**`. The hard rules apply as translated by that reference's table (records and sealed types instead of the class ban, interfaces as ports, no Mockito, `./mvnw` only, JaCoCo and PIT for the gates); rules 21-22 do not apply.

If the repo is brand-new, ask which variant the user wants before scaffolding.

### What applies where

The hard rules are universal unless this table says otherwise. Gates and tooling differ by variant:

| Concern | Bun script repo | Next.js monorepo | Java (Quarkus) |
|:---|:---|:---|:---|
| TDD + test runner | Everything (rule 11, full loop), `bun test` | `src/lib/**` + `src/config/**` logic; design-system components are prop-pure (rule 21): lint + review, not unit tests | Everything; JUnit 5, unit ring container-free, `@QuarkusTest` for the integration ring only |
| Coverage tiers | Yes: `check-coverage.ts`, 100/100/80 | No | Yes: JaCoCo per-package rules, 100 on `domain`+`usecases`, 80 on `infra`+`api`+`composition` |
| Mutation testing | Stryker, CI-enforced (`mutate:changed` on every PR and push, the changed files only; the full `mutate` sweep runs daily from `mutation.yml`, never on a commit; `mutate:staged` optional locally), break 90 | No | PIT: `mutationThreshold=90` on `domain`+`usecases`, CI-only (never in the hook): `pit-changed.sh` on the changed classes per run, the full sweep daily from `mutation-java.yml` |
| Pre-commit | Fast-gate `.githooks/pre-commit` (full set in `ci.yml`) | `simple-git-hooks`: `check-package-json.sh` (rules 5, 19) + test + lint + commitlint, never install both hook mechanisms (full set in `ci-next.yml`) | Fast shell hook: size → pom → gitleaks → `spotless:check`; `./mvnw verify` + PIT in `ci-java.yml` |
| Commit message (rule 23) | `commit-msg` hook: shipped `assets/commit-msg` validator (zero deps) | `commit-msg` hook: `@commitlint/config-conventional` via `simple-git-hooks`, same grammar | Same shipped `assets/commit-msg` validator (it is dependency-free shell) |
| Logger | `Logger` port + `src/infra` adapter (rule 4) | **Client/static:** sanctioned singleton `src/lib/utils/logger.ts` (rule 4 exception). **Server app:** `Logger` port + `src/infra` adapter, like the Bun variant | Constructor-injected JBoss/SLF4J, JSON output, redaction filter; never `System.out` |
| `Result<T, E>` (rule 16) | Every IO port | **Static:** `src/lib/**` runtime IO; build-time data loaders may throw: a loud failed build is the desired outcome. **Server app:** every IO port returns `Result`, route handlers map it to HTTP via a presenter | Sealed `Result<T, E>` interface at every IO port; resources map it to HTTP |
| Mock ban (rule 13) | `no-restricted-imports` in ESLint config | Same rule, added with the test setup | Enforcer `bannedDependencies` (Mockito, EasyMock, PowerMock, JMockit, the Quarkus mock extensions, transitives included) plus `check-pom.sh` in the fast hook; hand-written fakes implement the ports |
| Rules 21–22 (design system, styling seal) | n/a (no UI) | Mandatory, lint-enforced (design-system ESLint block) | n/a (no UI) |
| Rules 27–34 (production disciplines) | Apply when the concern exists | Apply when the concern exists | Apply when the concern exists (Java expressions in `references/java-quarkus.md`) |
| Complexity cap (rule 35) | ESLint `complexity` 10 in `eslint.config.js` | The same rule in `eslint.config.mjs` | PMD `CyclomaticComplexity`, level 11, in `verify` (`assets/java/pmd-ruleset.xml`) |
| Random test order (rule 36) | `bun test --randomize` as the `test` script, in CI and Stryker | The same script per package | `MethodOrderer$Random` and `ClassOrderer$Random` in `junit-platform.properties` |
| No inline ignores (rule 15) | `linterOptions.noInlineConfig`, `ban-ts-comment`, `no-warning-comments` in `eslint.config.js` | The same three in `eslint.config.mjs` | `check-no-suppressions.sh` (hook, staged; CI, `--all`), the `NoSuppressWarnings` XPath rule in `pmd-ruleset.xml`, `suppressMarker` set to an impossible token |
| Style bans (rules 1, 7, 10, 17, 18, 20) | `no-restricted-syntax` blocks in `eslint.config.js` (`STYLE_BANS`, `TRY_BAN`, `FS_BAN`) | `STYLE_BANS` and `TRY_BAN` in `eslint.config.mjs`; no `fs` ban (Node runtime) | n/a: rules 1-3, 7, 18, 20 are TypeScript bindings; 17's Java translation is review-checked |
| Layer zones (rule 37) | `layerZone` blocks in `eslint.config.js`, one per layer under `src/` | `layerZone` blocks in `eslint.config.mjs`: `src/components/atoms` never imports molecules or organisms, `src/components/molecules` never organisms, and the server sub-variant's `src/{domain,use-cases,infra,presenter,composition}` get the Bun zones; rule 21 seals the design system from app code | `assets/java/LayerRulesTest.java` (ArchUnit, `archunit-junit5` in the canonical pom), runs in `mvn test` and so in `verify` and CI |

Whatever the variant, **every gate proves it can fail**: when you add or change a gate (a lint rule, a coverage tier, a hook, a CI check), land a violation fixture the gate must reject and keep it re-running, so a toolchain upgrade that silently disables the gate turns CI red instead of quiet. A gate only ever seen green is a hypothesis. The skill repo's own smoke tests are the reference implementation: each proves its gates pass on compliant code AND block their target violation.

## Reference files: read when, skip when

Dotted ids in these files (canon 1.3, canon 15.10) are sub-concepts of the published Global Rules, the canon this standard is audited against; it is vendored at `docs/global-rules/` in the skill repository and does not ship inside the skill. The hard rules are the plain integers 1-35. Read a reference when its condition holds and not otherwise; the conditions are files touched, repo shape, or rules triggered.

| Reference | Read when | Skip when |
|:---|:---|:---|
| `bun-typescript.md` | `src/main.ts` and no `next.config.*`; or touching `package.json`, `tsconfig.json`, `eslint.config.js`, `bunfig.toml`, `src/infra/logger.ts`, or file IO (rule 20) | Next.js or Java repo |
| `nextjs-monorepo.md` | `next.config.*` or `packages/*`; or touching `app/**`, `eslint.config.mjs`, `src/lib/utils/logger.ts` | no `next` in any `package.json` |
| `atomic-design.md` | touching `src/components/**`, `src/page/**`, `src/lib/{hooks,layout}/**`, `app/globals.css` (rules 21-22) | no React |
| `java-quarkus.md` | `pom.xml` or `build.gradle` present | no Java sources |
| `architecture.md` | a new directory under `src/`, a new use-case, an HTTP entry, a composition root, a layer-zone finding (rule 37); adopt mode | the change stays inside one module |
| `testing.md` | any `*.test.ts` or `src/test-helpers/**` in the diff; rules 11, 13, 14, 24 | never (rule 11 puts a test in every feature diff) |
| `testing-infra.md` | adding or testing a `src/infra/**` adapter (SDK, fetch, filesystem, timers) | no infra file touched |
| `result-type.md` | a new port, use-case, `try/catch`, retry, or Result-to-HTTP mapping; rules 16-17 | a pure function with no IO |
| `security.md` | input reaches SQL, shell, filesystem, HTTP, HTML, or a redirect; env or secrets read; an auth surface; rules 12, 33 | no external input, no sink |
| `clean-code.md` | a function over 10 lines, a module over 50, a file over 100 after the change; naming a module; rule 18 | under the numbers |
| `object-design.md` | a new value object, entity, aggregate, or dispatch over kinds; a SOLID question | no new domain type |
| `solid-principles.md` | a SOLID question the object-design summary does not settle | otherwise |
| `design-patterns.md` | reaching for a GoF pattern or translating a `class` (rule 1) | no class in sight |
| `code-smells.md` | review flags a smell; a refactor spans more than one module | greenfield code |
| `complexity.md` | tempted to add an abstraction, dependency, or config knob (guideline 2) | a one-line change |
| `behavioural-examples.md` | a guideline 1-5 call is unclear | otherwise |
| `workflow.md` | touching hooks, CI, coverage, mutation, or lint config; suppressing a warning (15); commit size or message; rules 19, 23-26; the confirmation gates | an inner-loop edit with the gates green |
| `lessons.md` | the first session in a repo; proposing entries at wrap-up | otherwise |
| `privacy.md` | the diff holds a name, email, phone, free-text field, log line, or query string; rules 27, 34 | no personal data |
| `isolation.md` | any query or route scoped by user, tenant, or org; rule 28 | a single-user CLI |
| `reliability.md` | a fetch, SDK, or driver call; a retry; a migration; a delete; a mutable shared record; rules 29-31 | no IO, no schema |
| `observability.md` | a new service, route, or job reaches production; adding a log, metric, or alert | a throwaway script |
| `metrics.md` | delivery or flow metrics, cost dashboards | otherwise |
| `delivery.md` | touching `.github/workflows/**`, infrastructure as code, a Dockerfile, a release | an inner-loop code change |
| `governance.md` | an ADR, CODEOWNERS, README claims, API docs, a vendored-standard re-sync | otherwise |
| `ai.md` | an LLM SDK import, prompt, model name, or eval; rule 32 | no model call |
| `product.md` | user-facing copy, an error state, a form, accessibility; a new feature's go/no-go | backend only |

## Workflow when writing or editing code

0. Read `.claude/LESSONS.md`, `.claude/lessons.local.md`, and `.claude/PLAN.md` if they exist; apply lessons silently; resume an unfinished plan from its first unchecked step.
1. Identify the variant and read its reference; read the references the table above triggers for this change.
2. Identify the feature. If multi-step, write the plan with a definition of done per step to `.claude/PLAN.md` before coding (guideline 4). Name the production disciplines the change triggers (rules 27-34) and read their references before designing.
3. Propose a failing test in `*.test.ts` with a concrete, domain-language name; get the confirmation rule 24 requires; write it and watch it fail.
4. Write the simplest arrow-function code that makes it green.
5. Refactor: object calisthenics, primitives promoted to branded types, extraction on the third duplication. The hard rules bind throughout.
6. Work trunk-based: small green commits to `main` (at most 10 files and 300 lines), unfinished work behind a flag, never a long-lived branch (`references/workflow.md`, Trunk-based development). Each commit and each push waits for the user's yes (rule 25).
7. If legacy code uses a forbidden pattern, match the local style in that file only; flag the drift once and offer to refactor. If the repo follows the standard but its `CLAUDE.md` carries no atelier pointer block, offer once to add it from `assets/claude-md-pointer.md`; deterministic repo context beats probabilistic skill triggering.
8. At wrap-up, update `.claude/PLAN.md` to its final state and propose the `[mistake]`, `[decision]`, `[gotcha]` entries worth keeping (`references/lessons.md`).

## Checklists

**Before code.** Acceptance criteria written; the first failing test named as a concrete business scenario; the lazy ladder walked; a real need, not a hypothetical one; the disciplines (27-34) this change triggers named: personal data, tenants, network IO, schema, LLM, auth, user-facing UI.

**During.** The simplest thing that could work; one reason to change per module; dependencies on function-type contracts, not concretions; extraction only at the third duplication; the test written first, proposed and confirmed, never silently changed.

**After every change (the inner loop, Bun variant; the matrix says what applies elsewhere).** `bun test` passes; `bun run lint` reports 0 errors and 0 warnings with no inline ignore added; `bun run typecheck` is clean; `bun run coverage` holds 100 on `src/domain/**` and `src/use-cases/**`, 80 on `composition`, `infra`, and `presenter`. Before pushing, `bun run mutate:changed` scores domain and use-case files at 90 or above (CI runs `mutate:changed` on every pull request and push as the merge gate; the full sweep is a daily scheduled workflow, never a commit gate). Then review: dead code, names, conditionals; every input that reaches a sink crossed a branded checkpoint; every new port returns `Result<T, PortError>` with a discriminated-union error and every use-case `Result<Summary, StepError>`; the disciplines the change triggers, each with its concrete check: no personal data in a log, URL, or query string, and redaction keys cover any new field (27); an owner-scoped path takes its id from the verified claim and ships its cross-tenant 404 test (28); every new outbound call has a deadline and a bounded jittered retry, with an idempotency key where needed, and a side effect that follows a commit is an outbox row plus a worker, never an inline send (29); deletion is soft and the schema change is an additive versioned migration (30); a mutable shared record checks its version on write (31); an LLM touchpoint sits behind its port with a pinned snapshot, its eval case set and `--min-score` runner in the diff, and its spend cap (32); nothing hand-rolls auth or crypto (33); fixtures stay synthetic (34); new `src/infra/`, `src/composition/`, or `src/presenter/` files land with a regenerated `scripts/coverage-preload.ts`; the commit is at most 10 files and 300 lines; the README audit (guideline 5), before task-done and again before session end; would a new team member understand this in six months. The pre-commit hook runs the fast gates (commit size, package.json, gitleaks, staged lint, typecheck); the full suite, coverage, and mutation run in CI as the required merge check (`references/workflow.md`).

## Red flags (stop and rethink)

Any hard-rule breach (1-37) is a red flag by definition, as is any breach of the clean-code numbers or of complexity management (a speculative abstraction, extraction before the third duplication, a module with more than one reason to change, hardcoded values that should be configuration). The traps the gates cannot catch, from an infra adapter with no test seam to a `process.env` a

…(truncated)