228 lines
7.3 KiB
Markdown
228 lines
7.3 KiB
Markdown
# 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
|