GREACT/toir-automatization
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
aab7bfa6917a40bf0f5438bf61ec2a7fae1c0237
toir-automatization/.claude/REFERENCE_TABLES.md
MaKarin aab7bfa691 rebase generation
2026-04-07 19:40:41 +03:00

13 KiB
Raw Blame History

KIS-TOiR Reference Tables

For Quick Lookup During Generation

This file consolidates the key reference tables from AGENTS.md and companion prompts. Use this as a quick lookup; for authoritative details, refer to the source documents.

Subagent Registry

Agent Purpose Sandbox Model Entry Point When to Use
explorer Codebase discovery read-only haiku .claude/agents/explorer.toml First, to understand current state
docs_researcher Framework docs verification read-only haiku .claude/agents/docs-researcher.toml Before designing shared seams
generator_prisma Prisma schema generation workspace-write opus .claude/agents/generator_prisma.toml After contract freeze, for schema only
generator_nest_resources NestJS backend generation workspace-write opus .claude/agents/generator_nest_resources.toml After contract freeze, for modules only
generator_react_admin_resources React Admin generation workspace-write opus .claude/agents/generator_react_admin_resources.toml After contract freeze, for resources only
generator_data_access Frontend data-access integration workspace-write opus .claude/agents/generator_data_access.toml After contract freeze, for dataProvider only
reviewer Final review & validation read-only sonnet .claude/agents/reviewer.toml Last, after integration and validation

Key Rule: Use agents in this order: explorer → docs_researcher → contract freeze → specialized generators → integration → validation → reviewer.

Critical: Do not manually name agents. Instead, describe your task clearly; Claude will match intent to agent description and invoke automatically via the Agent tool.

Write-Zone Enforcement

Allowed Write Zones (per Agent):

Agent Allowed Forbidden
generator_prisma server/prisma/schema.prisma Everything else
generator_nest_resources server/src/modules/<entity>/ (optionally server/src/app.module.ts when explicitly delegated) server/src/auth/, client/**, prisma, docker-compose.yml, Dockerfile, .env, prompts/, domain/*.api.dsl, tools/
generator_react_admin_resources client/src/resources/<entity>/ client/src/auth/, client/src/dataProvider.ts, server/**, docker-compose.yml, all deploy/auth/prompts/domain/tools
generator_data_access Narrowly delegated parts of client/src/dataProvider.ts only Broad dataProvider rewrites, client/src/resources/**, server/**, client/src/auth/, auth, deploy, prompts
reviewer READ-ONLY (may propose patches, not write) No write permission on any file

Parent-Owned Zones (Never Delegated):

  • server/src/auth/, client/src/auth/
  • docker-compose.yml, server/Dockerfile, client/Dockerfile, client/nginx/default.conf
  • server/.env.example, client/.env.example, toir-realm.json
  • prompts/, AGENTS.md, domain/, tools/

Enforcement Rule: If a generator touches outside its allowed zones, reject it explicitly. Quote the specific violation. Allow one bounded repair. If it still violates, use manual fallback.

Approved Stack Versions

Runtime Baseline (All Stages):

  • Node.js: 22.12.0 or newer within the Node 22 LTS line
  • Package manager: npm only, with committed package-lock.json

Backend Baseline (Stages D & E):

  • @nestjs/common, @nestjs/core, @nestjs/platform-express, @nestjs/testing: 11.1.18
  • @nestjs/config: 4.0.3
  • @nestjs/cli: 11.0.17
  • @nestjs/schematics: 11.0.10
  • prisma and @prisma/client: 6.16.2 (must be same version)
  • class-validator: 0.15.1
  • class-transformer: 0.5.1
  • jose: 6.2.2
  • reflect-metadata: 0.2.2
  • rxjs: 7.8.1
  • TypeScript: 5.7.3

Frontend Baseline (Stages D & E):

  • react and react-dom: 19.2.4
  • react-admin and ra-data-simple-rest: 5.14.5
  • @mui/material and @mui/icons-material: 7.3.9
  • @emotion/react: 11.14.0
  • @emotion/styled: 11.14.1
  • vite: 8.0.3
  • @vitejs/plugin-react: 6.0.1
  • TypeScript: 5.9.3
  • keycloak-js: 26.2.3

Version Rules:

  • After official CLI scaffolding, immediately normalize package.json to these exact versions before domain generation starts
  • prisma and @prisma/client must always remain on the same exact version
  • Do not upgrade Prisma from v6 to v7 during routine generation (separate explicit migration task)
  • Do not use latest, caret ranges, or unreviewed major bumps

Generation Roadmap (8 Stages)

Stage Responsible Task Input Output
A. Discovery Orchestrator + explorer + docs_researcher Understand current state, scaffold health, local seams AGENTS.md, general-prompt.md, domain/toir.api.dsl Entity-scoped DSL quotes, clean stage plan, traced seams
B. Docs Verification Orchestrator + docs_researcher Verify framework behavior before planning Discovery findings, relevant prompts, Context7 docs Verified framework constraints, version-sensitive notes
C. Contract Freeze Orchestrator only Normalize DSL + prompts into bounded handoff Entity-scoped DSL, prompt docs, discovery findings Structured contract (entities, fields, types, endpoints, naming, write-zones)
D. Shared Platform Scaffold Orchestrator + explorer/docs_researcher Create/repair shared framework scaffolds, auth skeleton, deploy skeleton Frozen contract, auth-rules.md, runtime-rules.md server/ and client/ from official CLIs, auth platform, deploy skeleton, env/runtime conventions
E. Parallel Specialized Generation Orchestrator delegates to generators Generate bounded feature-layer artifacts Frozen contract, stage-specific prompts Prisma schema, NestJS modules, React Admin resources, dataProvider
F. Integration Orchestrator only Wire accepted outputs into shared platform Accepted generator outputs, auth-rules.md, runtime-rules.md Final shared wiring, no unresolved cross-layer drift
G. Validation Orchestrator + relevant generator (one repair pass) Prove run is complete, not merely plausible validation-rules.md, validation gate output Passing structural gate (validate-generation.mjs) + semantic gate (npm run eval:generation)
H. Final Review Orchestrator + reviewer Final correctness, security, test-gap review Validated integrated output, reviewer findings Reviewer signoff or blocking findings

Critical Rules:

  • Stages are sequential (A → B → C → D → E → F → G → H); do not skip stages
  • Generators start only after contract freeze (Stage C)
  • Validation gates (Stage G) are proof of completion, not optional
  • No stage is complete until its expected outputs are produced
  • Two gates must pass: node tools/validate-generation.mjs --artifacts-only AND npm run eval:generation

Mandatory Delegation Phases (Claude Code)

Phase When Who Key Actions
Phase 1: Discovery & Docs Verification At session start Orchestrator + explorer + docs_researcher Scan repo state, verify scaffold health, confirm framework behavior
Phase 2: Contract Freeze After discovery, before any generator Orchestrator only Extract DSL, read prompts, produce normalized contract with explicit write-zones
Phase 3: Parallel Specialized Generation After contract freeze Orchestrator delegates to generators Invoke generators in parallel (safe zones), receive outputs
Phase 4: Acceptance & Integration After each generator Orchestrator Check write-zones + contract adherence, explicit accept or reject, allow one repair, integrate accepted outputs
Phase 5: Validation & Final Review After integration Orchestrator + validators + reviewer Run both gates, diagnose failures, allow one bounded repair, hand off to reviewer for signoff

Acceptance Checklist:

  • ✅ Only allowed write-zones changed
  • ✅ No cross-layer edits outside delegated zone
  • ✅ Output matches frozen contract
  • ✅ Output is integration-ready
  • ✅ No unresolved issues

MCP Tool Access

Server Use For When Agents
github PR context, repo history, issue links When parent needs remote context All agents
context7 Official docs (NestJS, Prisma, React Admin, Vite, Docker, nginx, Keycloak/OIDC/JWT) Before framework-sensitive planning All agents
exa Web search for current behavior, release notes, breaking changes Only after Context7 is insufficient All agents
memory Persistent cross-session notes For durable repo context only (use sparingly) All agents
playwright Browser automation for UI/runtime verification When read-only code inspection insufficient All agents
sequential-thinking Structured multi-step reasoning For ambiguous conflicts or multi-finding investigations All agents

Tool-Order Policy (Golden Rule):

  1. Local authoritative files (domain/.api.dsl, prompts/.md, AGENTS.md)
  2. Context7 official docs
  3. Web fallback (exa)
  4. Validation gates

Success Criteria (All Must Pass)

Tier 1: Infrastructure Readiness

  • ✅ server/ exists and builds successfully (npm run build)
  • ✅ client/ exists and builds successfully (npm run build)
  • ✅ node tools/validate-generation.mjs --artifacts-only passes
  • ✅ Required scaffold files present (NestJS/Vite essentials)
  • ✅ Runtime/deploy baseline files present: docker-compose.yml, Dockerfiles, nginx, env templates, realm
  • ✅ Package manifests normalized to approved exact versions

Tier 2: Domain Fidelity

  • ✅ npm run eval:generation passes (DSL fidelity, CRUD behavior, UX invariants)
  • ✅ DTOs match DSL shapes exactly
  • ✅ Controllers have correct guards and roles
  • ✅ React Admin resources use type-correct components
  • ✅ Natural-key handling correct
  • ✅ Prisma schema reflects DSL without manual edits
  • ✅ Eval contracts not silently rewritten

Tier 3: Runtime/Deploy Readiness

  • ✅ Dockerfiles exist and are valid
  • ✅ nginx config supports SPA routing and /api proxying
  • ✅ Compose topology: postgres, server, db-seed, client (Keycloak external)
  • ✅ Env examples align with auth/runtime contracts
  • ✅ Realm artifact matches frontend/backend expectations

Tier 4: Auth Seam Integrity

  • ✅ JWKS resolution works
  • ✅ Role extraction from realm_access.roles
  • ✅ /health remains public
  • ✅ 401/403 semantics correct

Type Mappings (DSL → Prisma → TS → React Admin)

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 Names (Plural, Kebab-Case):

  • Equipment → equipment (irregular — stays as-is)
  • EquipmentType → equipment-types
  • RepairOrder → repair-orders
  • General rule: PascalCase → kebab-case → append s (or es if ends in s)

Default Sort Field (When Not Declared in DSL):

  • Priority: inventoryNumber > number > code > name > primary key

Quick Troubleshooting

Symptom Likely Cause Fix
Build fails, missing files Scaffold degraded Run official CLI repair, then regenerate domain
Eval fails on DTO shapes DSL mismatch Re-read DSL, regenerate affected artifacts
Generator edits unauthorized zones Contract violation Reject, allow one repair, manual fallback if still fails
Eval fails on guards/Content-Range Guard order or header issue Fix guard order (JwtAuthGuard first), ensure Content-Range: items, re-run evals
Prisma schema invalid Missing relation annotation Add explicit @relation(fields: [...], references: [...])
Validation gate fails Artifact drift or missing file Run gate, diagnose, allow one bounded repair, or flag for manual review
Version pins floating Manifest not normalized Pin to approved exact versions from this table after scaffold creation

Source of Authority: AGENTS.md (root), prompts/general-prompt.md, prompts/claude-orchestration-rules.md Last Updated: 2026-04-07 For Detailed Guidance: See corresponding documents listed above

Reference in New Issue View Git Blame Copy Permalink