rebase generation

agents/definitions.ts

@@ -0,0 +1,169 @@
+/**
+ * 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;