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	Write boundary
`generator`	`agents/generator.toml`	workspace-write	Tier 3 generation zones
`explorer`	`agents/explorer.toml`	read-only	None
`reviewer`	`agents/reviewer.toml`	read-only	Proposes patches only
`docs_researcher`	`agents/docs-researcher.toml`	read-only	None

Use /agent generator for implementation work. Use /agent explorer first for discovery, /agent docs_researcher when framework or prompt patterns need verification, and /agent reviewer before claiming a generation run is complete.

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

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 (written ONLY by generator agent)
  server/src/modules/<entity>/
  client/src/resources/<entity>/
  server/src/app.module.ts
  client/src/App.tsx
  server/prisma/schema.prisma   ← LLM-generated per prompts/prisma-rules.md
  server/src/auth/
  client/src/auth/
  client/src/dataProvider.ts
  toir-realm.json
  docker-compose.yml
  server/.env.example
  client/.env.example

Tier 4 — Handwritten / framework-managed support files
  framework scaffold and other manual support files outside prompt-governed outputs

Standard generation invocation

# 1. Read AGENTS.md + prompts/general-prompt.md
# 2. Read the entity-scoped DSL block from domain/toir.api.dsl
# 3. Load only the stage-specific companion rules you need
# 4. Run generation or repair with the appropriate agent
# 5. Refresh api-summary.json only if validator/tooling expects the auxiliary freshness artifact
# 6. Verify (both stages must pass)
node tools/validate-generation.mjs --artifacts-only
npm run eval:generation

MCP servers (project-local)

Defined in .codex/config.toml:

github — repository access
context7 — library documentation lookup (use for framework questions)
exa — web search
memory — persistent cross-session context
playwright — browser automation for smoke tests
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.

Security notes

Never commit secrets. Use environment variables from .env.example templates.
Run npm audit when adding new dependencies to server/ or client/.
Auth contracts live in prompts/auth-rules.md. Do not deviate from them.

3.5 KiB Raw Blame History