@champpaba/claude-agent-kit 1.0.0

package/template/.claude/contexts/patterns/testing.md

@@ -0,0 +1,413 @@
+# Testing Strategy & TDD Methodology
+
+**Red-Green-Refactor:** Write test → Watch it fail → Write code → Make it pass → Refactor
+
+---
+
+## Test-Driven Development (TDD)
+
+### Automatic TDD Classification
+
+**Orchestrator automatically determines if TDD is required based on task content.**
+
+You don't decide. Orchestrator decides. Your job is to **follow the `tdd_required` flag**.
+
+### When You Receive a Task
+
+**Check the metadata from Orchestrator:**
+```json
+{
+  "description": "Implement POST /api/auth/login",
+  "type": "critical",
+  "tdd_required": true,
+  "workflow": "red-green-refactor",
+  "reason": "API endpoint + authentication logic"
+}
+```
+
+### Classification Rules (Orchestrator Logic)
+
+✅ **TDD Required (`tdd_required: true`) for:**
+- API mutations (POST, PUT, PATCH, DELETE)
+- Business logic (calculations, transformations, validation)
+- External service integrations (payment, email, SMS, storage)
+- Data transformations (ETL, serialization, aggregations)
+- Security operations (authentication, authorization, encryption)
+- Complex UI logic (multi-step forms, state machines, accessibility)
+
+⚠️ **Test-Alongside OK (`tdd_required: false`) for:**
+- Simple GET endpoints (read-only)
+- Presentational UI components
+- Simple CRUD operations
+- Configuration files
+- Trivial utilities
+
+**Note:** For full classification logic, see `@.claude/contexts/patterns/task-classification.md`
+
+### TDD Workflow (Red-Green-Refactor)
+
+**Use when:** `tdd_required: true`
+
+```
+1. RED Phase - Write the test first
+   → Define expected behavior before implementation
+   → Run test → MUST FAIL (proves test works)
+   → Log: "tdd_red_phase"
+
+2. GREEN Phase - Write minimal code
+   → Just enough to make the test pass
+   → Run test → MUST PASS
+   → Log: "tdd_green_phase"
+
+3. REFACTOR Phase - Improve code quality
+   → Add logging for observability
+   → Add error handling
+   → Add documentation
+   → Run test → MUST STILL PASS
+   → Log: "tdd_refactor_phase"
+
+4. Repeat
+   → One test at a time
+```
+
+### Standard Workflow (Test-Alongside)
+
+**Use when:** `tdd_required: false`
+
+```
+1. Write implementation first
+2. Write tests to verify
+3. Run tests → PASS
+```
+
+---
+
+## Testing Layers
+
+### 1. Unit Tests
+
+**Purpose:** Test individual functions/modules in isolation
+
+**Framework:** Vitest (JS/TS) | Pytest (Python)
+
+#### TypeScript Example
+
+```typescript
+// __tests__/scoring.test.ts
+import { describe, it, expect, vi } from 'vitest'
+import { calculateDiscount } from '@/lib/pricing'
+import { logger } from '@/lib/logger'
+
+vi.mock('@/lib/logger')
+
+describe('calculateDiscount', () => {
+  it('applies 10% discount for members', () => {
+    const result = calculateDiscount(100, { isMember: true })
+    expect(result).toBe(90)
+
+    expect(logger.info).toHaveBeenCalledWith(
+      'discount_calculated',
+      expect.objectContaining({
+        originalPrice: 100,
+        discount: 10,
+        finalPrice: 90
+      })
+    )
+  })
+
+  it('no discount for non-members', () => {
+    const result = calculateDiscount(100, { isMember: false })
+    expect(result).toBe(100)
+  })
+
+  it('throws on invalid input', () => {
+    expect(() => calculateDiscount(-1, {})).toThrow('Price must be positive')
+  })
+})
+```
+
+#### Python Example
+
+```python
+# tests/test_pricing.py
+import pytest
+from app.lib.pricing import calculate_discount
+from unittest.mock import patch
+
+@pytest.mark.parametrize("price,is_member,expected", [
+    (100, True, 90),   # Member gets 10% discount
+    (100, False, 100), # Non-member no discount
+    (50, True, 45),    # Member discount on lower price
+])
+def test_calculate_discount(price, is_member, expected):
+    result = calculate_discount(price, is_member=is_member)
+    assert result == expected
+
+def test_calculate_discount_invalid_price():
+    with pytest.raises(ValueError, match="Price must be positive"):
+        calculate_discount(-1, is_member=True)
+```
+
+**When to use:**
+- Pure functions
+- Business logic
+- Data transformations
+- Utility functions
+
+---
+
+### 2. Integration Tests
+
+**Purpose:** Test multiple components working together
+
+#### API Route Test (Next.js)
+
+```typescript
+// __tests__/api/items.test.ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { POST } from '@/app/api/items/route'
+
+describe('POST /api/items', () => {
+  it('creates item and returns 201', async () => {
+    const request = new Request('http://localhost/api/items', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        name: 'Test Item',
+        price: 99.99
+      })
+    })
+
+    const response = await POST(request)
+    const data = await response.json()
+
+    expect(response.status).toBe(201)
+    expect(data.id).toBeDefined()
+    expect(data.name).toBe('Test Item')
+  })
+
+  it('returns 400 on validation error', async () => {
+    const request = new Request('http://localhost/api/items', {
+      method: 'POST',
+      body: JSON.stringify({ name: '' }) // Missing price
+    })
+
+    const response = await POST(request)
+    expect(response.status).toBe(400)
+  })
+})
+```
+
+#### API Test (FastAPI)
+
+```python
+# tests/test_api.py
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_create_item(client: AsyncClient):
+    response = await client.post("/api/items", json={
+        "name": "Test Item",
+        "price": 99.99
+    })
+
+    assert response.status_code == 201
+    data = response.json()
+    assert data["id"] is not None
+    assert data["name"] == "Test Item"
+
+@pytest.mark.asyncio
+async def test_create_item_validation_error(client: AsyncClient):
+    response = await client.post("/api/items", json={
+        "name": ""  # Invalid
+    })
+
+    assert response.status_code == 422  # Validation error
+```
+
+**When to use:**
+- API routes
+- Database operations
+- External service integrations
+- Multi-step workflows
+
+---
+
+### 3. E2E Tests (Playwright)
+
+**Purpose:** Test complete user flows in real browser
+
+```typescript
+// e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test'
+
+test('user completes checkout flow', async ({ page }) => {
+  // Add item to cart
+  await page.goto('/products')
+  await page.click('button:text("Add to Cart")')
+
+  // Go to cart
+  await page.click('[href="/cart"]')
+  await expect(page.locator('h1')).toContainText('Shopping Cart')
+
+  // Proceed to checkout
+  await page.click('button:text("Checkout")')
+
+  // Fill shipping info
+  await page.fill('#name', 'John Doe')
+  await page.fill('#email', 'john@example.com')
+  await page.fill('#address', '123 Main St')
+  await page.click('button:text("Continue")')
+
+  // Payment
+  await page.fill('#cardNumber', '4242424242424242')
+  await page.fill('#expiry', '12/25')
+  await page.fill('#cvc', '123')
+  await page.click('button:text("Pay Now")')
+
+  // Verify order confirmation
+  await expect(page.locator('h1')).toContainText('Order Confirmed')
+  await expect(page.locator('[data-testid="order-number"]')).toBeVisible()
+})
+
+test('shows validation errors on empty form', async ({ page }) => {
+  await page.goto('/checkout')
+  await page.click('button:text("Continue")')
+
+  await expect(page.locator('text=Name is required')).toBeVisible()
+  await expect(page.locator('text=Email is required')).toBeVisible()
+})
+```
+
+**When to use:**
+- Complete user journeys
+- Cross-browser compatibility
+- UI/UX validation
+- Critical paths
+
+---
+
+## Testing Best Practices
+
+### DO:
+- ✅ Test behavior, not implementation
+- ✅ Write tests first for critical code (TDD)
+- ✅ Mock external dependencies
+- ✅ Use descriptive test names
+- ✅ Test edge cases and error scenarios
+- ✅ Keep tests fast (< 1s per test)
+- ✅ Verify logging in tests
+
+### DON'T:
+- ❌ Test framework internals (React hooks, etc.)
+- ❌ Test trivial code (getters/setters)
+- ❌ Write flaky tests (time-dependent)
+- ❌ Skip error case tests
+- ❌ Commit failing tests
+
+---
+
+## Test Organization
+
+### TypeScript/JavaScript
+```
+project/
+├── __tests__/
+│   ├── unit/
+│   │   ├── lib/
+│   │   │   ├── pricing.test.ts
+│   │   │   └── validation.test.ts
+│   │   └── utils/
+│   │       └── formatters.test.ts
+│   ├── integration/
+│   │   ├── api/
+│   │   │   ├── items.test.ts
+│   │   │   └── users.test.ts
+│   │   └── stores/
+│   │       └── app-store.test.ts
+│   └── e2e/
+│       ├── checkout.spec.ts
+│       └── auth.spec.ts
+├── vitest.config.ts
+└── playwright.config.ts
+```
+
+### Python
+```
+project/
+├── tests/
+│   ├── unit/
+│   │   ├── test_pricing.py
+│   │   └── test_validation.py
+│   ├── integration/
+│   │   ├── test_api.py
+│   │   └── test_db.py
+│   └── conftest.py (fixtures)
+└── pytest.ini
+```
+
+---
+
+## Coverage Guidelines
+
+| Type | Target Coverage |
+|------|----------------|
+| Business Logic | 95%+ |
+| API Routes | 90%+ |
+| Utilities | 85%+ |
+| UI Components | 85%+ |
+
+---
+
+## Quick Reference
+
+### Vitest Commands
+```bash
+pnpm test                    # Run all tests
+pnpm test -- --run          # Run without watch mode
+pnpm test -- path/to/test   # Run specific test
+pnpm test -- --coverage     # Run with coverage
+```
+
+### Pytest Commands
+```bash
+pytest                      # Run all tests
+pytest -v                   # Verbose output
+pytest tests/unit/          # Run specific directory
+pytest --cov=app           # Run with coverage
+pytest -k "test_create"    # Run tests matching pattern
+```
+
+### Playwright Commands
+```bash
+pnpm test:e2e              # Run E2E tests
+pnpm test:e2e --ui         # Run with UI mode
+pnpm test:e2e --debug      # Run with debugger
+```
+
+---
+
+---
+
+## Trust the Classification
+
+**Orchestrator uses comprehensive pattern matching:**
+- API endpoints (HTTP methods, routes)
+- Business logic (calculations, validation)
+- External integrations (Stripe, SendGrid, Twilio, S3, etc.)
+- Data transformations (ETL, serialization)
+- Security operations (auth, encryption)
+
+**Your responsibility:**
+1. Check `tdd_required` flag in task metadata
+2. If `true` → Use Red-Green-Refactor workflow
+3. If `false` → Use Test-Alongside workflow
+4. Log each phase for observability
+
+**Don't override the classification unless you find a clear error.**
+If classification seems wrong, report to user for pattern refinement.
+
+---
+
+**💡 Remember:** Tests are documentation. Write tests that explain what your code does!

package/template/.claude/contexts/patterns/ui-component-consistency.md

@@ -0,0 +1,304 @@
+# UI Component Visual Consistency
+
+**Core Principle:** Before creating ANY UI component, extract and reuse design tokens from existing similar components to ensure 100% visual consistency.
+
+---
+
+## 🎯 The Problem
+
+**Symptom:** New components look "slightly different" from existing ones.
+
+**Common Issues:**
+- Icon opacity: `opacity-50` vs `text-foreground/70`
+- Spacing: `px-4` vs `px-3` (inconsistent padding)
+- Colors: `text-gray-500` vs `text-foreground/70` (hardcoded vs theme-aware)
+- Border radius: `rounded` vs `rounded-md` (inconsistent corners)
+
+**Root Cause:**
+- ❌ Agent creates component without checking existing ones
+- ❌ No visual comparison with reference components
+- ❌ Missing design token extraction step
+- ❌ No cross-component validation
+
+---
+
+## 📋 Mandatory Workflow
+
+**ALWAYS follow these 6 steps before creating UI components:**
+
+### Step 1: Search for Similar Components
+
+```bash
+# Find components with similar functionality
+Glob: "**/*{Field,Input,Select,Dropdown}*.{tsx,jsx,vue}"
+Grep: "ChevronDown"
+Grep: "dropdown.*icon"
+```
+
+**Questions to ask:**
+- Is there a component with similar user interaction?
+- What component has the same visual element (icon, border, shadow)?
+- Which component shares the same state behavior (focus, error, disabled)?
+
+---
+
+### Step 2: Extract Design Tokens
+
+**Read reference component and document these properties:**
+
+#### Icon Properties
+```typescript
+const ICON_TOKENS = {
+  component: 'ChevronDown',                    // Which icon?
+  size: 'h-4 w-4',                             // Dimensions
+  color: 'text-foreground/70',                 // ⚠️ NOT opacity-50
+  position: 'right-3 top-1/2 -translate-y-1/2', // Absolute positioning
+  pointer: 'pointer-events-none',              // Interaction
+}
+```
+
+#### Input/Select Properties
+```typescript
+const INPUT_TOKENS = {
+  padding: 'pl-3 pr-10 py-2',                  // pr-10 = space for icon
+  border: 'border-input',
+  borderError: 'border-destructive',
+  borderRadius: 'rounded-md',
+  background: 'bg-background',
+  text: 'text-foreground',
+  placeholder: 'placeholder:text-muted-foreground',
+
+  // States
+  focus: 'focus:ring-2 focus:ring-primary focus:ring-offset-2',
+  disabled: 'disabled:opacity-50 disabled:cursor-not-allowed',
+  transition: 'transition-colors',
+}
+```
+
+#### Layout Structure
+```typescript
+const LAYOUT_TOKENS = {
+  wrapper: 'relative',          // Required for absolute icon positioning
+  input: 'appearance-none',     // Hide native select arrow
+  icon: 'absolute',             // Icon positioning
+}
+```
+
+---
+
+### Step 3: Apply Tokens to New Component
+
+**Example: Creating ComboboxField**
+
+```typescript
+// ❌ WRONG - Custom values without reference
+<div>
+  <select className="px-4 py-3">...</select>
+  <ChevronDown className="opacity-50 h-5 w-5" />
+</div>
+
+// ✅ CORRECT - Extracted tokens from FormField
+<div className="relative">
+  <Combobox className="appearance-none pl-3 pr-10 py-2 rounded-md border border-input">
+    ...
+  </Combobox>
+  <ChevronDown className="absolute right-3 top-1/2 -translate-y-1/2 h-4 w-4 text-foreground/70 pointer-events-none" />
+</div>
+```
+
+**Key Rules:**
+1. Use **exact same classes** for identical elements
+2. Prefer **theme tokens** (`text-foreground/70`) over hardcoded colors (`text-gray-500`)
+3. Match **spacing patterns** exactly (`pl-3 pr-10 py-2`)
+4. Reuse **state classes** (focus, hover, disabled)
+
+---
+
+### Step 4: Visual Comparison Test
+
+**Use Browser DevTools to compare pixel-by-pixel:**
+
+1. Open page with both components side-by-side
+2. Press F12 → Inspect Element
+3. Compare CSS computed values:
+
+```css
+/* Icon - Must match exactly */
+width: 16px                    /* h-4 */
+height: 16px                   /* w-4 */
+right: 12px                    /* right-3 (0.75rem) */
+top: 50%                       /* top-1/2 */
+transform: translateY(-50%)    /* -translate-y-1/2 */
+opacity: 0.7                   /* text-foreground/70 */
+
+/* Input - Must match exactly */
+padding-left: 12px             /* pl-3 */
+padding-right: 40px            /* pr-10 */
+padding-top: 8px               /* py-2 */
+padding-bottom: 8px            /* py-2 */
+border-radius: 6px             /* rounded-md */
+```
+
+4. **If values differ → STOP and fix immediately**
+
+---
+
+### Step 5: State Consistency Check
+
+**Test every interactive state:**
+
+| State | Expected Behavior |
+|-------|------------------|
+| Normal | Icon visible, clear contrast |
+| Hover | Cursor changes if interactive |
+| Focus | Ring appears (same color/offset as reference) |
+| Error | Border becomes `border-destructive` |
+| Disabled | `opacity-50` + `cursor-not-allowed` |
+
+**Compare each state with reference component → Must be identical**
+
+---
+
+### Step 6: Document Design Reference
+
+**Add JSDoc comment with design lineage:**
+
+```typescript
+/**
+ * ComboboxField - Searchable dropdown field
+ *
+ * VISUAL CONSISTENCY:
+ * - Extracted design tokens from: components/ui/form-field.tsx
+ * - Icon: ChevronDown (h-4 w-4, text-foreground/70, right-3)
+ * - Matches FormField: focus ring, error states, spacing
+ * - States tested: normal, focus, error, disabled
+ *
+ * @see components/ui/form-field.tsx - Reference component
+ */
+export function ComboboxField({ ... }) {
+  // Implementation
+}
+```
+
+---
+
+## 🚨 Red Flags (Stop Immediately)
+
+### ❌ Hardcoded Colors
+```typescript
+// WRONG
+className="text-gray-500"      // Not theme-aware
+className="bg-blue-600"        // Hardcoded color
+
+// CORRECT
+className="text-foreground/70" // Theme token
+className="bg-primary"         // Theme token
+```
+
+### ❌ Non-Standard Opacity/Size
+```typescript
+// WRONG
+className="opacity-50"         // Too light for foreground
+className="h-5 w-5"            // Larger than standard
+
+// CORRECT
+className="text-foreground/70" // Standard opacity via color
+className="h-4 w-4"            // Standard icon size
+```
+
+### ❌ Inconsistent Spacing
+```typescript
+// WRONG
+className="px-4 py-3"          // Different from FormField
+
+// CORRECT
+className="pl-3 pr-10 py-2"    // Matches FormField exactly
+```
+
+### ❌ Visual Discrepancy
+- **If it "looks different" → STOP**
+- Open browser side-by-side
+- Compare with DevTools
+- Fix before proceeding
+
+---
+
+## 📊 Common Design Tokens Reference
+
+### Dropdown Components
+```typescript
+// Icon
+size: 'h-4 w-4'
+color: 'text-foreground/70'                    // ⚠️ NOT opacity-50
+position: 'right-3 top-1/2 -translate-y-1/2'
+
+// Container
+padding: 'pl-3 pr-10 py-2'                     // pr-10 for icon space
+border: 'rounded-md border border-input'
+focus: 'focus:ring-2 focus:ring-primary focus:ring-offset-2'
+```
+
+### Input Components
+```typescript
+padding: 'px-3 py-2'
+border: 'rounded-md border border-input'
+background: 'bg-background'
+text: 'text-foreground'
+placeholder: 'placeholder:text-muted-foreground'
+```
+
+### Button Components
+```typescript
+height: 'h-10'
+padding: 'px-4 py-2'
+borderRadius: 'rounded-md'
+fontWeight: 'font-medium'
+transition: 'transition-colors'
+```
+
+---
+
+## ✅ Quick Checklist
+
+**Before committing any UI component:**
+
+- [ ] Found similar reference component in codebase
+- [ ] Extracted all design tokens (icon, spacing, colors, states)
+- [ ] Applied tokens exactly (no guessing)
+- [ ] Tested visual appearance in browser
+- [ ] Compared computed CSS values with DevTools
+- [ ] Tested all states (normal, hover, focus, error, disabled)
+- [ ] Documented reference component in JSDoc
+- [ ] Visually indistinguishable from reference component
+
+---
+
+## 🎯 Summary
+
+**One-Sentence Rule:**
+> "Before creating a UI component → Find the most similar existing component → Extract its design tokens → Apply them exactly → Test that they're 100% identical"
+
+**Prevention Strategy:**
+1. ✅ Search for reference component first
+2. ✅ Extract design tokens systematically
+3. ✅ Apply tokens without modification
+4. ✅ Validate visual consistency in browser
+5. ✅ Document design lineage
+
+**Anti-Pattern:**
+1. ❌ Create component without checking existing ones
+2. ❌ Use custom values instead of extracted tokens
+3. ❌ Skip visual comparison test
+4. ❌ Commit without cross-component validation
+
+---
+
+## 📚 Related Patterns
+
+- `@/.claude/contexts/patterns/frontend-component-strategy.md` - Component reuse strategy
+- `@/.claude/contexts/design/index.md` - Design system foundation
+- `@/.claude/contexts/design/box-thinking.md` - Layout analysis
+
+---
+
+**Remember:** Visual consistency is not optional. Users notice when components "feel different" even if they can't articulate why.