agentic-team-templates 0.3.0

package/templates/web-frontend/.cursorrules/component-patterns.md

@@ -0,0 +1,204 @@
+# Component Patterns
+
+Best practices for building frontend components.
+
+## Composition Over Inheritance
+
+Build complex UIs by composing small components, not extending base classes.
+
+```tsx
+// Good: Composition
+const UserCard = ({ user }: { user: User }) => (
+  <Card>
+    <Avatar src={user.avatar} />
+    <CardContent>
+      <UserName name={user.name} />
+      <UserBio bio={user.bio} />
+    </CardContent>
+  </Card>
+);
+
+// Bad: Inheritance
+class UserCard extends BaseCard {
+  renderContent() { ... }
+}
+```
+
+## Pure Components
+
+Components should be predictable: same props = same output.
+
+```tsx
+// Good: Pure component
+const Greeting = ({ name }: { name: string }) => (
+  <h1>Hello, {name}!</h1>
+);
+
+// Bad: Side effects in render
+const Greeting = ({ name }: { name: string }) => {
+  document.title = name;  // Side effect!
+  return <h1>Hello, {name}!</h1>;
+};
+```
+
+## Single Responsibility
+
+Each component should do one thing well.
+
+```tsx
+// Good: Focused components
+const UserAvatar = ({ src, alt }: AvatarProps) => (
+  <img src={src} alt={alt} className="avatar" />
+);
+
+const UserName = ({ name }: { name: string }) => (
+  <span className="user-name">{name}</span>
+);
+
+// Bad: Component doing too much
+const UserDisplay = ({ user }: { user: User }) => {
+  // Fetching, formatting, displaying, handling clicks...
+  // This should be split up
+};
+```
+
+## Props Interface
+
+Define clear, typed interfaces for component props.
+
+```tsx
+// Good: Explicit props interface
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  onClick: () => void;
+  children: React.ReactNode;
+}
+
+const Button = ({ variant, size = 'md', disabled, onClick, children }: ButtonProps) => (
+  // ...
+);
+
+// Bad: Implicit or any props
+const Button = (props: any) => ( ... );
+```
+
+## Controlled vs Uncontrolled
+
+Prefer controlled components for form inputs.
+
+```tsx
+// Good: Controlled input
+const SearchInput = ({ value, onChange }: SearchInputProps) => (
+  <input
+    type="text"
+    value={value}
+    onChange={(e) => onChange(e.target.value)}
+  />
+);
+
+// Acceptable for simple cases: Uncontrolled with ref
+const FileInput = ({ onFile }: FileInputProps) => {
+  const ref = useRef<HTMLInputElement>(null);
+  return <input type="file" ref={ref} onChange={...} />;
+};
+```
+
+## Conditional Rendering
+
+Use clear patterns for conditional UI.
+
+```tsx
+// Good: Early return for guards
+const UserProfile = ({ user }: { user: User | null }) => {
+  if (!user) return <NotLoggedIn />;
+  return <Profile user={user} />;
+};
+
+// Good: Ternary for simple conditions
+const Status = ({ isActive }: { isActive: boolean }) => (
+  <span>{isActive ? 'Active' : 'Inactive'}</span>
+);
+
+// Good: && for optional rendering
+const Notification = ({ message }: { message?: string }) => (
+  <div>
+    {message && <Alert>{message}</Alert>}
+  </div>
+);
+```
+
+## Handling Events
+
+Keep event handlers clean and focused.
+
+```tsx
+// Good: Handler defined separately
+const Form = () => {
+  const handleSubmit = (e: FormEvent) => {
+    e.preventDefault();
+    // Submit logic
+  };
+
+  return <form onSubmit={handleSubmit}>...</form>;
+};
+
+// Avoid: Complex inline handlers
+const Form = () => (
+  <form onSubmit={(e) => {
+    e.preventDefault();
+    // Lots of logic here...
+  }}>
+    ...
+  </form>
+);
+```
+
+## Children Patterns
+
+Use children effectively for composition.
+
+```tsx
+// Good: Children for content injection
+const Card = ({ title, children }: CardProps) => (
+  <div className="card">
+    <h2>{title}</h2>
+    <div className="card-content">{children}</div>
+  </div>
+);
+
+// Usage
+<Card title="Settings">
+  <SettingsForm />
+</Card>
+```
+
+## Render Props & Compound Components
+
+For complex reusable patterns.
+
+```tsx
+// Compound components pattern
+const Tabs = ({ children }: TabsProps) => {
+  const [active, setActive] = useState(0);
+  return (
+    <TabsContext.Provider value={{ active, setActive }}>
+      {children}
+    </TabsContext.Provider>
+  );
+};
+
+Tabs.List = TabsList;
+Tabs.Panel = TabsPanel;
+
+// Usage
+<Tabs>
+  <Tabs.List>
+    <Tabs.Tab>One</Tabs.Tab>
+    <Tabs.Tab>Two</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel>Content One</Tabs.Panel>
+  <Tabs.Panel>Content Two</Tabs.Panel>
+</Tabs>
+```

package/templates/web-frontend/.cursorrules/overview.md

@@ -0,0 +1,72 @@
+# Web Frontend Development
+
+Guidelines for building modern web frontend applications.
+
+## Scope
+
+This ruleset applies to:
+- Single-page applications (SPAs)
+- Server-rendered web applications
+- Static sites with dynamic components
+- Progressive web applications (PWAs)
+
+## Core Technologies
+
+Frontend development typically involves:
+- JavaScript/TypeScript
+- Component frameworks (React, Vue, Angular, Svelte, etc.)
+- CSS/Styling solutions (CSS Modules, Tailwind, Styled Components, etc.)
+- Build tools (Vite, webpack, esbuild, etc.)
+- Testing frameworks (Jest, Vitest, Testing Library, Playwright, etc.)
+
+## Key Principles
+
+### 1. User Experience First
+- Fast initial load
+- Responsive to user input
+- Works across devices and browsers
+- Accessible to all users
+
+### 2. Component-Based Architecture
+- Small, focused components
+- Reusable and composable
+- Clear data flow
+- Separation of concerns
+
+### 3. Type Safety
+- Use TypeScript for all new code
+- Define explicit types for props and state
+- Avoid `any` type
+- Let types document your code
+
+### 4. Progressive Enhancement
+- Core functionality works without JavaScript where possible
+- Enhanced experience with JavaScript
+- Graceful degradation for older browsers
+
+## Project Structure
+
+```
+src/
+├── components/        # Reusable UI components
+│   ├── ui/           # Primitive components (Button, Input, Card)
+│   └── features/     # Feature-specific components
+├── pages/            # Page/route components
+├── hooks/            # Custom React hooks (or equivalent)
+├── lib/              # Business logic, utilities
+├── types/            # TypeScript type definitions
+├── styles/           # Global styles, theme
+└── assets/           # Static assets (images, fonts)
+```
+
+## Definition of Done
+
+A frontend feature is complete when:
+- [ ] Component renders correctly
+- [ ] Responsive across breakpoints
+- [ ] Keyboard navigable
+- [ ] Screen reader accessible
+- [ ] Loading and error states handled
+- [ ] Tests written and passing
+- [ ] No TypeScript errors
+- [ ] Meets performance budgets

package/templates/web-frontend/.cursorrules/performance.md

@@ -0,0 +1,325 @@
+# Frontend Performance
+
+Guidelines for building fast, responsive web applications.
+
+## Core Web Vitals
+
+### Largest Contentful Paint (LCP)
+Measures loading performance. Target: < 2.5 seconds.
+
+**Optimize by:**
+- Optimize critical rendering path
+- Preload critical resources
+- Use efficient image formats (WebP, AVIF)
+- Implement proper caching
+
+### First Input Delay (FID) / Interaction to Next Paint (INP)
+Measures interactivity. Target: < 100ms / < 200ms.
+
+**Optimize by:**
+- Break up long tasks
+- Minimize main thread work
+- Use web workers for heavy computation
+- Defer non-critical JavaScript
+
+### Cumulative Layout Shift (CLS)
+Measures visual stability. Target: < 0.1.
+
+**Optimize by:**
+- Always include size attributes on images/video
+- Reserve space for dynamic content
+- Avoid inserting content above existing content
+- Use CSS containment
+
+## JavaScript Performance
+
+### Code Splitting
+
+Load code only when needed.
+
+```tsx
+// Route-based splitting
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Settings = lazy(() => import('./pages/Settings'));
+
+function App() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <Routes>
+        <Route path="/dashboard" element={<Dashboard />} />
+        <Route path="/settings" element={<Settings />} />
+      </Routes>
+    </Suspense>
+  );
+}
+
+// Component-based splitting
+const HeavyChart = lazy(() => import('./components/HeavyChart'));
+
+function Dashboard() {
+  return (
+    <div>
+      <Suspense fallback={<ChartSkeleton />}>
+        <HeavyChart data={data} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+### Minimize Bundle Size
+
+```tsx
+// Bad: Import entire library
+import _ from 'lodash';
+_.debounce(fn, 300);
+
+// Good: Import only what you need
+import debounce from 'lodash/debounce';
+debounce(fn, 300);
+
+// Better: Use native or smaller alternatives
+function debounce(fn, ms) {
+  let timeoutId;
+  return (...args) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn(...args), ms);
+  };
+}
+```
+
+### Avoid Memory Leaks
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+
+  fetchData({ signal: controller.signal })
+    .then(setData)
+    .catch(err => {
+      if (err.name !== 'AbortError') throw err;
+    });
+
+  // Cleanup on unmount
+  return () => controller.abort();
+}, []);
+
+useEffect(() => {
+  const handler = () => { ... };
+  window.addEventListener('resize', handler);
+
+  // Remove listener on cleanup
+  return () => window.removeEventListener('resize', handler);
+}, []);
+```
+
+## React-Specific Optimizations
+
+### Prevent Unnecessary Re-renders
+
+```tsx
+// Memoize expensive components
+const ExpensiveList = memo(({ items }: Props) => {
+  return items.map(item => <ExpensiveItem key={item.id} {...item} />);
+});
+
+// Memoize expensive calculations
+const sortedItems = useMemo(
+  () => items.slice().sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+
+// Memoize callbacks passed to children
+const handleClick = useCallback((id: string) => {
+  setSelected(id);
+}, []);
+```
+
+### Virtualize Long Lists
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }) {
+  const parentRef = useRef(null);
+
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50,
+  });
+
+  return (
+    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
+      <div style={{ height: virtualizer.getTotalSize() }}>
+        {virtualizer.getVirtualItems().map((virtualItem) => (
+          <div
+            key={virtualItem.key}
+            style={{
+              position: 'absolute',
+              top: virtualItem.start,
+              height: virtualItem.size,
+            }}
+          >
+            {items[virtualItem.index].name}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Defer Non-Critical Updates
+
+```tsx
+// Use startTransition for non-urgent updates
+import { startTransition } from 'react';
+
+function SearchPage() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState([]);
+
+  const handleChange = (e) => {
+    // Urgent: Update input immediately
+    setQuery(e.target.value);
+
+    // Non-urgent: Can be interrupted
+    startTransition(() => {
+      setResults(filterResults(e.target.value));
+    });
+  };
+}
+```
+
+## Image Optimization
+
+### Use Modern Formats
+
+```tsx
+<picture>
+  <source srcset="image.avif" type="image/avif" />
+  <source srcset="image.webp" type="image/webp" />
+  <img src="image.jpg" alt="Description" />
+</picture>
+```
+
+### Lazy Load Images
+
+```tsx
+// Native lazy loading
+<img src="image.jpg" loading="lazy" alt="Description" />
+
+// With blur placeholder
+<Image
+  src="/image.jpg"
+  alt="Description"
+  placeholder="blur"
+  blurDataURL={blurHash}
+/>
+```
+
+### Proper Sizing
+
+```tsx
+// Always specify dimensions
+<img
+  src="image.jpg"
+  width={800}
+  height={600}
+  alt="Description"
+/>
+
+// Responsive images
+<img
+  src="image-800.jpg"
+  srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
+  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
+  alt="Description"
+/>
+```
+
+## Network Optimization
+
+### Preload Critical Resources
+
+```html
+<link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin />
+<link rel="preload" href="/hero.jpg" as="image" />
+<link rel="preconnect" href="https://api.example.com" />
+```
+
+### Cache Effectively
+
+```ts
+// Service worker caching
+// Cache static assets aggressively
+// Network-first for API calls
+// Stale-while-revalidate for semi-static content
+```
+
+### Compress Assets
+
+- Enable gzip/brotli compression on server
+- Minify JS, CSS, HTML
+- Optimize SVGs
+
+## Monitoring
+
+### Performance Metrics
+
+```ts
+// Web Vitals library
+import { onCLS, onFID, onLCP } from 'web-vitals';
+
+onCLS(console.log);
+onFID(console.log);
+onLCP(console.log);
+```
+
+### Performance Budgets
+
+Set limits and alert on regression:
+- JavaScript bundle: < 200KB (gzipped)
+- CSS: < 50KB (gzipped)
+- LCP: < 2.5s
+- TTI: < 5s
+
+## Anti-Patterns
+
+### Blocking the Main Thread
+
+```tsx
+// Bad: Synchronous heavy computation
+const sorted = hugeArray.sort((a, b) => complexComparison(a, b));
+
+// Good: Use web worker or break into chunks
+const worker = new Worker('sort-worker.js');
+worker.postMessage(hugeArray);
+```
+
+### Layout Thrashing
+
+```tsx
+// Bad: Read/write in loop
+items.forEach(item => {
+  const height = item.offsetHeight;  // Read
+  item.style.height = height + 10;    // Write
+});
+
+// Good: Batch reads then writes
+const heights = items.map(item => item.offsetHeight);
+items.forEach((item, i) => {
+  item.style.height = heights[i] + 10;
+});
+```
+
+### Importing Everything
+
+```tsx
+// Bad
+import * as utils from './utils';
+
+// Good
+import { specificUtil } from './utils';
+```