claude-flow-novice 1.2.1 → 1.3.1

package/.claude-flow-novice/templates/claude-md-templates/CLAUDE-TYPESCRIPT.md

@@ -0,0 +1,851 @@
+# Claude Code Configuration - SPARC Development Environment (TypeScript)
+
+## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT
+
+**ABSOLUTE RULES**:
+1. ALL operations MUST be concurrent/parallel in a single message
+2. **NEVER save working files, text/mds and tests to the root folder**
+3. ALWAYS organize files in appropriate subdirectories
+4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP
+
+### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
+
+**MANDATORY PATTERNS:**
+- **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
+- **Task tool (Claude Code)**: ALWAYS spawn ALL agents in ONE message with full instructions
+- **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
+- **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
+- **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
+
+### 🎯 CRITICAL: Claude Code Task Tool for Agent Execution
+
+**Claude Code's Task tool is the PRIMARY way to spawn agents:**
+```javascript
+// ✅ CORRECT: Use Claude Code's Task tool for parallel agent execution
+[Single Message]:
+  Task("TS researcher", "Analyze TypeScript patterns and ecosystem...", "researcher")
+  Task("TS coder", "Implement core TypeScript modules with strong typing...", "coder")
+  Task("TS tester", "Create comprehensive tests with Jest/Vitest and type testing...", "tester")
+  Task("TS reviewer", "Review code for TypeScript best practices and type safety...", "reviewer")
+  Task("TS architect", "Design system architecture with TypeScript patterns...", "system-architect")
+```
+
+### 📁 TypeScript File Organization Rules
+
+**NEVER save to root folder. Use TypeScript project structure:**
+- `/src` - Source TypeScript files (.ts, .tsx)
+- `/dist` or `/build` - Compiled JavaScript output
+- `/types` - Type declaration files (.d.ts)
+- `/test` or `/__tests__` - Test files (.test.ts, .spec.ts)
+- `/docs` - Documentation and markdown files
+- `/config` - Configuration files
+- `/scripts` - Build and utility scripts
+- `/node_modules` - Dependencies (auto-generated, add to .gitignore)
+- `package.json` - Project manifest and dependencies
+- `tsconfig.json` - TypeScript configuration
+- `package-lock.json` - Dependency lock file
+
+## Project Overview
+
+This TypeScript project uses SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) methodology with Claude-Flow orchestration for systematic Test-Driven Development with strong typing.
+
+## TypeScript-Specific SPARC Commands
+
+### Core Commands
+- `npx claude-flow sparc modes` - List available modes
+- `npx claude-flow sparc run <mode> "<ts-task>"` - Execute TypeScript-specific mode
+- `npx claude-flow sparc tdd "<ts-feature>"` - Run complete TDD workflow for TypeScript
+- `npx claude-flow sparc info <mode>` - Get mode details
+
+### TypeScript Build Commands
+- `npm install` - Install dependencies
+- `npm run build` - Compile TypeScript to JavaScript
+- `npm run build:watch` - Watch mode compilation
+- `npm run dev` - Development mode with hot reload
+- `npm test` - Run tests with type checking
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:coverage` - Run tests with coverage
+- `npm run typecheck` - Type checking only (no emit)
+- `npm run lint` - Run ESLint with TypeScript rules
+- `npm run lint:fix` - Fix ESLint issues automatically
+- `npm run format` - Format code with Prettier
+
+### TypeScript Quality Commands
+- `tsc --noEmit` - Type checking without compilation
+- `npm run build -- --strict` - Strict compilation
+- `npm run test:types` - Type-only testing
+- `madge --circular --extensions ts src/` - Check circular dependencies
+
+## TypeScript SPARC Workflow Phases
+
+1. **Specification** - Requirements analysis with type definitions (`sparc run spec-pseudocode`)
+2. **Pseudocode** - Algorithm design with type annotations (`sparc run spec-pseudocode`)
+3. **Architecture** - System design with TypeScript interfaces (`sparc run architect`)
+4. **Refinement** - TDD implementation with type-safe tests (`sparc tdd`)
+5. **Completion** - Integration with full type checking (`sparc run integration`)
+
+## TypeScript Code Style & Best Practices
+
+- **Strong Typing**: Use strict TypeScript configuration
+- **Type Safety**: Avoid `any`, prefer specific types and interfaces
+- **Generics**: Use generic types for reusable components
+- **Utility Types**: Leverage TypeScript utility types (Partial, Pick, etc.)
+- **Type Guards**: Implement runtime type checking
+- **Module Resolution**: Use path mapping and proper imports
+- **Testing**: Type-safe testing with proper mocking
+- **Documentation**: TSDoc comments for type documentation
+
+## 🚀 TypeScript-Specific Agents (78+ Total)
+
+### Core TypeScript Development
+`ts-coder`, `ts-architect`, `ts-tester`, `ts-reviewer`, `type-designer`
+
+### Type System Specialists
+`interface-designer`, `generic-specialist`, `utility-type-expert`, `type-guard-creator`
+
+### Framework Specialists
+`react-ts-dev`, `vue-ts-dev`, `angular-dev`, `node-ts-dev`, `express-ts-dev`
+
+### Testing & Quality
+`jest-ts-expert`, `vitest-specialist`, `type-test-creator`, `ts-lint-expert`
+
+### Build & Tooling
+`tsc-expert`, `webpack-ts-config`, `vite-ts-specialist`, `tsup-expert`
+
+### All Standard Agents Available
+`coder`, `reviewer`, `tester`, `planner`, `researcher`, `system-architect`, `code-analyzer`, `performance-benchmarker`, `cicd-engineer`, `security-manager`
+
+## 🎯 TypeScript Development Patterns
+
+### ✅ CORRECT TYPESCRIPT WORKFLOW
+
+```javascript
+// Step 1: Set up TypeScript project coordination
+[Single Message - Coordination Setup]:
+  mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 6 }
+  mcp__claude-flow__agent_spawn { type: "ts-architect" }
+  mcp__claude-flow__agent_spawn { type: "ts-coder" }
+  mcp__claude-flow__agent_spawn { type: "type-designer" }
+
+// Step 2: Parallel TypeScript development execution
+[Single Message - Parallel Agent Execution]:
+  Task("TS architect", "Design type-safe architecture with interfaces and generics. Store type definitions in memory.", "ts-architect")
+  Task("Type designer", "Create comprehensive type definitions and interfaces. Focus on type safety.", "type-designer")
+  Task("TS coder", "Implement modules with strict TypeScript. Use proper type annotations.", "ts-coder")
+  Task("TS tester", "Create type-safe test suite with Jest. Include type testing.", "ts-tester")
+  Task("Build engineer", "Configure TypeScript build pipeline with proper type checking.", "tsc-expert")
+
+  // Batch ALL TypeScript todos
+  TodoWrite { todos: [
+    {content: "Set up tsconfig.json with strict settings", status: "in_progress", activeForm: "Setting up tsconfig.json"},
+    {content: "Design core type definitions and interfaces", status: "pending", activeForm: "Designing core type definitions"},
+    {content: "Implement modules with strong typing", status: "pending", activeForm: "Implementing modules with strong typing"},
+    {content: "Add comprehensive type-safe tests", status: "pending", activeForm: "Adding comprehensive type-safe tests"},
+    {content: "Configure ESLint for TypeScript", status: "pending", activeForm: "Configuring ESLint for TypeScript"},
+    {content: "Set up build pipeline with type checking", status: "pending", activeForm: "Setting up build pipeline"},
+    {content: "Add TSDoc documentation", status: "pending", activeForm: "Adding TSDoc documentation"},
+    {content: "Configure path mapping and module resolution", status: "pending", activeForm: "Configuring path mapping"}
+  ]}
+
+  // Parallel TypeScript file operations
+  Write "package.json"
+  Write "tsconfig.json"
+  Write "src/index.ts"
+  Write "src/types/index.ts"
+  Write "test/index.test.ts"
+  Write ".eslintrc.js"
+```
+
+## TypeScript Agent Coordination Protocol
+
+### Every TypeScript Agent MUST:
+
+**1️⃣ BEFORE Work:**
+```bash
+npx claude-flow@alpha hooks pre-task --description "[ts-task]"
+npm run typecheck  # Verify type checking
+```
+
+**2️⃣ DURING Work:**
+```bash
+npm run lint  # Check TypeScript linting
+npm run typecheck  # Continuous type checking
+npx claude-flow@alpha hooks post-edit --file "[file]" --memory-key "ts/[agent]/[step]"
+```
+
+**3️⃣ AFTER Work:**
+```bash
+npm run build  # Compile TypeScript
+npm test  # Run type-safe tests
+npx claude-flow@alpha hooks post-task --task-id "[task]"
+```
+
+## TypeScript-Specific Configurations
+
+### package.json Template
+```json
+{
+  "name": "typescript-project",
+  "version": "1.0.0",
+  "description": "TypeScript project with SPARC methodology",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "start": "node dist/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ --ext .ts,.tsx",
+    "lint:fix": "eslint src/ --ext .ts,.tsx --fix",
+    "format": "prettier --write src/",
+    "validate": "npm run typecheck && npm run lint && npm run test",
+    "clean": "rimraf dist"
+  },
+  "keywords": ["typescript", "node", "api"],
+  "author": "Your Name <email@example.com>",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.18.0",
+    "cors": "^2.8.5",
+    "helmet": "^6.0.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "@types/express": "^4.17.0",
+    "@types/cors": "^2.8.0",
+    "@types/jest": "^29.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.50.0",
+    "@typescript-eslint/parser": "^5.50.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "prettier": "^2.7.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^4.9.0",
+    "rimraf": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=8.0.0"
+  }
+}
+```
+
+### tsconfig.json Template
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": false,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "baseUrl": "./src",
+    "paths": {
+      "@/*": ["*"],
+      "@/types/*": ["types/*"],
+      "@/utils/*": ["utils/*"],
+      "@/config/*": ["config/*"]
+    }
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ],
+  "ts-node": {
+    "esm": true
+  }
+}
+```
+
+### ESLint Configuration (.eslintrc.js)
+```javascript
+module.exports = {
+  env: {
+    browser: true,
+    es2021: true,
+    node: true,
+    jest: true,
+  },
+  extends: [
+    'eslint:recommended',
+    '@typescript-eslint/recommended',
+    '@typescript-eslint/recommended-requiring-type-checking',
+  ],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    project: './tsconfig.json',
+  },
+  plugins: [
+    '@typescript-eslint',
+  ],
+  rules: {
+    '@typescript-eslint/no-unused-vars': 'error',
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/explicit-function-return-type': 'error',
+    '@typescript-eslint/explicit-module-boundary-types': 'error',
+    '@typescript-eslint/no-unsafe-assignment': 'error',
+    '@typescript-eslint/no-unsafe-member-access': 'error',
+    '@typescript-eslint/no-unsafe-call': 'error',
+    '@typescript-eslint/no-unsafe-return': 'error',
+    '@typescript-eslint/prefer-nullish-coalescing': 'error',
+    '@typescript-eslint/prefer-optional-chain': 'error',
+    '@typescript-eslint/strict-boolean-expressions': 'error',
+  },
+};
+```
+
+### Jest Configuration (jest.config.js)
+```javascript
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src', '<rootDir>/test'],
+  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.test.ts',
+    '!src/**/*.spec.ts',
+    '!src/**/*.d.ts',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80,
+    },
+  },
+  moduleNameMapping: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+  setupFilesAfterEnv: ['<rootDir>/test/setup.ts'],
+};
+```
+
+## Type Definition Strategies
+
+### Interface Design
+```typescript
+// Core interfaces
+interface User {
+  readonly id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface CreateUserRequest {
+  name: string;
+  email: string;
+}
+
+interface UpdateUserRequest {
+  name?: string;
+  email?: string;
+}
+
+// Generic interfaces
+interface Repository<T, K = string> {
+  findById(id: K): Promise<T | null>;
+  findAll(): Promise<T[]>;
+  create(entity: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+  update(id: K, updates: Partial<T>): Promise<T | null>;
+  delete(id: K): Promise<boolean>;
+}
+
+// Utility types usage
+type UserRepository = Repository<User>;
+type PartialUser = Partial<User>;
+type UserWithoutDates = Omit<User, 'createdAt' | 'updatedAt'>;
+type UserEmailOnly = Pick<User, 'email'>;
+```
+
+### Advanced Type Patterns
+```typescript
+// Discriminated unions
+type ApiResponse<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+// Conditional types
+type NonNullable<T> = T extends null | undefined ? never : T;
+
+// Mapped types
+type Readonly<T> = {
+  readonly [P in keyof T]: T[P];
+};
+
+// Template literal types
+type EventName<T extends string> = `on${Capitalize<T>}`;
+type UserEvents = EventName<'create' | 'update' | 'delete'>;
+// Result: 'onCreate' | 'onUpdate' | 'onDelete'
+
+// Brand types for type safety
+type UserId = string & { readonly __brand: unique symbol };
+type Email = string & { readonly __brand: unique symbol };
+
+const createUserId = (id: string): UserId => id as UserId;
+const createEmail = (email: string): Email => {
+  if (!email.includes('@')) {
+    throw new Error('Invalid email format');
+  }
+  return email as Email;
+};
+```
+
+### Type Guards
+```typescript
+// Type guard functions
+const isString = (value: unknown): value is string => {
+  return typeof value === 'string';
+};
+
+const isUser = (value: unknown): value is User => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'name' in value &&
+    'email' in value &&
+    isString((value as User).id) &&
+    isString((value as User).name) &&
+    isString((value as User).email)
+  );
+};
+
+// Usage in functions
+const processUser = (data: unknown): User => {
+  if (!isUser(data)) {
+    throw new Error('Invalid user data');
+  }
+  return data; // TypeScript knows this is User
+};
+```
+
+## Testing Strategies
+
+### Type-Safe Unit Tests
+```typescript
+// test/user.test.ts
+import { User, UserService } from '../src/user';
+
+describe('UserService', () => {
+  let userService: UserService;
+
+  beforeEach(() => {
+    userService = new UserService();
+  });
+
+  describe('createUser', () => {
+    test('should create user with valid data', async () => {
+      const userData = {
+        name: 'John Doe',
+        email: 'john@example.com',
+      };
+
+      const result = await userService.createUser(userData);
+
+      expect(result).toEqual<User>({
+        id: expect.any(String),
+        name: userData.name,
+        email: userData.email,
+        createdAt: expect.any(Date),
+        updatedAt: expect.any(Date),
+      });
+    });
+
+    test('should throw error for invalid email', async () => {
+      const userData = {
+        name: 'John Doe',
+        email: 'invalid-email',
+      };
+
+      await expect(userService.createUser(userData))
+        .rejects
+        .toThrow('Invalid email format');
+    });
+  });
+});
+```
+
+### Mock Types
+```typescript
+// test/mocks.ts
+import { Repository } from '../src/types';
+
+export const createMockRepository = <T>(): jest.Mocked<Repository<T>> => ({
+  findById: jest.fn(),
+  findAll: jest.fn(),
+  create: jest.fn(),
+  update: jest.fn(),
+  delete: jest.fn(),
+});
+
+// Usage in tests
+describe('UserService with mocks', () => {
+  test('should call repository correctly', async () => {
+    const mockRepo = createMockRepository<User>();
+    const userService = new UserService(mockRepo);
+
+    mockRepo.findById.mockResolvedValue({
+      id: '1',
+      name: 'John',
+      email: 'john@example.com',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await userService.getUser('1');
+
+    expect(mockRepo.findById).toHaveBeenCalledWith('1');
+    expect(result).toBeDefined();
+  });
+});
+```
+
+### Type Testing
+```typescript
+// test/types.test.ts
+import { expectType, expectError } from 'tsd';
+import { User, CreateUserRequest } from '../src/types';
+
+// Test type assignments
+expectType<User>({
+  id: '123',
+  name: 'John',
+  email: 'john@example.com',
+  createdAt: new Date(),
+  updatedAt: new Date(),
+});
+
+// Test that certain assignments should fail
+expectError<CreateUserRequest>({
+  id: '123', // Should not have id
+  name: 'John',
+  email: 'john@example.com',
+});
+
+// Test utility types
+expectType<Partial<User>>({
+  name: 'John', // Only name is provided
+});
+```
+
+## Error Handling with Types
+
+### Typed Error Classes
+```typescript
+// Base error class
+abstract class AppError extends Error {
+  abstract readonly statusCode: number;
+  abstract readonly errorCode: string;
+
+  constructor(message: string, public readonly context?: Record<string, unknown>) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+// Specific error types
+class ValidationError extends AppError {
+  readonly statusCode = 400;
+  readonly errorCode = 'VALIDATION_ERROR';
+}
+
+class NotFoundError extends AppError {
+  readonly statusCode = 404;
+  readonly errorCode = 'NOT_FOUND';
+}
+
+class DatabaseError extends AppError {
+  readonly statusCode = 500;
+  readonly errorCode = 'DATABASE_ERROR';
+}
+
+// Type-safe error handling
+type ErrorType = ValidationError | NotFoundError | DatabaseError;
+
+const handleError = (error: ErrorType): void => {
+  switch (error.errorCode) {
+    case 'VALIDATION_ERROR':
+      console.log('Validation failed:', error.message);
+      break;
+    case 'NOT_FOUND':
+      console.log('Resource not found:', error.message);
+      break;
+    case 'DATABASE_ERROR':
+      console.log('Database error:', error.message);
+      break;
+    default:
+      // TypeScript ensures this is never reached
+      const _exhaustive: never = error;
+      break;
+  }
+};
+```
+
+### Result Type Pattern
+```typescript
+// Result type for error handling without exceptions
+type Result<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+const safeParseUser = (data: unknown): Result<User, ValidationError> => {
+  if (!isUser(data)) {
+    return {
+      success: false,
+      error: new ValidationError('Invalid user data'),
+    };
+  }
+
+  return {
+    success: true,
+    data: data,
+  };
+};
+
+// Usage
+const handleUserData = (data: unknown): void => {
+  const result = safeParseUser(data);
+
+  if (result.success) {
+    console.log('User:', result.data.name);
+  } else {
+    console.error('Error:', result.error.message);
+  }
+};
+```
+
+## Performance Optimization
+
+### Type-Level Performance
+```typescript
+// Use const assertions for better inference
+const config = {
+  apiUrl: 'https://api.example.com',
+  timeout: 5000,
+  retries: 3,
+} as const;
+
+type Config = typeof config;
+// Result: { readonly apiUrl: "https://api.example.com"; readonly timeout: 5000; ... }
+
+// Avoid deep object types in hot paths
+interface OptimizedUser {
+  id: string;
+  name: string;
+  // Avoid nested objects in frequently used types
+}
+
+// Use branded types for compile-time safety with zero runtime cost
+type ProductId = string & { readonly __brand: 'ProductId' };
+type CategoryId = string & { readonly __brand: 'CategoryId' };
+
+// These prevent mixing different ID types
+const getProduct = (id: ProductId): Product => { /* ... */ };
+const getCategory = (id: CategoryId): Category => { /* ... */ };
+```
+
+### Build Optimization
+```typescript
+// tsconfig.json for production builds
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "declaration": false,
+    "sourceMap": false,
+    "removeComments": true,
+    "importHelpers": true,
+    "skipLibCheck": true,
+    "incremental": true,
+    "tsBuildInfoFile": ".tsbuildinfo"
+  },
+  "exclude": [
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ]
+}
+```
+
+## Documentation with TSDoc
+
+### Comprehensive Documentation
+```typescript
+/**
+ * Service for managing user operations.
+ *
+ * @example
+ * ```typescript
+ * const userService = new UserService(userRepository);
+ * const user = await userService.createUser({
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ * ```
+ */
+export class UserService {
+  constructor(private readonly userRepository: Repository<User>) {}
+
+  /**
+   * Creates a new user with the provided data.
+   *
+   * @param userData - The user data for creation
+   * @returns Promise that resolves to the created user
+   *
+   * @throws {@link ValidationError}
+   * Thrown when the provided user data is invalid
+   *
+   * @throws {@link DatabaseError}
+   * Thrown when database operation fails
+   *
+   * @example
+   * ```typescript
+   * const newUser = await userService.createUser({
+   *   name: 'Alice Smith',
+   *   email: 'alice@example.com'
+   * });
+   * console.log(`Created user: ${newUser.name}`);
+   * ```
+   */
+  async createUser(userData: CreateUserRequest): Promise<User> {
+    // Implementation
+  }
+
+  /**
+   * Finds a user by their unique identifier.
+   *
+   * @param id - The unique user identifier
+   * @returns Promise that resolves to the user or null if not found
+   *
+   * @example
+   * ```typescript
+   * const user = await userService.findUser('user-123');
+   * if (user) {
+   *   console.log(`Found user: ${user.name}`);
+   * } else {
+   *   console.log('User not found');
+   * }
+   * ```
+   */
+  async findUser(id: string): Promise<User | null> {
+    // Implementation
+  }
+}
+```
+
+## CI/CD Configuration
+
+### GitHub Actions (.github/workflows/typescript.yml)
+```yaml
+name: TypeScript CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x, 20.x]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+
+    - run: npm ci
+
+    - name: Type Check
+      run: npm run typecheck
+
+    - name: Lint
+      run: npm run lint
+
+    - name: Test
+      run: npm run test:coverage
+
+    - name: Build
+      run: npm run build
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage/lcov.info
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-node@v3
+      with:
+        node-version: '18'
+        cache: 'npm'
+    - run: npm ci
+    - name: Type check
+      run: npm run typecheck
+```
+
+## Support Resources
+
+- **TypeScript Handbook**: https://www.typescriptlang.org/docs/
+- **TSDoc**: https://tsdoc.org/
+- **TypeScript ESLint**: https://typescript-eslint.io/
+- **Jest with TypeScript**: https://jestjs.io/docs/getting-started#using-typescript
+- **TypeScript Deep Dive**: https://basarat.gitbook.io/typescript/
+
+---
+
+Remember: **Claude Flow coordinates, Claude Code creates TypeScript!**