# 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