git init
This commit is contained in:
MaKarin
181
.codex/AGENTS.md
Normal file
181
.codex/AGENTS.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```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`.
|
||||
|
||||
Completion is defined in `docs/completion-contract.md`.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user