171 lines
6.4 KiB
Markdown
171 lines
6.4 KiB
Markdown
# 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.
|