# 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

---