agentic-team-templates 0.3.0

package/templates/web-backend/.cursorrules/database-patterns.md

@@ -0,0 +1,298 @@
+# Database Patterns
+
+Best practices for working with databases in backend applications.
+
+## General Principles
+
+### 1. Use a Data Access Layer
+
+Separate database operations from business logic.
+
+```ts
+// repository/userRepository.ts
+export const userRepository = {
+  async findById(id: string): Promise<User | null> {
+    return db.user.findUnique({ where: { id } });
+  },
+
+  async create(data: CreateUserInput): Promise<User> {
+    return db.user.create({ data });
+  },
+
+  async update(id: string, data: UpdateUserInput): Promise<User> {
+    return db.user.update({ where: { id }, data });
+  },
+};
+
+// services/userService.ts
+export const createUser = async (input: CreateUserInput) => {
+  // Business logic here
+  const validated = validateUserInput(input);
+  return userRepository.create(validated);
+};
+```
+
+### 2. Use Transactions for Related Operations
+
+```ts
+// Good: Atomic operation
+await db.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.inventory.update({
+    where: { productId: order.productId },
+    data: { quantity: { decrement: order.quantity } },
+  });
+  await tx.payment.create({ data: { orderId: order.id, ...paymentData } });
+});
+
+// Bad: Non-atomic, can leave inconsistent state
+const order = await db.order.create({ data: orderData });
+await db.inventory.update({ ... });  // What if this fails?
+await db.payment.create({ ... });
+```
+
+### 3. Handle Connection Errors
+
+```ts
+const connectWithRetry = async (maxRetries = 5) => {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      await db.$connect();
+      return;
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      await sleep(Math.pow(2, i) * 1000);  // Exponential backoff
+    }
+  }
+};
+```
+
+## Query Optimization
+
+### Select Only Needed Fields
+
+```ts
+// Good: Select specific fields
+const users = await db.user.findMany({
+  select: { id: true, name: true, email: true },
+});
+
+// Bad: Select everything when you don't need it
+const users = await db.user.findMany();  // Returns all fields including large blobs
+```
+
+### Use Pagination
+
+```ts
+// Offset-based (simple, but slow for large offsets)
+const users = await db.user.findMany({
+  skip: (page - 1) * limit,
+  take: limit,
+  orderBy: { createdAt: 'desc' },
+});
+
+// Cursor-based (better for large datasets)
+const users = await db.user.findMany({
+  take: limit,
+  cursor: cursor ? { id: cursor } : undefined,
+  orderBy: { id: 'asc' },
+});
+```
+
+### Avoid N+1 Queries
+
+```ts
+// Bad: N+1 queries
+const posts = await db.post.findMany();
+for (const post of posts) {
+  post.author = await db.user.findUnique({ where: { id: post.authorId } });
+}
+
+// Good: Single query with include
+const posts = await db.post.findMany({
+  include: { author: true },
+});
+
+// Good: Batch query
+const posts = await db.post.findMany();
+const authorIds = [...new Set(posts.map(p => p.authorId))];
+const authors = await db.user.findMany({ where: { id: { in: authorIds } } });
+const authorMap = new Map(authors.map(a => [a.id, a]));
+posts.forEach(p => p.author = authorMap.get(p.authorId));
+```
+
+### Use Indexes
+
+```sql
+-- Create indexes for frequently queried columns
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_posts_user_created ON posts(user_id, created_at);
+
+-- Composite index for common query patterns
+CREATE INDEX idx_orders_status_date ON orders(status, created_at);
+```
+
+## Migrations
+
+### Version Control Migrations
+
+```
+migrations/
+├── 001_create_users_table.sql
+├── 002_add_email_index.sql
+├── 003_create_posts_table.sql
+└── 004_add_user_avatar.sql
+```
+
+### Write Reversible Migrations
+
+```sql
+-- migrations/003_create_posts_table.sql
+
+-- Up
+CREATE TABLE posts (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  title VARCHAR(255) NOT NULL,
+  content TEXT,
+  user_id UUID REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Down
+DROP TABLE posts;
+```
+
+### Test Migrations
+
+- Test in staging before production
+- Have a rollback plan
+- Consider zero-downtime migrations for large tables
+
+## Connection Pooling
+
+### Configure Pool Size
+
+```ts
+// Match pool size to expected concurrency
+const pool = new Pool({
+  host: process.env.DB_HOST,
+  max: 20,              // Max connections
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+```
+
+### Handle Pool Exhaustion
+
+```ts
+// Set appropriate timeouts
+const result = await Promise.race([
+  db.query(sql),
+  new Promise((_, reject) =>
+    setTimeout(() => reject(new Error('Query timeout')), 5000)
+  ),
+]);
+```
+
+## Data Integrity
+
+### Use Constraints
+
+```sql
+-- Primary keys
+PRIMARY KEY (id)
+
+-- Foreign keys with appropriate actions
+FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+
+-- Unique constraints
+UNIQUE (email)
+
+-- Check constraints
+CHECK (price >= 0)
+CHECK (status IN ('pending', 'active', 'completed'))
+```
+
+### Use Appropriate Data Types
+
+```sql
+-- Good: Appropriate types
+id UUID PRIMARY KEY
+email VARCHAR(255) NOT NULL
+price DECIMAL(10, 2)
+created_at TIMESTAMP WITH TIME ZONE
+
+-- Bad: Wrong types
+id TEXT
+price FLOAT  -- Precision issues
+created_at VARCHAR(50)
+```
+
+## Soft Deletes (When Needed)
+
+```ts
+// Schema
+model User {
+  id        String    @id
+  email     String    @unique
+  deletedAt DateTime?
+}
+
+// Query active records
+const activeUsers = await db.user.findMany({
+  where: { deletedAt: null },
+});
+
+// Soft delete
+await db.user.update({
+  where: { id },
+  data: { deletedAt: new Date() },
+});
+```
+
+## Security
+
+### Parameterized Queries
+
+```ts
+// Good: Parameterized
+const user = await db.query(
+  'SELECT * FROM users WHERE id = $1',
+  [userId]
+);
+
+// Bad: SQL injection vulnerability
+const user = await db.query(
+  `SELECT * FROM users WHERE id = '${userId}'`
+);
+```
+
+### Encrypt Sensitive Data
+
+```ts
+// Encrypt at rest
+const encrypted = encrypt(sensitiveData, encryptionKey);
+await db.user.update({
+  where: { id },
+  data: { ssn: encrypted },
+});
+
+// Decrypt when needed
+const user = await db.user.findUnique({ where: { id } });
+const ssn = decrypt(user.ssn, encryptionKey);
+```
+
+### Audit Logging
+
+```ts
+// Track changes for sensitive operations
+await db.auditLog.create({
+  data: {
+    action: 'USER_UPDATE',
+    userId: currentUser.id,
+    targetId: targetUser.id,
+    changes: JSON.stringify(diff(before, after)),
+    timestamp: new Date(),
+  },
+});
+```

package/templates/web-backend/.cursorrules/error-handling.md

@@ -0,0 +1,366 @@
+# Error Handling
+
+Best practices for handling errors in backend applications.
+
+## Principles
+
+### 1. Fail Fast
+Detect errors early and fail immediately with clear diagnostics.
+
+### 2. Fail Gracefully
+Users should receive helpful messages, not stack traces.
+
+### 3. Log Everything
+Errors need context for debugging. Log appropriately.
+
+### 4. Recover When Possible
+Some errors are transient. Implement retry logic where appropriate.
+
+## Error Types
+
+### Custom Error Classes
+
+```ts
+// Base application error
+class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+// Specific error types
+class ValidationError extends AppError {
+  constructor(message: string, details?: ValidationDetail[]) {
+    super(422, 'VALIDATION_ERROR', message, details);
+    this.name = 'ValidationError';
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(404, 'NOT_FOUND', `${resource} with id ${id} not found`);
+    this.name = 'NotFoundError';
+  }
+}
+
+class UnauthorizedError extends AppError {
+  constructor(message = 'Authentication required') {
+    super(401, 'UNAUTHORIZED', message);
+    this.name = 'UnauthorizedError';
+  }
+}
+
+class ForbiddenError extends AppError {
+  constructor(message = 'Access denied') {
+    super(403, 'FORBIDDEN', message);
+    this.name = 'ForbiddenError';
+  }
+}
+
+class ConflictError extends AppError {
+  constructor(message: string) {
+    super(409, 'CONFLICT', message);
+    this.name = 'ConflictError';
+  }
+}
+```
+
+## Result Types
+
+Use Result types for explicit error handling:
+
+```ts
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
+const err = <E>(error: E): Result<never, E> => ({ ok: false, error });
+
+// Usage
+const findUser = async (id: string): Promise<Result<User, NotFoundError>> => {
+  const user = await db.user.findUnique({ where: { id } });
+
+  if (!user) {
+    return err(new NotFoundError('User', id));
+  }
+
+  return ok(user);
+};
+
+// Handling
+const result = await findUser(id);
+if (!result.ok) {
+  return res.status(result.error.statusCode).json({
+    error: { code: result.error.code, message: result.error.message }
+  });
+}
+const user = result.value;
+```
+
+## Global Error Handler
+
+```ts
+// Centralized error handling middleware
+const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => {
+  // Log error with context
+  logger.error({
+    error: err.message,
+    stack: err.stack,
+    requestId: req.id,
+    method: req.method,
+    path: req.path,
+    userId: req.user?.id,
+  });
+
+  // Handle known application errors
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details,
+      },
+    });
+  }
+
+  // Handle validation errors (e.g., from Zod)
+  if (err.name === 'ZodError') {
+    return res.status(422).json({
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Validation failed',
+        details: err.errors,
+      },
+    });
+  }
+
+  // Handle unknown errors (don't leak details)
+  res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+      requestId: req.id,  // For support reference
+    },
+  });
+};
+
+// Register at end of middleware chain
+app.use(errorHandler);
+```
+
+## Async Error Handling
+
+### Wrap Async Handlers
+
+```ts
+// Utility to catch async errors
+const asyncHandler = (fn: RequestHandler): RequestHandler => {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+};
+
+// Usage
+app.get('/users/:id', asyncHandler(async (req, res) => {
+  const user = await userService.findById(req.params.id);
+  res.json({ data: user });
+}));
+```
+
+### Or Use Try-Catch
+
+```ts
+app.get('/users/:id', async (req, res, next) => {
+  try {
+    const user = await userService.findById(req.params.id);
+    res.json({ data: user });
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+## Error Responses
+
+### Consistent Format
+
+```ts
+interface ErrorResponse {
+  error: {
+    code: string;           // Machine-readable code
+    message: string;        // Human-readable message
+    details?: unknown;      // Additional context
+    requestId?: string;     // For support/debugging
+  };
+}
+
+// Examples
+// 400 Bad Request
+{
+  "error": {
+    "code": "BAD_REQUEST",
+    "message": "Invalid JSON in request body"
+  }
+}
+
+// 422 Validation Error
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [
+      { "field": "email", "message": "Invalid email format" },
+      { "field": "age", "message": "Must be a positive number" }
+    ]
+  }
+}
+
+// 500 Internal Error
+{
+  "error": {
+    "code": "INTERNAL_ERROR",
+    "message": "An unexpected error occurred",
+    "requestId": "req_abc123"
+  }
+}
+```
+
+## Retry Logic
+
+For transient failures:
+
+```ts
+const retry = async <T>(
+  fn: () => Promise<T>,
+  options: { maxAttempts: number; delay: number; backoff?: number }
+): Promise<T> => {
+  const { maxAttempts, delay, backoff = 2 } = options;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+
+      const waitTime = delay * Math.pow(backoff, attempt - 1);
+      await sleep(waitTime);
+    }
+  }
+
+  throw new Error('Retry failed');  // Unreachable but TypeScript needs it
+};
+
+// Usage
+const result = await retry(
+  () => externalApi.call(),
+  { maxAttempts: 3, delay: 1000 }
+);
+```
+
+## Logging Best Practices
+
+### What to Log
+
+```ts
+// Log errors with context
+logger.error({
+  message: 'Failed to process payment',
+  error: error.message,
+  stack: error.stack,
+  paymentId: payment.id,
+  userId: user.id,
+  amount: payment.amount,
+  // Never log: card numbers, passwords, tokens
+});
+
+// Log important events
+logger.info({
+  message: 'Payment processed',
+  paymentId: payment.id,
+  userId: user.id,
+});
+
+// Log warnings for concerning but non-critical issues
+logger.warn({
+  message: 'Rate limit approaching',
+  userId: user.id,
+  remaining: 5,
+});
+```
+
+### What NOT to Log
+
+- Passwords and credentials
+- API keys and tokens
+- Credit card numbers
+- Personal identification numbers
+- Full request/response bodies with sensitive data
+
+## Anti-Patterns
+
+### Swallowing Errors
+
+```ts
+// Bad: Silent failure
+try {
+  await riskyOperation();
+} catch (e) {
+  // Nothing happens
+}
+
+// Good: Handle or rethrow
+try {
+  await riskyOperation();
+} catch (e) {
+  logger.error('Risky operation failed', e);
+  throw new AppError(500, 'OPERATION_FAILED', 'Could not complete operation');
+}
+```
+
+### Leaking Implementation Details
+
+```ts
+// Bad: Exposes internals
+res.status(500).json({ error: error.stack });
+
+// Good: Generic message
+res.status(500).json({
+  error: { code: 'INTERNAL_ERROR', message: 'An error occurred' }
+});
+```
+
+### Catching Too Broadly
+
+```ts
+// Bad: Catches everything including programming errors
+try {
+  const data = processInput(input);
+  await saveToDb(data);
+  sendNotification(data);
+} catch (e) {
+  res.status(400).json({ error: 'Bad request' });
+}
+
+// Good: Catch specific errors
+try {
+  const data = processInput(input);
+  await saveToDb(data);
+  sendNotification(data);
+} catch (e) {
+  if (e instanceof ValidationError) {
+    res.status(422).json({ error: e.message });
+  } else if (e instanceof DatabaseError) {
+    logger.error('Database error', e);
+    res.status(500).json({ error: 'Database error' });
+  } else {
+    throw e;  // Let unknown errors bubble up
+  }
+}
+```

package/templates/web-backend/.cursorrules/overview.md

@@ -0,0 +1,69 @@
+# Web Backend Development
+
+Guidelines for building robust backend APIs and services.
+
+## Scope
+
+This ruleset applies to:
+- RESTful APIs
+- GraphQL APIs
+- Microservices
+- Backend-for-frontend (BFF) services
+- Server-side web applications
+
+## Core Technologies
+
+Backend development typically involves:
+- Server frameworks (Express, Fastify, Koa, Hono, etc.)
+- Database systems (PostgreSQL, MySQL, MongoDB, Redis, etc.)
+- Authentication/Authorization (JWT, OAuth, sessions)
+- API documentation (OpenAPI/Swagger)
+- Testing frameworks
+
+## Key Principles
+
+### 1. Security First
+Every input is hostile until validated. Defense in depth.
+
+### 2. Reliability
+Handle errors gracefully. Fail fast with clear diagnostics.
+
+### 3. Observability
+Log meaningfully. Track metrics. Enable debugging.
+
+### 4. Scalability
+Design for horizontal scaling. Avoid single points of failure.
+
+## Project Structure
+
+```
+src/
+├── routes/           # Route handlers/controllers
+├── services/         # Business logic
+├── repositories/     # Data access layer
+├── middleware/       # Request/response middleware
+├── lib/              # Shared utilities
+├── types/            # TypeScript definitions
+├── validation/       # Input validation schemas
+└── config/           # Configuration management
+```
+
+## API Design Principles
+
+- Use consistent naming conventions
+- Return appropriate HTTP status codes
+- Provide meaningful error messages
+- Version your APIs
+- Document endpoints thoroughly
+
+## Definition of Done
+
+A backend feature is complete when:
+- [ ] Endpoint works as specified
+- [ ] Input validation implemented
+- [ ] Error handling covers edge cases
+- [ ] Authentication/authorization enforced
+- [ ] Unit and integration tests passing
+- [ ] API documentation updated
+- [ ] No security vulnerabilities
+- [ ] Logging in place for debugging