toir-automatization/.claude/ORCHESTRATION_SETUP.md

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)

cd /Users/yyy/Desktop/toir-light
npm install
# This installs @anthropic-ai/claude-agent-sdk

Orchestration Invocation

Option 1: Via npm script

npm run orchestrate "Your generation task here"

Option 2: Direct TypeScript

npx ts-node tools/orchestrator.ts "Your generation task here"

Option 3: From within Claude Code session (programmatic)

import orchestrate from './tools/orchestrator';
await orchestrate("Generate Prisma schema from domain/toir.api.dsl");

Example: Full Generation Task

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)

# .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)

// agents/definitions.ts
export const agents = {
  explorer: {
    description: "Codebase discovery and exploration...",
    prompt: loadAgentInstructions("explorer"),
    tools: ["Read", "Glob", "Grep"],
    model: "haiku"
  },
  // ... (7 agents total)
}

// 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