@directive-run/claude-plugin 1.16.0

package/skills/getting-started-with-directive/core-patterns.md

@@ -0,0 +1,240 @@
+# Core Patterns
+
+> Covers `@directive-run/core` — modules, facts, derivations, effects, events, and the constraint-resolver loop.
+
+How to think about building with Directive: modules, systems, and the constraint-resolver pattern.
+
+## Decision Tree: "Where does this logic go?"
+
+```
+User wants to...
+├── Store state → schema.facts + init()
+├── Compute derived values → schema.derivations + derive
+├── React to state changes → effects
+├── Trigger side effects when conditions are met → constraints + resolvers
+├── Handle user actions → schema.events + events handlers
+└── Coordinate multiple modules → createSystem({ modules: {} })
+```
+
+## Module Shape (Canonical Object Syntax)
+
+```typescript
+// CORRECT – full module definition
+import { createModule, t } from "@directive-run/core";
+
+const myModule = createModule("name", {
+  schema: {
+    facts: {
+      count: t.number(),
+      phase: t.string<"idle" | "loading" | "done">(),
+      user: t.object<{ id: string; name: string } | null>(),
+    },
+    derivations: {
+      isLoading: t.boolean(),
+      displayName: t.string(),
+    },
+    events: {
+      increment: {},
+      setUser: { user: t.object<{ id: string; name: string }>() },
+    },
+    requirements: {
+      FETCH_USER: { userId: t.string() },
+    },
+  },
+
+  init: (facts) => {
+    facts.count = 0;
+    facts.phase = "idle";
+    facts.user = null;
+  },
+
+  derive: {
+    isLoading: (facts) => facts.phase === "loading",
+    displayName: (facts) => {
+      if (!facts.user) {
+        return "Guest";
+      }
+
+      return facts.user.name;
+    },
+  },
+
+  effects: {
+    logPhase: {
+      run: (facts, prev) => {
+        if (prev?.phase !== facts.phase) {
+          console.log(`Phase: ${facts.phase}`);
+        }
+      },
+    },
+  },
+
+  constraints: {
+    fetchWhenReady: {
+      when: (facts) => facts.phase === "idle" && facts.count > 0,
+      require: (facts) => ({ type: "FETCH_USER", userId: "user-1" }),
+    },
+  },
+
+  resolvers: {
+    fetchUser: {
+      requirement: "FETCH_USER",
+      resolve: async (req, context) => {
+        context.facts.phase = "loading";
+        const res = await fetch(`/api/users/${req.userId}`);
+        const data = await res.json();
+        context.facts.user = data;
+        context.facts.phase = "done";
+      },
+    },
+  },
+
+  events: {
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    setUser: (facts, payload) => {
+      facts.user = payload.user;
+    },
+  },
+});
+```
+
+## System Creation
+
+```typescript
+import { createSystem } from "@directive-run/core";
+import { loggingPlugin, devtoolsPlugin } from "@directive-run/core/plugins";
+
+// Single module – direct access: system.facts.count
+const system = createSystem({
+  module: myModule,
+  plugins: [loggingPlugin(), devtoolsPlugin()],
+  history: { maxSnapshots: 100 },
+});
+
+// Multi-module – namespaced access: system.facts.auth.token
+const system = createSystem({
+  modules: { auth: authModule, cart: cartModule },
+  plugins: [devtoolsPlugin()],
+});
+
+// Lifecycle
+system.start();
+await system.settle(); // Wait for all resolvers to complete
+// ... use the system ...
+system.stop();
+system.destroy();
+```
+
+## Decision Tree: "User says 'fetch data when authenticated'"
+
+WRONG thinking: "I'll put the fetch call in a resolver that checks auth."
+
+```typescript
+// WRONG – resolver doing condition checking + data fetching
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      if (!context.facts.isAuthenticated) {
+        return; // Resolver should not check conditions
+      }
+      const data = await fetch("/api/data");
+      context.facts.data = await data.json();
+    },
+  },
+},
+```
+
+CORRECT thinking: "Constraint declares WHEN, resolver declares HOW."
+
+```typescript
+// CORRECT – constraint declares the need, resolver fulfills it
+constraints: {
+  fetchWhenAuthenticated: {
+    when: (facts) => facts.isAuthenticated && !facts.data,
+    require: { type: "FETCH_DATA" },
+  },
+},
+
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      const data = await fetch("/api/data");
+      context.facts.data = await data.json();
+    },
+  },
+},
+```
+
+## Reading System State
+
+```typescript
+// Facts – mutable state
+system.facts.count = 5;
+const val = system.facts.count;
+
+// Derivations – read-only computed values
+const loading = system.derive.isLoading;
+
+// Events – dispatch user actions
+system.events.increment();
+system.events.setUser({ user: { id: "1", name: "Alice" } });
+
+// Subscribe to changes
+const unsub = system.subscribe(["count", "isLoading"], () => {
+  console.log(system.facts.count, system.derive.isLoading);
+});
+
+// Watch individual values
+system.watch("count", (newVal, oldVal) => {
+  console.log(`Count: ${oldVal} -> ${newVal}`);
+});
+
+// Wait for a condition
+await system.when((facts) => facts.phase === "done");
+await system.when((facts) => facts.phase === "done", { timeout: 5000 });
+```
+
+## Schema Patterns
+
+Only `facts` is required in the schema. Other sections are optional:
+
+```typescript
+// Minimal module – facts only
+const minimal = createModule("minimal", {
+  schema: {
+    facts: { count: t.number() },
+  },
+  init: (facts) => {
+    facts.count = 0;
+  },
+});
+
+// Type assertion pattern (alternative to t.* builders)
+const typed = createModule("typed", {
+  schema: {
+    facts: {} as { count: number; name: string },
+    derivations: {} as { doubled: number },
+  },
+  init: (facts) => {
+    facts.count = 0;
+    facts.name = "";
+  },
+  derive: {
+    doubled: (facts) => facts.count * 2,
+  },
+});
+```
+
+## See also
+
+- [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
+- [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
+- [`multi-module.md`](./multi-module.md) — when a single module isn't enough
+- [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined
+- [`naming.md`](./naming.md) — terminology conventions every example here follows
+- [`testing.md`](./testing.md) — `createTestSystem` for the modules you're learning to write

package/skills/getting-started-with-directive/examples.md

@@ -0,0 +1,87 @@
+# Examples
+
+> Auto-generated from extracted examples. Do not edit manually.
+
+## counter
+
+```typescript
+// Example: counter
+// Source: examples/counter/src/module.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Counter — The simplest Directive module.
+ *
+ * Demonstrates: facts, events, derivations, one constraint, one resolver.
+ * Total: ~40 lines.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+
+const schema = {
+  facts: {
+    count: t.number(),
+  },
+  derivations: {
+    doubled: t.number(),
+    isPositive: t.boolean(),
+  },
+  events: {
+    increment: {},
+    decrement: {},
+    reset: {},
+  },
+  requirements: {
+    CLAMP_TO_ZERO: {},
+  },
+} satisfies ModuleSchema;
+
+export const counterModule = createModule("counter", {
+  schema,
+
+  init: (facts) => {
+    facts.count = 0;
+  },
+
+  derive: {
+    doubled: (facts) => facts.count * 2,
+    isPositive: (facts) => facts.count > 0,
+  },
+
+  events: {
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    decrement: (facts) => {
+      facts.count -= 1;
+    },
+    reset: (facts) => {
+      facts.count = 0;
+    },
+  },
+
+  // When count goes negative, automatically fix it
+  constraints: {
+    noNegative: {
+      when: (facts) => facts.count < 0,
+      require: { type: "CLAMP_TO_ZERO" },
+    },
+  },
+
+  resolvers: {
+    clamp: {
+      requirement: "CLAMP_TO_ZERO",
+      resolve: async (_req, context) => {
+        context.facts.count = 0;
+      },
+    },
+  },
+});
+
+export const system = createSystem({ module: counterModule });
+```

package/skills/getting-started-with-directive/sitemap.md

@@ -0,0 +1,202 @@
+# Directive Documentation Sitemap
+
+> Auto-generated from the docs site navigation. Do not edit manually.
+> Run `pnpm --filter @directive-run/knowledge generate-sitemap` to refresh.
+
+Website: https://directive.run
+
+## Docs
+
+### Getting Started
+- [Quick Start](https://directive.run/docs/quick-start)
+- [Why Directive](https://directive.run/docs/why-directive)
+- [Installation](https://directive.run/docs/installation)
+- [Core Concepts](https://directive.run/docs/core-concepts)
+- [Comparison](https://directive.run/docs/comparison)
+- [Choosing Primitives](https://directive.run/docs/choosing-primitives)
+
+### Core API
+- [Overview](https://directive.run/docs/core-api)
+- [Module & System](https://directive.run/docs/module-system)
+- [Facts](https://directive.run/docs/facts)
+- [Derivations](https://directive.run/docs/derivations)
+- [Constraints](https://directive.run/docs/constraints)
+- [Resolvers](https://directive.run/docs/resolvers)
+- [Effects](https://directive.run/docs/effects)
+- [Events](https://directive.run/docs/events)
+- [Schema & Types](https://directive.run/docs/schema-overview)
+- [API Reference](https://directive.run/docs/api/core)
+- [Type Reference](https://directive.run/docs/api/types)
+
+### Framework Adapters
+- [Overview](https://directive.run/docs/adapters/overview)
+- [React](https://directive.run/docs/adapters/react)
+- [React API](https://directive.run/docs/api/react)
+- [Vue](https://directive.run/docs/adapters/vue)
+- [Vue API](https://directive.run/docs/api/vue)
+- [Svelte](https://directive.run/docs/adapters/svelte)
+- [Svelte API](https://directive.run/docs/api/svelte)
+- [Solid](https://directive.run/docs/adapters/solid)
+- [Solid API](https://directive.run/docs/api/solid)
+- [Lit](https://directive.run/docs/adapters/lit)
+- [Lit API](https://directive.run/docs/api/lit)
+- [Vanilla](https://directive.run/docs/adapters/vanilla)
+- [Vanilla API](https://directive.run/docs/api/vanilla)
+
+### Data Fetching
+- [Overview](https://directive.run/docs/data-fetching/overview)
+- [Queries](https://directive.run/docs/data-fetching/queries)
+- [Mutations](https://directive.run/docs/data-fetching/mutations)
+- [Subscriptions](https://directive.run/docs/data-fetching/subscriptions)
+- [Infinite Queries](https://directive.run/docs/data-fetching/infinite)
+- [Convenience API](https://directive.run/docs/data-fetching/convenience)
+- [GraphQL](https://directive.run/docs/data-fetching/graphql)
+- [Explain & Debug](https://directive.run/docs/data-fetching/explain)
+
+### Advanced Patterns
+- [Overview](https://directive.run/docs/advanced/overview)
+- [Data-form Definitions](https://directive.run/docs/data-triggers)
+- [Resolver Binding (owns)](https://directive.run/docs/resolver-binding)
+- [Multi-Module](https://directive.run/docs/advanced/multi-module)
+- [Runtime Dynamics](https://directive.run/docs/advanced/runtime)
+- [History & Snapshots](https://directive.run/docs/advanced/history)
+- [SSR & Hydration](https://directive.run/docs/advanced/ssr)
+- [Error Boundaries](https://directive.run/docs/advanced/errors)
+- [Definition Meta](https://directive.run/docs/advanced/meta)
+
+### Predicate Tools
+- [predicateFromIntent (LLM emit)](https://directive.run/docs/predicate-from-intent)
+- [describePredicate (prose)](https://directive.run/docs/describe-predicate)
+- [Predicate Codegen (SQL/Mongo/PostgREST)](https://directive.run/docs/predicate-codegen)
+- [predict()](https://directive.run/docs/predict)
+- [doctor.checkAgainst()](https://directive.run/docs/doctor)
+- [Predicate Backtest (replay-under)](https://directive.run/docs/replay-under)
+- [Parameter Sweep (tune)](https://directive.run/docs/tune)
+- [Rules Diff](https://directive.run/docs/rules-diff)
+
+### Plugins
+- [Overview](https://directive.run/docs/plugins/overview)
+- [Logging](https://directive.run/docs/plugins/logging)
+- [DevTools](https://directive.run/docs/plugins/devtools)
+- [DevTools – whenExplain panel](https://directive.run/docs/when-explain-panel)
+- [Persistence](https://directive.run/docs/plugins/persistence)
+- [Performance](https://directive.run/docs/plugins/performance)
+- [Circuit Breaker](https://directive.run/docs/plugins/circuit-breaker)
+- [Audit Ledger](https://directive.run/docs/audit-ledger)
+- [Observability](https://directive.run/docs/plugins/observability)
+- [Custom Plugins](https://directive.run/docs/plugins/custom)
+
+### Packages
+- [Timeline (test REPL)](https://directive.run/docs/packages/timeline)
+- [Mutator (typed mutations)](https://directive.run/docs/packages/mutator)
+- [Optimistic (auto-rollback)](https://directive.run/docs/packages/optimistic)
+- [Query (data fetching)](https://directive.run/docs/packages/query)
+- [Vite Dev Proxy](https://directive.run/docs/packages/vite-dev-proxy)
+- [Composing all four](https://directive.run/docs/packages/composing-packages)
+
+### Testing
+- [Overview](https://directive.run/docs/testing/overview)
+- [Mock Resolvers](https://directive.run/docs/testing/mock-resolvers)
+- [Fake Timers](https://directive.run/docs/testing/fake-timers)
+- [Assertions](https://directive.run/docs/testing/assertions)
+- [Test Async Chains](https://directive.run/docs/guides/test-async-chains)
+
+### Examples
+- [Number Match](https://directive.run/docs/examples/counter)
+- [Auth Flow](https://directive.run/docs/examples/auth-flow)
+- [Shopping Cart](https://directive.run/docs/examples/shopping-cart)
+- [Async Chains](https://directive.run/docs/examples/async-chains)
+- [Form Wizard](https://directive.run/docs/examples/form-wizard)
+- [Sudoku](https://directive.run/docs/examples/sudoku)
+- [Checkers](https://directive.run/docs/examples/checkers)
+- [Time Machine](https://directive.run/docs/examples/time-machine)
+- [Error Boundaries](https://directive.run/docs/examples/error-boundaries)
+- [Fraud Analysis](https://directive.run/docs/examples/fraud-analysis)
+- [Dashboard Loader](https://directive.run/docs/examples/dashboard-loader)
+- [Compliance Audit](https://directive.run/docs/examples/compliance-audit)
+
+### Guides
+- [Overview](https://directive.run/docs/guides/overview)
+- [Loading & Error States](https://directive.run/docs/guides/loading-states)
+- [Authentication Flow](https://directive.run/docs/guides/auth-flow)
+- [Optimistic Updates](https://directive.run/docs/guides/optimistic-updates)
+- [Shopping Cart Rules](https://directive.run/docs/guides/shopping-cart)
+- [Multi-Step Form Wizard](https://directive.run/docs/guides/form-wizard)
+
+### Async Chains Across Modules
+- [Role-Based Permissions](https://directive.run/docs/guides/permissions)
+- [Batch Mutations](https://directive.run/docs/guides/batch-mutations)
+
+### Integration Guides
+- [Overview](https://directive.run/docs/works-with/overview)
+- [Redux](https://directive.run/docs/works-with/redux)
+- [Zustand](https://directive.run/docs/works-with/zustand)
+- [XState](https://directive.run/docs/works-with/xstate)
+- [React Query](https://directive.run/docs/works-with/react-query)
+- [Web Worker](https://directive.run/docs/works-with/worker)
+
+## AI
+
+### Foundations
+- [Overview](https://directive.run/ai/overview)
+- [Running Agents](https://directive.run/ai/running-agents)
+- [Resilience & Routing](https://directive.run/ai/resilience-routing)
+- [Comparison](https://directive.run/ai/comparison)
+- [Tutorial](https://directive.run/ai/tutorial)
+- [Troubleshooting](https://directive.run/ai/troubleshooting)
+
+### Agent Orchestrator
+- [Overview](https://directive.run/ai/orchestrator)
+- [Guardrails](https://directive.run/ai/guardrails)
+- [Streaming](https://directive.run/ai/streaming)
+- [Memory](https://directive.run/ai/memory)
+
+### Multi-Agent Orchestrator
+- [Overview](https://directive.run/ai/multi-agent)
+- [Execution Patterns](https://directive.run/ai/patterns)
+- [Communication](https://directive.run/ai/communication)
+- [Cross-Agent State](https://directive.run/ai/cross-agent-state)
+- [Tasks](https://directive.run/ai/tasks)
+- [Self-Healing](https://directive.run/ai/self-healing)
+
+### Infrastructure
+- [MCP Integration](https://directive.run/ai/mcp)
+- [RAG Enricher](https://directive.run/ai/rag)
+- [SSE Transport](https://directive.run/ai/sse-transport)
+- [Semantic Cache](https://directive.run/ai/semantic-cache)
+
+### Observability
+- [Debug Timeline](https://directive.run/ai/debug-timeline)
+- [Pattern Checkpoints](https://directive.run/ai/checkpoints)
+- [Breakpoints & Checkpoints](https://directive.run/ai/breakpoints)
+- [DevTools](https://directive.run/ai/devtools)
+
+### Security & Compliance
+- [Overview](https://directive.run/ai/security/overview)
+- [PII Detection](https://directive.run/ai/security/pii)
+- [Prompt Injection](https://directive.run/ai/security/prompt-injection)
+- [Audit Trail](https://directive.run/ai/security/audit)
+- [GDPR/CCPA](https://directive.run/ai/security/compliance)
+
+### Examples
+- [Chat](https://directive.run/ai/examples/chat)
+- [Research Pipeline](https://directive.run/ai/examples/research-pipeline)
+- [Safety Shield](https://directive.run/ai/examples/safety-shield)
+- [Checkpoint](https://directive.run/ai/examples/checkpoint)
+- [Fraud Analysis](https://directive.run/ai/examples/fraud-analysis)
+- [Pitch Deck](https://directive.run/ai/examples/pitch-deck)
+- [Data Pipeline](https://directive.run/ai/examples/data-pipeline)
+- [Code Review](https://directive.run/ai/examples/code-review)
+
+### Human Approval Workflows
+- [Control AI Costs](https://directive.run/ai/guides/control-ai-costs)
+
+### Validate Structured Output
+- [Handle Agent Errors](https://directive.run/ai/guides/handle-agent-errors)
+
+### Stream Agent Responses
+- [Multi-Step Pipeline](https://directive.run/ai/guides/multi-step-pipeline)
+
+### Test Without LLM Calls
+- [DAG Pipeline](https://directive.run/ai/guides/dag-pipeline)
+- [Goal Pipeline](https://directive.run/ai/guides/goal-pipeline)