Mastering the Explore, Plan, Execute methodology for AI-assisted development

# Project Name

## What This Project Does
[2-3 sentences explaining the core purpose and value proposition]

## Architecture Overview
- **Frontend**: Next.js 14 with TypeScript, deployed on Vercel
- **Backend**: Node.js + Express, containerized with Docker
- **Database**: PostgreSQL with Prisma ORM
- **Infrastructure**: Upsun PaaS with preview environments

## Quick Start
```bash
npm install
npm run dev
# API runs on http://localhost:3000
# Frontend runs on http://localhost:3001

## Core Concepts
- **User**: Authenticated entity with roles (admin, user, guest)
- **Workspace**: Isolated environment for team collaboration
- **Pipeline**: Automated workflow triggered by events

## Project Structure
src/
├── api/          # Express routes and middleware
├── services/     # Business logic layer
├── models/       # Database models (Prisma)
├── utils/        # Shared utilities
└── types/        # TypeScript definitions

## External Dependencies
- Stripe API for payments (test mode in development)
- SendGrid for transactional emails
- Redis for session management
- S3-compatible storage for file uploads

# Development Guidelines for AI Assistants

## Team Philosophy
We prioritize code readability over cleverness. Our codebase should be maintainable by any team member, including juniors. We favor explicit over implicit, and simple over complex. When in doubt, choose the solution that's easier to debug at 3 AM during an incident.

## Code Style Preferences

### General Principles
- Functions should do one thing well (Single Responsibility)
- Prefer composition over inheritance
- Use early returns to reduce nesting
- Maximum line length: 100 characters
- Maximum file length: 300 lines (split larger files)
- Indent with 2 spaces (never tabs)

### Naming Conventions
- Variables: camelCase (userId, orderTotal)
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES, API_TIMEOUT)
- Classes: PascalCase (UserService, OrderController)
- Interfaces: PascalCase with 'I' prefix (IUserService, IOrderData)
- Type aliases: PascalCase (UserRole, OrderStatus)
- Files: kebab-case (user-service.ts, order-controller.ts)
- Test files: *.spec.ts or *.test.ts adjacent to source
- React components: PascalCase files (UserProfile.tsx)
- Hooks: use prefix (useAuth, useLocalStorage)
- Boolean variables: is/has/should prefix (isLoading, hasError, shouldRefresh)
- Event handlers: on prefix (onSubmit, onClick)
- Private methods: underscore prefix (_validateInput, _processData)

### Comment Standards
- Use JSDoc for public APIs
- Comments explain "why" not "what"
- TODO comments must include author and date: // TODO(john, 2024-03): Refactor after v2 launch
- No commented-out code in main branch
- Document complex regex patterns
- Document magic numbers

Example:

/**
 * Calculates compound interest with monthly contributions
 * @param principal - Initial investment amount
 * @param rate - Annual interest rate as decimal (0.05 for 5%)
 * @param years - Investment period in years
 * @param monthlyContribution - Optional monthly addition
 * @returns Total value after compound interest
 */
function calculateCompoundInterest(
  principal: number,
  rate: number, 
  years: number,
  monthlyContribution = 0
): number {
  // Using monthly compounding for more accurate results
  const monthlyRate = rate / 12;
  const months = years * 12;
  
  // Formula: P(1 + r)^n + PMT × (((1 + r)^n - 1) / r)
  // where P = principal, r = rate, n = periods, PMT = payment
  const compoundPrincipal = principal * Math.pow(1 + monthlyRate, months);
  const contributionValue = monthlyContribution * 
    ((Math.pow(1 + monthlyRate, months) - 1) / monthlyRate);
  
  return compoundPrincipal + contributionValue;
}


## TypeScript Conventions

### Type Safety Rules
- Always define explicit return types for functions
- Use interfaces for object shapes, types for unions/primitives
- Prefer `unknown` over `any` when type is truly unknown
- Use strict mode with all checks enabled
- Define DTOs for all API boundaries
- Use branded types for domain primitives

### Type Examples

// Branded type for type safety
type UserId = string & { readonly brand: unique symbol };
type OrderId = string & { readonly brand: unique symbol };

// Domain types with clear constraints
type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';

// Interface for data objects
interface IOrderData {
  id: OrderId;
  userId: UserId;
  items: IOrderItem[];
  status: OrderStatus;
  createdAt: Date;
  updatedAt: Date;
}

// Type for function options
type CreateOrderOptions = {
  skipInventoryCheck?: boolean;
  notifyUser?: boolean;
  priority?: 'normal' | 'high';
};

// Utility types we use frequently
type Nullable<T> = T | null;
type Optional<T> = T | undefined;
type AsyncResult<T, E = Error> = Promise<Result<T, E>>;


## Architecture Patterns

### Service Layer Pattern
All business logic lives in services, not controllers or models:

// ✅ Good: Business logic in service
class OrderService {
  async createOrder(data: CreateOrderDTO): Promise<Order> {
    // Validation
    await this.validateInventory(data.items);
    
    // Business logic
    const pricing = this.calculatePricing(data.items);
    
    // Persistence
    return this.orderRepository.create({
      ...data,
      ...pricing
    });
  }
}

// ❌ Bad: Business logic in controller
class OrderController {
  async create(req: Request, res: Response) {
    // Don't put business logic here!
    const pricing = calculatePricing(req.body.items); // Wrong!
  }
}


### Dependency Injection
Use constructor injection with interfaces:

class OrderService {
  constructor(
    private readonly orderRepo: IOrderRepository,
    private readonly inventoryService: IInventoryService,
    private readonly emailService: IEmailService
  ) {}
}


### Repository Pattern
Abstract data access behind repositories:

interface IUserRepository {
  findById(id: UserId): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  create(data: CreateUserDTO): Promise<User>;
  update(id: UserId, data: UpdateUserDTO): Promise<User>;
  softDelete(id: UserId): Promise<void>;
}


## Error Handling

### Error Classes
Define specific error classes for different scenarios:

// Base error class
abstract class ApplicationError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public code: string
  ) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

// Specific error types
class ValidationError extends ApplicationError {
  constructor(message: string, public fields: Record<string, string>) {
    super(message, 400, 'VALIDATION_ERROR');
  }
}

class NotFoundError extends ApplicationError {
  constructor(resource: string, id: string) {
    super(`${resource} with id ${id} not found`, 404, 'NOT_FOUND');
  }
}

class UnauthorizedError extends ApplicationError {
  constructor(message = 'Unauthorized') {
    super(message, 401, 'UNAUTHORIZED');
  }
}


### Error Handling Rules
- Never use `console.log` in production code
- Use structured logging with context
- Always handle promise rejections
- Throw custom error classes, not strings
- Don't expose internal errors to users
- Log full error details, return safe messages

Example:

async function processPayment(orderId: OrderId): Promise<void> {
  try {
    const order = await orderRepo.findById(orderId);
    if (!order) {
      throw new NotFoundError('Order', orderId);
    }
    
    await paymentGateway.charge(order.total);
    
  } catch (error) {
    logger.error('Payment processing failed', {
      orderId,
      error: error instanceof Error ? error.message : 'Unknown error',
      stack: error instanceof Error ? error.stack : undefined,
      timestamp: new Date().toISOString()
    });
    
    if (error instanceof ApplicationError) {
      throw error; // Re-throw known errors
    }
    
    // Don't expose internal errors
    throw new ApplicationError('Payment processing failed', 500, 'PAYMENT_ERROR');
  }
}


## Testing Philosophy

### Testing Principles
- Write tests first (TDD approach)
- Aim for 80% code coverage minimum
- Focus on behavior, not implementation
- Test public interfaces, not private methods
- Each test should test one thing
- Tests should be independent and idempotent

### Test Structure
Follow AAA pattern (Arrange, Act, Assert):

describe('OrderService', () => {
  describe('createOrder', () => {
    it('should calculate correct total with tax and shipping', async () => {
      // Arrange
      const mockItems = [
        { productId: '1', quantity: 2, price: 10.00 },
        { productId: '2', quantity: 1, price: 20.00 }
      ];
      const orderData = { items: mockItems, userId: 'user123' };
      
      // Act
      const result = await orderService.createOrder(orderData);
      
      // Assert
      expect(result.subtotal).toBe(40.00);
      expect(result.tax).toBe(4.00); // 10% tax
      expect(result.shipping).toBe(5.00);
      expect(result.total).toBe(49.00);
    });
    
    it('should throw ValidationError when items array is empty', async () => {
      // Arrange
      const orderData = { items: [], userId: 'user123' };
      
      // Act & Assert
      await expect(orderService.createOrder(orderData))
        .rejects
        .toThrow(ValidationError);
    });
  });
});


### Mocking Strategy
- Mock external services (APIs, databases)
- Don't mock internal modules
- Use factories for test data
- Reset mocks between tests

## Database Patterns

### Query Patterns
- Use transactions for multi-table operations
- Always use parameterized queries
- Implement soft delete with `deletedAt` timestamps
- Include audit fields on all tables
- Use optimistic locking for concurrent updates

### Standard Fields
Every table must include:

interface IAuditFields {
  id: string; // UUID
  createdAt: Date;
  createdBy: UserId;
  updatedAt: Date;
  updatedBy: UserId;
  deletedAt: Date | null;
  deletedBy: UserId | null;
  version: number; // For optimistic locking
}


### Migration Rules
- Never modify existing migrations
- Always provide rollback logic
- Test migrations on copy of production data
- Name migrations descriptively: `001_add_user_email_verification.ts`

## API Design

### RESTful Conventions

GET    /api/v1/orders          # List with pagination
GET    /api/v1/orders/:id      # Get single resource
POST   /api/v1/orders          # Create new resource
PUT    /api/v1/orders/:id      # Full update
PATCH  /api/v1/orders/:id      # Partial update
DELETE /api/v1/orders/:id      # Soft delete


### Response Formats
Success response:

{
  "success": true,
  "data": {
    "id": "123",
    "name": "Example"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0.0"
  }
}


Error response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "requestId": "req_123456"
  }
}


### Pagination Standard

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}


## Security Requirements

### Authentication & Authorization
- Use JWT with refresh tokens
- Implement RBAC (Role-Based Access Control)
- Session timeout after 30 minutes of inactivity
- Require MFA for admin accounts
- Log all authentication events

### Input Validation
- Validate all input with Zod schemas
- Sanitize HTML content with DOMPurify
- Reject requests with unexpected fields
- Implement request size limits

### Security Headers

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      scriptSrc: ["'self'"],
      imgSrc: ["'self'", "data:", "https:"],
    },
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true
  }
}));


### Rate Limiting
- Public endpoints: 100 requests/minute
- Authenticated endpoints: 1000 requests/minute  
- Login endpoints: 5 attempts/15 minutes
- Use sliding window algorithm

## Performance Standards

### Response Time Targets
- API endpoints: < 200ms (p95)
- Database queries: < 50ms
- External API calls: implement circuit breakers
- Page load time: < 3 seconds

### Optimization Rules
- Implement pagination for lists (max 100 items)
- Use database indexes on foreign keys and frequently queried fields
- Cache expensive computations with Redis
- Implement database connection pooling
- Use CDN for static assets

## Git Workflow

### Branch Naming
- Features: `feature/JIRA-123-user-authentication`
- Bugfixes: `bugfix/JIRA-456-payment-calculation`
- Hotfixes: `hotfix/JIRA-789-critical-security-fix`
- Releases: `release/v1.2.0`

### Commit Message Format
Follow conventional commits:

type(scope): subject

body (optional)

footer (optional)


Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes
- refactor: Code refactoring
- perf: Performance improvements
- test: Test additions or corrections
- chore: Build process or auxiliary tool changes

Example:

feat(auth): implement OAuth2 login with Google

- Added Google OAuth2 strategy
- Created callback endpoint for token exchange
- Updated user model to store OAuth profiles

Closes JIRA-123


### PR Rules
- PRs must pass all CI checks
- Require at least 2 approvals
- Must include tests for new features
- Update documentation for API changes
- Link to JIRA ticket in description

## Documentation Standards

### Code Documentation
- Document all public APIs with JSDoc
- Include examples in documentation
- Keep documentation next to code
- Update documentation with code changes

### API Documentation
- Use OpenAPI 3.0 specification
- Include request/response examples
- Document all error codes
- Provide curl examples

### README Files
Each module should have a README explaining:
- Purpose and responsibilities
- Public interface
- Usage examples
- Dependencies
- Configuration options

## Monitoring and Logging

### Logging Levels
- ERROR: System errors requiring immediate attention
- WARN: Issues that should be investigated
- INFO: Important business events
- DEBUG: Detailed diagnostic information

### What to Log
- All API requests (method, path, duration, status)
- Authentication events (login, logout, failed attempts)
- Database query times > 100ms
- External API calls and responses
- Business events (order created, payment processed)
- Errors with full context

### Metrics to Track
- Request rate and latency (by endpoint)
- Error rate (4xx vs 5xx)
- Database connection pool usage
- Queue lengths and processing times
- Business metrics (orders/hour, conversion rate)

## Development Environment

### Required Tools
- Node.js 20.x LTS
- TypeScript 5.x
- Docker and Docker Compose
- Git 2.x
- VS Code with team settings

### VS Code Extensions
- ESLint
- Prettier
- GitLens
- Docker
- Thunder Client (API testing)
- Error Lens
- TODO Highlight

### Environment Variables
Never commit .env files. Use .env.example:

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname

# Redis
REDIS_URL=redis://localhost:6379

# Auth
JWT_SECRET=your-secret-here
JWT_REFRESH_SECRET=your-refresh-secret

# External APIs
STRIPE_API_KEY=sk_test_...
SENDGRID_API_KEY=SG...

# Feature Flags
ENABLE_NEW_PAYMENT_FLOW=false


## Definition of Done

A task is only "done" when:
- [ ] Code is written and follows team conventions
- [ ] Unit tests written and passing (>80% coverage)
- [ ] Integration tests for API endpoints
- [ ] Code reviewed and approved by 2 team members
- [ ] Documentation updated (code, API, README)
- [ ] No linting or TypeScript errors
- [ ] Security scan passed
- [ ] Performance requirements met
- [ ] Deployed to staging and tested
- [ ] Monitoring and alerts configured
- [ ] Feature flag configured (if applicable)
- [ ] JIRA ticket updated and moved to Done

## AI-Specific Instructions

When generating code:
1. Always follow these conventions without exception
2. If unsure about a convention, ask for clarification
3. Generate complete code, not snippets
4. Include error handling in all examples
5. Write tests alongside implementation
6. Add detailed comments for complex logic
7. Use our established patterns, don't introduce new ones
8. Validate all inputs according to our standards
9. Follow our Git commit message format
10. Alert us to any security concerns

Remember: Consistency is more important than perfection. Follow team patterns even if you know a "better" way.

## React/Frontend Conventions

### Component Structure
- One component per file
- Co-locate styles, tests, and stories
- Use function components with hooks
- Props interface named `I{ComponentName}Props`

### State Management
- Use Zustand for global state
- React Query for server state
- Local state with useState/useReducer
- No Redux (legacy pattern for us)

### Styling
- CSS Modules for component styles
- Tailwind for utility classes
- No inline styles except dynamic values
- Mobile-first responsive design

## Microservices Patterns

### Service Communication
- REST for synchronous communication
- RabbitMQ for async messaging
- gRPC for internal service-to-service
- GraphQL federation for client-facing API

### Service Boundaries
- Each service owns its database
- No shared database access
- Data duplication is acceptable
- Event sourcing for data sync

## Infrastructure as Code

### Container Standards
- Multi-stage Docker builds
- Non-root user in containers
- Health checks required
- Resource limits defined

### CI/CD Pipeline
- Build -> Test -> Security Scan -> Deploy
- Automatic rollback on metric degradation
- Blue-green deployments for production
- Canary releases for high-risk changes

## Multi-Tenant Implementation Plan

### Isolation Strategy: Row-Level Security (RLS)
**Justification**: Simpler operations, better resource utilization, easier backup/restore per tenant

### Database Changes

#### New Tables
1. **organizations**
   - id, name, slug (unique), created_at, settings (JSONB)
   - Purpose: Root tenant entity

2. **organization_users**
   - organization_id, user_id, role, joined_at
   - Purpose: Many-to-many relationship with roles

#### Modified Tables (add tenant_id)
- projects → add organization_id (FK, NOT NULL after migration)
- documents → add organization_id (via projects relation)
- api_keys → add organization_id

#### Migrations Required

// 001_add_organizations.ts
- Create organizations table
- Create organization_users table
- Add organization_id to affected tables (nullable initially)

// 002_populate_default_org.ts
- Create default organization for existing data
- Update all records with default org
- Make organization_id NOT NULL

// 003_add_rls_policies.ts
- Enable RLS on all tenant tables
- Create policies for tenant isolation


### API Changes

#### New Middleware: src/middleware/tenantContext.ts

// Extracts organization from subdomain or header
// Verifies user has access to organization
// Injects organizationId into req.context
// All queries automatically filtered by tenant


#### Modified Services
1. **src/services/auth.service.ts**
   - Add organization selection to login response
   - Include available organizations in JWT

2. **src/services/prisma.service.ts**
   - Extend Prisma client with automatic tenant filtering
   - Use middleware to inject WHERE clauses

### Test Scenarios

1. **Isolation Tests** (src/tests/multitenancy/isolation.spec.ts)
   - User A in Org1 cannot see Org2 data
   - API calls without org context fail
   - Direct database queries respect RLS

2. **Migration Tests** (src/tests/multitenancy/migration.spec.ts)
   - Existing data accessible after migration
   - Rollback preserves data integrity

3. **Performance Tests**
   - Query performance with tenant filtering
   - Index effectiveness on organization_id

### Rollout Strategy
1. Deploy with feature flag disabled
2. Run migrations in maintenance window
3. Enable for internal testing organization
4. Gradual percentage rollout
5. Full enablement after 1 week stability

### Rollback Plan
- Feature flag disables tenant filtering
- Keep organization_id columns (harmless if unused)
- Revert RLS policies if issues arise

// .eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser',
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:@typescript-eslint/recommended-requiring-type-checking',
    'plugin:security/recommended',
    'plugin:node/recommended'
  ],
  plugins: [
    '@typescript-eslint',
    'security',
    'no-secrets',
    'promise',
    'unicorn'
  ],
  rules: {
    // Catch common AI mistakes
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/explicit-function-return-type': 'error',
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/no-floating-promises': 'error',
    
    // Security rules for AI-generated code
    'security/detect-object-injection': 'error',
    'security/detect-non-literal-regexp': 'error',
    'security/detect-eval-with-expression': 'error',
    'no-secrets/no-secrets': 'error',
    
    // Prevent hallucinated imports
    'node/no-missing-import': 'error',
    'node/no-unpublished-import': 'error',
    
    // Code quality
    'complexity': ['error', { max: 10 }],
    'max-lines-per-function': ['error', { max: 50 }],
    'max-depth': ['error', { max: 3 }]
  },
  parserOptions: {
    project: './tsconfig.json'
  }
};

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    coverage: {
      provider: 'c8',
      reporter: ['text', 'json', 'html'],
      lines: 80,
      functions: 80,
      branches: 80,
      statements: 80,
      checkCoverage: true,
      excludeNodeModules: true
    },
    testTimeout: 10000,
    hookTimeout: 10000,
    teardownTimeout: 10000,
    isolate: true,
    threads: true,
    mockReset: true
  }
});

# .github/workflows/ai-code-review.yml
name: AI Code Quality Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: TypeScript compile check
        run: npm run build
        
      - name: ESLint security audit
        run: npm run lint:security
        
      - name: Run tests with coverage
        run: npm run test:coverage
        
      - name: Check for common AI anti-patterns
        run: |
          # Check for console.log in production code
          if grep -r "console\.log" --include="*.ts" --exclude-dir="test" src/; then
            echo "❌ Found console.log in production code"
            exit 1
          fi
          
          # Check for hardcoded secrets
          if grep -rE "(api[_-]?key|secret|password|token)\s*=\s*[\"'][^\"']+[\"']" --include="*.ts" src/; then
            echo "❌ Possible hardcoded secrets found"
            exit 1
          fi
          
          # Check for TODO comments (incomplete AI implementation)
          if grep -r "TODO\|FIXME\|XXX" --include="*.ts" src/; then
            echo "⚠️ Found TODO comments - ensure implementation is complete"
          fi          
      
      - name: Comment PR with results
        uses: actions/github-script@v6
        if: always()
        with:
          script: |
            const fs = require('fs');
            const coverage = JSON.parse(fs.readFileSync('coverage/coverage-summary.json', 'utf8'));
            const total = coverage.total;
            
            const comment = `## AI Code Review Results
            
            ### Coverage Report
            - Lines: ${total.lines.pct}%
            - Functions: ${total.functions.pct}%
            - Branches: ${total.branches.pct}%
            - Statements: ${total.statements.pct}%
            
            ${total.lines.pct < 80 ? '⚠️ Coverage below 80% threshold' : '✅ Coverage meets requirements'}
            `;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });            

{
  "servers": {
    "upsun": {
      "type": "http", 
      "url": "https://mcp.upsun.com",
      "headers": {
        "upsun-api-token": "---",
        "enable-write": "true"
      } 
    },
    "postgres": {
      "command": "npx",
      "args": ["mcp-server-postgres", "postgresql://localhost/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["mcp-server-playwright"]
    }
  }
}

# Deployment Context (add to AGENTS.md)

## Platform: Upsun
- Git-driven deployments from main branch
- Preview environments for each pull request
- Environment variables managed via platform
- Build hooks run during deployment
- Services configured in .upsun/config.yaml

## Build Process

# .upsun/config.yaml snippet
applications:
  app:
    build:
      flavor: none
    hooks:
      build: |
        npm ci --production=false
        npm run build
        npm prune --production
    deploy: |
        npm run migrate

## Available Services
- PostgreSQL 15 (primary database)
- Redis 7 (caching and sessions)
- Elasticsearch 8 (search)
- RabbitMQ (message queue)

## Environment-Specific Behavior
- Production: main branch
- Staging: staging branch  
- Preview: PR-* branches (data cloned from staging)
- Local: Use docker-compose for service parity