toir-automatization/agents/definitions.ts

/**
 * Claude Agent SDK — KIS-TOiR Agent Definitions
 *
 * This file defines all specialized subagents for the KIS-TOiR generation pipeline.
 * Agents are invoked programmatically by the orchestrator via Claude Agent SDK.
 *
 * Each agent has:
 * - description: Clear criteria for when Claude should delegate to this agent
 * - prompt: Agent-specific instructions loaded from .claude/agents/*.toml
 * - tools: Sandbox-limited toolset per role
 * - model: Optional model override
 */

import { AgentDefinition } from "@anthropic-ai/claude-agent-sdk";
import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

/**
 * Load developer instructions from .claude/agents/*.toml config files.
 * Extracts the developer_instructions markdown block.
 */
function loadAgentInstructions(agentName: string): string {
  const tomlPath = path.join(
    __dirname,
    "..",
    ".claude",
    "agents",
    `${agentName}.toml`
  );

  if (!fs.existsSync(tomlPath)) {
    throw new Error(
      `Agent config not found: ${tomlPath}. Ensure .claude/agents/${agentName}.toml exists.`
    );
  }

  const content = fs.readFileSync(tomlPath, "utf-8");
  const match = content.match(/developer_instructions = """([\s\S]*?)"""/);

  if (!match) {
    throw new Error(
      `No developer_instructions found in ${agentName}.toml. Check TOML format.`
    );
  }

  return match[1].trim();
}

/**
 * KIS-TOiR Specialized Agent Registry
 *
 * All agents share access to MCP servers defined in .claude/config.toml:
 * - github: repository and PR context
 * - context7: official framework documentation
 * - exa: web search fallback
 * - memory: persistent cross-session context
 * - playwright: browser automation for UI/runtime verification
 * - sequential-thinking: structured multi-step reasoning
 */
export const agents: Record<string, AgentDefinition> = {
  /**
   * explorer
   *
   * Discovery and codebase exploration. Use for:
   * - Understanding project structure and finding files
   * - Tracing execution paths and existing integrations
   * - Locating entity-scoped DSL context
   * - Inspecting scaffold health and registration seams
   */
  explorer: {
    description:
      "Codebase discovery and exploration specialist. Use for understanding project structure, finding files, tracing execution paths, locating existing registrations and integration seams.",
    prompt: loadAgentInstructions("explorer"),
    tools: ["Read", "Glob", "Grep"],
    model: "haiku",
  },

  /**
   * docs_researcher
   *
   * Official documentation research and framework verification. Use for:
   * - Verifying current framework behavior (NestJS, Prisma, React Admin, etc.)
   * - Checking CLI scaffolding conventions
   * - Auth/runtime/deployment planning questions
   * - Version-sensitive behavior clarification
   */
  docs_researcher: {
    description:
      "Framework documentation specialist. Use for verifying current behavior of NestJS, Prisma, React Admin, Vite, Docker, nginx, or Keycloak/OIDC against official docs.",
    prompt: loadAgentInstructions("docs-researcher"),
    tools: ["Read"],
    model: "haiku",
  },

  /**
   * generator_prisma
   *
   * Prisma schema generation and management. Delegated only after contract freeze.
   * Write zone: server/prisma/schema.prisma only.
   */
  generator_prisma: {
    description:
      "Prisma schema generator. Use ONLY after contract freeze to generate or repair server/prisma/schema.prisma from frozen contract and domain DSL.",
    prompt: loadAgentInstructions("generator_prisma"),
    tools: ["Read", "Write", "Edit", "Bash", "Glob"],
    model: "opus",
  },

  /**
   * generator_nest_resources
   *
   * NestJS resource module generation. Delegated only after contract freeze.
   * Write zones: server/src/modules/<entity>/ and optionally server/src/app.module.ts
   */
  generator_nest_resources: {
    description:
      "NestJS backend resource generator. Use ONLY after contract freeze to generate server/src/modules/<entity>/ controllers, services, and DTOs from frozen contract.",
    prompt: loadAgentInstructions("generator_nest_resources"),
    tools: ["Read", "Write", "Edit", "Bash", "Glob"],
    model: "opus",
  },

  /**
   * generator_react_admin_resources
   *
   * React Admin resource generation. Delegated only after contract freeze.
   * Write zone: client/src/resources/<entity>/ only.
   */
  generator_react_admin_resources: {
    description:
      "React Admin frontend resource generator. Use ONLY after contract freeze to generate client/src/resources/<entity>/ List, Create, Edit, and Show components from frozen contract.",
    prompt: loadAgentInstructions("generator_react_admin_resources"),
    tools: ["Read", "Write", "Edit", "Bash", "Glob"],
    model: "opus",
  },

  /**
   * generator_data_access
   *
   * Frontend data access layer generation. Delegated only after contract freeze.
   * Write zones: narrowly delegated portions of client/src/dataProvider.ts only.
   */
  generator_data_access: {
    description:
      "Frontend data access specialist. Use ONLY after contract freeze to generate or repair client/src/dataProvider.ts API integration from frozen contract.",
    prompt: loadAgentInstructions("generator_data_access"),
    tools: ["Read", "Write", "Edit", "Bash", "Glob"],
    model: "opus",
  },

  /**
   * reviewer
   *
   * Final review and validation. Use only after integration and validation gates.
   * Read-only mode. Can propose changes but must not write directly.
   */
  reviewer: {
    description:
      "Final code and contract reviewer. Use ONLY after integration and validation to perform quality, security, DSL fidelity, and compliance review.",
    prompt: loadAgentInstructions("reviewer"),
    tools: ["Read", "Grep", "Glob"],
    model: "sonnet",
  },
};

export default agents;