The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add Cursor, Codex, and OpenCode harnesses — maximize every AI coding tool
Affaan Mustafad70bab85e33a
diff --git a/.agents/skills/api-design/SKILL.md b/.agents/skills/api-design/SKILL.mdnew file mode 100644index 000000000..a45aca06d--- /dev/null+++ b/.agents/skills/api-design/SKILL.md@@ -0,0 +1,523 @@+---+name: api-design+description: REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.+origin: ECC+---++# API Design Patterns++Conventions and best practices for designing consistent, developer-friendly REST APIs.++## When to Activate++- Designing new API endpoints+- Reviewing existing API contracts+- Adding pagination, filtering, or sorting+- Implementing error handling for APIs+- Planning API versioning strategy+- Building public or partner-facing APIs++## Resource Design++### URL Structure++```+# Resources are nouns, plural, lowercase, kebab-case+GET /api/v1/users+GET /api/v1/users/:id+POST /api/v1/users+PUT /api/v1/users/:id+PATCH /api/v1/users/:id+DELETE /api/v1/users/:id++# Sub-resources for relationships+GET /api/v1/users/:id/orders+POST /api/v1/users/:id/orders++# Actions that don't map to CRUD (use verbs sparingly)+POST /api/v1/orders/:id/cancel+POST /api/v1/auth/login+POST /api/v1/auth/refresh+```++### Naming Rules++```+# GOOD+/api/v1/team-members # kebab-case for multi-word resources+/api/v1/orders?status=active # query params for filtering+/api/v1/users/123/orders # nested resources for ownership++# BAD+/api/v1/getUsers # verb in URL+/api/v1/user # singular (use plural)+/api/v1/team_members # snake_case in URLs+/api/v1/users/123/getOrders # verb in nested resource+```++## HTTP Methods and Status Codes++### Method Semantics++| Method | Idempotent | Safe | Use For |+|--------|-----------|------|---------|+| GET | Yes | Yes | Retrieve resources |+| POST | No | No | Create resources, trigger actions |+| PUT | Yes | No | Full replacement of a resource |+| PATCH | No* | No | Partial update of a resource |+| DELETE | Yes | No | Remove a resource |++*PATCH can be made idempotent with proper implementation++### Status Code Reference++```+# Success+200 OK — GET, PUT, PATCH (with response body)+201 Created — POST (include Location header)+204 No Content — DELETE, PUT (no response body)++# Client Errors+400 Bad Request — Validation failure, malformed JSON+401 Unauthorized — Missing or invalid authentication+403 Forbidden — Authenticated but not authorized+404 Not Found — Resource doesn't exist+409 Conflict — Duplicate entry, state conflict+422 Unprocessable Entity — Semantically invalid (valid JSON, bad data)+429 Too Many Requests — Rate limit exceeded++# Server Errors+500 Internal Server Error — Unexpected failure (never expose details)+502 Bad Gateway — Upstream service failed+503 Service Unavailable — Temporary overload, include Retry-After+```++### Common Mistakes++```+# BAD: 200 for everything+{ "status": 200, "success": false, "error": "Not found" }++# GOOD: Use HTTP status codes semantically+HTTP/1.1 404 Not Found+{ "error": { "code": "not_found", "message": "User not found" } }++# BAD: 500 for validation errors+# GOOD: 400 or 422 with field-level details++# BAD: 200 for created resources+# GOOD: 201 with Location header+HTTP/1.1 201 Created+Location: /api/v1/users/abc-123+```++## Response Format++### Success Response++```json+{+ "data": {+ "id": "abc-123",+ "email": "[email protected]",+ "name": "Alice",+ "created_at": "2025-01-15T10:30:00Z"+ }+}+```++### Collection Response (with Pagination)++```json+{+ "data": [+ { "id": "abc-123", "name": "Alice" },+ { "id": "def-456", "name": "Bob" }+ ],+ "meta": {+ "total": 142,+ "page": 1,+ "per_page": 20,+ "total_pages": 8+ },+ "links": {+ "self": "/api/v1/users?page=1&per_page=20",+ "next": "/api/v1/users?page=2&per_page=20",+ "last": "/api/v1/users?page=8&per_page=20"+ }+}+```++### Error Response++```json+{+ "error": {+ "code": "validation_error",+ "message": "Request validation failed",+ "details": [+ {+ "field": "email",+ "message": "Must be a valid email address",+ "code": "invalid_format"+ },+ {+ "field": "age",+ "message": "Must be between 0 and 150",+ "code": "out_of_range"+ }+ ]+ }+}+```++### Response Envelope Variants++```typescript+// Option A: Envelope with data wrapper (recommended for public APIs)+interface ApiResponse<T> {+ data: T;+ meta?: PaginationMeta;+ links?: PaginationLinks;+}++interface ApiError {+ error: {+ code: string;+ message: string;+ details?: FieldError[];+ };+}++// Option B: Flat response (simpler, common for internal APIs)+// Success: just return the resource directly+// Error: return error object+// Distinguish by HTTP status code+```++## Pagination++### Offset-Based (Simple)++```+GET /api/v1/users?page=2&per_page=20++# Implementation+SELECT * FROM users+ORDER BY created_at DESC+LIMIT 20 OFFSET 20;+```++**Pros:** Easy to implement, supports "jump to page N"+**Cons:** Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts++### Cursor-Based (Scalable)++```+GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20++# Implementation+SELECT * FROM users+WHERE id > :cursor_id+ORDER BY id ASC+LIMIT 21; -- fetch one extra to determine has_next+```++```json+{+ "data": [...],+ "meta": {+ "has_next": true,+ "next_cursor": "eyJpZCI6MTQzfQ"+ }+}+```++**Pros:** Consistent performance regardless of position, stable with concurrent inserts+**Cons:** Cannot jump to arbitrary page, cursor is opaque++### When to Use Which++| Use Case | Pagination Type |+|----------|----------------|+| Admin dashboards, small datasets (<10K) | Offset |+| Infinite scroll, feeds, large datasets | Cursor |+| Public APIs | Cursor (default) with offset (optional) |+| Search results | Offset (users expect page numbers) |++## Filtering, Sorting, and Search++### Filtering++```+# Simple equality+GET /api/v1/orders?status=active&customer_id=abc-123++# Comparison operators (use bracket notation)+GET /api/v1/products?price[gte]=10&price[lte]=100+GET /api/v1/orders?created_at[after]=2025-01-01++# Multiple values (comma-separated)+GET /api/v1/products?category=electronics,clothing++# Nested fields (dot notation)+GET /api/v1/orders?customer.country=US+```++### Sorting++```+# Single field (prefix - for descending)+GET /api/v1/products?sort=-created_at++# Multiple fields (comma-separated)+GET /api/v1/products?sort=-featured,price,-created_at+```++### Full-Text Search++```+# Search query parameter+GET /api/v1/products?q=wireless+headphones++# Field-specific search+GET /api/v1/users?email=alice+```++### Sparse Fieldsets++```+# Return only specified fields (reduces payload)+GET /api/v1/users?fields=id,name,email+GET /api/v1/orders?fields=id,total,status&include=customer.name+```++## Authentication and Authorization++### Token-Based Auth++```+# Bearer token in Authorization header+GET /api/v1/users+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...++# API key (for server-to-server)+GET /api/v1/data+X-API-Key: sk_live_abc123+```++### Authorization Patterns++```typescript+// Resource-level: check ownership+app.get("/api/v1/orders/:id", async (req, res) => {+ const order = await Order.findById(req.params.id);+ if (!order) return res.status(404).json({ error: { code: "not_found" } });+ if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });+ return res.json({ data: order });+});++// Role-based: check permissions+app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {+ await User.delete(req.params.id);+ return res.status(204).send();+});+```++## Rate Limiting++### Headers++```+HTTP/1.1 200 OK+X-RateLimit-Limit: 100+X-RateLimit-Remaining: 95+X-RateLimit-Reset: 1640000000++# When exceeded+HTTP/1.1 429 Too Many Requests+Retry-After: 60+{+ "error": {+ "code": "rate_limit_exceeded",+ "message": "Rate limit exceeded. Try again in 60 seconds."+ }+}+```++### Rate Limit Tiers++| Tier | Limit | Window | Use Case |+|------|-------|--------|----------|+| Anonymous | 30/min | Per IP | Public endpoints |+| Authenticated | 100/min | Per user | Standard API access |+| Premium | 1000/min | Per API key | Paid API plans |+| Internal | 10000/min | Per service | Service-to-service |++## Versioning++### URL Path Versioning (Recommended)++```+/api/v1/users+/api/v2/users+```++**Pros:** Explicit, easy to route, cacheable+**Cons:** URL changes between versions++### Header Versioning++```+GET /api/users+Accept: application/vnd.myapp.v2+json+```++**Pros:** Clean URLs+**Cons:** Harder to test, easy to forget++### Versioning Strategy++```+1. Start with /api/v1/ — don't version until you need to+2. Maintain at most 2 active versions (current + previous)+3. Deprecation timeline:+ - Announce deprecation (6 months notice for public APIs)+ - Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT+ - Return 410 Gone after sunset date+4. Non-breaking changes don't need a new version:+ - Adding new fields to responses+ - Adding new optional query parameters+ - Adding new endpoints+5. Breaking changes require a new version:+ - Removing or renaming fields+ - Changing field types+ - Changing URL structure+ - Changing authentication method+```++## Implementation Patterns++### TypeScript (Next.js API Route)++```typescript+import { z } from "zod";+import { NextRequest, NextResponse } from "next/server";++const createUserSchema = z.object({+ email: z.string().email(),+ name: z.string().min(1).max(100),+});++export async function POST(req: NextRequest) {+ const body = await req.json();+ const parsed = createUserSchema.safeParse(body);++ if (!parsed.success) {+ return NextResponse.json({+ error: {+ code: "validation_error",+ message: "Request validation failed",+ details: parsed.error.issues.map(i => ({+ field: i.path.join("."),+ message: i.message,+ code: i.code,+ })),+ },+ }, { status: 422 });+ }++ const user = await createUser(parsed.data);++ return NextResponse.json(+ { data: user },+ {+ status: 201,+ headers: { Location: `/api/v1/users/${user.id}` },+ },+ );+}+```++### Python (Django REST Framework)++```python+from rest_framework import serializers, viewsets, status+from rest_framework.response import Response++class CreateUserSerializer(serializers.Serializer):+ email = serializers.EmailField()+ name = serializers.CharField(max_length=100)++class UserSerializer(serializers.ModelSerializer):+ class Meta:+ model = User+ fields = ["id", "email", "name", "created_at"]++class UserViewSet(viewsets.ModelViewSet):+ serializer_class = UserSerializer+ permission_classes = [IsAuthenticated]++ def get_serializer_class(self):+ if self.action == "create":+ return CreateUserSerializer+ return UserSerializer++ def create(self, request):+ serializer = CreateUserSerializer(data=request.data)+ serializer.is_valid(raise_exception=True)+ user = UserService.create(**serializer.validated_data)+ return Response(+ {"data": UserSerializer(user).data},+ status=status.HTTP_201_CREATED,+ headers={"Location": f"/api/v1/users/{user.id}"},+ )+```++### Go (net/http)++```go+func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {+ var req CreateUserRequest+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {+ writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")+ return+ }++ if err := req.Validate(); err != nil {+ writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())+ return+ }++ user, err := h.service.Create(r.Context(), req)+ if err != nil {+ switch {+ case errors.Is(err, domain.ErrEmailTaken):+ writeError(w, http.StatusConflict, "email_taken", "Email already registered")+ default:+ writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")+ }+ return+ }++ w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))+ writeJSON(w, http.StatusCreated, map[string]any{"data": user})+}+```++## API Design Checklist++Before shipping a new endpoint:++- [ ] Resource URL follows naming conventions (plural, kebab-case, no verbs)+- [ ] Correct HTTP method used (GET for reads, POST for creates, etc.)+- [ ] Appropriate status codes returned (not 200 for everything)+- [ ] Input validated with schema (Zod, Pydantic, Bean Validation)+- [ ] Error responses follow standard format with codes and messages+- [ ] Pagination implemented for list endpoints (cursor or offset)+- [ ] Authentication required (or explicitly marked as public)+- [ ] Authorization checked (user can only access their own resources)+- [ ] Rate limiting configured+- [ ] Response does not leak internal details (stack traces, SQL errors)+- [ ] Consistent naming with existing endpoints (camelCase vs snake_case)+- [ ] Documented (OpenAPI/Swagger spec updated)diff --git a/.agents/skills/api-design/agents/openai.yaml b/.agents/skills/api-design/agents/openai.yamlnew file mode 100644index 000000000..b83fe25f3--- /dev/null+++ b/.agents/skills/api-design/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "API Design"+ short_description: "REST API design patterns and best practices"+ brand_color: "#F97316"+ default_prompt: "Design REST API: resources, status codes, pagination"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/backend-patterns/SKILL.md b/.agents/skills/backend-patterns/SKILL.mdnew file mode 100644index 000000000..42c0cbee9--- /dev/null+++ b/.agents/skills/backend-patterns/SKILL.md@@ -0,0 +1,598 @@+---+name: backend-patterns+description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.+origin: ECC+---++# Backend Development Patterns++Backend architecture patterns and best practices for scalable server-side applications.++## When to Activate++- Designing REST or GraphQL API endpoints+- Implementing repository, service, or controller layers+- Optimizing database queries (N+1, indexing, connection pooling)+- Adding caching (Redis, in-memory, HTTP cache headers)+- Setting up background jobs or async processing+- Structuring error handling and validation for APIs+- Building middleware (auth, logging, rate limiting)++## API Design Patterns++### RESTful API Structure++```typescript+// ✅ Resource-based URLs+GET /api/markets # List resources+GET /api/markets/:id # Get single resource+POST /api/markets # Create resource+PUT /api/markets/:id # Replace resource+PATCH /api/markets/:id # Update resource+DELETE /api/markets/:id # Delete resource++// ✅ Query parameters for filtering, sorting, pagination+GET /api/markets?status=active&sort=volume&limit=20&offset=0+```++### Repository Pattern++```typescript+// Abstract data access logic+interface MarketRepository {+ findAll(filters?: MarketFilters): Promise<Market[]>+ findById(id: string): Promise<Market | null>+ create(data: CreateMarketDto): Promise<Market>+ update(id: string, data: UpdateMarketDto): Promise<Market>+ delete(id: string): Promise<void>+}++class SupabaseMarketRepository implements MarketRepository {+ async findAll(filters?: MarketFilters): Promise<Market[]> {+ let query = supabase.from('markets').select('*')++ if (filters?.status) {+ query = query.eq('status', filters.status)+ }++ if (filters?.limit) {+ query = query.limit(filters.limit)+ }++ const { data, error } = await query++ if (error) throw new Error(error.message)+ return data+ }++ // Other methods...+}+```++### Service Layer Pattern++```typescript+// Business logic separated from data access+class MarketService {+ constructor(private marketRepo: MarketRepository) {}++ async searchMarkets(query: string, limit: number = 10): Promise<Market[]> {+ // Business logic+ const embedding = await generateEmbedding(query)+ const results = await this.vectorSearch(embedding, limit)++ // Fetch full data+ const markets = await this.marketRepo.findByIds(results.map(r => r.id))++ // Sort by similarity+ return markets.sort((a, b) => {+ const scoreA = results.find(r => r.id === a.id)?.score || 0+ const scoreB = results.find(r => r.id === b.id)?.score || 0+ return scoreA - scoreB+ })+ }++ private async vectorSearch(embedding: number[], limit: number) {+ // Vector search implementation+ }+}+```++### Middleware Pattern++```typescript+// Request/response processing pipeline+export function withAuth(handler: NextApiHandler): NextApiHandler {+ return async (req, res) => {+ const token = req.headers.authorization?.replace('Bearer ', '')++ if (!token) {+ return res.status(401).json({ error: 'Unauthorized' })+ }++ try {+ const user = await verifyToken(token)+ req.user = user+ return handler(req, res)+ } catch (error) {+ return res.status(401).json({ error: 'Invalid token' })+ }+ }+}++// Usage+export default withAuth(async (req, res) => {+ // Handler has access to req.user+})+```++## Database Patterns++### Query Optimization++```typescript+// ✅ GOOD: Select only needed columns+const { data } = await supabase+ .from('markets')+ .select('id, name, status, volume')+ .eq('status', 'active')+ .order('volume', { ascending: false })+ .limit(10)++// ❌ BAD: Select everything+const { data } = await supabase+ .from('markets')+ .select('*')+```++### N+1 Query Prevention++```typescript+// ❌ BAD: N+1 query problem+const markets = await getMarkets()+for (const market of markets) {+ market.creator = await getUser(market.creator_id) // N queries+}++// ✅ GOOD: Batch fetch+const markets = await getMarkets()+const creatorIds = markets.map(m => m.creator_id)+const creators = await getUsers(creatorIds) // 1 query+const creatorMap = new Map(creators.map(c => [c.id, c]))++markets.forEach(market => {+ market.creator = creatorMap.get(market.creator_id)+})+```++### Transaction Pattern++```typescript+async function createMarketWithPosition(+ marketData: CreateMarketDto,+ positionData: CreatePositionDto+) {+ // Use Supabase transaction+ const { data, error } = await supabase.rpc('create_market_with_position', {+ market_data: marketData,+ position_data: positionData+ })++ if (error) throw new Error('Transaction failed')+ return data+}++// SQL function in Supabase+CREATE OR REPLACE FUNCTION create_market_with_position(+ market_data jsonb,+ position_data jsonb+)+RETURNS jsonb+LANGUAGE plpgsql+AS $$+BEGIN+ -- Start transaction automatically+ INSERT INTO markets VALUES (market_data);+ INSERT INTO positions VALUES (position_data);+ RETURN jsonb_build_object('success', true);+EXCEPTION+ WHEN OTHERS THEN+ -- Rollback happens automatically+ RETURN jsonb_build_object('success', false, 'error', SQLERRM);+END;+$$;+```++## Caching Strategies++### Redis Caching Layer++```typescript+class CachedMarketRepository implements MarketRepository {+ constructor(+ private baseRepo: MarketRepository,+ private redis: RedisClient+ ) {}++ async findById(id: string): Promise<Market | null> {+ // Check cache first+ const cached = await this.redis.get(`market:${id}`)++ if (cached) {+ return JSON.parse(cached)+ }++ // Cache miss - fetch from database+ const market = await this.baseRepo.findById(id)++ if (market) {+ // Cache for 5 minutes+ await this.redis.setex(`market:${id}`, 300, JSON.stringify(market))+ }++ return market+ }++ async invalidateCache(id: string): Promise<void> {+ await this.redis.del(`market:${id}`)+ }+}+```++### Cache-Aside Pattern++```typescript+async function getMarketWithCache(id: string): Promise<Market> {+ const cacheKey = `market:${id}`++ // Try cache+ const cached = await redis.get(cacheKey)+ if (cached) return JSON.parse(cached)++ // Cache miss - fetch from DB+ const market = await db.markets.findUnique({ where: { id } })++ if (!market) throw new Error('Market not found')++ // Update cache+ await redis.setex(cacheKey, 300, JSON.stringify(market))++ return market+}+```++## Error Handling Patterns++### Centralized Error Handler++```typescript+class ApiError extends Error {+ constructor(+ public statusCode: number,+ public message: string,+ public isOperational = true+ ) {+ super(message)+ Object.setPrototypeOf(this, ApiError.prototype)+ }+}++export function errorHandler(error: unknown, req: Request): Response {+ if (error instanceof ApiError) {+ return NextResponse.json({+ success: false,+ error: error.message+ }, { status: error.statusCode })+ }++ if (error instanceof z.ZodError) {+ return NextResponse.json({+ success: false,+ error: 'Validation failed',+ details: error.errors+ }, { status: 400 })+ }++ // Log unexpected errors+ console.error('Unexpected error:', error)++ return NextResponse.json({+ success: false,+ error: 'Internal server error'+ }, { status: 500 })+}++// Usage+export async function GET(request: Request) {+ try {+ const data = await fetchData()+ return NextResponse.json({ success: true, data })+ } catch (error) {+ return errorHandler(error, request)+ }+}+```++### Retry with Exponential Backoff++```typescript+async function fetchWithRetry<T>(+ fn: () => Promise<T>,+ maxRetries = 3+): Promise<T> {+ let lastError: Error++ for (let i = 0; i < maxRetries; i++) {+ try {+ return await fn()+ } catch (error) {+ lastError = error as Error++ if (i < maxRetries - 1) {+ // Exponential backoff: 1s, 2s, 4s+ const delay = Math.pow(2, i) * 1000+ await new Promise(resolve => setTimeout(resolve, delay))+ }+ }+ }++ throw lastError!+}++// Usage+const data = await fetchWithRetry(() => fetchFromAPI())+```++## Authentication & Authorization++### JWT Token Validation++```typescript+import jwt from 'jsonwebtoken'++interface JWTPayload {+ userId: string+ email: string+ role: 'admin' | 'user'+}++export function verifyToken(token: string): JWTPayload {+ try {+ const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload+ return payload+ } catch (error) {+ throw new ApiError(401, 'Invalid token')+ }+}++export async function requireAuth(request: Request) {+ const token = request.headers.get('authorization')?.replace('Bearer ', '')++ if (!token) {+ throw new ApiError(401, 'Missing authorization token')+ }++ return verifyToken(token)+}++// Usage in API route+export async function GET(request: Request) {+ const user = await requireAuth(request)++ const data = await getDataForUser(user.userId)++ return NextResponse.json({ success: true, data })+}+```++### Role-Based Access Control++```typescript+type Permission = 'read' | 'write' | 'delete' | 'admin'++interface User {+ id: string+ role: 'admin' | 'moderator' | 'user'+}++const rolePermissions: Record<User['role'], Permission[]> = {+ admin: ['read', 'write', 'delete', 'admin'],+ moderator: ['read', 'write', 'delete'],+ user: ['read', 'write']+}++export function hasPermission(user: User, permission: Permission): boolean {+ return rolePermissions[user.role].includes(permission)+}++export function requirePermission(permission: Permission) {+ return (handler: (request: Request, user: User) => Promise<Response>) => {+ return async (request: Request) => {+ const user = await requireAuth(request)++ if (!hasPermission(user, permission)) {+ throw new ApiError(403, 'Insufficient permissions')+ }++ return handler(request, user)+ }+ }+}++// Usage - HOF wraps the handler+export const DELETE = requirePermission('delete')(+ async (request: Request, user: User) => {+ // Handler receives authenticated user with verified permission+ return new Response('Deleted', { status: 200 })+ }+)+```++## Rate Limiting++### Simple In-Memory Rate Limiter++```typescript+class RateLimiter {+ private requests = new Map<string, number[]>()++ async checkLimit(+ identifier: string,+ maxRequests: number,+ windowMs: number+ ): Promise<boolean> {+ const now = Date.now()+ const requests = this.requests.get(identifier) || []++ // Remove old requests outside window+ const recentRequests = requests.filter(time => now - time < windowMs)++ if (recentRequests.length >= maxRequests) {+ return false // Rate limit exceeded+ }++ // Add current request+ recentRequests.push(now)+ this.requests.set(identifier, recentRequests)++ return true+ }+}++const limiter = new RateLimiter()++export async function GET(request: Request) {+ const ip = request.headers.get('x-forwarded-for') || 'unknown'++ const allowed = await limiter.checkLimit(ip, 100, 60000) // 100 req/min++ if (!allowed) {+ return NextResponse.json({+ error: 'Rate limit exceeded'+ }, { status: 429 })+ }++ // Continue with request+}+```++## Background Jobs & Queues++### Simple Queue Pattern++```typescript+class JobQueue<T> {+ private queue: T[] = []+ private processing = false++ async add(job: T): Promise<void> {+ this.queue.push(job)++ if (!this.processing) {+ this.process()+ }+ }++ private async process(): Promise<void> {+ this.processing = true++ while (this.queue.length > 0) {+ const job = this.queue.shift()!++ try {+ await this.execute(job)+ } catch (error) {+ console.error('Job failed:', error)+ }+ }++ this.processing = false+ }++ private async execute(job: T): Promise<void> {+ // Job execution logic+ }+}++// Usage for indexing markets+interface IndexJob {+ marketId: string+}++const indexQueue = new JobQueue<IndexJob>()++export async function POST(request: Request) {+ const { marketId } = await request.json()++ // Add to queue instead of blocking+ await indexQueue.add({ marketId })++ return NextResponse.json({ success: true, message: 'Job queued' })+}+```++## Logging & Monitoring++### Structured Logging++```typescript+interface LogContext {+ userId?: string+ requestId?: string+ method?: string+ path?: string+ [key: string]: unknown+}++class Logger {+ log(level: 'info' | 'warn' | 'error', message: string, context?: LogContext) {+ const entry = {+ timestamp: new Date().toISOString(),+ level,+ message,+ ...context+ }++ console.log(JSON.stringify(entry))+ }++ info(message: string, context?: LogContext) {+ this.log('info', message, context)+ }++ warn(message: string, context?: LogContext) {+ this.log('warn', message, context)+ }++ error(message: string, error: Error, context?: LogContext) {+ this.log('error', message, {+ ...context,+ error: error.message,+ stack: error.stack+ })+ }+}++const logger = new Logger()++// Usage+export async function GET(request: Request) {+ const requestId = crypto.randomUUID()++ logger.info('Fetching markets', {+ requestId,+ method: 'GET',+ path: '/api/markets'+ })++ try {+ const markets = await fetchMarkets()+ return NextResponse.json({ success: true, data: markets })+ } catch (error) {+ logger.error('Failed to fetch markets', error as Error, { requestId })+ return NextResponse.json({ error: 'Internal error' }, { status: 500 })+ }+}+```++**Remember**: Backend patterns enable scalable, maintainable server-side applications. Choose patterns that fit your complexity level.diff --git a/.agents/skills/backend-patterns/agents/openai.yaml b/.agents/skills/backend-patterns/agents/openai.yamlnew file mode 100644index 000000000..5fb47c634--- /dev/null+++ b/.agents/skills/backend-patterns/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Backend Patterns"+ short_description: "API design, database, and server-side patterns"+ brand_color: "#F59E0B"+ default_prompt: "Apply backend patterns: API design, repository, caching"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/coding-standards/SKILL.md b/.agents/skills/coding-standards/SKILL.mdnew file mode 100644index 000000000..70d362398--- /dev/null+++ b/.agents/skills/coding-standards/SKILL.md@@ -0,0 +1,530 @@+---+name: coding-standards+description: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.+origin: ECC+---++# Coding Standards & Best Practices++Universal coding standards applicable across all projects.++## When to Activate++- Starting a new project or module+- Reviewing code for quality and maintainability+- Refactoring existing code to follow conventions+- Enforcing naming, formatting, or structural consistency+- Setting up linting, formatting, or type-checking rules+- Onboarding new contributors to coding conventions++## Code Quality Principles++### 1. Readability First+- Code is read more than written+- Clear variable and function names+- Self-documenting code preferred over comments+- Consistent formatting++### 2. KISS (Keep It Simple, Stupid)+- Simplest solution that works+- Avoid over-engineering+- No premature optimization+- Easy to understand > clever code++### 3. DRY (Don't Repeat Yourself)+- Extract common logic into functions+- Create reusable components+- Share utilities across modules+- Avoid copy-paste programming++### 4. YAGNI (You Aren't Gonna Need It)+- Don't build features before they're needed+- Avoid speculative generality+- Add complexity only when required+- Start simple, refactor when needed++## TypeScript/JavaScript Standards++### Variable Naming++```typescript+// ✅ GOOD: Descriptive names+const marketSearchQuery = 'election'+const isUserAuthenticated = true+const totalRevenue = 1000++// ❌ BAD: Unclear names+const q = 'election'+const flag = true+const x = 1000+```++### Function Naming++```typescript+// ✅ GOOD: Verb-noun pattern+async function fetchMarketData(marketId: string) { }+function calculateSimilarity(a: number[], b: number[]) { }+function isValidEmail(email: string): boolean { }++// ❌ BAD: Unclear or noun-only+async function market(id: string) { }+function similarity(a, b) { }+function email(e) { }+```++### Immutability Pattern (CRITICAL)++```typescript+// ✅ ALWAYS use spread operator+const updatedUser = {+ ...user,+ name: 'New Name'+}++const updatedArray = [...items, newItem]++// ❌ NEVER mutate directly+user.name = 'New Name' // BAD+items.push(newItem) // BAD+```++### Error Handling++```typescript+// ✅ GOOD: Comprehensive error handling+async function fetchData(url: string) {+ try {+ const response = await fetch(url)++ if (!response.ok) {+ throw new Error(`HTTP ${response.status}: ${response.statusText}`)+ }++ return await response.json()+ } catch (error) {+ console.error('Fetch failed:', error)+ throw new Error('Failed to fetch data')+ }+}++// ❌ BAD: No error handling+async function fetchData(url) {+ const response = await fetch(url)+ return response.json()+}+```++### Async/Await Best Practices++```typescript+// ✅ GOOD: Parallel execution when possible+const [users, markets, stats] = await Promise.all([+ fetchUsers(),+ fetchMarkets(),+ fetchStats()+])++// ❌ BAD: Sequential when unnecessary+const users = await fetchUsers()+const markets = await fetchMarkets()+const stats = await fetchStats()+```++### Type Safety++```typescript+// ✅ GOOD: Proper types+interface Market {+ id: string+ name: string+ status: 'active' | 'resolved' | 'closed'+ created_at: Date+}++function getMarket(id: string): Promise<Market> {+ // Implementation+}++// ❌ BAD: Using 'any'+function getMarket(id: any): Promise<any> {+ // Implementation+}+```++## React Best Practices++### Component Structure++```typescript+// ✅ GOOD: Functional component with types+interface ButtonProps {+ children: React.ReactNode+ onClick: () => void+ disabled?: boolean+ variant?: 'primary' | 'secondary'+}++export function Button({+ children,+ onClick,+ disabled = false,+ variant = 'primary'+}: ButtonProps) {+ return (+ <button+ onClick={onClick}+ disabled={disabled}+ className={`btn btn-${variant}`}+ >+ {children}+ </button>+ )+}++// ❌ BAD: No types, unclear structure+export function Button(props) {+ return <button onClick={props.onClick}>{props.children}</button>+}+```++### Custom Hooks++```typescript+// ✅ GOOD: Reusable custom hook+export function useDebounce<T>(value: T, delay: number): T {+ const [debouncedValue, setDebouncedValue] = useState<T>(value)++ useEffect(() => {+ const handler = setTimeout(() => {+ setDebouncedValue(value)+ }, delay)++ return () => clearTimeout(handler)+ }, [value, delay])++ return debouncedValue+}++// Usage+const debouncedQuery = useDebounce(searchQuery, 500)+```++### State Management++```typescript+// ✅ GOOD: Proper state updates+const [count, setCount] = useState(0)++// Functional update for state based on previous state+setCount(prev => prev + 1)++// ❌ BAD: Direct state reference+setCount(count + 1) // Can be stale in async scenarios+```++### Conditional Rendering++```typescript+// ✅ GOOD: Clear conditional rendering+{isLoading && <Spinner />}+{error && <ErrorMessage error={error} />}+{data && <DataDisplay data={data} />}++// ❌ BAD: Ternary hell+{isLoading ? <Spinner /> : error ? <ErrorMessage error={error} /> : data ? <DataDisplay data={data} /> : null}+```++## API Design Standards++### REST API Conventions++```+GET /api/markets # List all markets+GET /api/markets/:id # Get specific market+POST /api/markets # Create new market+PUT /api/markets/:id # Update market (full)+PATCH /api/markets/:id # Update market (partial)+DELETE /api/markets/:id # Delete market++# Query parameters for filtering+GET /api/markets?status=active&limit=10&offset=0+```++### Response Format++```typescript+// ✅ GOOD: Consistent response structure+interface ApiResponse<T> {+ success: boolean+ data?: T+ error?: string+ meta?: {+ total: number+ page: number+ limit: number+ }+}++// Success response+return NextResponse.json({+ success: true,+ data: markets,+ meta: { total: 100, page: 1, limit: 10 }+})++// Error response+return NextResponse.json({+ success: false,+ error: 'Invalid request'+}, { status: 400 })+```++### Input Validation++```typescript+import { z } from 'zod'++// ✅ GOOD: Schema validation+const CreateMarketSchema = z.object({+ name: z.string().min(1).max(200),+ description: z.string().min(1).max(2000),+ endDate: z.string().datetime(),+ categories: z.array(z.string()).min(1)+})++export async function POST(request: Request) {+ const body = await request.json()++ try {+ const validated = CreateMarketSchema.parse(body)+ // Proceed with validated data+ } catch (error) {+ if (error instanceof z.ZodError) {+ return NextResponse.json({+ success: false,+ error: 'Validation failed',+ details: error.errors+ }, { status: 400 })+ }+ }+}+```++## File Organization++### Project Structure++```+src/+├── app/ # Next.js App Router+│ ├── api/ # API routes+│ ├── markets/ # Market pages+│ └── (auth)/ # Auth pages (route groups)+├── components/ # React components+│ ├── ui/ # Generic UI components+│ ├── forms/ # Form components+│ └── layouts/ # Layout components+├── hooks/ # Custom React hooks+├── lib/ # Utilities and configs+│ ├── api/ # API clients+│ ├── utils/ # Helper functions+│ └── constants/ # Constants+├── types/ # TypeScript types+└── styles/ # Global styles+```++### File Naming++```+components/Button.tsx # PascalCase for components+hooks/useAuth.ts # camelCase with 'use' prefix+lib/formatDate.ts # camelCase for utilities+types/market.types.ts # camelCase with .types suffix+```++## Comments & Documentation++### When to Comment++```typescript+// ✅ GOOD: Explain WHY, not WHAT+// Use exponential backoff to avoid overwhelming the API during outages+const delay = Math.min(1000 * Math.pow(2, retryCount), 30000)++// Deliberately using mutation here for performance with large arrays+items.push(newItem)++// ❌ BAD: Stating the obvious+// Increment counter by 1+count++++// Set name to user's name+name = user.name+```++### JSDoc for Public APIs++```typescript+/**+ * Searches markets using semantic similarity.+ *+ * @param query - Natural language search query+ * @param limit - Maximum number of results (default: 10)+ * @returns Array of markets sorted by similarity score+ * @throws {Error} If OpenAI API fails or Redis unavailable+ *+ * @example+ * ```typescript+ * const results = await searchMarkets('election', 5)+ * console.log(results[0].name) // "Trump vs Biden"+ * ```+ */+export async function searchMarkets(+ query: string,+ limit: number = 10+): Promise<Market[]> {+ // Implementation+}+```++## Performance Best Practices++### Memoization++```typescript+import { useMemo, useCallback } from 'react'++// ✅ GOOD: Memoize expensive computations+const sortedMarkets = useMemo(() => {+ return markets.sort((a, b) => b.volume - a.volume)+}, [markets])++// ✅ GOOD: Memoize callbacks+const handleSearch = useCallback((query: string) => {+ setSearchQuery(query)+}, [])+```++### Lazy Loading++```typescript+import { lazy, Suspense } from 'react'++// ✅ GOOD: Lazy load heavy components+const HeavyChart = lazy(() => import('./HeavyChart'))++export function Dashboard() {+ return (+ <Suspense fallback={<Spinner />}>+ <HeavyChart />+ </Suspense>+ )+}+```++### Database Queries++```typescript+// ✅ GOOD: Select only needed columns+const { data } = await supabase+ .from('markets')+ .select('id, name, status')+ .limit(10)++// ❌ BAD: Select everything+const { data } = await supabase+ .from('markets')+ .select('*')+```++## Testing Standards++### Test Structure (AAA Pattern)++```typescript+test('calculates similarity correctly', () => {+ // Arrange+ const vector1 = [1, 0, 0]+ const vector2 = [0, 1, 0]++ // Act+ const similarity = calculateCosineSimilarity(vector1, vector2)++ // Assert+ expect(similarity).toBe(0)+})+```++### Test Naming++```typescript+// ✅ GOOD: Descriptive test names+test('returns empty array when no markets match query', () => { })+test('throws error when OpenAI API key is missing', () => { })+test('falls back to substring search when Redis unavailable', () => { })++// ❌ BAD: Vague test names+test('works', () => { })+test('test search', () => { })+```++## Code Smell Detection++Watch for these anti-patterns:++### 1. Long Functions+```typescript+// ❌ BAD: Function > 50 lines+function processMarketData() {+ // 100 lines of code+}++// ✅ GOOD: Split into smaller functions+function processMarketData() {+ const validated = validateData()+ const transformed = transformData(validated)+ return saveData(transformed)+}+```++### 2. Deep Nesting+```typescript+// ❌ BAD: 5+ levels of nesting+if (user) {+ if (user.isAdmin) {+ if (market) {+ if (market.isActive) {+ if (hasPermission) {+ // Do something+ }+ }+ }+ }+}++// ✅ GOOD: Early returns+if (!user) return+if (!user.isAdmin) return+if (!market) return+if (!market.isActive) return+if (!hasPermission) return++// Do something+```++### 3. Magic Numbers+```typescript+// ❌ BAD: Unexplained numbers+if (retryCount > 3) { }+setTimeout(callback, 500)++// ✅ GOOD: Named constants+const MAX_RETRIES = 3+const DEBOUNCE_DELAY_MS = 500++if (retryCount > MAX_RETRIES) { }+setTimeout(callback, DEBOUNCE_DELAY_MS)+```++**Remember**: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.diff --git a/.agents/skills/coding-standards/agents/openai.yaml b/.agents/skills/coding-standards/agents/openai.yamlnew file mode 100644index 000000000..b0dda0eff--- /dev/null+++ b/.agents/skills/coding-standards/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Coding Standards"+ short_description: "Universal coding standards and best practices"+ brand_color: "#3B82F6"+ default_prompt: "Apply standards: immutability, error handling, type safety"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/e2e-testing/SKILL.md b/.agents/skills/e2e-testing/SKILL.mdnew file mode 100644index 000000000..056319914--- /dev/null+++ b/.agents/skills/e2e-testing/SKILL.md@@ -0,0 +1,326 @@+---+name: e2e-testing+description: Playwright E2E testing patterns, Page Object Model, configuration, CI/CD integration, artifact management, and flaky test strategies.+origin: ECC+---++# E2E Testing Patterns++Comprehensive Playwright patterns for building stable, fast, and maintainable E2E test suites.++## Test File Organization++```+tests/+├── e2e/+│ ├── auth/+│ │ ├── login.spec.ts+│ │ ├── logout.spec.ts+│ │ └── register.spec.ts+│ ├── features/+│ │ ├── browse.spec.ts+│ │ ├── search.spec.ts+│ │ └── create.spec.ts+│ └── api/+│ └── endpoints.spec.ts+├── fixtures/+│ ├── auth.ts+│ └── data.ts+└── playwright.config.ts+```++## Page Object Model (POM)++```typescript+import { Page, Locator } from '@playwright/test'++export class ItemsPage {+ readonly page: Page+ readonly searchInput: Locator+ readonly itemCards: Locator+ readonly createButton: Locator++ constructor(page: Page) {+ this.page = page+ this.searchInput = page.locator('[data-testid="search-input"]')+ this.itemCards = page.locator('[data-testid="item-card"]')+ this.createButton = page.locator('[data-testid="create-btn"]')+ }++ async goto() {+ await this.page.goto('/items')+ await this.page.waitForLoadState('networkidle')+ }++ async search(query: string) {+ await this.searchInput.fill(query)+ await this.page.waitForResponse(resp => resp.url().includes('/api/search'))+ await this.page.waitForLoadState('networkidle')+ }++ async getItemCount() {+ return await this.itemCards.count()+ }+}+```++## Test Structure++```typescript+import { test, expect } from '@playwright/test'+import { ItemsPage } from '../../pages/ItemsPage'++test.describe('Item Search', () => {+ let itemsPage: ItemsPage++ test.beforeEach(async ({ page }) => {+ itemsPage = new ItemsPage(page)+ await itemsPage.goto()+ })++ test('should search by keyword', async ({ page }) => {+ await itemsPage.search('test')++ const count = await itemsPage.getItemCount()+ expect(count).toBeGreaterThan(0)++ await expect(itemsPage.itemCards.first()).toContainText(/test/i)+ await page.screenshot({ path: 'artifacts/search-results.png' })+ })++ test('should handle no results', async ({ page }) => {+ await itemsPage.search('xyznonexistent123')++ await expect(page.locator('[data-testid="no-results"]')).toBeVisible()+ expect(await itemsPage.getItemCount()).toBe(0)+ })+})+```++## Playwright Configuration++```typescript+import { defineConfig, devices } from '@playwright/test'++export default defineConfig({+ testDir: './tests/e2e',+ fullyParallel: true,+ forbidOnly: !!process.env.CI,+ retries: process.env.CI ? 2 : 0,+ workers: process.env.CI ? 1 : undefined,+ reporter: [+ ['html', { outputFolder: 'playwright-report' }],+ ['junit', { outputFile: 'playwright-results.xml' }],+ ['json', { outputFile: 'playwright-results.json' }]+ ],+ use: {+ baseURL: process.env.BASE_URL || 'http://localhost:3000',+ trace: 'on-first-retry',+ screenshot: 'only-on-failure',+ video: 'retain-on-failure',+ actionTimeout: 10000,+ navigationTimeout: 30000,+ },+ projects: [+ { name: 'chromium', use: { ...devices['Desktop Chrome'] } },+ { name: 'firefox', use: { ...devices['Desktop Firefox'] } },+ { name: 'webkit', use: { ...devices['Desktop Safari'] } },+ { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },+ ],+ webServer: {+ command: 'npm run dev',+ url: 'http://localhost:3000',+ reuseExistingServer: !process.env.CI,+ timeout: 120000,+ },+})+```++## Flaky Test Patterns++### Quarantine++```typescript+test('flaky: complex search', async ({ page }) => {+ test.fixme(true, 'Flaky - Issue #123')+ // test code...+})++test('conditional skip', async ({ page }) => {+ test.skip(process.env.CI, 'Flaky in CI - Issue #123')+ // test code...+})+```++### Identify Flakiness++```bash+npx playwright test tests/search.spec.ts --repeat-each=10+npx playwright test tests/search.spec.ts --retries=3+```++### Common Causes & Fixes++**Race conditions:**+```typescript+// Bad: assumes element is ready+await page.click('[data-testid="button"]')++// Good: auto-wait locator+await page.locator('[data-testid="button"]').click()+```++**Network timing:**+```typescript+// Bad: arbitrary timeout+await page.waitForTimeout(5000)++// Good: wait for specific condition+await page.waitForResponse(resp => resp.url().includes('/api/data'))+```++**Animation timing:**+```typescript+// Bad: click during animation+await page.click('[data-testid="menu-item"]')++// Good: wait for stability+await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })+await page.waitForLoadState('networkidle')+await page.locator('[data-testid="menu-item"]').click()+```++## Artifact Management++### Screenshots++```typescript+await page.screenshot({ path: 'artifacts/after-login.png' })+await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })+await page.locator('[data-testid="chart"]').screenshot({ path: 'artifacts/chart.png' })+```++### Traces++```typescript+await browser.startTracing(page, {+ path: 'artifacts/trace.json',+ screenshots: true,+ snapshots: true,+})+// ... test actions ...+await browser.stopTracing()+```++### Video++```typescript+// In playwright.config.ts+use: {+ video: 'retain-on-failure',+ videosPath: 'artifacts/videos/'+}+```++## CI/CD Integration++```yaml+# .github/workflows/e2e.yml+name: E2E Tests+on: [push, pull_request]++jobs:+ test:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: 20+ - run: npm ci+ - run: npx playwright install --with-deps+ - run: npx playwright test+ env:+ BASE_URL: ${{ vars.STAGING_URL }}+ - uses: actions/upload-artifact@v4+ if: always()+ with:+ name: playwright-report+ path: playwright-report/+ retention-days: 30+```++## Test Report Template++```markdown+# E2E Test Report++**Date:** YYYY-MM-DD HH:MM+**Duration:** Xm Ys+**Status:** PASSING / FAILING++## Summary+- Total: X | Passed: Y (Z%) | Failed: A | Flaky: B | Skipped: C++## Failed Tests++### test-name+**File:** `tests/e2e/feature.spec.ts:45`+**Error:** Expected element to be visible+**Screenshot:** artifacts/failed.png+**Recommended Fix:** [description]++## Artifacts+- HTML Report: playwright-report/index.html+- Screenshots: artifacts/*.png+- Videos: artifacts/videos/*.webm+- Traces: artifacts/*.zip+```++## Wallet / Web3 Testing++```typescript+test('wallet connection', async ({ page, context }) => {+ // Mock wallet provider+ await context.addInitScript(() => {+ window.ethereum = {+ isMetaMask: true,+ request: async ({ method }) => {+ if (method === 'eth_requestAccounts')+ return ['0x1234567890123456789012345678901234567890']+ if (method === 'eth_chainId') return '0x1'+ }+ }+ })++ await page.goto('/')+ await page.locator('[data-testid="connect-wallet"]').click()+ await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')+})+```++## Financial / Critical Flow Testing++```typescript+test('trade execution', async ({ page }) => {+ // Skip on production — real money+ test.skip(process.env.NODE_ENV === 'production', 'Skip on production')++ await page.goto('/markets/test-market')+ await page.locator('[data-testid="position-yes"]').click()+ await page.locator('[data-testid="trade-amount"]').fill('1.0')++ // Verify preview+ const preview = page.locator('[data-testid="trade-preview"]')+ await expect(preview).toContainText('1.0')++ // Confirm and wait for blockchain+ await page.locator('[data-testid="confirm-trade"]').click()+ await page.waitForResponse(+ resp => resp.url().includes('/api/trade') && resp.status() === 200,+ { timeout: 30000 }+ )++ await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()+})+```diff --git a/.agents/skills/e2e-testing/agents/openai.yaml b/.agents/skills/e2e-testing/agents/openai.yamlnew file mode 100644index 000000000..cdedda78c--- /dev/null+++ b/.agents/skills/e2e-testing/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "E2E Testing"+ short_description: "Playwright end-to-end testing"+ brand_color: "#06B6D4"+ default_prompt: "Generate Playwright E2E tests with Page Object Model"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/eval-harness/SKILL.md b/.agents/skills/eval-harness/SKILL.mdnew file mode 100644index 000000000..d320670c9--- /dev/null+++ b/.agents/skills/eval-harness/SKILL.md@@ -0,0 +1,236 @@+---+name: eval-harness+description: Formal evaluation framework for Claude Code sessions implementing eval-driven development (EDD) principles+origin: ECC+tools: Read, Write, Edit, Bash, Grep, Glob+---++# Eval Harness Skill++A formal evaluation framework for Claude Code sessions, implementing eval-driven development (EDD) principles.++## When to Activate++- Setting up eval-driven development (EDD) for AI-assisted workflows+- Defining pass/fail criteria for Claude Code task completion+- Measuring agent reliability with pass@k metrics+- Creating regression test suites for prompt or agent changes+- Benchmarking agent performance across model versions++## Philosophy++Eval-Driven Development treats evals as the "unit tests of AI development":+- Define expected behavior BEFORE implementation+- Run evals continuously during development+- Track regressions with each change+- Use pass@k metrics for reliability measurement++## Eval Types++### Capability Evals+Test if Claude can do something it couldn't before:+```markdown+[CAPABILITY EVAL: feature-name]+Task: Description of what Claude should accomplish+Success Criteria:+ - [ ] Criterion 1+ - [ ] Criterion 2+ - [ ] Criterion 3+Expected Output: Description of expected result+```++### Regression Evals+Ensure changes don't break existing functionality:+```markdown+[REGRESSION EVAL: feature-name]+Baseline: SHA or checkpoint name+Tests:+ - existing-test-1: PASS/FAIL+ - existing-test-2: PASS/FAIL+ - existing-test-3: PASS/FAIL+Result: X/Y passed (previously Y/Y)+```++## Grader Types++### 1. Code-Based Grader+Deterministic checks using code:+```bash+# Check if file contains expected pattern+grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"++# Check if tests pass+npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"++# Check if build succeeds+npm run build && echo "PASS" || echo "FAIL"+```++### 2. Model-Based Grader+Use Claude to evaluate open-ended outputs:+```markdown+[MODEL GRADER PROMPT]+Evaluate the following code change:+1. Does it solve the stated problem?+2. Is it well-structured?+3. Are edge cases handled?+4. Is error handling appropriate?++Score: 1-5 (1=poor, 5=excellent)+Reasoning: [explanation]+```++### 3. Human Grader+Flag for manual review:+```markdown+[HUMAN REVIEW REQUIRED]+Change: Description of what changed+Reason: Why human review is needed+Risk Level: LOW/MEDIUM/HIGH+```++## Metrics++### pass@k+"At least one success in k attempts"+- pass@1: First attempt success rate+- pass@3: Success within 3 attempts+- Typical target: pass@3 > 90%++### pass^k+"All k trials succeed"+- Higher bar for reliability+- pass^3: 3 consecutive successes+- Use for critical paths++## Eval Workflow++### 1. Define (Before Coding)+```markdown+## EVAL DEFINITION: feature-xyz++### Capability Evals+1. Can create new user account+2. Can validate email format+3. Can hash password securely++### Regression Evals+1. Existing login still works+2. Session management unchanged+3. Logout flow intact++### Success Metrics+- pass@3 > 90% for capability evals+- pass^3 = 100% for regression evals+```++### 2. Implement+Write code to pass the defined evals.++### 3. Evaluate+```bash+# Run capability evals+[Run each capability eval, record PASS/FAIL]++# Run regression evals+npm test -- --testPathPattern="existing"++# Generate report+```++### 4. Report+```markdown+EVAL REPORT: feature-xyz+========================++Capability Evals:+ create-user: PASS (pass@1)+ validate-email: PASS (pass@2)+ hash-password: PASS (pass@1)+ Overall: 3/3 passed++Regression Evals:+ login-flow: PASS+ session-mgmt: PASS+ logout-flow: PASS+ Overall: 3/3 passed++Metrics:+ pass@1: 67% (2/3)+ pass@3: 100% (3/3)++Status: READY FOR REVIEW+```++## Integration Patterns++### Pre-Implementation+```+/eval define feature-name+```+Creates eval definition file at `.claude/evals/feature-name.md`++### During Implementation+```+/eval check feature-name+```+Runs current evals and reports status++### Post-Implementation+```+/eval report feature-name+```+Generates full eval report++## Eval Storage++Store evals in project:+```+.claude/+ evals/+ feature-xyz.md # Eval definition+ feature-xyz.log # Eval run history+ baseline.json # Regression baselines+```++## Best Practices++1. **Define evals BEFORE coding** - Forces clear thinking about success criteria+2. **Run evals frequently** - Catch regressions early+3. **Track pass@k over time** - Monitor reliability trends+4. **Use code graders when possible** - Deterministic > probabilistic+5. **Human review for security** - Never fully automate security checks+6. **Keep evals fast** - Slow evals don't get run+7. **Version evals with code** - Evals are first-class artifacts++## Example: Adding Authentication++```markdown+## EVAL: add-authentication++### Phase 1: Define (10 min)+Capability Evals:+- [ ] User can register with email/password+- [ ] User can login with valid credentials+- [ ] Invalid credentials rejected with proper error+- [ ] Sessions persist across page reloads+- [ ] Logout clears session++Regression Evals:+- [ ] Public routes still accessible+- [ ] API responses unchanged+- [ ] Database schema compatible++### Phase 2: Implement (varies)+[Write code]++### Phase 3: Evaluate+Run: /eval check add-authentication++### Phase 4: Report+EVAL REPORT: add-authentication+==============================+Capability: 5/5 passed (pass@3: 100%)+Regression: 3/3 passed (pass^3: 100%)+Status: SHIP IT+```diff --git a/.agents/skills/eval-harness/agents/openai.yaml b/.agents/skills/eval-harness/agents/openai.yamlnew file mode 100644index 000000000..e017e6a7e--- /dev/null+++ b/.agents/skills/eval-harness/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Eval Harness"+ short_description: "Eval-driven development with pass/fail criteria"+ brand_color: "#EC4899"+ default_prompt: "Set up eval-driven development with pass/fail criteria"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/frontend-patterns/SKILL.md b/.agents/skills/frontend-patterns/SKILL.mdnew file mode 100644index 000000000..7ce388026--- /dev/null+++ b/.agents/skills/frontend-patterns/SKILL.md@@ -0,0 +1,642 @@+---+name: frontend-patterns+description: Frontend development patterns for React, Next.js, state management, performance optimization, and UI best practices.+origin: ECC+---++# Frontend Development Patterns++Modern frontend patterns for React, Next.js, and performant user interfaces.++## When to Activate++- Building React components (composition, props, rendering)+- Managing state (useState, useReducer, Zustand, Context)+- Implementing data fetching (SWR, React Query, server components)+- Optimizing performance (memoization, virtualization, code splitting)+- Working with forms (validation, controlled inputs, Zod schemas)+- Handling client-side routing and navigation+- Building accessible, responsive UI patterns++## Component Patterns++### Composition Over Inheritance++```typescript+// ✅ GOOD: Component composition+interface CardProps {+ children: React.ReactNode+ variant?: 'default' | 'outlined'+}++export function Card({ children, variant = 'default' }: CardProps) {+ return <div className={`card card-${variant}`}>{children}</div>+}++export function CardHeader({ children }: { children: React.ReactNode }) {+ return <div className="card-header">{children}</div>+}++export function CardBody({ children }: { children: React.ReactNode }) {+ return <div className="card-body">{children}</div>+}++// Usage+<Card>+ <CardHeader>Title</CardHeader>+ <CardBody>Content</CardBody>+</Card>+```++### Compound Components++```typescript+interface TabsContextValue {+ activeTab: string+ setActiveTab: (tab: string) => void+}++const TabsContext = createContext<TabsContextValue | undefined>(undefined)++export function Tabs({ children, defaultTab }: {+ children: React.ReactNode+ defaultTab: string+}) {+ const [activeTab, setActiveTab] = useState(defaultTab)++ return (+ <TabsContext.Provider value={{ activeTab, setActiveTab }}>+ {children}+ </TabsContext.Provider>+ )+}++export function TabList({ children }: { children: React.ReactNode }) {+ return <div className="tab-list">{children}</div>+}++export function Tab({ id, children }: { id: string, children: React.ReactNode }) {+ const context = useContext(TabsContext)+ if (!context) throw new Error('Tab must be used within Tabs')++ return (+ <button+ className={context.activeTab === id ? 'active' : ''}+ onClick={() => context.setActiveTab(id)}+ >+ {children}+ </button>+ )+}++// Usage+<Tabs defaultTab="overview">+ <TabList>+ <Tab id="overview">Overview</Tab>+ <Tab id="details">Details</Tab>+ </TabList>+</Tabs>+```++### Render Props Pattern++```typescript+interface DataLoaderProps<T> {+ url: string+ children: (data: T | null, loading: boolean, error: Error | null) => React.ReactNode+}++export function DataLoader<T>({ url, children }: DataLoaderProps<T>) {+ const [data, setData] = useState<T | null>(null)+ const [loading, setLoading] = useState(true)+ const [error, setError] = useState<Error | null>(null)++ useEffect(() => {+ fetch(url)+ .then(res => res.json())+ .then(setData)+ .catch(setError)+ .finally(() => setLoading(false))+ }, [url])++ return <>{children(data, loading, error)}</>+}++// Usage+<DataLoader<Market[]> url="/api/markets">+ {(markets, loading, error) => {+ if (loading) return <Spinner />+ if (error) return <Error error={error} />+ return <MarketList markets={markets!} />+ }}+</DataLoader>+```++## Custom Hooks Patterns++### State Management Hook++```typescript+export function useToggle(initialValue = false): [boolean, () => void] {+ const [value, setValue] = useState(initialValue)++ const toggle = useCallback(() => {+ setValue(v => !v)+ }, [])++ return [value, toggle]+}++// Usage+const [isOpen, toggleOpen] = useToggle()+```++### Async Data Fetching Hook++```typescript+interface UseQueryOptions<T> {+ onSuccess?: (data: T) => void+ onError?: (error: Error) => void+ enabled?: boolean+}++export function useQuery<T>(+ key: string,+ fetcher: () => Promise<T>,+ options?: UseQueryOptions<T>+) {+ const [data, setData] = useState<T | null>(null)+ const [error, setError] = useState<Error | null>(null)+ const [loading, setLoading] = useState(false)++ const refetch = useCallback(async () => {+ setLoading(true)+ setError(null)++ try {+ const result = await fetcher()+ setData(result)+ options?.onSuccess?.(result)+ } catch (err) {+ const error = err as Error+ setError(error)+ options?.onError?.(error)+ } finally {+ setLoading(false)+ }+ }, [fetcher, options])++ useEffect(() => {+ if (options?.enabled !== false) {+ refetch()+ }+ }, [key, refetch, options?.enabled])++ return { data, error, loading, refetch }+}++// Usage+const { data: markets, loading, error, refetch } = useQuery(+ 'markets',+ () => fetch('/api/markets').then(r => r.json()),+ {+ onSuccess: data => console.log('Fetched', data.length, 'markets'),+ onError: err => console.error('Failed:', err)+ }+)+```++### Debounce Hook++```typescript+export function useDebounce<T>(value: T, delay: number): T {+ const [debouncedValue, setDebouncedValue] = useState<T>(value)++ useEffect(() => {+ const handler = setTimeout(() => {+ setDebouncedValue(value)+ }, delay)++ return () => clearTimeout(handler)+ }, [value, delay])++ return debouncedValue+}++// Usage+const [searchQuery, setSearchQuery] = useState('')+const debouncedQuery = useDebounce(searchQuery, 500)++useEffect(() => {+ if (debouncedQuery) {+ performSearch(debouncedQuery)+ }+}, [debouncedQuery])+```++## State Management Patterns++### Context + Reducer Pattern++```typescript+interface State {+ markets: Market[]+ selectedMarket: Market | null+ loading: boolean+}++type Action =+ | { type: 'SET_MARKETS'; payload: Market[] }+ | { type: 'SELECT_MARKET'; payload: Market }+ | { type: 'SET_LOADING'; payload: boolean }++function reducer(state: State, action: Action): State {+ switch (action.type) {+ case 'SET_MARKETS':+ return { ...state, markets: action.payload }+ case 'SELECT_MARKET':+ return { ...state, selectedMarket: action.payload }+ case 'SET_LOADING':+ return { ...state, loading: action.payload }+ default:+ return state+ }+}++const MarketContext = createContext<{+ state: State+ dispatch: Dispatch<Action>+} | undefined>(undefined)++export function MarketProvider({ children }: { children: React.ReactNode }) {+ const [state, dispatch] = useReducer(reducer, {+ markets: [],+ selectedMarket: null,+ loading: false+ })++ return (+ <MarketContext.Provider value={{ state, dispatch }}>+ {children}+ </MarketContext.Provider>+ )+}++export function useMarkets() {+ const context = useContext(MarketContext)+ if (!context) throw new Error('useMarkets must be used within MarketProvider')+ return context+}+```++## Performance Optimization++### Memoization++```typescript+// ✅ useMemo for expensive computations+const sortedMarkets = useMemo(() => {+ return markets.sort((a, b) => b.volume - a.volume)+}, [markets])++// ✅ useCallback for functions passed to children+const handleSearch = useCallback((query: string) => {+ setSearchQuery(query)+}, [])++// ✅ React.memo for pure components+export const MarketCard = React.memo<MarketCardProps>(({ market }) => {+ return (+ <div className="market-card">+ <h3>{market.name}</h3>+ <p>{market.description}</p>+ </div>+ )+})+```++### Code Splitting & Lazy Loading++```typescript+import { lazy, Suspense } from 'react'++// ✅ Lazy load heavy components+const HeavyChart = lazy(() => import('./HeavyChart'))+const ThreeJsBackground = lazy(() => import('./ThreeJsBackground'))++export function Dashboard() {+ return (+ <div>+ <Suspense fallback={<ChartSkeleton />}>+ <HeavyChart data={data} />+ </Suspense>++ <Suspense fallback={null}>+ <ThreeJsBackground />+ </Suspense>+ </div>+ )+}+```++### Virtualization for Long Lists++```typescript+import { useVirtualizer } from '@tanstack/react-virtual'++export function VirtualMarketList({ markets }: { markets: Market[] }) {+ const parentRef = useRef<HTMLDivElement>(null)++ const virtualizer = useVirtualizer({+ count: markets.length,+ getScrollElement: () => parentRef.current,+ estimateSize: () => 100, // Estimated row height+ overscan: 5 // Extra items to render+ })++ return (+ <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>+ <div+ style={{+ height: `${virtualizer.getTotalSize()}px`,+ position: 'relative'+ }}+ >+ {virtualizer.getVirtualItems().map(virtualRow => (+ <div+ key={virtualRow.index}+ style={{+ position: 'absolute',+ top: 0,+ left: 0,+ width: '100%',+ height: `${virtualRow.size}px`,+ transform: `translateY(${virtualRow.start}px)`+ }}+ >+ <MarketCard market={markets[virtualRow.index]} />+ </div>+ ))}+ </div>+ </div>+ )+}+```++## Form Handling Patterns++### Controlled Form with Validation++```typescript+interface FormData {+ name: string+ description: string+ endDate: string+}++interface FormErrors {+ name?: string+ description?: string+ endDate?: string+}++export function CreateMarketForm() {+ const [formData, setFormData] = useState<FormData>({+ name: '',+ description: '',+ endDate: ''+ })++ const [errors, setErrors] = useState<FormErrors>({})++ const validate = (): boolean => {+ const newErrors: FormErrors = {}++ if (!formData.name.trim()) {+ newErrors.name = 'Name is required'+ } else if (formData.name.length > 200) {+ newErrors.name = 'Name must be under 200 characters'+ }++ if (!formData.description.trim()) {+ newErrors.description = 'Description is required'+ }++ if (!formData.endDate) {+ newErrors.endDate = 'End date is required'+ }++ setErrors(newErrors)+ return Object.keys(newErrors).length === 0+ }++ const handleSubmit = async (e: React.FormEvent) => {+ e.preventDefault()++ if (!validate()) return++ try {+ await createMarket(formData)+ // Success handling+ } catch (error) {+ // Error handling+ }+ }++ return (+ <form onSubmit={handleSubmit}>+ <input+ value={formData.name}+ onChange={e => setFormData(prev => ({ ...prev, name: e.target.value }))}+ placeholder="Market name"+ />+ {errors.name && <span className="error">{errors.name}</span>}++ {/* Other fields */}++ <button type="submit">Create Market</button>+ </form>+ )+}+```++## Error Boundary Pattern++```typescript+interface ErrorBoundaryState {+ hasError: boolean+ error: Error | null+}++export class ErrorBoundary extends React.Component<+ { children: React.ReactNode },+ ErrorBoundaryState+> {+ state: ErrorBoundaryState = {+ hasError: false,+ error: null+ }++ static getDerivedStateFromError(error: Error): ErrorBoundaryState {+ return { hasError: true, error }+ }++ componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {+ console.error('Error boundary caught:', error, errorInfo)+ }++ render() {+ if (this.state.hasError) {+ return (+ <div className="error-fallback">+ <h2>Something went wrong</h2>+ <p>{this.state.error?.message}</p>+ <button onClick={() => this.setState({ hasError: false })}>+ Try again+ </button>+ </div>+ )+ }++ return this.props.children+ }+}++// Usage+<ErrorBoundary>+ <App />+</ErrorBoundary>+```++## Animation Patterns++### Framer Motion Animations++```typescript+import { motion, AnimatePresence } from 'framer-motion'++// ✅ List animations+export function AnimatedMarketList({ markets }: { markets: Market[] }) {+ return (+ <AnimatePresence>+ {markets.map(market => (+ <motion.div+ key={market.id}+ initial={{ opacity: 0, y: 20 }}+ animate={{ opacity: 1, y: 0 }}+ exit={{ opacity: 0, y: -20 }}+ transition={{ duration: 0.3 }}+ >+ <MarketCard market={market} />+ </motion.div>+ ))}+ </AnimatePresence>+ )+}++// ✅ Modal animations+export function Modal({ isOpen, onClose, children }: ModalProps) {+ return (+ <AnimatePresence>+ {isOpen && (+ <>+ <motion.div+ className="modal-overlay"+ initial={{ opacity: 0 }}+ animate={{ opacity: 1 }}+ exit={{ opacity: 0 }}+ onClick={onClose}+ />+ <motion.div+ className="modal-content"+ initial={{ opacity: 0, scale: 0.9, y: 20 }}+ animate={{ opacity: 1, scale: 1, y: 0 }}+ exit={{ opacity: 0, scale: 0.9, y: 20 }}+ >+ {children}+ </motion.div>+ </>+ )}+ </AnimatePresence>+ )+}+```++## Accessibility Patterns++### Keyboard Navigation++```typescript+export function Dropdown({ options, onSelect }: DropdownProps) {+ const [isOpen, setIsOpen] = useState(false)+ const [activeIndex, setActiveIndex] = useState(0)++ const handleKeyDown = (e: React.KeyboardEvent) => {+ switch (e.key) {+ case 'ArrowDown':+ e.preventDefault()+ setActiveIndex(i => Math.min(i + 1, options.length - 1))+ break+ case 'ArrowUp':+ e.preventDefault()+ setActiveIndex(i => Math.max(i - 1, 0))+ break+ case 'Enter':+ e.preventDefault()+ onSelect(options[activeIndex])+ setIsOpen(false)+ break+ case 'Escape':+ setIsOpen(false)+ break+ }+ }++ return (+ <div+ role="combobox"+ aria-expanded={isOpen}+ aria-haspopup="listbox"+ onKeyDown={handleKeyDown}+ >+ {/* Dropdown implementation */}+ </div>+ )+}+```++### Focus Management++```typescript+export function Modal({ isOpen, onClose, children }: ModalProps) {+ const modalRef = useRef<HTMLDivElement>(null)+ const previousFocusRef = useRef<HTMLElement | null>(null)++ useEffect(() => {+ if (isOpen) {+ // Save currently focused element+ previousFocusRef.current = document.activeElement as HTMLElement++ // Focus modal+ modalRef.current?.focus()+ } else {+ // Restore focus when closing+ previousFocusRef.current?.focus()+ }+ }, [isOpen])++ return isOpen ? (+ <div+ ref={modalRef}+ role="dialog"+ aria-modal="true"+ tabIndex={-1}+ onKeyDown={e => e.key === 'Escape' && onClose()}+ >+ {children}+ </div>+ ) : null+}+```++**Remember**: Modern frontend patterns enable maintainable, performant user interfaces. Choose patterns that fit your project complexity.diff --git a/.agents/skills/frontend-patterns/agents/openai.yaml b/.agents/skills/frontend-patterns/agents/openai.yamlnew file mode 100644index 000000000..00f859956--- /dev/null+++ b/.agents/skills/frontend-patterns/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Frontend Patterns"+ short_description: "React and Next.js patterns and best practices"+ brand_color: "#8B5CF6"+ default_prompt: "Apply React/Next.js patterns and best practices"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/security-review/SKILL.md b/.agents/skills/security-review/SKILL.mdnew file mode 100644index 000000000..35403243b--- /dev/null+++ b/.agents/skills/security-review/SKILL.md@@ -0,0 +1,495 @@+---+name: security-review+description: Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment/sensitive features. Provides comprehensive security checklist and patterns.+origin: ECC+---++# Security Review Skill++This skill ensures all code follows security best practices and identifies potential vulnerabilities.++## When to Activate++- Implementing authentication or authorization+- Handling user input or file uploads+- Creating new API endpoints+- Working with secrets or credentials+- Implementing payment features+- Storing or transmitting sensitive data+- Integrating third-party APIs++## Security Checklist++### 1. Secrets Management++#### ❌ NEVER Do This+```typescript+const apiKey = "sk-proj-xxxxx" // Hardcoded secret+const dbPassword = "password123" // In source code+```++#### ✅ ALWAYS Do This+```typescript+const apiKey = process.env.OPENAI_API_KEY+const dbUrl = process.env.DATABASE_URL++// Verify secrets exist+if (!apiKey) {+ throw new Error('OPENAI_API_KEY not configured')+}+```++#### Verification Steps+- [ ] No hardcoded API keys, tokens, or passwords+- [ ] All secrets in environment variables+- [ ] `.env.local` in .gitignore+- [ ] No secrets in git history+- [ ] Production secrets in hosting platform (Vercel, Railway)++### 2. Input Validation++#### Always Validate User Input+```typescript+import { z } from 'zod'++// Define validation schema+const CreateUserSchema = z.object({+ email: z.string().email(),+ name: z.string().min(1).max(100),+ age: z.number().int().min(0).max(150)+})++// Validate before processing+export async function createUser(input: unknown) {+ try {+ const validated = CreateUserSchema.parse(input)+ return await db.users.create(validated)+ } catch (error) {+ if (error instanceof z.ZodError) {+ return { success: false, errors: error.errors }+ }+ throw error+ }+}+```++#### File Upload Validation+```typescript+function validateFileUpload(file: File) {+ // Size check (5MB max)+ const maxSize = 5 * 1024 * 1024+ if (file.size > maxSize) {+ throw new Error('File too large (max 5MB)')+ }++ // Type check+ const allowedTypes = ['image/jpeg', 'image/png', 'image/gif']+ if (!allowedTypes.includes(file.type)) {+ throw new Error('Invalid file type')+ }++ // Extension check+ const allowedExtensions = ['.jpg', '.jpeg', '.png', '.gif']+ const extension = file.name.toLowerCase().match(/\.[^.]+$/)?.[0]+ if (!extension || !allowedExtensions.includes(extension)) {+ throw new Error('Invalid file extension')+ }++ return true+}+```++#### Verification Steps+- [ ] All user inputs validated with schemas+- [ ] File uploads restricted (size, type, extension)+- [ ] No direct use of user input in queries+- [ ] Whitelist validation (not blacklist)+- [ ] Error messages don't leak sensitive info++### 3. SQL Injection Prevention++#### ❌ NEVER Concatenate SQL+```typescript+// DANGEROUS - SQL Injection vulnerability+const query = `SELECT * FROM users WHERE email = '${userEmail}'`+await db.query(query)+```++#### ✅ ALWAYS Use Parameterized Queries+```typescript+// Safe - parameterized query+const { data } = await supabase+ .from('users')+ .select('*')+ .eq('email', userEmail)++// Or with raw SQL+await db.query(+ 'SELECT * FROM users WHERE email = $1',+ [userEmail]+)+```++#### Verification Steps+- [ ] All database queries use parameterized queries+- [ ] No string concatenation in SQL+- [ ] ORM/query builder used correctly+- [ ] Supabase queries properly sanitized++### 4. Authentication & Authorization++#### JWT Token Handling+```typescript+// ❌ WRONG: localStorage (vulnerable to XSS)+localStorage.setItem('token', token)++// ✅ CORRECT: httpOnly cookies+res.setHeader('Set-Cookie',+ `token=${token}; HttpOnly; Secure; SameSite=Strict; Max-Age=3600`)+```++#### Authorization Checks+```typescript+export async function deleteUser(userId: string, requesterId: string) {+ // ALWAYS verify authorization first+ const requester = await db.users.findUnique({+ where: { id: requesterId }+ })++ if (requester.role !== 'admin') {+ return NextResponse.json(+ { error: 'Unauthorized' },+ { status: 403 }+ )+ }++ // Proceed with deletion+ await db.users.delete({ where: { id: userId } })+}+```++#### Row Level Security (Supabase)+```sql+-- Enable RLS on all tables+ALTER TABLE users ENABLE ROW LEVEL SECURITY;++-- Users can only view their own data+CREATE POLICY "Users view own data"+ ON users FOR SELECT+ USING (auth.uid() = id);++-- Users can only update their own data+CREATE POLICY "Users update own data"+ ON users FOR UPDATE+ USING (auth.uid() = id);+```++#### Verification Steps+- [ ] Tokens stored in httpOnly cookies (not localStorage)+- [ ] Authorization checks before sensitive operations+- [ ] Row Level Security enabled in Supabase+- [ ] Role-based access control implemented+- [ ] Session management secure++### 5. XSS Prevention++#### Sanitize HTML+```typescript+import DOMPurify from 'isomorphic-dompurify'++// ALWAYS sanitize user-provided HTML+function renderUserContent(html: string) {+ const clean = DOMPurify.sanitize(html, {+ ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'],+ ALLOWED_ATTR: []+ })+ return <div dangerouslySetInnerHTML={{ __html: clean }} />+}+```++#### Content Security Policy+```typescript+// next.config.js+const securityHeaders = [+ {+ key: 'Content-Security-Policy',+ value: `+ default-src 'self';+ script-src 'self' 'unsafe-eval' 'unsafe-inline';+ style-src 'self' 'unsafe-inline';+ img-src 'self' data: https:;+ font-src 'self';+ connect-src 'self' https://api.example.com;+ `.replace(/\s{2,}/g, ' ').trim()+ }+]+```++#### Verification Steps+- [ ] User-provided HTML sanitized+- [ ] CSP headers configured+- [ ] No unvalidated dynamic content rendering+- [ ] React's built-in XSS protection used++### 6. CSRF Protection++#### CSRF Tokens+```typescript+import { csrf } from '@/lib/csrf'++export async function POST(request: Request) {+ const token = request.headers.get('X-CSRF-Token')++ if (!csrf.verify(token)) {+ return NextResponse.json(+ { error: 'Invalid CSRF token' },+ { status: 403 }+ )+ }++ // Process request+}+```++#### SameSite Cookies+```typescript+res.setHeader('Set-Cookie',+ `session=${sessionId}; HttpOnly; Secure; SameSite=Strict`)+```++#### Verification Steps+- [ ] CSRF tokens on state-changing operations+- [ ] SameSite=Strict on all cookies+- [ ] Double-submit cookie pattern implemented++### 7. Rate Limiting++#### API Rate Limiting+```typescript+import rateLimit from 'express-rate-limit'++const limiter = rateLimit({+ windowMs: 15 * 60 * 1000, // 15 minutes+ max: 100, // 100 requests per window+ message: 'Too many requests'+})++// Apply to routes+app.use('/api/', limiter)+```++#### Expensive Operations+```typescript+// Aggressive rate limiting for searches+const searchLimiter = rateLimit({+ windowMs: 60 * 1000, // 1 minute+ max: 10, // 10 requests per minute+ message: 'Too many search requests'+})++app.use('/api/search', searchLimiter)+```++#### Verification Steps+- [ ] Rate limiting on all API endpoints+- [ ] Stricter limits on expensive operations+- [ ] IP-based rate limiting+- [ ] User-based rate limiting (authenticated)++### 8. Sensitive Data Exposure++#### Logging+```typescript+// ❌ WRONG: Logging sensitive data+console.log('User login:', { email, password })+console.log('Payment:', { cardNumber, cvv })++// ✅ CORRECT: Redact sensitive data+console.log('User login:', { email, userId })+console.log('Payment:', { last4: card.last4, userId })+```++#### Error Messages+```typescript+// ❌ WRONG: Exposing internal details+catch (error) {+ return NextResponse.json(+ { error: error.message, stack: error.stack },+ { status: 500 }+ )+}++// ✅ CORRECT: Generic error messages+catch (error) {+ console.error('Internal error:', error)+ return NextResponse.json(+ { error: 'An error occurred. Please try again.' },+ { status: 500 }+ )+}+```++#### Verification Steps+- [ ] No passwords, tokens, or secrets in logs+- [ ] Error messages generic for users+- [ ] Detailed errors only in server logs+- [ ] No stack traces exposed to users++### 9. Blockchain Security (Solana)++#### Wallet Verification+```typescript+import { verify } from '@solana/web3.js'++async function verifyWalletOwnership(+ publicKey: string,+ signature: string,+ message: string+) {+ try {+ const isValid = verify(+ Buffer.from(message),+ Buffer.from(signature, 'base64'),+ Buffer.from(publicKey, 'base64')+ )+ return isValid+ } catch (error) {+ return false+ }+}+```++#### Transaction Verification+```typescript+async function verifyTransaction(transaction: Transaction) {+ // Verify recipient+ if (transaction.to !== expectedRecipient) {+ throw new Error('Invalid recipient')+ }++ // Verify amount+ if (transaction.amount > maxAmount) {+ throw new Error('Amount exceeds limit')+ }++ // Verify user has sufficient balance+ const balance = await getBalance(transaction.from)+ if (balance < transaction.amount) {+ throw new Error('Insufficient balance')+ }++ return true+}+```++#### Verification Steps+- [ ] Wallet signatures verified+- [ ] Transaction details validated+- [ ] Balance checks before transactions+- [ ] No blind transaction signing++### 10. Dependency Security++#### Regular Updates+```bash+# Check for vulnerabilities+npm audit++# Fix automatically fixable issues+npm audit fix++# Update dependencies+npm update++# Check for outdated packages+npm outdated+```++#### Lock Files+```bash+# ALWAYS commit lock files+git add package-lock.json++# Use in CI/CD for reproducible builds+npm ci # Instead of npm install+```++#### Verification Steps+- [ ] Dependencies up to date+- [ ] No known vulnerabilities (npm audit clean)+- [ ] Lock files committed+- [ ] Dependabot enabled on GitHub+- [ ] Regular security updates++## Security Testing++### Automated Security Tests+```typescript+// Test authentication+test('requires authentication', async () => {+ const response = await fetch('/api/protected')+ expect(response.status).toBe(401)+})++// Test authorization+test('requires admin role', async () => {+ const response = await fetch('/api/admin', {+ headers: { Authorization: `Bearer ${userToken}` }+ })+ expect(response.status).toBe(403)+})++// Test input validation+test('rejects invalid input', async () => {+ const response = await fetch('/api/users', {+ method: 'POST',+ body: JSON.stringify({ email: 'not-an-email' })+ })+ expect(response.status).toBe(400)+})++// Test rate limiting+test('enforces rate limits', async () => {+ const requests = Array(101).fill(null).map(() =>+ fetch('/api/endpoint')+ )++ const responses = await Promise.all(requests)+ const tooManyRequests = responses.filter(r => r.status === 429)++ expect(tooManyRequests.length).toBeGreaterThan(0)+})+```++## Pre-Deployment Security Checklist++Before ANY production deployment:++- [ ] **Secrets**: No hardcoded secrets, all in env vars+- [ ] **Input Validation**: All user inputs validated+- [ ] **SQL Injection**: All queries parameterized+- [ ] **XSS**: User content sanitized+- [ ] **CSRF**: Protection enabled+- [ ] **Authentication**: Proper token handling+- [ ] **Authorization**: Role checks in place+- [ ] **Rate Limiting**: Enabled on all endpoints+- [ ] **HTTPS**: Enforced in production+- [ ] **Security Headers**: CSP, X-Frame-Options configured+- [ ] **Error Handling**: No sensitive data in errors+- [ ] **Logging**: No sensitive data logged+- [ ] **Dependencies**: Up to date, no vulnerabilities+- [ ] **Row Level Security**: Enabled in Supabase+- [ ] **CORS**: Properly configured+- [ ] **File Uploads**: Validated (size, type)+- [ ] **Wallet Signatures**: Verified (if blockchain)++## Resources++- [OWASP Top 10](https://owasp.org/www-project-top-ten/)+- [Next.js Security](https://nextjs.org/docs/security)+- [Supabase Security](https://supabase.com/docs/guides/auth)+- [Web Security Academy](https://portswigger.net/web-security)++---++**Remember**: Security is not optional. One vulnerability can compromise the entire platform. When in doubt, err on the side of caution.diff --git a/.agents/skills/security-review/agents/openai.yaml b/.agents/skills/security-review/agents/openai.yamlnew file mode 100644index 000000000..9af830238--- /dev/null+++ b/.agents/skills/security-review/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Security Review"+ short_description: "Comprehensive security checklist and vulnerability detection"+ brand_color: "#EF4444"+ default_prompt: "Run security checklist: secrets, input validation, injection prevention"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/strategic-compact/SKILL.md b/.agents/skills/strategic-compact/SKILL.mdnew file mode 100644index 000000000..67bbb31ee--- /dev/null+++ b/.agents/skills/strategic-compact/SKILL.md@@ -0,0 +1,103 @@+---+name: strategic-compact+description: Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.+origin: ECC+---++# Strategic Compact Skill++Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.++## When to Activate++- Running long sessions that approach context limits (200K+ tokens)+- Working on multi-phase tasks (research → plan → implement → test)+- Switching between unrelated tasks within the same session+- After completing a major milestone and starting new work+- When responses slow down or become less coherent (context pressure)++## Why Strategic Compaction?++Auto-compaction triggers at arbitrary points:+- Often mid-task, losing important context+- No awareness of logical task boundaries+- Can interrupt complex multi-step operations++Strategic compaction at logical boundaries:+- **After exploration, before execution** — Compact research context, keep implementation plan+- **After completing a milestone** — Fresh start for next phase+- **Before major context shifts** — Clear exploration context before different task++## How It Works++The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:++1. **Tracks tool calls** — Counts tool invocations in session+2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)+3. **Periodic reminders** — Reminds every 25 calls after threshold++## Hook Setup++Add to your `~/.claude/settings.json`:++```json+{+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Edit",+ "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]+ },+ {+ "matcher": "Write",+ "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]+ }+ ]+ }+}+```++## Configuration++Environment variables:+- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)++## Compaction Decision Guide++Use this table to decide when to compact:++| Phase Transition | Compact? | Why |+|-----------------|----------|-----|+| Research → Planning | Yes | Research context is bulky; plan is the distilled output |+| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |+| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |+| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |+| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |+| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |++## What Survives Compaction++Understanding what persists helps you compact with confidence:++| Persists | Lost |+|----------|------|+| CLAUDE.md instructions | Intermediate reasoning and analysis |+| TodoWrite task list | File contents you previously read |+| Memory files (`~/.claude/memory/`) | Multi-step conversation context |+| Git state (commits, branches) | Tool call history and counts |+| Files on disk | Nuanced user preferences stated verbally |++## Best Practices++1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh+2. **Compact after debugging** — Clear error-resolution context before continuing+3. **Don't compact mid-implementation** — Preserve context for related changes+4. **Read the suggestion** — The hook tells you *when*, you decide *if*+5. **Write before compacting** — Save important context to files or memory before compacting+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`++## Related++- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section+- Memory persistence hooks — For state that survives compaction+- `continuous-learning` skill — Extracts patterns before session endsdiff --git a/.agents/skills/strategic-compact/agents/openai.yaml b/.agents/skills/strategic-compact/agents/openai.yamlnew file mode 100644index 000000000..19ecabf8a--- /dev/null+++ b/.agents/skills/strategic-compact/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Strategic Compact"+ short_description: "Context management via strategic compaction"+ brand_color: "#14B8A6"+ default_prompt: "Suggest task boundary compaction for context management"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/tdd-workflow/SKILL.md b/.agents/skills/tdd-workflow/SKILL.mdnew file mode 100644index 000000000..90c0a6df6--- /dev/null+++ b/.agents/skills/tdd-workflow/SKILL.md@@ -0,0 +1,410 @@+---+name: tdd-workflow+description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.+origin: ECC+---++# Test-Driven Development Workflow++This skill ensures all code development follows TDD principles with comprehensive test coverage.++## When to Activate++- Writing new features or functionality+- Fixing bugs or issues+- Refactoring existing code+- Adding API endpoints+- Creating new components++## Core Principles++### 1. Tests BEFORE Code+ALWAYS write tests first, then implement code to make tests pass.++### 2. Coverage Requirements+- Minimum 80% coverage (unit + integration + E2E)+- All edge cases covered+- Error scenarios tested+- Boundary conditions verified++### 3. Test Types++#### Unit Tests+- Individual functions and utilities+- Component logic+- Pure functions+- Helpers and utilities++#### Integration Tests+- API endpoints+- Database operations+- Service interactions+- External API calls++#### E2E Tests (Playwright)+- Critical user flows+- Complete workflows+- Browser automation+- UI interactions++## TDD Workflow Steps++### Step 1: Write User Journeys+```+As a [role], I want to [action], so that [benefit]++Example:+As a user, I want to search for markets semantically,+so that I can find relevant markets even without exact keywords.+```++### Step 2: Generate Test Cases+For each user journey, create comprehensive test cases:++```typescript+describe('Semantic Search', () => {+ it('returns relevant markets for query', async () => {+ // Test implementation+ })++ it('handles empty query gracefully', async () => {+ // Test edge case+ })++ it('falls back to substring search when Redis unavailable', async () => {+ // Test fallback behavior+ })++ it('sorts results by similarity score', async () => {+ // Test sorting logic+ })+})+```++### Step 3: Run Tests (They Should Fail)+```bash+npm test+# Tests should fail - we haven't implemented yet+```++### Step 4: Implement Code+Write minimal code to make tests pass:++```typescript+// Implementation guided by tests+export async function searchMarkets(query: string) {+ // Implementation here+}+```++### Step 5: Run Tests Again+```bash+npm test+# Tests should now pass+```++### Step 6: Refactor+Improve code quality while keeping tests green:+- Remove duplication+- Improve naming+- Optimize performance+- Enhance readability++### Step 7: Verify Coverage+```bash+npm run test:coverage+# Verify 80%+ coverage achieved+```++## Testing Patterns++### Unit Test Pattern (Jest/Vitest)+```typescript+import { render, screen, fireEvent } from '@testing-library/react'+import { Button } from './Button'++describe('Button Component', () => {+ it('renders with correct text', () => {+ render(<Button>Click me</Button>)+ expect(screen.getByText('Click me')).toBeInTheDocument()+ })++ it('calls onClick when clicked', () => {+ const handleClick = jest.fn()+ render(<Button onClick={handleClick}>Click</Button>)++ fireEvent.click(screen.getByRole('button'))++ expect(handleClick).toHaveBeenCalledTimes(1)+ })++ it('is disabled when disabled prop is true', () => {+ render(<Button disabled>Click</Button>)+ expect(screen.getByRole('button')).toBeDisabled()+ })+})+```++### API Integration Test Pattern+```typescript+import { NextRequest } from 'next/server'+import { GET } from './route'++describe('GET /api/markets', () => {+ it('returns markets successfully', async () => {+ const request = new NextRequest('http://localhost/api/markets')+ const response = await GET(request)+ const data = await response.json()++ expect(response.status).toBe(200)+ expect(data.success).toBe(true)+ expect(Array.isArray(data.data)).toBe(true)+ })++ it('validates query parameters', async () => {+ const request = new NextRequest('http://localhost/api/markets?limit=invalid')+ const response = await GET(request)++ expect(response.status).toBe(400)+ })++ it('handles database errors gracefully', async () => {+ // Mock database failure+ const request = new NextRequest('http://localhost/api/markets')+ // Test error handling+ })+})+```++### E2E Test Pattern (Playwright)+```typescript+import { test, expect } from '@playwright/test'++test('user can search and filter markets', async ({ page }) => {+ // Navigate to markets page+ await page.goto('/')+ await page.click('a[href="/markets"]')++ // Verify page loaded+ await expect(page.locator('h1')).toContainText('Markets')++ // Search for markets+ await page.fill('input[placeholder="Search markets"]', 'election')++ // Wait for debounce and results+ await page.waitForTimeout(600)++ // Verify search results displayed+ const results = page.locator('[data-testid="market-card"]')+ await expect(results).toHaveCount(5, { timeout: 5000 })++ // Verify results contain search term+ const firstResult = results.first()+ await expect(firstResult).toContainText('election', { ignoreCase: true })++ // Filter by status+ await page.click('button:has-text("Active")')++ // Verify filtered results+ await expect(results).toHaveCount(3)+})++test('user can create a new market', async ({ page }) => {+ // Login first+ await page.goto('/creator-dashboard')++ // Fill market creation form+ await page.fill('input[name="name"]', 'Test Market')+ await page.fill('textarea[name="description"]', 'Test description')+ await page.fill('input[name="endDate"]', '2025-12-31')++ // Submit form+ await page.click('button[type="submit"]')++ // Verify success message+ await expect(page.locator('text=Market created successfully')).toBeVisible()++ // Verify redirect to market page+ await expect(page).toHaveURL(/\/markets\/test-market/)+})+```++## Test File Organization++```+src/+├── components/+│ ├── Button/+│ │ ├── Button.tsx+│ │ ├── Button.test.tsx # Unit tests+│ │ └── Button.stories.tsx # Storybook+│ └── MarketCard/+│ ├── MarketCard.tsx+│ └── MarketCard.test.tsx+├── app/+│ └── api/+│ └── markets/+│ ├── route.ts+│ └── route.test.ts # Integration tests+└── e2e/+ ├── markets.spec.ts # E2E tests+ ├── trading.spec.ts+ └── auth.spec.ts+```++## Mocking External Services++### Supabase Mock+```typescript+jest.mock('@/lib/supabase', () => ({+ supabase: {+ from: jest.fn(() => ({+ select: jest.fn(() => ({+ eq: jest.fn(() => Promise.resolve({+ data: [{ id: 1, name: 'Test Market' }],+ error: null+ }))+ }))+ }))+ }+}))+```++### Redis Mock+```typescript+jest.mock('@/lib/redis', () => ({+ searchMarketsByVector: jest.fn(() => Promise.resolve([+ { slug: 'test-market', similarity_score: 0.95 }+ ])),+ checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))+}))+```++### OpenAI Mock+```typescript+jest.mock('@/lib/openai', () => ({+ generateEmbedding: jest.fn(() => Promise.resolve(+ new Array(1536).fill(0.1) // Mock 1536-dim embedding+ ))+}))+```++## Test Coverage Verification++### Run Coverage Report+```bash+npm run test:coverage+```++### Coverage Thresholds+```json+{+ "jest": {+ "coverageThresholds": {+ "global": {+ "branches": 80,+ "functions": 80,+ "lines": 80,+ "statements": 80+ }+ }+ }+}+```++## Common Testing Mistakes to Avoid++### ❌ WRONG: Testing Implementation Details+```typescript+// Don't test internal state+expect(component.state.count).toBe(5)+```++### ✅ CORRECT: Test User-Visible Behavior+```typescript+// Test what users see+expect(screen.getByText('Count: 5')).toBeInTheDocument()+```++### ❌ WRONG: Brittle Selectors+```typescript+// Breaks easily+await page.click('.css-class-xyz')+```++### ✅ CORRECT: Semantic Selectors+```typescript+// Resilient to changes+await page.click('button:has-text("Submit")')+await page.click('[data-testid="submit-button"]')+```++### ❌ WRONG: No Test Isolation+```typescript+// Tests depend on each other+test('creates user', () => { /* ... */ })+test('updates same user', () => { /* depends on previous test */ })+```++### ✅ CORRECT: Independent Tests+```typescript+// Each test sets up its own data+test('creates user', () => {+ const user = createTestUser()+ // Test logic+})++test('updates user', () => {+ const user = createTestUser()+ // Update logic+})+```++## Continuous Testing++### Watch Mode During Development+```bash+npm test -- --watch+# Tests run automatically on file changes+```++### Pre-Commit Hook+```bash+# Runs before every commit+npm test && npm run lint+```++### CI/CD Integration+```yaml+# GitHub Actions+- name: Run Tests+ run: npm test -- --coverage+- name: Upload Coverage+ uses: codecov/codecov-action@v3+```++## Best Practices++1. **Write Tests First** - Always TDD+2. **One Assert Per Test** - Focus on single behavior+3. **Descriptive Test Names** - Explain what's tested+4. **Arrange-Act-Assert** - Clear test structure+5. **Mock External Dependencies** - Isolate unit tests+6. **Test Edge Cases** - Null, undefined, empty, large+7. **Test Error Paths** - Not just happy paths+8. **Keep Tests Fast** - Unit tests < 50ms each+9. **Clean Up After Tests** - No side effects+10. **Review Coverage Reports** - Identify gaps++## Success Metrics++- 80%+ code coverage achieved+- All tests passing (green)+- No skipped or disabled tests+- Fast test execution (< 30s for unit tests)+- E2E tests cover critical user flows+- Tests catch bugs before production++---++**Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.diff --git a/.agents/skills/tdd-workflow/agents/openai.yaml b/.agents/skills/tdd-workflow/agents/openai.yamlnew file mode 100644index 000000000..425c7d1c5--- /dev/null+++ b/.agents/skills/tdd-workflow/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "TDD Workflow"+ short_description: "Test-driven development with 80%+ coverage"+ brand_color: "#22C55E"+ default_prompt: "Follow TDD: write tests first, implement, verify 80%+ coverage"+policy:+ allow_implicit_invocation: truediff --git a/.agents/skills/verification-loop/SKILL.md b/.agents/skills/verification-loop/SKILL.mdnew file mode 100644index 000000000..1933545d5--- /dev/null+++ b/.agents/skills/verification-loop/SKILL.md@@ -0,0 +1,126 @@+---+name: verification-loop+description: "A comprehensive verification system for Claude Code sessions."+origin: ECC+---++# Verification Loop Skill++A comprehensive verification system for Claude Code sessions.++## When to Use++Invoke this skill:+- After completing a feature or significant code change+- Before creating a PR+- When you want to ensure quality gates pass+- After refactoring++## Verification Phases++### Phase 1: Build Verification+```bash+# Check if project builds+npm run build 2>&1 | tail -20+# OR+pnpm build 2>&1 | tail -20+```++If build fails, STOP and fix before continuing.++### Phase 2: Type Check+```bash+# TypeScript projects+npx tsc --noEmit 2>&1 | head -30++# Python projects+pyright . 2>&1 | head -30+```++Report all type errors. Fix critical ones before continuing.++### Phase 3: Lint Check+```bash+# JavaScript/TypeScript+npm run lint 2>&1 | head -30++# Python+ruff check . 2>&1 | head -30+```++### Phase 4: Test Suite+```bash+# Run tests with coverage+npm run test -- --coverage 2>&1 | tail -50++# Check coverage threshold+# Target: 80% minimum+```++Report:+- Total tests: X+- Passed: X+- Failed: X+- Coverage: X%++### Phase 5: Security Scan+```bash+# Check for secrets+grep -rn "sk-" --include="*.ts" --include="*.js" . 2>/dev/null | head -10+grep -rn "api_key" --include="*.ts" --include="*.js" . 2>/dev/null | head -10++# Check for console.log+grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10+```++### Phase 6: Diff Review+```bash+# Show what changed+git diff --stat+git diff HEAD~1 --name-only+```++Review each changed file for:+- Unintended changes+- Missing error handling+- Potential edge cases++## Output Format++After running all phases, produce a verification report:++```+VERIFICATION REPORT+==================++Build: [PASS/FAIL]+Types: [PASS/FAIL] (X errors)+Lint: [PASS/FAIL] (X warnings)+Tests: [PASS/FAIL] (X/Y passed, Z% coverage)+Security: [PASS/FAIL] (X issues)+Diff: [X files changed]++Overall: [READY/NOT READY] for PR++Issues to Fix:+1. ...+2. ...+```++## Continuous Mode++For long sessions, run verification every 15 minutes or after major changes:++```markdown+Set a mental checkpoint:+- After completing each function+- After finishing a component+- Before moving to next task++Run: /verify+```++## Integration with Hooks++This skill complements PostToolUse hooks but provides deeper verification.+Hooks catch issues immediately; this skill provides comprehensive review.diff --git a/.agents/skills/verification-loop/agents/openai.yaml b/.agents/skills/verification-loop/agents/openai.yamlnew file mode 100644index 000000000..644a9ad53--- /dev/null+++ b/.agents/skills/verification-loop/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Verification Loop"+ short_description: "Build, test, lint, typecheck verification"+ brand_color: "#10B981"+ default_prompt: "Run verification: build, test, lint, typecheck, security"+policy:+ allow_implicit_invocation: truediff --git a/.codex/AGENTS.md b/.codex/AGENTS.mdnew file mode 100644index 000000000..97fdd57aa--- /dev/null+++ b/.codex/AGENTS.md@@ -0,0 +1,55 @@+# ECC for Codex CLI++This supplements the root `AGENTS.md` with Codex-specific guidance.++## Model Recommendations++| Task Type | Recommended Model |+|-----------|------------------|+| Routine coding, tests, formatting | o4-mini |+| Complex features, architecture | o3 |+| Debugging, refactoring | o4-mini |+| Security review | o3 |++## Skills Discovery++Skills are auto-loaded from `.agents/skills/`. Each skill contains:+- `SKILL.md` — Detailed instructions and workflow+- `agents/openai.yaml` — Codex interface metadata++Available skills:+- tdd-workflow — Test-driven development with 80%+ coverage+- security-review — Comprehensive security checklist+- coding-standards — Universal coding standards+- frontend-patterns — React/Next.js patterns+- backend-patterns — API design, database, caching+- e2e-testing — Playwright E2E tests+- eval-harness — Eval-driven development+- strategic-compact — Context management+- api-design — REST API design patterns+- verification-loop — Build, test, lint, typecheck, security++## MCP Servers++Configure in `~/.codex/config.toml` under `[mcp_servers]`. See `.codex/config.toml` for reference configuration with GitHub, Context7, Memory, and Sequential Thinking servers.++## Key Differences from Claude Code++| Feature | Claude Code | Codex CLI |+|---------|------------|-----------|+| Hooks | 8+ event types | Not yet supported |+| Context file | CLAUDE.md + AGENTS.md | AGENTS.md only |+| Skills | Skills loaded via plugin | `.agents/skills/` directory |+| Commands | `/slash` commands | Instruction-based |+| Agents | Subagent Task tool | Single agent model |+| Security | Hook-based enforcement | Instruction + sandbox |+| MCP | Full support | Command-based only |++## Security Without Hooks++Since Codex lacks hooks, security enforcement is instruction-based:+1. Always validate inputs at system boundaries+2. Never hardcode secrets — use environment variables+3. Run `npm audit` / `pip audit` before committing+4. Review `git diff` before every push+5. Use `sandbox_mode = "workspace-write"` in configdiff --git a/.codex/config.toml b/.codex/config.tomlnew file mode 100644index 000000000..87d9747aa--- /dev/null+++ b/.codex/config.toml@@ -0,0 +1,80 @@+# Everything Claude Code (ECC) — Codex CLI Reference Configuration+#+# Copy this file to ~/.codex/config.toml to apply globally.+# Or keep it in your project root for project-level config.+#+# Docs: https://github.com/openai/codex++# Model selection+model = "o4-mini"+model_provider = "openai"++# Permissions+[permissions]+# "untrusted" = no writes, "on-request" = ask per action, "never" = full auto+approval_policy = "on-request"+# "off", "workspace-read", "workspace-write", "danger-full-access"+sandbox_mode = "workspace-write"++# Notifications (macOS)+[notify]+command = "terminal-notifier -title 'Codex ECC' -message 'Task completed!' -sound default"+on_complete = true++# History - persistent instructions applied to every session+[history]+# These are prepended to every conversation+persistent_instructions = """+Follow ECC principles:+1. Test-Driven Development (TDD) - write tests first, 80%+ coverage required+2. Immutability - always create new objects, never mutate+3. Security-First - validate all inputs, no hardcoded secrets+4. Conventional commits: feat|fix|refactor|docs|test|chore|perf|ci: description+5. File organization: many small files (200-400 lines, 800 max)+6. Error handling: handle at every level, never swallow errors+7. Input validation: schema-based validation at system boundaries+"""++# MCP Servers+# Codex supports command-based MCP servers+[mcp_servers.github]+command = "npx"+args = ["-y", "@modelcontextprotocol/server-github"]++[mcp_servers.context7]+command = "npx"+args = ["-y", "@upstash/context7-mcp@latest"]++[mcp_servers.memory]+command = "npx"+args = ["-y", "@modelcontextprotocol/server-memory"]++[mcp_servers.sequential-thinking]+command = "npx"+args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]++# Additional MCP servers (uncomment as needed):+# [mcp_servers.supabase]+# command = "npx"+# args = ["-y", "supabase-mcp-server@latest", "--read-only"]+#+# [mcp_servers.firecrawl]+# command = "npx"+# args = ["-y", "firecrawl-mcp"]+#+# [mcp_servers.railway]+# command = "npx"+# args = ["-y", "@anthropic/railway-mcp"]++# Features+[features]+web_search_request = true++# Profiles — switch with CODEX_PROFILE=<name>+[profiles.strict]+approval_policy = "on-request"+sandbox_mode = "workspace-read"++[profiles.yolo]+approval_policy = "never"+sandbox_mode = "workspace-write"diff --git a/.cursor/hooks.json b/.cursor/hooks.jsonnew file mode 100644index 000000000..f46121b84--- /dev/null+++ b/.cursor/hooks.json@@ -0,0 +1,109 @@+{+ "hooks": {+ "sessionStart": [+ {+ "command": "node .cursor/hooks/session-start.js",+ "event": "sessionStart",+ "description": "Load previous context and detect environment"+ }+ ],+ "sessionEnd": [+ {+ "command": "node .cursor/hooks/session-end.js",+ "event": "sessionEnd",+ "description": "Persist session state and evaluate patterns"+ }+ ],+ "beforeShellExecution": [+ {+ "command": "node .cursor/hooks/before-shell-execution.js",+ "event": "beforeShellExecution",+ "description": "Tmux dev server blocker, tmux reminder, git push review"+ }+ ],+ "afterShellExecution": [+ {+ "command": "node .cursor/hooks/after-shell-execution.js",+ "event": "afterShellExecution",+ "description": "PR URL logging, build analysis"+ }+ ],+ "afterFileEdit": [+ {+ "command": "node .cursor/hooks/after-file-edit.js",+ "event": "afterFileEdit",+ "description": "Auto-format, TypeScript check, console.log warning"+ }+ ],+ "beforeMCPExecution": [+ {+ "command": "node .cursor/hooks/before-mcp-execution.js",+ "event": "beforeMCPExecution",+ "description": "MCP audit logging and untrusted server warning"+ }+ ],+ "afterMCPExecution": [+ {+ "command": "node .cursor/hooks/after-mcp-execution.js",+ "event": "afterMCPExecution",+ "description": "MCP result logging"+ }+ ],+ "beforeReadFile": [+ {+ "command": "node .cursor/hooks/before-read-file.js",+ "event": "beforeReadFile",+ "description": "Warn when reading sensitive files (.env, .key, .pem)"+ }+ ],+ "beforeSubmitPrompt": [+ {+ "command": "node .cursor/hooks/before-submit-prompt.js",+ "event": "beforeSubmitPrompt",+ "description": "Detect secrets in prompts (sk-, ghp_, AKIA patterns)"+ }+ ],+ "subagentStart": [+ {+ "command": "node .cursor/hooks/subagent-start.js",+ "event": "subagentStart",+ "description": "Log agent spawning for observability"+ }+ ],+ "subagentStop": [+ {+ "command": "node .cursor/hooks/subagent-stop.js",+ "event": "subagentStop",+ "description": "Log agent completion"+ }+ ],+ "beforeTabFileRead": [+ {+ "command": "node .cursor/hooks/before-tab-file-read.js",+ "event": "beforeTabFileRead",+ "description": "Block Tab from reading secrets (.env, .key, .pem, credentials)"+ }+ ],+ "afterTabFileEdit": [+ {+ "command": "node .cursor/hooks/after-tab-file-edit.js",+ "event": "afterTabFileEdit",+ "description": "Auto-format Tab edits"+ }+ ],+ "preCompact": [+ {+ "command": "node .cursor/hooks/pre-compact.js",+ "event": "preCompact",+ "description": "Save state before context compaction"+ }+ ],+ "stop": [+ {+ "command": "node .cursor/hooks/stop.js",+ "event": "stop",+ "description": "Console.log audit on all modified files"+ }+ ]+ }+}diff --git a/.cursor/hooks/adapter.js b/.cursor/hooks/adapter.jsnew file mode 100644index 000000000..23ba4723e--- /dev/null+++ b/.cursor/hooks/adapter.js@@ -0,0 +1,62 @@+#!/usr/bin/env node+/**+ * Cursor-to-Claude Code Hook Adapter+ * Transforms Cursor stdin JSON to Claude Code hook format,+ * then delegates to existing scripts/hooks/*.js+ */++const { execFileSync } = require('child_process');+const path = require('path');++const MAX_STDIN = 1024 * 1024;++function readStdin() {+ return new Promise((resolve) => {+ let data = '';+ process.stdin.setEncoding('utf8');+ process.stdin.on('data', chunk => {+ if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);+ });+ process.stdin.on('end', () => resolve(data));+ });+}++function getPluginRoot() {+ return path.resolve(__dirname, '..', '..');+}++function transformToClaude(cursorInput, overrides = {}) {+ return {+ tool_input: {+ command: cursorInput.command || cursorInput.args?.command || '',+ file_path: cursorInput.path || cursorInput.file || '',+ ...overrides.tool_input,+ },+ tool_output: {+ output: cursorInput.output || cursorInput.result || '',+ ...overrides.tool_output,+ },+ _cursor: {+ conversation_id: cursorInput.conversation_id,+ hook_event_name: cursorInput.hook_event_name,+ workspace_roots: cursorInput.workspace_roots,+ model: cursorInput.model,+ },+ };+}++function runExistingHook(scriptName, stdinData) {+ const scriptPath = path.join(getPluginRoot(), 'scripts', 'hooks', scriptName);+ try {+ execFileSync('node', [scriptPath], {+ input: typeof stdinData === 'string' ? stdinData : JSON.stringify(stdinData),+ stdio: ['pipe', 'pipe', 'pipe'],+ timeout: 15000,+ cwd: process.cwd(),+ });+ } catch (e) {+ if (e.status === 2) process.exit(2); // Forward blocking exit code+ }+}++module.exports = { readStdin, getPluginRoot, transformToClaude, runExistingHook };diff --git a/.cursor/hooks/after-file-edit.js b/.cursor/hooks/after-file-edit.jsnew file mode 100644index 000000000..f4c39e498--- /dev/null+++ b/.cursor/hooks/after-file-edit.js@@ -0,0 +1,17 @@+#!/usr/bin/env node+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const claudeInput = transformToClaude(input, {+ tool_input: { file_path: input.path || input.file || '' }+ });+ const claudeStr = JSON.stringify(claudeInput);++ // Run format, typecheck, and console.log warning sequentially+ runExistingHook('post-edit-format.js', claudeStr);+ runExistingHook('post-edit-typecheck.js', claudeStr);+ runExistingHook('post-edit-console-warn.js', claudeStr);+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/after-mcp-execution.js b/.cursor/hooks/after-mcp-execution.jsnew file mode 100644index 000000000..d09a780ed--- /dev/null+++ b/.cursor/hooks/after-mcp-execution.js@@ -0,0 +1,12 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const server = input.server || input.mcp_server || 'unknown';+ const tool = input.tool || input.mcp_tool || 'unknown';+ const success = input.error ? 'FAILED' : 'OK';+ console.error(`[ECC] MCP result: ${server}/${tool} - ${success}`);+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/after-shell-execution.js b/.cursor/hooks/after-shell-execution.jsnew file mode 100644index 000000000..bdccc9730--- /dev/null+++ b/.cursor/hooks/after-shell-execution.js@@ -0,0 +1,26 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const cmd = input.command || '';+ const output = input.output || input.result || '';++ // PR creation logging+ if (/gh pr create/.test(cmd)) {+ const m = output.match(/https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/);+ if (m) {+ console.error('[ECC] PR created: ' + m[0]);+ const repo = m[0].replace(/https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/\d+/, '$1');+ const pr = m[0].replace(/.+\/pull\/(\d+)/, '$1');+ console.error('[ECC] To review: gh pr review ' + pr + ' --repo ' + repo);+ }+ }++ // Build completion notice+ if (/(npm run build|pnpm build|yarn build)/.test(cmd)) {+ console.error('[ECC] Build completed');+ }+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/after-tab-file-edit.js b/.cursor/hooks/after-tab-file-edit.jsnew file mode 100644index 000000000..355876c05--- /dev/null+++ b/.cursor/hooks/after-tab-file-edit.js@@ -0,0 +1,12 @@+#!/usr/bin/env node+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const claudeInput = transformToClaude(input, {+ tool_input: { file_path: input.path || input.file || '' }+ });+ runExistingHook('post-edit-format.js', JSON.stringify(claudeInput));+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/before-mcp-execution.js b/.cursor/hooks/before-mcp-execution.jsnew file mode 100644index 000000000..38c56c249--- /dev/null+++ b/.cursor/hooks/before-mcp-execution.js@@ -0,0 +1,11 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const server = input.server || input.mcp_server || 'unknown';+ const tool = input.tool || input.mcp_tool || 'unknown';+ console.error(`[ECC] MCP invocation: ${server}/${tool}`);+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/before-read-file.js b/.cursor/hooks/before-read-file.jsnew file mode 100644index 000000000..e221530c3--- /dev/null+++ b/.cursor/hooks/before-read-file.js@@ -0,0 +1,13 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const filePath = input.path || input.file || '';+ if (/\.(env|key|pem)$|\.env\.|credentials|secret/i.test(filePath)) {+ console.error('[ECC] WARNING: Reading sensitive file: ' + filePath);+ console.error('[ECC] Ensure this data is not exposed in outputs');+ }+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/before-shell-execution.js b/.cursor/hooks/before-shell-execution.jsnew file mode 100644index 000000000..bb5448d97--- /dev/null+++ b/.cursor/hooks/before-shell-execution.js@@ -0,0 +1,27 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const cmd = input.command || '';++ // 1. Block dev server outside tmux+ if (process.platform !== 'win32' && /(npm run dev\b|pnpm( run)? dev\b|yarn dev\b|bun run dev\b)/.test(cmd)) {+ console.error('[ECC] BLOCKED: Dev server must run in tmux for log access');+ console.error('[ECC] Use: tmux new-session -d -s dev "npm run dev"');+ process.exit(2);+ }++ // 2. Tmux reminder for long-running commands+ if (process.platform !== 'win32' && !process.env.TMUX &&+ /(npm (install|test)|pnpm (install|test)|yarn (install|test)?|bun (install|test)|cargo build|make\b|docker\b|pytest|vitest|playwright)/.test(cmd)) {+ console.error('[ECC] Consider running in tmux for session persistence');+ }++ // 3. Git push review reminder+ if (/git push/.test(cmd)) {+ console.error('[ECC] Review changes before push: git diff origin/main...HEAD');+ }+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/before-submit-prompt.js b/.cursor/hooks/before-submit-prompt.jsnew file mode 100644index 000000000..f48426ae5--- /dev/null+++ b/.cursor/hooks/before-submit-prompt.js@@ -0,0 +1,23 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const prompt = input.prompt || input.content || input.message || '';+ const secretPatterns = [+ /sk-[a-zA-Z0-9]{20,}/, // OpenAI API keys+ /ghp_[a-zA-Z0-9]{36,}/, // GitHub personal access tokens+ /AKIA[A-Z0-9]{16}/, // AWS access keys+ /xox[bpsa]-[a-zA-Z0-9-]+/, // Slack tokens+ /-----BEGIN (RSA |EC )?PRIVATE KEY-----/, // Private keys+ ];+ for (const pattern of secretPatterns) {+ if (pattern.test(prompt)) {+ console.error('[ECC] WARNING: Potential secret detected in prompt!');+ console.error('[ECC] Remove secrets before submitting. Use environment variables instead.');+ break;+ }+ }+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/before-tab-file-read.js b/.cursor/hooks/before-tab-file-read.jsnew file mode 100644index 000000000..f4ea79a49--- /dev/null+++ b/.cursor/hooks/before-tab-file-read.js@@ -0,0 +1,13 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const filePath = input.path || input.file || '';+ if (/\.(env|key|pem)$|\.env\.|credentials|secret/i.test(filePath)) {+ console.error('[ECC] BLOCKED: Tab cannot read sensitive file: ' + filePath);+ process.exit(2);+ }+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/pre-compact.js b/.cursor/hooks/pre-compact.jsnew file mode 100644index 000000000..1b2156e1d--- /dev/null+++ b/.cursor/hooks/pre-compact.js@@ -0,0 +1,7 @@+#!/usr/bin/env node+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');+readStdin().then(raw => {+ const claudeInput = JSON.parse(raw || '{}');+ runExistingHook('pre-compact.js', transformToClaude(claudeInput));+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/session-end.js b/.cursor/hooks/session-end.jsnew file mode 100644index 000000000..5b7592879--- /dev/null+++ b/.cursor/hooks/session-end.js@@ -0,0 +1,9 @@+#!/usr/bin/env node+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');+readStdin().then(raw => {+ const input = JSON.parse(raw);+ const claudeInput = transformToClaude(input);+ runExistingHook('session-end.js', claudeInput);+ runExistingHook('evaluate-session.js', claudeInput);+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/session-start.js b/.cursor/hooks/session-start.jsnew file mode 100644index 000000000..bdd9121a5--- /dev/null+++ b/.cursor/hooks/session-start.js@@ -0,0 +1,8 @@+#!/usr/bin/env node+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');+readStdin().then(raw => {+ const input = JSON.parse(raw);+ const claudeInput = transformToClaude(input);+ runExistingHook('session-start.js', claudeInput);+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/stop.js b/.cursor/hooks/stop.jsnew file mode 100644index 000000000..d2bbbc3c6--- /dev/null+++ b/.cursor/hooks/stop.js@@ -0,0 +1,7 @@+#!/usr/bin/env node+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');+readStdin().then(raw => {+ const claudeInput = JSON.parse(raw || '{}');+ runExistingHook('check-console-log.js', transformToClaude(claudeInput));+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/subagent-start.js b/.cursor/hooks/subagent-start.jsnew file mode 100644index 000000000..c03c9cd50--- /dev/null+++ b/.cursor/hooks/subagent-start.js@@ -0,0 +1,10 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const agent = input.agent_name || input.agent || 'unknown';+ console.error(`[ECC] Agent spawned: ${agent}`);+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/hooks/subagent-stop.js b/.cursor/hooks/subagent-stop.jsnew file mode 100644index 000000000..d6cf681b1--- /dev/null+++ b/.cursor/hooks/subagent-stop.js@@ -0,0 +1,10 @@+#!/usr/bin/env node+const { readStdin } = require('./adapter');+readStdin().then(raw => {+ try {+ const input = JSON.parse(raw);+ const agent = input.agent_name || input.agent || 'unknown';+ console.error(`[ECC] Agent completed: ${agent}`);+ } catch {}+ process.stdout.write(raw);+}).catch(() => process.exit(0));diff --git a/.cursor/rules/common-agents.md b/.cursor/rules/common-agents.mdnew file mode 100644index 000000000..c5b17463e--- /dev/null+++ b/.cursor/rules/common-agents.md@@ -0,0 +1,53 @@+---+description: "Agent orchestration: available agents, parallel execution, multi-perspective analysis"+alwaysApply: true+---+# Agent Orchestration++## Available Agents++Located in `~/.claude/agents/`:++| Agent | Purpose | When to Use |+|-------|---------|-------------|+| planner | Implementation planning | Complex features, refactoring |+| architect | System design | Architectural decisions |+| tdd-guide | Test-driven development | New features, bug fixes |+| code-reviewer | Code review | After writing code |+| security-reviewer | Security analysis | Before commits |+| build-error-resolver | Fix build errors | When build fails |+| e2e-runner | E2E testing | Critical user flows |+| refactor-cleaner | Dead code cleanup | Code maintenance |+| doc-updater | Documentation | Updating docs |++## Immediate Agent Usage++No user prompt needed:+1. Complex feature requests - Use **planner** agent+2. Code just written/modified - Use **code-reviewer** agent+3. Bug fix or new feature - Use **tdd-guide** agent+4. Architectural decision - Use **architect** agent++## Parallel Task Execution++ALWAYS use parallel Task execution for independent operations:++```markdown+# GOOD: Parallel execution+Launch 3 agents in parallel:+1. Agent 1: Security analysis of auth module+2. Agent 2: Performance review of cache system+3. Agent 3: Type checking of utilities++# BAD: Sequential when unnecessary+First agent 1, then agent 2, then agent 3+```++## Multi-Perspective Analysis++For complex problems, use split role sub-agents:+- Factual reviewer+- Senior engineer+- Security expert+- Consistency reviewer+- Redundancy checkerdiff --git a/.cursor/rules/common-coding-style.md b/.cursor/rules/common-coding-style.mdnew file mode 100644index 000000000..d7e2745b4--- /dev/null+++ b/.cursor/rules/common-coding-style.md@@ -0,0 +1,52 @@+---+description: "ECC coding style: immutability, file organization, error handling, validation"+alwaysApply: true+---+# Coding Style++## Immutability (CRITICAL)++ALWAYS create new objects, NEVER mutate existing ones:++```+// Pseudocode+WRONG: modify(original, field, value) → changes original in-place+CORRECT: update(original, field, value) → returns new copy with change+```++Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.++## File Organization++MANY SMALL FILES > FEW LARGE FILES:+- High cohesion, low coupling+- 200-400 lines typical, 800 max+- Extract utilities from large modules+- Organize by feature/domain, not by type++## Error Handling++ALWAYS handle errors comprehensively:+- Handle errors explicitly at every level+- Provide user-friendly error messages in UI-facing code+- Log detailed error context on the server side+- Never silently swallow errors++## Input Validation++ALWAYS validate at system boundaries:+- Validate all user input before processing+- Use schema-based validation where available+- Fail fast with clear error messages+- Never trust external data (API responses, user input, file content)++## Code Quality Checklist++Before marking work complete:+- [ ] Code is readable and well-named+- [ ] Functions are small (<50 lines)+- [ ] Files are focused (<800 lines)+- [ ] No deep nesting (>4 levels)+- [ ] Proper error handling+- [ ] No hardcoded values (use constants or config)+- [ ] No mutation (immutable patterns used)diff --git a/.cursor/rules/common-development-workflow.md b/.cursor/rules/common-development-workflow.mdnew file mode 100644index 000000000..a218b94c5--- /dev/null+++ b/.cursor/rules/common-development-workflow.md@@ -0,0 +1,33 @@+---+description: "Development workflow: plan, TDD, review, commit pipeline"+alwaysApply: true+---+# Development Workflow++> This rule extends the git workflow rule with the full feature development process that happens before git operations.++The Feature Implementation Workflow describes the development pipeline: planning, TDD, code review, and then committing to git.++## Feature Implementation Workflow++1. **Plan First**+ - Use **planner** agent to create implementation plan+ - Identify dependencies and risks+ - Break down into phases++2. **TDD Approach**+ - Use **tdd-guide** agent+ - Write tests first (RED)+ - Implement to pass tests (GREEN)+ - Refactor (IMPROVE)+ - Verify 80%+ coverage++3. **Code Review**+ - Use **code-reviewer** agent immediately after writing code+ - Address CRITICAL and HIGH issues+ - Fix MEDIUM issues when possible++4. **Commit & Push**+ - Detailed commit messages+ - Follow conventional commits format+ - See the git workflow rule for commit message format and PR processdiff --git a/.cursor/rules/common-git-workflow.md b/.cursor/rules/common-git-workflow.mdnew file mode 100644index 000000000..b275023e0--- /dev/null+++ b/.cursor/rules/common-git-workflow.md@@ -0,0 +1,28 @@+---+description: "Git workflow: conventional commits, PR process"+alwaysApply: true+---+# Git Workflow++## Commit Message Format+```+<type>: <description>++<optional body>+```++Types: feat, fix, refactor, docs, test, chore, perf, ci++Note: Attribution disabled globally via ~/.claude/settings.json.++## Pull Request Workflow++When creating PRs:+1. Analyze full commit history (not just latest commit)+2. Use `git diff [base-branch]...HEAD` to see all changes+3. Draft comprehensive PR summary+4. Include test plan with TODOs+5. Push with `-u` flag if new branch++> For the full development process (planning, TDD, code review) before git operations,+> see the development workflow rule.diff --git a/.cursor/rules/common-hooks.md b/.cursor/rules/common-hooks.mdnew file mode 100644index 000000000..0f9586fd1--- /dev/null+++ b/.cursor/rules/common-hooks.md@@ -0,0 +1,34 @@+---+description: "Hooks system: types, auto-accept permissions, TodoWrite best practices"+alwaysApply: true+---+# Hooks System++## Hook Types++- **PreToolUse**: Before tool execution (validation, parameter modification)+- **PostToolUse**: After tool execution (auto-format, checks)+- **Stop**: When session ends (final verification)++## Auto-Accept Permissions++Use with caution:+- Enable for trusted, well-defined plans+- Disable for exploratory work+- Never use dangerously-skip-permissions flag+- Configure `allowedTools` in `~/.claude.json` instead++## TodoWrite Best Practices++Use TodoWrite tool to:+- Track progress on multi-step tasks+- Verify understanding of instructions+- Enable real-time steering+- Show granular implementation steps++Todo list reveals:+- Out of order steps+- Missing items+- Extra unnecessary items+- Wrong granularity+- Misinterpreted requirementsdiff --git a/.cursor/rules/common-patterns.md b/.cursor/rules/common-patterns.mdnew file mode 100644index 000000000..7304709ad--- /dev/null+++ b/.cursor/rules/common-patterns.md@@ -0,0 +1,35 @@+---+description: "Common patterns: repository, API response, skeleton projects"+alwaysApply: true+---+# Common Patterns++## Skeleton Projects++When implementing new functionality:+1. Search for battle-tested skeleton projects+2. Use parallel agents to evaluate options:+ - Security assessment+ - Extensibility analysis+ - Relevance scoring+ - Implementation planning+3. Clone best match as foundation+4. Iterate within proven structure++## Design Patterns++### Repository Pattern++Encapsulate data access behind a consistent interface:+- Define standard operations: findAll, findById, create, update, delete+- Concrete implementations handle storage details (database, API, file, etc.)+- Business logic depends on the abstract interface, not the storage mechanism+- Enables easy swapping of data sources and simplifies testing with mocks++### API Response Format++Use a consistent envelope for all API responses:+- Include a success/status indicator+- Include the data payload (nullable on error)+- Include an error message field (nullable on success)+- Include metadata for paginated responses (total, page, limit)diff --git a/.cursor/rules/common-performance.md b/.cursor/rules/common-performance.mdnew file mode 100644index 000000000..dc65dccb0--- /dev/null+++ b/.cursor/rules/common-performance.md@@ -0,0 +1,59 @@+---+description: "Performance: model selection, context management, build troubleshooting"+alwaysApply: true+---+# Performance Optimization++## Model Selection Strategy++**Haiku 4.5** (90% of Sonnet capability, 3x cost savings):+- Lightweight agents with frequent invocation+- Pair programming and code generation+- Worker agents in multi-agent systems++**Sonnet 4.6** (Best coding model):+- Main development work+- Orchestrating multi-agent workflows+- Complex coding tasks++**Opus 4.5** (Deepest reasoning):+- Complex architectural decisions+- Maximum reasoning requirements+- Research and analysis tasks++## Context Window Management++Avoid last 20% of context window for:+- Large-scale refactoring+- Feature implementation spanning multiple files+- Debugging complex interactions++Lower context sensitivity tasks:+- Single-file edits+- Independent utility creation+- Documentation updates+- Simple bug fixes++## Extended Thinking + Plan Mode++Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning.++Control extended thinking via:+- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux)+- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json`+- **Budget cap**: `export MAX_THINKING_TOKENS=10000`+- **Verbose mode**: Ctrl+O to see thinking output++For complex tasks requiring deep reasoning:+1. Ensure extended thinking is enabled (on by default)+2. Enable **Plan Mode** for structured approach+3. Use multiple critique rounds for thorough analysis+4. Use split role sub-agents for diverse perspectives++## Build Troubleshooting++If build fails:+1. Use **build-error-resolver** agent+2. Analyze error messages+3. Fix incrementally+4. Verify after each fixdiff --git a/.cursor/rules/common-security.md b/.cursor/rules/common-security.mdnew file mode 100644index 000000000..a45737c6b--- /dev/null+++ b/.cursor/rules/common-security.md@@ -0,0 +1,33 @@+---+description: "Security: mandatory checks, secret management, response protocol"+alwaysApply: true+---+# Security Guidelines++## Mandatory Security Checks++Before ANY commit:+- [ ] No hardcoded secrets (API keys, passwords, tokens)+- [ ] All user inputs validated+- [ ] SQL injection prevention (parameterized queries)+- [ ] XSS prevention (sanitized HTML)+- [ ] CSRF protection enabled+- [ ] Authentication/authorization verified+- [ ] Rate limiting on all endpoints+- [ ] Error messages don't leak sensitive data++## Secret Management++- NEVER hardcode secrets in source code+- ALWAYS use environment variables or a secret manager+- Validate that required secrets are present at startup+- Rotate any secrets that may have been exposed++## Security Response Protocol++If security issue found:+1. STOP immediately+2. Use **security-reviewer** agent+3. Fix CRITICAL issues before continuing+4. Rotate any exposed secrets+5. Review entire codebase for similar issuesdiff --git a/.cursor/rules/common-testing.md b/.cursor/rules/common-testing.mdnew file mode 100644index 000000000..bc6cd86db--- /dev/null+++ b/.cursor/rules/common-testing.md@@ -0,0 +1,33 @@+---+description: "Testing requirements: 80% coverage, TDD workflow, test types"+alwaysApply: true+---+# Testing Requirements++## Minimum Test Coverage: 80%++Test Types (ALL required):+1. **Unit Tests** - Individual functions, utilities, components+2. **Integration Tests** - API endpoints, database operations+3. **E2E Tests** - Critical user flows (framework chosen per language)++## Test-Driven Development++MANDATORY workflow:+1. Write test first (RED)+2. Run test - it should FAIL+3. Write minimal implementation (GREEN)+4. Run test - it should PASS+5. Refactor (IMPROVE)+6. Verify coverage (80%+)++## Troubleshooting Test Failures++1. Use **tdd-guide** agent+2. Check test isolation+3. Verify mocks are correct+4. Fix implementation, not tests (unless tests are wrong)++## Agent Support++- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-firstdiff --git a/.cursor/rules/golang-coding-style.md b/.cursor/rules/golang-coding-style.mdnew file mode 100644index 000000000..412bb77d1--- /dev/null+++ b/.cursor/rules/golang-coding-style.md@@ -0,0 +1,31 @@+---+description: "Go coding style extending common rules"+globs: ["**/*.go", "**/go.mod", "**/go.sum"]+alwaysApply: false+---+# Go Coding Style++> This file extends the common coding style rule with Go specific content.++## Formatting++- **gofmt** and **goimports** are mandatory -- no style debates++## Design Principles++- Accept interfaces, return structs+- Keep interfaces small (1-3 methods)++## Error Handling++Always wrap errors with context:++```go+if err != nil {+ return fmt.Errorf("failed to create user: %w", err)+}+```++## Reference++See skill: `golang-patterns` for comprehensive Go idioms and patterns.diff --git a/.cursor/rules/golang-hooks.md b/.cursor/rules/golang-hooks.mdnew file mode 100644index 000000000..4edadb8e4--- /dev/null+++ b/.cursor/rules/golang-hooks.md@@ -0,0 +1,16 @@+---+description: "Go hooks extending common rules"+globs: ["**/*.go", "**/go.mod", "**/go.sum"]+alwaysApply: false+---+# Go Hooks++> This file extends the common hooks rule with Go specific content.++## PostToolUse Hooks++Configure in `~/.claude/settings.json`:++- **gofmt/goimports**: Auto-format `.go` files after edit+- **go vet**: Run static analysis after editing `.go` files+- **staticcheck**: Run extended static checks on modified packagesdiff --git a/.cursor/rules/golang-patterns.md b/.cursor/rules/golang-patterns.mdnew file mode 100644index 000000000..d03fbb971--- /dev/null+++ b/.cursor/rules/golang-patterns.md@@ -0,0 +1,44 @@+---+description: "Go patterns extending common rules"+globs: ["**/*.go", "**/go.mod", "**/go.sum"]+alwaysApply: false+---+# Go Patterns++> This file extends the common patterns rule with Go specific content.++## Functional Options++```go+type Option func(*Server)++func WithPort(port int) Option {+ return func(s *Server) { s.port = port }+}++func NewServer(opts ...Option) *Server {+ s := &Server{port: 8080}+ for _, opt := range opts {+ opt(s)+ }+ return s+}+```++## Small Interfaces++Define interfaces where they are used, not where they are implemented.++## Dependency Injection++Use constructor functions to inject dependencies:++```go+func NewUserService(repo UserRepository, logger Logger) *UserService {+ return &UserService{repo: repo, logger: logger}+}+```++## Reference++See skill: `golang-patterns` for comprehensive Go patterns including concurrency, error handling, and package organization.diff --git a/.cursor/rules/golang-security.md b/.cursor/rules/golang-security.mdnew file mode 100644index 000000000..e2f88942a--- /dev/null+++ b/.cursor/rules/golang-security.md@@ -0,0 +1,33 @@+---+description: "Go security extending common rules"+globs: ["**/*.go", "**/go.mod", "**/go.sum"]+alwaysApply: false+---+# Go Security++> This file extends the common security rule with Go specific content.++## Secret Management++```go+apiKey := os.Getenv("OPENAI_API_KEY")+if apiKey == "" {+ log.Fatal("OPENAI_API_KEY not configured")+}+```++## Security Scanning++- Use **gosec** for static security analysis:+ ```bash+ gosec ./...+ ```++## Context & Timeouts++Always use `context.Context` for timeout control:++```go+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)+defer cancel()+```diff --git a/.cursor/rules/golang-testing.md b/.cursor/rules/golang-testing.mdnew file mode 100644index 000000000..530963a7e--- /dev/null+++ b/.cursor/rules/golang-testing.md@@ -0,0 +1,30 @@+---+description: "Go testing extending common rules"+globs: ["**/*.go", "**/go.mod", "**/go.sum"]+alwaysApply: false+---+# Go Testing++> This file extends the common testing rule with Go specific content.++## Framework++Use the standard `go test` with **table-driven tests**.++## Race Detection++Always run with the `-race` flag:++```bash+go test -race ./...+```++## Coverage++```bash+go test -cover ./...+```++## Reference++See skill: `golang-testing` for detailed Go testing patterns and helpers.diff --git a/.cursor/rules/python-coding-style.md b/.cursor/rules/python-coding-style.mdnew file mode 100644index 000000000..4537653b4--- /dev/null+++ b/.cursor/rules/python-coding-style.md@@ -0,0 +1,42 @@+---+description: "Python coding style extending common rules"+globs: ["**/*.py", "**/*.pyi"]+alwaysApply: false+---+# Python Coding Style++> This file extends the common coding style rule with Python specific content.++## Standards++- Follow **PEP 8** conventions+- Use **type annotations** on all function signatures++## Immutability++Prefer immutable data structures:++```python+from dataclasses import dataclass++@dataclass(frozen=True)+class User:+ name: str+ email: str++from typing import NamedTuple++class Point(NamedTuple):+ x: float+ y: float+```++## Formatting++- **black** for code formatting+- **isort** for import sorting+- **ruff** for linting++## Reference++See skill: `python-patterns` for comprehensive Python idioms and patterns.diff --git a/.cursor/rules/python-hooks.md b/.cursor/rules/python-hooks.mdnew file mode 100644index 000000000..33165eaed--- /dev/null+++ b/.cursor/rules/python-hooks.md@@ -0,0 +1,19 @@+---+description: "Python hooks extending common rules"+globs: ["**/*.py", "**/*.pyi"]+alwaysApply: false+---+# Python Hooks++> This file extends the common hooks rule with Python specific content.++## PostToolUse Hooks++Configure in `~/.claude/settings.json`:++- **black/ruff**: Auto-format `.py` files after edit+- **mypy/pyright**: Run type checking after editing `.py` files++## Warnings++- Warn about `print()` statements in edited files (use `logging` module instead)diff --git a/.cursor/rules/python-patterns.md b/.cursor/rules/python-patterns.mdnew file mode 100644index 000000000..f6058bf09--- /dev/null+++ b/.cursor/rules/python-patterns.md@@ -0,0 +1,39 @@+---+description: "Python patterns extending common rules"+globs: ["**/*.py", "**/*.pyi"]+alwaysApply: false+---+# Python Patterns++> This file extends the common patterns rule with Python specific content.++## Protocol (Duck Typing)++```python+from typing import Protocol++class Repository(Protocol):+ def find_by_id(self, id: str) -> dict | None: ...+ def save(self, entity: dict) -> dict: ...+```++## Dataclasses as DTOs++```python+from dataclasses import dataclass++@dataclass+class CreateUserRequest:+ name: str+ email: str+ age: int | None = None+```++## Context Managers & Generators++- Use context managers (`with` statement) for resource management+- Use generators for lazy evaluation and memory-efficient iteration++## Reference++See skill: `python-patterns` for comprehensive patterns including decorators, concurrency, and package organization.diff --git a/.cursor/rules/python-security.md b/.cursor/rules/python-security.mdnew file mode 100644index 000000000..5d76b184e--- /dev/null+++ b/.cursor/rules/python-security.md@@ -0,0 +1,30 @@+---+description: "Python security extending common rules"+globs: ["**/*.py", "**/*.pyi"]+alwaysApply: false+---+# Python Security++> This file extends the common security rule with Python specific content.++## Secret Management++```python+import os+from dotenv import load_dotenv++load_dotenv()++api_key = os.environ["OPENAI_API_KEY"] # Raises KeyError if missing+```++## Security Scanning++- Use **bandit** for static security analysis:+ ```bash+ bandit -r src/+ ```++## Reference++See skill: `django-security` for Django-specific security guidelines (if applicable).diff --git a/.cursor/rules/python-testing.md b/.cursor/rules/python-testing.mdnew file mode 100644index 000000000..c72c612a8--- /dev/null+++ b/.cursor/rules/python-testing.md@@ -0,0 +1,38 @@+---+description: "Python testing extending common rules"+globs: ["**/*.py", "**/*.pyi"]+alwaysApply: false+---+# Python Testing++> This file extends the common testing rule with Python specific content.++## Framework++Use **pytest** as the testing framework.++## Coverage++```bash+pytest --cov=src --cov-report=term-missing+```++## Test Organization++Use `pytest.mark` for test categorization:++```python+import pytest++def test_calculate_total():+ ...++def test_database_connection():+ ...+```++## Reference++See skill: `python-testing` for detailed pytest patterns and fixtures.diff --git a/.cursor/rules/swift-coding-style.md b/.cursor/rules/swift-coding-style.mdnew file mode 100644index 000000000..a19640498--- /dev/null+++ b/.cursor/rules/swift-coding-style.md@@ -0,0 +1,47 @@+---+description: "Swift coding style extending common rules"+globs: ["**/*.swift", "**/Package.swift"]+alwaysApply: false+---+# Swift Coding Style++> This file extends the common coding style rule with Swift specific content.++## Formatting++- **SwiftFormat** for auto-formatting, **SwiftLint** for style enforcement+- `swift-format` is bundled with Xcode 16+ as an alternative++## Immutability++- Prefer `let` over `var` -- define everything as `let` and only change to `var` if the compiler requires it+- Use `struct` with value semantics by default; use `class` only when identity or reference semantics are needed++## Naming++Follow [Apple API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/):++- Clarity at the point of use -- omit needless words+- Name methods and properties for their roles, not their types+- Use `static let` for constants over global constants++## Error Handling++Use typed throws (Swift 6+) and pattern matching:++```swift+func load(id: String) throws(LoadError) -> Item {+ guard let data = try? read(from: path) else {+ throw .fileNotFound(id)+ }+ return try decode(data)+}+```++## Concurrency++Enable Swift 6 strict concurrency checking. Prefer:++- `Sendable` value types for data crossing isolation boundaries+- Actors for shared mutable state+- Structured concurrency (`async let`, `TaskGroup`) over unstructured `Task {}`diff --git a/.cursor/rules/swift-hooks.md b/.cursor/rules/swift-hooks.mdnew file mode 100644index 000000000..f9f1b7fe8--- /dev/null+++ b/.cursor/rules/swift-hooks.md@@ -0,0 +1,20 @@+---+description: "Swift hooks extending common rules"+globs: ["**/*.swift", "**/Package.swift"]+alwaysApply: false+---+# Swift Hooks++> This file extends the common hooks rule with Swift specific content.++## PostToolUse Hooks++Configure in `~/.claude/settings.json`:++- **SwiftFormat**: Auto-format `.swift` files after edit+- **SwiftLint**: Run lint checks after editing `.swift` files+- **swift build**: Type-check modified packages after edit++## Warning++Flag `print()` statements -- use `os.Logger` or structured logging instead for production code.diff --git a/.cursor/rules/swift-patterns.md b/.cursor/rules/swift-patterns.mdnew file mode 100644index 000000000..d65947ca6--- /dev/null+++ b/.cursor/rules/swift-patterns.md@@ -0,0 +1,66 @@+---+description: "Swift patterns extending common rules"+globs: ["**/*.swift", "**/Package.swift"]+alwaysApply: false+---+# Swift Patterns++> This file extends the common patterns rule with Swift specific content.++## Protocol-Oriented Design++Define small, focused protocols. Use protocol extensions for shared defaults:++```swift+protocol Repository: Sendable {+ associatedtype Item: Identifiable & Sendable+ func find(by id: Item.ID) async throws -> Item?+ func save(_ item: Item) async throws+}+```++## Value Types++- Use structs for data transfer objects and models+- Use enums with associated values to model distinct states:++```swift+enum LoadState<T: Sendable>: Sendable {+ case idle+ case loading+ case loaded(T)+ case failed(Error)+}+```++## Actor Pattern++Use actors for shared mutable state instead of locks or dispatch queues:++```swift+actor Cache<Key: Hashable & Sendable, Value: Sendable> {+ private var storage: [Key: Value] = [:]++ func get(_ key: Key) -> Value? { storage[key] }+ func set(_ key: Key, value: Value) { storage[key] = value }+}+```++## Dependency Injection++Inject protocols with default parameters -- production uses defaults, tests inject mocks:++```swift+struct UserService {+ private let repository: any UserRepository++ init(repository: any UserRepository = DefaultUserRepository()) {+ self.repository = repository+ }+}+```++## References++See skill: `swift-actor-persistence` for actor-based persistence patterns.+See skill: `swift-protocol-di-testing` for protocol-based DI and testing.diff --git a/.cursor/rules/swift-security.md b/.cursor/rules/swift-security.mdnew file mode 100644index 000000000..b965f174c--- /dev/null+++ b/.cursor/rules/swift-security.md@@ -0,0 +1,33 @@+---+description: "Swift security extending common rules"+globs: ["**/*.swift", "**/Package.swift"]+alwaysApply: false+---+# Swift Security++> This file extends the common security rule with Swift specific content.++## Secret Management++- Use **Keychain Services** for sensitive data (tokens, passwords, keys) -- never `UserDefaults`+- Use environment variables or `.xcconfig` files for build-time secrets+- Never hardcode secrets in source -- decompilation tools extract them trivially++```swift+let apiKey = ProcessInfo.processInfo.environment["API_KEY"]+guard let apiKey, !apiKey.isEmpty else {+ fatalError("API_KEY not configured")+}+```++## Transport Security++- App Transport Security (ATS) is enforced by default -- do not disable it+- Use certificate pinning for critical endpoints+- Validate all server certificates++## Input Validation++- Sanitize all user input before display to prevent injection+- Use `URL(string:)` with validation rather than force-unwrapping+- Validate data from external sources (APIs, deep links, pasteboard) before processingdiff --git a/.cursor/rules/swift-testing.md b/.cursor/rules/swift-testing.mdnew file mode 100644index 000000000..8b65b55b6--- /dev/null+++ b/.cursor/rules/swift-testing.md@@ -0,0 +1,45 @@+---+description: "Swift testing extending common rules"+globs: ["**/*.swift", "**/Package.swift"]+alwaysApply: false+---+# Swift Testing++> This file extends the common testing rule with Swift specific content.++## Framework++Use **Swift Testing** (`import Testing`) for new tests. Use `@Test` and `#expect`:++```swift+@Test("User creation validates email")+func userCreationValidatesEmail() throws {+ #expect(throws: ValidationError.invalidEmail) {+ try User(email: "not-an-email")+ }+}+```++## Test Isolation++Each test gets a fresh instance -- set up in `init`, tear down in `deinit`. No shared mutable state between tests.++## Parameterized Tests++```swift+@Test("Validates formats", arguments: ["json", "xml", "csv"])+func validatesFormat(format: String) throws {+ let parser = try Parser(format: format)+ #expect(parser.isValid)+}+```++## Coverage++```bash+swift test --enable-code-coverage+```++## Reference++See skill: `swift-protocol-di-testing` for protocol-based dependency injection and mock patterns with Swift Testing.diff --git a/.cursor/rules/typescript-coding-style.md b/.cursor/rules/typescript-coding-style.mdnew file mode 100644index 000000000..af5c4f843--- /dev/null+++ b/.cursor/rules/typescript-coding-style.md@@ -0,0 +1,63 @@+---+description: "TypeScript coding style extending common rules"+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]+alwaysApply: false+---+# TypeScript/JavaScript Coding Style++> This file extends the common coding style rule with TypeScript/JavaScript specific content.++## Immutability++Use spread operator for immutable updates:++```typescript+// WRONG: Mutation+function updateUser(user, name) {+ user.name = name // MUTATION!+ return user+}++// CORRECT: Immutability+function updateUser(user, name) {+ return {+ ...user,+ name+ }+}+```++## Error Handling++Use async/await with try-catch:++```typescript+try {+ const result = await riskyOperation()+ return result+} catch (error) {+ console.error('Operation failed:', error)+ throw new Error('Detailed user-friendly message')+}+```++## Input Validation++Use Zod for schema-based validation:++```typescript+import { z } from 'zod'++const schema = z.object({+ email: z.string().email(),+ age: z.number().int().min(0).max(150)+})++const validated = schema.parse(input)+```++## Console.log++- No `console.log` statements in production code+- Use proper logging libraries instead+- See hooks for automatic detectiondiff --git a/.cursor/rules/typescript-hooks.md b/.cursor/rules/typescript-hooks.mdnew file mode 100644index 000000000..9032d3027--- /dev/null+++ b/.cursor/rules/typescript-hooks.md@@ -0,0 +1,20 @@+---+description: "TypeScript hooks extending common rules"+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]+alwaysApply: false+---+# TypeScript/JavaScript Hooks++> This file extends the common hooks rule with TypeScript/JavaScript specific content.++## PostToolUse Hooks++Configure in `~/.claude/settings.json`:++- **Prettier**: Auto-format JS/TS files after edit+- **TypeScript check**: Run `tsc` after editing `.ts`/`.tsx` files+- **console.log warning**: Warn about `console.log` in edited files++## Stop Hooks++- **console.log audit**: Check all modified files for `console.log` before session endsdiff --git a/.cursor/rules/typescript-patterns.md b/.cursor/rules/typescript-patterns.mdnew file mode 100644index 000000000..0c8a9b80f--- /dev/null+++ b/.cursor/rules/typescript-patterns.md@@ -0,0 +1,50 @@+---+description: "TypeScript patterns extending common rules"+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]+alwaysApply: false+---+# TypeScript/JavaScript Patterns++> This file extends the common patterns rule with TypeScript/JavaScript specific content.++## API Response Format++```typescript+interface ApiResponse<T> {+ success: boolean+ data?: T+ error?: string+ meta?: {+ total: number+ page: number+ limit: number+ }+}+```++## Custom Hooks Pattern++```typescript+export function useDebounce<T>(value: T, delay: number): T {+ const [debouncedValue, setDebouncedValue] = useState<T>(value)++ useEffect(() => {+ const handler = setTimeout(() => setDebouncedValue(value), delay)+ return () => clearTimeout(handler)+ }, [value, delay])++ return debouncedValue+}+```++## Repository Pattern++```typescript+interface Repository<T> {+ findAll(filters?: Filters): Promise<T[]>+ findById(id: string): Promise<T | null>+ create(data: CreateDto): Promise<T>+ update(id: string, data: UpdateDto): Promise<T>+ delete(id: string): Promise<void>+}+```diff --git a/.cursor/rules/typescript-security.md b/.cursor/rules/typescript-security.mdnew file mode 100644index 000000000..8aea61f5b--- /dev/null+++ b/.cursor/rules/typescript-security.md@@ -0,0 +1,26 @@+---+description: "TypeScript security extending common rules"+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]+alwaysApply: false+---+# TypeScript/JavaScript Security++> This file extends the common security rule with TypeScript/JavaScript specific content.++## Secret Management++```typescript+// NEVER: Hardcoded secrets+const apiKey = "sk-proj-xxxxx"++// ALWAYS: Environment variables+const apiKey = process.env.OPENAI_API_KEY++if (!apiKey) {+ throw new Error('OPENAI_API_KEY not configured')+}+```++## Agent Support++- Use **security-reviewer** skill for comprehensive security auditsdiff --git a/.cursor/rules/typescript-testing.md b/.cursor/rules/typescript-testing.mdnew file mode 100644index 000000000..894b9fe95--- /dev/null+++ b/.cursor/rules/typescript-testing.md@@ -0,0 +1,16 @@+---+description: "TypeScript testing extending common rules"+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]+alwaysApply: false+---+# TypeScript/JavaScript Testing++> This file extends the common testing rule with TypeScript/JavaScript specific content.++## E2E Testing++Use **Playwright** as the E2E testing framework for critical user flows.++## Agent Support++- **e2e-runner** - Playwright E2E testing specialistdiff --git a/.opencode/index.ts b/.opencode/index.tsindex 43240823c..4b686715f 100644--- a/.opencode/index.ts+++ b/.opencode/index.ts@@ -4,8 +4,8 @@* This package provides a complete OpenCode plugin with:* - 13 specialized agents (planner, architect, code-reviewer, etc.)* - 31 commands (/plan, /tdd, /code-review, etc.)- * - Plugin hooks (auto-format, TypeScript check, console.log warning, etc.)- * - Custom tools (run-tests, check-coverage, security-audit)+ * - Plugin hooks (auto-format, TypeScript check, console.log warning, env injection, etc.)+ * - Custom tools (run-tests, check-coverage, security-audit, format-code, lint-check, git-summary)* - 37 skills (coding-standards, security-review, tdd-workflow, etc.)** Usage:@@ -39,7 +39,7 @@ export { ECCHooksPlugin, default } from "./plugins/index.js"export * from "./plugins/index.js"// Version export-export const VERSION = "1.4.1"+export const VERSION = "1.6.0"// Plugin metadataexport const metadata = {@@ -59,13 +59,18 @@ export const metadata = {"session.idle","session.deleted","file.watcher.updated",- "permission.asked",+ "permission.ask","todo.updated",+ "shell.env",+ "experimental.session.compacting",],customTools: ["run-tests","check-coverage","security-audit",+ "format-code",+ "lint-check",+ "git-summary",],},}diff --git a/.opencode/opencode.json b/.opencode/opencode.jsonindex 0dbf66381..42cb5112c 100644--- a/.opencode/opencode.json+++ b/.opencode/opencode.json@@ -4,11 +4,19 @@"small_model": "anthropic/claude-haiku-4-5","default_agent": "build","instructions": [+ "AGENTS.md","CONTRIBUTING.md",".opencode/instructions/INSTRUCTIONS.md","skills/tdd-workflow/SKILL.md","skills/security-review/SKILL.md",- "skills/coding-standards/SKILL.md"+ "skills/coding-standards/SKILL.md",+ "skills/frontend-patterns/SKILL.md",+ "skills/backend-patterns/SKILL.md",+ "skills/e2e-testing/SKILL.md",+ "skills/verification-loop/SKILL.md",+ "skills/api-design/SKILL.md",+ "skills/strategic-compact/SKILL.md",+ "skills/eval-harness/SKILL.md"],"plugin": ["./.opencode/plugins"diff --git a/.opencode/package.json b/.opencode/package.jsonindex 75a243084..d8defaae1 100644--- a/.opencode/package.json+++ b/.opencode/package.json@@ -1,6 +1,6 @@{"name": "ecc-universal",- "version": "1.4.1",+ "version": "1.6.0","description": "Everything Claude Code (ECC) plugin for OpenCode - agents, commands, hooks, and skills","main": "dist/index.js","types": "dist/index.d.ts",diff --git a/.opencode/plugins/ecc-hooks.ts b/.opencode/plugins/ecc-hooks.tsindex 50d23bfde..1f158d799 100644--- a/.opencode/plugins/ecc-hooks.ts+++ b/.opencode/plugins/ecc-hooks.ts@@ -261,17 +261,6 @@ export const ECCHooksPlugin = async ({}},- /**- * Permission Asked Hook- * OpenCode-only feature- *- * Triggers: When permission is requested- * Action: Logs for audit trail- */- "permission.asked": async (event: { tool: string; args: unknown }) => {- log("info", `[ECC] Permission requested for: ${event.tool}`)- },-/*** Todo Updated Hook* OpenCode-only feature@@ -286,6 +275,131 @@ export const ECCHooksPlugin = async ({log("info", `[ECC] Progress: ${completed}/${total} tasks completed`)}},++ /**+ * Shell Environment Hook+ * OpenCode-specific: Inject environment variables into shell commands+ *+ * Triggers: Before shell command execution+ * Action: Sets PROJECT_ROOT, PACKAGE_MANAGER, DETECTED_LANGUAGES, ECC_VERSION+ */+ "shell.env": async () => {+ const env: Record<string, string> = {+ ECC_VERSION: "1.6.0",+ ECC_PLUGIN: "true",+ PROJECT_ROOT: worktree || directory,+ }++ // Detect package manager+ const lockfiles: Record<string, string> = {+ "bun.lockb": "bun",+ "pnpm-lock.yaml": "pnpm",+ "yarn.lock": "yarn",+ "package-lock.json": "npm",+ }+ for (const [lockfile, pm] of Object.entries(lockfiles)) {+ try {+ await $`test -f ${worktree}/${lockfile}`+ env.PACKAGE_MANAGER = pm+ break+ } catch {+ // Not found, try next+ }+ }++ // Detect languages+ const langDetectors: Record<string, string> = {+ "tsconfig.json": "typescript",+ "go.mod": "go",+ "pyproject.toml": "python",+ "Cargo.toml": "rust",+ "Package.swift": "swift",+ }+ const detected: string[] = []+ for (const [file, lang] of Object.entries(langDetectors)) {+ try {+ await $`test -f ${worktree}/${file}`+ detected.push(lang)+ } catch {+ // Not found+ }+ }+ if (detected.length > 0) {+ env.DETECTED_LANGUAGES = detected.join(",")+ env.PRIMARY_LANGUAGE = detected[0]+ }++ return env+ },++ /**+ * Session Compacting Hook+ * OpenCode-specific: Control context compaction behavior+ *+ * Triggers: Before context compaction+ * Action: Push ECC context block and custom compaction prompt+ */+ "experimental.session.compacting": async () => {+ const contextBlock = [+ "# ECC Context (preserve across compaction)",+ "",+ "## Active Plugin: Everything Claude Code v1.6.0",+ "- Hooks: file.edited, tool.execute.before/after, session.created/idle/deleted, shell.env, compacting, permission.ask",+ "- Tools: run-tests, check-coverage, security-audit, format-code, lint-check, git-summary",+ "- Agents: 13 specialized (planner, architect, tdd-guide, code-reviewer, security-reviewer, build-error-resolver, e2e-runner, refactor-cleaner, doc-updater, go-reviewer, go-build-resolver, database-reviewer, python-reviewer)",+ "",+ "## Key Principles",+ "- TDD: write tests first, 80%+ coverage",+ "- Immutability: never mutate, always return new copies",+ "- Security: validate inputs, no hardcoded secrets",+ "",+ ]++ // Include recently edited files+ if (editedFiles.size > 0) {+ contextBlock.push("## Recently Edited Files")+ for (const f of editedFiles) {+ contextBlock.push(`- ${f}`)+ }+ contextBlock.push("")+ }++ return {+ context: contextBlock.join("\n"),+ compaction_prompt: "Focus on preserving: 1) Current task status and progress, 2) Key decisions made, 3) Files created/modified, 4) Remaining work items, 5) Any security concerns flagged. Discard: verbose tool outputs, intermediate exploration, redundant file listings.",+ }+ },++ /**+ * Permission Auto-Approve Hook+ * OpenCode-specific: Auto-approve safe operations+ *+ * Triggers: When permission is requested+ * Action: Auto-approve reads, formatters, and test commands; log all for audit+ */+ "permission.ask": async (event: { tool: string; args: unknown }) => {+ log("info", `[ECC] Permission requested for: ${event.tool}`)++ const cmd = String((event.args as Record<string, unknown>)?.command || event.args || "")++ // Auto-approve: read/search tools+ if (["read", "glob", "grep", "search", "list"].includes(event.tool)) {+ return { approved: true, reason: "Read-only operation" }+ }++ // Auto-approve: formatters+ if (event.tool === "bash" && /^(npx )?(prettier|biome|black|gofmt|rustfmt|swift-format)/.test(cmd)) {+ return { approved: true, reason: "Formatter execution" }+ }++ // Auto-approve: test execution+ if (event.tool === "bash" && /^(npm test|npx vitest|npx jest|pytest|go test|cargo test)/.test(cmd)) {+ return { approved: true, reason: "Test execution" }+ }++ // Everything else: let user decide+ return { approved: undefined }+ },}}diff --git a/.opencode/tools/format-code.ts b/.opencode/tools/format-code.tsnew file mode 100644index 000000000..080bd5b4c--- /dev/null+++ b/.opencode/tools/format-code.ts@@ -0,0 +1,66 @@+/**+ * ECC Custom Tool: Format Code+ *+ * Language-aware code formatter that auto-detects the project's formatter.+ * Supports: Biome/Prettier (JS/TS), Black (Python), gofmt (Go), rustfmt (Rust)+ */++import { tool } from "@opencode-ai/plugin"+import { z } from "zod"++export default tool({+ name: "format-code",+ description: "Format a file using the project's configured formatter. Auto-detects Biome, Prettier, Black, gofmt, or rustfmt.",+ parameters: z.object({+ filePath: z.string().describe("Path to the file to format"),+ formatter: z.string().optional().describe("Override formatter: biome, prettier, black, gofmt, rustfmt (default: auto-detect)"),+ }),+ execute: async ({ filePath, formatter }, { $ }) => {+ const ext = filePath.split(".").pop()?.toLowerCase() || ""++ // Auto-detect formatter based on file extension and config files+ let detected = formatter+ if (!detected) {+ if (["ts", "tsx", "js", "jsx", "json", "css", "scss"].includes(ext)) {+ // Check for Biome first, then Prettier+ try {+ await $`test -f biome.json || test -f biome.jsonc`+ detected = "biome"+ } catch {+ detected = "prettier"+ }+ } else if (["py", "pyi"].includes(ext)) {+ detected = "black"+ } else if (ext === "go") {+ detected = "gofmt"+ } else if (ext === "rs") {+ detected = "rustfmt"+ }+ }++ if (!detected) {+ return { formatted: false, message: `No formatter detected for .${ext} files` }+ }++ const commands: Record<string, string> = {+ biome: `npx @biomejs/biome format --write ${filePath}`,+ prettier: `npx prettier --write ${filePath}`,+ black: `black ${filePath}`,+ gofmt: `gofmt -w ${filePath}`,+ rustfmt: `rustfmt ${filePath}`,+ }++ const cmd = commands[detected]+ if (!cmd) {+ return { formatted: false, message: `Unknown formatter: ${detected}` }+ }++ try {+ const result = await $`${cmd}`.text()+ return { formatted: true, formatter: detected, output: result }+ } catch (error: unknown) {+ const err = error as { stderr?: string }+ return { formatted: false, formatter: detected, error: err.stderr || "Format failed" }+ }+ },+})diff --git a/.opencode/tools/git-summary.ts b/.opencode/tools/git-summary.tsnew file mode 100644index 000000000..23fcc5e3a--- /dev/null+++ b/.opencode/tools/git-summary.ts@@ -0,0 +1,56 @@+/**+ * ECC Custom Tool: Git Summary+ *+ * Provides a comprehensive git status including branch info, status,+ * recent log, and diff against base branch.+ */++import { tool } from "@opencode-ai/plugin"+import { z } from "zod"++export default tool({+ name: "git-summary",+ description: "Get comprehensive git summary: branch, status, recent log, and diff against base branch.",+ parameters: z.object({+ depth: z.number().optional().describe("Number of recent commits to show (default: 5)"),+ includeDiff: z.boolean().optional().describe("Include diff against base branch (default: true)"),+ baseBranch: z.string().optional().describe("Base branch for comparison (default: main)"),+ }),+ execute: async ({ depth = 5, includeDiff = true, baseBranch = "main" }, { $ }) => {+ const results: Record<string, string> = {}++ try {+ results.branch = (await $`git branch --show-current`.text()).trim()+ } catch {+ results.branch = "unknown"+ }++ try {+ results.status = (await $`git status --short`.text()).trim()+ } catch {+ results.status = "unable to get status"+ }++ try {+ results.log = (await $`git log --oneline -${depth}`.text()).trim()+ } catch {+ results.log = "unable to get log"+ }++ if (includeDiff) {+ try {+ results.stagedDiff = (await $`git diff --cached --stat`.text()).trim()+ } catch {+ results.stagedDiff = ""+ }++ try {+ results.branchDiff = (await $`git diff ${baseBranch}...HEAD --stat`.text()).trim()+ } catch {+ results.branchDiff = `unable to diff against ${baseBranch}`+ }+ }++ return results+ },+})diff --git a/.opencode/tools/index.ts b/.opencode/tools/index.tsindex e779fde69..dabacc4ec 100644--- a/.opencode/tools/index.ts+++ b/.opencode/tools/index.ts@@ -8,3 +8,6 @@export { default as runTests } from "./run-tests.js"export { default as checkCoverage } from "./check-coverage.js"export { default as securityAudit } from "./security-audit.js"+export { default as formatCode } from "./format-code.js"+export { default as lintCheck } from "./lint-check.js"+export { default as gitSummary } from "./git-summary.js"diff --git a/.opencode/tools/lint-check.ts b/.opencode/tools/lint-check.tsnew file mode 100644index 000000000..30d3f93aa--- /dev/null+++ b/.opencode/tools/lint-check.ts@@ -0,0 +1,74 @@+/**+ * ECC Custom Tool: Lint Check+ *+ * Multi-language linter that auto-detects the project's linting tool.+ * Supports: ESLint/Biome (JS/TS), Pylint/Ruff (Python), golangci-lint (Go)+ */++import { tool } from "@opencode-ai/plugin"+import { z } from "zod"++export default tool({+ name: "lint-check",+ description: "Run linter on files or directories. Auto-detects ESLint, Biome, Ruff, Pylint, or golangci-lint.",+ parameters: z.object({+ target: z.string().optional().describe("File or directory to lint (default: current directory)"),+ fix: z.boolean().optional().describe("Auto-fix issues if supported (default: false)"),+ linter: z.string().optional().describe("Override linter: eslint, biome, ruff, pylint, golangci-lint (default: auto-detect)"),+ }),+ execute: async ({ target = ".", fix = false, linter }, { $ }) => {+ // Auto-detect linter+ let detected = linter+ if (!detected) {+ try {+ await $`test -f biome.json || test -f biome.jsonc`+ detected = "biome"+ } catch {+ try {+ await $`test -f .eslintrc.json || test -f .eslintrc.js || test -f .eslintrc.cjs || test -f eslint.config.js || test -f eslint.config.mjs`+ detected = "eslint"+ } catch {+ try {+ await $`test -f pyproject.toml && grep -q "ruff" pyproject.toml`+ detected = "ruff"+ } catch {+ try {+ await $`test -f .golangci.yml || test -f .golangci.yaml`+ detected = "golangci-lint"+ } catch {+ // Fall back based on file extensions in target+ detected = "eslint"+ }+ }+ }+ }+ }++ const fixFlag = fix ? " --fix" : ""+ const commands: Record<string, string> = {+ biome: `npx @biomejs/biome lint${fix ? " --write" : ""} ${target}`,+ eslint: `npx eslint${fixFlag} ${target}`,+ ruff: `ruff check${fixFlag} ${target}`,+ pylint: `pylint ${target}`,+ "golangci-lint": `golangci-lint run${fixFlag} ${target}`,+ }++ const cmd = commands[detected]+ if (!cmd) {+ return { success: false, message: `Unknown linter: ${detected}` }+ }++ try {+ const result = await $`${cmd}`.text()+ return { success: true, linter: detected, output: result, issues: 0 }+ } catch (error: unknown) {+ const err = error as { stdout?: string; stderr?: string }+ return {+ success: false,+ linter: detected,+ output: err.stdout || "",+ errors: err.stderr || "",+ }+ }+ },+})diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 000000000..ad250c43b--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,136 @@+# Everything Claude Code (ECC) — Agent Instructions++This is a **production-ready AI coding plugin** providing 13 specialized agents, 50+ skills, 33 commands, and automated hook workflows for software development.++## Core Principles++1. **Agent-First** — Delegate to specialized agents for domain tasks+2. **Test-Driven** — Write tests before implementation, 80%+ coverage required+3. **Security-First** — Never compromise on security; validate all inputs+4. **Immutability** — Always create new objects, never mutate existing ones+5. **Plan Before Execute** — Plan complex features before writing code++## Available Agents++| Agent | Purpose | When to Use |+|-------|---------|-------------|+| planner | Implementation planning | Complex features, refactoring |+| architect | System design and scalability | Architectural decisions |+| tdd-guide | Test-driven development | New features, bug fixes |+| code-reviewer | Code quality and maintainability | After writing/modifying code |+| security-reviewer | Vulnerability detection | Before commits, sensitive code |+| build-error-resolver | Fix build/type errors | When build fails |+| e2e-runner | End-to-end Playwright testing | Critical user flows |+| refactor-cleaner | Dead code cleanup | Code maintenance |+| doc-updater | Documentation and codemaps | Updating docs |+| go-reviewer | Go code review | Go projects |+| go-build-resolver | Go build errors | Go build failures |+| database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |+| python-reviewer | Python code review | Python projects |++## Agent Orchestration++Use agents proactively without user prompt:+- Complex feature requests → **planner**+- Code just written/modified → **code-reviewer**+- Bug fix or new feature → **tdd-guide**+- Architectural decision → **architect**+- Security-sensitive code → **security-reviewer**++Use parallel execution for independent operations — launch multiple agents simultaneously.++## Security Guidelines++**Before ANY commit:**+- No hardcoded secrets (API keys, passwords, tokens)+- All user inputs validated+- SQL injection prevention (parameterized queries)+- XSS prevention (sanitized HTML)+- CSRF protection enabled+- Authentication/authorization verified+- Rate limiting on all endpoints+- Error messages don't leak sensitive data++**Secret management:** NEVER hardcode secrets. Use environment variables or a secret manager. Validate required secrets at startup. Rotate any exposed secrets immediately.++**If security issue found:** STOP → use security-reviewer agent → fix CRITICAL issues → rotate exposed secrets → review codebase for similar issues.++## Coding Style++**Immutability (CRITICAL):** Always create new objects, never mutate. Return new copies with changes applied.++**File organization:** Many small files over few large ones. 200-400 lines typical, 800 max. Organize by feature/domain, not by type. High cohesion, low coupling.++**Error handling:** Handle errors at every level. Provide user-friendly messages in UI code. Log detailed context server-side. Never silently swallow errors.++**Input validation:** Validate all user input at system boundaries. Use schema-based validation. Fail fast with clear messages. Never trust external data.++**Code quality checklist:**+- Functions small (<50 lines), files focused (<800 lines)+- No deep nesting (>4 levels)+- Proper error handling, no hardcoded values+- Readable, well-named identifiers++## Testing Requirements++**Minimum coverage: 80%**++Test types (all required):+1. **Unit tests** — Individual functions, utilities, components+2. **Integration tests** — API endpoints, database operations+3. **E2E tests** — Critical user flows++**TDD workflow (mandatory):**+1. Write test first (RED) — test should FAIL+2. Write minimal implementation (GREEN) — test should PASS+3. Refactor (IMPROVE) — verify coverage 80%+++Troubleshoot failures: check test isolation → verify mocks → fix implementation (not tests, unless tests are wrong).++## Development Workflow++1. **Plan** — Use planner agent, identify dependencies and risks, break into phases+2. **TDD** — Use tdd-guide agent, write tests first, implement, refactor+3. **Review** — Use code-reviewer agent immediately, address CRITICAL/HIGH issues+4. **Commit** — Conventional commits format, comprehensive PR summaries++## Git Workflow++**Commit format:** `<type>: <description>` — Types: feat, fix, refactor, docs, test, chore, perf, ci++**PR workflow:** Analyze full commit history → draft comprehensive summary → include test plan → push with `-u` flag.++## Architecture Patterns++**API response format:** Consistent envelope with success indicator, data payload, error message, and pagination metadata.++**Repository pattern:** Encapsulate data access behind standard interface (findAll, findById, create, update, delete). Business logic depends on abstract interface, not storage mechanism.++**Skeleton projects:** Search for battle-tested templates, evaluate with parallel agents (security, extensibility, relevance), clone best match, iterate within proven structure.++## Performance++**Context management:** Avoid last 20% of context window for large refactoring and multi-file features. Lower-sensitivity tasks (single edits, docs, simple fixes) tolerate higher utilization.++**Build troubleshooting:** Use build-error-resolver agent → analyze errors → fix incrementally → verify after each fix.++## Project Structure++```+agents/ — 13 specialized subagents+skills/ — 50+ workflow skills and domain knowledge+commands/ — 33 slash commands+hooks/ — Trigger-based automations+rules/ — Always-follow guidelines (common + per-language)+scripts/ — Cross-platform Node.js utilities+mcp-configs/ — 14 MCP server configurations+tests/ — Test suite+```++## Success Metrics++- All tests pass with 80%+ coverage+- No security vulnerabilities+- Code is readable and maintainable+- Performance is acceptable+- User requirements are metdiff --git a/README.md b/README.mdindex eb01c6f9e..70acfcff3 100644--- a/README.md+++ b/README.md@@ -774,31 +774,102 @@ Please contribute! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.## Cursor IDE Support-ecc-universal includes pre-translated configurations for [Cursor IDE](https://cursor.com). The `.cursor/` directory contains rules, agents, skills, commands, and MCP configs adapted for Cursor's format.+ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's native format.### Quick Start (Cursor)```bash-# Install the package-npm install ecc-universal-# Install for your language(s)./install.sh --target cursor typescript-./install.sh --target cursor python golang+./install.sh --target cursor python golang swift+```++### What's Included++| Component | Count | Details |+|-----------|-------|---------|+| Hook Events | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more |+| Hook Scripts | 16 | Thin Node.js scripts delegating to `scripts/hooks/` via shared adapter |+| Rules | 29 | 9 common (alwaysApply) + 20 language-specific (TypeScript, Python, Go, Swift) |+| Agents | Shared | Via AGENTS.md at root (read by Cursor natively) |+| Skills | Shared | Via AGENTS.md at root |+| Commands | Shared | `.cursor/commands/` if installed |+| MCP Config | Shared | `.cursor/mcp.json` if installed |++### Hook Architecture (DRY Adapter Pattern)++Cursor has **more hook events than Claude Code** (20 vs 8). The `.cursor/hooks/adapter.js` module transforms Cursor's stdin JSON to Claude Code's format, allowing existing `scripts/hooks/*.js` to be reused without duplication.++```+Cursor stdin JSON → adapter.js → transforms → scripts/hooks/*.js+ (shared with Claude Code)```-### What's Translated+Key hooks:+- **beforeShellExecution** — Blocks dev servers outside tmux (exit 2), git push review+- **afterFileEdit** — Auto-format + TypeScript check + console.log warning+- **beforeSubmitPrompt** — Detects secrets (sk-, ghp_, AKIA patterns) in prompts+- **beforeTabFileRead** — Blocks Tab from reading .env, .key, .pem files (exit 2)+- **beforeMCPExecution / afterMCPExecution** — MCP audit logging-| Component | Claude Code → Cursor | Parity |-|-----------|---------------------|--------|-| Rules | YAML frontmatter added, paths flattened | Full |-| Agents | Model IDs expanded, tools → readonly flag | Full |-| Skills | No changes needed (identical standard) | Identical |-| Commands | Path references updated, multi-* stubbed | Partial |-| MCP Config | Env interpolation syntax updated | Full |-| Hooks | No equivalent in Cursor | See alternatives |+### Rules Format-See [.cursor/README.md](.cursor/README.md) for details and [.cursor/MIGRATION.md](.cursor/MIGRATION.md) for the full migration guide.+Cursor rules use YAML frontmatter with `description`, `globs`, and `alwaysApply`:++```yaml+---+description: "TypeScript coding style extending common rules"+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]+alwaysApply: false+---+```++---++## Codex CLI Support++ECC provides **first-class Codex CLI support** with a reference configuration, Codex-specific AGENTS.md supplement, and 10 ported skills.++### Quick Start (Codex)++```bash+# Copy the reference config to your home directory+cp .codex/config.toml ~/.codex/config.toml++# Run Codex in the repo — AGENTS.md is auto-detected+codex+```++### What's Included++| Component | Count | Details |+|-----------|-------|---------|+| Config | 1 | `.codex/config.toml` — model, permissions, MCP servers, persistent instructions |+| AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) |+| Skills | 10 | `.agents/skills/` — SKILL.md + agents/openai.yaml per skill |+| MCP Servers | 4 | GitHub, Context7, Memory, Sequential Thinking (command-based) |+| Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) |++### Skills++Skills at `.agents/skills/` are auto-loaded by Codex:++| Skill | Description |+|-------|-------------|+| tdd-workflow | Test-driven development with 80%+ coverage |+| security-review | Comprehensive security checklist |+| coding-standards | Universal coding standards |+| frontend-patterns | React/Next.js patterns |+| backend-patterns | API design, database, caching |+| e2e-testing | Playwright E2E tests |+| eval-harness | Eval-driven development |+| strategic-compact | Context management |+| api-design | REST API design patterns |+| verification-loop | Build, test, lint, typecheck, security |++### Key Limitation++Codex CLI does **not yet support hooks** ([GitHub Issue #2109](https://github.com/openai/codex/issues/2109), 430+ upvotes). Security enforcement is instruction-based via `persistent_instructions` in config.toml and the sandbox permission system.---@@ -823,12 +894,12 @@ The configuration is automatically detected from `.opencode/opencode.json`.| Feature | Claude Code | OpenCode | Status ||---------|-------------|----------|--------|| Agents | ✅ 13 agents | ✅ 12 agents | **Claude Code leads** |-| Commands | ✅ 32 commands | ✅ 24 commands | **Claude Code leads** |-| Skills | ✅ 48 skills | ✅ 16 skills | **Claude Code leads** |-| Hooks | ✅ 3 phases | ✅ 20+ events | **OpenCode has more!** |-| Rules | ✅ 8 rules | ✅ 8 rules | **Full parity** |-| MCP Servers | ✅ Full | ✅ Full | **Full parity** |-| Custom Tools | ✅ Via hooks | ✅ Native support | **OpenCode is better** |+| Commands | ✅ 33 commands | ✅ 24 commands | **Claude Code leads** |+| Skills | ✅ 50+ skills | ✅ 37 skills | **Claude Code leads** |+| Hooks | ✅ 8 event types | ✅ 11 events | **OpenCode has more!** |+| Rules | ✅ 29 rules | ✅ 13 instructions | **Claude Code leads** |+| MCP Servers | ✅ 14 servers | ✅ Full | **Full parity** |+| Custom Tools | ✅ Via hooks | ✅ 6 native tools | **OpenCode is better** |### Hook Support via Plugins@@ -910,6 +981,34 @@ Then add to your `opencode.json`:---+## Cross-Tool Feature Parity++ECC is the **first plugin to maximize every major AI coding tool**. Here's how each harness compares:++| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode |+|---------|------------|------------|-----------|----------|+| **Agents** | 13 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |+| **Commands** | 33 | Shared | Instruction-based | 24 |+| **Skills** | 50+ | Shared | 10 (native format) | 37 |+| **Hook Events** | 8 types | 15 types | None yet | 11 types |+| **Hook Scripts** | 9 scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |+| **Rules** | 29 (common + lang) | 29 (YAML frontmatter) | Instruction-based | 13 instructions |+| **Custom Tools** | Via hooks | Via hooks | N/A | 6 native tools |+| **MCP Servers** | 14 | Shared (mcp.json) | 4 (command-based) | Full |+| **Config Format** | settings.json | hooks.json + rules/ | config.toml | opencode.json |+| **Context File** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md |+| **Secret Detection** | Hook-based | beforeSubmitPrompt hook | Sandbox-based | Hook-based |+| **Auto-Format** | PostToolUse hook | afterFileEdit hook | N/A | file.edited hook |+| **Version** | Plugin | Plugin | Reference config | 1.6.0 |++**Key architectural decisions:**+- **AGENTS.md** at root is the universal cross-tool file (read by all 4 tools)+- **DRY adapter pattern** lets Cursor reuse Claude Code's hook scripts without duplication+- **Skills format** (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode+- Codex's lack of hooks is compensated by `persistent_instructions` and sandbox permissions++---+## 📖 BackgroundI've been using Claude Code since the experimental rollout. Won the Anthropic x Forum Ventures hackathon in Sep 2025 building [zenith.chat](https://zenith.chat) with [@DRodriguezFX](https://x.com/DRodriguezFX) - entirely using Claude Code.diff --git a/examples/sessions/2026-01-17-debugging-memory.tmp b/examples/sessions/2026-01-17-debugging-memory.tmpdeleted file mode 100644index 1d0fb6fd3..000000000--- a/examples/sessions/2026-01-17-debugging-memory.tmp+++ /dev/null@@ -1,54 +0,0 @@-# Session: Memory Leak Investigation-**Date:** 2026-01-17-**Started:** 09:00-**Last Updated:** 12:00-------## Current State--Investigating memory leak in production. Heap growing unbounded over 24h period.--### Completed-- [x] Set up heap snapshots in staging-- [x] Identified leak source: event listeners not being cleaned up-- [x] Fixed leak in WebSocket handler-- [x] Verified fix with 4h soak test--### Root Cause-WebSocket `onMessage` handlers were being added on reconnect but not removed on disconnect. After ~1000 reconnects, memory grew from 200MB to 2GB.--### The Fix-```javascript-// Before (leaking)-socket.on('connect', () => {- socket.on('message', handleMessage)-})--// After (fixed)-socket.on('connect', () => {- socket.off('message', handleMessage) // Remove old listener first- socket.on('message', handleMessage)-})--// Even better - use once or cleanup on disconnect-socket.on('disconnect', () => {- socket.removeAllListeners('message')-})-```--### Debugging Technique Worth Saving-1. Take heap snapshot at T=0-2. Force garbage collection: `global.gc()`-3. Run suspected operation N times-4. Take heap snapshot at T=1-5. Compare snapshots - look for objects with count = N--### Notes for Next Session-- Add memory monitoring alert at 1GB threshold-- Document this debugging pattern for team--### Context to Load-```-src/services/websocket.js-```diff --git a/examples/sessions/2026-01-19-refactor-api.tmp b/examples/sessions/2026-01-19-refactor-api.tmpdeleted file mode 100644index df1049420..000000000--- a/examples/sessions/2026-01-19-refactor-api.tmp+++ /dev/null@@ -1,43 +0,0 @@-# Session: API Refactor - Error Handling-**Date:** 2026-01-19-**Started:** 10:00-**Last Updated:** 13:30-------## Current State--Standardizing error handling across all API endpoints. Moving from ad-hoc try/catch to centralized error middleware.--### Completed-- [x] Created AppError class with status codes-- [x] Built global error handler middleware-- [x] Migrated `/users` routes to new pattern-- [x] Migrated `/products` routes--### Key Findings-- 47 endpoints with inconsistent error responses-- Some returning `{ error: message }`, others `{ message: message }`-- No consistent HTTP status codes--### Error Response Standard-```javascript-{- success: false,- error: {- code: 'VALIDATION_ERROR',- message: 'Email is required',- field: 'email' // optional, for validation errors- }-}-```--### Notes for Next Session-- Migrate remaining routes: `/orders`, `/payments`, `/admin`-- Add error logging to monitoring service--### Context to Load-```-src/middleware/errorHandler.js-src/utils/AppError.js-```diff --git a/examples/sessions/2026-01-20-feature-auth.tmp b/examples/sessions/2026-01-20-feature-auth.tmpdeleted file mode 100644index 20a59506d..000000000--- a/examples/sessions/2026-01-20-feature-auth.tmp+++ /dev/null@@ -1,76 +0,0 @@-# Session: Auth Feature Implementation-**Date:** 2026-01-20-**Started:** 14:30-**Last Updated:** 17:45-------## Current State--Working on JWT authentication flow for the API. Main goal is replacing session-based auth with stateless tokens.--### Completed-- [x] Set up JWT signing with RS256-- [x] Created `/auth/login` endpoint-- [x] Added refresh token rotation-- [x] Fixed token expiry bug (was using seconds, needed milliseconds)--### In Progress-- [ ] Add rate limiting to auth endpoints-- [ ] Implement token blacklist for logout--### Blockers Encountered-1. **jsonwebtoken version mismatch** - v9.x changed the `verify()` signature, had to update error handling-2. **Redis TTL for refresh tokens** - Was setting TTL in seconds but passing milliseconds--### Key Decisions Made-- Using RS256 over HS256 for better security with distributed services-- Storing refresh tokens in Redis with 7-day TTL-- Access tokens expire in 15 minutes--### Code Locations Modified-- `src/middleware/auth.js` - JWT verification middleware-- `src/routes/auth.js` - Login/logout/refresh endpoints-- `src/services/token.service.js` - Token generation and validation--### Notes for Next Session-- Need to add CSRF protection for cookie-based token storage-- Consider adding fingerprinting for refresh token binding-- Review rate limit values with team--### Context to Load-```-src/middleware/-src/routes/auth.js-src/services/token.service.js-```-------## Session Log--**14:30** - Started session, goal is JWT implementation--**14:45** - Set up basic JWT signing. Using RS256 with key pair stored in env vars.--**15:20** - Login endpoint working. Discovered jsonwebtoken v9 breaking change - `verify()` now throws different error types. Updated catch block:-```javascript-// Old (v8)-if (err.name === 'TokenExpiredError') { ... }--// New (v9)-if (err instanceof jwt.TokenExpiredError) { ... }-```--**16:00** - Refresh token rotation working but tokens expiring immediately. Bug: was passing `Date.now()` (milliseconds) to `expiresIn` which expects seconds. Fixed:-```javascript-// Wrong-expiresIn: Date.now() + 900000--// Correct-expiresIn: '15m'-```--**17:30** - Auth flow complete. Login -> access token -> refresh -> new tokens. Ready for rate limiting tomorrow.--**17:45** - Saving session state.diff --git a/install.sh b/install.shindex 0b468f7db..dbc2c959e 100755--- a/install.sh+++ b/install.sh@@ -162,6 +162,17 @@ if [[ "$TARGET" == "cursor" ]]; thencp -r "$CURSOR_SRC/commands/." "$DEST_DIR/commands/"fi+ # --- Hooks ---+ if [[ -f "$CURSOR_SRC/hooks.json" ]]; then+ echo "Installing hooks config -> $DEST_DIR/hooks.json"+ cp "$CURSOR_SRC/hooks.json" "$DEST_DIR/hooks.json"+ fi+ if [[ -d "$CURSOR_SRC/hooks" ]]; then+ echo "Installing hook scripts -> $DEST_DIR/hooks/"+ mkdir -p "$DEST_DIR/hooks"+ cp -r "$CURSOR_SRC/hooks/." "$DEST_DIR/hooks/"+ fi+# --- MCP Config ---if [[ -f "$CURSOR_SRC/mcp.json" ]]; thenecho "Installing MCP config -> $DEST_DIR/mcp.json"diff --git a/package.json b/package.jsonindex e58f63e77..5a9f15359 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ecc-universal",- "version": "1.4.1",+ "version": "1.6.0","description": "Complete collection of battle-tested Claude Code configs — agents, skills, hooks, commands, and rules evolved over 10+ months of intensive daily use by an Anthropic hackathon winner","keywords": ["claude-code",