@directive-run/claude-plugin 1.16.0

package/skills/building-ai-orchestrators/SKILL.md

@@ -0,0 +1,401 @@
+---
+name: building-ai-orchestrators
+description: "Create AI orchestration systems using createAgentOrchestrator (single agent) and createMultiAgentOrchestrator (multi-agent). Define factsSchema with t.*() builders, init state, constraints for trigger conditions, and resolvers for LLM execution. Use when building LLM-powered workflows, agent pipelines, task runners, or multi-agent coordination systems."
+---
+
+# Building AI Orchestrators
+
+## Prerequisites
+
+This skill applies when the project uses `@directive-run/ai`. If not found in `package.json`, suggest installing it: `npm install @directive-run/ai`.
+
+## When Claude Should Use This Skill
+
+## Auto-Invoke Triggers
+- User asks to "build an AI agent", "create an orchestrator", "set up an LLM workflow"
+- User wants agents to coordinate, handoff, or collaborate
+- User needs structured AI task execution with constraints and state
+- User mentions `createAgentOrchestrator` or `createMultiAgentOrchestrator`
+- User asks about `orchestrator.run()` or `orchestrator.runStream()`
+
+## Exclusions
+- Do NOT invoke for general Directive (non-AI) patterns – use core Directive docs instead
+- Do NOT invoke for testing orchestrators – use `testing-ai-systems` skill
+- Do NOT invoke for guardrails, budgets, or security – use `hardening-ai-systems` skill
+
+---
+
+## Quick Reference
+
+## Decision Tree: Which Orchestrator?
+
+```
+Need AI orchestration?
+├── Single agent doing one job → createAgentOrchestrator
+│   ├── Simple: runner + factsSchema + init + resolvers
+│   └── Complex: add constraints, retry, plugins
+└── Multiple agents coordinating → createMultiAgentOrchestrator
+    ├── Agents run in sequence → default sequential
+    ├── Agents run in parallel → parallel: true on agents
+    └── Dynamic routing → coordinator constraints
+```
+
+## createAgentOrchestrator – Core Pattern
+
+```typescript
+import { createAgentOrchestrator } from "@directive-run/ai";
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+import { t } from "@directive-run/core";
+
+const orchestrator = createAgentOrchestrator({
+  runner: createAnthropicRunner({
+    model: "claude-opus-4-6",
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  }),
+
+  // ALWAYS use t.*() builders – never TypeScript type annotations
+  factsSchema: {
+    input: t.string(),
+    output: t.string().optional(),
+    status: t.string<"idle" | "running" | "done" | "error">(),
+    attempt: t.number(),
+    error: t.string().optional(),
+  },
+
+  // init() is required – sets starting state
+  init: (facts) => {
+    facts.status = "idle";
+    facts.attempt = 0;
+  },
+
+  constraints: {
+    startProcessing: {
+      when: (facts) => facts.status === "idle" && facts.input.length > 0,
+      require: { type: "PROCESS_INPUT" },
+    },
+    retryOnError: {
+      priority: 10,
+      when: (facts) => facts.status === "error" && facts.attempt < 3,
+      require: { type: "PROCESS_INPUT" },
+    },
+  },
+
+  resolvers: {
+    processInput: {
+      requirement: "PROCESS_INPUT",
+      resolve: async (req, context) => {
+        context.facts.status = "running";
+        context.facts.attempt += 1;
+
+        const result = await context.runner.run({
+          prompt: context.facts.input,
+          system: "You are a helpful assistant.",
+        });
+
+        context.facts.output = result.text;
+        context.facts.status = "done";
+      },
+    },
+  },
+});
+
+// Execute
+const result = await orchestrator.run({ input: "Summarize this text..." });
+console.log(result.facts.output);
+```
+
+## createMultiAgentOrchestrator – Core Pattern
+
+```typescript
+import { createMultiAgentOrchestrator } from "@directive-run/ai";
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+import { t } from "@directive-run/core";
+
+const orchestrator = createMultiAgentOrchestrator({
+  // Coordinator defines shared state across all agents
+  coordinator: {
+    factsSchema: {
+      topic: t.string(),
+      phase: t.string<"research" | "draft" | "review" | "done">(),
+      researchNotes: t.string().optional(),
+      draft: t.string().optional(),
+      finalOutput: t.string().optional(),
+    },
+    init: (facts) => {
+      facts.phase = "research";
+    },
+  },
+
+  agents: {
+    researcher: {
+      runner: createAnthropicRunner({ model: "claude-haiku-4-5" }),
+      // Per-agent schema – merged with coordinator facts
+      factsSchema: {
+        searchDepth: t.number(),
+      },
+      init: (facts) => {
+        facts.searchDepth = 3;
+      },
+      constraints: {
+        doResearch: {
+          when: (facts) => facts.phase === "research",
+          require: { type: "RESEARCH" },
+        },
+      },
+      resolvers: {
+        research: {
+          requirement: "RESEARCH",
+          resolve: async (req, context) => {
+            const result = await context.runner.run({
+              prompt: `Research this topic: ${context.facts.topic}`,
+            });
+            context.facts.researchNotes = result.text;
+            context.facts.phase = "draft";
+          },
+        },
+      },
+    },
+
+    writer: {
+      runner: createAnthropicRunner({ model: "claude-opus-4-6" }),
+      factsSchema: {
+        style: t.string(),
+      },
+      init: (facts) => {
+        facts.style = "professional";
+      },
+      constraints: {
+        writeDraft: {
+          when: (facts) => facts.phase === "draft" && !!facts.researchNotes,
+          require: { type: "WRITE" },
+        },
+      },
+      resolvers: {
+        write: {
+          requirement: "WRITE",
+          resolve: async (req, context) => {
+            const result = await context.runner.run({
+              prompt: `Write a ${context.facts.style} article based on: ${context.facts.researchNotes}`,
+            });
+            context.facts.draft = result.text;
+            context.facts.phase = "done";
+          },
+        },
+      },
+    },
+  },
+});
+
+const result = await orchestrator.run({ topic: "Quantum computing" });
+console.log(result.facts.finalOutput);
+```
+
+## Streaming Execution
+
+```typescript
+// runStream() returns AsyncIterable<OrchestratorEvent>
+const stream = orchestrator.runStream({ input: "Analyze this..." });
+
+for await (const event of stream) {
+  switch (event.type) {
+    case "token": {
+      process.stdout.write(event.text);
+      break;
+    }
+    case "requirement_met": {
+      console.log(`Resolved: ${event.requirementType}`);
+      break;
+    }
+    case "done": {
+      console.log("Final:", event.facts);
+      break;
+    }
+    case "error": {
+      console.error("Failed:", event.error);
+      break;
+    }
+  }
+}
+```
+
+## createTask – Structured Work Units
+
+```typescript
+import { createTask } from "@directive-run/ai";
+
+const summarizeTask = createTask({
+  name: "summarize",
+  description: "Summarize text to a target length",
+  input: {
+    text: t.string(),
+    maxWords: t.number(),
+  },
+  output: {
+    summary: t.string(),
+    wordCount: t.number(),
+  },
+  // Tasks integrate into orchestrator resolvers
+  resolve: async (input, context) => {
+    const result = await context.runner.run({
+      prompt: `Summarize in ${input.maxWords} words: ${input.text}`,
+    });
+
+    return {
+      summary: result.text,
+      wordCount: result.text.split(" ").length,
+    };
+  },
+});
+
+// Use task inside a resolver
+resolvers: {
+  summarize: {
+    requirement: "SUMMARIZE",
+    resolve: async (req, context) => {
+      const output = await summarizeTask.run(
+        { text: context.facts.input, maxWords: 100 },
+        context
+      );
+      context.facts.summary = output.summary;
+    },
+  },
+},
+```
+
+## Resolver Context API
+
+```typescript
+resolve: async (req, context) => {
+  context.facts          // Read/write orchestrator facts
+  context.runner         // Execute LLM calls
+  context.signal         // AbortSignal for cancellation
+  context.emit(event)    // Emit custom events to stream
+  context.plugins        // Access plugin instances
+}
+```
+
+## factsSchema Type Builders Reference
+
+```typescript
+// Primitives
+t.string()                          // string
+t.number()                          // number
+t.boolean()                         // boolean
+
+// Optional / nullable
+t.string().optional()               // string | undefined
+t.string().nullable()               // string | null
+
+// Union literal types
+t.string<"idle" | "running">()      // typed string union
+t.number<1 | 2 | 3>()             // typed number union
+
+// Objects and arrays
+t.object<MyInterface>()             // typed object
+t.array(t.string())                 // string[]
+t.array(t.object<Item>())          // Item[]
+
+// Record / map
+t.record(t.string(), t.number())    // Record<string, number>
+```
+
+## Common Constraint Patterns
+
+```typescript
+constraints: {
+  // Trigger on status transition
+  onIdle: {
+    when: (facts) => facts.status === "idle" && !!facts.input,
+    require: { type: "START" },
+  },
+
+  // Priority for conflict resolution (higher = wins)
+  emergency: {
+    priority: 100,
+    when: (facts) => facts.errorCount > 5,
+    require: { type: "ABORT" },
+  },
+
+  // Pass data in requirement
+  withPayload: {
+    when: (facts) => facts.ready,
+    require: (facts) => ({ type: "PROCESS", model: facts.preferredModel }),
+  },
+}
+```
+
+---
+
+## Critical Anti-Patterns
+
+## Using TypeScript types instead of t.*() in factsSchema
+
+```typescript
+// WRONG – TypeScript type annotations, not schema builders
+factsSchema: {
+  status: "idle" | "running" | "done",  // type annotation, not runtime schema
+  count: number,
+}
+
+// CORRECT – t.*() builders provide runtime validation + TypeScript inference
+factsSchema: {
+  status: t.string<"idle" | "running" | "done">(),
+  count: t.number(),
+}
+```
+
+## Forgetting init()
+
+```typescript
+// WRONG – facts start undefined, constraints fail immediately
+const orchestrator = createAgentOrchestrator({
+  factsSchema: { status: t.string() },
+  // missing init: facts.status is undefined
+  constraints: {
+    start: { when: (facts) => facts.status === "idle", ... },
+  },
+});
+
+// CORRECT
+init: (facts) => {
+  facts.status = "idle";
+},
+```
+
+### Resolver parameter naming
+Always use `(req, context)` – never `(req, ctx)` or `(request, context)`.
+
+## Single-line returns without braces
+
+```typescript
+// WRONG
+when: (facts) => facts.status === "idle" ? true : false,
+
+// CORRECT – always use multi-line blocks when branching
+when: (facts) => {
+  return facts.status === "idle";
+},
+```
+
+## Mutating facts outside resolvers
+
+```typescript
+// WRONG – direct mutation bypasses reactivity
+orchestrator.facts.status = "done";
+
+// CORRECT – always via context.facts inside resolvers
+resolve: async (req, context) => {
+  context.facts.status = "done";
+},
+```
+
+---
+
+## Reference Files
+
+- `ai-orchestrator.md` – Full createAgentOrchestrator API, options, lifecycle
+- `ai-multi-agent.md` – createMultiAgentOrchestrator, coordinator pattern, agent communication
+- `ai-tasks.md` – createTask API, task composition, input/output validation
+- `examples/ai-orchestrator.ts` – Complete single-agent example
+- `examples/ai-checkpoint.ts` – Checkpoint/resume pattern
+- `examples/fraud-analysis.ts` – Multi-agent fraud detection example