rebase generation
This commit is contained in:
MaKarin
227
.claude/ORCHESTRATION_SETUP.md
Normal file
227
.claude/ORCHESTRATION_SETUP.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# Claude Code Orchestration Setup — KIS-TOiR
|
||||
|
||||
**Status:** ✅ Configuration complete
|
||||
|
||||
This document confirms the orchestration system is ready for Claude Code use.
|
||||
|
||||
---
|
||||
|
||||
## 📋 What Was Changed
|
||||
|
||||
### 1. New Files Created
|
||||
|
||||
#### SDK-Style Agent Definitions
|
||||
- **`agents/definitions.ts`** — Programmatic subagent registry using Claude Agent SDK
|
||||
- Loads agent instructions from `.claude/agents/*.toml`
|
||||
- Defines 7 specialized subagents: explorer, docs_researcher, 5 generators, reviewer
|
||||
- Sets sandbox limits and model overrides per agent
|
||||
- Makes agents auto-discoverable via description matching
|
||||
|
||||
#### Orchestrator Engine
|
||||
- **`tools/orchestrator.ts`** — CLI orchestrator tool
|
||||
- Entry point for multi-agent coordination
|
||||
- Configures `Agent` tool for subagent invocation
|
||||
- Shares MCP servers (github, context7, exa, memory, playwright, sequential-thinking)
|
||||
- Command: `npx ts-node tools/orchestrator.ts "Your task"`
|
||||
|
||||
#### Claude Code Orchestration Rules
|
||||
- **`prompts/claude-orchestration-rules.md`** — Subagent governance (MANDATORY)
|
||||
- Write-zone enforcement per agent
|
||||
- Contract freeze workflow
|
||||
- Delegation phases (discovery → contract → generation → acceptance → integration → validation)
|
||||
- Failure handling and repair protocols
|
||||
- MCP tool ordering
|
||||
- Example: full delegation cycle
|
||||
|
||||
#### Claude-Specific Supplement
|
||||
- **`.claude/CLAUDE.md` (UPDATED)** — Governance supplement
|
||||
- Describes subagent invocation model
|
||||
- Lists write-zones and allowed files
|
||||
- Documents MCP server access
|
||||
- Explains orchestration entry points
|
||||
|
||||
### 2. Configuration Updates
|
||||
|
||||
#### `package.json` (UPDATED)
|
||||
- Added `"type": "module"` for ES modules
|
||||
- Added dev dependency: `@anthropic-ai/claude-agent-sdk`
|
||||
- Added npm script: `npm run orchestrate` for CLI convenience
|
||||
|
||||
#### `.claude/settings.local.json` (UPDATED)
|
||||
- Added permissions for `tools/orchestrator.ts`
|
||||
- Added `npm install` permission for dependency setup
|
||||
- Added `node --loader ts-node/esm` loader permission
|
||||
|
||||
#### `prompts/general-prompt.md` (UPDATED)
|
||||
- Updated "Role" section with explicit delegation principle
|
||||
- Expanded "Orchestration Model" with subagent invocation details
|
||||
- Added reference to `prompts/claude-orchestration-rules.md` (mandatory)
|
||||
- Clarified mandatory delegation pattern for each agent
|
||||
- Added "Subagent Invocation" section explaining Agent tool requirement
|
||||
|
||||
#### `AGENTS.md` (UPDATED)
|
||||
- Added Tier 1 entries for:
|
||||
- `.claude/CLAUDE.md` — Claude Code governance supplement
|
||||
- `prompts/claude-orchestration-rules.md` — Orchestration rules (mandatory)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Use
|
||||
|
||||
### Installation (One-time)
|
||||
|
||||
```bash
|
||||
cd /Users/yyy/Desktop/toir-light
|
||||
npm install
|
||||
# This installs @anthropic-ai/claude-agent-sdk
|
||||
```
|
||||
|
||||
### Orchestration Invocation
|
||||
|
||||
**Option 1: Via npm script**
|
||||
```bash
|
||||
npm run orchestrate "Your generation task here"
|
||||
```
|
||||
|
||||
**Option 2: Direct TypeScript**
|
||||
```bash
|
||||
npx ts-node tools/orchestrator.ts "Your generation task here"
|
||||
```
|
||||
|
||||
**Option 3: From within Claude Code session (programmatic)**
|
||||
```typescript
|
||||
import orchestrate from './tools/orchestrator';
|
||||
await orchestrate("Generate Prisma schema from domain/toir.api.dsl");
|
||||
```
|
||||
|
||||
### Example: Full Generation Task
|
||||
|
||||
```bash
|
||||
npm run orchestrate "Execute full KIS-TOiR generation:
|
||||
1. Use explorer to understand current workspace state
|
||||
2. Freeze contract for ChangeEquipmentStatus resource
|
||||
3. Delegate to generator_prisma, generator_nest_resources, generator_react_admin_resources, generator_data_access
|
||||
4. Accept all outputs, integrate into shared platform
|
||||
5. Run validation gates
|
||||
6. Send to reviewer for final signoff"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Required Reading Order
|
||||
|
||||
When starting any orchestration session in Claude Code:
|
||||
|
||||
1. **This file** — Understand what changed and how to invoke
|
||||
2. **AGENTS.md** — Understand agent workflow and mutation boundaries
|
||||
3. **prompts/general-prompt.md** — Understand orchestration model and roles
|
||||
4. **prompts/claude-orchestration-rules.md** — MANDATORY before delegating; defines write-zones, contract freeze, acceptance protocol
|
||||
5. **.claude/CLAUDE.md** — Understand Claude-specific entry points and MCP access
|
||||
|
||||
When delegating to specific agents, read their `.claude/agents/*.toml` files for detailed instructions.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Key Architectural Changes
|
||||
|
||||
### Before (Codex-style, not working in Claude Code)
|
||||
|
||||
```toml
|
||||
# .claude/config.toml
|
||||
[agents]
|
||||
explorer = { config_file = "agents/explorer.toml" }
|
||||
# ... (config file references)
|
||||
```
|
||||
|
||||
❌ Claude Code couldn't invoke these agents — incompatible naming/invocation model
|
||||
|
||||
### After (Claude Agent SDK style, fully compatible)
|
||||
|
||||
```typescript
|
||||
// agents/definitions.ts
|
||||
export const agents = {
|
||||
explorer: {
|
||||
description: "Codebase discovery and exploration...",
|
||||
prompt: loadAgentInstructions("explorer"),
|
||||
tools: ["Read", "Glob", "Grep"],
|
||||
model: "haiku"
|
||||
},
|
||||
// ... (7 agents total)
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// tools/orchestrator.ts
|
||||
for await (const message of query({
|
||||
prompt: mainPrompt,
|
||||
options: {
|
||||
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"],
|
||||
agents // ← Agent tool enables subagent invocation
|
||||
}
|
||||
})) { ... }
|
||||
```
|
||||
|
||||
✅ Claude Code can now:
|
||||
- Read agent definitions
|
||||
- Match task intent to agent descriptions
|
||||
- Invoke subagents via `Agent` tool
|
||||
- Enforce write-zones and sandbox limits
|
||||
- Accept/reject delegated outputs
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verification Checklist
|
||||
|
||||
Before running your first orchestration task:
|
||||
|
||||
- [ ] Read `.claude/CLAUDE.md`
|
||||
- [ ] Read `prompts/claude-orchestration-rules.md`
|
||||
- [ ] Run `npm install` (installs `@anthropic-ai/claude-agent-sdk`)
|
||||
- [ ] Verify `agents/definitions.ts` exists
|
||||
- [ ] Verify `tools/orchestrator.ts` exists
|
||||
- [ ] Try `npm run orchestrate "Test: list the KIS-TOiR agents"`
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### "Agent tool not available"
|
||||
→ Add `"Agent"` to `allowedTools` in orchestrator.ts (already done, but verify)
|
||||
|
||||
### "Subagent descriptions don't match my task"
|
||||
→ Be explicit in your orchestration prompt; use agent names or clear descriptions
|
||||
→ Example: "Use the generator_prisma agent to generate server/prisma/schema.prisma"
|
||||
|
||||
### "Subagent writes to forbidden zone"
|
||||
→ This is grounds for rejection. Examine .claude/agents/*.toml for agent instructions and write-zone rules.
|
||||
→ Reread `prompts/claude-orchestration-rules.md` write-zone table
|
||||
|
||||
### "npm install fails"
|
||||
→ Ensure Node.js 22 LTS is installed: `node --version`
|
||||
→ Ensure npm is available: `npm --version`
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Notes
|
||||
|
||||
- ✅ All agent instructions loaded from version-controlled `.claude/agents/*.toml` files
|
||||
- ✅ Write-zones strictly enforced per agent (sandbox restrictions)
|
||||
- ✅ MCP servers configured in `.claude/config.toml` (read-only agents can't write)
|
||||
- ✅ No hardcoded secrets; use `.env.example` patterns only
|
||||
- ✅ Reviewer agent is read-only; cannot write or modify artifacts
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Files
|
||||
|
||||
- **AGENTS.md** — Master agent operating rules (authoritative)
|
||||
- **prompts/general-prompt.md** — Master orchestrator prompt
|
||||
- **prompts/claude-orchestration-rules.md** — Subagent governance (mandatory for delegation)
|
||||
- **.claude/CLAUDE.md** — Claude Code-specific governance supplement
|
||||
- **.claude/agents/*.toml** — Individual agent configurations (6 generator + reviewer)
|
||||
- **.claude/config.toml** — MCP server definitions (github, context7, exa, memory, playwright, sequential-thinking)
|
||||
|
||||
---
|
||||
|
||||
**Generated:** 2026-04-06
|
||||
**System:** Claude Agent SDK Orchestration v0.2.0
|
||||
Reference in New Issue
Block a user