PROTOCOL: CREATE-MODULE (EXECUTION LEVEL 3)

<state_machine> CURRENT_STEP -> REQUIRED_TOOL -> REQUIRED_OUTPUT -> MANDATORY_HALT Step 1: Prerequisites -> read_file / ls (packages/modules/, AGENTS.md) -> Confirmed non-existent module & kebab-case {context} -> Continue to Step 2 Step 2-5: Scaffold -> write_file (4 exact files from embedded templates) -> package.json, tsconfig.json, .gitignore, container.ts -> Continue to Step 6 Step 6: Validate -> run_command (npm install, typecheck, build) -> Passing workspace typecheck & build -> 🛑 HALT TURN (Present module) </state_machine>

<execution_invariants>

1. WORKFLOW IMMUTABILITY: You may reason freely INSIDE each step to inspect the repository's workspace conventions, shared packages, and tsconfig references, but you must execute the scaffolding steps in order (workflow structure = immutable | step reasoning = flexible).
2. EXACT 4-FILE SCOPE: Create only package.json, tsconfig.json, .gitignore, and src/container.ts under packages/modules/{context}/ using the exact templates in this skill. Do NOT add domain entities, value objects, or handlers in this skill.
3. NO OVERWRITE: Never overwrite an existing module under packages/modules/{context}/.
4. ESCAPE HATCH: If the repository's workspace or module architecture does not fit the 4-file Turborepo contract, do not silently improvise and do not force-fit: declare the deviation in one line and ask. </execution_invariants>

<output_contract>

• TARGET_FILES:
  1. packages/modules/{context}/package.json
  2. packages/modules/{context}/tsconfig.json
  3. packages/modules/{context}/.gitignore
  4. packages/modules/{context}/src/container.ts
• SCHEMA_INVARIANCE: Match the 4 embedded templates in ## 📄 Templates verbatim (substituting {context} and {Context}).
• ESCAPE_HATCH: If the repository uses a different workspace scope or shared package prefix than @sessioflow/* (discovered from AGENTS.md or existing packages/modules/*/package.json), adapt the scope prefix to match the repository's real workspace naming and declare the adaptation in your response. </output_contract>

Scaffold a new DDD module as a buildable Turborepo workspace package.

This skill creates exactly four files in packages/modules/{context}/. No domain content — just the packaging and wiring infrastructure so the module can be built, tested, and imported by other packages immediately.

Important: Follow AGENTS.md for all code conventions and quality standards. Domain content scaffolding (entities, value objects, CQRS, controllers) is handled by create-entity-lifecycle and implement-flow skills.

📋 Prerequisites

Before running, confirm:

• Module name is decided (kebab-case for folder, e.g. sessions)
• The context doesn't already exist under packages/modules/
• Shared packages exist (@sessioflow/shared-*)

If unsure, ask the user.

🧠 Think Before Coding

Follow AGENTS.md Karpathy principles:

1. Understand — what is the module's purpose?
2. Plan — which files, what content
3. Check — verify no existing module covers this context
4. Execute — create the four files, run validation

📦 Output

🛠️ Step-by-Step

Step 1: Create directory

mkdir -p packages/modules/{context}/src

Step 2: Create package.json

Generate from template. Replace {context} with the kebab-case context name.

Step 3: Create tsconfig.json

Generate from template. The references list must include all four shared packages: bus, database, domain, logging.

Step 4: Create .gitignore

Generate from template (standard npm/node/gitignore).

Step 5: Create container.ts

Generate from template. This is the wiring scaffold:

• Imports shared bus/middleware types
• Defines factory methods for handlers with default repository injection
• Creates a mediator with command bus + query bus + logging middleware
• Creates HTTP controller wrappers with auth injection
• Supports dependency injection (pass a mock for testing)

No domain types are imported — that's filled in later by the domain skills.

Step 6: Validate

# Register workspace
npm install

# Type-check (should pass — no domain code yet)
npx turbo typecheck --filter=@sessioflow/{context}

# Build (should pass — container compiles fine)
npx turbo build --filter=@sessioflow/{context}

📄 Templates

All templates use {context} placeholder (kebab-case module name).

package.json

{
  "name": "@sessioflow/{context}",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "exports": {
    "./container": "./dist/container.js",
    "./domain/*": "./dist/domain/*.js",
    "./application/*": "./dist/application/*.js",
    "./infrastructure/*": "./dist/infrastructure/*.js",
    "./interfaces/*": "./dist/interfaces/*.js"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@sessioflow/bus": "*",
    "@sessioflow/shared-database": "*",
    "@sessioflow/shared-domain": "*",
    "@sessioflow/shared-logging": "*",
    "drizzle-orm": "^0.45.2",
    "zod": "^4.4.3"
  },
  "devDependencies": {
    "@sessioflow/tsconfig": "*",
    "typescript": "^5"
  }
}

Key fields:

• "private": true — not published to npm registry
• "type": "module" — ESM output; all imports use .js extension
• "exports" — granular subpath exports per DDD layer
• Dependencies use "*" — workspace resolution aligns versions automatically

tsconfig.json

{
  "extends": "../../config/tsconfig/base.json",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist",
    "composite": true
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../../shared/bus" },
    { "path": "../../shared/database" },
    { "path": "../../shared/domain" },
    { "path": "../../shared/logging" }
  ]
}

Key fields:

• "extends" — shares compiler options with all other packages
• "composite": true — enables project references for incremental builds
• "references" — declares cross-package type dependencies; TypeScript compile order

.gitignore

# Build artifacts
dist/

container.ts

import {
  InMemoryCommandBus,
  InMemoryQueryBus,
  LoggingMiddleware,
  Mediator,
} from '@sessioflow/bus';
import type { OutboxRepository } from '@sessioflow/shared-database/outbox-repository';
import { DrizzleOutboxRepository } from '@sessioflow/shared-database/outbox-repository';

// ──────────────────────────────────────────────────────────────
// TODO: Import domain types, handlers, repositories, and HTTP controllers.
//
// Example:
//   import { type {Entity}Repository } from './domain/{entity}-repository.interface.js';
//   import { Create{Entity}Handler } from './application/commands/create-{context}/create-{entity}.handler.js';
//   import { create{Entity}Controller } from './interfaces/http/{entity}.controller.js';
// ──────────────────────────────────────────────────────────────

/**
 * {Context} Module Container (Composition Root).
 *
 * Wires Application Use-Cases & HTTP Controllers with
 * default Infrastructure Repositories.
 */
export const {context}Container = {
  /**
   * Create the CQRS mediator with command & query buses.
   */
  createMediator(): Mediator {
    const commandBus = new InMemoryCommandBus();
    const queryBus = new InMemoryQueryBus();
    const loggingMiddleware = new LoggingMiddleware();

    commandBus.use(loggingMiddleware);
    queryBus.use(loggingMiddleware);

    // TODO: Register commands and queries.
    // Example:
    //   commandBus.register(Create{Entity}Command, this.create{Entity}Handler());

    return new Mediator(commandBus, queryBus);
  },

  /**
   * Create the HTTP POST controller.
   */
  createController(
    getAuthUser: () => Promise<{ id: string } | undefined> = async () => ({ id: 'mock-user-id' }),
  ) {
    // TODO: Wire mediator + handler + auth to controller.
    // Example:
    //   const mediator = this.createMediator();
    //   const busHandler = {
    //     execute: (command) => mediator.send<Create{Entity}Command, Create{Entity}Response>(command),
    //   };
    //   return create{Entity}HttpController(request, busHandler, getAuthUser);

    throw new Error('Not implemented — wire in the handler step');
  },
};

What this gives you:

• A factory function (createMediator) that wires buses, middleware, and (later) handlers
• A controller factory (createController) for HTTP endpoints
• Dependency injection support: pass mock repositories for testing
• TODO markers to guide domain integration

📐 What You Get

After this skill runs, the module is:

🚫 Anti-Patterns

📚 Related Skills

Last Updated: 2026-07-14
Version: 1.0

<self_validation_gate> Before ending your turn, verify every item below with concrete evidence (not just a checkmark). If any item cannot be cited with real evidence from this turn, DO NOT produce your final response — fix the violation first:

• 4-File Scope Evidence: List the exact 4 file paths written under packages/modules/{context}/ (confirming 0 domain files added prematurely): <4 paths>
• Template Fidelity Evidence: Confirm "private": true, "type": "module", granular exports, and "composite": true are present: <confirmed>
• Build & Typecheck Evidence: Exact typecheck and build commands executed and exit codes (0): <commands> </self_validation_gate>