@directive-run/claude-plugin 1.16.0

package/skills/migrating-to-directive/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: migrating-to-directive
+description: "Migrate state management code from Redux, Zustand, XState, MobX, Recoil, or Jotai to Directive. Provides concept mapping, step-by-step migration patterns, and before/after code examples. Use when asked to migrate, convert, or port existing state management to Directive."
+---
+
+# Migrating to Directive
+
+## Prerequisites
+
+This skill applies when migrating TO Directive. The user should have or plan to install `@directive-run/core`: `npm install @directive-run/core`.
+
+## When Claude Should Use This Skill
+
+### Auto-Invoke Triggers
+- User mentions migrating FROM Redux, Zustand, XState, MobX, Recoil, or Jotai
+- User asks "how do I convert this Redux code to Directive"
+- User wants to replace their state management with Directive
+- User asks about Directive equivalents of concepts from other libraries
+- User has existing code in another library and wants Directive version
+
+### Exclusions – Use a Different Skill
+- User is writing Directive from scratch (no migration) → `writing-directive-modules`
+- User wants to understand Directive basics → `getting-started-with-directive`
+
+---
+
+## Concept Mapping
+
+## Redux → Directive
+
+| Redux | Directive | Notes |
+|-------|-----------|-------|
+| Store | System | `createSystem()` wraps modules |
+| Slice / Reducer | Module | `createModule()` with schema + init |
+| State fields | Facts | Schema keys with `t.*()` type builders |
+| Selectors | Derivations | Auto-tracked, no `createSelector` needed |
+| Actions | Requirements | Typed with `UPPER_SNAKE_CASE` |
+| Thunks / Sagas | Resolvers | Async handlers with retry, dedup |
+| Middleware | Plugins | Lifecycle hooks |
+| `useSelector` | `useSelector` | From `@directive-run/react` |
+| `dispatch(action)` | `system.dispatch(event)` | Or constraint auto-triggers |
+| `configureStore` | `createSystem` | With plugins instead of middleware |
+
+### Migration Pattern
+
+```typescript
+// BEFORE: Redux Toolkit
+const counterSlice = createSlice({
+  name: "counter",
+  initialState: { value: 0, status: "idle" },
+  reducers: {
+    increment: (state) => { state.value += 1; },
+    decrement: (state) => { state.value -= 1; },
+  },
+  extraReducers: (builder) => {
+    builder.addCase(fetchCount.fulfilled, (state, action) => {
+      state.value = action.payload;
+      state.status = "loaded";
+    });
+  },
+});
+
+// AFTER: Directive
+const counter = createModule("counter", {
+  schema: {
+    value: t.number(),
+    status: t.string<"idle" | "loading" | "loaded">(),
+  },
+  init: (facts) => {
+    facts.value = 0;
+    facts.status = "idle";
+  },
+  // Reducers become direct mutations:
+  //   system.facts.value += 1  (no action dispatch needed)
+  //
+  // Async thunks become constraint + resolver:
+  constraints: {
+    needsData: {
+      when: (facts) => facts.status === "idle",
+      require: { type: "FETCH_COUNT" },
+    },
+  },
+  resolvers: {
+    fetchCount: {
+      requirement: "FETCH_COUNT",
+      retry: { attempts: 3, backoff: "exponential" },
+      resolve: async (req, context) => {
+        context.facts.status = "loading";
+        const response = await fetch("/api/count");
+        const data = await response.json();
+        context.facts.value = data.count;
+        context.facts.status = "loaded";
+      },
+    },
+  },
+});
+```
+
+## Zustand → Directive
+
+| Zustand | Directive | Notes |
+|---------|-----------|-------|
+| `create()` | `createModule()` | Module is more structured |
+| State object | Schema + init | Explicit types with `t.*()` |
+| Actions (set) | Direct mutation | `system.facts.x = y` |
+| Selectors | Derivations | Auto-tracked |
+| Middleware | Plugins | Built-in logging, devtools |
+| `useStore` | `useSelector` | From React adapter |
+
+### Migration Pattern
+
+```typescript
+// BEFORE: Zustand
+const useStore = create((set) => ({
+  bears: 0,
+  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
+  removeAllBears: () => set({ bears: 0 }),
+}));
+
+// AFTER: Directive
+const bearStore = createModule("bear-store", {
+  schema: { bears: t.number() },
+  init: (facts) => { facts.bears = 0; },
+});
+const system = createSystem({ module: bearStore });
+
+// Actions become direct mutations:
+system.facts.bears += 1;   // increasePopulation
+system.facts.bears = 0;    // removeAllBears
+```
+
+## XState → Directive
+
+| XState | Directive | Notes |
+|--------|-----------|-------|
+| Machine | Module | States → facts, transitions → constraints |
+| States | Fact values | `status: t.string<"idle" \| "loading">()` |
+| Context | Facts | All state in schema |
+| Events | Events / Requirements | `dispatch()` or auto-triggered |
+| Guards | Constraint `when()` | Predicate functions |
+| Actions | Resolver `resolve()` | Async handlers |
+| Services | Resolvers | With retry policies |
+| `useMachine` | `useSystem` | React adapter |
+
+### Migration Pattern
+
+```typescript
+// BEFORE: XState
+const toggleMachine = createMachine({
+  id: "toggle",
+  initial: "inactive",
+  states: {
+    inactive: { on: { TOGGLE: "active" } },
+    active: { on: { TOGGLE: "inactive" } },
+  },
+});
+
+// AFTER: Directive
+const toggle = createModule("toggle", {
+  schema: {
+    status: t.string<"active" | "inactive">(),
+  },
+  init: (facts) => { facts.status = "inactive"; },
+  events: {
+    TOGGLE: (facts) => {
+      facts.status = facts.status === "active" ? "inactive" : "active";
+    },
+  },
+});
+const system = createSystem({ module: toggle });
+
+// Trigger: system.dispatch({ type: "TOGGLE" });
+```
+
+## MobX → Directive
+
+| MobX | Directive | Notes |
+|------|-----------|-------|
+| `observable` | Facts (schema) | Proxy-based, similar feel |
+| `computed` | Derivations | Auto-tracked in both |
+| `action` | Events / direct mutation | Both work |
+| `reaction` | Constraints | When/require pattern |
+| `autorun` | Effects | Fire-and-forget |
+
+## Recoil / Jotai → Directive
+
+| Recoil/Jotai | Directive | Notes |
+|--------------|-----------|-------|
+| Atoms | Facts | Individual state units |
+| Selectors/Derived atoms | Derivations | Auto-tracked |
+| `useRecoilValue` | `useSelector` | React adapter |
+| Async selectors | Constraint + Resolver | Explicit async pattern |
+
+---
+
+## Migration Steps
+
+## Step-by-Step Process
+
+```
+1. Identify state shape
+   → Map to schema with t.*() type builders
+   → Every state field → fact
+
+2. Identify computed values
+   → Map to derive {} block
+   → Auto-tracked, no dependency arrays needed
+
+3. Identify synchronous actions
+   → Direct mutations: system.facts.x = y
+   → Or events: events: { ACTION_NAME: (facts, payload) => { ... } }
+
+4. Identify async operations
+   → Constraint: when should this async work trigger?
+   → Resolver: how to fulfill the requirement?
+   → Add retry policies for network calls
+
+5. Identify side effects
+   → Map to effects {} block
+   → Logging, analytics, DOM sync
+
+6. Identify middleware
+   → Map to plugins [] array
+   → Use built-in: loggingPlugin, devtoolsPlugin, persistencePlugin
+
+7. Update React components
+   → Replace useSelector/useStore with Directive's useSelector
+   → Replace dispatch with direct mutation or system.dispatch
+```
+
+## Key Differences to Explain
+
+```
+Redux:     Action → Reducer → New State (immutable)
+Directive: Mutation → Auto-constraint-check → Auto-resolve (mutable proxy)
+
+Zustand:   set() callback → New state
+Directive: Direct mutation → Reactive updates
+
+XState:    Event → Guard → Transition → Action
+Directive: Fact change → Constraint when() → Requirement → Resolver
+```
+
+## Reference Files
+
+Supporting knowledge files loaded with this skill:
+- `core-patterns.md` – Directive patterns reference
+- `schema-types.md` – Type builder reference for migration
+- `anti-patterns.md` – Common mistakes when migrating

package/skills/migrating-to-directive/anti-patterns.md

@@ -0,0 +1,382 @@
+# Anti-Patterns
+
+> Covers `@directive-run/core` and `@directive-run/react` — hallucination-prone API patterns to avoid.
+
+19 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
+
+## 1. Unnecessary Type Casting on Facts/Derivations
+
+```typescript
+// WRONG – schema already provides the type
+const profile = system.facts.profile as ResourceState<Profile>;
+
+// CORRECT – trust the schema
+const profile = system.facts.profile;
+```
+
+## 2. Flat Schema (Missing facts Wrapper)
+
+```typescript
+// WRONG – facts must be nested under schema.facts
+createModule("counter", {
+  schema: {
+    phase: t.string(),
+    count: t.number(),
+  },
+});
+
+// CORRECT
+createModule("counter", {
+  schema: {
+    facts: {
+      phase: t.string(),
+      count: t.number(),
+    },
+  },
+});
+```
+
+## 3. Bare `facts.*` in Multi-Module Constraints
+
+```typescript
+// WRONG – multi-module constraints use facts.self for own module
+constraints: {
+  checkItems: {
+    when: (facts) => facts.items.length > 0,
+    require: { type: "PROCESS" },
+  },
+},
+
+// CORRECT – use facts.self.* for own module facts
+constraints: {
+  checkItems: {
+    when: (facts) => facts.self.items.length > 0,
+    require: { type: "PROCESS" },
+  },
+},
+```
+
+## 4. Nonexistent Schema Builders
+
+```typescript
+// WRONG – t.map(), t.set(), t.promise() do not exist
+schema: {
+  facts: {
+    cache: t.map<string, User>(),
+    tags: t.set<string>(),
+    pending: t.promise<Data>(),
+  },
+},
+
+// CORRECT – use t.object() with type parameter
+schema: {
+  facts: {
+    cache: t.object<Map<string, User>>(),
+    tags: t.object<Set<string>>(),
+    pending: t.object<Promise<Data>>(),
+  },
+},
+```
+
+## 5. Abbreviating `context` to `ctx`
+
+```typescript
+// WRONG – never abbreviate context
+resolve: async (req, ctx) => {
+  ctx.facts.status = "done";
+},
+
+// CORRECT – always spell out context
+resolve: async (req, context) => {
+  context.facts.status = "done";
+},
+```
+
+## 6. Flat Module Config (No schema Wrapper)
+
+```typescript
+// WRONG – properties must be inside schema.facts
+createModule("timer", {
+  phase: t.string(),
+  elapsed: t.number(),
+});
+
+// CORRECT – wrap in schema: { facts: {} }
+createModule("timer", {
+  schema: {
+    facts: {
+      phase: t.string(),
+      elapsed: t.number(),
+    },
+  },
+});
+```
+
+## 7. String-Based Event Dispatch
+
+```typescript
+// WRONG – there is no two-argument string-keyed dispatch signature
+system.dispatch("login", { token: "abc" });
+
+// CORRECT – use the typed events accessor (preferred — autocomplete + payload typing)
+system.events.login({ token: "abc" });
+
+// ALSO VALID – the single-arg object form of dispatch() is supported when you
+// need to forward a programmatically-built event. Prefer the events accessor
+// for normal code.
+system.dispatch({ type: "login", token: "abc" });
+```
+
+## 8. Direct Array/Object Mutation
+
+```typescript
+// WRONG – proxy cannot detect in-place mutations
+facts.items.push(item);
+facts.config.theme = "dark";
+
+// CORRECT – replace the entire value
+facts.items = [...facts.items, item];
+facts.config = { ...facts.config, theme: "dark" };
+```
+
+## 9. Nonexistent `useDirective` Hook
+
+```typescript
+// WRONG – there is no useDirective hook
+const state = useDirective(system);
+
+// CORRECT – use useSelector with a selector function
+const count = useSelector(system, (s) => s.facts.count);
+const isLoading = useSelector(system, (s) => s.derive.isLoading);
+```
+
+## 10. Bracket Notation for Namespaced Facts
+
+```typescript
+// WRONG – internal separator is not part of the public API
+const status = facts["auth::status"];
+const token = facts["auth_token"];
+
+// CORRECT – use dot notation through the namespace proxy
+const status = facts.auth.status;
+const token = facts.auth.token;
+```
+
+## 11. Returning Data from Resolvers
+
+```typescript
+// WRONG – resolvers return void, not data
+resolve: async (req, context) => {
+  const user = await fetchUser(req.userId);
+
+  return user; // Return value is ignored
+},
+
+// CORRECT – mutate context.facts to store results
+resolve: async (req, context) => {
+  const user = await fetchUser(req.userId);
+  context.facts.user = user;
+},
+```
+
+## 12. Async Logic in `init`
+
+```typescript
+// WRONG – init is synchronous, facts assignment only
+init: async (facts) => {
+  const data = await fetch("/api/config");
+  facts.config = await data.json();
+},
+
+// CORRECT – init sets defaults; use constraints/resolvers for async work
+init: (facts) => {
+  facts.config = null;
+  facts.phase = "loading";
+},
+
+constraints: {
+  loadConfig: {
+    when: (facts) => facts.config === null,
+    require: { type: "LOAD_CONFIG" },
+  },
+},
+```
+
+## 13. Missing `settle()` After `start()`
+
+```typescript
+// WRONG – constraints fire on start, resolvers are async
+system.start();
+console.log(system.facts.data); // May still be null
+
+// CORRECT – wait for resolvers to complete
+system.start();
+await system.settle();
+console.log(system.facts.data); // Resolved
+```
+
+## 14. Missing `crossModuleDeps` Declaration
+
+```typescript
+// WRONG – accessing auth facts without declaring dependency
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  constraints: {
+    fetchWhenAuth: {
+      when: (facts) => facts.auth.isAuthenticated, // Type error
+      require: { type: "FETCH" },
+    },
+  },
+});
+
+// CORRECT – declare crossModuleDeps for type-safe cross-module access
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  crossModuleDeps: { auth: authSchema },
+  constraints: {
+    fetchWhenAuth: {
+      when: (facts) => facts.auth.isAuthenticated,
+      require: { type: "FETCH" },
+    },
+  },
+});
+```
+
+## 15. String Literal for `require`
+
+```typescript
+// WRONG – require must be an object with type property
+constraints: {
+  check: {
+    when: (facts) => facts.ready,
+    require: "FETCH_DATA",
+  },
+},
+
+// CORRECT – use object form with type
+constraints: {
+  check: {
+    when: (facts) => facts.ready,
+    require: { type: "FETCH_DATA" },
+  },
+},
+```
+
+## 16. Passthrough Derivations
+
+```typescript
+// WRONG – derivation just returns a fact value unchanged
+derive: {
+  count: (facts) => facts.count,
+},
+
+// CORRECT – remove it, read the fact directly instead
+// system.facts.count instead of system.derive.count
+```
+
+## 17. Deep Import Paths
+
+```typescript
+// WRONG – internal module paths are not public API
+import { createModule } from "@directive-run/core/module";
+import { createSystem } from "@directive-run/core/system";
+
+// CORRECT – import from package root
+import { createModule, createSystem } from "@directive-run/core";
+
+// Exception: plugins have their own entry point
+import { loggingPlugin } from "@directive-run/core/plugins";
+```
+
+## 18. Async `when()` Without `deps`
+
+```typescript
+// WRONG – async constraints need explicit deps for tracking
+constraints: {
+  validate: {
+    async: true,
+    when: async (facts) => {
+      const valid = await checkRemote(facts.token);
+
+      return valid;
+    },
+    require: { type: "REFRESH_TOKEN" },
+  },
+},
+
+// CORRECT – add deps array for async constraints
+constraints: {
+  validate: {
+    async: true,
+    deps: ["token"],
+    when: async (facts) => {
+      const valid = await checkRemote(facts.token);
+
+      return valid;
+    },
+    require: { type: "REFRESH_TOKEN" },
+  },
+},
+```
+
+## 19. No Error Handling on Failing Resolvers
+
+```typescript
+// WRONG – unhandled errors crash the system
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data");
+      context.facts.data = await res.json();
+    },
+  },
+},
+
+// CORRECT – use retry policy and/or module error boundary
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    retry: { attempts: 3, backoff: "exponential" },
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data");
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      context.facts.data = await res.json();
+    },
+  },
+},
+
+// Also set error boundary at system level
+const system = createSystem({
+  module: myModule,
+  errorBoundary: {
+    onResolverError: "retry-later",
+  },
+});
+```
+
+## Quick Reference Checklist
+
+Before generating any Directive code, verify:
+
+1. Schema is nested: `schema: { facts: { ... } }` (not flat)
+2. No `as` casts when reading facts or derivations
+3. Resolver params are `(req, context)` not `(req, ctx)`
+4. `require` is an object `{ type: "..." }` not a string
+5. `init()` is synchronous
+6. Resolvers return void and mutate `context.facts`
+7. Arrays/objects replaced, not mutated in place
+8. Multi-module uses `facts.self.*` for own facts
+9. Imports from `@directive-run/core`, not deep paths
+10. `await system.settle()` after `system.start()`
+
+## See also
+
+- [`naming.md`](./naming.md) — the strict canonical-term rules AND the alias map for cross-paradigm searches
+- [`constraints.md`](./constraints.md) — the constraint shape these anti-patterns reference (`facts` not in scope inside static `require:`, etc.)
+- [`resolvers.md`](./resolvers.md) — the resolver shape these anti-patterns reference (return `void`, mutate `context.facts`, `(req, context)` not `(req, ctx)`)
+- [`schema-types.md`](./schema-types.md) — the `t.*()` builders that exist and the hallucinated ones (`t.map`, `t.set`, `t.promise`, `t.date`) that don't
+- [`react-adapter.md`](./react-adapter.md) — the React hooks that exist and the hallucinated ones (`useEvent`, `useSystem`, `DirectiveProvider`) that don't
+- [`error-boundaries.md`](./error-boundaries.md) — error-handling shapes AI assistants sometimes invent

package/skills/migrating-to-directive/api-skeleton.md

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