agentic-team-templates 0.9.2 → 0.10.0

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

@@ -0,0 +1,203 @@
+# JavaScript Performance
+
+Expert-level performance patterns for JavaScript across browser and server environments.
+
+## Profiling First
+
+Never optimize without data. Always profile before and after changes.
+
+```typescript
+// Node.js profiling
+// node --prof app.js
+// node --prof-process isolate-*.log
+
+// Browser: use Performance API
+performance.mark('operation-start');
+doExpensiveWork();
+performance.mark('operation-end');
+performance.measure('operation', 'operation-start', 'operation-end');
+const duration = performance.getEntriesByName('operation')[0]!.duration;
+```
+
+## V8 Optimization Patterns
+
+### Monomorphic Functions
+
+```typescript
+// Good: Consistent argument shapes (monomorphic — V8 optimizes)
+function processItem(item: { id: string; value: number }) {
+  return item.id + item.value;
+}
+
+items.forEach(processItem); // All same shape — fast
+
+// Bad: Polymorphic — different shapes deoptimize
+function processAnything(item: any) {
+  return item.id + item.value;
+}
+// Called with { id, value }, { id, value, extra }, { id, value, other }
+// V8 can't optimize — megamorphic IC
+```
+
+### Hidden Classes
+
+```typescript
+// Good: Initialize all properties in the same order
+class Point {
+  x: number;
+  y: number;
+  constructor(x: number, y: number) {
+    this.x = x; // Always x first
+    this.y = y; // Always y second
+  }
+}
+
+// Bad: Conditional property assignment
+function createPoint(x: number, y: number, z?: number) {
+  const p: any = {};
+  p.x = x;
+  if (z) p.z = z; // Different hidden class!
+  p.y = y;
+  return p;
+}
+```
+
+## Data Structures
+
+```typescript
+// Map vs Object
+// Use Map when: keys are dynamic, non-string keys, frequent add/delete
+const cache = new Map<string, CacheEntry>();
+
+// Use Object when: static shape, string keys, serialization needed
+const config = { host: 'localhost', port: 3000 };
+
+// Set vs Array for membership tests
+// O(1) lookup vs O(n)
+const allowedIds = new Set(['a', 'b', 'c']);
+if (allowedIds.has(id)) { ... }
+
+// TypedArrays for numeric data
+const buffer = new Float64Array(1000);
+// 8x more memory efficient than number[]
+// Faster iteration for numeric operations
+```
+
+## Memory Management
+
+```typescript
+// Avoid memory leaks in event listeners
+class Component {
+  #controller = new AbortController();
+
+  mount() {
+    window.addEventListener('resize', this.#onResize, {
+      signal: this.#controller.signal,
+    });
+  }
+
+  unmount() {
+    this.#controller.abort(); // Removes all listeners at once
+  }
+
+  #onResize = () => { ... };
+}
+
+// WeakMap for metadata on objects without preventing GC
+const metadata = new WeakMap<object, Metadata>();
+
+function annotate(obj: object, data: Metadata) {
+  metadata.set(obj, data); // Won't prevent obj from being GC'd
+}
+
+// Avoid closures that capture large scopes
+// Bad: Entire scope captured
+function createHandler(largeData: BigObject[]) {
+  const id = largeData[0]!.id; // Only need id
+  return () => console.log(largeData); // Captures entire array!
+}
+
+// Good: Capture only what's needed
+function createHandler(largeData: BigObject[]) {
+  const id = largeData[0]!.id;
+  return () => console.log(id); // Only captures id
+}
+```
+
+## Async Performance
+
+```typescript
+// Batch concurrent operations with limits
+async function processInBatches<T, R>(
+  items: T[],
+  fn: (item: T) => Promise<R>,
+  batchSize: number,
+): Promise<R[]> {
+  const results: R[] = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize);
+    const batchResults = await Promise.all(batch.map(fn));
+    results.push(...batchResults);
+  }
+  return results;
+}
+
+// Use streams for large data — don't load everything into memory
+// See node-patterns.md for stream examples
+
+// requestAnimationFrame for visual updates (browser)
+function animateValue(element: HTMLElement, from: number, to: number) {
+  const start = performance.now();
+  const duration = 300;
+
+  const tick = (now: number) => {
+    const progress = Math.min((now - start) / duration, 1);
+    const value = from + (to - from) * progress;
+    element.textContent = String(Math.round(value));
+    if (progress < 1) requestAnimationFrame(tick);
+  };
+
+  requestAnimationFrame(tick);
+}
+```
+
+## Bundle Size (Client-Side)
+
+```typescript
+// Dynamic imports for code splitting
+const AdminPanel = lazy(() => import('./AdminPanel.js'));
+
+// Tree-shakeable exports (named, not default)
+export { validateEmail } from './validators.js';
+
+// Avoid barrel file re-exports for large packages
+// Bad: import { Button } from './components'; // Pulls everything
+// Good: import { Button } from './components/Button.js';
+
+// Check bundle impact before adding dependencies
+// npx bundlephobia <package-name>
+
+// Prefer native APIs over libraries
+// Use Intl.DateTimeFormat instead of moment/date-fns for formatting
+// Use structuredClone instead of lodash.cloneDeep
+// Use URL instead of query-string
+// Use AbortController instead of custom cancellation
+// Use crypto.randomUUID() instead of uuid
+```
+
+## Anti-Patterns
+
+```typescript
+// Never: Premature optimization
+// Measure first, optimize the bottleneck, measure again
+
+// Never: Micro-optimizations that harm readability
+// arr[arr.length - 1] vs arr.at(-1) — the difference is negligible
+
+// Never: Caching without invalidation strategy
+// Every cache needs a TTL, max size, or explicit invalidation
+
+// Never: Synchronous operations blocking the event loop
+// Use worker threads for CPU work
+// Use async I/O for file/network operations
+```

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

@@ -0,0 +1,249 @@
+# React Patterns
+
+Expert-level React patterns for building production UI applications.
+
+## Component Design
+
+### Server Components First (React 19+)
+
+```tsx
+// Default: Server Components — no 'use client' directive
+// They run on the server, have zero client bundle cost
+async function ProjectList() {
+  const projects = await db.projects.findMany();
+  return (
+    <ul>
+      {projects.map(p => <ProjectCard key={p.id} project={p} />)}
+    </ul>
+  );
+}
+
+// Only add 'use client' when you need:
+// - useState, useEffect, useReducer
+// - Browser APIs (window, document)
+// - Event handlers (onClick, onChange)
+// - Custom hooks that use client features
+'use client';
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('');
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+}
+```
+
+### Composition Patterns
+
+```tsx
+// Compound components for related UI
+function Tabs({ children }: { children: React.ReactNode }) {
+  const [active, setActive] = useState(0);
+  return (
+    <TabsContext.Provider value={{ active, setActive }}>
+      {children}
+    </TabsContext.Provider>
+  );
+}
+
+Tabs.List = function TabList({ children }: { children: React.ReactNode }) { ... };
+Tabs.Panel = function TabPanel({ children, index }: { children: React.ReactNode; index: number }) { ... };
+
+// Usage — clean, declarative API
+<Tabs>
+  <Tabs.List>
+    <Tab>Overview</Tab>
+    <Tab>Details</Tab>
+  </Tabs.List>
+  <Tabs.Panel index={0}>Overview content</Tabs.Panel>
+  <Tabs.Panel index={1}>Details content</Tabs.Panel>
+</Tabs>
+```
+
+### Render Props and Children as Function
+
+```tsx
+// For maximum flexibility in rendering
+interface DataLoaderProps<T> {
+  load: () => Promise<T>;
+  children: (data: T) => React.ReactNode;
+  fallback?: React.ReactNode;
+}
+
+function DataLoader<T>({ load, children, fallback }: DataLoaderProps<T>) {
+  const data = use(load());
+  return <>{children(data)}</>;
+}
+
+// Usage
+<Suspense fallback={<Spinner />}>
+  <DataLoader load={fetchUsers}>
+    {users => <UserList users={users} />}
+  </DataLoader>
+</Suspense>
+```
+
+## Hooks
+
+### Custom Hook Patterns
+
+```tsx
+// Encapsulate complex state logic
+function useOptimisticUpdate<T>(
+  current: T,
+  updateFn: (value: T) => Promise<void>,
+) {
+  const [optimistic, setOptimistic] = useState(current);
+  const [isPending, startTransition] = useTransition();
+
+  const update = (next: T) => {
+    setOptimistic(next);
+    startTransition(async () => {
+      try {
+        await updateFn(next);
+      } catch {
+        setOptimistic(current); // Rollback
+      }
+    });
+  };
+
+  return [optimistic, update, isPending] as const;
+}
+
+// Debounced value hook
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debounced;
+}
+```
+
+### Hook Rules (Enforced, Not Suggested)
+
+- Only call hooks at the top level — never inside conditions, loops, or nested functions
+- Only call hooks from React function components or custom hooks
+- Custom hooks must start with `use`
+- Always include correct dependencies in `useEffect`/`useMemo`/`useCallback`
+
+## State Management
+
+```tsx
+// Rule: Use the simplest tool that works
+// 1. useState — local state
+// 2. useReducer — complex local state with actions
+// 3. Context — low-frequency shared state (theme, auth, locale)
+// 4. External store (Zustand, Jotai) — high-frequency shared state
+
+// useReducer for complex state machines
+type Action =
+  | { type: 'FETCH_START' }
+  | { type: 'FETCH_SUCCESS'; payload: User[] }
+  | { type: 'FETCH_ERROR'; error: Error };
+
+interface State {
+  status: 'idle' | 'loading' | 'success' | 'error';
+  data: User[];
+  error: Error | null;
+}
+
+const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case 'FETCH_START':
+      return { ...state, status: 'loading', error: null };
+    case 'FETCH_SUCCESS':
+      return { status: 'success', data: action.payload, error: null };
+    case 'FETCH_ERROR':
+      return { ...state, status: 'error', error: action.error };
+  }
+};
+```
+
+## Performance
+
+```tsx
+// React Compiler (React 19+) handles most memoization automatically
+// Only manually optimize when profiling shows a bottleneck
+
+// Virtualize large lists
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }: { items: Item[] }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50,
+  });
+
+  return (
+    <div ref={parentRef} style={{ overflow: 'auto', height: '500px' }}>
+      <div style={{ height: virtualizer.getTotalSize() }}>
+        {virtualizer.getVirtualItems().map(row => (
+          <div key={row.key} style={{
+            position: 'absolute',
+            top: row.start,
+            height: row.size,
+          }}>
+            <ItemRow item={items[row.index]!} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Error Boundaries
+
+```tsx
+// Every route and major feature section needs an error boundary
+'use client';
+
+interface ErrorBoundaryProps {
+  children: React.ReactNode;
+  fallback: (error: Error, reset: () => void) => React.ReactNode;
+}
+
+class ErrorBoundary extends React.Component<ErrorBoundaryProps, { error: Error | null }> {
+  state = { error: null as Error | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  render() {
+    if (this.state.error) {
+      return this.props.fallback(this.state.error, () => this.setState({ error: null }));
+    }
+    return this.props.children;
+  }
+}
+```
+
+## Anti-Patterns
+
+```tsx
+// Never: useEffect for derived state
+// Bad
+const [fullName, setFullName] = useState('');
+useEffect(() => {
+  setFullName(`${firstName} ${lastName}`);
+}, [firstName, lastName]);
+// Good
+const fullName = `${firstName} ${lastName}`;
+
+// Never: Object/array literals as default props (new reference every render)
+// Bad
+function List({ items = [] }) { ... }
+// Good
+const EMPTY: readonly Item[] = [];
+function List({ items = EMPTY }: { items?: readonly Item[] }) { ... }
+
+// Never: index as key for dynamic lists
+// Bad
+{items.map((item, i) => <Item key={i} item={item} />)}
+// Good
+{items.map(item => <Item key={item.id} item={item} />)}
+```