greact-admin/toir-light
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

git init

Browse Source
This commit is contained in:
MaKarin
2026-04-03 20:54:37 +03:00
commit c89c23fd1d
50 changed files with 6716 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
.codex/AGENTS.md Normal file
View File

@@ -0,0 +1,108 @@
# 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.

10
.codex/agents/docs-researcher.toml Normal file
View File

@@ -0,0 +1,10 @@
model = "anthropic/claude-sonnet-4.5"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
developer_instructions = """
Verify APIs, framework behavior, and release-note claims against primary documentation before changes land.
Cite the exact docs or file paths that support each claim.
Do not invent undocumented behavior.
Use Context7 and official docs first when the current environment exposes them.
"""

23
.codex/agents/explorer.toml Normal file
View File

@@ -0,0 +1,23 @@
model = "anthropic/claude-haiku-4.5"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode. Read files freely; write nothing.
Trace the real execution path, cite files and symbols, and avoid proposing
fixes unless the parent agent asks for them.
Prefer targeted search and file reads over broad scans.
KIS-TOiR source-of-truth tier reference (read-only for this agent):
Tier 1: domain/*.api.dsl, prompts/*.md, AGENTS.md
Tier 2: api-summary.json (deterministic auxiliary derivative; never authoritative)
Tier 3: server/src/modules/, client/src/resources/, server/src/app.module.ts,
client/src/App.tsx, server/prisma/schema.prisma, server/src/auth/,
client/src/auth/, client/src/dataProvider.ts, toir-realm.json,
docker-compose.yml, server/.env.example, client/.env.example
Tier 4: framework scaffold and other handwritten support files
When asked about generation output, always trace it back to its Tier 1 DSL source
and do not recommend api-summary.json as the primary input when the DSL is available.
"""

51
.codex/agents/generator.toml Normal file
View File

@@ -0,0 +1,51 @@
model = "anthropic/claude-opus-4.6"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
developer_instructions = """
You are the LLM generation agent for KIS-TOiR.
PERMITTED write zones (Tier 3 — LLM-generated artifacts):
server/src/modules/<entity>/ — NestJS modules, controllers, services, DTOs
client/src/resources/<entity>/ — React Admin List/Create/Edit/Show
server/src/app.module.ts — module registration section only
client/src/App.tsx — resource registration section only
server/prisma/schema.prisma — LLM-generated per prompts/prisma-rules.md
server/src/auth/ — auth artifacts per prompts/auth-rules.md
client/src/auth/ — auth artifacts per prompts/auth-rules.md
client/src/dataProvider.ts — authenticated data provider seam per prompts/auth-rules.md
toir-realm.json — realm artifact per prompts/auth-rules.md
docker-compose.yml — runtime artifact per prompts/runtime-rules.md
server/.env.example — runtime defaults per prompts/runtime-rules.md
client/.env.example — runtime defaults per prompts/runtime-rules.md
FORBIDDEN write zones — never modify these files:
domain/*.api.dsl — source of truth (Tier 1)
prompts/*.md — generation spec (Tier 1)
AGENTS.md — workflow contract (Tier 1)
api-summary.json — deterministic derivative (Tier 2)
tools/ — deterministic tooling, not generated artifacts
CONTEXT BUDGET (mandatory):
1. Read prompts/general-prompt.md first.
2. Read ONLY the entity-scoped api.dsl block (api API.<EntityName> + its DTOs + enums)
from domain/toir.api.dsl. Do NOT inject the full api.dsl as a blob.
3. Read ONLY the relevant companion rule file for the active stage.
4. Before generating any DTO or component, quote the relevant DSL field definitions
verbatim, then generate from those quotes. This prevents training-data contamination.
5. Use api-summary.json only as an auxiliary inventory or validator-related artifact,
never as the source of truth or default starting point.
GENERATION WORKFLOW:
1. Read prompts/general-prompt.md.
2. Read the entity-scoped block from domain/toir.api.dsl.
3. Read the relevant stage rule docs.
4. Generate or update Tier 3 artifacts.
5. Refresh api-summary.json only if the validator/tooling requires it.
6. Run: node tools/validate-generation.mjs --artifacts-only
7. Run: npm run eval:generation
8. Fix all failures before reporting complete.
NEVER report generation complete if either validation gate fails.
"""

32
.codex/agents/reviewer.toml Normal file
View File

@@ -0,0 +1,32 @@
model = "anthropic/claude-sonnet-4.5"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Review mode. You may propose changes as text patches but must not write files directly.
Focus on:
- Correctness: does generated code match the api.dsl and prompt contracts?
- Security: auth guard placement, CORS, env variable handling.
- Regression: do both verification gates pass?
node tools/validate-generation.mjs --artifacts-only
npm run eval:generation
- DSL fidelity: do generated DTOs contain all fields declared in DTO.<Entity>Create/Update?
- Decorator coverage: does each DTO field have the correct class-validator decorator?
- Frontend type correctness: does each field use the correct React Admin component?
- Prompt-architecture consistency: if prompts/configs changed, is domain/toir.api.dsl still clearly authoritative and api-summary.json still clearly auxiliary?
KIS-TOiR mutation boundary (reviewer must not write to these zones):
FORBIDDEN writes: domain/*.api.dsl, prompts/*.md, AGENTS.md,
api-summary.json, tools/, server/prisma/schema.prisma
ALLOWED proposal targets (propose patches, not direct writes):
server/src/modules/<entity>/ — backend artifacts
client/src/resources/<entity>/ — frontend artifacts
server/src/app.module.ts, client/src/App.tsx — registrations
server/src/auth/, client/src/auth/ — auth artifacts
client/src/dataProvider.ts — authenticated data provider seam
toir-realm.json, docker-compose.yml — runtime/realm artifacts
server/.env.example, client/.env.example — runtime defaults
docs/ — documentation updates
"""

141
.codex/config.toml Normal file
View File

@@ -0,0 +1,141 @@
#:schema https://developers.openai.com/codex/config-schema.json
# Everything Claude Code (ECC) — Codex Reference Configuration
#
# Copy this file to ~/.codex/config.toml for global defaults, or keep it in
# the project root as .codex/config.toml for project-local settings.
#
# Official docs:
# - https://developers.openai.com/codex/config-reference
# - https://developers.openai.com/codex/multi-agent
# Model selection
# This project intentionally pins a project-local provider + model so the same
# orchestration, MCP servers, and sub-agents run through OpenRouter + Claude.
# Paste your OpenRouter token directly below if you do not want to use env vars.
model_provider = "openrouter"
model = "anthropic/claude-sonnet-4.5"
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
# Paste your token here:
# experimental_bearer_token = "or-xxxxxxxxxxxxxxxxxxxxxxxx"
experimental_bearer_token = "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"
wire_api = "responses"
requires_openai_auth = false
[model_providers.openrouter.http_headers]
# Optional but recommended by OpenRouter for app attribution.
HTTP-Referer = "https://local.kis-toir"
X-Title = "KIS-TOiR"
# Top-level runtime settings (current Codex schema)
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "live"
# External notifications receive a JSON payload on stdin.
# macOS example (uncomment on Mac if `terminal-notifier` is installed):
# notify = [
# "terminal-notifier",
# "-title", "Codex KIS",
# "-message", "Task completed!",
# "-sound", "default",
# ]
# Persistent instructions are appended to every prompt (additive, unlike
# model_instructions_file which replaces AGENTS.md).
persistent_instructions = "Follow project AGENTS.md guidelines. Use available MCP servers when they can help."
# model_instructions_file replaces built-in instructions instead of AGENTS.md,
# so leave it unset unless you intentionally want a single override file.
# model_instructions_file = "/absolute/path/to/instructions.md"
# MCP servers
# Keep the default project set lean. API-backed servers inherit credentials from
# the launching environment or can be supplied by a user-level ~/.codex/config.toml.
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
startup_timeout_sec = 30
[mcp_servers.context7]
command = "npx"
# Canonical Codex section name is `context7`; the package itself remains
# `@upstash/context7-mcp`.
args = ["-y", "@upstash/context7-mcp@latest"]
startup_timeout_sec = 30
[mcp_servers.exa]
url = "https://mcp.exa.ai/mcp"
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]
startup_timeout_sec = 30
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest", "--extension"]
startup_timeout_sec = 30
[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
startup_timeout_sec = 30
# Additional MCP servers (uncomment as needed):
# [mcp_servers.supabase]
# command = "npx"
# args = ["-y", "supabase-mcp-server@latest", "--read-only"]
#
# [mcp_servers.firecrawl]
# command = "npx"
# args = ["-y", "firecrawl-mcp"]
#
# [mcp_servers.fal-ai]
# command = "npx"
# args = ["-y", "fal-ai-mcp-server"]
#
# [mcp_servers.cloudflare]
# command = "npx"
# args = ["-y", "@cloudflare/mcp-server-cloudflare"]
[features]
# Codex multi-agent collaboration is stable and on by default in current builds.
# Keep the explicit toggle here so the repo documents its expectation clearly.
multi_agent = true
# Profiles — switch with `codex -p <name>`
[profiles.strict]
approval_policy = "on-request"
sandbox_mode = "read-only"
web_search = "cached"
[profiles.yolo]
approval_policy = "never"
sandbox_mode = "workspace-write"
web_search = "live"
[agents]
# Multi-agent role limits and local role definitions.
# These map to `.codex/agents/*.toml` and mirror the repo's explorer/reviewer/docs workflow.
max_threads = 6
max_depth = 1
[agents.explorer]
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
config_file = "agents/explorer.toml"
[agents.reviewer]
description = "PR reviewer focused on correctness, security, and DSL fidelity. Proposes patches; writes nothing directly."
config_file = "agents/reviewer.toml"
[agents.docs_researcher]
description = "Documentation specialist that verifies APIs, framework behavior, and release notes."
config_file = "agents/docs-researcher.toml"
[agents.generator]
description = "LLM generation agent: writes server/src/modules/, client/src/resources/, app.module.ts, App.tsx only. Never touches DSL, prompts, or deterministic tooling."
config_file = "agents/generator.toml"