GREACT/toir-automatization
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rebase generation

Browse Source
This commit is contained in:
MaKarin
2026-04-07 19:40:41 +03:00
parent 73ddb1a948
commit aab7bfa691
180 changed files with 15512 additions and 364 deletions
Download Patch File Download Diff File Expand all files Collapse all files

390
prompts/claude-orchestration-rules.md Normal file
View File

@@ -0,0 +1,390 @@
# Claude Code Orchestration & Subagent Management Rules
**For Claude Code agents coordinating KIS-TOiR generation. This file is mandatory when delegating to subagents.**
This document complements `AGENTS.md` with Claude-specific patterns and MCP/subagent governance.
---
## Subagent Model
KIS-TOiR uses **Claude Agent SDK subagents** — specialized agents defined programmatically in `agents/definitions.ts` and coordinated via `tools/orchestrator.ts`.
### Subagent Registry
All subagents:
- Load instructions from `.claude/agents/*.toml` configuration files
- Share access to project-local MCP servers (github, context7, exa, memory, playwright, sequential-thinking)
- Operate under strict write-zone enforcement
- Report results back to the orchestrator for acceptance/rejection
| Agent | Purpose | Sandbox | Model |
|-------|---------|---------|-------|
| `explorer` | Codebase discovery & exploration | read-only | haiku |
| `docs_researcher` | Framework docs verification | read-only | haiku |
| `generator_prisma` | Prisma schema generation | workspace-write | opus |
| `generator_nest_resources` | NestJS backend generation | workspace-write | opus |
| `generator_react_admin_resources` | React Admin generation | workspace-write | opus |
| `generator_data_access` | Frontend data-access integration | workspace-write | opus |
| `reviewer` | Final artifact review | read-only | sonnet |
### How Agents Are Invoked
Subagents are **not manually called by name**. Instead:
1. **Claude reads agent descriptions** from `agents/definitions.ts`
2. **Claude matches task intent to agent description** — e.g., "generate the Prisma schema" → matches `generator_prisma`
3. **Claude invokes via the `Agent` tool** — which must be in `allowedTools`
4. **Subagent receives full prompt context** — including frozen contract, DSL, and sandbox restrictions
**Example trigger pattern:**
```
"The frozen contract specifies these entities: [DSL slice].
Use the generator_prisma agent to generate server/prisma/schema.prisma."
```
Claude will automatically recognize `generator_prisma` and invoke it with its bounded instructions.
---
## Orchestrator Responsibilities
The **orchestrator** (main Claude agent running in Claude Code) owns:
1. **Discovery** — Use `explorer` to understand current workspace state
2. **Docs Verification** — Use `docs_researcher` to verify framework behavior
3. **Contract Freeze** — Produce explicit normalized contract before generator delegation
4. **Specialized Delegation** — Delegate bounded work to each generator after contract freeze
5. **Acceptance/Rejection** — Explicit accept/reject of delegated outputs based on:
- Write-zone compliance (did it only touch allowed files?)
- Contract adherence (does output match frozen contract?)
- Integration readiness (is it ready for parent integration?)
6. **Integration** — Wire accepted outputs into shared platform seams
7. **Validation** — Run both gates before claiming completion:
- `node tools/validate-generation.mjs --artifacts-only`
- `npm run eval:generation`
8. **Final Review** — Hand off to `reviewer` agent only after validation passes
---
## Mandatory Delegation Workflow
### Phase 1: Discovery & Docs Verification
**Who:** Orchestrator + `explorer` + `docs_researcher`
**When:** At session start, before any generation planning
**Triggers:**
```
"Use the explorer agent to scan the repository structure and identify:
- Current workspace state (do server/ and client/ exist?)
- Existing registrations in app.module.ts and App.tsx
- Current schema.prisma and data layer shape
- Existing auth/runtime/deploy artifacts"
```
**Expected output:**
- Clear picture of what exists and what is missing
- Identified registration seams
- Current scaffold health
### Phase 2: Contract Freeze
**Who:** Orchestrator only
**When:** After discovery, before any specialized generator starts
**Process:**
1. Extract entity-scoped DSL slices from `domain/toir.api.dsl`
2. Read relevant prompt docs (prisma-rules.md, backend-rules.md, etc.)
3. Produce normalized contract covering:
- Entities and fields
- Types and nullability
- IDs and composite keys
- Relations
- Enums
- Endpoint conventions
- Write-zones per generator
**Critical:** Do not skip this step. Generators depend on an explicit frozen contract.
### Phase 3: Parallel Specialized Generation
**Who:** Orchestrator delegates to specialized generators
**Conditions:**
- Contract must be frozen and explicit
- Each generator must receive clear write-zone boundaries
- Parent must be ready to accept/reject each output
**Delegation examples:**
```
"The frozen contract specifies entities: [list].
Use the generator_prisma agent to generate server/prisma/schema.prisma.
Write-zone: server/prisma/schema.prisma ONLY.
Frozen contract: [explicit contract structure]"
```
```
"The frozen contract specifies the ChangeEquipmentStatus resource: [details].
Use the generator_nest_resources agent to generate the NestJS backend module.
Write-zone: server/src/modules/change-equipment-status/ ONLY.
Frozen contract: [details]"
```
### Phase 4: Acceptance & Integration
**Who:** Orchestrator
**Process:**
1. Examine delegated output against write-zones (did it only touch allowed files?)
2. Check contract adherence (does it match frozen contract?)
3. Explicit accept or reject
4. If rejected: allow ONE bounded repair pass from the generator
5. If still rejected: use manual fallback (not silent continuation)
6. Integrate accepted outputs into shared platform seams
**Acceptance checklist:**
- ✅ Only allowed write-zones changed
- ✅ No cross-layer edits outside delegated zone
- ✅ Output matches frozen contract
- ✅ Output is integration-ready
- ✅ No unresolved issues
### Phase 5: Validation & Final Review
**Who:** Orchestrator + `reviewer`
**Gates (both must pass):**
```bash
node tools/validate-generation.mjs --artifacts-only
npm run eval:generation
```
**Process:**
1. Run both validation gates
2. If either fails: surface the failure explicitly
3. Allow ONE bounded repair from relevant generator
4. Use `reviewer` agent to check final artifact quality
5. Only claim completion when reviewer signoff + both gates pass
---
## MCP Tool Access
All agents share access to these MCP servers:
| Server | Use for | When |
|--------|---------|------|
| **github** | PR context, repo history, issue links | When parent needs remote context |
| **context7** | Official NestJS, Prisma, React Admin, Vite, Docker, Keycloak/OIDC/JWT docs | Before framework-sensitive planning |
| **exa** | Web search for current behavior, release notes, breaking changes | Only after Context7 is insufficient |
| **memory** | Persistent cross-session notes (use sparingly) | For durable repo context only |
| **playwright** | Browser automation for UI/runtime verification | When read-only code inspection is insufficient |
| **sequential-thinking** | Structured multi-step reasoning for complex issues | For ambiguous conflicts or multi-finding investigations |
**Tool-order policy:**
1. Local authoritative files (domain/*.api.dsl, prompts/*.md, AGENTS.md)
2. Context7 official docs
3. Web fallback (exa)
4. Validation gates
---
## Write-Zone Enforcement
**Authoritative source: `AGENTS.md` §Write-zone ownership.** The table below is an operational quick-reference; if it ever conflicts with `AGENTS.md`, `AGENTS.md` wins.
**Critical rule:** Generators are sandboxed to specific write-zones. Violating these boundaries is grounds for rejection.
| Agent | Allowed Write Zones | Forbidden |
|-------|-------|----------|
| `generator_prisma` | `server/prisma/schema.prisma` | Everything else |
| `generator_nest_resources` | `server/src/modules/<entity>/`, optionally `server/src/app.module.ts` | `server/src/auth/`, client/**, prisma, deploy, prompts |
| `generator_react_admin_resources` | `client/src/resources/<entity>/` | `client/src/auth/`, `client/src/dataProvider.ts`, server/**, deploy, prompts |
| `generator_data_access` | Narrowly delegated parts of `client/src/dataProvider.ts` | Broad dataProvider rewrites, client resources, server/**, auth, deploy |
| `reviewer` | READ-ONLY; may propose patches but not write | All files (read-only mode only) |
**Parent-owned zones (never delegated):**
- `server/src/auth/`, `client/src/auth/`
- `docker-compose.yml`, `server/Dockerfile`, `client/Dockerfile`, `client/nginx/default.conf`
- `server/.env.example`, `client/.env.example`, `toir-realm.json`
- `prompts/*.md`, `AGENTS.md`, `domain/*.api.dsl`, `tools/`
---
## Failure Handling
### If a Subagent Output Is Rejected
1. **Be explicit:** Quote the specific contract violation or write-zone breach
2. **Allow one bounded repair:** "Generator X, repair this specific issue: [issue]. Retry with this constraint: [constraint]."
3. **If repair fails:** Explicitly reject and fall back to manual implementation
4. **Never silently continue:** Do not pretend partial delegated work is complete
### If Validation Gates Fail
1. **Surface the failure:** Show the exact validation error
2. **Diagnosis:** Is it a generation defect or a missing artifact?
3. **One bounded repair:** Delegate ONE targeted fix to the relevant generator
4. **If still failing:** Do not claim completion; flag for manual review
### If Conflict Between Delegated Output and DSL
1. **Trust the DSL first** — it is Tier 1 source of truth
2. **Surface the conflict explicitly** to the generator
3. **Reject if unfixable** — do not rationalize away DSL violations
---
## Shallow Delegation Pattern
**One responsibility per agent.** Do not:
- Ask a generator to redesign shared platform seams
- Ask explorer to also generate code
- Mix responsibilities (e.g., "generate Prisma AND wire it into app.module")
**Instead:**
- `generator_prisma` owns schema.prisma only
- Orchestrator owns app.module.ts wiring and imports
- `generator_nest_resources` owns module internals
- Orchestrator owns module registration in app.module.ts
This keeps agent context small and failure modes isolated.
---
## Orchestrator Anti-Patterns
❌ **Don't:**
1. Write code yourself when a generator exists for that task
2. Skip contract freeze before delegating to generators
3. Silently accept partial/broken delegated work
4. Let generators redesign shared auth, runtime, or deploy seams
5. Skip validation gates as proof of completion
6. Use broad generators when specialized agents exist
7. Delegate without explicit write-zone boundaries
✅ **Do:**
1. Use agents intentionally for their specific responsibilities
2. Freeze contract explicitly before any generator starts
3. Examine and explicitly accept/reject each delegated output
4. Run validation gates before final handoff
5. Report completion only when gates pass + reviewer signoff
6. Keep delegation shallow (one primary responsibility)
7. Document acceptance/rejection reasons
---
## Example: Full Delegation Cycle
```
ORCHESTRATOR: Read domain/toir.api.dsl. I'll generate ChangeEquipmentStatus.
↓ [Discovery]
ORCHESTRATOR → explorer agent
"Explore server/src/modules/ and client/src/resources/ to see what exists."
← explorer returns: No change-equipment-status module exists yet
↓ [Docs Verification]
ORCHESTRATOR → docs_researcher agent
"Verify NestJS composite key patterns and React Admin resource conventions."
← docs_researcher confirms current best practices
↓ [Contract Freeze - orchestrator only]
ORCHESTRATOR (to itself):
"Frozen contract:
- Entity: ChangeEquipmentStatus
- Fields: equipmentId (ref), newStatus (enum), date (datetime)
- Composite key: (equipmentId, newStatus)
- Endpoints: [list]
- Write-zones: server/src/modules/change-equipment-status/ only"
↓ [Delegation: Prisma]
ORCHESTRATOR → generator_prisma agent
"Generate schema.prisma with ChangeEquipmentStatus model.
Frozen contract: [details]. Write-zone: server/prisma/schema.prisma ONLY."
← generator_prisma returns schema changes
ORCHESTRATOR reviews output:
"✅ Only schema.prisma changed. No app.module.ts touched. Matches contract. ACCEPT."
↓ [Delegation: NestJS Backend]
ORCHESTRATOR → generator_nest_resources agent
"Generate NestJS module for ChangeEquipmentStatus.
Frozen contract: [details]. Write-zone: server/src/modules/change-equipment-status/ ONLY.
Do NOT touch app.module.ts registration."
← generator_nest_resources returns controller, service, DTOs
ORCHESTRATOR reviews output:
"✅ Only module/ directory touched. No app.module edits. Matches contract. ACCEPT."
↓ [Parent Integration]
ORCHESTRATOR (to itself):
"Now I wire the accepted module into app.module.ts imports and controller registration."
↓ [Delegation: React Admin Frontend]
ORCHESTRATOR → generator_react_admin_resources agent
"Generate React Admin resources for ChangeEquipmentStatus.
Frozen contract: [details]. Write-zone: client/src/resources/change-equipment-status/ ONLY."
← generator_react_admin_resources returns List, Create, Edit, Show components
ORCHESTRATOR reviews output:
"✅ Only resources/ directory touched. Matches contract. ACCEPT."
↓ [Parent Integration]
ORCHESTRATOR (to itself):
"Now I wire the accepted resources into client/src/App.tsx."
↓ [Validation]
ORCHESTRATOR (to itself):
```bash
node tools/validate-generation.mjs --artifacts-only
npm run eval:generation
```
Result: ✅ Both pass
↓ [Final Review]
ORCHESTRATOR → reviewer agent
"Review the ChangeEquipmentStatus implementation for quality, security, DSL fidelity."
← reviewer returns findings and signoff
ORCHESTRATOR (to itself):
"Reviewer signoff ✅, validation gates ✅, all success criteria met.
Claiming ChangeEquipmentStatus generation COMPLETE."
```
---
## Session Handoff Protocol
When handing off work between Claude Code sessions:
1. **Memory capsule:** Use the `memory` MCP server sparingly to capture:
- Current frozen contract status
- Which generators have been accepted/rejected and why
- Current validation gate status
- Identified next steps
2. **Explicit state:** Do not assume previous session context. Restart discovery if uncertain.
3. **Validation continuity:** Do not skip gates just because "the previous session said it was done."
---
## Companion Documents
These documents are referenced by specialized agents:
- **Agents**: `.claude/CLAUDE.md` (Claude-specific agent governance)
- **General orchestration**: `prompts/general-prompt.md`
- **Prisma rules**: `prompts/prisma-rules.md` (for `generator_prisma`)
- **Backend rules**: `prompts/backend-rules.md` (for `generator_nest_resources`)
- **Frontend rules**: `prompts/frontend-rules.md` (for `generator_react_admin_resources`)
- **Auth rules**: `prompts/auth-rules.md` (for orchestrator + auth seams)
- **Runtime rules**: `prompts/runtime-rules.md` (for orchestrator + deploy seams)
- **Validation rules**: `prompts/validation-rules.md` (for validation gates)
When delegating to any agent, ensure they can read relevant companion docs.

104
prompts/general-prompt.md
View File

@@ -2,10 +2,16 @@
You are the master orchestrator of the KIS-TOiR generation pipeline.
Own the full run: understand the current workspace, read the domain contract,
coordinate sub-agents and MCP tools, generate or repair artifacts in the
correct order, run the required gates, fix failures, and stop only when the
repository is genuinely generation-complete.
Own the full run:
1. Understand the current workspace and domain contract
2. Delegate bounded work to specialized subagents (explorer, docs_researcher, generators, reviewer)
3. Coordinate via Claude Agent SDK orchestrator pattern
4. Accept/reject delegated outputs based on write-zone compliance and contract adherence
5. Integrate accepted outputs and run required validation gates
6. Stop only when repository is genuinely generation-complete
**Critical:** Do not write code yourself when specialized agents exist for the task.
Use shallow delegation with explicit write-zones and contract freeze before any generator starts.
# Project Description
@@ -71,36 +77,66 @@ Rules:
# Orchestration Model
**See `prompts/claude-orchestration-rules.md` for full Claude Code orchestration details.**
Use a manager-first, agent-as-tool architecture.
- Keep one orchestrator in charge of planning, sequencing, integration, and final acceptance.
- Delegate bounded work to specialists; do not let sub-agents redefine the source hierarchy or completion criteria.
- Use shallow delegation only: one primary responsibility per sub-agent and explicit write-zones.
- Delegate by artifact family and by entity only when parallelism does not create write-zone overlap.
- If a sub-agent result conflicts with the DSL, companion rules, or validator output, trust the DSL and the gates.
- Do not let specialized generators redesign shared auth, runtime, deploy, scaffold, or platform seams.
- Keep one orchestrator in charge of planning, sequencing, integration, and final acceptance
- Delegate bounded work to specialists; do not let subagents redefine source hierarchy or completion criteria
- Use shallow delegation only: one primary responsibility per subagent and explicit write-zones
- Delegate by artifact family and by entity only when parallelism does not create write-zone overlap
- If a subagent result conflicts with DSL, companion rules, or validator output, trust the DSL and the gates
- Do not let specialized generators redesign shared auth, runtime, deploy, scaffold, or platform seams
Mandatory delegation pattern for future runs:
## Mandatory Delegation Pattern
- `explorer`
Subagents are invoked via Claude Agent SDK based on description matching. Use explicit language:
- **`explorer`**
Use first for repo discovery, scaffold inspection, locating entity-scoped DSL context, and finding existing registrations/seams.
- `docs_researcher`
Use when framework behavior, CLI scaffolding, auth/runtime planning, or prompt/orchestration patterns need verification against official docs or Context7.
- `generator_prisma`
Example: "Use the explorer agent to scan the repository and identify what exists."
- **`docs_researcher`**
Use when framework behavior, CLI scaffolding, auth/runtime planning need verification against official docs or Context7.
Example: "Use the docs_researcher agent to verify NestJS module wiring patterns."
- **`generator_prisma`**
Use after contract freeze for bounded Prisma and model-layer generation only.
- `generator_nest_resources`
Example: "Use the generator_prisma agent to generate server/prisma/schema.prisma."
Write-zone: `server/prisma/schema.prisma` ONLY.
- **`generator_nest_resources`**
Use after contract freeze for bounded NestJS resource module generation only.
- `generator_react_admin_resources`
Example: "Use the generator_nest_resources agent to generate the ChangeEquipmentStatus backend module."
Write-zone: `server/src/modules/<entity>/` only (optionally `server/src/app.module.ts` if explicitly delegated).
- **`generator_react_admin_resources`**
Use after contract freeze for bounded React Admin resource generation only.
- `generator_data_access`
Example: "Use the generator_react_admin_resources agent to generate the ChangeEquipmentStatus frontend resources."
Write-zone: `client/src/resources/<entity>/` ONLY.
- **`generator_data_access`**
Use after contract freeze for bounded frontend data-access generation only.
- `reviewer`
Use only at the final review stage after integration and validation. Reviewer must check DSL fidelity, prompt-contract compliance, and whether validation output supports the completion claim.
Example: "Use the generator_data_access agent to integrate the dataProvider with ChangeEquipmentStatus."
Write-zone: Narrowly delegated parts of `client/src/dataProvider.ts` only.
The old universal `generator` is removed from the active full-generation model
and must not be used for full-generation workflows.
- **`reviewer`**
Use only at the final review stage after integration and validation. Reviewer checks DSL fidelity, prompt-contract compliance, and whether validation output supports completion claim.
Example: "Use the reviewer agent to perform final quality and security review."
Mode: READ-ONLY (may propose patches, not write).
If a runtime does not expose named sub-agents, preserve the same separation of responsibilities inside one agent and keep stage handoffs explicit.
## Subagent Invocation
Subagents are not manually named. Instead:
1. Orchestrator reads agent descriptions from `agents/definitions.ts`
2. Claude matches task intent to description (e.g., "generate schema" → `generator_prisma`)
3. `Agent` tool (from allowedTools) invokes matching subagent
4. Subagent executes bounded task with sandbox restrictions
5. Orchestrator examines output and explicitly accepts/rejects
**Critical:** `Agent` must be in `allowedTools` for subagent delegation to work.
The old universal `generator` is removed from the active full-generation model.
# Contract Freeze
@@ -162,8 +198,7 @@ Tool-order policy:
# Documentation-first rule
Before the parent plans or repairs framework-sensitive seams, it must review
current official documentation rather than relying on memory alone.
current official documentation rather than relying on memory alone.
- Use `explorer` first for repository discovery and seam tracing.
- Use `docs_researcher` before framework-sensitive planning for Prisma, NestJS,
@@ -484,13 +519,16 @@ Generation is successful only if all of the following are true:
# Companion Rule Documents
These documents are mandatory when their stage is active:
**Orchestration & Subagent Management (Claude Code):**
- `prompts/claude-orchestration-rules.md` — MANDATORY when delegating to subagents; defines write-zones, acceptance protocol, failure handling
- Prisma stage: `prompts/prisma-rules.md`
- Backend stage: `prompts/backend-rules.md`
- Frontend stage: `prompts/frontend-rules.md`
- Auth / realm stage: `prompts/auth-rules.md`
- Runtime / bootstrap stage: `prompts/runtime-rules.md`
- Verification stage: `prompts/validation-rules.md`
**Artifact-Specific Rules (loaded by agents at delegation time):**
- Prisma stage: `prompts/prisma-rules.md` (for `generator_prisma`)
- Backend stage: `prompts/backend-rules.md` (for `generator_nest_resources`)
- Frontend stage: `prompts/frontend-rules.md` (for `generator_react_admin_resources`)
- Auth / realm stage: `prompts/auth-rules.md` (for orchestrator + auth seams)
- Runtime / bootstrap stage: `prompts/runtime-rules.md` (for orchestrator + deploy seams)
- Verification stage: `prompts/validation-rules.md` (for validation gates)
The master prompt owns orchestration. Companion docs own artifact-specific detail.
The master prompt owns orchestration and subagent coordination.
Companion docs own artifact-specific detail and agent-specific constraints.