clearctx 3.0.0 → 3.1.0

package/skills/typescript/SKILL.md

@@ -0,0 +1,932 @@
+---
+name: typescript
+description: Production-grade TypeScript patterns for type-first development, generics, strict mode, type narrowing, and module architecture
+domain: language
+keywords: [typescript, types, generics, interfaces, strict-mode, type-guards, utility-types, tsconfig]
+version: 1.0.0
+---
+
+# TypeScript Expertise Skill
+
+## Worker Context
+
+You are a TypeScript expert worker. Apply these patterns to ALL code you write.
+
+### Type-First Development
+
+**CRITICAL:** Define types/interfaces BEFORE implementation. Types ARE your documentation.
+
+```typescript
+// GOOD: Type-first approach
+interface User {
+  id: string;
+  email: string;
+  role: 'admin' | 'user';
+  createdAt: Date;
+}
+
+interface CreateUserRequest {
+  email: string;
+  password: string;
+}
+
+function createUser(req: CreateUserRequest): User {
+  // Implementation follows types
+}
+
+// BAD: Implementation-first, types retrofitted
+function createUser(email, password) {
+  return { id: generateId(), email, role: 'user', createdAt: new Date() };
+}
+```
+
+**IMPORTANT:** Export types from module index. Shared types go in `types/` directory.
+
+### Interface vs Type Decision Tree
+
+| Use Case | Use This | Why |
+|----------|----------|-----|
+| Object shapes (may extend later) | `interface` | Declaration merging, cleaner extends |
+| Unions, intersections, primitives | `type` | Only types support `A \| B`, `A & B`, mapped types |
+| Function signatures | `type` | Cleaner: `type Handler = (req: Request) => Response` |
+| Class contracts | `interface` | `implements` keyword, natural fit |
+| When either works | `interface` | Slightly better error messages, extendable |
+
+```typescript
+// GOOD: Correct tool selection
+interface User {
+  id: string;
+  name: string;
+}
+
+interface AdminUser extends User {
+  permissions: string[];
+}
+
+type Result<T> = { success: true; data: T } | { success: false; error: string };
+type Handler = (req: Request) => Promise<Response>;
+type Nullable<T> = T | null;
+
+// BAD: Wrong tool for the job
+type User = {  // Should be interface (object shape)
+  id: string;
+  name: string;
+}
+
+interface Result<T> {  // Cannot express union with interface
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+```
+
+### Generics
+
+**Constrain generics with `extends`** — NEVER add generics that don't constrain anything.
+
+```typescript
+// GOOD: Meaningful constraints
+function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
+  return items.find(item => item.id === id);
+}
+
+type ApiResponse<TData> = {
+  data: TData;
+  timestamp: number;
+};
+
+function processItems<T extends { status: string }>(
+  items: T[],
+  filter: (item: T) => boolean
+): T[] {
+  return items.filter(filter);
+}
+
+// BAD: Unconstrained generics (just use concrete types)
+function log<T>(value: T): void {  // T adds no value here
+  console.log(value);
+}
+
+// GOOD: No generic needed
+function log(value: unknown): void {
+  console.log(value);
+}
+```
+
+**Use descriptive names for complex generics:** `TResponse`, `TInput`, `TEntity`, not just `T`, `U`, `V`.
+
+### Strict Mode Configuration
+
+**CRITICAL:** Always enable in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+**NEVER use `// @ts-ignore`** unless fixing third-party type bugs — add comment explaining why.
+
+```typescript
+// BAD: Silencing errors
+// @ts-ignore
+const result = dangerousOperation();
+
+// GOOD: Fix the type issue
+const result = dangerousOperation() as Result;
+
+// ACCEPTABLE: Third-party bug with explanation
+// @ts-ignore — bug in @types/legacy-lib v3.2.1, fixed in v3.3.0
+// See: https://github.com/DefinitelyTyped/DefinitelyTyped/issues/12345
+import { brokenFunction } from 'legacy-lib';
+```
+
+### Null Safety
+
+**CRITICAL:** Strict null checks ON. Use `??` for defaults, `?.` for optional access.
+
+```typescript
+// GOOD: Null-safe patterns
+const username = user?.profile?.name ?? 'Anonymous';
+const config = loadConfig() ?? getDefaults();
+
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+function processResult<T>(result: Result<T>): void {
+  if (result.success) {
+    console.log(result.data);  // TypeScript knows data exists
+  } else {
+    console.error(result.error);  // TypeScript knows error exists
+  }
+}
+
+// BAD: Non-null assertions without guards
+const name = user!.profile!.name;  // Crashes if user/profile is null
+
+// GOOD: Type guard first
+if (user?.profile) {
+  const name = user.profile.name;  // Safe
+}
+```
+
+**NEVER use non-null assertion `!`** without explicit type guard first.
+
+### Enum Patterns
+
+**Prefer `as const` objects over enums** for tree-shaking:
+
+```typescript
+// GOOD: const object (tree-shakable, no runtime overhead)
+const STATUS = {
+  PENDING: 'pending',
+  ACTIVE: 'active',
+  COMPLETED: 'completed',
+} as const;
+
+type Status = typeof STATUS[keyof typeof STATUS];  // 'pending' | 'active' | 'completed'
+
+function updateStatus(status: Status): void {
+  if (status === STATUS.PENDING) { /* ... */ }
+}
+
+// ACCEPTABLE: String enum when you need runtime iteration
+enum Color {
+  Red = 'red',
+  Green = 'green',
+  Blue = 'blue',
+}
+
+// BAD: Numeric enum (ambiguous reverse mapping)
+enum Status {
+  Pending,    // 0
+  Active,     // 1
+  Completed   // 2
+}
+```
+
+### Type Narrowing
+
+**Use discriminated unions** (tagged unions with `kind`/`type` field):
+
+```typescript
+// GOOD: Discriminated union
+type ApiState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: string };
+
+function render<T>(state: ApiState<T>): string {
+  switch (state.status) {
+    case 'idle':
+      return 'Not started';
+    case 'loading':
+      return 'Loading...';
+    case 'success':
+      return `Data: ${state.data}`;  // TypeScript knows data exists
+    case 'error':
+      return `Error: ${state.error}`;  // TypeScript knows error exists
+  }
+}
+
+// Custom type guard
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'email' in value
+  );
+}
+
+// Use 'in' operator for narrowing
+function processValue(value: string | { message: string }): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  return value.message;
+}
+
+// Use 'satisfies' for type checking without widening
+const config = {
+  host: 'localhost',
+  port: 3000,
+} satisfies Record<string, string | number>;
+
+config.port;  // Type is still number, not string | number
+```
+
+**NEVER use type assertions instead of narrowing:**
+
+```typescript
+// BAD: Type assertion
+function getUser(data: unknown): User {
+  return data as User;  // No runtime validation
+}
+
+// GOOD: Type guard
+function getUser(data: unknown): User {
+  if (!isUser(data)) {
+    throw new Error('Invalid user data');
+  }
+  return data;
+}
+```
+
+### Utility Types Reference
+
+| Type | Use When | Example |
+|------|----------|---------|
+| `Partial<T>` | Optional update payload | `Partial<User>` for PATCH body |
+| `Required<T>` | Ensure all fields present | Config after defaults applied |
+| `Pick<T, K>` | Subset of fields | `Pick<User, 'id' \| 'name'>` |
+| `Omit<T, K>` | Exclude fields | `Omit<User, 'password'>` for API response |
+| `Record<K, V>` | Typed dictionaries | `Record<string, Handler>` |
+| `ReturnType<F>` | Infer function return | `ReturnType<typeof getUser>` |
+| `Parameters<F>` | Infer function args | `Parameters<typeof handler>[0]` |
+| `Awaited<T>` | Unwrap Promise | `Awaited<ReturnType<typeof fetchUser>>` |
+| `NonNullable<T>` | Exclude null/undefined | `NonNullable<string \| null>` |
+
+```typescript
+// Common utility type patterns
+type UserUpdatePayload = Partial<Omit<User, 'id' | 'createdAt'>>;
+
+type ApiHandler = (req: Request) => Promise<Response>;
+type HandlerParams = Parameters<ApiHandler>[0];
+type HandlerReturn = Awaited<ReturnType<ApiHandler>>;
+
+type UserPublic = Omit<User, 'password' | 'passwordHash'>;
+type UserCache = Pick<User, 'id' | 'email' | 'role'>;
+
+type StatusMap = Record<Status, { label: string; color: string }>;
+```
+
+### Module Patterns
+
+**Barrel exports** — `index.ts` per feature:
+
+```typescript
+// src/users/index.ts
+export { createUser, updateUser, deleteUser } from './user.service';
+export { UserController } from './user.controller';
+export type { User, CreateUserRequest, UpdateUserRequest } from './user.types';
+
+// Import from barrel
+import { createUser, type User } from '@/users';
+```
+
+**Path aliases** — configure in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@/types": ["src/types"]
+    }
+  }
+}
+```
+
+**Declaration files** — for untyped third-party libs:
+
+```typescript
+// src/types/legacy-lib.d.ts
+declare module 'legacy-lib' {
+  export function doSomething(input: string): Promise<Result>;
+  export interface Result {
+    success: boolean;
+    data: unknown;
+  }
+}
+```
+
+**NEVER use `require()`** — always use `import`:
+
+```typescript
+// BAD
+const express = require('express');
+
+// GOOD
+import express from 'express';
+import type { Request, Response } from 'express';
+```
+
+### Error Handling
+
+**Typed error classes:**
+
+```typescript
+// GOOD: Type-safe error handling
+class AppError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public statusCode: number = 500
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message: string, public fields: string[]) {
+    super('VALIDATION_ERROR', message, 400);
+  }
+}
+
+// Result pattern for expected failures
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parseUser(data: unknown): Result<User, ValidationError> {
+  if (!isUser(data)) {
+    return { ok: false, error: new ValidationError('Invalid user', []) };
+  }
+  return { ok: true, value: data };
+}
+```
+
+**Exhaustive switch checks with `never`:**
+
+```typescript
+type Action =
+  | { type: 'create'; payload: User }
+  | { type: 'update'; payload: Partial<User> }
+  | { type: 'delete'; payload: string };
+
+function reducer(action: Action): void {
+  switch (action.type) {
+    case 'create':
+      return handleCreate(action.payload);
+    case 'update':
+      return handleUpdate(action.payload);
+    case 'delete':
+      return handleDelete(action.payload);
+    default:
+      // If we add a new action type and forget to handle it, TypeScript errors here
+      const _exhaustive: never = action;
+      throw new Error(`Unhandled action: ${_exhaustive}`);
+  }
+}
+```
+
+### tsconfig.json Best Practices
+
+```json
+{
+  "compilerOptions": {
+    // Modern JavaScript
+    "target": "ES2022",
+    "lib": ["ES2022"],
+
+    // Module system
+    "module": "NodeNext",           // For Node.js
+    "moduleResolution": "NodeNext", // For Node.js
+    // OR for bundlers:
+    // "module": "ESNext",
+    // "moduleResolution": "bundler",
+
+    // Emit
+    "outDir": "./dist",
+    "declaration": true,            // For libraries
+    "declarationMap": true,
+    "sourceMap": true,
+
+    // Strict checks (CRITICAL)
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Module resolution
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+
+    // Monorepo support
+    "composite": true,              // For project references
+
+    // Path aliases
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    },
+
+    // Performance
+    "skipLibCheck": true,
+    "incremental": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+```
+
+## Conventions
+
+1. **Naming:**
+   - Interfaces/Types: PascalCase — `User`, `CreateUserRequest`, `ApiResponse<T>`
+   - Type parameters: Single letter for simple (`T`, `K`, `V`) or descriptive prefix for complex (`TData`, `TResponse`, `TEntity`)
+   - Enums/const objects: UPPER_CASE keys — `STATUS.PENDING`, `Color.Red`
+   - Files: kebab-case — `user.service.ts`, `api-client.ts`
+
+2. **Exports:**
+   - Always export types using `export type` for type-only exports
+   - Use barrel exports (`index.ts`) per feature module
+   - Shared types in `src/types/` or `@/types`
+
+3. **Imports:**
+   - Group imports: (1) external packages, (2) internal absolute imports, (3) relative imports
+   - Type imports: `import type { User } from './types'` when only used in type position
+
+4. **File structure:**
+   ```
+   src/
+     types/           # Shared types
+       index.ts
+       user.types.ts
+       api.types.ts
+     users/
+       index.ts       # Barrel export
+       user.service.ts
+       user.types.ts  # Feature-specific types
+   ```
+
+## Common Patterns
+
+### 1. API Response Types
+
+```typescript
+// Generic API response wrapper
+type ApiResponse<T> = {
+  data: T;
+  meta: {
+    timestamp: number;
+    requestId: string;
+  };
+};
+
+type ApiError = {
+  error: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+};
+
+type ApiResult<T> = ApiResponse<T> | ApiError;
+
+// Type guard
+function isApiError(response: ApiResult<unknown>): response is ApiError {
+  return 'error' in response;
+}
+
+// Usage
+async function fetchUser(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  const json: ApiResult<User> = await response.json();
+
+  if (isApiError(json)) {
+    throw new AppError(json.error.code, json.error.message);
+  }
+
+  return json.data;
+}
+```
+
+### 2. Builder Pattern with Fluent Interface
+
+```typescript
+class QueryBuilder<T> {
+  private filters: Array<(item: T) => boolean> = [];
+  private sortFn?: (a: T, b: T) => number;
+  private limitValue?: number;
+
+  where(predicate: (item: T) => boolean): this {
+    this.filters.push(predicate);
+    return this;
+  }
+
+  sortBy(compareFn: (a: T, b: T) => number): this {
+    this.sortFn = compareFn;
+    return this;
+  }
+
+  limit(n: number): this {
+    this.limitValue = n;
+    return this;
+  }
+
+  execute(items: T[]): T[] {
+    let result = items.filter(item =>
+      this.filters.every(filter => filter(item))
+    );
+
+    if (this.sortFn) {
+      result = result.sort(this.sortFn);
+    }
+
+    if (this.limitValue !== undefined) {
+      result = result.slice(0, this.limitValue);
+    }
+
+    return result;
+  }
+}
+
+// Usage
+const activeUsers = new QueryBuilder<User>()
+  .where(u => u.role === 'admin')
+  .where(u => u.isActive)
+  .sortBy((a, b) => a.name.localeCompare(b.name))
+  .limit(10)
+  .execute(allUsers);
+```
+
+### 3. Discriminated Union State Machine
+
+```typescript
+type ConnectionState =
+  | { status: 'disconnected' }
+  | { status: 'connecting'; startedAt: number }
+  | { status: 'connected'; socket: WebSocket; connectedAt: number }
+  | { status: 'error'; error: Error; lastAttempt: number };
+
+class Connection {
+  private state: ConnectionState = { status: 'disconnected' };
+
+  connect(): void {
+    if (this.state.status === 'connected') {
+      return; // Already connected
+    }
+
+    this.state = { status: 'connecting', startedAt: Date.now() };
+    // ... connection logic
+  }
+
+  handleConnected(socket: WebSocket): void {
+    if (this.state.status !== 'connecting') {
+      throw new Error('Cannot transition to connected from ' + this.state.status);
+    }
+
+    this.state = { status: 'connected', socket, connectedAt: Date.now() };
+  }
+
+  getStatus(): string {
+    switch (this.state.status) {
+      case 'disconnected':
+        return 'Not connected';
+      case 'connecting':
+        return `Connecting... (${Date.now() - this.state.startedAt}ms)`;
+      case 'connected':
+        return `Connected for ${Date.now() - this.state.connectedAt}ms`;
+      case 'error':
+        return `Error: ${this.state.error.message}`;
+    }
+  }
+}
+```
+
+### 4. Mapped Types for Transformations
+
+```typescript
+// Make all properties of T into functions that return T[K]
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+// Make all properties of T into functions that accept T[K]
+type Setters<T> = {
+  [K in keyof T as `set${Capitalize<string & K>}`]: (value: T[K]) => void;
+};
+
+type User = {
+  name: string;
+  age: number;
+};
+
+type UserGetters = Getters<User>;
+// { getName: () => string; getAge: () => number; }
+
+type UserSetters = Setters<User>;
+// { setName: (value: string) => void; setAge: (value: number) => void; }
+
+// Practical example: Create immutable update helpers
+type UpdateFunctions<T> = {
+  [K in keyof T as `update${Capitalize<string & K>}`]: (value: T[K]) => T;
+};
+
+function createUpdateHelpers<T>(initial: T): UpdateFunctions<T> {
+  const helpers = {} as UpdateFunctions<T>;
+
+  for (const key in initial) {
+    const capitalizedKey = key.charAt(0).toUpperCase() + key.slice(1);
+    const helperName = `update${capitalizedKey}` as keyof UpdateFunctions<T>;
+
+    helpers[helperName] = ((value: T[typeof key]) => ({
+      ...initial,
+      [key]: value,
+    })) as UpdateFunctions<T>[typeof helperName];
+  }
+
+  return helpers;
+}
+```
+
+### 5. Type-Safe Event Emitter
+
+```typescript
+type EventMap = {
+  'user:created': { user: User };
+  'user:updated': { user: User; changes: Partial<User> };
+  'user:deleted': { userId: string };
+};
+
+class TypedEventEmitter<T extends Record<string, unknown>> {
+  private listeners = new Map<keyof T, Set<(data: unknown) => void>>();
+
+  on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(handler as (data: unknown) => void);
+  }
+
+  emit<K extends keyof T>(event: K, data: T[K]): void {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      handlers.forEach(handler => handler(data));
+    }
+  }
+
+  off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      handlers.delete(handler as (data: unknown) => void);
+    }
+  }
+}
+
+// Usage (fully type-safe)
+const emitter = new TypedEventEmitter<EventMap>();
+
+emitter.on('user:created', ({ user }) => {
+  console.log(`User created: ${user.name}`);
+});
+
+emitter.on('user:updated', ({ user, changes }) => {
+  console.log(`User ${user.id} updated:`, changes);
+});
+
+emitter.emit('user:created', { user: newUser });
+// emitter.emit('user:created', { wrong: 'data' }); // Type error!
+```
+
+## Anti-Patterns
+
+### 1. ❌ Using `any` Instead of `unknown`
+
+```typescript
+// BAD: any disables all type checking
+function processData(data: any): void {
+  data.something.that.might.not.exist();  // No error, crashes at runtime
+}
+
+// GOOD: unknown forces type validation
+function processData(data: unknown): void {
+  if (typeof data === 'object' && data !== null && 'id' in data) {
+    console.log((data as { id: string }).id);
+  }
+}
+
+// ACCEPTABLE: any at system boundaries with immediate validation
+async function fetchData(url: string): Promise<User> {
+  const response = await fetch(url);
+  const data: any = await response.json();  // External data = any
+
+  if (!isUser(data)) {  // Immediately validate
+    throw new Error('Invalid user data');
+  }
+
+  return data;  // Now type-safe
+}
+```
+
+### 2. ❌ Type Assertions Instead of Narrowing
+
+```typescript
+// BAD: Type assertion without validation
+function getUser(data: unknown): User {
+  return data as User;  // No runtime safety
+}
+
+const config = JSON.parse(configString) as Config;  // Crashes if wrong shape
+
+// GOOD: Type guard with validation
+function getUser(data: unknown): User {
+  if (!isUser(data)) {
+    throw new Error('Invalid user data');
+  }
+  return data;
+}
+
+function parseConfig(configString: string): Config {
+  const parsed: unknown = JSON.parse(configString);
+
+  if (!isConfig(parsed)) {
+    throw new Error('Invalid config format');
+  }
+
+  return parsed;
+}
+```
+
+### 3. ❌ Overly Complex Generic Chains
+
+```typescript
+// BAD: Generic inception (>3 levels deep)
+type DeepGeneric<
+  T extends Record<string, unknown>,
+  K extends keyof T,
+  V extends T[K],
+  R extends V extends Array<infer U> ? U : never
+> = R extends object ? Partial<R> : never;
+
+// GOOD: Break into named steps
+type ArrayElement<T> = T extends Array<infer U> ? U : never;
+type ObjectOrNever<T> = T extends object ? T : never;
+
+type ExtractedItem<T, K extends keyof T> = ObjectOrNever<ArrayElement<T[K]>>;
+type PartialItem<T, K extends keyof T> = Partial<ExtractedItem<T, K>>;
+
+// Or just use concrete types if only used once
+```
+
+### 4. ❌ Ignoring Strict Mode Errors
+
+```typescript
+// BAD: Disabling strict checks
+{
+  "compilerOptions": {
+    "strict": false,  // Defeats the purpose of TypeScript
+    "noImplicitAny": false
+  }
+}
+
+function doSomething(data) {  // Implicit any
+  return data.value;  // No safety
+}
+
+// GOOD: Enable strict mode and fix the issues
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+
+function doSomething(data: { value: string }): string {
+  return data.value;
+}
+```
+
+### 5. ❌ Optional Properties Instead of Discriminated Unions
+
+```typescript
+// BAD: Ambiguous optional fields
+type Result = {
+  success: boolean;
+  data?: User;
+  error?: string;
+};
+
+function handle(result: Result): void {
+  if (result.success) {
+    console.log(result.data.name);  // TypeScript doesn't know data exists!
+  }
+}
+
+// GOOD: Discriminated union
+type Result =
+  | { success: true; data: User }
+  | { success: false; error: string };
+
+function handle(result: Result): void {
+  if (result.success) {
+    console.log(result.data.name);  // TypeScript knows data exists
+  } else {
+    console.error(result.error);  // TypeScript knows error exists
+  }
+}
+```
+
+## Integration Notes
+
+### Multi-Session Team Context
+
+**If you are a worker in a multi-session team:**
+
+1. **CRITICAL:** Call `team_check_inbox()` BEFORE starting work to receive shared artifacts and messages from other workers
+2. **Read shared conventions:** Look for `shared-conventions` artifact containing naming conventions, enum values, response formats, error formats
+3. **TypeScript applies to ALL workers:** Backend, frontend, testing workers all follow these patterns
+4. **Publish shared types:** Create and publish `shared-types` artifact containing:
+   - Common interfaces (`User`, `ApiResponse<T>`, etc.)
+   - API request/response types
+   - Error types and error codes
+   - Enum/status value definitions
+5. **Types = contract:** Types published in `shared-types` become the contract between frontend and backend workers — changes must be coordinated
+6. **Broadcast completion:** Use `team_broadcast()` when you publish new types so other workers know to re-read the artifact
+7. **Use relative paths only:** Never use absolute paths in published artifacts
+
+### Artifact Publication Format
+
+When publishing `shared-types` artifact:
+
+```typescript
+// shared-types artifact data structure
+{
+  "files": ["src/types/user.types.ts", "src/types/api.types.ts"],
+  "exports": {
+    "user.types": ["User", "CreateUserRequest", "UpdateUserRequest"],
+    "api.types": ["ApiResponse", "ApiError", "Result"]
+  },
+  "conventions": {
+    "enumValues": {
+      "UserRole": ["admin", "user", "guest"],
+      "Status": ["pending", "active", "completed"]
+    },
+    "errorCodes": ["VALIDATION_ERROR", "NOT_FOUND", "UNAUTHORIZED"]
+  }
+}
+```
+
+### Coordinating with Other Workers
+
+- **Backend worker:** Consumes `shared-types` for request/response types, error handling
+- **Frontend worker:** Consumes `shared-types` for API client types, state management
+- **Testing worker:** Consumes `shared-types` for test data factories, type assertions
+- **Database worker:** Shares model types via `shared-types` that backend worker uses
+
+### Type Changes Workflow
+
+1. Identify type change needed (e.g., add field to `User`)
+2. Update type definition in `shared-types` artifact source
+3. Re-publish `shared-types` artifact
+4. Broadcast to team: "Updated User type — added `phoneNumber` field"
+5. Affected workers re-read artifact and update their implementations
+
+---
+
+**Remember:** TypeScript is not just type checking — it's documentation, refactoring safety, and IDE autocomplete. Invest in types upfront, reap benefits throughout the project lifecycle.