rebase generation
This commit is contained in:
MaKarin
@@ -1,97 +1,81 @@
|
||||
# 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.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Agent role summary
|
||||
## Subagent Registry
|
||||
|
||||
| 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 |
|
||||
All subagents operate under the orchestrator pattern defined in `prompts/claude-orchestration-rules.md`.
|
||||
|
||||
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.
|
||||
| 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` |
|
||||
|
||||
---
|
||||
|
||||
## Delegation model
|
||||
## Orchestration Entry Points
|
||||
|
||||
- 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.
|
||||
### CLI (TypeScript/Node)
|
||||
|
||||
---
|
||||
|
||||
## Mutation boundary map
|
||||
```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"
|
||||
```
|
||||
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)
|
||||
### From Claude Code (programmatic)
|
||||
|
||||
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
|
||||
```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
|
||||
@@ -109,51 +93,56 @@ Tier 4 — Framework-managed support files
|
||||
|
||||
## 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`.
|
||||
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
|
||||
|
||||
- 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.
|
||||
For approved stack version policy and dependency pinning, see:
|
||||
- `AGENTS.md` §Approved Stack Version Policy (lines 77–96)
|
||||
|
||||
---
|
||||
|
||||
## Standard generation invocation
|
||||
## 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
|
||||
# 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
|
||||
# 6. Integrate, validate, and send to reviewer
|
||||
# 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)
|
||||
## MCP Servers (Project-Local)
|
||||
|
||||
Defined in `.claude/config.toml`:
|
||||
Defined in `.claude/config.toml`. All subagents have access:
|
||||
|
||||
- **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
|
||||
- **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
|
||||
|
||||
Add heavier or credential-backed servers in `~/.claude/config.toml`.
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user