thrivekit 2.0.0

package/templates/examples/CLAUDE-fullstack.md

@@ -0,0 +1,256 @@
+# Project Instructions for AI Coding Agents
+
+## Naming Conventions
+
+### Frontend (React/TypeScript)
+- **Files**: `PascalCase.tsx` for components, `camelCase.ts` for utilities
+- **Components**: `PascalCase` — e.g., `UserProfile`, `AuthProvider`
+- **Hooks**: `useCamelCase` — e.g., `useAuth`, `useUserData`
+- **Functions/Variables**: `camelCase` — e.g., `handleSubmit`, `isLoading`
+
+### Backend (Django/Python)
+- **Files**: `snake_case.py` — e.g., `user_views.py`
+- **Functions/Variables**: `snake_case` — e.g., `get_user_by_id`
+- **Classes**: `PascalCase` — e.g., `UserViewSet`, `UserSerializer`
+
+### Shared
+- **API endpoints**: `kebab-case` — e.g., `/api/user-profile/`
+- **Database tables**: `snake_case` — e.g., `user_sessions`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_RETRIES`
+
+## Tech Stack
+- **Frontend**: React 18, TypeScript, Vite, TailwindCSS
+- **Backend**: Django 5, Django REST Framework
+- **Database**: PostgreSQL
+- **Cache/Queue**: Redis, Celery
+- **Testing**: pytest (backend), Vitest (frontend), Playwright (E2E)
+
+## Architecture Overview
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   React     │────▶│   Django    │────▶│  PostgreSQL │
+│   Frontend  │     │   REST API  │     │   Database  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                          │
+                          ▼
+                    ┌─────────────┐
+                    │   Redis     │
+                    │   + Celery  │
+                    └─────────────┘
+```
+
+## Code Quality Standards
+
+### API Contract
+- Frontend and backend share type definitions
+- Use consistent naming (camelCase in TS, snake_case in Python)
+- API transforms snake_case responses to camelCase
+- Document API changes before implementing
+
+```typescript
+// Frontend: types/api.ts
+interface User {
+  id: number;
+  email: string;
+  firstName: string;  // Transformed from first_name
+  lastName: string;
+  createdAt: string;
+}
+```
+
+```python
+# Backend: serializers.py
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ['id', 'email', 'first_name', 'last_name', 'created_at']
+```
+
+### Frontend Standards
+
+**Components**
+- Use functional components with TypeScript
+- Keep components under 100 lines
+- Extract logic to custom hooks
+- Handle loading/error/empty states
+
+**State Management**
+- React Query for server state
+- Zustand for UI state only
+- Don't duplicate server state
+
+**API Calls**
+```typescript
+// services/api.ts
+const api = {
+  users: {
+    getAll: () => fetch<User[]>('/api/users/'),
+    getById: (id: number) => fetch<User>(`/api/users/${id}/`),
+    create: (data: CreateUserInput) => post<User>('/api/users/', data),
+  },
+};
+```
+
+### Backend Standards
+
+**Views**
+- Use DRF ViewSets for CRUD
+- Apply proper permissions
+- Return appropriate status codes
+- Filter querysets by user ownership
+
+**Models**
+- Add explicit `related_name`
+- Include `__str__` method
+- Index frequently queried fields
+- Use model managers for complex queries
+
+**Queries**
+- Avoid N+1 with select_related/prefetch_related
+- Use pagination for list endpoints
+- Add database indexes
+
+### Shared Patterns
+
+**Authentication**
+- JWT tokens in httpOnly cookies
+- CSRF protection for state-changing requests
+- Refresh tokens for long sessions
+
+**Error Handling**
+```typescript
+// Frontend
+try {
+  await api.users.create(data);
+} catch (error) {
+  if (error instanceof ApiError) {
+    showToast(error.message);
+  } else {
+    showToast('Something went wrong');
+    logger.error(error);
+  }
+}
+```
+
+```python
+# Backend
+try:
+    user = create_user(data)
+except ValidationError as e:
+    raise DRFValidationError(e.messages)
+except IntegrityError:
+    raise DRFValidationError({'email': 'Email already exists'})
+```
+
+### Testing Strategy
+
+**Unit Tests**
+- Frontend: Test hooks, utilities, complex components
+- Backend: Test services, serializers, model methods
+
+**Integration Tests**
+- Backend: Test API endpoints with pytest
+- Frontend: Test API integration with MSW
+
+**E2E Tests (Playwright)**
+- Test critical user flows
+- Use TDD workflow (test first, then implement)
+- Include SCENARIO/EXPECTED/FAILURE documentation
+
+```typescript
+test('user can complete checkout', async ({ page }) => {
+  /**
+   * SCENARIO: Logged-in user adds item and completes checkout
+   * EXPECTED: Order confirmation shown, order in database
+   * FAILURE: Stuck at any step, error shown
+   */
+  await loginAsTestUser(page);
+  await page.goto('/products/1');
+  await page.click('[data-testid="add-to-cart"]');
+  await page.click('[data-testid="checkout"]');
+  await page.fill('[name="address"]', '123 Main St');
+  await page.click('[data-testid="place-order"]');
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+```
+
+## File Structure
+
+```
+project/
+├── frontend/
+│   ├── src/
+│   │   ├── components/
+│   │   ├── hooks/
+│   │   ├── pages/
+│   │   ├── services/
+│   │   ├── stores/
+│   │   └── types/
+│   └── e2e/              # Playwright tests
+├── backend/
+│   ├── config/           # Django settings
+│   ├── apps/
+│   │   ├── users/
+│   │   └── orders/
+│   └── tests/
+├── docker-compose.yml
+└── Makefile
+```
+
+## Environment Variables
+
+```bash
+# .env.example
+
+# Database
+DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
+
+# Django
+SECRET_KEY=your-secret-key
+DEBUG=True
+ALLOWED_HOSTS=localhost,127.0.0.1
+
+# Frontend
+VITE_API_URL=http://localhost:8000/api
+
+# Redis
+REDIS_URL=redis://localhost:6379
+```
+
+## Pre-commit Hooks
+This project uses thrivekit hooks. Run `/vibe-check` before committing.
+
+## Common Commands
+
+```bash
+# Development
+make up              # Start all services (Docker)
+make frontend        # Run frontend dev server
+make logs            # View backend logs
+
+# Database
+make migrate         # Run migrations
+make makemigrations  # Create migrations
+
+# Testing
+make test            # Run all tests
+make test-backend    # Run backend tests
+make test-frontend   # Run frontend tests
+make test-e2e        # Run Playwright E2E tests
+
+# Code Quality
+make lint            # Run all linters
+make format          # Format all code
+make typecheck       # Check TypeScript types
+```
+
+## Workflow
+
+1. **Idea** - Run `/idea "feature description"` to brainstorm
+2. **Approve** - Review the idea file, then approve
+3. **PRD** - Review generated stories in `.ralph/prd.json`
+4. **Run** - Execute `ralph run` for autonomous coding
+5. **Audit** - Run `/vibe-check` before shipping
+6. **Commit** - Pre-commit hooks catch remaining issues

package/templates/examples/CLAUDE-node.md

@@ -0,0 +1,246 @@
+# Project Instructions for AI Coding Agents
+
+## Naming Conventions
+- **Files**: `kebab-case.ts` — e.g., `user-service.ts`, `auth-middleware.ts`
+- **Functions/Variables**: `camelCase` — e.g., `getUserById`, `isValid`
+- **Classes/Interfaces/Types**: `PascalCase` — e.g., `UserService`, `CreateUserInput`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_RETRIES`, `DEFAULT_PORT`
+- **Database tables**: `snake_case` — e.g., `user_sessions` (Prisma converts to camelCase)
+- **API endpoints**: `kebab-case` — e.g., `/api/user-profile`, `/api/auth/sign-in`
+
+## Tech Stack
+- **Runtime**: Node.js 20+
+- **Framework**: Express.js / Fastify
+- **Language**: TypeScript
+- **Database**: PostgreSQL with Prisma
+- **Testing**: Jest, Supertest
+
+## Code Quality Standards
+
+### TypeScript
+- Enable strict mode in tsconfig
+- Never use `any` - define proper types
+- Use `unknown` for truly dynamic data
+- Export types from dedicated files
+
+```typescript
+// types/user.ts
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: Date;
+}
+
+export interface CreateUserInput {
+  email: string;
+  name: string;
+  password: string;
+}
+```
+
+### API Endpoints
+- Use consistent response format
+- Return appropriate HTTP status codes
+- Validate all input with Zod or Joi
+- Handle errors with middleware
+
+```typescript
+// Consistent response format
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+// Controller
+export async function createUser(req: Request, res: Response) {
+  const input = createUserSchema.parse(req.body);
+
+  const user = await userService.create(input);
+
+  res.status(201).json({
+    success: true,
+    data: user,
+  });
+}
+```
+
+### Error Handling
+- Use custom error classes
+- Centralize error handling in middleware
+- Log errors with context
+- Never expose stack traces to clients
+
+```typescript
+// errors.ts
+export class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(404, 'NOT_FOUND', `${resource} not found`);
+  }
+}
+
+// middleware/errorHandler.ts
+export function errorHandler(
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  logger.error('Request error', { error: err, path: req.path });
+
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      success: false,
+      error: { code: err.code, message: err.message },
+    });
+  }
+
+  // Don't expose internal errors
+  res.status(500).json({
+    success: false,
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
+  });
+}
+```
+
+### Database (Prisma)
+- Use transactions for multi-step operations
+- Select only needed fields
+- Use pagination for list endpoints
+- Add indexes in schema
+
+```typescript
+// Good - select only needed fields
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    name: true,
+  },
+  take: 20,
+  skip: page * 20,
+});
+
+// Transaction
+await prisma.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.inventory.decrement({ where: { productId }, data: { quantity } });
+  return order;
+});
+```
+
+### Async/Await
+- Always use try/catch or error middleware
+- Use Promise.all for parallel operations
+- Handle promise rejections
+- Avoid callback-style code
+
+```typescript
+// Parallel operations
+const [user, orders, notifications] = await Promise.all([
+  userService.getById(userId),
+  orderService.getByUser(userId),
+  notificationService.getUnread(userId),
+]);
+```
+
+### Security
+- Validate all input
+- Use parameterized queries (Prisma does this)
+- Set security headers (helmet)
+- Rate limit sensitive endpoints
+- Never log sensitive data
+
+### Logging
+- Use structured logging (pino, winston)
+- Include request ID for tracing
+- Log appropriate levels
+- Never log passwords or tokens
+
+```typescript
+logger.info('User created', {
+  userId: user.id,
+  email: user.email,
+  // Never log: password, token, etc.
+});
+```
+
+### Testing
+- Unit test business logic
+- Integration test API endpoints
+- Mock external services
+- Use test database
+
+```typescript
+describe('POST /api/users', () => {
+  it('creates a user with valid input', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'test@example.com', name: 'Test', password: 'secure123' });
+
+    expect(response.status).toBe(201);
+    expect(response.body.success).toBe(true);
+    expect(response.body.data.email).toBe('test@example.com');
+  });
+
+  it('returns 400 for invalid email', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'invalid', name: 'Test', password: 'secure123' });
+
+    expect(response.status).toBe(400);
+    expect(response.body.error.code).toBe('VALIDATION_ERROR');
+  });
+});
+```
+
+## File Structure
+```
+src/
+├── controllers/      # Route handlers
+├── services/         # Business logic
+├── repositories/     # Database access
+├── middleware/       # Express middleware
+├── types/            # TypeScript types
+├── utils/            # Helper functions
+├── routes/           # Route definitions
+└── index.ts          # App entry point
+```
+
+## Environment Variables
+```typescript
+// config.ts
+export const config = {
+  port: process.env.PORT || 3000,
+  databaseUrl: process.env.DATABASE_URL!,
+  jwtSecret: process.env.JWT_SECRET!,
+  nodeEnv: process.env.NODE_ENV || 'development',
+};
+```
+
+## Pre-commit Hooks
+This project uses thrivekit hooks. Run `/vibe-check` before committing.
+
+## Common Commands
+```bash
+npm run dev          # Start dev server with hot reload
+npm run build        # Build TypeScript
+npm start            # Start production server
+npm test             # Run tests
+npm run lint         # Run linter
+npm run db:migrate   # Run Prisma migrations
+```

package/templates/examples/CLAUDE-react.md

@@ -0,0 +1,138 @@
+# Project Instructions for AI Coding Agents
+
+## Naming Conventions
+- **Files**: `PascalCase.tsx` for components, `camelCase.ts` for utilities — e.g., `UserProfile.tsx`, `useAuth.ts`
+- **Components**: `PascalCase` — e.g., `UserProfile`, `AuthProvider`
+- **Hooks**: `useCamelCase` — e.g., `useAuth`, `useUserData`
+- **Functions/Variables**: `camelCase` — e.g., `handleSubmit`, `isLoading`
+- **Types/Interfaces**: `PascalCase` — e.g., `UserProps`, `AuthState`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `API_BASE_URL`, `MAX_RETRIES`
+- **CSS classes**: `kebab-case` (TailwindCSS utility classes are standard)
+
+## Tech Stack
+- **Frontend**: React 18, TypeScript, Vite
+- **Styling**: TailwindCSS
+- **State**: React Query for server state, Zustand for client state
+- **Testing**: Vitest, React Testing Library, Playwright
+
+## Code Quality Standards
+
+### TypeScript
+- **Never use `any`** - Create proper interfaces for all data
+- Use strict mode (`"strict": true` in tsconfig)
+- Prefer `interface` for object shapes, `type` for unions/intersections
+- Use `unknown` instead of `any` when type is truly unknown
+
+```typescript
+// Bad
+const data: any = await fetchUser();
+
+// Good
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+const data: User = await fetchUser();
+```
+
+### React Components
+- Use functional components with hooks
+- Keep components small and focused (< 100 lines)
+- Extract logic into custom hooks
+- Use proper TypeScript types for props
+
+```typescript
+// Good component structure
+interface UserCardProps {
+  user: User;
+  onEdit: (user: User) => void;
+}
+
+export function UserCard({ user, onEdit }: UserCardProps) {
+  return (/* ... */);
+}
+```
+
+### State Management
+- Use React Query for server state (caching, refetching)
+- Use Zustand for UI state only
+- Keep state as close to usage as possible
+- Don't duplicate server state in client state
+
+### Error Handling
+- Always handle loading, error, and empty states
+- Use Error Boundaries for unexpected errors
+- Show user-friendly error messages
+- Log errors with context for debugging
+
+```typescript
+// Always handle all states
+const { data, isLoading, error } = useQuery(['user'], fetchUser);
+
+if (isLoading) return <Skeleton />;
+if (error) return <ErrorMessage error={error} />;
+if (!data) return <EmptyState />;
+
+return <UserProfile user={data} />;
+```
+
+### Styling with TailwindCSS
+- Use Tailwind utility classes
+- Extract repeated patterns to components, not @apply
+- Use design system tokens (colors, spacing)
+- Keep className strings readable
+
+### Testing
+- Write tests for business logic and user interactions
+- Use React Testing Library (test behavior, not implementation)
+- Mock external dependencies
+- Use Playwright for critical user flows
+
+```typescript
+// Test user behavior, not implementation
+test('user can submit form', async () => {
+  render(<ContactForm />);
+
+  await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com');
+  await userEvent.click(screen.getByRole('button', { name: /submit/i }));
+
+  expect(screen.getByText(/thanks/i)).toBeInTheDocument();
+});
+```
+
+## File Structure
+```
+src/
+├── components/     # Reusable UI components
+│   ├── ui/         # Design system primitives
+│   └── features/   # Feature-specific components
+├── hooks/          # Custom React hooks
+├── pages/          # Page components (routes)
+├── services/       # API calls and external services
+├── stores/         # Zustand stores
+├── types/          # TypeScript types/interfaces
+└── utils/          # Helper functions
+```
+
+## Environment Variables
+- Use `import.meta.env.VITE_*` for client-side env vars
+- Never commit real secrets
+- Provide defaults for local development
+
+```typescript
+const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000/api';
+```
+
+## Pre-commit Hooks
+This project uses thrivekit hooks. Run `/vibe-check` before committing.
+
+## Common Commands
+```bash
+npm run dev          # Start dev server
+npm run build        # Build for production
+npm test             # Run unit tests
+npm run test:e2e     # Run E2E tests
+npm run lint         # Run linter
+npm run typecheck    # Check types
+```