# 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.