182 lines
7.0 KiB
Markdown
182 lines
7.0 KiB
Markdown
# Claude Code — KIS-TOiR workspace supplement
|
|
|
|
This file supplements the repository root `AGENTS.md` with Claude-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 bounded sub-tasks and 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 — Codex-specific supplement
|
|
.claude/CLAUDE.md (this file) — 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 `.claude/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 `~/.claude/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.
|