228 lines
13 KiB
Markdown
228 lines
13 KiB
Markdown
# 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
|
|
|
|
---
|