@directive-run/knowledge 0.2.0 → 0.4.2

package/README.md

@@ -3,9 +3,9 @@
 Knowledge files, examples, and validation scripts for the [Directive](https://directive.run) runtime.
 
 This package is the **source of truth** for all Directive coding knowledge used by:
-- `@directive-run/cli` — generates AI rules files (`.cursorrules`, `CLAUDE.md`, etc.)
-- `@directive-run/claude-plugin` — builds Claude Code plugin skills
-- `directive.run/llms.txt` — website LLM reference
+- `@directive-run/cli` – generates AI rules files (`.cursorrules`, `CLAUDE.md`, etc.)
+- `@directive-run/claude-plugin` – builds Claude Code plugin skills
+- `directive.run/llms.txt` – website LLM reference
 
 ## Contents
 

package/ai/ai-adapters.md

@@ -24,7 +24,7 @@ Which LLM provider?
 Every adapter MUST be imported from its subpath. The main `@directive-run/ai` entry does NOT export adapters.
 
 ```typescript
-// CORRECT — subpath imports
+// CORRECT – subpath imports
 import { createAnthropicRunner } from "@directive-run/ai/anthropic";
 import { createOpenAIRunner } from "@directive-run/ai/openai";
 import { createOllamaRunner } from "@directive-run/ai/ollama";
@@ -34,11 +34,11 @@ import { createGeminiRunner } from "@directive-run/ai/gemini";
 ### Anti-Pattern #26: Importing adapters from the main entry
 
 ```typescript
-// WRONG — adapters are NOT exported from the main package
+// WRONG – adapters are NOT exported from the main package
 import { createOpenAIRunner } from "@directive-run/ai";
 import { createAnthropicRunner } from "@directive-run/ai";
 
-// CORRECT — use subpath imports
+// CORRECT – use subpath imports
 import { createOpenAIRunner } from "@directive-run/ai/openai";
 import { createAnthropicRunner } from "@directive-run/ai/anthropic";
 ```
@@ -136,12 +136,12 @@ const runner = createGeminiRunner({
 ### Anti-Pattern #27: Assuming provider-specific token structure
 
 ```typescript
-// WRONG — Anthropic returns { input_tokens, output_tokens } natively
+// WRONG – Anthropic returns { input_tokens, output_tokens } natively
 // but adapters normalize this
 const result = await runner.run(agent, prompt);
 console.log(result.tokenUsage.input_tokens); // undefined!
 
-// CORRECT — adapters normalize to camelCase
+// CORRECT – adapters normalize to camelCase
 const result = await runner.run(agent, prompt);
 console.log(result.tokenUsage.inputTokens);   // number
 console.log(result.tokenUsage.outputTokens);   // number
@@ -201,7 +201,7 @@ const runner = createAnthropicRunner({
 // Single-agent
 const orchestrator = createAgentOrchestrator({ runner });
 
-// Multi-agent — same runner shared across all agents
+// Multi-agent – same runner shared across all agents
 const multiOrchestrator = createMultiAgentOrchestrator({
   agents: { /* ... */ },
   runner,
@@ -219,7 +219,7 @@ const runner = createAnthropicRunner({
   apiKey: process.env.ANTHROPIC_API_KEY,
 });
 
-// After: OpenAI — same orchestrator, different runner
+// After: OpenAI – same orchestrator, different runner
 import { createOpenAIRunner } from "@directive-run/ai/openai";
 const runner = createOpenAIRunner({
   apiKey: process.env.OPENAI_API_KEY,

package/ai/ai-agents-streaming.md

@@ -18,11 +18,11 @@ Need the complete result?
         └── Default          → strategy: "buffer"
 ```
 
-## AgentLike — What the Runner Receives
+## AgentLike – What the Runner Receives
 
 ```typescript
 interface AgentLike {
-  // Required — unique identifier
+  // Required – unique identifier
   name: string;
 
   // System prompt / instructions
@@ -44,7 +44,7 @@ const agent: AgentLike = {
 };
 ```
 
-## RunResult — What the Runner Returns
+## RunResult – What the Runner Returns
 
 ```typescript
 interface RunResult<T = unknown> {
@@ -143,7 +143,7 @@ Control behavior when the consumer cannot keep up with token production:
 
 ```typescript
 const stream = orchestrator.runStream(agent, "Generate long report", {
-  backpressure: "buffer",  // default — buffer all tokens in memory
+  backpressure: "buffer",  // default – buffer all tokens in memory
 });
 
 const stream = orchestrator.runStream(agent, "Generate long report", {
@@ -228,12 +228,12 @@ eventSource.onmessage = (event) => {
 ### Not checking chunk.type before accessing fields
 
 ```typescript
-// WRONG — not all chunks have .data
+// WRONG – not all chunks have .data
 for await (const chunk of stream) {
   console.log(chunk.data); // undefined for non-token chunks
 }
 
-// CORRECT — switch on chunk.type
+// CORRECT – switch on chunk.type
 for await (const chunk of stream) {
   if (chunk.type === "token") {
     console.log(chunk.data);
@@ -244,12 +244,12 @@ for await (const chunk of stream) {
 ### Ignoring the stopped flag on guardrail chunks
 
 ```typescript
-// WRONG — continuing after a stopping guardrail
+// WRONG – continuing after a stopping guardrail
 case "guardrail_triggered":
   console.log("Guardrail triggered, continuing...");
   break;
 
-// CORRECT — check if the stream was stopped
+// CORRECT – check if the stream was stopped
 case "guardrail_triggered":
   if (chunk.stopped) {
     console.error(`Stopped by ${chunk.guardrailName}: ${chunk.reason}`);

package/ai/ai-budget-resilience.md

@@ -55,13 +55,13 @@ const budgetRunner = withBudget(baseRunner, {
 ### Anti-Pattern #29: budgetWarningThreshold out of range
 
 ```typescript
-// WRONG — threshold must be a 0-1 percentage
+// WRONG – threshold must be a 0-1 percentage
 const budgetRunner = withBudget(baseRunner, {
   budgetWarningThreshold: 80, // Not a percentage!
   budgets: [{ window: "hour", maxCost: 1.0, pricing: { inputPerMillion: 3, outputPerMillion: 15 } }],
 });
 
-// CORRECT — use a decimal between 0 and 1
+// CORRECT – use a decimal between 0 and 1
 const budgetRunner = withBudget(baseRunner, {
   budgetWarningThreshold: 0.8, // 80%
   budgets: [{ window: "hour", maxCost: 1.0, pricing: { inputPerMillion: 3, outputPerMillion: 15 } }],
@@ -127,12 +127,12 @@ breaker.reset();            // Force back to closed
 ### Anti-Pattern #28: Sharing a CircuitBreaker across unrelated agents
 
 ```typescript
-// WRONG — one failing agent opens the breaker for all agents
+// WRONG – one failing agent opens the breaker for all agents
 const sharedBreaker = createCircuitBreaker({ failureThreshold: 3, resetTimeout: 30000 });
 const researchRunner = sharedBreaker.wrap(baseRunner);
 const writerRunner = sharedBreaker.wrap(baseRunner); // Same breaker!
 
-// CORRECT — each agent gets its own breaker instance
+// CORRECT – each agent gets its own breaker instance
 const researchBreaker = createCircuitBreaker({ failureThreshold: 3, resetTimeout: 30000 });
 const writerBreaker = createCircuitBreaker({ failureThreshold: 3, resetTimeout: 30000 });
 
@@ -207,7 +207,7 @@ const router = createConstraintRouter({
 
 ## Combining Wrappers
 
-Wrappers compose — apply them inside-out (innermost runs first):
+Wrappers compose – apply them inside-out (innermost runs first):
 
 ```typescript
 import { withBudget, withRetry, withFallback } from "@directive-run/ai";

package/ai/ai-communication.md

@@ -184,7 +184,7 @@ const isReady = orchestrator.system.derive.researcher.isComplete;
 The scratchpad is an ephemeral key-value store scoped to a single pattern execution. Tasks and agents in the same pattern share it:
 
 ```typescript
-// In a task — write to scratchpad
+// In a task – write to scratchpad
 tasks: {
   gather: {
     run: async (input, context) => {

package/ai/ai-guardrails-memory.md

@@ -28,7 +28,7 @@ interface GuardrailResult {
   // Why it failed (when passed: false)
   reason?: string;
 
-  // Modified data — guardrail can transform the input/output
+  // Modified data – guardrail can transform the input/output
   transformed?: unknown;
 }
 ```
@@ -60,7 +60,7 @@ const piiGuardrail = createPIIGuardrail({
 import { createModerationGuardrail } from "@directive-run/ai";
 
 const moderationGuardrail = createModerationGuardrail({
-  // Custom check function — return true if content is safe
+  // Custom check function – return true if content is safe
   checkFn: async (content) => {
     const result = await moderationAPI.check(content);
 
@@ -171,7 +171,7 @@ const orchestrator = createAgentOrchestrator({
 ## Anti-Pattern #25: Catching Error Instead of GuardrailError
 
 ```typescript
-// WRONG — loses guardrail-specific metadata
+// WRONG – loses guardrail-specific metadata
 try {
   const result = await orchestrator.run(agent, prompt);
 } catch (error) {
@@ -180,7 +180,7 @@ try {
   }
 }
 
-// CORRECT — catch GuardrailError for full context
+// CORRECT – catch GuardrailError for full context
 import { GuardrailError } from "@directive-run/ai";
 
 try {
@@ -259,7 +259,7 @@ When messages are evicted, a summarizer condenses them:
 ```typescript
 import { createTruncationSummarizer } from "@directive-run/ai";
 
-// Simply drops old messages — no summary generated
+// Simply drops old messages – no summary generated
 const summarizer = createTruncationSummarizer();
 ```
 
@@ -299,14 +299,14 @@ const orchestrator = createAgentOrchestrator({
 ## Anti-Pattern #31: Async Summarizer Without autoManage: false
 
 ```typescript
-// WRONG — LLM summarizer is async but autoManage runs synchronously
+// WRONG – LLM summarizer is async but autoManage runs synchronously
 const memory = createAgentMemory({
   strategy: createSlidingWindowStrategy({ maxMessages: 20 }),
   summarizer: createLLMSummarizer(runner),
   autoManage: true, // Will not await the summarizer properly
 });
 
-// CORRECT — disable autoManage, call memory.manage() manually
+// CORRECT – disable autoManage, call memory.manage() manually
 const memory = createAgentMemory({
   strategy: createSlidingWindowStrategy({ maxMessages: 20 }),
   summarizer: createLLMSummarizer(runner),

package/ai/ai-mcp-rag.md

@@ -30,13 +30,13 @@ import { createMCPAdapter } from "@directive-run/ai";
 
 const mcp = createMCPAdapter({
   servers: [
-    // stdio transport — runs a local process
+    // stdio transport – runs a local process
     {
       name: "tools",
       transport: "stdio",
       command: "npx mcp-server-tools",
     },
-    // SSE transport — connects to an HTTP server
+    // SSE transport – connects to an HTTP server
     {
       name: "data",
       transport: "sse",
@@ -78,10 +78,10 @@ const agent = {
 ### Anti-Pattern #36: Importing MCP from subpath
 
 ```typescript
-// WRONG — there is no /mcp subpath export
+// WRONG – there is no /mcp subpath export
 import { createMCPToolProvider } from "@directive-run/ai/mcp";
 
-// CORRECT — MCP adapter is exported from the main package
+// CORRECT – MCP adapter is exported from the main package
 import { createMCPAdapter } from "@directive-run/ai";
 ```
 
@@ -193,7 +193,7 @@ await enricher.ingestFile("./docs/architecture.md", {
 ## Enriching Prompts
 
 ```typescript
-// Basic enrichment — prepends relevant context
+// Basic enrichment – prepends relevant context
 const enrichedInput = await enricher.enrich("How do facts work?", {
   prefix: "Use this context to answer:\n",
 });

package/ai/ai-multi-agent.md

@@ -67,7 +67,7 @@ const orchestrator = createMultiAgentOrchestrator({
   runner,
 });
 
-// REQUIRED for multi-agent — must call start() before running patterns
+// REQUIRED for multi-agent – must call start() before running patterns
 orchestrator.start();
 
 const result = await orchestrator.runPattern("pipeline", "Write about AI");
@@ -75,7 +75,7 @@ const result = await orchestrator.runPattern("pipeline", "Write about AI");
 
 ## Pattern Details
 
-### parallel — Run agents concurrently, merge results
+### parallel – Run agents concurrently, merge results
 
 ```typescript
 const brainstorm = parallel(
@@ -91,21 +91,21 @@ const brainstorm = parallel(
 );
 ```
 
-### sequential — Chain agents in order
+### sequential – Chain agents in order
 
 ```typescript
 // Each agent receives the previous agent's output as its prompt
 const pipeline = sequential(["researcher", "writer", "editor"]);
 ```
 
-### supervisor — One agent delegates to workers
+### supervisor – One agent delegates to workers
 
 ```typescript
 // Editor decides which worker to invoke and when to stop
 const managed = supervisor("editor", ["researcher", "writer"]);
 ```
 
-### dag — Directed acyclic graph of dependencies
+### dag – Directed acyclic graph of dependencies
 
 ```typescript
 // DagNode shape
@@ -132,7 +132,7 @@ const workflow = dag([
 ]);
 ```
 
-### reflect — Agent critiques and revises its own output
+### reflect – Agent critiques and revises its own output
 
 ```typescript
 const selfImprove = reflect("writer", {
@@ -143,7 +143,7 @@ const selfImprove = reflect("writer", {
 });
 ```
 
-### race — First agent to finish wins
+### race – First agent to finish wins
 
 ```typescript
 const fastest = race(["researcher", "writer"], {
@@ -152,7 +152,7 @@ const fastest = race(["researcher", "writer"], {
 });
 ```
 
-### debate — Agents argue to consensus
+### debate – Agents argue to consensus
 
 ```typescript
 const consensus = debate(["researcher", "writer"], {
@@ -161,7 +161,7 @@ const consensus = debate(["researcher", "writer"], {
 });
 ```
 
-### goal — Iterate until a condition is met
+### goal – Iterate until a condition is met
 
 ```typescript
 const iterative = goal("researcher", {
@@ -220,7 +220,7 @@ const workflow = dag([
 ### #24: Forgetting start() for multi-agent
 
 ```typescript
-// WRONG — multi-agent orchestrators require explicit start()
+// WRONG – multi-agent orchestrators require explicit start()
 const orchestrator = createMultiAgentOrchestrator({ agents, runner });
 const result = await orchestrator.runPattern("pipeline", "prompt");
 // Error: Orchestrator not started
@@ -234,12 +234,12 @@ const result = await orchestrator.runPattern("pipeline", "prompt");
 ### #30: race minSuccess greater than agent count
 
 ```typescript
-// WRONG — minSuccess cannot exceed the number of agents
+// WRONG – minSuccess cannot exceed the number of agents
 const broken = race(["researcher", "writer"], {
   minSuccess: 3, // Only 2 agents, will never satisfy
 });
 
-// CORRECT — minSuccess <= agents.length
+// CORRECT – minSuccess <= agents.length
 const working = race(["researcher", "writer"], {
   minSuccess: 1,
 });
@@ -248,13 +248,13 @@ const working = race(["researcher", "writer"], {
 ### Reusing agent names across patterns
 
 ```typescript
-// WRONG — agent names must match keys in the agents config
+// WRONG – agent names must match keys in the agents config
 patterns: {
   pipeline: sequential(["research-agent", "write-agent"]),
   // These don't match the keys "researcher", "writer"
 },
 
-// CORRECT — use the exact keys from agents config
+// CORRECT – use the exact keys from agents config
 patterns: {
   pipeline: sequential(["researcher", "writer"]),
 },

package/ai/ai-orchestrator.md

@@ -156,13 +156,13 @@ const restored = createAgentOrchestrator({
 ### #21: TypeScript types instead of t.*() for factsSchema
 
 ```typescript
-// WRONG — TS types are erased at runtime, no schema validation
+// WRONG – TS types are erased at runtime, no schema validation
 const orchestrator = createAgentOrchestrator({
   runner,
   factsSchema: {} as { confidence: number; analysis: string },
 });
 
-// CORRECT — use t.*() builders for runtime schema
+// CORRECT – use t.*() builders for runtime schema
 const orchestrator = createAgentOrchestrator({
   runner,
   factsSchema: {
@@ -175,24 +175,24 @@ const orchestrator = createAgentOrchestrator({
 ### #22: Mutating arrays/objects in place
 
 ```typescript
-// WRONG — proxy cannot detect in-place mutations
+// WRONG – proxy cannot detect in-place mutations
 context.facts.cache.push("new-item");
 
-// CORRECT — replace the entire value
+// CORRECT – replace the entire value
 context.facts.cache = [...context.facts.cache, "new-item"];
 ```
 
 ### #23: Returning data from resolve
 
 ```typescript
-// WRONG — resolvers return void, not data
+// WRONG – resolvers return void, not data
 resolve: async (req, context) => {
   const result = await analyzeData(req.input);
 
   return result; // Return value is ignored
 },
 
-// CORRECT — mutate context.facts to store results
+// CORRECT – mutate context.facts to store results
 resolve: async (req, context) => {
   const result = await analyzeData(req.input);
   context.facts.analysis = result;
@@ -202,11 +202,11 @@ resolve: async (req, context) => {
 ### #24: Forgetting start() for multi-agent
 
 ```typescript
-// WRONG — multi-agent orchestrators require explicit start()
+// WRONG – multi-agent orchestrators require explicit start()
 const orchestrator = createMultiAgentOrchestrator({ agents, runner });
 const result = await orchestrator.runPattern("pipeline", "prompt");
 
-// CORRECT — call start() before running patterns
+// CORRECT – call start() before running patterns
 const orchestrator = createMultiAgentOrchestrator({ agents, runner });
 orchestrator.start();
 const result = await orchestrator.runPattern("pipeline", "prompt");

package/ai/ai-security.md

@@ -224,10 +224,10 @@ const orchestrator = createAgentOrchestrator({
 ### Input Validation
 
 ```typescript
-// WRONG — passing raw user input to the agent
+// WRONG – passing raw user input to the agent
 const result = await orchestrator.run(agent, userInput);
 
-// CORRECT — validate and sanitize input first
+// CORRECT – validate and sanitize input first
 const sanitized = sanitizeInput(userInput);
 const result = await orchestrator.run(agent, sanitized);
 ```

package/ai/ai-tasks.md

@@ -21,7 +21,7 @@ Does this work need an LLM?
 
 ```typescript
 interface TaskRegistration {
-  // The work function — input is ALWAYS a string
+  // The work function – input is ALWAYS a string
   run: (input: string, context: TaskContext) => Promise<string>;
 
   // Human-readable label for debugging/logging
@@ -184,11 +184,11 @@ tasks: {
 ### #33: Tasks calling agents internally
 
 ```typescript
-// WRONG — tasks cannot invoke agents
+// WRONG – tasks cannot invoke agents
 tasks: {
   enhance: {
     run: async (input, context) => {
-      // Tasks have no runner access — this won't work
+      // Tasks have no runner access – this won't work
       const result = await runner.run(someAgent, input);
 
       return result.output;
@@ -196,7 +196,7 @@ tasks: {
   },
 },
 
-// CORRECT — use a pattern to compose agents and tasks
+// CORRECT – use a pattern to compose agents and tasks
 patterns: {
   enhance: sequential(["enhancer-agent", "format-task"]),
 },
@@ -205,17 +205,17 @@ patterns: {
 ### #34: Expecting structured input (not a string)
 
 ```typescript
-// WRONG — task input is always a string
+// WRONG – task input is always a string
 tasks: {
   process: {
     run: async (input, context) => {
-      // input.items is undefined — input is a string
+      // input.items is undefined – input is a string
       return input.items.map((i) => i.name).join(", ");
     },
   },
 },
 
-// CORRECT — parse the string input
+// CORRECT – parse the string input
 tasks: {
   process: {
     run: async (input, context) => {
@@ -230,7 +230,7 @@ tasks: {
 ### #35: Task and agent IDs collide
 
 ```typescript
-// WRONG — "researcher" exists as both agent and task
+// WRONG – "researcher" exists as both agent and task
 agents: {
   researcher: { name: "researcher", instructions: "...", model: "claude-sonnet-4-5" },
 },
@@ -238,7 +238,7 @@ tasks: {
   researcher: { run: async (input) => input }, // Name collision!
 },
 
-// CORRECT — use distinct names
+// CORRECT – use distinct names
 agents: {
   researcher: { name: "researcher", instructions: "...", model: "claude-sonnet-4-5" },
 },

package/ai/ai-testing-evals.md

@@ -254,7 +254,7 @@ const evaluator = createEvaluator({
 ### Anti-Pattern #32: Side effects in evaluator scorer
 
 ```typescript
-// WRONG — scorers must be pure functions
+// WRONG – scorers must be pure functions
 {
   name: "quality",
   scorer: (input, output) => {
@@ -266,7 +266,7 @@ const evaluator = createEvaluator({
   },
 }
 
-// CORRECT — scorers are pure, return score + reason only
+// CORRECT – scorers are pure, return score + reason only
 {
   name: "quality",
   scorer: (input, output) => {