TMNL Common Conventions

Overview

TMNL maintains strict conventions for code organization, naming, and documentation. This skill codifies patterns observed across the codebase to ensure consistency.

Mandatory Conventions (Non-negotiable):

1. Schema discipline — All domain types use Effect Schema
2. Typography 12px floor — No text smaller than 12px
3. Atom-as-State doctrine — No Effect.Ref for React consumers
4. Dependency audit — Grep before cutting imports

---

Pattern 1: Library Module Structure

When: Creating a new library at src/lib/{feature}/

Standard Directory Layout

src/lib/{feature}/
├── index.ts              # Barrel export (required)
├── types.ts              # TypeScript types (UI props, configs)
├── schemas/              # Effect Schema definitions
│   └── index.ts
├── services/             # Effect.Service implementations
│   ├── index.ts
│   └── {Feature}Service.ts
├── atoms/                # effect-atom definitions
│   └── index.ts
├── hooks/                # React hooks
│   └── use{Feature}.ts
├── components/           # React components (if UI-heavy)
│   └── {Component}.tsx
├── machines/             # XState machines (if stateful)
│   └── {feature}-machine.ts
├── v1/, v2/              # Version directories (for evolution)
└── CLAUDE.{feature}.md   # Agent handoff documentation

When to Use Each Directory

| Directory | When to Create | |-----------|----------------| | services/ | Multiple Effect services, or single complex service | | service.ts (root) | Single simple service (e.g., src/lib/commands/service.ts) | | atoms/ | effect-atom state management | | hooks/ | Multiple React hooks | | use{Feature}.tsx (root) | Single hook | | schemas/ | Domain types requiring validation | | types.ts | UI props, configs, non-validated types | | machines/ | XState state machines | | v1/, v2/ | Major version evolution (not breaking changes) |

---

Pattern 2: Barrel File (index.ts) Structure

When: Every src/lib/{feature}/ directory requires a barrel export.

Standard Format

/**
 * {Feature} Library
 *
 * {Brief description}
 *
 * @example
 * ```tsx
 * import { Component, useFeature } from '@/lib/{feature}'
 * ```
 */

// ═══════════════════════════════════════════════════════════════════════════
// CORE EXPORTS
// ═══════════════════════════════════════════════════════════════════════════

export { MainComponent } from './components/Main'
export { FeatureService } from './services'

// ═══════════════════════════════════════════════════════════════════════════
// SCHEMAS
// ═══════════════════════════════════════════════════════════════════════════

export * from './schemas'

// ═══════════════════════════════════════════════════════════════════════════
// ATOMS (effect-atom)
// ═══════════════════════════════════════════════════════════════════════════

export {
  stateAtom,
  configAtom,
  operationsAtom,
} from './atoms'

// ═══════════════════════════════════════════════════════════════════════════
// REACT HOOKS
// ═══════════════════════════════════════════════════════════════════════════

export { useFeature, useFeatureState } from './hooks'

// ═══════════════════════════════════════════════════════════════════════════
// TYPES
// ═══════════════════════════════════════════════════════════════════════════

export type { FeatureConfig, FeatureState } from './types'

Section Separators

Use box-drawing characters for major sections:

// ═══════════════════════════════════════════════════════════════════════════
// SECTION NAME (all caps)
// ═══════════════════════════════════════════════════════════════════════════

Use simple dashes for subsections:

// ───────────────────────────────────────────────────────────────────────────
// Subsection name
// ───────────────────────────────────────────────────────────────────────────

Version Re-exports

For modules with v1/v2:

// Default exports from v1
export * from './v1'

// Explicit v2 namespace
export * as v2 from './v2'

Usage:

import { Slider } from '@/lib/slider'         // v1 (default)
import { Slider } from '@/lib/slider/v2'      // v2 (explicit)

---

Pattern 3: Naming Conventions

Atoms

| Pattern | Example | Usage | |---------|---------|-------| | {noun}Atom | resultsAtom | State atom | | {noun}sAtom | layersAtom | Collection atom | | {verb}Atom | computedAtom | Derived/computed atom | | {feature}OpsAtom | layerOpsAtom | Operation atoms (mutations) | | {verb}Op | searchOp, clearOp | Individual operation |

Services

| Pattern | Example | Usage | |---------|---------|-------| | {Feature}Service | DataManagerService | Effect.Service class | | {Feature}ServiceShape | ChannelServiceShape | Interface type | | {Behavior}Behavior | LinearBehavior, DecibelBehavior | Strategy pattern |

Hooks

| Pattern | Example | Usage | |---------|---------|-------| | use{Feature} | useSlider | Main feature hook | | use{Feature}Value | useSliderValue | Read-only value hook | | use{Feature}State | useMinibufferState | State + updater | | use{Feature}Ops | useOverlayOps | Operations only | | useAtom{Feature} | useAtomValue | Atom-specific |

Components

| Pattern | Example | Usage | |---------|---------|-------| | {Name}.tsx | Slider.tsx | Component file | | {Name}Props | SliderProps | Props interface | | {Name}Context | DataGridContext | Context type | | {Name}Provider | CommandProvider | Context provider |

Machines

| Pattern | Example | Usage | |---------|---------|-------| | {feature}Machine | minibufferMachine | XState machine | | {Feature}Machine | MinibufferMachine | Type alias | | {Feature}Actor | MinibufferActor | ActorRef type |

---

Pattern 4: Comment Styles

File Header (JSDoc)

/**
 * {Module Name} — {Brief description}
 *
 * {Longer description if needed}
 *
 * @example
 * ```tsx
 * // Usage example
 * ```
 */

Architectural Notes

For non-obvious design decisions:

// ARCHITECTURAL NOTE:
// CommandProvider lives here (commands/), not in minibuffer/.
// Minibuffer is a generic prompt engine. Commands USES minibuffer, not the reverse.

TODO/FIXME

// TODO(prime): Migrate to v2 API after EPOCH-0003
// FIXME: This breaks when input is empty
// HACK: Workaround for WSLg rendering bug

---

Pattern 5: Types vs Schemas

When to Use types.ts

• React component props
• UI configuration
• Local function parameters
• Types that don't need runtime validation

// src/lib/slider/v1/types.ts
export interface SliderProps {
  value: number
  onChange: (value: number) => void
  min?: number
  max?: number
}

export interface SliderConfig {
  min: number
  max: number
  step: number
  defaultValue: number
}

When to Use schemas/

• Domain types requiring validation
• Event payloads
• API responses
• Discriminated unions with pattern matching
• EventLog integration

// src/lib/overlays/schemas/core.ts
import { Schema } from 'effect'

export const OverlayId = Schema.String.pipe(
  Schema.brand('OverlayId')
)
export type OverlayId = typeof OverlayId.Type

export const OverlayOpened = Schema.TaggedStruct('OverlayOpened', {
  id: OverlayId,
  timestamp: Schema.DateFromSelf,
})

---

Pattern 6: Test File Organization

Location Patterns

| Pattern | Example | When | |---------|---------|------| | __tests__/ directory | src/lib/stx/__tests__/ | Multiple test files | | .test.ts suffix | service.test.ts | Single test file | | .bun.test.ts suffix | eventlog-integration.bun.test.ts | Bun-specific |

Test Naming

// src/lib/feature/__tests__/feature.test.ts
describe('FeatureService', () => {
  describe('operation', () => {
    it('does X when Y', () => { ... })
    it('fails with Z when W', () => { ... })
  })
})

Effect Service Tests

Use @effect/vitest with it.effect():

import { describe, it } from '@effect/vitest'

describe('MyService', () => {
  it.effect('returns data', () =>
    Effect.gen(function* () {
      const service = yield* MyService
      const result = yield* service.getData()
      expect(result).toBeDefined()
    }).pipe(Effect.provide(MyService.Default))
  )
})

Atom Tests

Use Registry.make():

it('atom updates', () => {
  const r = Registry.make()
  expect(r.get(counterAtom)).toBe(0)
  r.set(counterAtom, 1)
  expect(r.get(counterAtom)).toBe(1)
})

---

Pattern 7: Documentation Files

Per-Module Documentation

| File | Purpose | Audience | |------|---------|----------| | CLAUDE.{feature}.md | Agent handoff | AI assistants | | README.md | User-facing docs | Developers | | ARCHITECTURE.md | Deep design analysis | Architects | | AGENTS.{feature}.md | Agent-specific notes | AI assistants |

CLAUDE.{feature}.md Structure

# {Feature} — Claude Context

## Overview
{Brief description}

## Key Files
- `service.ts` — Main service implementation
- `atoms/index.ts` — Reactive state

## Patterns Used
- Effect.Service<>() for DI
- Atom.runtime() for state

## Gotchas
- Don't use X because Y
- Always Z before W

## Related Skills
- effect-patterns
- effect-atom-integration

---

Pattern 8: Service File Patterns

Single Service (Root Level)

// src/lib/commands/service.ts

/**
 * TMNL Commands — Effect Service
 */

// ───────────────────────────────────────────────────────────────────────────
// Atoms (Reactive State)
// ───────────────────────────────────────────────────────────────────────────

export const commandsAtom = Atom.make<ReadonlyMap<string, Command>>(new Map())

// ───────────────────────────────────────────────────────────────────────────
// Service Implementation
// ───────────────────────────────────────────────────────────────────────────

export class CommandService extends Effect.Service<CommandService>()('app/CommandService', {
  effect: Effect.gen(function* () {
    // ...
  }),
}) {}

Multiple Services (Directory)

src/lib/overlays/services/
├── index.ts              # Re-exports all services
├── OverlayRegistry.ts    # Registry service
├── PortHub.ts            # Port management
└── EventDispatcher.ts    # Event dispatch

---

Anti-Patterns

1. Barrel File Without Sections

// WRONG — Unorganized exports
export * from './components'
export * from './hooks'
export * from './types'
export * from './atoms'

// CORRECT — Sectioned exports
// ═══════════════════════════════════════════════════════════════════════════
// COMPONENTS
// ═══════════════════════════════════════════════════════════════════════════
export { Slider } from './components/Slider'

// ═══════════════════════════════════════════════════════════════════════════
// HOOKS
// ═══════════════════════════════════════════════════════════════════════════
export { useSlider } from './hooks/useSlider'

2. Types in Wrong Location

// WRONG — Domain type without Schema
// src/lib/feature/types.ts
export interface UserEvent {
  _tag: 'UserCreated'
  id: string
  name: string
}

// CORRECT — Domain type with Schema
// src/lib/feature/schemas/events.ts
export const UserCreated = Schema.TaggedStruct('UserCreated', {
  id: Schema.String,
  name: Schema.NonEmptyString,
})

3. Inconsistent Naming

// WRONG — Mixed naming styles
export const user_state_atom = Atom.make(...)  // snake_case
export const UseUserHook = () => { ... }       // PascalCase for hook
export const userservice = Effect.Service()    // no separator

// CORRECT — Consistent camelCase with type suffix
export const userStateAtom = Atom.make(...)
export const useUser = () => { ... }
export const UserService = Effect.Service()

4. Missing JSDoc on Exports

// WRONG — No documentation
export const searchOp = runtimeAtom.fn<string>()(...)

// CORRECT — JSDoc on public exports
/**
 * Search operation. Triggers search with given query.
 *
 * @param query - Search query string
 * @returns Effect that updates resultsAtom
 */
export const searchOp = runtimeAtom.fn<string>()(...)

---

Checklist: New Module Creation

When creating src/lib/{feature}/:

• [ ] Create index.ts with JSDoc header and sectioned exports
• [ ] Create types.ts for non-domain types (UI props, configs)
• [ ] Create schemas/ for domain types using Effect Schema
• [ ] Create services/ (or service.ts) with Effect.Service<>()
• [ ] Create atoms/index.ts with Atom definitions
• [ ] Create hooks/ with React hooks
• [ ] Use section comments: // ═══════...
• [ ] Add ARCHITECTURAL NOTE for non-obvious decisions
• [ ] Create CLAUDE.{feature}.md for agent handoff
• [ ] Prefer Atom.make<T>() over Effect.Ref<T> for React
• [ ] Test with @effect/vitest for services, Registry.make() for atoms

---

Canonical Examples

| Convention | Best Example | File | |------------|--------------|------| | Barrel file | Overlays | src/lib/overlays/index.ts | | Service pattern | Commands | src/lib/commands/service.ts | | Atom organization | Slider | src/lib/slider/v1/atoms/index.ts | | Schema usage | Commands | src/lib/commands/types.ts | | Hook naming | Commands | src/lib/commands/useCommandWire.tsx | | Version strategy | Slider | src/lib/slider/index.ts | | Test organization | STX | src/lib/stx/__tests__/ |

---

Integration Points

• tmnl-file-organization — Directory structure details
• effect-patterns — Service definition patterns
• effect-atom-integration — Atom patterns
• tmnl-typography-discipline — Typography rules
• effect-schema-mastery — Schema patterns