AGENTS.md@examples/scheduling git:20261018.5d99527A

Immutable. This exact content never changes and is served at /api/v1/blob/aba2508af6d117ea.

# scheduling

A ddd-ts-kit project: one bounded context per directory of `src/contexts/`, each described by its `CONTEXT.md`. The plan and what is next: `docs/architecture/plan.md`, when the project follows the method.

## Commands

- `npm run verify`: types, lint, format, tests with the coverage thresholds of `ddd-ts-kit.config.json` (per context and layer), architecture rules, import graph, dead code, documentation drift. Once, before a commit that closes a slice. A layer under its threshold gets the missing test, never an exclusion.
- `npx ddd-ts-kit check --changed-since <ref>`: the architecture rules on what changed; `npx ddd-ts-kit explain <rule-id>` gives the reason and an example.
- `npx ddd-ts-kit list --json`: the map of the contexts. `npx ddd-ts-kit describe <context> --json`: one context as data (use cases, routes, events, ports, dependencies).
- `npx ddd-ts-kit status`: the next step of the plan, the slices by status, the markers left per context. `npx ddd-ts-kit todo [<context>]`: each remaining `TODO(domain)` and `it.todo` as `file:line`.
- `npm run regenerate`: every derived file in one step, after a change of route, schema, event or config: `.dependency-cruiser.cjs`, then `npm run docs:generate`, which runs `npx ddd-ts-kit docs` (the context map, the barrels, the generated sections of each `CONTEXT.md`) and writes the OpenAPI contract, the forms and the event catalog.

## Read less

1. `describe <context> --json` and the `CONTEXT.md` of the context before the tree: do not browse `src/` to learn what exists.
2. Open only what the `next` list of a generator (`file:line`) or a violation names.
3. `check --changed-since <ref>` and the tests of the context while iterating; `npm run verify` once at the end.

## Rules by layer

One file per layer in `.claude/rules/`: `domain.md` (`domain/`, the shared kernel), `application.md`, `published-language.md`, `infrastructure.md`, `presentation.md` (and the OpenAPI contract), `platform.md` (`src/platform/`, `main.ts`, `apps/`), `tests.md` (specs, fakes, builders, worlds, `test/`). The same text is in `.github/instructions/<layer>.instructions.md`. Claude Code and GitHub Copilot load it with the files it applies to; an agent that does not (Codex) reads the file of a layer before it edits a file of that layer.

## Generated files

Create every file of a role with `npx ddd-ts-kit generate <kind> ... --json`, then fill the `TODO(domain)` places it lists; never write one by hand, never restructure what a generator wrote.
Never edit `<context>.declarations.ts`: `generate`, `docs` and `npm run dev` rewrite it, from the role files and from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
Never edit the contracts under `openapi/` (`openapi/openapi.yaml`, one file per document when `openapi.documents` splits it, the forms of `openapi/forms/`), `docs/integration/asyncapi.yaml`, `docs/integration/event-catalog.md`, `src/platform/http/openapi-documents.ts`, `.dependency-cruiser.cjs` or the generated sections of a `CONTEXT.md`: change the code or the config, then `npm run regenerate`. `stored-events.lock.json` is written by `npx ddd-ts-kit docs --stored-events` once the shape of a version is final (`docs --check` fails while one is unrecorded), never by hand: a stored shape changes only by a new version with its upcaster (`event-sourcing/upcaster-required`).
Never edit the clients under `clients/`, except the version and your own keys in their `package.json`: `npm run docs:generate` (`npx ddd-ts-kit sdk`) rewrites them from the contract, `docs:check` fails while they differ from it. A spec or a script calls the API through a client by its package name, which the command resolves to its sources under `paths` in `tsconfig.json`.
Imports: a file of the project is imported by its alias from the project root, never by a relative path, the same directory included: `@/...` for `src/`, `$test/...` for `test/`, `$scripts/...` for `scripts/`, never ending in `.js` or `.ts`, and naming a file, never a directory (`imports/alias-only`, `imports/extension`; `npm run lint:fix` rewrites a relative import and a wrong ending). The alias is declared once, under `paths` in `tsconfig.json`, from `importAlias` of `ddd-ts-kit.config.json`, and the ending follows `importExtension`: never add a second entry or mapping, never change `module` or `moduleResolution` in `tsconfig.json`, and never compile without `npm run build`, which rewrites the aliases of `dist/` into relative paths ending in `.js` for Node (`imports/alias-declared`).
Everywhere: one exported class, interface or function per file, named after it in kebab-case; at most 350 lines a file, 30 lines and 3 parameters a function; `private` members, never `#name`; a blank line before a `return` and around `if`, `for`, `try` (`npm run lint:fix`); braces around the body of every `if`, `else`, `for`, `while` and `do`, on its own lines: a branch is visible at a glance, and a statement added to it later cannot silently fall outside it. `npm run format` (Biome, line width 120) lays out every file, then `npm run lint:fix` adds the blank lines a wrapped statement now needs: do not spend tokens on line breaks, and never run Prettier or a bare `npx biome`.

## TypeScript

The compiler is the native TypeScript 7, installed as `@typescript/native`; `typescript` 6 is there for the tools that need its API (ESLint, dependency-cruiser). Use `npm run typecheck` and `npm run build`, never `npx tsc`, which would run version 6.

## Workflow

Follow the recommended steps in order, the supported path (`README.md` of ddd-ts-kit, "Start a project"): discover the domain, bounded contexts, glossaries, context map, bootstrap, plan the slices, build slice by slice, quality gate, document. `npx ddd-ts-kit status` says where the project stands. When asked to skip a step, say which one and what it costs, and record it in `docs/architecture/plan.md`.
With the ddd-ts-kit plugin: `/ddd-ts-kit:start` for a new project or to resume one, `/ddd-ts-kit:glossary` before a new name, `/ddd-ts-kit:use-case` for a feature, `/ddd-ts-kit:document` for the contracts, `/ddd-ts-kit:quality-gate` before a pull or merge request. The plugin installs in Claude Code, Codex and the Copilot CLI from the marketplace `gbourgeat/ddd-ts-kit`; Codex calls a skill by its name, `$start`, `$use-case`.