Codex CLI — KIS-TOiR workspace supplement

This file supplements the repository root AGENTS.md with Codex-specific operational notes. The root AGENTS.md is the authoritative contract — if anything here contradicts root, root wins.

Agent role summary

Role	Config file	Sandbox	Primary responsibility
`explorer`	`agents/explorer.toml`	read-only	Discovery only
`docs_researcher`	`agents/docs-researcher.toml`	read-only	Official docs only
`generator_prisma`	`agents/generator_prisma.toml`	workspace-write	Prisma schema only
`generator_nest_resources`	`agents/generator_nest_resources.toml`	workspace-write	Nest resource layer
`generator_react_admin_resources`	`agents/generator_react_admin_resources.toml`	workspace-write	React Admin resources
`generator_data_access`	`agents/generator_data_access.toml`	workspace-write	Frontend data access
`reviewer`	`agents/reviewer.toml`	read-only	Final review only

Use explorer first for discovery, docs_researcher for framework verification, the specialized generators only after contract freeze, and reviewer only after integration and validation. The old broad generator role is removed from the normal full-generation workflow.

Delegation model

Shallow delegation only: keep max_depth = 1 and bounded sub-tasks.
One primary responsibility per sub-agent.
Parent owns discovery orchestration, docs verification, contract freeze, shared scaffold, auth platform skeleton, deploy/runtime skeleton, integration, validation, and reviewer handoff.
Feature/resource generation must be delegated to specialized generators before the parent falls back to manual implementation.
Shared seams stay parent-owned even when resource generators attach resource-aware bindings inside their delegated zones.

Mutation boundary map

Tier 1 — Source of truth (NEVER written by any agent)
  domain/*.api.dsl              — single source of truth for all generation
  prompts/*.md                  — generation spec / rules
  AGENTS.md                     — agent operating rules
  .codex/AGENTS.md (this file)  — Codex-specific supplement
  .claude/CLAUDE.md             — Claude-specific supplement

Tier 2 — Deterministic derivatives (written only by npm scripts, not by agents)
  api-summary.json              ← npm run generate:api-summary
  openapi.json                  ← npm run generate:openapi  (auxiliary)

Tier 3 — LLM-generated artifacts (ownership split by bounded role)
  Parent-owned shared seams:
    server/src/auth/
    client/src/auth/
    toir-realm.json
    docker-compose.yml
    server/Dockerfile
    client/Dockerfile
    client/nginx/default.conf
    server/docker-entrypoint.sh
    db-seed/Dockerfile
    db-seed/import.sh
    server/.env.example
    client/.env.example

  Specialized generators:
    generator_prisma
      server/prisma/schema.prisma

    generator_nest_resources
      server/src/modules/<entity>/
      server/src/app.module.ts (only when explicitly delegated)

    generator_react_admin_resources
      client/src/resources/<entity>/
      client/src/App.tsx (only when explicitly delegated)

    generator_data_access
      client/src/dataProvider.ts
      narrowly delegated frontend integration seams only when explicitly delegated

  Note: these Tier 3 outputs may be absent at the start of a repo-wide full
  regeneration run. Their absence is expected until CLI scaffolding and
  generation recreate them from Tier 1 inputs.

Tier 4 — Framework-managed support files
  framework scaffold and Prisma CLI-managed migrations outside prompt-governed outputs

Contract freeze and acceptance

Parent must freeze a normalized structured contract before specialized generation starts.
Each delegated task must include explicit write-zones, expected outputs, and non-goals.
Parent accepts delegated output only if allowed zones were respected, the frozen contract still holds, no cross-layer edits leaked, and the result is integration-ready.
Allow at most one bounded repair pass before explicit rejection.
Manual fallback is allowed only after rejection, not as a silent continuation of partial delegated work.

Runtime / Deploy Contract

Tier 3 runtime/deploy outputs are first-class generation targets and must be regenerated or repaired from the companion rules when they drift.
Tier 4 support files are framework-managed rather than hand-authored sources of truth.
Runtime/deploy readiness is part of completion, not an optional follow-up.

Completion is defined in docs/completion-contract.md.

Version Policy

The approved stack version policy lives in root AGENTS.md and the companion prompt docs.
After CLI scaffold creation or repair, normalize package manifests back to the approved exact versions before generation continues.
Do not leave latest, caret ranges, or unreviewed major-version upgrades in regenerated manifests.
Treat a Prisma v6 -> v7 move as an explicit migration task, not as a routine dependency refresh.

Standard generation invocation

# 0. In full-regeneration mode, begin without relying on existing Tier 3 outputs
# 1. Read AGENTS.md + prompts/general-prompt.md
# 2. Use explorer for discovery and docs_researcher for official verification
# 3. Freeze the structured contract and delegated write-zones
# 4. Recreate or repair official CLI scaffolds
# 5. Launch specialized generators after contract freeze
# 6. Integrate, validate, and send to reviewer
node tools/validate-generation.mjs --artifacts-only
npm run eval:generation

MCP servers (project-local)

Defined in .codex/config.toml:

github — repository access when PR/repo context matters
context7 — primary library documentation lookup
exa — current web search fallback
memory — persistent cross-session context, sparingly
playwright — browser automation only when UI/runtime verification needs it
sequential-thinking — structured multi-step reasoning

Add heavier or credential-backed servers in ~/.codex/config.toml.

Validation gate

Run before every commit and after every generation:

# Stage 1 — structural gate
node tools/validate-generation.mjs --artifacts-only

# Stage 2 — eval harness
npm run eval:generation

The pre-commit hook (tools/hooks/pre-commit) runs both stages automatically after npm run install-hooks.