toir-automatization/.claude/CLAUDE.md

Claude Code — KIS-TOiR workspace supplement

This file supplements the repository root AGENTS.md with Claude Code-specific operational notes.

Architecture: Subagents are defined programmatically in agents/definitions.ts using Claude Agent SDK. Agent instructions are loaded from .claude/agents/*.toml config files at invocation time.

---

Subagent Registry

All subagents operate under the orchestrator pattern defined in prompts/claude-orchestration-rules.md.

Agent	Description	Sandbox	Model	Config
explorer	Codebase discovery & exploration	read-only	haiku	.claude/agents/explorer.toml
docs_researcher	Framework docs verification	read-only	haiku	.claude/agents/docs-researcher.toml
generator_prisma	Prisma schema generation	workspace-write	opus	.claude/agents/generator_prisma.toml
generator_nest_resources	NestJS backend generation	workspace-write	opus	.claude/agents/generator_nest_resources.toml
generator_react_admin_resources	React Admin generation	workspace-write	opus	.claude/agents/generator_react_admin_resources.toml
generator_data_access	Frontend data-access integration	workspace-write	opus	.claude/agents/generator_data_access.toml
reviewer	Final review & validation	read-only	sonnet	.claude/agents/reviewer.toml

---

Orchestration Entry Points

CLI (TypeScript/Node)

# Use the orchestrator directly
npx ts-node tools/orchestrator.ts "Your generation task"

# Add to package.json for convenience
npm run orchestrate "Your task"

From Claude Code (programmatic)

import orchestrate from './tools/orchestrator';
await orchestrate("Generate Prisma schema from domain/toir.api.dsl");

How Subagents Are Invoked

1. Orchestrator (main agent) reads task and frozen contract

2. Agent SDK reads subagent descriptions from agents/definitions.ts

3. Claude matches intent to description → "generate schema" → generator_prisma

4. Agent tool invokes matching subagent with:

   • Agent-specific instructions (from .claude/agents/*.toml)
   • Frozen contract & relevant DSL context
   • Sandbox restrictions (read-only vs. workspace-write)
   • Available MCP servers

5. Subagent executes bounded task and returns result

6. Orchestrator examines output for write-zone compliance + contract adherence

7. Orchestrator explicitly accepts or rejects the output

---

Delegation Model

Full details in prompts/claude-orchestration-rules.md — read this file when delegating.

• Shallow delegation only: one primary responsibility per subagent
• Orchestrator owns: discovery, docs verification, contract freeze, shared scaffold, auth skeleton, deploy skeleton, integration, validation, final handoff
• Generators own: bounded feature-layer artifacts only (Prisma, NestJS modules, React Admin resources, data-access)
• Shared seams stay parent-owned: orchestrator manages app.module.ts, App.tsx, auth/, runtime/, deploy/ integration even when generators produce resource-aware bindings

Write-Zone Enforcement

Authoritative source: AGENTS.md §Source-of-truth hierarchy (lines 17–76)

For detailed write-zone enforcement and acceptance protocols specific to Claude Code orchestration, see:

• prompts/claude-orchestration-rules.md §Write-Zone Enforcement
• prompts/claude-orchestration-rules.md §Acceptance Protocol

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

For runtime and deploy contract definition, see:

• AGENTS.md §Runtime / Deploy Contract (lines 71–75)
• docs/completion-contract.md — operational definition of done

Version Policy

For approved stack version policy and dependency pinning, see:

• AGENTS.md §Approved Stack Version Policy (lines 77–96)

---

Standard Generation Invocation

# Full-generation mode: start from Tier 1 inputs only
# 1. Read AGENTS.md + prompts/general-prompt.md + prompts/claude-orchestration-rules.md
# 2. Use explorer for discovery, docs_researcher for framework verification
# 3. Freeze structured contract and write-zones
# 4. Recreate or repair official CLI scaffolds
# 5. Launch specialized generators after contract freeze via orchestrator
# 6. Integrate accepted outputs, run validation gates, send to reviewer

# Run orchestrator
npx ts-node tools/orchestrator.ts "Full-generation task: [details]"

# Verify completion
node tools/validate-generation.mjs --artifacts-only
npm run eval:generation

---

MCP Servers (Project-Local)

Defined in .claude/config.toml. All subagents have access:

• github — repository context & PR history
• context7 — official NestJS, Prisma, React Admin, Vite, Docker, Keycloak/OIDC docs
• exa — web search for current behavior, release notes, breaking changes
• memory — persistent cross-session notes (use sparingly)
• playwright — browser automation for UI/runtime verification
• sequential-thinking — structured multi-step reasoning for complex investigations

Tool-order policy (all agents):

1. Local authoritative files (domain/.api.dsl, prompts/.md, AGENTS.md)
2. Context7 official docs
3. Web search (exa)
4. Validation gates

Add credential-backed servers in ~/.claude/config.toml if needed.

---

Validation gate

Run before every commit and after every generation:

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