class-ai-agent 1.2.0

package/.claude/commands/spec.md

@@ -0,0 +1,95 @@
+---
+name: spec
+description: Spec before code — structured PRD creation for new features
+---
+
+# /spec — Specification-Driven Development
+
+> "Plan the work, then work the plan."
+
+## Purpose
+
+Create a comprehensive specification document **before** writing any code. This ensures alignment on requirements, constraints, and acceptance criteria.
+
+## Workflow
+
+### Phase 1: Discovery (Ask Questions)
+
+Before generating a spec, gather requirements by asking:
+
+**Scope**
+- What is the objective of this feature?
+- Who are the target users?
+- What problem does this solve?
+
+**Features**
+- What are the core features (MVP)?
+- What are the acceptance criteria for each?
+- What is explicitly out of scope?
+
+**Technical**
+- Any tech stack preferences or constraints?
+- Integration points with existing systems?
+- Performance requirements?
+
+### Phase 2: Generate Specification
+
+After discovery, produce `SPEC.md` with these sections:
+
+```markdown
+# Feature: [Name]
+
+## Objective
+[1-2 sentences describing the goal]
+
+## Target Users
+[Who will use this and why]
+
+## Core Features
+1. [Feature A] — [Acceptance criteria]
+2. [Feature B] — [Acceptance criteria]
+3. [Feature C] — [Acceptance criteria]
+
+## Out of Scope
+- [What we're NOT building in this iteration]
+
+## Technical Approach
+- Tech stack decisions
+- Data models
+- API contracts (if applicable)
+- Integration points
+
+## Code Style
+- Follow rules in `.claude/rules/`
+- [Any feature-specific conventions]
+
+## Testing Strategy
+- Unit tests for: [areas]
+- Integration tests for: [areas]
+- E2E tests for: [critical paths]
+
+## Boundaries
+### Always Do
+- [Non-negotiables]
+
+### Ask First
+- [Decisions requiring approval]
+
+### Never Do
+- [Hard constraints]
+```
+
+### Phase 3: Review & Confirm
+
+- Present the spec to the user
+- Confirm before proceeding to `/plan`
+- Save as `SPEC.md` in project root or `docs/specs/[feature].md`
+
+## Output
+
+- `SPEC.md` — The specification document
+- Clear alignment on what to build
+
+## Next Step
+
+After spec is approved, run `/plan` to decompose into tasks.

package/.claude/commands/test.md

@@ -0,0 +1,214 @@
+---
+name: test
+description: Write tests using TDD patterns — tests are proof of correctness
+---
+
+# /test — Test-Driven Development
+
+> "Tests are proof, not afterthought."
+
+## Purpose
+
+Write tests that prove code works correctly. Use the RED-GREEN-REFACTOR cycle for new features and the Prove-It pattern for bug fixes.
+
+## For New Features: RED-GREEN-REFACTOR
+
+### RED: Write Failing Test First
+
+```javascript
+describe('UserService.findById', () => {
+  it('should return user when found', async () => {
+    // Arrange
+    const userId = 'user-123';
+    
+    // Act
+    const user = await userService.findById(userId);
+    
+    // Assert
+    expect(user).toBeDefined();
+    expect(user.id).toBe(userId);
+  });
+
+  it('should throw NotFoundError when user does not exist', async () => {
+    await expect(userService.findById('non-existent'))
+      .rejects.toThrow(NotFoundError);
+  });
+});
+```
+
+Run tests — **they should fail** (proves nothing is implemented yet).
+
+### GREEN: Write Minimal Code to Pass
+
+```javascript
+async findById(id: string): Promise<User> {
+  const user = await this.db.user.findUnique({ where: { id } });
+  if (!user) throw new NotFoundError('User not found');
+  return user;
+}
+```
+
+Run tests — **they should pass**.
+
+### REFACTOR: Improve While Green
+
+Clean up code while keeping tests passing:
+- Better naming
+- Extract helpers
+- Remove duplication
+
+---
+
+## For Bug Fixes: Prove-It Pattern
+
+### Step 1: Write Test That Reproduces the Bug
+
+```javascript
+it('should not duplicate items when adding to cart twice', async () => {
+  // This test should FAIL with the current buggy code
+  await cart.addItem('product-1', 1);
+  await cart.addItem('product-1', 1);
+  
+  expect(cart.items).toHaveLength(1);
+  expect(cart.items[0].quantity).toBe(2);
+});
+```
+
+### Step 2: Verify Test Fails
+
+Run the test — confirm it **fails** (proving the bug exists).
+
+### Step 3: Fix the Bug
+
+```javascript
+async addItem(productId: string, quantity: number) {
+  const existing = this.items.find(i => i.productId === productId);
+  if (existing) {
+    existing.quantity += quantity;  // Fix: increment instead of duplicate
+  } else {
+    this.items.push({ productId, quantity });
+  }
+}
+```
+
+### Step 4: Verify Test Passes
+
+Run the test — confirm it **passes** (proving the fix works).
+
+### Step 5: Run Full Suite
+
+```bash
+npm test  # Ensure no regressions
+```
+
+---
+
+## Test Pyramid
+
+| Level | Percentage | Speed | Scope |
+|-------|------------|-------|-------|
+| **Unit** | 80% | ms | Single function, no I/O |
+| **Integration** | 15% | seconds | API + DB, component interactions |
+| **E2E** | 5% | minutes | Full user flows |
+
+---
+
+## Writing Good Tests
+
+### Arrange-Act-Assert Pattern
+
+```javascript
+it('should calculate total with discount', () => {
+  // Arrange — setup
+  const cart = new Cart();
+  cart.addItem({ price: 100 });
+  cart.applyDiscount(10);
+
+  // Act — execute
+  const total = cart.calculateTotal();
+
+  // Assert — verify
+  expect(total).toBe(90);
+});
+```
+
+### DAMP Over DRY
+
+Tests should be **Descriptive And Meaningful Phrases**. Each test reads independently:
+
+```javascript
+// ✅ DAMP — clear and independent
+it('should reject password shorter than 8 characters', () => {
+  const result = validatePassword('short');
+  expect(result.valid).toBe(false);
+  expect(result.error).toBe('Password must be at least 8 characters');
+});
+
+// ❌ Too DRY — requires reading shared setup
+it('should reject short password', () => {
+  expect(validate(shortPassword)).toBe(false);
+});
+```
+
+### Descriptive Test Names
+
+```javascript
+// ✅ Good — describes behavior
+'should return 404 when user is not found'
+'should increment quantity when adding existing product'
+'should send welcome email after registration'
+
+// ❌ Bad — vague
+'works correctly'
+'handles error'
+'test user'
+```
+
+### One Behavior Per Test
+
+```javascript
+// ✅ Good — focused
+it('should validate email format', () => { ... });
+it('should require email field', () => { ... });
+
+// ❌ Bad — testing multiple things
+it('should validate email', () => {
+  expect(validate('')).toBe(false);      // required
+  expect(validate('bad')).toBe(false);   // format
+  expect(validate('a@b.c')).toBe(true);  // valid
+});
+```
+
+---
+
+## Test Doubles Preference
+
+```
+1. Real implementations (best)
+2. In-memory fakes (test DB, fake filesystem)
+3. Stubs (canned responses)
+4. Mocks (verify interactions — use sparingly)
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| Testing internals | Breaks on refactor | Test inputs/outputs only |
+| Flaky tests | Erodes trust | Use deterministic data, isolate state |
+| Over-mocking | False confidence | Prefer real implementations |
+| Snapshot abuse | Large diffs ignored | Use for rare cases only |
+| Shared state | Tests affect each other | Reset state in beforeEach |
+
+---
+
+## Verification Checklist
+
+- [ ] All new behaviors have tests
+- [ ] Bug fixes have reproduction tests
+- [ ] Test names describe behavior
+- [ ] No skipped or disabled tests
+- [ ] Coverage maintained or improved
+- [ ] Full test suite passes

package/.claude/references/accessibility-checklist.md

@@ -0,0 +1,174 @@
+# Accessibility Checklist (WCAG 2.1 AA)
+
+> Ensure your application is usable by everyone.
+
+## Keyboard Navigation
+
+- [ ] All interactive elements focusable with Tab
+- [ ] Focus order is logical (follows visual order)
+- [ ] Focus indicator visible (never `outline: none`)
+- [ ] Skip link to main content
+- [ ] No keyboard traps
+- [ ] Custom components work with Enter/Space
+
+```jsx
+// ✅ Good: Custom button with keyboard support
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') handleClick();
+  }}
+>
+  Click me
+</div>
+
+// ✅ Better: Use native button
+<button onClick={handleClick}>Click me</button>
+```
+
+## Screen Readers
+
+### Semantic HTML
+- [ ] Use semantic elements (`<nav>`, `<main>`, `<article>`, etc.)
+- [ ] Headings in logical order (h1 → h2 → h3)
+- [ ] Lists use `<ul>`, `<ol>`, `<dl>`
+- [ ] Tables have `<th>` with scope
+
+### ARIA
+- [ ] Images have alt text (empty `alt=""` for decorative)
+- [ ] Form inputs have labels
+- [ ] Buttons have accessible names
+- [ ] Dynamic content announced (aria-live)
+- [ ] Modals trap focus and have aria-modal
+
+```jsx
+// ✅ Good: Accessible form
+<label htmlFor="email">Email</label>
+<input id="email" type="email" aria-describedby="email-hint" />
+<span id="email-hint">We'll never share your email</span>
+
+// ✅ Good: Accessible icon button
+<button aria-label="Close menu">
+  <CloseIcon aria-hidden="true" />
+</button>
+
+// ✅ Good: Live region for updates
+<div aria-live="polite" aria-atomic="true">
+  {notification}
+</div>
+```
+
+## Visual Design
+
+### Color
+- [ ] Color contrast ratio ≥ 4.5:1 (text)
+- [ ] Color contrast ratio ≥ 3:1 (large text, UI components)
+- [ ] Information not conveyed by color alone
+- [ ] Links distinguishable from text (underline or contrast)
+
+### Text
+- [ ] Text resizable to 200% without loss
+- [ ] Line height ≥ 1.5
+- [ ] No text in images (except logos)
+
+### Motion
+- [ ] Respect `prefers-reduced-motion`
+- [ ] No flashing content (> 3 flashes/second)
+- [ ] Animations can be paused
+
+```css
+/* Respect motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Forms
+
+- [ ] All inputs have visible labels
+- [ ] Required fields marked
+- [ ] Error messages associated with inputs
+- [ ] Autocomplete attributes used
+- [ ] Form validation accessible
+
+```jsx
+// ✅ Accessible error message
+<input
+  id="email"
+  aria-invalid={hasError}
+  aria-describedby={hasError ? 'email-error' : undefined}
+/>
+{hasError && (
+  <span id="email-error" role="alert">
+    Please enter a valid email address
+  </span>
+)}
+```
+
+## Interactive Components
+
+### Buttons & Links
+- [ ] Buttons for actions, links for navigation
+- [ ] Link text is descriptive (not "click here")
+- [ ] Disabled state communicated
+
+### Modals/Dialogs
+- [ ] Focus trapped inside modal
+- [ ] Close with Escape key
+- [ ] Focus returns on close
+- [ ] `role="dialog"` and `aria-modal="true"`
+
+### Menus & Dropdowns
+- [ ] Arrow key navigation
+- [ ] `role="menu"` and `role="menuitem"`
+- [ ] Current item indicated
+
+## Testing Tools
+
+```bash
+# Automated testing
+npx axe-cli https://example.com
+npx pa11y https://example.com
+
+# Browser extensions
+- axe DevTools (Chrome)
+- WAVE (Chrome/Firefox)
+- Accessibility Insights (Chrome)
+```
+
+### Manual Testing
+- [ ] Navigate with keyboard only
+- [ ] Test with screen reader (VoiceOver/NVDA)
+- [ ] Zoom to 200%
+- [ ] Use high contrast mode
+- [ ] Test with reduced motion
+
+## ARIA Roles Quick Reference
+
+| Role | Use For |
+|------|---------|
+| `button` | Clickable elements (prefer `<button>`) |
+| `link` | Navigation (prefer `<a>`) |
+| `dialog` | Modal windows |
+| `alert` | Important messages |
+| `status` | Status updates |
+| `navigation` | Nav sections (prefer `<nav>`) |
+| `main` | Main content (prefer `<main>`) |
+| `region` | Distinct sections with label |
+| `tablist`, `tab`, `tabpanel` | Tab interfaces |
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Missing alt text | Add descriptive alt or `alt=""` |
+| Low contrast | Increase color contrast |
+| Missing form labels | Add `<label>` elements |
+| Focus not visible | Don't remove outline, style it |
+| Mouse-only interactions | Add keyboard handlers |
+| Auto-playing media | Add controls, respect preferences |

package/.claude/references/performance-checklist.md

@@ -0,0 +1,150 @@
+# Performance Checklist
+
+> Quick reference for performance optimization.
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| **LCP** (Largest Contentful Paint) | < 2.5s | 2.5-4s | > 4s |
+| **INP** (Interaction to Next Paint) | < 200ms | 200-500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | < 0.1 | 0.1-0.25 | > 0.25 |
+
+## Frontend Performance
+
+### Critical Render Path
+- [ ] Minimize critical CSS (inline above-fold styles)
+- [ ] Defer non-critical JavaScript
+- [ ] Preload critical resources
+- [ ] Optimize font loading (font-display: swap)
+
+### Images
+- [ ] Use modern formats (WebP, AVIF)
+- [ ] Implement lazy loading
+- [ ] Serve responsive sizes (srcset)
+- [ ] Use CDN for static assets
+- [ ] Set explicit width/height (prevent CLS)
+
+### JavaScript
+- [ ] Code splitting (dynamic imports)
+- [ ] Tree shaking enabled
+- [ ] Bundle size monitored (< 200KB initial)
+- [ ] No unused dependencies
+
+### React Specific
+- [ ] Memoize expensive computations (useMemo)
+- [ ] Prevent unnecessary re-renders (React.memo)
+- [ ] Virtualize long lists (react-window)
+- [ ] Use Suspense for code splitting
+
+```javascript
+// ✅ Good: Memoized component
+const ExpensiveList = React.memo(({ items }) => {
+  return items.map(item => <Item key={item.id} {...item} />);
+});
+
+// ✅ Good: Memoized computation
+const sortedItems = useMemo(
+  () => items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+```
+
+## Backend Performance
+
+### Database
+- [ ] Indexes on queried columns
+- [ ] No N+1 queries
+- [ ] Pagination implemented
+- [ ] Connection pooling configured
+- [ ] Query timeouts set
+
+```javascript
+// ❌ N+1 Problem
+const users = await db.user.findMany();
+for (const user of users) {
+  user.orders = await db.order.findMany({ where: { userId: user.id } });
+}
+
+// ✅ Fixed: Include relation
+const users = await db.user.findMany({
+  include: { orders: true }
+});
+```
+
+### Caching
+- [ ] Cache frequently accessed data
+- [ ] Appropriate TTLs set
+- [ ] Cache invalidation strategy
+- [ ] CDN for static content
+
+```javascript
+// Cache pattern
+async function getUser(id) {
+  const cached = await redis.get(`user:${id}`);
+  if (cached) return JSON.parse(cached);
+  
+  const user = await db.user.findUnique({ where: { id } });
+  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
+  return user;
+}
+```
+
+### API
+- [ ] Response compression (gzip/brotli)
+- [ ] Pagination for lists
+- [ ] Field selection (select only needed)
+- [ ] Async operations for slow tasks
+
+```javascript
+// ✅ Good: Paginated API
+GET /api/users?page=1&limit=20&fields=id,name,email
+```
+
+## Measurement Commands
+
+```bash
+# Lighthouse (Chrome)
+npx lighthouse https://example.com --output=json
+
+# Bundle analysis
+npx webpack-bundle-analyzer stats.json
+
+# Check bundle size
+npx bundlephobia <package-name>
+
+# Database query analysis
+EXPLAIN ANALYZE SELECT * FROM users WHERE email = '...';
+
+# Redis latency
+redis-cli --latency
+
+# API response time
+curl -o /dev/null -s -w '%{time_total}\n' https://api.example.com/users
+```
+
+## Performance Budget
+
+| Resource | Budget |
+|----------|--------|
+| Initial JS | < 200KB |
+| Initial CSS | < 50KB |
+| Total page weight | < 1MB |
+| Time to Interactive | < 3s |
+| API response (p95) | < 200ms |
+
+## Monitoring
+
+- [ ] Real User Monitoring (RUM) enabled
+- [ ] Synthetic monitoring configured
+- [ ] Alerting on degradation
+- [ ] Performance tracked in CI
+
+```javascript
+// Example: Track Core Web Vitals
+import { onLCP, onINP, onCLS } from 'web-vitals';
+
+onLCP(metric => sendToAnalytics('LCP', metric.value));
+onINP(metric => sendToAnalytics('INP', metric.value));
+onCLS(metric => sendToAnalytics('CLS', metric.value));
+```