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

```bash
# 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)

```typescript
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

```bash
# 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:

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