scaffolding-directive-modules

name	scaffolding-directive-modules
description	Generate Directive module scaffolds with schema, init, derivations, constraints, resolvers, and matching test files. Use when asked to scaffold, generate, or create a new module from scratch, or when the user describes a feature and wants the boilerplate created.

Scaffolding Directive Modules

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 to "scaffold a module" or "generate a module"
• User describes a feature and wants boilerplate created
• User asks for a "starter" or "template" for a Directive module
• User wants to create a module with tests in one step

Exclusions – Use a Different Skill

• User wants to understand Directive concepts → getting-started-with-directive
• User has existing code and wants patterns guidance → writing-directive-modules
• User wants to review existing code → reviewing-directive-code

---

Module Scaffold Template

Step 1: Identify the Domain

Ask the user (or infer from context):

1. What is the module managing? (e.g., "user authentication", "shopping cart")
2. What state does it track? (e.g., "login status, user profile, tokens")
3. What actions should happen automatically? (e.g., "redirect when not logged in", "fetch profile on login")

Step 2: Generate Module

import { createModule, t } from "@directive-run/core";

// Module: {module-name}
// Purpose: {one-line description}

export const {camelCaseName} = createModule("{kebab-case-name}", {
  schema: {
    // State – all facts must have type builders
    // {factName}: t.{type}(),
  },

  init: (facts) => {
    // Set ALL schema keys to sensible defaults
    // No async work, no side effects
  },

  derive: {
    // Computed values – pure functions, auto-tracked
    // {derivedName}: (facts) => {computation},
    // Composition: {name}: (facts, derived) => derived.other && facts.x,
  },

  constraints: {
    // Business rules: when X is true, require Y
    // {constraintName}: {
    //   when: (facts) => {condition},
    //   require: { type: "REQUIREMENT_TYPE", ...payload },
    // },
  },

  resolvers: {
    // Async handlers for requirements
    // {resolverName}: {
    //   requirement: "REQUIREMENT_TYPE",
    //   resolve: async (req, context) => {
    //     // Fulfill the requirement
    //   },
    // },
  },
});

Step 3: Generate Test File

import { describe, it, expect } from "vitest";
import { createTestSystem } from "@directive-run/core/testing";
import { {camelCaseName} } from "./{kebab-case-name}";

describe("{kebab-case-name}", () => {
  function createTest() {
    return createTestSystem({ module: {camelCaseName} });
  }

  describe("initialization", () => {
    it("sets default values", () => {
      const system = createTest();
      // expect(system.facts.{fact}).toBe({default});
    });
  });

  describe("derivations", () => {
    it("computes {derivedName}", () => {
      const system = createTest();
      // system.facts.{fact} = {value};
      // expect(system.derive.{derivedName}).toBe({expected});
    });
  });

  describe("constraints + resolvers", () => {
    it("triggers {requirement} when {condition}", async () => {
      const system = createTest();
      // system.facts.{fact} = {trigger value};
      // await system.settle();
      // expect(system.facts.{result}).toBe({expected});
    });
  });
});

Scaffold Decision Tree

What kind of module?
│
├── Simple state container (no async)
│   → schema + init + derive
│   → Skip constraints/resolvers
│   → Example: counter, feature-flags
│
├── Data-fetching module
│   → schema includes loading/error/data states
│   → Constraint triggers fetch when needed
│   → Resolver fetches with retry policy
│   → Example: dashboard-loader, auth-flow
│
├── Form/validation module
│   → schema for field values + validation state
│   → Constraints check validity rules
│   → Resolver submits form data
│   → Example: contact-form, form-wizard
│
├── Multi-module coordination
│   → Multiple modules + crossModuleDeps
│   → createSystem({ modules: { a, b } })
│   → Example: multi-module, permissions
│
└── AI orchestrator module
│   → Use createAgentOrchestrator or createMultiAgentOrchestrator
│   → See building-ai-orchestrators skill

Common Schema Patterns

Loading State

schema: {
  status: t.string<"idle" | "loading" | "success" | "error">(),
  data: t.object<DataType | null>(),
  error: t.string<string | null>(),
},
init: (facts) => {
  facts.status = "idle";
  facts.data = null;
  facts.error = null;
},

Resource State (Generic)

schema: {
  resource: t.object<ResourceState<T>>(),
},
// Where ResourceState<T> = { status, data, error, lastFetched }

Authentication

schema: {
  isAuthenticated: t.boolean(),
  user: t.object<User | null>(),
  token: t.string<string | null>(),
  loginError: t.string<string | null>(),
},

Pagination

schema: {
  items: t.array<Item>(),
  page: t.number(),
  pageSize: t.number(),
  total: t.number(),
  hasMore: t.boolean(),
},

Naming Rules (Enforced)

Module variable:    camelCase       const userAuth = createModule(...)
Module string:      kebab-case      createModule("user-auth", ...)
Fact keys:          camelCase       isLoggedIn, userName
Derivation keys:    camelCase       canEdit, isAdmin
Constraint keys:    camelCase       enforceLogin, requireProfile
Resolver keys:      camelCase       fetchProfile, submitLogin
Requirement types:  UPPER_SNAKE     "FETCH_PROFILE", "SUBMIT_LOGIN"
Test describe:      kebab-case      describe("user-auth", ...)

Reference Files

Supporting knowledge files loaded with this skill:

• core-patterns.md – Patterns and API reference
• schema-types.md – Type builders and schema patterns
• naming.md – Naming conventions