agentic-team-templates 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-team-templates",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "AI coding assistant templates for Cursor IDE. Pre-configured rules and guidelines that help AI assistants write better code. - use at your own risk",
   "keywords": [
     "cursor",

package/src/index.js

@@ -28,6 +28,14 @@ const TEMPLATES = {
     description: 'Command-line applications and developer tools (Cobra, Commander, Click)',
     rules: ['architecture.md', 'arguments.md', 'distribution.md', 'error-handling.md', 'overview.md', 'testing.md', 'user-experience.md']
   },
+  'data-engineering': {
+    description: 'Data platforms and pipelines (ETL, data modeling, data quality)',
+    rules: ['data-modeling.md', 'data-quality.md', 'overview.md', 'performance.md', 'pipeline-design.md', 'security.md', 'testing.md']
+  },
+  'devops-sre': {
+    description: 'DevOps and SRE practices (incident management, observability, SLOs, chaos engineering)',
+    rules: ['capacity-planning.md', 'change-management.md', 'chaos-engineering.md', 'disaster-recovery.md', 'incident-management.md', 'observability.md', 'overview.md', 'postmortems.md', 'runbooks.md', 'slo-sli.md', 'toil-reduction.md']
+  },
   'documentation': {
     description: 'Technical documentation standards (READMEs, API docs, ADRs, code comments)',
     rules: ['adr.md', 'api-documentation.md', 'code-comments.md', 'maintenance.md', 'overview.md', 'readme-standards.md']
@@ -36,10 +44,34 @@ const TEMPLATES = {
     description: 'Full-stack web applications (Next.js, Nuxt, SvelteKit, Remix)',
     rules: ['api-contracts.md', 'architecture.md', 'overview.md', 'shared-types.md', 'testing.md']
   },
+  'javascript-expert': {
+    description: 'Principal-level JavaScript engineering across Node.js, React, vanilla JS, and testing',
+    rules: ['language-deep-dive.md', 'node-patterns.md', 'overview.md', 'performance.md', 'react-patterns.md', 'testing.md', 'tooling.md']
+  },
+  'ml-ai': {
+    description: 'Machine learning and AI systems (model development, deployment, monitoring)',
+    rules: ['data-engineering.md', 'deployment.md', 'model-development.md', 'monitoring.md', 'overview.md', 'security.md', 'testing.md']
+  },
   'mobile': {
     description: 'Mobile applications (React Native, Flutter, native iOS/Android)',
     rules: ['navigation.md', 'offline-first.md', 'overview.md', 'performance.md', 'testing.md']
   },
+  'platform-engineering': {
+    description: 'Internal developer platforms, infrastructure automation, and reliability engineering',
+    rules: ['ci-cd.md', 'developer-experience.md', 'infrastructure-as-code.md', 'kubernetes.md', 'observability.md', 'overview.md', 'security.md', 'testing.md']
+  },
+  'product-manager': {
+    description: 'Product management with customer-centric discovery, prioritization, and execution',
+    rules: ['communication.md', 'discovery.md', 'metrics.md', 'overview.md', 'prioritization.md', 'requirements.md']
+  },
+  'qa-engineering': {
+    description: 'Quality assurance programs for confident, rapid software delivery',
+    rules: ['automation.md', 'metrics.md', 'overview.md', 'quality-gates.md', 'test-design.md', 'test-strategy.md']
+  },
+  'testing': {
+    description: 'Comprehensive testing practices (TDD, test design, CI/CD integration, performance testing)',
+    rules: ['advanced-techniques.md', 'ci-cd-integration.md', 'overview.md', 'performance-testing.md', 'quality-metrics.md', 'reliability.md', 'tdd-methodology.md', 'test-data.md', 'test-design.md', 'test-types.md']
+  },
   'utility-agent': {
     description: 'AI agent utilities with context management and hallucination prevention',
     rules: ['action-control.md', 'context-management.md', 'hallucination-prevention.md', 'overview.md', 'token-optimization.md']

package/src/index.test.js

@@ -75,9 +75,17 @@ describe('Constants', () => {
       const expectedTemplates = [
         'blockchain',
         'cli-tools',
+        'data-engineering',
+        'devops-sre',
         'documentation',
         'fullstack',
+        'javascript-expert',
+        'ml-ai',
         'mobile',
+        'platform-engineering',
+        'product-manager',
+        'qa-engineering',
+        'testing',
         'utility-agent',
         'web-backend',
         'web-frontend',

package/templates/javascript-expert/.cursorrules/language-deep-dive.md

@@ -0,0 +1,245 @@
+# JavaScript Language Deep Dive
+
+Advanced JavaScript patterns and idioms for expert-level engineering.
+
+## The Event Loop
+
+Understanding execution order is fundamental:
+
+```typescript
+// Know the execution order: synchronous > microtasks > macrotasks
+console.log('1 - sync');
+
+setTimeout(() => console.log('2 - macrotask'), 0);
+
+Promise.resolve().then(() => console.log('3 - microtask'));
+
+queueMicrotask(() => console.log('4 - microtask'));
+
+console.log('5 - sync');
+
+// Output: 1, 5, 3, 4, 2
+```
+
+### Async Patterns
+
+```typescript
+// Prefer async/await over raw promises
+// But know when Promise combinators are the right tool
+
+// Parallel independent operations
+const [users, posts] = await Promise.all([
+  fetchUsers(),
+  fetchPosts(),
+]);
+
+// Race with timeout
+const withTimeout = <T>(promise: Promise<T>, ms: number): Promise<T> =>
+  Promise.race([
+    promise,
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms)
+    ),
+  ]);
+
+// Settle all, handle individually
+const results = await Promise.allSettled(tasks.map(processTask));
+const failures = results.filter(
+  (r): r is PromiseRejectedResult => r.status === 'rejected'
+);
+
+// Async iteration for streams
+async function* readChunks(stream: ReadableStream<Uint8Array>) {
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+```
+
+## Closures and Scope
+
+```typescript
+// Closures for encapsulation
+const createRateLimiter = (maxCalls: number, windowMs: number) => {
+  const calls: number[] = [];
+
+  return <T>(fn: () => T): T | null => {
+    const now = Date.now();
+    const windowStart = now - windowMs;
+    // Remove expired entries
+    while (calls.length > 0 && calls[0]! < windowStart) calls.shift();
+
+    if (calls.length >= maxCalls) return null;
+    calls.push(now);
+    return fn();
+  };
+};
+
+// Private state with closures (pre-#private fields pattern)
+// Prefer #private fields in classes, closures in functions
+```
+
+## Proxy and Reflect
+
+```typescript
+// Observable objects
+const createObservable = <T extends object>(
+  target: T,
+  onChange: (prop: string | symbol, value: unknown) => void,
+): T =>
+  new Proxy(target, {
+    set(obj, prop, value, receiver) {
+      const result = Reflect.set(obj, prop, value, receiver);
+      onChange(prop, value);
+      return result;
+    },
+  });
+
+// Validation proxies
+const createValidated = <T extends Record<string, unknown>>(
+  target: T,
+  validators: Partial<Record<keyof T, (v: unknown) => boolean>>,
+): T =>
+  new Proxy(target, {
+    set(obj, prop, value, receiver) {
+      const validate = validators[prop as keyof T];
+      if (validate && !validate(value)) {
+        throw new TypeError(`Invalid value for ${String(prop)}`);
+      }
+      return Reflect.set(obj, prop, value, receiver);
+    },
+  });
+```
+
+## WeakRef and FinalizationRegistry
+
+```typescript
+// Cache that doesn't prevent garbage collection
+class WeakCache<K extends object, V> {
+  readonly #cache = new Map<string, WeakRef<V & object>>();
+  readonly #registry = new FinalizationRegistry<string>((key) => {
+    this.#cache.delete(key);
+  });
+
+  set(key: string, value: V & object): void {
+    this.#cache.set(key, new WeakRef(value));
+    this.#registry.register(value, key);
+  }
+
+  get(key: string): V | undefined {
+    return this.#cache.get(key)?.deref();
+  }
+}
+```
+
+## Iterators and Generators
+
+```typescript
+// Custom iterable
+class Range implements Iterable<number> {
+  constructor(
+    private readonly start: number,
+    private readonly end: number,
+    private readonly step = 1,
+  ) {}
+
+  *[Symbol.iterator](): Generator<number> {
+    for (let i = this.start; i < this.end; i += this.step) {
+      yield i;
+    }
+  }
+}
+
+// Lazy evaluation with generators
+function* filter<T>(iterable: Iterable<T>, predicate: (item: T) => boolean) {
+  for (const item of iterable) {
+    if (predicate(item)) yield item;
+  }
+}
+
+function* map<T, U>(iterable: Iterable<T>, transform: (item: T) => U) {
+  for (const item of iterable) {
+    yield transform(item);
+  }
+}
+
+function* take<T>(iterable: Iterable<T>, count: number) {
+  let i = 0;
+  for (const item of iterable) {
+    if (i++ >= count) break;
+    yield item;
+  }
+}
+
+// Compose lazy operations — no intermediate arrays
+const result = [...take(
+  map(
+    filter(hugeDataset, item => item.active),
+    item => item.name,
+  ),
+  10,
+)];
+```
+
+## Structured Clone and Transfer
+
+```typescript
+// Deep clone without JSON.parse(JSON.stringify(...))
+const clone = structuredClone(complexObject);
+
+// Transfer ownership (zero-copy for ArrayBuffers)
+const buffer = new ArrayBuffer(1024);
+worker.postMessage({ buffer }, [buffer]);
+// buffer.byteLength is now 0 — ownership transferred
+```
+
+## Module Patterns
+
+```typescript
+// Named exports for tree-shaking
+export const validateEmail = (email: string): boolean => { ... };
+export const validatePhone = (phone: string): boolean => { ... };
+
+// Barrel files only at package boundaries, never internal
+// src/validators/index.ts — public API
+export { validateEmail } from './email.js';
+export { validatePhone } from './phone.js';
+
+// Dynamic imports for code splitting
+const module = await import(`./locales/${locale}.js`);
+
+// Import attributes (for JSON, CSS modules)
+import config from './config.json' with { type: 'json' };
+```
+
+## Anti-Patterns to Avoid
+
+```typescript
+// Never: for...in on arrays (iterates prototype chain)
+for (const key in array) { } // BAD
+
+// Instead: for...of, .forEach, .map, .reduce
+for (const item of array) { } // GOOD
+
+// Never: == for comparison (type coercion surprises)
+if (value == null) { } // Only acceptable case (null + undefined check)
+
+// Never: delete on arrays (creates sparse array)
+delete arr[2]; // BAD — leaves hole
+arr.splice(2, 1); // GOOD
+
+// Never: blocking the event loop
+// Use worker_threads for CPU-intensive work in Node.js
+// Use Web Workers in the browser
+
+// Never: implicit globals
+function bad() { x = 5; } // Creates global!
+// Always use const/let, always use strict mode
+```

package/templates/javascript-expert/.cursorrules/node-patterns.md

@@ -0,0 +1,184 @@
+# Node.js Patterns
+
+Expert-level Node.js patterns for building production services, CLIs, and tooling.
+
+## Runtime Essentials
+
+### Process Lifecycle
+
+```typescript
+// Graceful shutdown
+const shutdown = async (signal: string) => {
+  console.log(`Received ${signal}, shutting down gracefully...`);
+  server.close();
+  await db.disconnect();
+  process.exit(0);
+};
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+// Unhandled rejection = crash (don't swallow errors)
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled rejection:', reason);
+  process.exit(1);
+});
+```
+
+### Streams
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createGzip } from 'node:zlib';
+import { Transform } from 'node:stream';
+
+// Always use pipeline for proper error handling and cleanup
+await pipeline(
+  createReadStream('input.log'),
+  new Transform({
+    transform(chunk, _encoding, callback) {
+      const filtered = chunk
+        .toString()
+        .split('\n')
+        .filter((line: string) => line.includes('ERROR'))
+        .join('\n');
+      callback(null, filtered);
+    },
+  }),
+  createGzip(),
+  createWriteStream('errors.log.gz'),
+);
+
+// Web-standard streams in Node.js
+const response = await fetch(url);
+const reader = response.body!.getReader();
+```
+
+### Worker Threads
+
+```typescript
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
+
+if (isMainThread) {
+  const runWorker = <T>(data: unknown): Promise<T> =>
+    new Promise((resolve, reject) => {
+      const worker = new Worker(new URL(import.meta.url), { workerData: data });
+      worker.on('message', resolve);
+      worker.on('error', reject);
+    });
+
+  const result = await runWorker({ task: 'hash', input: largeBuffer });
+} else {
+  // Worker thread — CPU-intensive work here
+  const result = performExpensiveComputation(workerData);
+  parentPort!.postMessage(result);
+}
+```
+
+### File System
+
+```typescript
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+
+// Always use fs/promises, never sync variants in async code
+const data = await readFile('config.json', 'utf-8');
+
+// Check existence without TOCTOU race
+const fileExists = async (path: string): Promise<boolean> => {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// Atomic writes to prevent corruption
+import { writeFile as atomicWrite } from 'atomically';
+await atomicWrite('important.json', JSON.stringify(data));
+
+// Use node:path for all path manipulation
+import { join, resolve, extname, basename } from 'node:path';
+```
+
+## Module System
+
+```typescript
+// Use node: protocol for builtins (explicit, no ambiguity)
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+// ESM by default — set "type": "module" in package.json
+// Use .js extensions in imports (required for ESM)
+import { validate } from './validators.js';
+```
+
+## Error Handling in Node.js
+
+```typescript
+// Custom error classes with cause chaining
+class DatabaseError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'DatabaseError';
+  }
+}
+
+// Wrap external errors with context
+try {
+  await db.query(sql);
+} catch (err) {
+  throw new DatabaseError(`Query failed: ${sql}`, { cause: err });
+}
+
+// AbortController for cancellation
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  const response = await fetch(url, { signal: controller.signal });
+} catch (err) {
+  if (err instanceof DOMException && err.name === 'AbortError') {
+    // Handle timeout specifically
+  }
+  throw err;
+}
+```
+
+## Configuration
+
+```typescript
+// Validate environment at startup, fail fast
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  PORT: z.coerce.number().int().positive().default(3000),
+  DATABASE_URL: z.string().url(),
+  API_KEY: z.string().min(1),
+});
+
+// Parse once at startup — crash if invalid
+export const env = EnvSchema.parse(process.env);
+```
+
+## Anti-Patterns
+
+```typescript
+// Never: require() in ESM (use import or createRequire)
+// Never: sync fs operations in request handlers
+// Never: unbounded concurrency
+// Bad:
+await Promise.all(thousandItems.map(item => processItem(item)));
+// Good: Use p-limit or manual batching
+import pLimit from 'p-limit';
+const limit = pLimit(10);
+await Promise.all(thousandItems.map(item => limit(() => processItem(item))));
+
+// Never: string concatenation for SQL (injection risk)
+// Never: eval() or new Function() with user input
+// Never: process.exit() without cleanup
+```

package/templates/javascript-expert/.cursorrules/overview.md

@@ -0,0 +1,130 @@
+# JavaScript Expert
+
+Guidelines for principal-level JavaScript engineering across all runtimes, frameworks, and paradigms.
+
+## Scope
+
+This ruleset applies to:
+- Node.js services, CLIs, and tooling
+- React, Vue, Angular, Svelte, and other UI frameworks
+- Vanilla JavaScript and Web APIs
+- TypeScript (strict mode, always)
+- Build tools, bundlers, and transpilers
+- Testing at every level (unit, integration, E2E, performance)
+
+## Core Philosophy
+
+JavaScript is the runtime. Know it deeply:
+- The event loop is not optional knowledge — it's the foundation
+- Prototypes, closures, and the module system are first principles
+- The spec (ECMAScript) is the source of truth, not blog posts
+- Every abstraction leaks — understand what's underneath
+
+## Key Principles
+
+### 1. Language Mastery Over Framework Dependence
+
+Frameworks come and go. JavaScript fundamentals are permanent:
+- Understand `this` binding rules (default, implicit, explicit, `new`)
+- Know the difference between the task queue, microtask queue, and rendering pipeline
+- Use native APIs before reaching for libraries (`structuredClone`, `AbortController`, `Intl`, `URL`, `crypto.subtle`)
+- Understand generator functions, iterators, and async iteration
+
+### 2. Type Safety Is Non-Negotiable
+
+```typescript
+// Always: strict TypeScript
+// tsconfig.json: "strict": true, "noUncheckedIndexedAccess": true
+
+// Prefer discriminated unions over optional fields
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+// Use const assertions and template literal types
+const EVENTS = ['click', 'keydown', 'submit'] as const;
+type EventName = (typeof EVENTS)[number];
+
+// Branded types for domain safety
+type UserId = string & { readonly __brand: unique symbol };
+type Email = string & { readonly __brand: unique symbol };
+```
+
+### 3. Functional by Default, Object-Oriented When It Fits
+
+```typescript
+// Prefer pure functions and composition
+const pipe = <T>(...fns: Array<(arg: T) => T>) =>
+  (value: T): T => fns.reduce((acc, fn) => fn(acc), value);
+
+const processUser = pipe(
+  validateInput,
+  normalizeEmail,
+  hashPassword,
+  persistToDb,
+);
+
+// Use classes for stateful services with clear lifecycle
+class ConnectionPool {
+  readonly #connections: Map<string, Connection>;
+  constructor(private readonly config: PoolConfig) {
+    this.#connections = new Map();
+  }
+}
+```
+
+### 4. Performance Is a Feature
+
+- Profile before optimizing — measure, don't guess
+- Understand V8 optimization patterns (monomorphic calls, hidden classes, inline caches)
+- Know when to use `Map`/`Set` over plain objects and arrays
+- Avoid unnecessary allocations in hot paths
+- Use `WeakRef` and `FinalizationRegistry` when appropriate
+
+### 5. Error Handling Is Control Flow
+
+```typescript
+// Use Result types, not thrown exceptions for expected failures
+function parseConfig(raw: string): Result<Config> {
+  try {
+    const parsed = JSON.parse(raw);
+    const validated = ConfigSchema.safeParse(parsed);
+    if (!validated.success) {
+      return { ok: false, error: new ValidationError(validated.error) };
+    }
+    return { ok: true, value: validated.data };
+  } catch {
+    return { ok: false, error: new ParseError('Invalid JSON') };
+  }
+}
+
+// Reserve throw for programmer errors (invariant violations)
+function assertNonNull<T>(value: T | null | undefined, msg: string): asserts value is T {
+  if (value == null) throw new Error(`Invariant: ${msg}`);
+}
+```
+
+## Project Structure
+
+```
+src/
+├── core/              # Pure business logic, zero dependencies
+├── adapters/          # External integrations (DB, HTTP, FS)
+├── services/          # Orchestration layer
+├── utils/             # Pure utility functions
+├── types/             # TypeScript type definitions
+├── __tests__/         # Test files (co-located or centralized)
+└── index.ts           # Public API surface
+```
+
+## Definition of Done
+
+A JavaScript feature is complete when:
+- [ ] TypeScript strict mode passes with zero errors
+- [ ] All code paths have explicit types (no `any`, no implicit `any`)
+- [ ] Unit tests cover logic branches and edge cases
+- [ ] Integration tests verify external boundaries
+- [ ] Error cases are tested, not just happy paths
+- [ ] No floating promises (all async paths handled)
+- [ ] No memory leaks in long-running code paths
+- [ ] Bundle impact assessed (for client-side code)