10 KiB
KIS-TOiR — Agent Operating Rules
Read this file at the start of every session before reading any other file.
What this repository is
KIS-TOiR is a fullstack CRUD application (NestJS backend + React Admin frontend) for equipment maintenance management (Техническое обслуживание и ремонт).
Generation is driven by a single authoritative source file:
domain/toir.api.dsl— the complete API contract: enums, DTOs, endpoints, HTTP methods, pagination
Source-of-truth hierarchy
Tier 1 — authoritative (hand-authored; never overwritten by generation)
| File | Authoritative for |
|---|---|
domain/*.api.dsl |
Enums, DTO shapes per operation, nullability, HTTP verb+path per endpoint, endpoint names, pagination contracts. Single source of truth. Drives: NestJS modules + React Admin resources + Prisma schema. |
prompts/*.md |
Auth rules, runtime rules, framework scaffold rules, Prisma rules, validation rules, generation policy, naming conventions. |
AGENTS.md (this file) |
Agent workflow, mutation boundaries, verification contract. |
Tier 2 — deterministic derivative (generated by script; never edited manually)
| File | Generated from | Command |
|---|---|---|
api-summary.json |
domain/*.api.dsl |
npm run generate:api-summary |
Tier 3 — LLM-generated artifacts (never edit manually after generation)
| Zone | Generated from |
|---|---|
server/src/modules/<entity>/ |
domain/*.api.dsl + prompts/backend-rules.md |
client/src/resources/<entity>/ |
domain/*.api.dsl + prompts/frontend-rules.md |
server/src/app.module.ts |
Module registrations derived from api.dsl api blocks |
client/src/App.tsx |
Resource registrations derived from api.dsl api blocks |
server/prisma/schema.prisma |
domain/*.api.dsl + prompts/prisma-rules.md |
server/src/auth/ |
prompts/auth-rules.md |
client/src/auth/ |
prompts/auth-rules.md |
client/src/dataProvider.ts |
prompts/auth-rules.md |
toir-realm.json |
prompts/auth-rules.md |
docker-compose.yml |
prompts/runtime-rules.md |
server/.env.example |
prompts/runtime-rules.md |
client/.env.example |
prompts/runtime-rules.md |
Tier 4 — handwritten / framework-managed support files
- Framework scaffold:
server/nest-cli.json,server/tsconfig*.json,client/vite.config.*, etc.
Forbidden mutations during any generation run
NEVER write to *.dsl files.
They are read-only inputs. To change the API contract or domain model, edit domain/*.api.dsl
as a separate explicit task.
NEVER manually edit files under server/src/modules/ or client/src/resources/.
To change generated code: update domain/*.api.dsl and regenerate.
NEVER edit server/prisma/schema.prisma directly.
It is LLM-generated from domain/*.api.dsl following prompts/prisma-rules.md.
Generation workflow (required sequence)
- Read
AGENTS.mdandprompts/general-prompt.md. - Read the active
api API.<EntityName>block + its DTOs + its enums fromdomain/toir.api.dsl(entity-scoped — do not inject the full DSL as a blob). - Load the companion rule files required for the active stage:
prompts/prisma-rules.mdprompts/backend-rules.mdprompts/frontend-rules.mdprompts/auth-rules.mdprompts/runtime-rules.mdprompts/validation-rules.md
- Verify or repair framework scaffolds before domain generation:
- official Nest CLI for backend workspace creation/repair
- official Vite React TypeScript CLI for frontend workspace creation/repair
- official Prisma CLI when Prisma initialization or repair is required
- Generate
server/prisma/schema.prismaperprompts/prisma-rules.md. - Generate backend modules and registrations per
prompts/backend-rules.md. - Generate frontend resources and registrations per
prompts/frontend-rules.md. - Generate auth/runtime/realm artifacts per
prompts/auth-rules.mdandprompts/runtime-rules.md. - Refresh
api-summary.jsononly when validation/tooling requires the auxiliary freshness artifact:npm run generate:api-summary. - Run:
node tools/validate-generation.mjs --artifacts-only - Run:
npm run eval:generation - Fix all failures before considering the task complete.
Context budget rule: Before generating any DTO or component, quote the field
definitions from the DSL api block verbatim, then generate from those quotes. This
prevents training-data contamination. See prompts/general-prompt.md.
Type mappings
| DSL type | Prisma type | TS DTO type | React Admin component |
|---|---|---|---|
uuid |
String @id @default(uuid()) |
string |
TextInput / TextField |
string |
String |
string |
TextInput / TextField |
text |
String |
string |
TextInput / TextField |
integer |
Int |
number |
NumberInput / NumberField |
number |
Float |
number |
NumberInput / NumberField |
decimal |
Decimal |
string |
NumberInput / NumberField |
date |
DateTime |
string |
DateInput / DateField |
boolean |
Boolean |
boolean |
(appropriate boolean input) |
| enum name | enum name | string |
SelectInput / SelectField |
Naming conventions
Resource name (plural, kebab-case):
Equipment→equipment(irregular — stays as-is)EquipmentType→equipment-typesRepairOrder→repair-orders- General: PascalCase → kebab-case → append
s(oresif ends ins; irregular cases explicit)
Default sort field (when not declared in api.dsl):
Priority: inventoryNumber > number > code > name > primary key
Verification gate (two-stage)
Stage 1 — Structural gate
node tools/validate-generation.mjs --artifacts-only
Checks: file existence, api-summary freshness, auth seam contracts, natural-key handling, realm structure, runtime contract, api.dsl coverage (backend + frontend files per entity), DTO field name coverage, DTO class-validator decorator coverage, @UseGuards presence on controllers, frontend component type correctness.
Full structural verification (requires installed node_modules):
node tools/validate-generation.mjs
Stage 2 — Eval harness (Rule 6)
npm run eval:generation
Fixture-based semantic checks from tools/eval/fixtures/. Checks: correct HTTP method decorators, Content-Range header, enum filter patterns, FK reference wiring, component type correctness, class-validator decorator patterns.
See tools/eval/README.md for fixture authoring and eval-driven development workflow.
Generation is incomplete unless both stages pass.
Pre-commit hook
Install with npm run install-hooks. The hook runs both the structural gate and
the eval harness before every commit. Commits are blocked when either fails.
Auth and runtime defaults
Full auth contract: prompts/auth-rules.md
Working defaults (do not regress to localhost):
- Keycloak base:
https://sso.greact.ru - Realm/client:
toir/toir-frontend/toir-backend - Production frontend:
https://toir-frontend.greact.ru - CORS:
http://localhost:5173,https://toir-frontend.greact.ru
OpenRouter configuration
OPENAI_API_KEY=<openrouter-key>
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=<model-id>
These variables are used by tools/api-format-to-openapi/convert.mjs --mode llm.
Reading order for generation tasks
Critical zone (load first, never drop):
AGENTS.md(this file) — project governance, mutation boundaries, tier hierarchyprompts/general-prompt.md— master orchestration prompt: mission, stage ownership, delegation model, completion criteriadomain/toir.api.dsl §API.<EntityName>— active api block only, plus its referenced DTOs and enums
Companion zone (load when the matching stage is active):
prompts/prisma-rules.md— Prisma schema generation detailsprompts/backend-rules.md— NestJS generation detailsprompts/frontend-rules.md— React Admin generation detailsprompts/auth-rules.md— auth seam and realm requirementsprompts/runtime-rules.md— scaffold, env, and bootstrap requirementsprompts/validation-rules.md— success gate requirements
Auxiliary zone (never authoritative):
api-summary.json— optional inventory/freshness artifact for validators and supporting tooling; do not use it instead of the DSL
Reference only (do not load proactively):
domain/dsl-spec.md— DSL syntax reference; load only if DSL is ambiguousdocs/generation-playbook.md— step-by-step workflow referencedocs/future-work.md— deferred items (Rules 7 and 8)