feat: add coordinator/delegate expert separation

.changeset/coordinator-delegate-separation.md

@@ -0,0 +1,8 @@
+---
+"@perstack/core": patch
+"@perstack/runtime": patch
+"@perstack/skill-manager": patch
+"@perstack/installer": patch
+---
+
+Add coordinator/delegate expert separation with naming convention, delegation rule enforcement, and type-specific meta-prompts

SECURITY.md

@@ -86,7 +86,6 @@ The `exec` tool blocks overriding critical variables (case-insensitive):
 
 - Run in isolated directories without sensitive data
 - Review tool calls in verbose mode
-- Set `maxSteps` limits
 
 ### For Production
 

apps/base/src/tools/skill-management.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vitest"
 import type { SkillManagementCallbacks } from "./skill-management.js"
 import {
   registerAddDelegate,
+  registerAddDelegateFromConfig,
   registerAddSkill,
   registerCreateExpert,
   registerRemoveDelegate,
@@ -15,6 +16,9 @@ function createMockCallbacks(): SkillManagementCallbacks {
     addDelegate: vi.fn().mockResolvedValue({ delegateToolName: "delegate-tool" }),
     removeDelegate: vi.fn().mockResolvedValue(undefined),
     createExpert: vi.fn().mockResolvedValue({ expertKey: "my-expert" }),
+    addDelegateFromConfig: vi
+      .fn()
+      .mockResolvedValue({ delegateToolName: "delegate-from-config-tool" }),
   }
 }
 
@@ -250,4 +254,60 @@ describe("skill-management tools", () => {
       })
     })
   })
+
+  describe("addDelegateFromConfig", () => {
+    it("registers tool with correct metadata", () => {
+      const server = createMockServer()
+      const callbacks = createMockCallbacks()
+      registerAddDelegateFromConfig(server as never, callbacks)
+      expect(server.registerTool).toHaveBeenCalledWith(
+        "addDelegateFromConfig",
+        expect.objectContaining({ title: "Add delegate from config" }),
+        expect.any(Function),
+      )
+    })
+
+    it("calls callback with correct input and returns delegate tool name", async () => {
+      const server = createMockServer()
+      const callbacks = createMockCallbacks()
+      registerAddDelegateFromConfig(server as never, callbacks)
+      const handler = getHandler(server)
+      const input = {
+        configPath: "/path/to/perstack.toml",
+        delegateExpertName: "my-expert",
+      }
+      const result = await handler(input)
+      expect(callbacks.addDelegateFromConfig).toHaveBeenCalledWith(input)
+      expect(result).toStrictEqual({
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ delegateToolName: "delegate-from-config-tool" }),
+          },
+        ],
+      })
+    })
+
+    it("returns errorToolResult when callback throws", async () => {
+      const server = createMockServer()
+      const callbacks = createMockCallbacks()
+      ;(callbacks.addDelegateFromConfig as ReturnType<typeof vi.fn>).mockRejectedValue(
+        new Error("config not found"),
+      )
+      registerAddDelegateFromConfig(server as never, callbacks)
+      const handler = getHandler(server)
+      const result = await handler({
+        configPath: "/bad/path.toml",
+        delegateExpertName: "missing",
+      })
+      expect(result).toStrictEqual({
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: "Error", message: "config not found" }),
+          },
+        ],
+      })
+    })
+  })
 })

apps/base/src/tools/skill-management.ts

@@ -44,6 +44,10 @@ export interface SkillManagementCallbacks {
     tags?: string[]
     providerTools?: string[]
   }): Promise<{ expertKey: string }>
+  addDelegateFromConfig(input: {
+    configPath: string
+    delegateExpertName: string
+  }): Promise<{ delegateToolName: string }>
 }
 
 export function registerAddSkill(server: McpServer, callbacks: SkillManagementCallbacks) {
@@ -233,6 +237,34 @@ export function registerCreateExpert(server: McpServer, callbacks: SkillManageme
   )
 }
 
+export function registerAddDelegateFromConfig(
+  server: McpServer,
+  callbacks: SkillManagementCallbacks,
+) {
+  server.registerTool(
+    "addDelegateFromConfig",
+    {
+      title: "Add delegate from config",
+      description:
+        "Load all experts from a perstack.toml config file and add the specified one as a delegate. This is a shortcut that combines reading the config, creating the expert, and adding it as a delegate in a single step.",
+      inputSchema: {
+        configPath: z.string().describe("Path to the perstack.toml config file"),
+        delegateExpertName: z
+          .string()
+          .describe("Name of the expert in the config to add as a delegate"),
+      },
+    },
+    async (input: { configPath: string; delegateExpertName: string }) => {
+      try {
+        return successToolResult(await callbacks.addDelegateFromConfig(input))
+      } catch (e) {
+        if (e instanceof Error) return errorToolResult(e)
+        throw e
+      }
+    },
+  )
+}
+
 export function registerSkillManagementTools(
   server: McpServer,
   callbacks: SkillManagementCallbacks,
@@ -242,4 +274,5 @@ export function registerSkillManagementTools(
   registerAddDelegate(server, callbacks)
   registerRemoveDelegate(server, callbacks)
   registerCreateExpert(server, callbacks)
+  registerAddDelegateFromConfig(server, callbacks)
 }

apps/create-expert-skill/src/tools/run-expert.ts

@@ -36,7 +36,6 @@ interface RunExpertInput {
   provider: string
   model?: string
   timeout: number
-  maxSteps?: number
 }
 
 interface RunExpertOutput {
@@ -156,10 +155,6 @@ export async function runExpert(input: RunExpertInput): Promise<RunExpertOutput>
     args.push("--timeout", String(input.timeout))
   }
 
-  if (input.maxSteps) {
-    args.push("--max-steps", String(input.maxSteps))
-  }
-
   args.push(input.expertKey, input.query)
 
   // Map PROVIDER_API_KEY to the provider-specific env var
@@ -274,7 +269,6 @@ export function registerRunExpert(server: McpServer) {
           .optional()
           .default(120000)
           .describe("Timeout in milliseconds (default: 120000)"),
-        maxSteps: z.number().optional().describe("Maximum steps (optional)"),
       },
     },
     async (input: RunExpertInput) => {

apps/create-expert/bin/cli.ts

@@ -26,10 +26,6 @@ new Command()
     "--reasoning-budget <budget>",
     "Reasoning budget for native LLM reasoning (minimal, low, medium, high, or token count)",
   )
-  .option(
-    "--max-steps <maxSteps>",
-    "Maximum number of steps to run, default is undefined (no limit)",
-  )
   .option("--max-retries <maxRetries>", "Maximum number of generation retries, default is 5")
   .option(
     "--timeout <timeout>",
@@ -66,13 +62,13 @@ new Command()
         console.error("Error: query argument is required in headless mode")
         process.exit(1)
       }
-      await runHandler("expert", query, options, {
+      await runHandler("create-expert", query, options, {
         perstackConfig: config,
         lockfile,
         additionalEnv,
       })
     } else {
-      await startHandler("expert", query, options, {
+      await startHandler("create-expert", query, options, {
         perstackConfig: config,
         lockfile,
         additionalEnv,