@directive-run/claude-plugin 1.16.0

package/skills/building-directive-systems/system-api.md

@@ -0,0 +1,463 @@
+# System API
+
+> Covers `@directive-run/core` — `createSystem`, the system instance surface, hydration, inspection, distributable snapshots.
+
+The system is created with `createSystem()` and is the runtime that orchestrates modules, constraints, resolvers, and plugins.
+
+## Decision Tree: "How do I interact with the system?"
+
+```
+What do you want to do?
+├── Read/write state → system.facts.fieldName
+├── Read computed values → system.derive.derivationName
+├── Dispatch user actions → system.events.eventName(payload)
+├── React to changes → system.subscribe() or system.watch()
+├── Wait for a condition → system.when()
+├── Wait for all async to finish → system.settle()
+├── Debug/inspect current state → system.inspect()
+├── Control lifecycle → system.start() / system.stop() / system.destroy()
+└── Multi-module access → system.facts.moduleName.fieldName
+```
+
+## Creating a System
+
+```typescript
+import { createSystem } from "@directive-run/core";
+import { loggingPlugin, devtoolsPlugin } from "@directive-run/core/plugins";
+
+// Single module – direct access to facts/derive/events
+const system = createSystem({
+  module: myModule,
+  plugins: [loggingPlugin(), devtoolsPlugin()],
+  history: { maxSnapshots: 100 },
+});
+
+// Multi-module – namespaced access
+const system = createSystem({
+  modules: {
+    auth: authModule,
+    cart: cartModule,
+    ui: uiModule,
+  },
+  plugins: [devtoolsPlugin()],
+});
+```
+
+## Facts: Reading and Writing State
+
+```typescript
+// Single module
+system.facts.count = 5;
+const val = system.facts.count;
+
+// Multi-module – access through module namespace
+system.facts.auth.token = "abc123";
+system.facts.cart.items = [];
+const token = system.facts.auth.token;
+```
+
+Facts are proxy-based. Mutations are tracked automatically and trigger derivation recomputation, constraint evaluation, and effect execution.
+
+## Derivations: Reading Computed Values
+
+```typescript
+// Single module
+const loading = system.derive.isLoading;
+const display = system.derive.displayName;
+
+// Multi-module
+const isAdmin = system.derive.auth.isAdmin;
+const total = system.derive.cart.totalPrice;
+```
+
+Derivations are read-only. They recompute lazily when their tracked facts change.
+
+## Events: Dispatching Actions
+
+```typescript
+// Single module
+system.events.increment();
+system.events.setUser({ user: { id: "1", name: "Alice" } });
+
+// Multi-module
+system.events.auth.login({ email: "alice@example.com" });
+system.events.cart.addItem({ productId: "p1", quantity: 2 });
+```
+
+Events are synchronous. They mutate facts in the event handler, which triggers the reactive pipeline.
+
+## Subscribing to Changes
+
+```typescript
+// Subscribe to specific keys (facts or derivations)
+const unsub = system.subscribe(["count", "isLoading"], () => {
+  console.log(system.facts.count, system.derive.isLoading);
+});
+
+// Watch a single value with old/new
+system.watch("count", (newVal, oldVal) => {
+  console.log(`Count: ${oldVal} -> ${newVal}`);
+});
+
+// Unsubscribe
+unsub();
+```
+
+## Waiting for Conditions
+
+```typescript
+// Wait until a condition is true
+await system.when((facts) => facts.phase === "done");
+
+// With timeout – throws if condition not met in time
+await system.when((facts) => facts.phase === "done", { timeout: 5000 });
+```
+
+## Settling: Waiting for Async Completion
+
+```typescript
+system.start();
+
+// Wait for all resolvers and async constraints to complete
+await system.settle();
+
+// With timeout
+await system.settle(5000); // Throws if not settled in 5s
+
+// Check settlement state synchronously
+if (system.isSettled) {
+  console.log("All resolvers complete");
+}
+
+// Subscribe to settlement changes
+const unsub = system.onSettledChange(() => {
+  console.log("Settlement:", system.isSettled);
+});
+```
+
+## Reading by Key
+
+```typescript
+// Read fact or derivation by string key
+const count = system.read("count");
+const isLoading = system.read("isLoading");
+
+// Multi-module – use dot notation
+const token = system.read("auth.token");
+const total = system.read("cart.totalPrice");
+```
+
+## Inspecting System State
+
+```typescript
+const inspection = system.inspect();
+
+// Unmet requirements
+inspection.unmet;
+// [{ id: "req-1", requirement: { type: "FETCH_USER" }, fromConstraint: "needsUser" }]
+
+// Inflight resolvers
+inspection.inflight;
+// [{ id: "req-2", resolverId: "fetchData", startedAt: 1709000000 }]
+
+// Facts with meta
+inspection.facts;
+// [{ key: "userId", meta: { label: "User ID" } }, { key: "count" }]
+
+// Constraints with state + meta
+inspection.constraints;
+// [{ id: "needsUser", active: true, disabled: false, priority: 0, hitCount: 3, meta: { label: "..." } }]
+
+// Resolver definitions + meta
+inspection.resolverDefs;
+// [{ id: "fetchUser", requirement: "FETCH_USER", meta: { label: "..." } }]
+
+// Resolver statuses (inflight only)
+inspection.resolvers;
+// { "req-1": { state: "running" } }
+
+// Effects, derivations, modules — all with optional meta
+inspection.effects;     // [{ id: "log", meta: { ... } }]
+inspection.derivations; // [{ id: "doubled", meta: { ... } }]
+inspection.modules;     // [{ id: "auth", meta: { ... } }]
+inspection.events;      // [{ name: "increment", meta: { ... } }]
+
+// Unmet requirements (no matching resolver)
+inspection.unmet;
+
+// Explain why a requirement exists (uses meta.label + meta.description)
+const explanation = system.explain("req-123");
+```
+
+## Definition Meta
+
+Attach optional metadata to any definition for debugging, devtools, and AI context:
+
+```typescript
+// On constraints, resolvers, effects — meta field
+constraints: {
+  needsAuth: {
+    when: (f) => !f.user,
+    require: { type: "LOGIN" },
+    meta: { label: "Requires Auth", category: "auth", tags: ["critical"] },
+  },
+},
+
+// On derivations — { compute, meta } object form
+derive: {
+  displayName: {
+    compute: (f) => `${f.first} ${f.last}`,
+    meta: { label: "Display Name" },
+  },
+},
+
+// On facts — chainable .meta()
+schema: { facts: { email: t.string().meta({ label: "Email", tags: ["pii"] }) } },
+
+// On modules
+meta: { label: "Auth Module", category: "auth" },
+
+// O(1) accessor
+system.meta.constraint("needsAuth")?.label;  // "Requires Auth"
+system.meta.fact("email")?.tags;             // ["pii"]
+system.meta.module("auth")?.label;           // "Auth Module"
+
+// Bulk queries
+system.meta.byCategory("auth");  // MetaMatch[] — all auth definitions
+system.meta.byTag("pii");        // MetaMatch[] — all PII-tagged fields
+```
+
+Meta is frozen at registration (Object.create(null) + Object.freeze). Zero hot-path cost. See [Definition Meta docs](https://directive.run/docs/advanced/meta).
+
+## Observation Protocol
+
+Typed event stream for all lifecycle events — enables browser extensions, third-party tools, and test assertions:
+
+```typescript
+import type { ObservationEvent } from "@directive-run/core";
+
+const unsub = system.observe((event: ObservationEvent) => {
+  if (event.type === "constraint.evaluate") console.log(event.id, event.active);
+  if (event.type === "resolver.complete") console.log(event.resolver, event.duration);
+  if (event.type === "fact.change") console.log(event.key, event.prev, "→", event.next);
+});
+
+// 18 event types: fact.change, constraint.evaluate/error, requirement.created/met/canceled,
+// resolver.start/complete/error, effect.run/error, derivation.compute,
+// reconcile.start/end, system.init/start/stop/destroy
+
+unsub(); // Stop observing
+```
+
+Zero overhead when no observers. Implemented as an internal plugin.
+
+## Lifecycle
+
+```typescript
+// Start – begins constraint evaluation and reconciliation
+system.start();
+
+// Stop – pauses evaluation, cancels inflight resolvers
+system.stop();
+
+// Destroy – cleans up all resources, subscriptions, plugins
+system.destroy();
+
+// Lifecycle order:
+// createSystem() → system.start() → ... → system.stop() → system.destroy()
+```
+
+`system.start()` is auto-called in most cases. Call it explicitly when you need to set up subscriptions before the first evaluation cycle.
+
+## Constraint Control at Runtime
+
+```typescript
+// Disable a constraint – it won't be evaluated
+system.constraints.disable("fetchWhenReady");
+
+// Check if disabled
+system.constraints.isDisabled("fetchWhenReady"); // true
+
+// Re-enable – triggers re-evaluation on next cycle
+system.constraints.enable("fetchWhenReady");
+```
+
+## SSR and Hydration
+
+Four mechanisms for populating a system with external state:
+
+```typescript
+// 1. initialFacts – simplest, at construction time
+const system = createSystem({
+  module: myModule,
+  initialFacts: { userId: "user-1", name: "Alice" },
+});
+system.start();
+
+// 2. system.hydrate() – async, before start()
+const system = createSystem({ module: myModule });
+await system.hydrate(async () => {
+  const res = await fetch('/api/state');
+
+  return res.json();
+});
+system.start();
+
+// 3. system.restore() – sync, applies facts from a snapshot
+const system = createSystem({ module: myModule });
+system.restore(serverSnapshot);
+system.start();
+
+// 4. DirectiveHydrator + useHydratedSystem (React only)
+// Server: getDistributableSnapshot() → serialize
+// Client: <DirectiveHydrator snapshot={s}><App /></DirectiveHydrator>
+//         useHydratedSystem(module) inside App
+```
+
+### SSR Lifecycle
+
+```typescript
+// Server: create → start → settle → snapshot → destroy
+const system = createSystem({
+  module: pageModule,
+  initialFacts: { userId: req.user.id },
+});
+system.start();
+await system.settle(5000); // Throws on timeout
+const snapshot = system.getSnapshot();
+system.stop();
+system.destroy();
+```
+
+### Snapshot Types
+
+- `SystemSnapshot` – facts only, used with `getSnapshot()` / `restore()`
+- `DistributableSnapshot` – facts + derivations + metadata + TTL, used with `getDistributableSnapshot()` and `DirectiveHydrator`
+
+### Avoiding Singletons
+
+Never use module-level systems in SSR – they share state across concurrent requests. Always create a fresh system per request and destroy it when done.
+
+## Runtime Dynamics
+
+All four subsystems (constraints, resolvers, derivations, effects) share a uniform dynamic definition interface:
+
+### Enable / Disable (Constraints & Effects only)
+
+```typescript
+system.constraints.disable("id");
+system.constraints.enable("id");
+system.constraints.isDisabled("id");
+
+system.effects.disable("id");
+system.effects.enable("id");
+system.effects.isEnabled("id");
+```
+
+### Register / Assign / Unregister (All 4 subsystems)
+
+```typescript
+// Register a new definition at runtime
+system.constraints.register("id", { when: ..., require: ... });
+system.resolvers.register("id", { requirement: "TYPE", resolve: ... });
+system.derive.register("id", (facts) => facts.count * 3);
+system.effects.register("id", { run: (facts) => { ... } });
+
+// Override an existing definition
+system.constraints.assign("id", { when: ..., require: ... });
+
+// Remove a dynamically registered definition (static = no-op + dev warning)
+system.constraints.unregister("id");
+```
+
+Semantics: `register` throws if ID exists. `assign` throws if ID doesn't exist. `unregister` on static ID = dev warning, no-op. All three are deferred if called during reconciliation.
+
+### Introspection
+
+```typescript
+system.constraints.isDynamic("id");  // true if registered at runtime
+system.constraints.listDynamic();    // all dynamic constraint IDs
+```
+
+### getOriginal / restoreOriginal
+
+When `assign()` overrides a static definition, the original is saved:
+
+```typescript
+system.getOriginal("constraint", "id");    // returns original definition
+system.restoreOriginal("constraint", "id"); // restores it, returns true/false
+```
+
+### Dynamic Module Registration
+
+```typescript
+system.registerModule("chat", chatModule); // adds module to running system
+```
+
+See docs: https://directive.run/docs/advanced/runtime
+
+## Common Mistakes
+
+### Reading facts before settling
+
+```typescript
+// WRONG – resolver hasn't completed, facts are stale
+system.start();
+console.log(system.facts.user); // null
+
+// CORRECT – wait for async resolution
+system.start();
+await system.settle();
+console.log(system.facts.user); // { id: "1", name: "Alice" }
+```
+
+### Casting facts/derivations unnecessarily
+
+```typescript
+// WRONG – the schema already provides types
+const profile = system.facts.profile as ResourceState<Profile>;
+
+// CORRECT – types are inferred from the schema
+const profile = system.facts.profile;
+```
+
+### Using single-line returns without braces
+
+```typescript
+// WRONG
+system.watch("phase", (val) => { if (val === "done") return; });
+
+// CORRECT
+system.watch("phase", (val) => {
+  if (val === "done") {
+    return;
+  }
+});
+```
+
+### Forgetting to destroy
+
+```typescript
+// WRONG – resources leak
+function setupSystem() {
+  const system = createSystem({ module: myModule });
+  system.start();
+
+  return system;
+}
+
+// CORRECT – clean up when done
+const system = createSystem({ module: myModule });
+system.start();
+// ... when finished:
+system.stop();
+system.destroy();
+```
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — the modules that go into `createSystem({ module: ... })`
+- [`multi-module.md`](./multi-module.md) — `createSystem({ modules: { ... } })` for namespaced systems
+- [`history.md`](./history.md) — the `history:` config and the `system.history.*` time-travel surface
+- [`plugins.md`](./plugins.md) — the `plugins:` config and the lifecycle hooks plugins observe
+- [`react-adapter.md`](./react-adapter.md) — consuming a system from React components

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

@@ -0,0 +1,198 @@
+---
+name: getting-started-with-directive
+description: "Understand Directive fundamentals: what modules, facts, derivations, constraints, resolvers, and systems are, and how they fit together. Use when someone is new to Directive, asks 'what is Directive', wants to understand the mental model, or needs help choosing between Directive concepts."
+---
+
+# Getting Started with Directive
+
+## Prerequisites
+
+This skill applies when the project uses `@directive-run/core`. If not found in `package.json`, suggest installing it: `npm install @directive-run/core`.
+
+## When Claude Should Use This Skill
+
+### Auto-Invoke Triggers
+- User asks "what is Directive" or "how does Directive work"
+- User is new to Directive and needs orientation
+- User asks about the relationship between facts, constraints, and resolvers
+- User asks "should I use a constraint or an effect" or similar conceptual questions
+- User wants to understand the Directive mental model before writing code
+
+### Exclusions – Use a Different Skill
+- User already knows Directive and wants to write a specific module → `writing-directive-modules`
+- User asks about specific constraint/resolver patterns → `writing-directive-constraints`
+- User asks about multi-module systems or React → `building-directive-systems`
+- User asks about testing → `testing-directive-code`
+- User asks about AI agents → `building-ai-orchestrators`
+
+---
+
+## Directive Mental Model
+
+Directive is a **constraint-driven runtime** for TypeScript. Instead of imperative state management, you:
+
+1. **Declare facts** – observable state values
+2. **Derive** computed values – auto-tracked, no manual deps
+3. **Set constraints** – conditions that must be true (when X, require Y)
+4. **Write resolvers** – how to fulfill requirements (async handlers)
+5. **Compose into systems** – wire modules together with plugins
+
+The runtime watches your facts, evaluates constraints, and dispatches requirements to resolvers automatically.
+
+## Core Concepts Flow
+
+```
+Facts (state) → Derivations (computed)
+     ↓
+Constraints (when/require) → Requirements → Resolvers (async handlers)
+     ↓
+Effects (side effects, logging, sync)
+```
+
+## Key Terminology
+
+| Term | What it is | Analogy |
+|------|-----------|---------|
+| **Fact** | A piece of observable state | Redux store field |
+| **Derivation** | Auto-tracked computed value | Recoil selector |
+| **Constraint** | "When X is true, require Y" declaration | Business rule |
+| **Requirement** | A typed request emitted by a constraint | Redux action |
+| **Resolver** | Async handler that fulfills requirements | Redux thunk |
+| **Effect** | Fire-and-forget side effect on fact changes | useEffect |
+| **Module** | Bundle of schema + init + derive + constraints + resolvers | Feature slice |
+| **System** | Runtime that wires modules together | Redux store |
+
+## Minimal Example
+
+```typescript
+import { createModule, createSystem, t } from "@directive-run/core";
+
+const counter = createModule("counter", {
+  schema: {
+    facts: {
+      count: t.number(),
+      limit: t.number(),
+    },
+  },
+
+  init: (facts) => {
+    facts.count = 0;
+    facts.limit = 10;
+  },
+
+  derive: {
+    isAtLimit: (facts) => facts.count >= facts.limit,
+    remaining: (facts) => facts.limit - facts.count,
+  },
+
+  constraints: {
+    enforceLimit: {
+      when: (facts) => facts.count > facts.limit,
+      require: { type: "RESET_COUNT" },
+    },
+  },
+
+  resolvers: {
+    resetCount: {
+      requirement: "RESET_COUNT",
+      resolve: async (req, context) => {
+        context.facts.count = context.facts.limit;
+      },
+    },
+  },
+});
+
+const system = createSystem({ module: counter });
+
+// Read state
+console.log(system.facts.count);     // 0
+console.log(system.derive.isAtLimit); // false
+
+// Mutate – constraints auto-evaluate
+system.facts.count = 15;
+// → constraint fires → resolver resets count to limit
+```
+
+## When to Use What
+
+```
+Need to store state?                    → schema + init (facts)
+Need computed values from state?        → derive (derivations)
+Need "if X then do Y" business logic?   → constraint + resolver
+Need side effects (logging, sync)?      → effect
+Need to compose multiple features?      → multi-module system
+Need lifecycle hooks?                   → plugins
+```
+
+## Decision Tree: Constraint vs Effect vs Direct Mutation
+
+```
+Is it a business rule (if X then Y)?
+├── YES → Constraint + Resolver
+│   Examples: auth redirect, data fetch, validation enforcement
+│
+├── NO → Does it modify facts?
+│   ├── YES → Direct mutation (system.facts.x = y)
+│   │   Examples: user input, button click handlers
+│   │
+│   └── NO → Effect
+│       Examples: logging, analytics, DOM sync, external API sync
+```
+
+## Common Patterns
+
+### Schema Type Builders
+
+```typescript
+schema: {
+  facts: {
+    name: t.string(),                           // string
+    age: t.number(),                            // number
+    active: t.boolean(),                        // boolean
+    role: t.string<"admin" | "user">(),         // union type
+    profile: t.object<{ name: string }>(),      // typed object
+    tags: t.array<string>(),                    // typed array
+    data: t.object<Profile | null>(),           // nullable
+  },
+}
+```
+
+### Naming Convention
+
+```
+Module name:    "kebab-case"     → createModule("user-auth", ...)
+Fact keys:      camelCase        → schema: { isLoggedIn: t.boolean() }
+Derivation:     camelCase        → derive: { canEdit: ... }
+Constraint:     camelCase        → constraints: { enforceAuth: ... }
+Resolver:       camelCase        → resolvers: { fetchProfile: ... }
+Requirement:    UPPER_SNAKE_CASE → require: { type: "FETCH_PROFILE" }
+```
+
+## Skill Map
+
+All available Directive skills, grouped by use case:
+
+**Learning:**
+- `getting-started-with-directive` – This skill. Fundamentals and mental model
+- `migrating-to-directive` – Convert from Redux, Zustand, XState, MobX
+
+**Building (Core):**
+- `writing-directive-modules` – Schema, type builders, derivations, naming
+- `writing-directive-constraints` – Constraints, resolvers, error boundaries, retry
+- `building-directive-systems` – Multi-module, plugins, React integration
+- `scaffolding-directive-modules` – Generate module + test boilerplate
+
+**Building (AI):**
+- `building-ai-orchestrators` – Single and multi-agent orchestrators
+- `building-ai-agents` – Streaming, provider adapters, cross-agent communication
+- `hardening-ai-systems` – Guardrails, budgets, PII detection, security
+
+**Quality:**
+- `testing-directive-code` – createTestSystem, mockResolver, time-travel
+- `testing-ai-systems` – Mock runners, evaluations, observability
+- `reviewing-directive-code` – Anti-pattern scanner, naming audit
+
+## Reference Files
+
+Supporting knowledge files loaded with this skill:
+- `core-patterns.md` – Core patterns and API reference

package/skills/getting-started-with-directive/api-skeleton.md

@@ -0,0 +1,5 @@
+# API Skeleton
+
+> Auto-generated. Do not edit.
+
+> Source JSON not found. Build website docs first.