Initial commit

commands/api/api-new.md

@@ -0,0 +1,389 @@
+# Create New API Endpoint (RepairCoin)
+
+Create a new API endpoint for RepairCoin. This command supports both:
+1. **Backend Express API** (Domain-Driven Design) - Primary use case
+2. **Frontend Next.js API Routes** - For frontend-only features
+
+---
+
+## Part 1: Backend Express API (Primary)
+
+Use this for main backend features requiring database access, blockchain interaction, or cross-domain events.
+
+### Architecture
+
+RepairCoin uses Domain-Driven Design with these domains:
+- **admin** - Platform analytics, treasury, user management
+- **customer** - Customer management, tiers, referrals, balances
+- **shop** - Shop subscriptions, RCN purchasing, reward issuance
+- **token** - RCN/RCG minting, redemption, cross-shop transfers
+- **webhook** - FixFlow and Stripe webhook processing
+
+### Directory Structure
+
+```
+backend/src/domains/{domain}/
+├── {Domain}Domain.ts           # Domain module
+├── routes/
+│   ├── index.ts               # Main router
+│   └── {feature}.ts           # Feature routes
+├── controllers/
+│   └── {Feature}Controller.ts
+└── services/
+    └── {Feature}Service.ts
+```
+
+### Step 1: Create Routes File
+
+**Path**: `backend/src/domains/{domain}/routes/{feature}.ts`
+
+```typescript
+import { Router } from 'express';
+import { requireRole, authMiddleware } from '../../../middleware/auth';
+import {
+  validateRequired,
+  validateEthereumAddress,
+  validateEmail,
+  validateNumeric,
+  asyncHandler
+} from '../../../middleware/errorHandler';
+import { {Feature}Controller } from '../controllers/{Feature}Controller';
+import { {Feature}Service } from '../services/{Feature}Service';
+
+const router = Router();
+
+// Initialize service and controller
+const {feature}Service = new {Feature}Service();
+const {feature}Controller = new {Feature}Controller({feature}Service);
+
+/**
+ * @swagger
+ * /api/{domain}/{feature}:
+ *   post:
+ *     summary: {Description}
+ *     tags: [{Domain}]
+ *     security:
+ *       - bearerAuth: []
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - field1
+ *             properties:
+ *               field1:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Success
+ */
+router.post('/{feature}',
+  authMiddleware,
+  requireRole(['admin', 'shop']),
+  validateRequired(['field1']),
+  asyncHandler({feature}Controller.{method}.bind({feature}Controller))
+);
+
+export default router;
+```
+
+### Step 2: Create Controller
+
+**Path**: `backend/src/domains/{domain}/controllers/{Feature}Controller.ts`
+
+```typescript
+import { Request, Response } from 'express';
+import { {Feature}Service } from '../services/{Feature}Service';
+import { ResponseHelper } from '../../../utils/responseHelper';
+
+export class {Feature}Controller {
+  constructor(private {feature}Service: {Feature}Service) {}
+
+  async {method}(req: Request, res: Response) {
+    try {
+      const { field1, field2 } = req.body;
+      const { id } = req.params;
+
+      const result = await this.{feature}Service.{method}({
+        field1,
+        field2,
+        id,
+        userAddress: req.user?.address,
+        userRole: req.user?.role
+      });
+
+      ResponseHelper.success(res, result);
+    } catch (error: unknown) {
+      const err = error as Error;
+      if (err.message === 'Not found') {
+        ResponseHelper.notFound(res, err.message);
+      } else if (err.message === 'Unauthorized') {
+        ResponseHelper.forbidden(res, err.message);
+      } else if (err.message.includes('already exists')) {
+        ResponseHelper.conflict(res, err.message);
+      } else {
+        ResponseHelper.error(res, err.message, 500);
+      }
+    }
+  }
+}
+```
+
+### Step 3: Create Service
+
+**Path**: `backend/src/domains/{domain}/services/{Feature}Service.ts`
+
+```typescript
+import { logger } from '../../../utils/logger';
+import { {Entity}Repository } from '../../../repositories/{Entity}Repository';
+import { eventBus, createDomainEvent } from '../../../events/EventBus';
+
+interface {Method}Input {
+  field1: string;
+  field2?: number;
+  userAddress?: string;
+  userRole?: string;
+}
+
+export class {Feature}Service {
+  private {entity}Repository: {Entity}Repository;
+
+  constructor() {
+    this.{entity}Repository = new {Entity}Repository();
+  }
+
+  async {method}(input: {Method}Input): Promise<unknown> {
+    logger.info('{Feature}Service.{method} called', { input });
+
+    try {
+      // Validation
+      if (!input.field1) {
+        throw new Error('field1 is required');
+      }
+
+      // Authorization
+      if (input.userRole !== 'admin') {
+        throw new Error('Unauthorized');
+      }
+
+      // Business logic
+      const result = await this.{entity}Repository.{operation}({
+        field1: input.field1
+      });
+
+      if (!result) {
+        throw new Error('Not found');
+      }
+
+      // Publish event
+      await eventBus.publish(createDomainEvent(
+        '{domain}.{event}',
+        result.id,
+        { field1: input.field1 },
+        '{Feature}Service'
+      ));
+
+      logger.info('{Feature}Service.{method} completed');
+
+      return {
+        success: true,
+        data: result
+      };
+    } catch (error: unknown) {
+      const err = error as Error;
+      logger.error('{Feature}Service.{method} error', {
+        error: err.message
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Step 4: Register Routes
+
+Update `backend/src/domains/{domain}/routes/index.ts`:
+
+```typescript
+import { Router } from 'express';
+import {feature}Routes from './{feature}';
+
+const router = Router();
+
+router.use('/{feature}', {feature}Routes);
+
+export default router;
+```
+
+### Middleware Options
+
+```typescript
+// Authentication
+authMiddleware                              // JWT auth
+
+// Authorization
+requireRole(['admin'])                      // Admin only
+requireRole(['admin', 'shop'])              // Admin or Shop
+requireRole(['customer'])                   // Customer only
+
+// Validation
+validateRequired(['field1', 'field2'])      // Required fields
+validateEthereumAddress('walletAddress')    // Ethereum address
+validateEmail('email')                      // Email format
+validateNumeric('amount', 0.1, 1000)        // Numeric range
+```
+
+### Response Helpers
+
+```typescript
+ResponseHelper.success(res, data, 'Message');
+ResponseHelper.created(res, data, 'Created');
+ResponseHelper.badRequest(res, 'Validation error');
+ResponseHelper.unauthorized(res, 'Auth required');
+ResponseHelper.forbidden(res, 'Insufficient permissions');
+ResponseHelper.notFound(res, 'Not found');
+ResponseHelper.conflict(res, 'Already exists');
+ResponseHelper.error(res, 'Internal error', 500);
+```
+
+### Testing
+
+**Path**: `backend/tests/{domain}/{feature}.test.ts`
+
+```typescript
+import request from 'supertest';
+import { describe, it, expect, beforeAll } from '@jest/globals';
+import RepairCoinApp from '../../src/app';
+
+describe('{Feature} API', () => {
+  let app: unknown;
+  let token: string;
+
+  beforeAll(async () => {
+    process.env.NODE_ENV = 'test';
+    const repairCoinApp = new RepairCoinApp();
+    await repairCoinApp.initialize();
+    app = repairCoinApp.app;
+
+    const auth = await request(app as any)
+      .post('/api/auth/admin')
+      .send({ walletAddress: process.env.ADMIN_ADDRESSES?.split(',')[0] });
+    token = auth.body.token;
+  });
+
+  it('should create {feature}', async () => {
+    const response = await request(app as any)
+      .post('/api/{domain}/{feature}')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ field1: 'value1' });
+
+    expect(response.status).toBe(200);
+    expect(response.body.success).toBe(true);
+  });
+
+  it('should reject unauthorized', async () => {
+    const response = await request(app as any)
+      .post('/api/{domain}/{feature}')
+      .send({ field1: 'value1' });
+
+    expect(response.status).toBe(401);
+  });
+});
+```
+
+### Checklist
+
+- [ ] Identified correct domain
+- [ ] Created routes file with middleware
+- [ ] Created controller with error handling
+- [ ] Created service with business logic
+- [ ] Registered routes in domain index
+- [ ] Added Swagger documentation
+- [ ] Added TypeScript types (no `any`)
+- [ ] Implemented auth/validation
+- [ ] Published domain events if needed
+- [ ] Created integration tests
+- [ ] Tested with auth token
+
+---
+
+## Part 2: Frontend Next.js API Route (Secondary)
+
+Use this for frontend-only features (e.g., client-side data transformation, SSR helpers).
+
+### Directory Structure
+
+```
+frontend/app/api/{route}/route.ts
+```
+
+### Implementation
+
+```typescript
+import { NextRequest, NextResponse } from 'next';
+import { z } from 'zod';
+
+// Validation schema
+const RequestSchema = z.object({
+  field1: z.string().min(1),
+  field2: z.number().optional()
+});
+
+type RequestBody = z.infer<typeof RequestSchema>;
+
+// Response helper
+function success<T>(data: T) {
+  return NextResponse.json({ success: true, data });
+}
+
+function error(message: string, status: number = 500) {
+  return NextResponse.json(
+    { success: false, error: message },
+    { status }
+  );
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const body: unknown = await req.json();
+
+    // Validate
+    const validated = RequestSchema.parse(body) as RequestBody;
+
+    // Business logic
+    const result = {
+      id: '123',
+      ...validated
+    };
+
+    return success(result);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      return error(err.errors[0].message, 400);
+    }
+    return error('Internal error');
+  }
+}
+```
+
+---
+
+## Important Notes
+
+1. **Never use `any` type** - Always use proper TypeScript types
+2. **Always use asyncHandler** - For Express route error handling
+3. **Use ResponseHelper** - Consistent API responses
+4. **Bind controller methods** - `.bind(controller)` in routes
+5. **Validate inputs** - Use validation middleware
+6. **Check authorization** - In service layer
+7. **Log operations** - Use logger for debugging
+8. **Publish events** - For cross-domain communication
+9. **Write tests** - Integration tests with auth
+
+## Examples
+
+- Customer API: `backend/src/domains/customer/`
+- Shop API: `backend/src/domains/shop/routes/subscription.ts`
+- Token API: `backend/src/domains/token/routes/redemptionSession.ts`

commands/api/api-protect.md

@@ -0,0 +1,147 @@
+---
+description: Add authentication, authorization, and security to API endpoints
+model: claude-sonnet-4-5
+---
+
+Add comprehensive security, authentication, and authorization to the specified API route.
+
+## Target API Route
+
+$ARGUMENTS
+
+## Security Layers to Implement
+
+###1. **Authentication** (Who are you?)
+- Verify user identity
+- Token validation (JWT, session, API keys)
+- Handle expired/invalid tokens
+
+### 2. **Authorization** (What can you do?)
+- Role-based access control (RBAC)
+- Resource-level permissions
+- Check user ownership
+
+### 3. **Input Validation**
+- Sanitize all inputs
+- SQL/NoSQL injection prevention
+- XSS prevention
+- Type validation with Zod
+
+### 4. **Rate Limiting**
+- Prevent abuse
+- Per-user/IP limits
+- Sliding window algorithm
+
+### 5. **CORS** (if needed)
+- Whitelist allowed origins
+- Proper headers
+- Credentials handling
+
+## Implementation Approach
+
+### For Supabase Projects:
+```typescript
+// Use Supabase Auth + RLS
+- getUser() from server-side client
+- RLS policies for data access
+- Service role key for admin operations
+```
+
+### For NextAuth.js Projects:
+```typescript
+// Use NextAuth sessions
+- getServerSession() in route handlers
+- Protect with middleware
+- Role checking logic
+```
+
+### For Custom Auth:
+```typescript
+// JWT validation
+- Verify tokens
+- Decode and validate claims
+- Check expiration
+```
+
+## Security Checklist
+
+**Authentication**
+-  Verify authentication tokens
+-  Handle missing/invalid tokens (401)
+-  Check token expiration
+-  Secure token storage recommendations
+
+**Authorization**
+-  Check user roles/permissions (403)
+-  Verify resource ownership
+-  Implement least privilege principle
+-  Log authorization failures
+
+**Input Validation**
+-  Validate all inputs with Zod
+-  Sanitize SQL/NoSQL inputs
+-  Escape special characters
+-  Limit payload sizes
+
+**Rate Limiting**
+-  Per-user limits
+-  Per-IP limits
+-  Clear error messages (429)
+-  Retry-After headers
+
+**CORS**
+-  Whitelist specific origins
+-  Handle preflight requests
+-  Secure credentials
+-  Appropriate headers
+
+**Error Handling**
+-  Don't expose stack traces
+-  Generic error messages
+-  Log detailed errors server-side
+-  Consistent error format
+
+**Logging & Monitoring**
+-  Log authentication attempts
+-  Log authorization failures
+-  Track suspicious activity
+-  Monitor rate limit hits
+
+## What to Generate
+
+1. **Protected Route Handler** - Secured version of the API route
+2. **Middleware/Utilities** - Reusable auth helpers
+3. **Type Definitions** - User, permissions, roles
+4. **Error Responses** - Standardized auth errors
+5. **Usage Examples** - Client-side integration
+
+## Common Patterns for Solo Developers
+
+**Pattern 1: Simple Token Auth**
+```typescript
+// For internal tools, admin panels
+const token = request.headers.get('authorization')
+if (token !== process.env.ADMIN_TOKEN) {
+  return new Response('Unauthorized', { status: 401 })
+}
+```
+
+**Pattern 2: User-based Auth**
+```typescript
+// For user-facing apps
+const user = await getCurrentUser(request)
+if (!user) {
+  return new Response('Unauthorized', { status: 401 })
+}
+```
+
+**Pattern 3: Role-based Auth**
+```typescript
+// For apps with different user types
+const user = await getCurrentUser(request)
+if (!user || !hasRole(user, 'admin')) {
+  return new Response('Forbidden', { status: 403 })
+}
+```
+
+Generate production-ready, secure code that follows the principle of least privilege.

commands/api/api-test.md

@@ -0,0 +1,116 @@
+---
+description: Test API endpoints with automated test generation
+model: claude-sonnet-4-5
+---
+
+Generate comprehensive API tests for the specified endpoint.
+
+## Target
+
+$ARGUMENTS
+
+## Test Strategy for Solo Developers
+
+Create practical, maintainable tests using modern tools:
+
+### 1. **Testing Approach**
+- Unit tests for validation logic
+- Integration tests for full API flow
+- Edge case coverage
+- Error scenario testing
+
+### 2. **Tools** (choose based on project)
+- **Vitest** - Fast, modern (recommended for new projects)
+- **Jest** - Established, widely used
+- **Supertest** - HTTP assertions
+- **MSW** - API mocking
+
+### 3. **Test Coverage**
+
+**Happy Paths**
+- Valid inputs return expected results
+- Proper status codes
+- Correct response structure
+
+**Error Paths**
+- Invalid input validation
+- Authentication failures
+- Rate limiting
+- Server errors
+- Missing required fields
+
+**Edge Cases**
+- Empty requests
+- Malformed JSON
+- Large payloads
+- Special characters
+- SQL injection attempts
+- XSS attempts
+
+### 4. **Test Structure**
+
+```typescript
+describe('API Endpoint', () => {
+  describe('Success Cases', () => {
+    it('should handle valid request', () => {})
+    it('should return correct status code', () => {})
+  })
+
+  describe('Validation', () => {
+    it('should reject invalid input', () => {})
+    it('should validate required fields', () => {})
+  })
+
+  describe('Error Handling', () => {
+    it('should handle server errors', () => {})
+    it('should return proper error format', () => {})
+  })
+})
+```
+
+### 5. **What to Generate**
+
+1. **Test File** - Complete test suite with all scenarios
+2. **Mock Data** - Realistic test fixtures
+3. **Helper Functions** - Reusable test utilities
+4. **Setup/Teardown** - Database/state management
+5. **Quick Test Script** - npm script to run tests
+
+## Key Testing Principles
+
+-  Test behavior, not implementation
+-  Clear, descriptive test names
+-  Arrange-Act-Assert pattern
+-  Independent tests (no shared state)
+-  Fast execution (<5s for unit tests)
+-  Realistic mock data
+-  Test error messages
+- L Don't test framework internals
+- L Don't mock what you don't own
+- L Avoid brittle tests
+
+## Additional Scenarios to Cover
+
+1. **Authentication/Authorization**
+   - Valid tokens
+   - Expired tokens
+   - Missing tokens
+   - Invalid permissions
+
+2. **Data Validation**
+   - Type mismatches
+   - Out of range values
+   - SQL/NoSQL injection
+   - XSS payloads
+
+3. **Rate Limiting**
+   - Within limits
+   - Exceeding limits
+   - Reset behavior
+
+4. **Performance**
+   - Response times
+   - Large dataset handling
+   - Concurrent requests
+
+Generate production-ready tests I can run immediately with `npm test`.

commands/misc/code-cleanup.md

@@ -0,0 +1,207 @@
+---
+description: Refactor and clean up code following best practices
+model: claude-sonnet-4-5
+---
+
+Clean up and refactor the following code to improve readability, maintainability, and follow best practices.
+
+## Code to Clean
+
+$ARGUMENTS
+
+## Cleanup Checklist for Solo Developers
+
+### 1. **Code Smells to Fix**
+
+**Naming**
+-  Descriptive variable/function names
+-  Consistent naming conventions (camelCase, PascalCase)
+-  Avoid abbreviations unless obvious
+-  Boolean names start with is/has/can
+
+**Functions**
+-  Single responsibility per function
+-  Keep functions small (<50 lines)
+-  Reduce parameters (max 3-4)
+-  Extract complex logic
+-  Avoid side effects where possible
+
+**DRY (Don't Repeat Yourself)**
+-  Extract repeated code to utilities
+-  Create reusable components
+-  Use TypeScript generics for type reuse
+-  Centralize constants/configuration
+
+**Complexity**
+-  Reduce nested if statements
+-  Replace complex conditions with functions
+-  Use early returns
+-  Simplify boolean logic
+
+**TypeScript**
+-  Remove `any` types
+-  Add proper type annotations
+-  Use interfaces for object shapes
+-  Leverage utility types (Pick, Omit, Partial)
+
+### 2. **Modern Patterns to Apply**
+
+**JavaScript/TypeScript**
+```typescript
+// Use optional chaining
+const value = obj?.prop?.nested
+
+// Use nullish coalescing
+const result = value ?? defaultValue
+
+// Use destructuring
+const { name, email } = user
+
+// Use template literals
+const message = `Hello, ${name}!`
+
+// Use array methods
+const filtered = arr.filter(x => x.active)
+```
+
+**React**
+```typescript
+// Extract custom hooks
+const useUserData = () => {
+  // logic here
+}
+
+// Use proper TypeScript types
+interface Props {
+  user: User
+  onUpdate: (user: User) => void
+}
+
+// Avoid prop drilling with composition
+<Provider value={data}>
+  <Component />
+</Provider>
+```
+
+### 3. **Refactoring Techniques**
+
+**Extract Function**
+```typescript
+// Before
+const process = () => {
+  // 50 lines of code
+}
+
+// After
+const validate = () => { /* ... */ }
+const transform = () => { /* ... */ }
+const save = () => { /* ... */ }
+
+const process = () => {
+  validate()
+  const data = transform()
+  save(data)
+}
+```
+
+**Replace Conditional with Polymorphism**
+```typescript
+// Before
+if (type === 'A') return processA()
+if (type === 'B') return processB()
+
+// After
+const processors = {
+  A: processA,
+  B: processB
+}
+return processors[type]()
+```
+
+**Introduce Parameter Object**
+```typescript
+// Before
+function create(name, email, age, address)
+
+// After
+interface UserData {
+  name: string
+  email: string
+  age: number
+  address: string
+}
+function create(userData: UserData)
+```
+
+### 4. **Common Cleanup Tasks**
+
+**Remove Dead Code**
+- Unused imports
+- Unreachable code
+- Commented out code
+- Unused variables
+
+**Improve Error Handling**
+```typescript
+// Before
+try { doSomething() } catch (e) { console.log(e) }
+
+// After
+try {
+  doSomething()
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // Handle validation
+  } else {
+    logger.error('Unexpected error', { error })
+    throw error
+  }
+}
+```
+
+**Consistent Formatting**
+- Proper indentation
+- Consistent quotes
+- Line length (<100 characters)
+- Organized imports
+
+**Better Comments**
+- Remove obvious comments
+- Add why, not what
+- Document complex logic
+- Update outdated comments
+
+### 5. **Next.js/React Specific**
+
+**Server vs Client Components**
+```typescript
+// Move state to client component
+'use client'
+function Interactive() {
+  const [state, setState] = useState()
+}
+
+// Keep data fetching in server component
+async function Page() {
+  const data = await fetchData()
+}
+```
+
+**Proper Data Fetching**
+```typescript
+// Use SWR/React Query for client
+const { data } = useSWR('/api/user')
+
+// Use direct fetch in server components
+const data = await fetch('/api/user').then(r => r.json())
+```
+
+## Output Format
+
+1. **Issues Found** - List of code smells and problems
+2. **Cleaned Code** - Refactored version
+3. **Explanations** - What changed and why
+4. **Before/After Comparison** - Side-by-side if helpful
+5. **Further Improvements** - Optional enhancements
+
+Focus on practical improvements that make code more maintainable without over-engineering. Balance clean code with pragmatism.

commands/misc/code-explain.md

@@ -0,0 +1,849 @@
+---
+model: claude-sonnet-4-5
+---
+
+# Code Explanation and Analysis
+
+You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable explanations for developers at all levels.
+
+## Context
+
+The user needs help understanding complex code sections, algorithms, design patterns, or system architectures. Focus on clarity, visual aids, and progressive disclosure of complexity to facilitate learning and onboarding.
+
+## Requirements
+
+$ARGUMENTS
+
+## Instructions
+
+### 1. Code Comprehension Analysis
+
+Analyze the code to determine complexity and structure:
+
+**Code Complexity Assessment**
+
+```python
+import ast
+import re
+from typing import Dict, List, Tuple
+
+class CodeAnalyzer:
+    def analyze_complexity(self, code: str) -> Dict:
+        """
+        Analyze code complexity and structure
+        """
+        analysis = {
+            'complexity_score': 0,
+            'concepts': [],
+            'patterns': [],
+            'dependencies': [],
+            'difficulty_level': 'beginner'
+        }
+
+        # Parse code structure
+        try:
+            tree = ast.parse(code)
+
+            # Analyze complexity metrics
+            analysis['metrics'] = {
+                'lines_of_code': len(code.splitlines()),
+                'cyclomatic_complexity': self._calculate_cyclomatic_complexity(tree),
+                'nesting_depth': self._calculate_max_nesting(tree),
+                'function_count': len([n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]),
+                'class_count': len([n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)])
+            }
+
+            # Identify concepts used
+            analysis['concepts'] = self._identify_concepts(tree)
+
+            # Detect design patterns
+            analysis['patterns'] = self._detect_patterns(tree)
+
+            # Extract dependencies
+            analysis['dependencies'] = self._extract_dependencies(tree)
+
+            # Determine difficulty level
+            analysis['difficulty_level'] = self._assess_difficulty(analysis)
+
+        except SyntaxError as e:
+            analysis['parse_error'] = str(e)
+
+        return analysis
+
+    def _identify_concepts(self, tree) -> List[str]:
+        """
+        Identify programming concepts used in the code
+        """
+        concepts = []
+
+        for node in ast.walk(tree):
+            # Async/await
+            if isinstance(node, (ast.AsyncFunctionDef, ast.AsyncWith, ast.AsyncFor)):
+                concepts.append('asynchronous programming')
+
+            # Decorators
+            elif isinstance(node, ast.FunctionDef) and node.decorator_list:
+                concepts.append('decorators')
+
+            # Context managers
+            elif isinstance(node, ast.With):
+                concepts.append('context managers')
+
+            # Generators
+            elif isinstance(node, ast.Yield):
+                concepts.append('generators')
+
+            # List/Dict/Set comprehensions
+            elif isinstance(node, (ast.ListComp, ast.DictComp, ast.SetComp)):
+                concepts.append('comprehensions')
+
+            # Lambda functions
+            elif isinstance(node, ast.Lambda):
+                concepts.append('lambda functions')
+
+            # Exception handling
+            elif isinstance(node, ast.Try):
+                concepts.append('exception handling')
+
+        return list(set(concepts))
+```
+
+### 2. Visual Explanation Generation
+
+Create visual representations of code flow:
+
+**Flow Diagram Generation**
+
+````python
+class VisualExplainer:
+    def generate_flow_diagram(self, code_structure):
+        """
+        Generate Mermaid diagram showing code flow
+        """
+        diagram = "```mermaid\nflowchart TD\n"
+
+        # Example: Function call flow
+        if code_structure['type'] == 'function_flow':
+            nodes = []
+            edges = []
+
+            for i, func in enumerate(code_structure['functions']):
+                node_id = f"F{i}"
+                nodes.append(f"    {node_id}[{func['name']}]")
+
+                # Add function details
+                if func.get('parameters'):
+                    nodes.append(f"    {node_id}_params[/{', '.join(func['parameters'])}/]")
+                    edges.append(f"    {node_id}_params --> {node_id}")
+
+                # Add return value
+                if func.get('returns'):
+                    nodes.append(f"    {node_id}_return[{func['returns']}]")
+                    edges.append(f"    {node_id} --> {node_id}_return")
+
+                # Connect to called functions
+                for called in func.get('calls', []):
+                    called_id = f"F{code_structure['function_map'][called]}"
+                    edges.append(f"    {node_id} --> {called_id}")
+
+            diagram += "\n".join(nodes) + "\n"
+            diagram += "\n".join(edges) + "\n"
+
+        diagram += "```"
+        return diagram
+
+    def generate_class_diagram(self, classes):
+        """
+        Generate UML-style class diagram
+        """
+        diagram = "```mermaid\nclassDiagram\n"
+
+        for cls in classes:
+            # Class definition
+            diagram += f"    class {cls['name']} {{\n"
+
+            # Attributes
+            for attr in cls.get('attributes', []):
+                visibility = '+' if attr['public'] else '-'
+                diagram += f"        {visibility}{attr['name']} : {attr['type']}\n"
+
+            # Methods
+            for method in cls.get('methods', []):
+                visibility = '+' if method['public'] else '-'
+                params = ', '.join(method.get('params', []))
+                diagram += f"        {visibility}{method['name']}({params}) : {method['returns']}\n"
+
+            diagram += "    }\n"
+
+            # Relationships
+            if cls.get('inherits'):
+                diagram += f"    {cls['inherits']} <|-- {cls['name']}\n"
+
+            for composition in cls.get('compositions', []):
+                diagram += f"    {cls['name']} *-- {composition}\n"
+
+        diagram += "```"
+        return diagram
+````
+
+### 3. Step-by-Step Explanation
+
+Break down complex code into digestible steps:
+
+**Progressive Explanation**
+
+````python
+def generate_step_by_step_explanation(self, code, analysis):
+    """
+    Create progressive explanation from simple to complex
+    """
+    explanation = {
+        'overview': self._generate_overview(code, analysis),
+        'steps': [],
+        'deep_dive': [],
+        'examples': []
+    }
+
+    # Level 1: High-level overview
+    explanation['overview'] = f"""
+## What This Code Does
+
+{self._summarize_purpose(code, analysis)}
+
+**Key Concepts**: {', '.join(analysis['concepts'])}
+**Difficulty Level**: {analysis['difficulty_level'].capitalize()}
+"""
+
+    # Level 2: Step-by-step breakdown
+    if analysis.get('functions'):
+        for i, func in enumerate(analysis['functions']):
+            step = f"""
+### Step {i+1}: {func['name']}
+
+**Purpose**: {self._explain_function_purpose(func)}
+
+**How it works**:
+"""
+            # Break down function logic
+            for j, logic_step in enumerate(self._analyze_function_logic(func)):
+                step += f"{j+1}. {logic_step}\n"
+
+            # Add visual flow if complex
+            if func['complexity'] > 5:
+                step += f"\n{self._generate_function_flow(func)}\n"
+
+            explanation['steps'].append(step)
+
+    # Level 3: Deep dive into complex parts
+    for concept in analysis['concepts']:
+        deep_dive = self._explain_concept(concept, code)
+        explanation['deep_dive'].append(deep_dive)
+
+    return explanation
+
+def _explain_concept(self, concept, code):
+    """
+    Explain programming concept with examples
+    """
+    explanations = {
+        'decorators': '''
+## Understanding Decorators
+
+Decorators are a way to modify or enhance functions without changing their code directly.
+
+**Simple Analogy**: Think of a decorator like gift wrapping - it adds something extra around the original item.
+
+**How it works**:
+```python
+# This decorator:
+@timer
+def slow_function():
+    time.sleep(1)
+
+# Is equivalent to:
+def slow_function():
+    time.sleep(1)
+slow_function = timer(slow_function)
+````
+
+**In this code**: The decorator is used to {specific_use_in_code}
+''',
+'generators': '''
+
+## Understanding Generators
+
+Generators produce values one at a time, saving memory by not creating all values at once.
+
+**Simple Analogy**: Like a ticket dispenser that gives one ticket at a time, rather than printing all tickets upfront.
+
+**How it works**:
+
+```python
+# Generator function
+def count_up_to(n):
+    i = 0
+    while i < n:
+        yield i  # Produces one value and pauses
+        i += 1
+
+# Using the generator
+for num in count_up_to(5):
+    print(num)  # Prints 0, 1, 2, 3, 4
+```
+
+**In this code**: The generator is used to {specific_use_in_code}
+'''
+}
+
+    return explanations.get(concept, f"Explanation for {concept}")
+
+````
+
+### 4. Algorithm Visualization
+
+Visualize algorithm execution:
+
+**Algorithm Step Visualization**
+```python
+class AlgorithmVisualizer:
+    def visualize_sorting_algorithm(self, algorithm_name, array):
+        """
+        Create step-by-step visualization of sorting algorithm
+        """
+        steps = []
+
+        if algorithm_name == 'bubble_sort':
+            steps.append("""
+## Bubble Sort Visualization
+
+**Initial Array**: [5, 2, 8, 1, 9]
+
+### How Bubble Sort Works:
+1. Compare adjacent elements
+2. Swap if they're in wrong order
+3. Repeat until no swaps needed
+
+### Step-by-Step Execution:
+""")
+
+            # Simulate bubble sort with visualization
+            arr = array.copy()
+            n = len(arr)
+
+            for i in range(n):
+                swapped = False
+                step_viz = f"\n**Pass {i+1}**:\n"
+
+                for j in range(0, n-i-1):
+                    # Show comparison
+                    step_viz += f"Compare [{arr[j]}] and [{arr[j+1]}]: "
+
+                    if arr[j] > arr[j+1]:
+                        arr[j], arr[j+1] = arr[j+1], arr[j]
+                        step_viz += f"Swap → {arr}\n"
+                        swapped = True
+                    else:
+                        step_viz += "No swap needed\n"
+
+                steps.append(step_viz)
+
+                if not swapped:
+                    steps.append(f"\n✅ Array is sorted: {arr}")
+                    break
+
+        return '\n'.join(steps)
+
+    def visualize_recursion(self, func_name, example_input):
+        """
+        Visualize recursive function calls
+        """
+        viz = f"""
+## Recursion Visualization: {func_name}
+
+### Call Stack Visualization:
+````
+
+{func*name}({example_input})
+│
+├─> Base case check: {example_input} == 0? No
+├─> Recursive call: {func_name}({example_input - 1})
+│ │
+│ ├─> Base case check: {example_input - 1} == 0? No
+│ ├─> Recursive call: {func_name}({example_input - 2})
+│ │ │
+│ │ ├─> Base case check: 1 == 0? No
+│ │ ├─> Recursive call: {func_name}(0)
+│ │ │ │
+│ │ │ └─> Base case: Return 1
+│ │ │
+│ │ └─> Return: 1 * 1 = 1
+│ │
+│ └─> Return: 2 \_ 1 = 2
+│
+└─> Return: 3 \* 2 = 6
+
+```
+
+**Final Result**: {func_name}({example_input}) = 6
+"""
+        return viz
+```
+
+### 5. Interactive Examples
+
+Generate interactive examples for better understanding:
+
+**Code Playground Examples**
+
+````python
+def generate_interactive_examples(self, concept):
+    """
+    Create runnable examples for concepts
+    """
+    examples = {
+        'error_handling': '''
+## Try It Yourself: Error Handling
+
+### Example 1: Basic Try-Except
+```python
+def safe_divide(a, b):
+    try:
+        result = a / b
+        print(f"{a} / {b} = {result}")
+        return result
+    except ZeroDivisionError:
+        print("Error: Cannot divide by zero!")
+        return None
+    except TypeError:
+        print("Error: Please provide numbers only!")
+        return None
+    finally:
+        print("Division attempt completed")
+
+# Test cases - try these:
+safe_divide(10, 2)    # Success case
+safe_divide(10, 0)    # Division by zero
+safe_divide(10, "2")  # Type error
+````
+
+### Example 2: Custom Exceptions
+
+```python
+class ValidationError(Exception):
+    """Custom exception for validation errors"""
+    pass
+
+def validate_age(age):
+    try:
+        age = int(age)
+        if age < 0:
+            raise ValidationError("Age cannot be negative")
+        if age > 150:
+            raise ValidationError("Age seems unrealistic")
+        return age
+    except ValueError:
+        raise ValidationError("Age must be a number")
+
+# Try these examples:
+try:
+    validate_age(25)     # Valid
+    validate_age(-5)     # Negative age
+    validate_age("abc")  # Not a number
+except ValidationError as e:
+    print(f"Validation failed: {e}")
+```
+
+### Exercise: Implement Your Own
+
+Try implementing a function that:
+
+1. Takes a list of numbers
+2. Returns their average
+3. Handles empty lists
+4. Handles non-numeric values
+5. Uses appropriate exception handling
+   ''',
+   'async_programming': '''
+
+## Try It Yourself: Async Programming
+
+### Example 1: Basic Async/Await
+
+```python
+import asyncio
+import time
+
+async def slow_operation(name, duration):
+    print(f"{name} started...")
+    await asyncio.sleep(duration)
+    print(f"{name} completed after {duration}s")
+    return f"{name} result"
+
+async def main():
+    # Sequential execution (slow)
+    start = time.time()
+    await slow_operation("Task 1", 2)
+    await slow_operation("Task 2", 2)
+    print(f"Sequential time: {time.time() - start:.2f}s")
+
+    # Concurrent execution (fast)
+    start = time.time()
+    results = await asyncio.gather(
+        slow_operation("Task 3", 2),
+        slow_operation("Task 4", 2)
+    )
+    print(f"Concurrent time: {time.time() - start:.2f}s")
+    print(f"Results: {results}")
+
+# Run it:
+asyncio.run(main())
+```
+
+### Example 2: Real-world Async Pattern
+
+```python
+async def fetch_data(url):
+    """Simulate API call"""
+    await asyncio.sleep(1)  # Simulate network delay
+    return f"Data from {url}"
+
+async def process_urls(urls):
+    tasks = [fetch_data(url) for url in urls]
+    results = await asyncio.gather(*tasks)
+    return results
+
+# Try with different URLs:
+urls = ["api.example.com/1", "api.example.com/2", "api.example.com/3"]
+results = asyncio.run(process_urls(urls))
+print(results)
+```
+
+'''
+}
+
+    return examples.get(concept, "No example available")
+
+````
+
+### 6. Design Pattern Explanation
+
+Explain design patterns found in code:
+
+**Pattern Recognition and Explanation**
+```python
+class DesignPatternExplainer:
+    def explain_pattern(self, pattern_name, code_example):
+        """
+        Explain design pattern with diagrams and examples
+        """
+        patterns = {
+            'singleton': '''
+## Singleton Pattern
+
+### What is it?
+The Singleton pattern ensures a class has only one instance and provides global access to it.
+
+### When to use it?
+- Database connections
+- Configuration managers
+- Logging services
+- Cache managers
+
+### Visual Representation:
+```mermaid
+classDiagram
+    class Singleton {
+        -instance: Singleton
+        -__init__()
+        +getInstance(): Singleton
+    }
+    Singleton --> Singleton : returns same instance
+````
+
+### Implementation in this code:
+
+{code_analysis}
+
+### Benefits:
+
+✅ Controlled access to single instance
+✅ Reduced namespace pollution
+✅ Permits refinement of operations
+
+### Drawbacks:
+
+❌ Can make unit testing difficult
+❌ Violates Single Responsibility Principle
+❌ Can hide dependencies
+
+### Alternative Approaches:
+
+1. Dependency Injection
+2. Module-level singleton
+3. Borg pattern
+   ''',
+   'observer': '''
+
+## Observer Pattern
+
+### What is it?
+
+The Observer pattern defines a one-to-many dependency between objects so that when one object changes state, all dependents are notified.
+
+### When to use it?
+
+- Event handling systems
+- Model-View architectures
+- Distributed event handling
+
+### Visual Representation:
+
+```mermaid
+classDiagram
+    class Subject {
+        +attach(Observer)
+        +detach(Observer)
+        +notify()
+    }
+    class Observer {
+        +update()
+    }
+    class ConcreteSubject {
+        -state
+        +getState()
+        +setState()
+    }
+    class ConcreteObserver {
+        -subject
+        +update()
+    }
+    Subject <|-- ConcreteSubject
+    Observer <|-- ConcreteObserver
+    ConcreteSubject --> Observer : notifies
+    ConcreteObserver --> ConcreteSubject : observes
+```
+
+### Implementation in this code:
+
+{code_analysis}
+
+### Real-world Example:
+
+```python
+# Newsletter subscription system
+class Newsletter:
+    def __init__(self):
+        self._subscribers = []
+        self._latest_article = None
+
+    def subscribe(self, subscriber):
+        self._subscribers.append(subscriber)
+
+    def unsubscribe(self, subscriber):
+        self._subscribers.remove(subscriber)
+
+    def publish_article(self, article):
+        self._latest_article = article
+        self._notify_subscribers()
+
+    def _notify_subscribers(self):
+        for subscriber in self._subscribers:
+            subscriber.update(self._latest_article)
+
+class EmailSubscriber:
+    def __init__(self, email):
+        self.email = email
+
+    def update(self, article):
+        print(f"Sending email to {self.email}: New article - {article}")
+```
+
+'''
+}
+
+        return patterns.get(pattern_name, "Pattern explanation not available")
+
+````
+
+### 7. Common Pitfalls and Best Practices
+
+Highlight potential issues and improvements:
+
+**Code Review Insights**
+```python
+def analyze_common_pitfalls(self, code):
+    """
+    Identify common mistakes and suggest improvements
+    """
+    issues = []
+
+    # Check for common Python pitfalls
+    pitfall_patterns = [
+        {
+            'pattern': r'except:',
+            'issue': 'Bare except clause',
+            'severity': 'high',
+            'explanation': '''
+## ⚠️ Bare Except Clause
+
+**Problem**: `except:` catches ALL exceptions, including system exits and keyboard interrupts.
+
+**Why it's bad**:
+- Hides programming errors
+- Makes debugging difficult
+- Can catch exceptions you didn't intend to handle
+
+**Better approach**:
+```python
+# Bad
+try:
+    risky_operation()
+except:
+    print("Something went wrong")
+
+# Good
+try:
+    risky_operation()
+except (ValueError, TypeError) as e:
+    print(f"Expected error: {e}")
+except Exception as e:
+    logger.error(f"Unexpected error: {e}")
+    raise
+````
+
+'''
+},
+{
+'pattern': r'def._\(\s_\):.\*global',
+'issue': 'Global variable usage',
+'severity': 'medium',
+'explanation': '''
+
+## ⚠️ Global Variable Usage
+
+**Problem**: Using global variables makes code harder to test and reason about.
+
+**Better approaches**:
+
+1. Pass as parameter
+2. Use class attributes
+3. Use dependency injection
+4. Return values instead
+
+**Example refactor**:
+
+```python
+# Bad
+count = 0
+def increment():
+    global count
+    count += 1
+
+# Good
+class Counter:
+    def __init__(self):
+        self.count = 0
+
+    def increment(self):
+        self.count += 1
+        return self.count
+```
+
+'''
+}
+]
+
+    for pitfall in pitfall_patterns:
+        if re.search(pitfall['pattern'], code):
+            issues.append(pitfall)
+
+    return issues
+
+````
+
+### 8. Learning Path Recommendations
+
+Suggest resources for deeper understanding:
+
+**Personalized Learning Path**
+```python
+def generate_learning_path(self, analysis):
+    """
+    Create personalized learning recommendations
+    """
+    learning_path = {
+        'current_level': analysis['difficulty_level'],
+        'identified_gaps': [],
+        'recommended_topics': [],
+        'resources': []
+    }
+
+    # Identify knowledge gaps
+    if 'async' in analysis['concepts'] and analysis['difficulty_level'] == 'beginner':
+        learning_path['identified_gaps'].append('Asynchronous programming fundamentals')
+        learning_path['recommended_topics'].extend([
+            'Event loops',
+            'Coroutines vs threads',
+            'Async/await syntax',
+            'Concurrent programming patterns'
+        ])
+
+    # Add resources
+    learning_path['resources'] = [
+        {
+            'topic': 'Async Programming',
+            'type': 'tutorial',
+            'title': 'Async IO in Python: A Complete Walkthrough',
+            'url': 'https://realpython.com/async-io-python/',
+            'difficulty': 'intermediate',
+            'time_estimate': '45 minutes'
+        },
+        {
+            'topic': 'Design Patterns',
+            'type': 'book',
+            'title': 'Head First Design Patterns',
+            'difficulty': 'beginner-friendly',
+            'format': 'visual learning'
+        }
+    ]
+
+    # Create structured learning plan
+    learning_path['structured_plan'] = f"""
+## Your Personalized Learning Path
+
+### Week 1-2: Fundamentals
+- Review basic concepts: {', '.join(learning_path['recommended_topics'][:2])}
+- Complete exercises on each topic
+- Build a small project using these concepts
+
+### Week 3-4: Applied Learning
+- Study the patterns in this codebase
+- Refactor a simple version yourself
+- Compare your approach with the original
+
+### Week 5-6: Advanced Topics
+- Explore edge cases and optimizations
+- Learn about alternative approaches
+- Contribute to open source projects using these patterns
+
+### Practice Projects:
+1. **Beginner**: {self._suggest_beginner_project(analysis)}
+2. **Intermediate**: {self._suggest_intermediate_project(analysis)}
+3. **Advanced**: {self._suggest_advanced_project(analysis)}
+"""
+
+    return learning_path
+````
+
+## Output Format
+
+1. **Complexity Analysis**: Overview of code complexity and concepts used
+2. **Visual Diagrams**: Flow charts, class diagrams, and execution visualizations
+3. **Step-by-Step Breakdown**: Progressive explanation from simple to complex
+4. **Interactive Examples**: Runnable code samples to experiment with
+5. **Common Pitfalls**: Issues to avoid with explanations
+6. **Best Practices**: Improved approaches and patterns
+7. **Learning Resources**: Curated resources for deeper understanding
+8. **Practice Exercises**: Hands-on challenges to reinforce learning
+
+Focus on making complex code accessible through clear explanations, visual aids, and practical examples that build understanding progressively.

commands/misc/code-optimize.md

@@ -0,0 +1,148 @@
+---
+description: Analyze and optimize code for performance, memory, and efficiency
+model: claude-sonnet-4-5
+---
+
+Optimize the following code for performance and efficiency.
+
+## Code to Optimize
+
+$ARGUMENTS
+
+## Optimization Strategy for Solo Developers
+
+### 1. **Profiling First**
+- Identify actual bottlenecks
+- Don't optimize prematurely
+- Measure before and after
+- Focus on high-impact areas
+
+### 2. **Performance Optimization Areas**
+
+**React/Next.js**
+- Memoization (React.memo, useMemo, useCallback)
+- Code splitting and lazy loading
+- Image optimization (next/image)
+- Font optimization (next/font)
+- Remove unnecessary re-renders
+- Virtual scrolling for long lists
+
+**Database Queries**
+- Add indexes for frequently queried fields
+- Batch queries (reduce N+1 problems)
+- Use select to limit fields
+- Implement pagination
+- Cache frequent queries
+- Use database views for complex joins
+
+**API Calls**
+- Implement caching (SWR, React Query)
+- Debounce/throttle requests
+- Parallel requests where possible
+- Request deduplication
+- Optimistic updates
+
+**Bundle Size**
+- Tree-shaking unused code
+- Dynamic imports for large libraries
+- Replace heavy dependencies
+- Code splitting by route
+- Lazy load below-the-fold content
+
+**Memory**
+- Fix memory leaks (cleanup useEffect)
+- Avoid unnecessary object creation
+- Use const for non-changing values
+- Clear intervals/timeouts
+- Remove event listeners
+
+### 3. **Optimization Checklist**
+
+**JavaScript/TypeScript**
+-  Use const/let instead of var
+-  Avoid nested loops where possible
+-  Use Map/Set for lookups
+-  Minimize DOM manipulations
+-  Debounce/throttle expensive operations
+
+**React**
+-  Memo components that render often
+-  Move static values outside components
+-  Use keys properly in lists
+-  Avoid inline functions in render
+-  Lazy load routes and components
+
+**Next.js**
+-  Use Server Components where possible
+-  Implement ISR for dynamic content
+-  Optimize images with next/image
+-  Prefetch critical routes
+-  Use Suspense for streaming
+
+**Database**
+-  Add indexes on foreign keys
+-  Use prepared statements
+-  Batch inserts/updates
+-  Implement connection pooling
+-  Cache expensive queries
+
+**Network**
+-  Compress responses (gzip/brotli)
+-  Use CDN for static assets
+-  Implement HTTP/2
+-  Set proper cache headers
+-  Minimize payload size
+
+### 4. **Measurement Tools**
+
+**Frontend**
+- Chrome DevTools Performance tab
+- Lighthouse CI
+- React DevTools Profiler
+- Bundle Analyzer (next/bundle-analyzer)
+
+**Backend**
+- Node.js profiler
+- Database query analyzer
+- APM tools (DataDog, New Relic)
+- Load testing (k6, Artillery)
+
+### 5. **Common Optimizations**
+
+**Replace inefficient array methods**
+```typescript
+// Before: Multiple iterations
+const result = arr
+  .filter(x => x > 0)
+  .map(x => x * 2)
+  .reduce((sum, x) => sum + x, 0)
+
+// After: Single iteration
+const result = arr.reduce((sum, x) => {
+  return x > 0 ? sum + (x * 2) : sum
+}, 0)
+```
+
+**Memoize expensive calculations**
+```typescript
+const expensiveValue = useMemo(() => {
+  return complexCalculation(props.data)
+}, [props.data])
+```
+
+**Virtual scrolling for long lists**
+```typescript
+import { useVirtual } from 'react-virtual'
+// Only render visible items
+```
+
+## Output Format
+
+1. **Analysis** - Identify performance bottlenecks
+2. **Optimized Code** - Improved version
+3. **Explanation** - What changed and why
+4. **Benchmarks** - Expected performance improvement
+5. **Trade-offs** - Any complexity added
+6. **Next Steps** - Further optimization opportunities
+
+Focus on practical, measurable optimizations that provide real user value. Don't sacrifice readability for micro-optimizations.

commands/misc/lint.md

@@ -0,0 +1,202 @@
+---
+description: Run linting and fix code quality issues
+model: claude-sonnet-4-5
+---
+
+Run linting and fix code quality issues in the codebase.
+
+## Target
+
+$ARGUMENTS
+
+## Lint Strategy for Solo Developers
+
+### 1. **Run Linting Commands**
+
+```bash
+# ESLint (JavaScript/TypeScript)
+npm run lint
+npx eslint . --fix
+
+# TypeScript Compiler
+npx tsc --noEmit
+
+# Prettier (formatting)
+npx prettier --write .
+
+# All together
+npm run lint && npx tsc --noEmit && npx prettier --write .
+```
+
+### 2. **Common ESLint Issues**
+
+**TypeScript Errors**
+- Missing type annotations
+- `any` types used
+- Unused variables
+- Missing return types
+
+**React/Next.js Issues**
+- Missing keys in lists
+- Unsafe useEffect dependencies
+- Unescaped entities in JSX
+- Missing alt text on images
+
+**Code Quality**
+- Unused imports
+- Console.log statements
+- Debugger statements
+- TODO comments
+
+**Best Practices**
+- No var, use const/let
+- Prefer const over let
+- No nested ternaries
+- Consistent return statements
+
+### 3. **Auto-Fix What You Can**
+
+**Safe Auto-Fixes**
+```bash
+# Fix formatting
+prettier --write .
+
+# Fix ESLint auto-fixable rules
+eslint --fix .
+
+# Fix import order
+eslint --fix --rule 'import/order: error' .
+```
+
+**Manual Fixes Needed**
+- Type annotations
+- Logic errors
+- Missing error handling
+- Accessibility issues
+
+### 4. **Lint Configuration**
+
+**ESLint Config** (`.eslintrc.json`)
+```json
+{
+  "extends": [
+    "next/core-web-vitals",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unused-vars": "error",
+    "no-console": "warn"
+  }
+}
+```
+
+**Prettier Config** (`.prettierrc`)
+```json
+{
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}
+```
+
+### 5. **Priority Fixes**
+
+**High Priority** (fix immediately)
+- Type errors blocking build
+- Security vulnerabilities
+- Runtime errors
+- Broken accessibility
+
+**Medium Priority** (fix before commit)
+- Missing type annotations
+- Unused variables
+- Code style violations
+- TODO comments
+
+**Low Priority** (fix when convenient)
+- Formatting inconsistencies
+- Comment improvements
+- Minor refactoring opportunities
+
+### 6. **Pre-Commit Hooks** (Recommended)
+
+**Install Husky + lint-staged**
+```bash
+npm install -D husky lint-staged
+npx husky init
+```
+
+**Configure** (`.husky/pre-commit`)
+```bash
+npx lint-staged
+```
+
+**lint-staged config** (`package.json`)
+```json
+{
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}
+```
+
+### 7. **VSCode Integration**
+
+**Settings** (`.vscode/settings.json`)
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  },
+  "typescript.tsdk": "node_modules/typescript/lib"
+}
+```
+
+## What to Generate
+
+1. **Lint Report** - All issues found
+2. **Auto-Fix Results** - What was automatically fixed
+3. **Manual Fix Suggestions** - Issues requiring manual intervention
+4. **Priority List** - Ordered by severity
+5. **Configuration Recommendations** - Improve lint setup
+
+## Common Fixes
+
+**Remove Unused Imports**
+```typescript
+// Before
+import { A, B, C } from 'lib'
+
+// After
+import { A, C } from 'lib'  // B was unused
+```
+
+**Add Type Annotations**
+```typescript
+// Before
+function process(data) {
+  return data.map(x => x.value)
+}
+
+// After
+function process(data: DataItem[]): number[] {
+  return data.map(x => x.value)
+}
+```
+
+**Fix Missing Keys**
+```typescript
+// Before
+{items.map(item => <div>{item.name}</div>)}
+
+// After
+{items.map(item => <div key={item.id}>{item.name}</div>)}
+```
+
+Focus on fixes that improve code quality and prevent bugs. Run linting before every commit.

commands/new-task.md

@@ -0,0 +1,97 @@
+---
+description: Analyze task complexity and create actionable implementation plan
+model: claude-sonnet-4-5
+---
+
+Analyze the following task and create a clear, actionable implementation plan.
+
+## Task
+
+$ARGUMENTS
+
+## Analysis Framework
+
+### 1. **Task Breakdown**
+- Understand requirements
+- Identify dependencies
+- List affected files/components
+- Estimate complexity (Small/Medium/Large)
+
+### 2. **Time Estimation**
+- **Small**: 1-2 hours (simple bug fix, minor feature)
+- **Medium**: Half day to 1 day (new component, API endpoint)
+- **Large**: 2-5 days (complex feature, multiple integrations)
+- **Very Large**: 1+ week (major refactor, new subsystem)
+
+### 3. **Risk Assessment**
+Identify potential blockers:
+- Unknown dependencies
+- API limitations
+- Data migration needs
+- Breaking changes
+- Third-party service issues
+
+### 4. **Implementation Steps**
+
+Create sequential, logical steps:
+1. Setup/preparation
+2. Backend changes
+3. Frontend changes
+4. Testing
+5. Documentation
+6. Deployment
+
+### 5. **Success Criteria**
+
+Define "done":
+- Feature works as specified
+- Tests pass
+- No regressions
+- Code reviewed
+- Documented
+
+## Output Format
+
+### Task Analysis
+- **Type**: [Bug Fix / Feature / Refactor / Infrastructure]
+- **Complexity**: [Small / Medium / Large / Very Large]
+- **Estimated Time**: X hours/days
+- **Priority**: [High / Medium / Low]
+
+### Implementation Plan
+
+**Phase 1: [Name]** (Time estimate)
+- [ ] Step 1
+- [ ] Step 2
+
+**Phase 2: [Name]** (Time estimate)
+- [ ] Step 3
+- [ ] Step 4
+
+### Files to Modify/Create
+```
+app/page.tsx (modify)
+components/NewComponent.tsx (create)
+lib/utils.ts (modify)
+```
+
+### Dependencies
+```bash
+npm install package-name
+```
+
+### Testing Strategy
+- Unit tests for X
+- Integration tests for Y
+- Manual testing steps
+
+### Potential Issues
+- Issue 1 and mitigation
+- Issue 2 and mitigation
+
+### Next Steps
+1. Start with Phase 1, Step 1
+2. Test incrementally
+3. Commit often
+
+Provide a clear, solo-developer-friendly plan that breaks down complex tasks into manageable steps.

commands/ui/component-new.md

@@ -0,0 +1,138 @@
+---
+description: Create a new React component with TypeScript and modern best practices
+model: claude-sonnet-4-5
+---
+
+Generate a new React component following 2025 best practices.
+
+## Component Specification
+
+$ARGUMENTS
+
+## Modern React + TypeScript Standards
+
+### 1. **Function Components Only**
+- Use function components (not class components)
+- React 19 patterns
+- Server Components where appropriate (Next.js)
+
+### 2. **TypeScript Best Practices**
+- Strict typing (`strict: true`)
+- Interface for props
+- Proper TypeScript utility types (ComponentProps, ReactNode, etc.)
+- NO `any` types
+- Explicit return types for complex components
+
+### 3. **Component Patterns**
+
+**Client Components** (interactive, use hooks)
+```typescript
+'use client'
+import { useState } from 'react'
+
+interface Props {
+  // typed props
+}
+
+export function Component({ }: Props) {
+  // implementation
+}
+```
+
+**Server Components** (default in Next.js App Router)
+```typescript
+interface Props {
+  // typed props
+}
+
+export async function Component({ }: Props) {
+  // can fetch data directly
+}
+```
+
+### 4. **State Management**
+- `useState` for local state
+- `useReducer` for complex state
+- Zustand for global state
+- React Context for theme/auth
+
+### 5. **Performance**
+- Lazy loading with `React.lazy()`
+- Code splitting
+- `use memo()` for expensive computations
+- `useCallback()` for callback functions
+
+### 6. **Styling Approach** (choose based on project)
+- **Tailwind CSS** - Utility-first (recommended)
+- **CSS Modules** - Scoped styles
+- **Styled Components** - CSS-in-JS
+
+## What to Generate
+
+1. **Component File** - Main component with TypeScript
+2. **Props Interface** - Fully typed props
+3. **Styles** - Tailwind classes or CSS module
+4. **Example Usage** - How to import and use
+5. **Storybook Story** (optional) - Component documentation
+
+## Code Quality Standards
+
+**Structure**
+-  Feature-based folder organization
+-  Co-locate related files
+-  Barrel exports (index.ts)
+-  Clear file naming conventions
+
+**TypeScript**
+-  Explicit prop types via interface
+-  Proper generics where needed
+-  Utility types (Pick, Omit, Partial)
+-  Discriminated unions for variants
+
+**Props**
+-  Required vs optional props
+-  Default values where appropriate
+-  Destructure in function signature
+-  Props spread carefully
+
+**Accessibility**
+-  Semantic HTML
+-  ARIA labels where needed
+-  Keyboard navigation
+-  Screen reader friendly
+
+**Best Practices**
+-  Single Responsibility Principle
+-  Composition over inheritance
+-  Extract complex logic to hooks
+-  Keep components small (<200 lines)
+
+## Component Types to Consider
+
+**Presentational Components**
+- Pure UI rendering
+- No business logic
+- Receive data via props
+- Easy to test
+
+**Container Components**
+- Data fetching
+- Business logic
+- State management
+- Pass data to presentational components
+
+**Compound Components**
+- Related components working together
+- Shared context
+- Flexible API
+- Example: `<Select><Select.Trigger/><Select.Content/></Select>`
+
+## React 19 Features to Use
+
+- **use()** API for reading promises/context
+- **useActionState()** for form state
+- **useFormStatus()** for form pending state
+- **useOptimistic()** for optimistic UI updates
+- **Server Actions** for mutations
+
+Generate production-ready, accessible, and performant React components following Next.js 15 and React 19 patterns.