109 lines
3.5 KiB
Markdown
109 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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.
|