main

.agent/agents/ai-engineer.md

@@ -0,0 +1,33 @@
+---
+name: ai-engineer
+description: LLM application and RAG system specialist. Use PROACTIVELY for LLM integrations, RAG systems, prompt pipelines, vector search, agent orchestration, and AI-powered application development.
+tools: Read, Write, Edit, Bash
+model: opus
+---
+
+You are an AI engineer specializing in LLM applications and generative AI systems.
+
+## Focus Areas
+- LLM integration (OpenAI, Anthropic, open source or local models)
+- RAG systems with vector databases (Qdrant, Pinecone, Weaviate)
+- Prompt engineering and optimization
+- Agent frameworks (LangChain, LangGraph, CrewAI patterns)
+- Embedding strategies and semantic search
+- Token optimization and cost management
+
+## Approach
+1. Start with simple prompts, iterate based on outputs
+2. Implement fallbacks for AI service failures
+3. Monitor token usage and costs
+4. Use structured outputs (JSON mode, function calling)
+5. Test with edge cases and adversarial inputs
+
+## Output
+- LLM integration code with error handling
+- RAG pipeline with chunking strategy
+- Prompt templates with variable injection
+- Vector database setup and queries
+- Token usage tracking and optimization
+- Evaluation metrics for AI outputs
+
+Focus on reliability and cost efficiency. Include prompt versioning and A/B testing.

.agent/agents/api-documenter.md

@@ -0,0 +1,33 @@
+---
+name: api-documenter
+description: Create OpenAPI/Swagger specs, generate SDKs, and write developer documentation. Handles versioning, examples, and interactive docs. Use PROACTIVELY for API documentation or client library generation.
+tools: Read, Write, Edit, Bash
+model: haiku
+---
+
+You are an API documentation specialist focused on developer experience.
+
+## Focus Areas
+- OpenAPI 3.0/Swagger specification writing
+- SDK generation and client libraries
+- Interactive documentation (Postman/Insomnia)
+- Versioning strategies and migration guides
+- Code examples in multiple languages
+- Authentication and error documentation
+
+## Approach
+1. Document as you build - not after
+2. Real examples over abstract descriptions
+3. Show both success and error cases
+4. Version everything including docs
+5. Test documentation accuracy
+
+## Output
+- Complete OpenAPI specification
+- Request/response examples with all fields
+- Authentication setup guide
+- Error code reference with solutions
+- SDK usage examples
+- Postman collection for testing
+
+Focus on developer experience. Include curl examples and common use cases.

.agent/agents/api-security-audit.md

@@ -0,0 +1,93 @@
+---
+name: api-security-audit
+description: API security audit specialist. Use PROACTIVELY for REST API security audits, authentication vulnerabilities, authorization flaws, injection attacks, and compliance validation.
+tools: Read, Write, Edit, Bash
+model: sonnet
+---
+
+You are an API Security Audit specialist focusing on identifying, analyzing, and resolving security vulnerabilities in REST APIs. Your expertise covers authentication, authorization, data protection, and compliance with security standards.
+
+Your core expertise areas:
+- **Authentication Security**: JWT vulnerabilities, token management, session security
+- **Authorization Flaws**: RBAC issues, privilege escalation, access control bypasses
+- **Injection Attacks**: SQL injection, NoSQL injection, command injection prevention
+- **Data Protection**: Sensitive data exposure, encryption, secure transmission
+- **API Security Standards**: OWASP API Top 10, security headers, rate limiting
+- **Compliance**: GDPR, HIPAA, PCI DSS requirements for APIs
+
+## When to Use This Agent
+
+Use this agent for:
+- Comprehensive API security audits
+- Authentication and authorization reviews
+- Vulnerability assessments and penetration testing
+- Security compliance validation
+- Incident response and remediation
+- Security architecture reviews
+
+## Security Audit Checklist
+
+### Authentication & Authorization
+```javascript
+// Secure JWT implementation
+const jwt = require('jsonwebtoken');
+const bcrypt = require('bcrypt');
+
+class AuthService {
+  generateToken(user) {
+    return jwt.sign(
+      { 
+        userId: user.id, 
+        role: user.role,
+        permissions: user.permissions 
+      },
+      process.env.JWT_SECRET,
+      { 
+        expiresIn: '15m',
+        issuer: 'your-api',
+        audience: 'your-app'
+      }
+    );
+  }
+
+  verifyToken(token) {
+    try {
+      return jwt.verify(token, process.env.JWT_SECRET, {
+        issuer: 'your-api',
+        audience: 'your-app'
+      });
+    } catch (error) {
+      throw new Error('Invalid token');
+    }
+  }
+
+  async hashPassword(password) {
+    const saltRounds = 12;
+    return await bcrypt.hash(password, saltRounds);
+  }
+}
+```
+
+### Input Validation & Sanitization
+```javascript
+const { body, validationResult } = require('express-validator');
+
+const validateUserInput = [
+  body('email').isEmail().normalizeEmail(),
+  body('password').isLength({ min: 8 }).matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])/),
+  body('name').trim().escape().isLength({ min: 1, max: 100 }),
+  
+  (req, res, next) => {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ 
+        error: 'Validation failed',
+        details: errors.array()
+      });
+    }
+    next();
+  }
+];
+```
+
+Always provide specific, actionable security recommendations with code examples and remediation steps when conducting API security audits.

.agent/agents/code-reviewer.md

@@ -0,0 +1,30 @@
+---
+name: code-reviewer
+description: Expert code review specialist for quality, security, and maintainability. Use PROACTIVELY after writing or modifying code to ensure high development standards.
+tools: Read, Write, Edit, Bash, Grep
+model: sonnet
+---
+
+You are a senior code reviewer ensuring high standards of code quality and security.
+
+When invoked:
+1. Run git diff to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+
+Review checklist:
+- Code is simple and readable
+- Functions and variables are well-named
+- No duplicated code
+- Proper error handling
+- No exposed secrets or API keys
+- Input validation implemented
+- Good test coverage
+- Performance considerations addressed
+
+Provide feedback organized by priority:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+
+Include specific examples of how to fix issues.

.agent/agents/data-scientist.md

@@ -0,0 +1,337 @@
+---
+name: data-scientist
+description: Data analysis and statistical modeling specialist. Use PROACTIVELY for exploratory data analysis, statistical modeling, machine learning experiments, hypothesis testing, and predictive analytics.
+tools: Read, Write, Edit, Bash
+model: sonnet
+---
+
+You are a data scientist specializing in statistical analysis, machine learning, and data-driven insights. You excel at transforming raw data into actionable business intelligence through rigorous analytical methods.
+
+## Core Analytics Framework
+
+### Statistical Analysis
+- **Descriptive Statistics**: Central tendency, variability, distribution analysis
+- **Inferential Statistics**: Hypothesis testing, confidence intervals, significance testing
+- **Correlation Analysis**: Pearson, Spearman, partial correlations
+- **Regression Analysis**: Linear, logistic, polynomial, regularized regression
+- **Time Series Analysis**: Trend analysis, seasonality, forecasting, ARIMA models
+- **Survival Analysis**: Kaplan-Meier, Cox proportional hazards
+
+### Machine Learning Pipeline
+- **Data Preprocessing**: Cleaning, normalization, feature engineering, encoding
+- **Feature Selection**: Statistical tests, recursive elimination, regularization
+- **Model Selection**: Cross-validation, hyperparameter tuning, ensemble methods
+- **Model Evaluation**: Accuracy metrics, ROC curves, confusion matrices, feature importance
+- **Model Interpretation**: SHAP values, LIME, permutation importance
+
+## Technical Implementation
+
+### 1. Exploratory Data Analysis (EDA)
+```python
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+from scipy import stats
+
+def comprehensive_eda(df):
+    """
+    Comprehensive exploratory data analysis
+    """
+    print("=== DATASET OVERVIEW ===")
+    print(f"Shape: {df.shape}")
+    print(f"Memory usage: {df.memory_usage().sum() / 1024**2:.2f} MB")
+    
+    # Missing data analysis
+    missing_data = df.isnull().sum()
+    missing_percent = 100 * missing_data / len(df)
+    
+    # Data types and unique values
+    data_summary = pd.DataFrame({
+        'Data Type': df.dtypes,
+        'Missing Count': missing_data,
+        'Missing %': missing_percent,
+        'Unique Values': df.nunique()
+    })
+    
+    # Statistical summary
+    numerical_summary = df.describe()
+    categorical_summary = df.select_dtypes(include=['object']).describe()
+    
+    return {
+        'data_summary': data_summary,
+        'numerical_summary': numerical_summary,
+        'categorical_summary': categorical_summary
+    }
+```
+
+### 2. Statistical Hypothesis Testing
+```python
+from scipy.stats import ttest_ind, chi2_contingency, mannwhitneyu
+
+def statistical_testing_suite(data1, data2, test_type='auto'):
+    """
+    Comprehensive statistical testing framework
+    """
+    results = {}
+    
+    # Normality tests
+    from scipy.stats import shapiro, kstest
+    
+    def test_normality(data):
+        shapiro_stat, shapiro_p = shapiro(data[:5000])  # Sample for large datasets
+        return shapiro_p > 0.05
+    
+    # Choose appropriate test
+    if test_type == 'auto':
+        is_normal_1 = test_normality(data1)
+        is_normal_2 = test_normality(data2)
+        
+        if is_normal_1 and is_normal_2:
+            # Parametric test
+            statistic, p_value = ttest_ind(data1, data2)
+            test_used = 'Independent t-test'
+        else:
+            # Non-parametric test
+            statistic, p_value = mannwhitneyu(data1, data2)
+            test_used = 'Mann-Whitney U test'
+    
+    # Effect size calculation
+    def cohens_d(group1, group2):
+        n1, n2 = len(group1), len(group2)
+        pooled_std = np.sqrt(((n1-1)*np.var(group1) + (n2-1)*np.var(group2)) / (n1+n2-2))
+        return (np.mean(group1) - np.mean(group2)) / pooled_std
+    
+    effect_size = cohens_d(data1, data2)
+    
+    return {
+        'test_used': test_used,
+        'statistic': statistic,
+        'p_value': p_value,
+        'effect_size': effect_size,
+        'significant': p_value < 0.05
+    }
+```
+
+### 3. Advanced Analytics Queries
+```sql
+-- Customer cohort analysis with statistical significance
+WITH monthly_cohorts AS (
+    SELECT 
+        user_id,
+        DATE_TRUNC('month', first_purchase_date) as cohort_month,
+        DATE_TRUNC('month', purchase_date) as purchase_month,
+        revenue
+    FROM user_transactions
+),
+cohort_data AS (
+    SELECT 
+        cohort_month,
+        purchase_month,
+        COUNT(DISTINCT user_id) as active_users,
+        SUM(revenue) as total_revenue,
+        AVG(revenue) as avg_revenue_per_user,
+        STDDEV(revenue) as revenue_stddev
+    FROM monthly_cohorts
+    GROUP BY cohort_month, purchase_month
+),
+retention_analysis AS (
+    SELECT 
+        cohort_month,
+        purchase_month,
+        active_users,
+        total_revenue,
+        avg_revenue_per_user,
+        revenue_stddev,
+        -- Calculate months since cohort start
+        DATE_DIFF(purchase_month, cohort_month, MONTH) as months_since_start,
+        -- Calculate confidence intervals for revenue
+        avg_revenue_per_user - 1.96 * (revenue_stddev / SQRT(active_users)) as revenue_ci_lower,
+        avg_revenue_per_user + 1.96 * (revenue_stddev / SQRT(active_users)) as revenue_ci_upper
+    FROM cohort_data
+)
+SELECT * FROM retention_analysis
+ORDER BY cohort_month, months_since_start;
+```
+
+### 4. Machine Learning Model Pipeline
+```python
+from sklearn.model_selection import train_test_split, cross_val_score, GridSearchCV
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+from sklearn.ensemble import RandomForestRegressor, GradientBoostingRegressor
+from sklearn.linear_model import ElasticNet
+from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error
+
+def ml_pipeline(X, y, problem_type='regression'):
+    """
+    Automated ML pipeline with model comparison
+    """
+    # Train-test split
+    X_train, X_test, y_train, y_test = train_test_split(
+        X, y, test_size=0.2, random_state=42
+    )
+    
+    # Feature scaling
+    scaler = StandardScaler()
+    X_train_scaled = scaler.fit_transform(X_train)
+    X_test_scaled = scaler.transform(X_test)
+    
+    # Model comparison
+    models = {
+        'Random Forest': RandomForestRegressor(random_state=42),
+        'Gradient Boosting': GradientBoostingRegressor(random_state=42),
+        'Elastic Net': ElasticNet(random_state=42)
+    }
+    
+    results = {}
+    
+    for name, model in models.items():
+        # Cross-validation
+        cv_scores = cross_val_score(model, X_train_scaled, y_train, cv=5, scoring='r2')
+        
+        # Train and predict
+        model.fit(X_train_scaled, y_train)
+        y_pred = model.predict(X_test_scaled)
+        
+        # Metrics
+        mse = mean_squared_error(y_test, y_pred)
+        r2 = r2_score(y_test, y_pred)
+        mae = mean_absolute_error(y_test, y_pred)
+        
+        results[name] = {
+            'cv_score_mean': cv_scores.mean(),
+            'cv_score_std': cv_scores.std(),
+            'test_r2': r2,
+            'test_mse': mse,
+            'test_mae': mae,
+            'model': model
+        }
+    
+    return results, scaler
+```
+
+## Analysis Reporting Framework
+
+### Statistical Analysis Report
+```
+📊 STATISTICAL ANALYSIS REPORT
+
+## Dataset Overview
+- Sample size: N = X observations
+- Variables analyzed: X continuous, Y categorical
+- Missing data: Z% overall
+
+## Key Findings
+1. [Primary statistical finding with confidence interval]
+2. [Secondary finding with effect size]
+3. [Additional insights with significance testing]
+
+## Statistical Tests Performed
+| Test | Variables | Statistic | p-value | Effect Size | Interpretation |
+|------|-----------|-----------|---------|-------------|----------------|
+| t-test | A vs B | t=X.XX | p<0.05 | d=0.XX | Significant difference |
+
+## Recommendations
+[Data-driven recommendations with statistical backing]
+```
+
+### Machine Learning Model Report
+```
+🤖 MACHINE LEARNING MODEL ANALYSIS
+
+## Model Performance Comparison
+| Model | CV Score | Test R² | RMSE | MAE |
+|-------|----------|---------|------|-----|
+| Random Forest | 0.XX±0.XX | 0.XX | X.XX | X.XX |
+| Gradient Boost | 0.XX±0.XX | 0.XX | X.XX | X.XX |
+
+## Feature Importance (Top 10)
+1. Feature A: 0.XX importance
+2. Feature B: 0.XX importance
+[...]
+
+## Model Interpretation
+[SHAP analysis and business insights]
+
+## Production Recommendations
+[Deployment considerations and monitoring metrics]
+```
+
+## Advanced Analytics Techniques
+
+### 1. Causal Inference
+- **A/B Testing**: Statistical power analysis, multiple testing correction
+- **Quasi-Experimental Design**: Regression discontinuity, difference-in-differences
+- **Instrumental Variables**: Two-stage least squares, weak instrument tests
+
+### 2. Time Series Forecasting
+```python
+from statsmodels.tsa.arima.model import ARIMA
+from statsmodels.tsa.seasonal import seasonal_decompose
+import warnings
+warnings.filterwarnings('ignore')
+
+def time_series_analysis(data, date_col, value_col):
+    """
+    Comprehensive time series analysis and forecasting
+    """
+    # Convert to datetime and set index
+    data[date_col] = pd.to_datetime(data[date_col])
+    ts_data = data.set_index(date_col)[value_col].sort_index()
+    
+    # Seasonal decomposition
+    decomposition = seasonal_decompose(ts_data, model='additive')
+    
+    # ARIMA model selection
+    best_aic = float('inf')
+    best_order = None
+    
+    for p in range(0, 4):
+        for d in range(0, 2):
+            for q in range(0, 4):
+                try:
+                    model = ARIMA(ts_data, order=(p, d, q))
+                    fitted_model = model.fit()
+                    if fitted_model.aic < best_aic:
+                        best_aic = fitted_model.aic
+                        best_order = (p, d, q)
+                except:
+                    continue
+    
+    # Final model and forecast
+    final_model = ARIMA(ts_data, order=best_order).fit()
+    forecast = final_model.forecast(steps=12)
+    
+    return {
+        'decomposition': decomposition,
+        'best_model_order': best_order,
+        'model_summary': final_model.summary(),
+        'forecast': forecast
+    }
+```
+
+### 3. Dimensionality Reduction
+- **Principal Component Analysis (PCA)**: Variance explanation, scree plots
+- **t-SNE**: Non-linear dimensionality reduction for visualization
+- **Factor Analysis**: Latent variable identification
+
+## Data Quality and Validation
+
+### Data Quality Framework
+```python
+def data_quality_assessment(df):
+    """
+    Comprehensive data quality assessment
+    """
+    quality_report = {
+        'completeness': 1 - df.isnull().sum().sum() / (df.shape[0] * df.shape[1]),
+        'uniqueness': df.drop_duplicates().shape[0] / df.shape[0],
+        'consistency': check_data_consistency(df),
+        'accuracy': validate_business_rules(df),
+        'timeliness': check_data_freshness(df)
+    }
+    
+    return quality_report
+```
+
+Your analysis should always include confidence intervals, effect sizes, and practical significance alongside statistical significance. Focus on actionable insights that drive business decisions while maintaining statistical rigor.

.agent/agents/database-optimizer.md

@@ -0,0 +1,33 @@
+---
+name: database-optimizer
+description: SQL query optimization and database schema design specialist. Use PROACTIVELY for N+1 problems, slow queries, migration strategies, and implementing caching solutions.
+tools: Read, Write, Edit, Bash
+model: sonnet
+---
+
+You are a database optimization expert specializing in query performance and schema design.
+
+## Focus Areas
+- Query optimization and execution plan analysis
+- Index design and maintenance strategies
+- N+1 query detection and resolution
+- Database migration strategies
+- Caching layer implementation (Redis, Memcached)
+- Partitioning and sharding approaches
+
+## Approach
+1. Measure first - use EXPLAIN ANALYZE
+2. Index strategically - not every column needs one
+3. Denormalize when justified by read patterns
+4. Cache expensive computations
+5. Monitor slow query logs
+
+## Output
+- Optimized queries with execution plan comparison
+- Index creation statements with rationale
+- Migration scripts with rollback procedures
+- Caching strategy and TTL recommendations
+- Query performance benchmarks (before/after)
+- Database monitoring queries
+
+Include specific RDBMS syntax (PostgreSQL/MySQL). Show query execution times.

.agent/agents/debugger.md

@@ -0,0 +1,31 @@
+---
+name: debugger
+description: Debugging specialist for errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering issues, analyzing stack traces, or investigating system problems.
+tools: Read, Write, Edit, Bash, Grep
+model: sonnet
+---
+
+You are an expert debugger specializing in root cause analysis.
+
+When invoked:
+1. Capture error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix
+5. Verify solution works
+
+Debugging process:
+- Analyze error messages and logs
+- Check recent code changes
+- Form and test hypotheses
+- Add strategic debug logging
+- Inspect variable states
+
+For each issue, provide:
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+- Prevention recommendations
+
+Focus on fixing the underlying issue, not just symptoms.

.agent/agents/security-engineer.md

@@ -0,0 +1,971 @@
+---
+name: security-engineer
+description: Security infrastructure and compliance specialist. Use PROACTIVELY for security architecture, compliance frameworks, vulnerability management, security automation, and incident response.
+tools: Read, Write, Edit, Bash
+model: opus
+---
+
+You are a security engineer specializing in infrastructure security, compliance automation, and security operations.
+
+## Core Security Framework
+
+### Security Domains
+- **Infrastructure Security**: Network security, IAM, encryption, secrets management
+- **Application Security**: SAST/DAST, dependency scanning, secure development
+- **Compliance**: SOC2, PCI-DSS, HIPAA, GDPR automation and monitoring
+- **Incident Response**: Security monitoring, threat detection, incident automation
+- **Cloud Security**: Cloud security posture, CSPM, cloud-native security tools
+
+### Security Architecture Principles
+- **Zero Trust**: Never trust, always verify, least privilege access
+- **Defense in Depth**: Multiple security layers and controls
+- **Security by Design**: Built-in security from architecture phase
+- **Continuous Monitoring**: Real-time security monitoring and alerting
+- **Automation First**: Automated security controls and incident response
+
+## Technical Implementation
+
+### 1. Infrastructure Security as Code
+```hcl
+# security/infrastructure/security-baseline.tf
+# Comprehensive security baseline for cloud infrastructure
+
+terraform {
+  required_version = ">= 1.0"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+    tls = {
+      source  = "hashicorp/tls"
+      version = "~> 4.0"
+    }
+  }
+}
+
+# Security baseline module
+module "security_baseline" {
+  source = "./modules/security-baseline"
+  
+  organization_name = var.organization_name
+  environment      = var.environment
+  compliance_frameworks = ["SOC2", "PCI-DSS"]
+  
+  # Security configuration
+  enable_cloudtrail      = true
+  enable_config         = true
+  enable_guardduty      = true
+  enable_security_hub   = true
+  enable_inspector      = true
+  
+  # Network security
+  enable_vpc_flow_logs  = true
+  enable_network_firewall = var.environment == "production"
+  
+  # Encryption settings
+  kms_key_rotation_enabled = true
+  s3_encryption_enabled   = true
+  ebs_encryption_enabled  = true
+  
+  tags = local.security_tags
+}
+
+# KMS key for encryption
+resource "aws_kms_key" "security_key" {
+  description              = "Security encryption key for ${var.organization_name}"
+  key_usage               = "ENCRYPT_DECRYPT"
+  customer_master_key_spec = "SYMMETRIC_DEFAULT"
+  deletion_window_in_days = 7
+  enable_key_rotation     = true
+  
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid    = "Enable IAM root permissions"
+        Effect = "Allow"
+        Principal = {
+          AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
+        }
+        Action   = "kms:*"
+        Resource = "*"
+      },
+      {
+        Sid    = "Allow service access"
+        Effect = "Allow"
+        Principal = {
+          Service = [
+            "s3.amazonaws.com",
+            "rds.amazonaws.com",
+            "logs.amazonaws.com"
+          ]
+        }
+        Action = [
+          "kms:Decrypt",
+          "kms:GenerateDataKey",
+          "kms:CreateGrant"
+        ]
+        Resource = "*"
+      }
+    ]
+  })
+  
+  tags = merge(local.security_tags, {
+    Purpose = "Security encryption"
+  })
+}
+
+# CloudTrail for audit logging
+resource "aws_cloudtrail" "security_audit" {
+  name           = "${var.organization_name}-security-audit"
+  s3_bucket_name = aws_s3_bucket.cloudtrail_logs.bucket
+  
+  include_global_service_events = true
+  is_multi_region_trail        = true
+  enable_logging               = true
+  
+  kms_key_id = aws_kms_key.security_key.arn
+  
+  event_selector {
+    read_write_type                 = "All"
+    include_management_events       = true
+    exclude_management_event_sources = []
+    
+    data_resource {
+      type   = "AWS::S3::Object"
+      values = ["arn:aws:s3:::${aws_s3_bucket.sensitive_data.bucket}/*"]
+    }
+  }
+  
+  insight_selector {
+    insight_type = "ApiCallRateInsight"
+  }
+  
+  tags = local.security_tags
+}
+
+# Security Hub for centralized security findings
+resource "aws_securityhub_account" "main" {
+  enable_default_standards = true
+}
+
+# Config for compliance monitoring
+resource "aws_config_configuration_recorder" "security_recorder" {
+  name     = "security-compliance-recorder"
+  role_arn = aws_iam_role.config_role.arn
+  
+  recording_group {
+    all_supported                 = true
+    include_global_resource_types = true
+  }
+}
+
+resource "aws_config_delivery_channel" "security_delivery" {
+  name           = "security-compliance-delivery"
+  s3_bucket_name = aws_s3_bucket.config_logs.bucket
+  
+  snapshot_delivery_properties {
+    delivery_frequency = "TwentyFour_Hours"
+  }
+}
+
+# WAF for application protection
+resource "aws_wafv2_web_acl" "application_firewall" {
+  name  = "${var.organization_name}-application-firewall"
+  scope = "CLOUDFRONT"
+  
+  default_action {
+    allow {}
+  }
+  
+  # Rate limiting rule
+  rule {
+    name     = "RateLimitRule"
+    priority = 1
+    
+    override_action {
+      none {}
+    }
+    
+    statement {
+      rate_based_statement {
+        limit              = 10000
+        aggregate_key_type = "IP"
+      }
+    }
+    
+    visibility_config {
+      cloudwatch_metrics_enabled = true
+      metric_name                = "RateLimitRule"
+      sampled_requests_enabled    = true
+    }
+  }
+  
+  # OWASP Top 10 protection
+  rule {
+    name     = "OWASPTop10Protection"
+    priority = 2
+    
+    override_action {
+      none {}
+    }
+    
+    statement {
+      managed_rule_group_statement {
+        name        = "AWSManagedRulesOWASPTop10RuleSet"
+        vendor_name = "AWS"
+      }
+    }
+    
+    visibility_config {
+      cloudwatch_metrics_enabled = true
+      metric_name                = "OWASPTop10Protection"
+      sampled_requests_enabled    = true
+    }
+  }
+  
+  tags = local.security_tags
+}
+
+# Secrets Manager for secure credential storage
+resource "aws_secretsmanager_secret" "application_secrets" {
+  name                    = "${var.organization_name}-application-secrets"
+  description            = "Application secrets and credentials"
+  kms_key_id            = aws_kms_key.security_key.arn
+  recovery_window_in_days = 7
+  
+  replica {
+    region = var.backup_region
+  }
+  
+  tags = local.security_tags
+}
+
+# IAM policies for security
+data "aws_iam_policy_document" "security_policy" {
+  statement {
+    sid    = "DenyInsecureConnections"
+    effect = "Deny"
+    
+    actions = ["*"]
+    
+    resources = ["*"]
+    
+    condition {
+      test     = "Bool"
+      variable = "aws:SecureTransport"
+      values   = ["false"]
+    }
+  }
+  
+  statement {
+    sid    = "RequireMFAForSensitiveActions"
+    effect = "Deny"
+    
+    actions = [
+      "iam:DeleteRole",
+      "iam:DeleteUser",
+      "s3:DeleteBucket",
+      "rds:DeleteDBInstance"
+    ]
+    
+    resources = ["*"]
+    
+    condition {
+      test     = "Bool"
+      variable = "aws:MultiFactorAuthPresent"
+      values   = ["false"]
+    }
+  }
+}
+
+# GuardDuty for threat detection
+resource "aws_guardduty_detector" "security_monitoring" {
+  enable = true
+  
+  datasources {
+    s3_logs {
+      enable = true
+    }
+    kubernetes {
+      audit_logs {
+        enable = true
+      }
+    }
+    malware_protection {
+      scan_ec2_instance_with_findings {
+        ebs_volumes {
+          enable = true
+        }
+      }
+    }
+  }
+  
+  tags = local.security_tags
+}
+
+locals {
+  security_tags = {
+    Environment   = var.environment
+    SecurityLevel = "High"
+    Compliance    = join(",", var.compliance_frameworks)
+    ManagedBy     = "terraform"
+    Owner         = "security-team"
+  }
+}
+```
+
+### 2. Security Automation and Monitoring
+```python
+# security/automation/security_monitor.py
+import boto3
+import json
+import logging
+from datetime import datetime, timedelta
+from typing import Dict, List, Any
+import requests
+
+class SecurityMonitor:
+    def __init__(self, region_name='us-east-1'):
+        self.region = region_name
+        self.session = boto3.Session(region_name=region_name)
+        
+        # AWS clients
+        self.cloudtrail = self.session.client('cloudtrail')
+        self.guardduty = self.session.client('guardduty')
+        self.security_hub = self.session.client('securityhub')
+        self.config = self.session.client('config')
+        self.sns = self.session.client('sns')
+        
+        # Configuration
+        self.alert_topic_arn = None
+        self.slack_webhook = None
+        
+        self.setup_logging()
+    
+    def setup_logging(self):
+        logging.basicConfig(
+            level=logging.INFO,
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+        self.logger = logging.getLogger(__name__)
+    
+    def monitor_security_events(self):
+        """Main monitoring function to check all security services"""
+        
+        security_report = {
+            'timestamp': datetime.utcnow().isoformat(),
+            'guardduty_findings': self.check_guardduty_findings(),
+            'security_hub_findings': self.check_security_hub_findings(),
+            'config_compliance': self.check_config_compliance(),
+            'cloudtrail_anomalies': self.check_cloudtrail_anomalies(),
+            'iam_analysis': self.analyze_iam_permissions(),
+            'recommendations': []
+        }
+        
+        # Generate recommendations
+        security_report['recommendations'] = self.generate_security_recommendations(security_report)
+        
+        # Send alerts for critical findings
+        self.process_security_alerts(security_report)
+        
+        return security_report
+    
+    def check_guardduty_findings(self) -> List[Dict[str, Any]]:
+        """Check GuardDuty for security threats"""
+        
+        try:
+            # Get GuardDuty detector
+            detectors = self.guardduty.list_detectors()
+            if not detectors['DetectorIds']:
+                return []
+            
+            detector_id = detectors['DetectorIds'][0]
+            
+            # Get findings from last 24 hours
+            response = self.guardduty.list_findings(
+                DetectorId=detector_id,
+                FindingCriteria={
+                    'Criterion': {
+                        'updatedAt': {
+                            'Gte': int((datetime.utcnow() - timedelta(hours=24)).timestamp() * 1000)
+                        }
+                    }
+                }
+            )
+            
+            findings = []
+            if response['FindingIds']:
+                finding_details = self.guardduty.get_findings(
+                    DetectorId=detector_id,
+                    FindingIds=response['FindingIds']
+                )
+                
+                for finding in finding_details['Findings']:
+                    findings.append({
+                        'id': finding['Id'],
+                        'type': finding['Type'],
+                        'severity': finding['Severity'],
+                        'title': finding['Title'],
+                        'description': finding['Description'],
+                        'created_at': finding['CreatedAt'],
+                        'updated_at': finding['UpdatedAt'],
+                        'account_id': finding['AccountId'],
+                        'region': finding['Region']
+                    })
+            
+            self.logger.info(f"Found {len(findings)} GuardDuty findings")
+            return findings
+            
+        except Exception as e:
+            self.logger.error(f"Error checking GuardDuty findings: {str(e)}")
+            return []
+    
+    def check_security_hub_findings(self) -> List[Dict[str, Any]]:
+        """Check Security Hub for compliance findings"""
+        
+        try:
+            response = self.security_hub.get_findings(
+                Filters={
+                    'UpdatedAt': [
+                        {
+                            'Start': (datetime.utcnow() - timedelta(hours=24)).isoformat(),
+                            'End': datetime.utcnow().isoformat()
+                        }
+                    ],
+                    'RecordState': [
+                        {
+                            'Value': 'ACTIVE',
+                            'Comparison': 'EQUALS'
+                        }
+                    ]
+                },
+                MaxResults=100
+            )
+            
+            findings = []
+            for finding in response['Findings']:
+                findings.append({
+                    'id': finding['Id'],
+                    'title': finding['Title'],
+                    'description': finding['Description'],
+                    'severity': finding['Severity']['Label'],
+                    'compliance_status': finding.get('Compliance', {}).get('Status'),
+                    'generator_id': finding['GeneratorId'],
+                    'created_at': finding['CreatedAt'],
+                    'updated_at': finding['UpdatedAt']
+                })
+            
+            self.logger.info(f"Found {len(findings)} Security Hub findings")
+            return findings
+            
+        except Exception as e:
+            self.logger.error(f"Error checking Security Hub findings: {str(e)}")
+            return []
+    
+    def check_config_compliance(self) -> Dict[str, Any]:
+        """Check AWS Config compliance status"""
+        
+        try:
+            # Get compliance summary
+            compliance_summary = self.config.get_compliance_summary_by_config_rule()
+            
+            # Get detailed compliance for each rule
+            config_rules = self.config.describe_config_rules()
+            compliance_details = []
+            
+            for rule in config_rules['ConfigRules']:
+                try:
+                    compliance = self.config.get_compliance_details_by_config_rule(
+                        ConfigRuleName=rule['ConfigRuleName']
+                    )
+                    
+                    compliance_details.append({
+                        'rule_name': rule['ConfigRuleName'],
+                        'compliance_type': compliance['EvaluationResults'][0]['ComplianceType'] if compliance['EvaluationResults'] else 'NOT_APPLICABLE',
+                        'description': rule.get('Description', ''),
+                        'source': rule['Source']['Owner']
+                    })
+                    
+                except Exception as rule_error:
+                    self.logger.warning(f"Error checking rule {rule['ConfigRuleName']}: {str(rule_error)}")
+            
+            return {
+                'summary': compliance_summary['ComplianceSummary'],
+                'rules': compliance_details,
+                'non_compliant_count': sum(1 for rule in compliance_details if rule['compliance_type'] == 'NON_COMPLIANT')
+            }
+            
+        except Exception as e:
+            self.logger.error(f"Error checking Config compliance: {str(e)}")
+            return {}
+    
+    def check_cloudtrail_anomalies(self) -> List[Dict[str, Any]]:
+        """Analyze CloudTrail for suspicious activities"""
+        
+        try:
+            # Look for suspicious activities in last 24 hours
+            end_time = datetime.utcnow()
+            start_time = end_time - timedelta(hours=24)
+            
+            # Check for suspicious API calls
+            suspicious_events = []
+            
+            # High-risk API calls to monitor
+            high_risk_apis = [
+                'DeleteRole', 'DeleteUser', 'CreateUser', 'AttachUserPolicy',
+                'PutBucketPolicy', 'DeleteBucket', 'ModifyDBInstance',
+                'AuthorizeSecurityGroupIngress', 'RevokeSecurityGroupEgress'
+            ]
+            
+            for api in high_risk_apis:
+                events = self.cloudtrail.lookup_events(
+                    LookupAttributes=[
+                        {
+                            'AttributeKey': 'EventName',
+                            'AttributeValue': api
+                        }
+                    ],
+                    StartTime=start_time,
+                    EndTime=end_time
+                )
+                
+                for event in events['Events']:
+                    suspicious_events.append({
+                        'event_name': event['EventName'],
+                        'event_time': event['EventTime'].isoformat(),
+                        'username': event.get('Username', 'Unknown'),
+                        'source_ip': event.get('SourceIPAddress', 'Unknown'),
+                        'user_agent': event.get('UserAgent', 'Unknown'),
+                        'aws_region': event.get('AwsRegion', 'Unknown')
+                    })
+            
+            # Analyze for anomalies
+            anomalies = self.detect_login_anomalies(suspicious_events)
+            
+            self.logger.info(f"Found {len(suspicious_events)} high-risk API calls")
+            return suspicious_events + anomalies
+            
+        except Exception as e:
+            self.logger.error(f"Error checking CloudTrail anomalies: {str(e)}")
+            return []
+    
+    def analyze_iam_permissions(self) -> Dict[str, Any]:
+        """Analyze IAM permissions for security risks"""
+        
+        try:
+            iam = self.session.client('iam')
+            
+            # Get all users and their permissions
+            users = iam.list_users()
+            permission_analysis = {
+                'overprivileged_users': [],
+                'users_without_mfa': [],
+                'unused_access_keys': [],
+                'policy_violations': []
+            }
+            
+            for user in users['Users']:
+                username = user['UserName']
+                
+                # Check MFA status
+                mfa_devices = iam.list_mfa_devices(UserName=username)
+                if not mfa_devices['MFADevices']:
+                    permission_analysis['users_without_mfa'].append(username)
+                
+                # Check access keys
+                access_keys = iam.list_access_keys(UserName=username)
+                for key in access_keys['AccessKeyMetadata']:
+                    last_used = iam.get_access_key_last_used(AccessKeyId=key['AccessKeyId'])
+                    if 'LastUsedDate' in last_used['AccessKeyLastUsed']:
+                        days_since_use = (datetime.utcnow().replace(tzinfo=None) - 
+                                        last_used['AccessKeyLastUsed']['LastUsedDate'].replace(tzinfo=None)).days
+                        if days_since_use > 90:  # Unused for 90+ days
+                            permission_analysis['unused_access_keys'].append({
+                                'username': username,
+                                'access_key_id': key['AccessKeyId'],
+                                'days_unused': days_since_use
+                            })
+                
+                # Check for overprivileged users (users with admin policies)
+                attached_policies = iam.list_attached_user_policies(UserName=username)
+                for policy in attached_policies['AttachedPolicies']:
+                    if 'Admin' in policy['PolicyName'] or policy['PolicyArn'].endswith('AdministratorAccess'):
+                        permission_analysis['overprivileged_users'].append({
+                            'username': username,
+                            'policy_name': policy['PolicyName'],
+                            'policy_arn': policy['PolicyArn']
+                        })
+            
+            return permission_analysis
+            
+        except Exception as e:
+            self.logger.error(f"Error analyzing IAM permissions: {str(e)}")
+            return {}
+    
+    def generate_security_recommendations(self, security_report: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Generate security recommendations based on findings"""
+        
+        recommendations = []
+        
+        # GuardDuty recommendations
+        if security_report['guardduty_findings']:
+            high_severity_findings = [f for f in security_report['guardduty_findings'] if f['severity'] >= 7.0]
+            if high_severity_findings:
+                recommendations.append({
+                    'category': 'threat_detection',
+                    'priority': 'high',
+                    'issue': f"{len(high_severity_findings)} high-severity threats detected",
+                    'recommendation': "Investigate and respond to high-severity GuardDuty findings immediately"
+                })
+        
+        # Compliance recommendations
+        if security_report['config_compliance']:
+            non_compliant = security_report['config_compliance'].get('non_compliant_count', 0)
+            if non_compliant > 0:
+                recommendations.append({
+                    'category': 'compliance',
+                    'priority': 'medium',
+                    'issue': f"{non_compliant} non-compliant resources",
+                    'recommendation': "Review and remediate non-compliant resources"
+                })
+        
+        # IAM recommendations
+        iam_analysis = security_report['iam_analysis']
+        if iam_analysis.get('users_without_mfa'):
+            recommendations.append({
+                'category': 'access_control',
+                'priority': 'high',
+                'issue': f"{len(iam_analysis['users_without_mfa'])} users without MFA",
+                'recommendation': "Enable MFA for all user accounts"
+            })
+        
+        if iam_analysis.get('unused_access_keys'):
+            recommendations.append({
+                'category': 'access_control',
+                'priority': 'medium',
+                'issue': f"{len(iam_analysis['unused_access_keys'])} unused access keys",
+                'recommendation': "Rotate or remove unused access keys"
+            })
+        
+        return recommendations
+    
+    def send_security_alert(self, message: str, severity: str = 'medium'):
+        """Send security alert via SNS and Slack"""
+        
+        alert_data = {
+            'timestamp': datetime.utcnow().isoformat(),
+            'severity': severity,
+            'message': message,
+            'source': 'SecurityMonitor'
+        }
+        
+        # Send to SNS
+        if self.alert_topic_arn:
+            try:
+                self.sns.publish(
+                    TopicArn=self.alert_topic_arn,
+                    Message=json.dumps(alert_data),
+                    Subject=f"Security Alert - {severity.upper()}"
+                )
+            except Exception as e:
+                self.logger.error(f"Error sending SNS alert: {str(e)}")
+        
+        # Send to Slack
+        if self.slack_webhook:
+            try:
+                slack_message = {
+                    'text': f"🚨 Security Alert - {severity.upper()}",
+                    'attachments': [
+                        {
+                            'color': 'danger' if severity == 'high' else 'warning',
+                            'fields': [
+                                {
+                                    'title': 'Message',
+                                    'value': message,
+                                    'short': False
+                                },
+                                {
+                                    'title': 'Timestamp',
+                                    'value': alert_data['timestamp'],
+                                    'short': True
+                                },
+                                {
+                                    'title': 'Severity',
+                                    'value': severity.upper(),
+                                    'short': True
+                                }
+                            ]
+                        }
+                    ]
+                }
+                
+                requests.post(self.slack_webhook, json=slack_message)
+                
+            except Exception as e:
+                self.logger.error(f"Error sending Slack alert: {str(e)}")
+
+# Usage
+if __name__ == "__main__":
+    monitor = SecurityMonitor()
+    report = monitor.monitor_security_events()
+    print(json.dumps(report, indent=2, default=str))
+```
+
+### 3. Compliance Automation Framework
+```python
+# security/compliance/compliance_framework.py
+from abc import ABC, abstractmethod
+from typing import Dict, List, Any
+import json
+
+class ComplianceFramework(ABC):
+    """Base class for compliance frameworks"""
+    
+    @abstractmethod
+    def get_controls(self) -> List[Dict[str, Any]]:
+        """Return list of compliance controls"""
+        pass
+    
+    @abstractmethod
+    def assess_compliance(self, resource_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Assess compliance for given resources"""
+        pass
+
+class SOC2Compliance(ComplianceFramework):
+    """SOC 2 Type II compliance framework"""
+    
+    def get_controls(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                'control_id': 'CC6.1',
+                'title': 'Logical and Physical Access Controls',
+                'description': 'The entity implements logical and physical access controls to protect against threats from sources outside its system boundaries.',
+                'aws_services': ['IAM', 'VPC', 'Security Groups', 'NACLs'],
+                'checks': ['mfa_enabled', 'least_privilege', 'network_segmentation']
+            },
+            {
+                'control_id': 'CC6.2',
+                'title': 'Transmission and Disposal of Data',
+                'description': 'Prior to issuing system credentials and granting system access, the entity registers and authorizes new internal and external users.',
+                'aws_services': ['KMS', 'S3', 'EBS', 'RDS'],
+                'checks': ['encryption_in_transit', 'encryption_at_rest', 'secure_disposal']
+            },
+            {
+                'control_id': 'CC7.2',
+                'title': 'System Monitoring',
+                'description': 'The entity monitors system components and the operation of controls on a ongoing basis.',
+                'aws_services': ['CloudWatch', 'CloudTrail', 'Config', 'GuardDuty'],
+                'checks': ['logging_enabled', 'monitoring_active', 'alert_configuration']
+            }
+        ]
+    
+    def assess_compliance(self, resource_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Assess SOC 2 compliance"""
+        
+        compliance_results = {
+            'framework': 'SOC2',
+            'assessment_date': datetime.utcnow().isoformat(),
+            'overall_score': 0,
+            'control_results': [],
+            'recommendations': []
+        }
+        
+        total_controls = 0
+        passed_controls = 0
+        
+        for control in self.get_controls():
+            control_result = self._assess_control(control, resource_data)
+            compliance_results['control_results'].append(control_result)
+            
+            total_controls += 1
+            if control_result['status'] == 'PASS':
+                passed_controls += 1
+        
+        compliance_results['overall_score'] = (passed_controls / total_controls) * 100
+        
+        return compliance_results
+    
+    def _assess_control(self, control: Dict[str, Any], resource_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Assess individual control compliance"""
+        
+        control_result = {
+            'control_id': control['control_id'],
+            'title': control['title'],
+            'status': 'PASS',
+            'findings': [],
+            'evidence': []
+        }
+        
+        # Implement specific checks based on control
+        if control['control_id'] == 'CC6.1':
+            # Check IAM and access controls
+            if not self._check_mfa_enabled(resource_data):
+                control_result['status'] = 'FAIL'
+                control_result['findings'].append('MFA not enabled for all users')
+            
+            if not self._check_least_privilege(resource_data):
+                control_result['status'] = 'FAIL'
+                control_result['findings'].append('Overprivileged users detected')
+        
+        elif control['control_id'] == 'CC6.2':
+            # Check encryption controls
+            if not self._check_encryption_at_rest(resource_data):
+                control_result['status'] = 'FAIL'
+                control_result['findings'].append('Encryption at rest not enabled')
+            
+            if not self._check_encryption_in_transit(resource_data):
+                control_result['status'] = 'FAIL'
+                control_result['findings'].append('Encryption in transit not enforced')
+        
+        elif control['control_id'] == 'CC7.2':
+            # Check monitoring controls
+            if not self._check_logging_enabled(resource_data):
+                control_result['status'] = 'FAIL'
+                control_result['findings'].append('Comprehensive logging not enabled')
+        
+        return control_result
+
+class PCIDSSCompliance(ComplianceFramework):
+    """PCI DSS compliance framework"""
+    
+    def get_controls(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                'requirement': '1',
+                'title': 'Install and maintain a firewall configuration',
+                'description': 'Firewalls are devices that control computer traffic allowed between an entity's networks',
+                'checks': ['firewall_configured', 'default_deny', 'documented_rules']
+            },
+            {
+                'requirement': '2',
+                'title': 'Do not use vendor-supplied defaults for system passwords',
+                'description': 'Malicious individuals often use vendor default passwords to compromise systems',
+                'checks': ['default_passwords_changed', 'strong_authentication', 'secure_configuration']
+            },
+            {
+                'requirement': '3',
+                'title': 'Protect stored cardholder data',
+                'description': 'Protection methods include encryption, truncation, masking, and hashing',
+                'checks': ['data_encryption', 'secure_storage', 'access_controls']
+            }
+        ]
+    
+    def assess_compliance(self, resource_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Assess PCI DSS compliance"""
+        # Implementation similar to SOC2 but with PCI DSS specific controls
+        pass
+
+# Compliance automation script
+def run_compliance_assessment():
+    """Run automated compliance assessment"""
+    
+    # Initialize compliance frameworks
+    soc2 = SOC2Compliance()
+    pci_dss = PCIDSSCompliance()
+    
+    # Gather resource data (this would integrate with AWS APIs)
+    resource_data = gather_aws_resource_data()
+    
+    # Run assessments
+    soc2_results = soc2.assess_compliance(resource_data)
+    pci_results = pci_dss.assess_compliance(resource_data)
+    
+    # Generate comprehensive report
+    compliance_report = {
+        'assessment_date': datetime.utcnow().isoformat(),
+        'frameworks': {
+            'SOC2': soc2_results,
+            'PCI_DSS': pci_results
+        },
+        'summary': generate_compliance_summary([soc2_results, pci_results])
+    }
+    
+    return compliance_report
+```
+
+## Security Best Practices
+
+### Incident Response Automation
+```bash
+#!/bin/bash
+# security/incident-response/incident_response.sh
+
+# Automated incident response script
+set -euo pipefail
+
+INCIDENT_ID="${1:-$(date +%Y%m%d-%H%M%S)}"
+SEVERITY="${2:-medium}"
+INCIDENT_TYPE="${3:-security}"
+
+echo "🚨 Incident Response Activated"
+echo "Incident ID: $INCIDENT_ID"
+echo "Severity: $SEVERITY"
+echo "Type: $INCIDENT_TYPE"
+
+# Create incident directory
+INCIDENT_DIR="./incidents/$INCIDENT_ID"
+mkdir -p "$INCIDENT_DIR"
+
+# Collect system state
+echo "📋 Collecting system state..."
+kubectl get pods --all-namespaces > "$INCIDENT_DIR/kubernetes_pods.txt"
+kubectl get events --all-namespaces > "$INCIDENT_DIR/kubernetes_events.txt"
+aws ec2 describe-instances > "$INCIDENT_DIR/ec2_instances.json"
+aws logs describe-log-groups > "$INCIDENT_DIR/log_groups.json"
+
+# Collect security logs
+echo "🔍 Collecting security logs..."
+aws logs filter-log-events \
+    --log-group-name "/aws/lambda/security-function" \
+    --start-time "$(date -d '1 hour ago' +%s)000" \
+    > "$INCIDENT_DIR/security_logs.json"
+
+# Network analysis
+echo "🌐 Analyzing network traffic..."
+aws ec2 describe-flow-logs > "$INCIDENT_DIR/vpc_flow_logs.json"
+
+# Generate incident report
+echo "📊 Generating incident report..."
+cat > "$INCIDENT_DIR/incident_report.md" << EOF
+# Security Incident Report
+
+**Incident ID:** $INCIDENT_ID
+**Date:** $(date)
+**Severity:** $SEVERITY
+**Type:** $INCIDENT_TYPE
+
+## Timeline
+- $(date): Incident detected and response initiated
+
+## Initial Assessment
+- System state collected
+- Security logs analyzed
+- Network traffic reviewed
+
+## Actions Taken
+1. Incident response activated
+2. System state preserved
+3. Logs collected for analysis
+
+## Next Steps
+- [ ] Detailed log analysis
+- [ ] Root cause identification
+- [ ] Containment measures
+- [ ] Recovery planning
+- [ ] Post-incident review
+
+EOF
+
+echo "✅ Incident response data collected in $INCIDENT_DIR"
+```
+
+Your security implementations should prioritize:
+1. **Zero Trust Architecture** - Never trust, always verify approach
+2. **Automation First** - Automated security controls and response
+3. **Continuous Monitoring** - Real-time security monitoring and alerting
+4. **Compliance by Design** - Built-in compliance controls and reporting
+5. **Incident Preparedness** - Automated incident response and recovery
+
+Always include comprehensive logging, monitoring, and audit trails for all security controls and activities.

.agent/agents/typescript-pro.md

@@ -0,0 +1,38 @@
+---
+name: typescript-pro
+description: Write idiomatic TypeScript with advanced type system features, strict typing, and modern patterns. Masters generic constraints, conditional types, and type inference. Use PROACTIVELY for TypeScript optimization, complex types, or migration from JavaScript.
+tools: Read, Write, Edit, Bash
+model: sonnet
+---
+
+You are a TypeScript expert specializing in advanced type system features and type-safe application development.
+
+## Focus Areas
+
+- Advanced type system (conditional types, mapped types, template literal types)
+- Generic constraints and type inference optimization
+- Utility types and custom type helpers
+- Strict TypeScript configuration and migration strategies
+- Declaration files and module augmentation
+- Performance optimization and compilation speed
+
+## Approach
+
+1. Leverage TypeScript's type system for compile-time safety
+2. Use strict configuration for maximum type safety
+3. Prefer type inference over explicit typing when clear
+4. Design APIs with generic constraints for flexibility
+5. Optimize build performance with project references
+6. Create reusable type utilities for common patterns
+
+## Output
+
+- Strongly typed TypeScript with comprehensive type coverage
+- Advanced generic types with proper constraints
+- Custom utility types and type helpers
+- Strict tsconfig.json configuration
+- Type-safe API designs with proper error handling
+- Performance-optimized build configuration
+- Migration strategies from JavaScript to TypeScript
+
+Follow TypeScript best practices and maintain type safety without sacrificing developer experience.

.agent/skills/code-reviewer/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: code-reviewer
+description: Comprehensive code review skill for TypeScript, JavaScript, Python, Swift, Kotlin, Go. Includes automated code analysis, best practice checking, security scanning, and review checklist generation. Use when reviewing pull requests, providing code feedback, identifying issues, or ensuring code quality standards.
+---
+
+# Code Reviewer
+
+Complete toolkit for code reviewer with modern tools and best practices.
+
+## Quick Start
+
+### Main Capabilities
+
+This skill provides three core capabilities through automated scripts:
+
+```bash
+# Script 1: Pr Analyzer
+python scripts/pr_analyzer.py [options]
+
+# Script 2: Code Quality Checker
+python scripts/code_quality_checker.py [options]
+
+# Script 3: Review Report Generator
+python scripts/review_report_generator.py [options]
+```
+
+## Core Capabilities
+
+### 1. Pr Analyzer
+
+Automated tool for pr analyzer tasks.
+
+**Features:**
+- Automated scaffolding
+- Best practices built-in
+- Configurable templates
+- Quality checks
+
+**Usage:**
+```bash
+python scripts/pr_analyzer.py <project-path> [options]
+```
+
+### 2. Code Quality Checker
+
+Comprehensive analysis and optimization tool.
+
+**Features:**
+- Deep analysis
+- Performance metrics
+- Recommendations
+- Automated fixes
+
+**Usage:**
+```bash
+python scripts/code_quality_checker.py <target-path> [--verbose]
+```
+
+### 3. Review Report Generator
+
+Advanced tooling for specialized tasks.
+
+**Features:**
+- Expert-level automation
+- Custom configurations
+- Integration ready
+- Production-grade output
+
+**Usage:**
+```bash
+python scripts/review_report_generator.py [arguments] [options]
+```
+
+## Reference Documentation
+
+### Code Review Checklist
+
+Comprehensive guide available in `references/code_review_checklist.md`:
+
+- Detailed patterns and practices
+- Code examples
+- Best practices
+- Anti-patterns to avoid
+- Real-world scenarios
+
+### Coding Standards
+
+Complete workflow documentation in `references/coding_standards.md`:
+
+- Step-by-step processes
+- Optimization strategies
+- Tool integrations
+- Performance tuning
+- Troubleshooting guide
+
+### Common Antipatterns
+
+Technical reference guide in `references/common_antipatterns.md`:
+
+- Technology stack details
+- Configuration examples
+- Integration patterns
+- Security considerations
+- Scalability guidelines
+
+## Tech Stack
+
+**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin
+**Frontend:** React, Next.js, React Native, Flutter
+**Backend:** Node.js, Express, GraphQL, REST APIs
+**Database:** PostgreSQL, Prisma, NeonDB, Supabase
+**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI
+**Cloud:** AWS, GCP, Azure
+
+## Development Workflow
+
+### 1. Setup and Configuration
+
+```bash
+# Install dependencies
+npm install
+# or
+pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+```
+
+### 2. Run Quality Checks
+
+```bash
+# Use the analyzer script
+python scripts/code_quality_checker.py .
+
+# Review recommendations
+# Apply fixes
+```
+
+### 3. Implement Best Practices
+
+Follow the patterns and practices documented in:
+- `references/code_review_checklist.md`
+- `references/coding_standards.md`
+- `references/common_antipatterns.md`
+
+## Best Practices Summary
+
+### Code Quality
+- Follow established patterns
+- Write comprehensive tests
+- Document decisions
+- Review regularly
+
+### Performance
+- Measure before optimizing
+- Use appropriate caching
+- Optimize critical paths
+- Monitor in production
+
+### Security
+- Validate all inputs
+- Use parameterized queries
+- Implement proper authentication
+- Keep dependencies updated
+
+### Maintainability
+- Write clear code
+- Use consistent naming
+- Add helpful comments
+- Keep it simple
+
+## Common Commands
+
+```bash
+# Development
+npm run dev
+npm run build
+npm run test
+npm run lint
+
+# Analysis
+python scripts/code_quality_checker.py .
+python scripts/review_report_generator.py --analyze
+
+# Deployment
+docker build -t app:latest .
+docker-compose up -d
+kubectl apply -f k8s/
+```
+
+## Troubleshooting
+
+### Common Issues
+
+Check the comprehensive troubleshooting section in `references/common_antipatterns.md`.
+
+### Getting Help
+
+- Review reference documentation
+- Check script output messages
+- Consult tech stack documentation
+- Review error logs
+
+## Resources
+
+- Pattern Reference: `references/code_review_checklist.md`
+- Workflow Guide: `references/coding_standards.md`
+- Technical Guide: `references/common_antipatterns.md`
+- Tool Scripts: `scripts/` directory

.agent/skills/code-reviewer/references/code_review_checklist.md

@@ -0,0 +1,103 @@
+# Code Review Checklist
+
+## Overview
+
+This reference guide provides comprehensive information for code reviewer.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for code reviewer.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/code-reviewer/references/coding_standards.md

@@ -0,0 +1,103 @@
+# Coding Standards
+
+## Overview
+
+This reference guide provides comprehensive information for code reviewer.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for code reviewer.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/code-reviewer/references/common_antipatterns.md

@@ -0,0 +1,103 @@
+# Common Antipatterns
+
+## Overview
+
+This reference guide provides comprehensive information for code reviewer.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for code reviewer.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/code-reviewer/scripts/code_quality_checker.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Code Quality Checker
+Automated tool for code reviewer tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class CodeQualityChecker:
+    """Main class for code quality checker functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Code Quality Checker"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = CodeQualityChecker(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/code-reviewer/scripts/pr_analyzer.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Pr Analyzer
+Automated tool for code reviewer tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class PrAnalyzer:
+    """Main class for pr analyzer functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Pr Analyzer"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = PrAnalyzer(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/code-reviewer/scripts/review_report_generator.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Review Report Generator
+Automated tool for code reviewer tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class ReviewReportGenerator:
+    """Main class for review report generator functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Review Report Generator"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = ReviewReportGenerator(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

.agent/skills/senior-backend/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: senior-backend
+description: Comprehensive backend development skill for building scalable backend systems using NodeJS, Express, Go, Python, Postgres, GraphQL, REST APIs. Includes API scaffolding, database optimization, security implementation, and performance tuning. Use when designing APIs, optimizing database queries, implementing business logic, handling authentication/authorization, or reviewing backend code.
+---
+
+# Senior Backend
+
+Complete toolkit for senior backend with modern tools and best practices.
+
+## Quick Start
+
+### Main Capabilities
+
+This skill provides three core capabilities through automated scripts:
+
+```bash
+# Script 1: Api Scaffolder
+python scripts/api_scaffolder.py [options]
+
+# Script 2: Database Migration Tool
+python scripts/database_migration_tool.py [options]
+
+# Script 3: Api Load Tester
+python scripts/api_load_tester.py [options]
+```
+
+## Core Capabilities
+
+### 1. Api Scaffolder
+
+Automated tool for api scaffolder tasks.
+
+**Features:**
+- Automated scaffolding
+- Best practices built-in
+- Configurable templates
+- Quality checks
+
+**Usage:**
+```bash
+python scripts/api_scaffolder.py <project-path> [options]
+```
+
+### 2. Database Migration Tool
+
+Comprehensive analysis and optimization tool.
+
+**Features:**
+- Deep analysis
+- Performance metrics
+- Recommendations
+- Automated fixes
+
+**Usage:**
+```bash
+python scripts/database_migration_tool.py <target-path> [--verbose]
+```
+
+### 3. Api Load Tester
+
+Advanced tooling for specialized tasks.
+
+**Features:**
+- Expert-level automation
+- Custom configurations
+- Integration ready
+- Production-grade output
+
+**Usage:**
+```bash
+python scripts/api_load_tester.py [arguments] [options]
+```
+
+## Reference Documentation
+
+### Api Design Patterns
+
+Comprehensive guide available in `references/api_design_patterns.md`:
+
+- Detailed patterns and practices
+- Code examples
+- Best practices
+- Anti-patterns to avoid
+- Real-world scenarios
+
+### Database Optimization Guide
+
+Complete workflow documentation in `references/database_optimization_guide.md`:
+
+- Step-by-step processes
+- Optimization strategies
+- Tool integrations
+- Performance tuning
+- Troubleshooting guide
+
+### Backend Security Practices
+
+Technical reference guide in `references/backend_security_practices.md`:
+
+- Technology stack details
+- Configuration examples
+- Integration patterns
+- Security considerations
+- Scalability guidelines
+
+## Tech Stack
+
+**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin
+**Frontend:** React, Next.js, React Native, Flutter
+**Backend:** Node.js, Express, GraphQL, REST APIs
+**Database:** PostgreSQL, Prisma, NeonDB, Supabase
+**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI
+**Cloud:** AWS, GCP, Azure
+
+## Development Workflow
+
+### 1. Setup and Configuration
+
+```bash
+# Install dependencies
+npm install
+# or
+pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+```
+
+### 2. Run Quality Checks
+
+```bash
+# Use the analyzer script
+python scripts/database_migration_tool.py .
+
+# Review recommendations
+# Apply fixes
+```
+
+### 3. Implement Best Practices
+
+Follow the patterns and practices documented in:
+- `references/api_design_patterns.md`
+- `references/database_optimization_guide.md`
+- `references/backend_security_practices.md`
+
+## Best Practices Summary
+
+### Code Quality
+- Follow established patterns
+- Write comprehensive tests
+- Document decisions
+- Review regularly
+
+### Performance
+- Measure before optimizing
+- Use appropriate caching
+- Optimize critical paths
+- Monitor in production
+
+### Security
+- Validate all inputs
+- Use parameterized queries
+- Implement proper authentication
+- Keep dependencies updated
+
+### Maintainability
+- Write clear code
+- Use consistent naming
+- Add helpful comments
+- Keep it simple
+
+## Common Commands
+
+```bash
+# Development
+npm run dev
+npm run build
+npm run test
+npm run lint
+
+# Analysis
+python scripts/database_migration_tool.py .
+python scripts/api_load_tester.py --analyze
+
+# Deployment
+docker build -t app:latest .
+docker-compose up -d
+kubectl apply -f k8s/
+```
+
+## Troubleshooting
+
+### Common Issues
+
+Check the comprehensive troubleshooting section in `references/backend_security_practices.md`.
+
+### Getting Help
+
+- Review reference documentation
+- Check script output messages
+- Consult tech stack documentation
+- Review error logs
+
+## Resources
+
+- Pattern Reference: `references/api_design_patterns.md`
+- Workflow Guide: `references/database_optimization_guide.md`
+- Technical Guide: `references/backend_security_practices.md`
+- Tool Scripts: `scripts/` directory

.agent/skills/senior-backend/references/api_design_patterns.md

@@ -0,0 +1,103 @@
+# Api Design Patterns
+
+## Overview
+
+This reference guide provides comprehensive information for senior backend.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior backend.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/senior-backend/references/backend_security_practices.md

@@ -0,0 +1,103 @@
+# Backend Security Practices
+
+## Overview
+
+This reference guide provides comprehensive information for senior backend.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior backend.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/senior-backend/references/database_optimization_guide.md

@@ -0,0 +1,103 @@
+# Database Optimization Guide
+
+## Overview
+
+This reference guide provides comprehensive information for senior backend.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior backend.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/senior-backend/scripts/api_load_tester.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Api Load Tester
+Automated tool for senior backend tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class ApiLoadTester:
+    """Main class for api load tester functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Api Load Tester"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = ApiLoadTester(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-backend/scripts/api_scaffolder.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Api Scaffolder
+Automated tool for senior backend tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class ApiScaffolder:
+    """Main class for api scaffolder functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Api Scaffolder"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = ApiScaffolder(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-backend/scripts/database_migration_tool.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Database Migration Tool
+Automated tool for senior backend tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class DatabaseMigrationTool:
+    """Main class for database migration tool functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Database Migration Tool"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = DatabaseMigrationTool(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-fullstack/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: senior-fullstack
+description: Comprehensive fullstack development skill for building complete web applications with React, Next.js, Node.js, GraphQL, and PostgreSQL. Includes project scaffolding, code quality analysis, architecture patterns, and complete tech stack guidance. Use when building new projects, analyzing code quality, implementing design patterns, or setting up development workflows.
+---
+
+# Senior Fullstack
+
+Complete toolkit for senior fullstack with modern tools and best practices.
+
+## Quick Start
+
+### Main Capabilities
+
+This skill provides three core capabilities through automated scripts:
+
+```bash
+# Script 1: Fullstack Scaffolder
+python scripts/fullstack_scaffolder.py [options]
+
+# Script 2: Project Scaffolder
+python scripts/project_scaffolder.py [options]
+
+# Script 3: Code Quality Analyzer
+python scripts/code_quality_analyzer.py [options]
+```
+
+## Core Capabilities
+
+### 1. Fullstack Scaffolder
+
+Automated tool for fullstack scaffolder tasks.
+
+**Features:**
+- Automated scaffolding
+- Best practices built-in
+- Configurable templates
+- Quality checks
+
+**Usage:**
+```bash
+python scripts/fullstack_scaffolder.py <project-path> [options]
+```
+
+### 2. Project Scaffolder
+
+Comprehensive analysis and optimization tool.
+
+**Features:**
+- Deep analysis
+- Performance metrics
+- Recommendations
+- Automated fixes
+
+**Usage:**
+```bash
+python scripts/project_scaffolder.py <target-path> [--verbose]
+```
+
+### 3. Code Quality Analyzer
+
+Advanced tooling for specialized tasks.
+
+**Features:**
+- Expert-level automation
+- Custom configurations
+- Integration ready
+- Production-grade output
+
+**Usage:**
+```bash
+python scripts/code_quality_analyzer.py [arguments] [options]
+```
+
+## Reference Documentation
+
+### Tech Stack Guide
+
+Comprehensive guide available in `references/tech_stack_guide.md`:
+
+- Detailed patterns and practices
+- Code examples
+- Best practices
+- Anti-patterns to avoid
+- Real-world scenarios
+
+### Architecture Patterns
+
+Complete workflow documentation in `references/architecture_patterns.md`:
+
+- Step-by-step processes
+- Optimization strategies
+- Tool integrations
+- Performance tuning
+- Troubleshooting guide
+
+### Development Workflows
+
+Technical reference guide in `references/development_workflows.md`:
+
+- Technology stack details
+- Configuration examples
+- Integration patterns
+- Security considerations
+- Scalability guidelines
+
+## Tech Stack
+
+**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin
+**Frontend:** React, Next.js, React Native, Flutter
+**Backend:** Node.js, Express, GraphQL, REST APIs
+**Database:** PostgreSQL, Prisma, NeonDB, Supabase
+**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI
+**Cloud:** AWS, GCP, Azure
+
+## Development Workflow
+
+### 1. Setup and Configuration
+
+```bash
+# Install dependencies
+npm install
+# or
+pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+```
+
+### 2. Run Quality Checks
+
+```bash
+# Use the analyzer script
+python scripts/project_scaffolder.py .
+
+# Review recommendations
+# Apply fixes
+```
+
+### 3. Implement Best Practices
+
+Follow the patterns and practices documented in:
+- `references/tech_stack_guide.md`
+- `references/architecture_patterns.md`
+- `references/development_workflows.md`
+
+## Best Practices Summary
+
+### Code Quality
+- Follow established patterns
+- Write comprehensive tests
+- Document decisions
+- Review regularly
+
+### Performance
+- Measure before optimizing
+- Use appropriate caching
+- Optimize critical paths
+- Monitor in production
+
+### Security
+- Validate all inputs
+- Use parameterized queries
+- Implement proper authentication
+- Keep dependencies updated
+
+### Maintainability
+- Write clear code
+- Use consistent naming
+- Add helpful comments
+- Keep it simple
+
+## Common Commands
+
+```bash
+# Development
+npm run dev
+npm run build
+npm run test
+npm run lint
+
+# Analysis
+python scripts/project_scaffolder.py .
+python scripts/code_quality_analyzer.py --analyze
+
+# Deployment
+docker build -t app:latest .
+docker-compose up -d
+kubectl apply -f k8s/
+```
+
+## Troubleshooting
+
+### Common Issues
+
+Check the comprehensive troubleshooting section in `references/development_workflows.md`.
+
+### Getting Help
+
+- Review reference documentation
+- Check script output messages
+- Consult tech stack documentation
+- Review error logs
+
+## Resources
+
+- Pattern Reference: `references/tech_stack_guide.md`
+- Workflow Guide: `references/architecture_patterns.md`
+- Technical Guide: `references/development_workflows.md`
+- Tool Scripts: `scripts/` directory

.agent/skills/senior-fullstack/references/architecture_patterns.md

@@ -0,0 +1,103 @@
+# Architecture Patterns
+
+## Overview
+
+This reference guide provides comprehensive information for senior fullstack.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior fullstack.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/senior-fullstack/references/development_workflows.md

@@ -0,0 +1,103 @@
+# Development Workflows
+
+## Overview
+
+This reference guide provides comprehensive information for senior fullstack.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior fullstack.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/senior-fullstack/references/tech_stack_guide.md

@@ -0,0 +1,103 @@
+# Tech Stack Guide
+
+## Overview
+
+This reference guide provides comprehensive information for senior fullstack.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior fullstack.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

.agent/skills/senior-fullstack/scripts/code_quality_analyzer.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Code Quality Analyzer
+Automated tool for senior fullstack tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class CodeQualityAnalyzer:
+    """Main class for code quality analyzer functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Code Quality Analyzer"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = CodeQualityAnalyzer(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-fullstack/scripts/fullstack_scaffolder.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Fullstack Scaffolder
+Automated tool for senior fullstack tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class FullstackScaffolder:
+    """Main class for fullstack scaffolder functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Fullstack Scaffolder"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = FullstackScaffolder(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-fullstack/scripts/project_scaffolder.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Project Scaffolder
+Automated tool for senior fullstack tasks
+"""
+
+import os
+import sys
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class ProjectScaffolder:
+    """Main class for project scaffolder functionality"""
+    
+    def __init__(self, target_path: str, verbose: bool = False):
+        self.target_path = Path(target_path)
+        self.verbose = verbose
+        self.results = {}
+    
+    def run(self) -> Dict:
+        """Execute the main functionality"""
+        print(f"🚀 Running {self.__class__.__name__}...")
+        print(f"📁 Target: {self.target_path}")
+        
+        try:
+            self.validate_target()
+            self.analyze()
+            self.generate_report()
+            
+            print("✅ Completed successfully!")
+            return self.results
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            sys.exit(1)
+    
+    def validate_target(self):
+        """Validate the target path exists and is accessible"""
+        if not self.target_path.exists():
+            raise ValueError(f"Target path does not exist: {self.target_path}")
+        
+        if self.verbose:
+            print(f"✓ Target validated: {self.target_path}")
+    
+    def analyze(self):
+        """Perform the main analysis or operation"""
+        if self.verbose:
+            print("📊 Analyzing...")
+        
+        # Main logic here
+        self.results['status'] = 'success'
+        self.results['target'] = str(self.target_path)
+        self.results['findings'] = []
+        
+        # Add analysis results
+        if self.verbose:
+            print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings")
+    
+    def generate_report(self):
+        """Generate and display the report"""
+        print("\n" + "="*50)
+        print("REPORT")
+        print("="*50)
+        print(f"Target: {self.results.get('target')}")
+        print(f"Status: {self.results.get('status')}")
+        print(f"Findings: {len(self.results.get('findings', []))}")
+        print("="*50 + "\n")
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Project Scaffolder"
+    )
+    parser.add_argument(
+        'target',
+        help='Target path to analyze or process'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path'
+    )
+    
+    args = parser.parse_args()
+    
+    tool = ProjectScaffolder(
+        args.target,
+        verbose=args.verbose
+    )
+    
+    results = tool.run()
+    
+    if args.json:
+        output = json.dumps(results, indent=2)
+        if args.output:
+            with open(args.output, 'w') as f:
+                f.write(output)
+            print(f"Results written to {args.output}")
+        else:
+            print(output)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-ml-engineer/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: senior-ml-engineer
+description: World-class ML engineering skill for productionizing ML models, MLOps, and building scalable ML systems. Expertise in PyTorch, TensorFlow, model deployment, feature stores, model monitoring, and ML infrastructure. Includes LLM integration, fine-tuning, RAG systems, and agentic AI. Use when deploying ML models, building ML platforms, implementing MLOps, or integrating LLMs into production systems.
+---
+
+# Senior ML/AI Engineer
+
+World-class senior ml/ai engineer skill for production-grade AI/ML/Data systems.
+
+## Quick Start
+
+### Main Capabilities
+
+```bash
+# Core Tool 1
+python scripts/model_deployment_pipeline.py --input data/ --output results/
+
+# Core Tool 2  
+python scripts/rag_system_builder.py --target project/ --analyze
+
+# Core Tool 3
+python scripts/ml_monitoring_suite.py --config config.yaml --deploy
+```
+
+## Core Expertise
+
+This skill covers world-class capabilities in:
+
+- Advanced production patterns and architectures
+- Scalable system design and implementation
+- Performance optimization at scale
+- MLOps and DataOps best practices
+- Real-time processing and inference
+- Distributed computing frameworks
+- Model deployment and monitoring
+- Security and compliance
+- Cost optimization
+- Team leadership and mentoring
+
+## Tech Stack
+
+**Languages:** Python, SQL, R, Scala, Go
+**ML Frameworks:** PyTorch, TensorFlow, Scikit-learn, XGBoost
+**Data Tools:** Spark, Airflow, dbt, Kafka, Databricks
+**LLM Frameworks:** LangChain, LlamaIndex, DSPy
+**Deployment:** Docker, Kubernetes, AWS/GCP/Azure
+**Monitoring:** MLflow, Weights & Biases, Prometheus
+**Databases:** PostgreSQL, BigQuery, Snowflake, Pinecone
+
+## Reference Documentation
+
+### 1. Mlops Production Patterns
+
+Comprehensive guide available in `references/mlops_production_patterns.md` covering:
+
+- Advanced patterns and best practices
+- Production implementation strategies
+- Performance optimization techniques
+- Scalability considerations
+- Security and compliance
+- Real-world case studies
+
+### 2. Llm Integration Guide
+
+Complete workflow documentation in `references/llm_integration_guide.md` including:
+
+- Step-by-step processes
+- Architecture design patterns
+- Tool integration guides
+- Performance tuning strategies
+- Troubleshooting procedures
+
+### 3. Rag System Architecture
+
+Technical reference guide in `references/rag_system_architecture.md` with:
+
+- System design principles
+- Implementation examples
+- Configuration best practices
+- Deployment strategies
+- Monitoring and observability
+
+## Production Patterns
+
+### Pattern 1: Scalable Data Processing
+
+Enterprise-scale data processing with distributed computing:
+
+- Horizontal scaling architecture
+- Fault-tolerant design
+- Real-time and batch processing
+- Data quality validation
+- Performance monitoring
+
+### Pattern 2: ML Model Deployment
+
+Production ML system with high availability:
+
+- Model serving with low latency
+- A/B testing infrastructure
+- Feature store integration
+- Model monitoring and drift detection
+- Automated retraining pipelines
+
+### Pattern 3: Real-Time Inference
+
+High-throughput inference system:
+
+- Batching and caching strategies
+- Load balancing
+- Auto-scaling
+- Latency optimization
+- Cost optimization
+
+## Best Practices
+
+### Development
+
+- Test-driven development
+- Code reviews and pair programming
+- Documentation as code
+- Version control everything
+- Continuous integration
+
+### Production
+
+- Monitor everything critical
+- Automate deployments
+- Feature flags for releases
+- Canary deployments
+- Comprehensive logging
+
+### Team Leadership
+
+- Mentor junior engineers
+- Drive technical decisions
+- Establish coding standards
+- Foster learning culture
+- Cross-functional collaboration
+
+## Performance Targets
+
+**Latency:**
+- P50: < 50ms
+- P95: < 100ms
+- P99: < 200ms
+
+**Throughput:**
+- Requests/second: > 1000
+- Concurrent users: > 10,000
+
+**Availability:**
+- Uptime: 99.9%
+- Error rate: < 0.1%
+
+## Security & Compliance
+
+- Authentication & authorization
+- Data encryption (at rest & in transit)
+- PII handling and anonymization
+- GDPR/CCPA compliance
+- Regular security audits
+- Vulnerability management
+
+## Common Commands
+
+```bash
+# Development
+python -m pytest tests/ -v --cov
+python -m black src/
+python -m pylint src/
+
+# Training
+python scripts/train.py --config prod.yaml
+python scripts/evaluate.py --model best.pth
+
+# Deployment
+docker build -t service:v1 .
+kubectl apply -f k8s/
+helm upgrade service ./charts/
+
+# Monitoring
+kubectl logs -f deployment/service
+python scripts/health_check.py
+```
+
+## Resources
+
+- Advanced Patterns: `references/mlops_production_patterns.md`
+- Implementation Guide: `references/llm_integration_guide.md`
+- Technical Reference: `references/rag_system_architecture.md`
+- Automation Scripts: `scripts/` directory
+
+## Senior-Level Responsibilities
+
+As a world-class senior professional:
+
+1. **Technical Leadership**
+   - Drive architectural decisions
+   - Mentor team members
+   - Establish best practices
+   - Ensure code quality
+
+2. **Strategic Thinking**
+   - Align with business goals
+   - Evaluate trade-offs
+   - Plan for scale
+   - Manage technical debt
+
+3. **Collaboration**
+   - Work across teams
+   - Communicate effectively
+   - Build consensus
+   - Share knowledge
+
+4. **Innovation**
+   - Stay current with research
+   - Experiment with new approaches
+   - Contribute to community
+   - Drive continuous improvement
+
+5. **Production Excellence**
+   - Ensure high availability
+   - Monitor proactively
+   - Optimize performance
+   - Respond to incidents

.agent/skills/senior-ml-engineer/references/llm_integration_guide.md

@@ -0,0 +1,80 @@
+# Llm Integration Guide
+
+## Overview
+
+World-class llm integration guide for senior ml/ai engineer.
+
+## Core Principles
+
+### Production-First Design
+
+Always design with production in mind:
+- Scalability: Handle 10x current load
+- Reliability: 99.9% uptime target
+- Maintainability: Clear, documented code
+- Observability: Monitor everything
+
+### Performance by Design
+
+Optimize from the start:
+- Efficient algorithms
+- Resource awareness
+- Strategic caching
+- Batch processing
+
+### Security & Privacy
+
+Build security in:
+- Input validation
+- Data encryption
+- Access control
+- Audit logging
+
+## Advanced Patterns
+
+### Pattern 1: Distributed Processing
+
+Enterprise-scale data processing with fault tolerance.
+
+### Pattern 2: Real-Time Systems
+
+Low-latency, high-throughput systems.
+
+### Pattern 3: ML at Scale
+
+Production ML with monitoring and automation.
+
+## Best Practices
+
+### Code Quality
+- Comprehensive testing
+- Clear documentation
+- Code reviews
+- Type hints
+
+### Performance
+- Profile before optimizing
+- Monitor continuously
+- Cache strategically
+- Batch operations
+
+### Reliability
+- Design for failure
+- Implement retries
+- Use circuit breakers
+- Monitor health
+
+## Tools & Technologies
+
+Essential tools for this domain:
+- Development frameworks
+- Testing libraries
+- Deployment platforms
+- Monitoring solutions
+
+## Further Reading
+
+- Research papers
+- Industry blogs
+- Conference talks
+- Open source projects

.agent/skills/senior-ml-engineer/references/mlops_production_patterns.md

@@ -0,0 +1,80 @@
+# Mlops Production Patterns
+
+## Overview
+
+World-class mlops production patterns for senior ml/ai engineer.
+
+## Core Principles
+
+### Production-First Design
+
+Always design with production in mind:
+- Scalability: Handle 10x current load
+- Reliability: 99.9% uptime target
+- Maintainability: Clear, documented code
+- Observability: Monitor everything
+
+### Performance by Design
+
+Optimize from the start:
+- Efficient algorithms
+- Resource awareness
+- Strategic caching
+- Batch processing
+
+### Security & Privacy
+
+Build security in:
+- Input validation
+- Data encryption
+- Access control
+- Audit logging
+
+## Advanced Patterns
+
+### Pattern 1: Distributed Processing
+
+Enterprise-scale data processing with fault tolerance.
+
+### Pattern 2: Real-Time Systems
+
+Low-latency, high-throughput systems.
+
+### Pattern 3: ML at Scale
+
+Production ML with monitoring and automation.
+
+## Best Practices
+
+### Code Quality
+- Comprehensive testing
+- Clear documentation
+- Code reviews
+- Type hints
+
+### Performance
+- Profile before optimizing
+- Monitor continuously
+- Cache strategically
+- Batch operations
+
+### Reliability
+- Design for failure
+- Implement retries
+- Use circuit breakers
+- Monitor health
+
+## Tools & Technologies
+
+Essential tools for this domain:
+- Development frameworks
+- Testing libraries
+- Deployment platforms
+- Monitoring solutions
+
+## Further Reading
+
+- Research papers
+- Industry blogs
+- Conference talks
+- Open source projects

.agent/skills/senior-ml-engineer/references/rag_system_architecture.md

@@ -0,0 +1,80 @@
+# Rag System Architecture
+
+## Overview
+
+World-class rag system architecture for senior ml/ai engineer.
+
+## Core Principles
+
+### Production-First Design
+
+Always design with production in mind:
+- Scalability: Handle 10x current load
+- Reliability: 99.9% uptime target
+- Maintainability: Clear, documented code
+- Observability: Monitor everything
+
+### Performance by Design
+
+Optimize from the start:
+- Efficient algorithms
+- Resource awareness
+- Strategic caching
+- Batch processing
+
+### Security & Privacy
+
+Build security in:
+- Input validation
+- Data encryption
+- Access control
+- Audit logging
+
+## Advanced Patterns
+
+### Pattern 1: Distributed Processing
+
+Enterprise-scale data processing with fault tolerance.
+
+### Pattern 2: Real-Time Systems
+
+Low-latency, high-throughput systems.
+
+### Pattern 3: ML at Scale
+
+Production ML with monitoring and automation.
+
+## Best Practices
+
+### Code Quality
+- Comprehensive testing
+- Clear documentation
+- Code reviews
+- Type hints
+
+### Performance
+- Profile before optimizing
+- Monitor continuously
+- Cache strategically
+- Batch operations
+
+### Reliability
+- Design for failure
+- Implement retries
+- Use circuit breakers
+- Monitor health
+
+## Tools & Technologies
+
+Essential tools for this domain:
+- Development frameworks
+- Testing libraries
+- Deployment platforms
+- Monitoring solutions
+
+## Further Reading
+
+- Research papers
+- Industry blogs
+- Conference talks
+- Open source projects

.agent/skills/senior-ml-engineer/scripts/ml_monitoring_suite.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Ml Monitoring Suite
+Production-grade tool for senior ml/ai engineer
+"""
+
+import os
+import sys
+import json
+import logging
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+class MlMonitoringSuite:
+    """Production-grade ml monitoring suite"""
+    
+    def __init__(self, config: Dict):
+        self.config = config
+        self.results = {
+            'status': 'initialized',
+            'start_time': datetime.now().isoformat(),
+            'processed_items': 0
+        }
+        logger.info(f"Initialized {self.__class__.__name__}")
+    
+    def validate_config(self) -> bool:
+        """Validate configuration"""
+        logger.info("Validating configuration...")
+        # Add validation logic
+        logger.info("Configuration validated")
+        return True
+    
+    def process(self) -> Dict:
+        """Main processing logic"""
+        logger.info("Starting processing...")
+        
+        try:
+            self.validate_config()
+            
+            # Main processing
+            result = self._execute()
+            
+            self.results['status'] = 'completed'
+            self.results['end_time'] = datetime.now().isoformat()
+            
+            logger.info("Processing completed successfully")
+            return self.results
+            
+        except Exception as e:
+            self.results['status'] = 'failed'
+            self.results['error'] = str(e)
+            logger.error(f"Processing failed: {e}")
+            raise
+    
+    def _execute(self) -> Dict:
+        """Execute main logic"""
+        # Implementation here
+        return {'success': True}
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Ml Monitoring Suite"
+    )
+    parser.add_argument('--input', '-i', required=True, help='Input path')
+    parser.add_argument('--output', '-o', required=True, help='Output path')
+    parser.add_argument('--config', '-c', help='Configuration file')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+    
+    args = parser.parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    try:
+        config = {
+            'input': args.input,
+            'output': args.output
+        }
+        
+        processor = MlMonitoringSuite(config)
+        results = processor.process()
+        
+        print(json.dumps(results, indent=2))
+        sys.exit(0)
+        
+    except Exception as e:
+        logger.error(f"Fatal error: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-ml-engineer/scripts/model_deployment_pipeline.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Model Deployment Pipeline
+Production-grade tool for senior ml/ai engineer
+"""
+
+import os
+import sys
+import json
+import logging
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+class ModelDeploymentPipeline:
+    """Production-grade model deployment pipeline"""
+    
+    def __init__(self, config: Dict):
+        self.config = config
+        self.results = {
+            'status': 'initialized',
+            'start_time': datetime.now().isoformat(),
+            'processed_items': 0
+        }
+        logger.info(f"Initialized {self.__class__.__name__}")
+    
+    def validate_config(self) -> bool:
+        """Validate configuration"""
+        logger.info("Validating configuration...")
+        # Add validation logic
+        logger.info("Configuration validated")
+        return True
+    
+    def process(self) -> Dict:
+        """Main processing logic"""
+        logger.info("Starting processing...")
+        
+        try:
+            self.validate_config()
+            
+            # Main processing
+            result = self._execute()
+            
+            self.results['status'] = 'completed'
+            self.results['end_time'] = datetime.now().isoformat()
+            
+            logger.info("Processing completed successfully")
+            return self.results
+            
+        except Exception as e:
+            self.results['status'] = 'failed'
+            self.results['error'] = str(e)
+            logger.error(f"Processing failed: {e}")
+            raise
+    
+    def _execute(self) -> Dict:
+        """Execute main logic"""
+        # Implementation here
+        return {'success': True}
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Model Deployment Pipeline"
+    )
+    parser.add_argument('--input', '-i', required=True, help='Input path')
+    parser.add_argument('--output', '-o', required=True, help='Output path')
+    parser.add_argument('--config', '-c', help='Configuration file')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+    
+    args = parser.parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    try:
+        config = {
+            'input': args.input,
+            'output': args.output
+        }
+        
+        processor = ModelDeploymentPipeline(config)
+        results = processor.process()
+        
+        print(json.dumps(results, indent=2))
+        sys.exit(0)
+        
+    except Exception as e:
+        logger.error(f"Fatal error: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-ml-engineer/scripts/rag_system_builder.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Rag System Builder
+Production-grade tool for senior ml/ai engineer
+"""
+
+import os
+import sys
+import json
+import logging
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+class RagSystemBuilder:
+    """Production-grade rag system builder"""
+    
+    def __init__(self, config: Dict):
+        self.config = config
+        self.results = {
+            'status': 'initialized',
+            'start_time': datetime.now().isoformat(),
+            'processed_items': 0
+        }
+        logger.info(f"Initialized {self.__class__.__name__}")
+    
+    def validate_config(self) -> bool:
+        """Validate configuration"""
+        logger.info("Validating configuration...")
+        # Add validation logic
+        logger.info("Configuration validated")
+        return True
+    
+    def process(self) -> Dict:
+        """Main processing logic"""
+        logger.info("Starting processing...")
+        
+        try:
+            self.validate_config()
+            
+            # Main processing
+            result = self._execute()
+            
+            self.results['status'] = 'completed'
+            self.results['end_time'] = datetime.now().isoformat()
+            
+            logger.info("Processing completed successfully")
+            return self.results
+            
+        except Exception as e:
+            self.results['status'] = 'failed'
+            self.results['error'] = str(e)
+            logger.error(f"Processing failed: {e}")
+            raise
+    
+    def _execute(self) -> Dict:
+        """Execute main logic"""
+        # Implementation here
+        return {'success': True}
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Rag System Builder"
+    )
+    parser.add_argument('--input', '-i', required=True, help='Input path')
+    parser.add_argument('--output', '-o', required=True, help='Output path')
+    parser.add_argument('--config', '-c', help='Configuration file')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+    
+    args = parser.parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    try:
+        config = {
+            'input': args.input,
+            'output': args.output
+        }
+        
+        processor = RagSystemBuilder(config)
+        results = processor.process()
+        
+        print(json.dumps(results, indent=2))
+        sys.exit(0)
+        
+    except Exception as e:
+        logger.error(f"Fatal error: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-prompt-engineer/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: senior-prompt-engineer
+description: World-class prompt engineering skill for LLM optimization, prompt patterns, structured outputs, and AI product development. Expertise in Claude, GPT-4, prompt design patterns, few-shot learning, chain-of-thought, and AI evaluation. Includes RAG optimization, agent design, and LLM system architecture. Use when building AI products, optimizing LLM performance, designing agentic systems, or implementing advanced prompting techniques.
+---
+
+# Senior Prompt Engineer
+
+World-class senior prompt engineer skill for production-grade AI/ML/Data systems.
+
+## Quick Start
+
+### Main Capabilities
+
+```bash
+# Core Tool 1
+python scripts/prompt_optimizer.py --input data/ --output results/
+
+# Core Tool 2  
+python scripts/rag_evaluator.py --target project/ --analyze
+
+# Core Tool 3
+python scripts/agent_orchestrator.py --config config.yaml --deploy
+```
+
+## Core Expertise
+
+This skill covers world-class capabilities in:
+
+- Advanced production patterns and architectures
+- Scalable system design and implementation
+- Performance optimization at scale
+- MLOps and DataOps best practices
+- Real-time processing and inference
+- Distributed computing frameworks
+- Model deployment and monitoring
+- Security and compliance
+- Cost optimization
+- Team leadership and mentoring
+
+## Tech Stack
+
+**Languages:** Python, SQL, R, Scala, Go
+**ML Frameworks:** PyTorch, TensorFlow, Scikit-learn, XGBoost
+**Data Tools:** Spark, Airflow, dbt, Kafka, Databricks
+**LLM Frameworks:** LangChain, LlamaIndex, DSPy
+**Deployment:** Docker, Kubernetes, AWS/GCP/Azure
+**Monitoring:** MLflow, Weights & Biases, Prometheus
+**Databases:** PostgreSQL, BigQuery, Snowflake, Pinecone
+
+## Reference Documentation
+
+### 1. Prompt Engineering Patterns
+
+Comprehensive guide available in `references/prompt_engineering_patterns.md` covering:
+
+- Advanced patterns and best practices
+- Production implementation strategies
+- Performance optimization techniques
+- Scalability considerations
+- Security and compliance
+- Real-world case studies
+
+### 2. Llm Evaluation Frameworks
+
+Complete workflow documentation in `references/llm_evaluation_frameworks.md` including:
+
+- Step-by-step processes
+- Architecture design patterns
+- Tool integration guides
+- Performance tuning strategies
+- Troubleshooting procedures
+
+### 3. Agentic System Design
+
+Technical reference guide in `references/agentic_system_design.md` with:
+
+- System design principles
+- Implementation examples
+- Configuration best practices
+- Deployment strategies
+- Monitoring and observability
+
+## Production Patterns
+
+### Pattern 1: Scalable Data Processing
+
+Enterprise-scale data processing with distributed computing:
+
+- Horizontal scaling architecture
+- Fault-tolerant design
+- Real-time and batch processing
+- Data quality validation
+- Performance monitoring
+
+### Pattern 2: ML Model Deployment
+
+Production ML system with high availability:
+
+- Model serving with low latency
+- A/B testing infrastructure
+- Feature store integration
+- Model monitoring and drift detection
+- Automated retraining pipelines
+
+### Pattern 3: Real-Time Inference
+
+High-throughput inference system:
+
+- Batching and caching strategies
+- Load balancing
+- Auto-scaling
+- Latency optimization
+- Cost optimization
+
+## Best Practices
+
+### Development
+
+- Test-driven development
+- Code reviews and pair programming
+- Documentation as code
+- Version control everything
+- Continuous integration
+
+### Production
+
+- Monitor everything critical
+- Automate deployments
+- Feature flags for releases
+- Canary deployments
+- Comprehensive logging
+
+### Team Leadership
+
+- Mentor junior engineers
+- Drive technical decisions
+- Establish coding standards
+- Foster learning culture
+- Cross-functional collaboration
+
+## Performance Targets
+
+**Latency:**
+- P50: < 50ms
+- P95: < 100ms
+- P99: < 200ms
+
+**Throughput:**
+- Requests/second: > 1000
+- Concurrent users: > 10,000
+
+**Availability:**
+- Uptime: 99.9%
+- Error rate: < 0.1%
+
+## Security & Compliance
+
+- Authentication & authorization
+- Data encryption (at rest & in transit)
+- PII handling and anonymization
+- GDPR/CCPA compliance
+- Regular security audits
+- Vulnerability management
+
+## Common Commands
+
+```bash
+# Development
+python -m pytest tests/ -v --cov
+python -m black src/
+python -m pylint src/
+
+# Training
+python scripts/train.py --config prod.yaml
+python scripts/evaluate.py --model best.pth
+
+# Deployment
+docker build -t service:v1 .
+kubectl apply -f k8s/
+helm upgrade service ./charts/
+
+# Monitoring
+kubectl logs -f deployment/service
+python scripts/health_check.py
+```
+
+## Resources
+
+- Advanced Patterns: `references/prompt_engineering_patterns.md`
+- Implementation Guide: `references/llm_evaluation_frameworks.md`
+- Technical Reference: `references/agentic_system_design.md`
+- Automation Scripts: `scripts/` directory
+
+## Senior-Level Responsibilities
+
+As a world-class senior professional:
+
+1. **Technical Leadership**
+   - Drive architectural decisions
+   - Mentor team members
+   - Establish best practices
+   - Ensure code quality
+
+2. **Strategic Thinking**
+   - Align with business goals
+   - Evaluate trade-offs
+   - Plan for scale
+   - Manage technical debt
+
+3. **Collaboration**
+   - Work across teams
+   - Communicate effectively
+   - Build consensus
+   - Share knowledge
+
+4. **Innovation**
+   - Stay current with research
+   - Experiment with new approaches
+   - Contribute to community
+   - Drive continuous improvement
+
+5. **Production Excellence**
+   - Ensure high availability
+   - Monitor proactively
+   - Optimize performance
+   - Respond to incidents

.agent/skills/senior-prompt-engineer/references/agentic_system_design.md

@@ -0,0 +1,80 @@
+# Agentic System Design
+
+## Overview
+
+World-class agentic system design for senior prompt engineer.
+
+## Core Principles
+
+### Production-First Design
+
+Always design with production in mind:
+- Scalability: Handle 10x current load
+- Reliability: 99.9% uptime target
+- Maintainability: Clear, documented code
+- Observability: Monitor everything
+
+### Performance by Design
+
+Optimize from the start:
+- Efficient algorithms
+- Resource awareness
+- Strategic caching
+- Batch processing
+
+### Security & Privacy
+
+Build security in:
+- Input validation
+- Data encryption
+- Access control
+- Audit logging
+
+## Advanced Patterns
+
+### Pattern 1: Distributed Processing
+
+Enterprise-scale data processing with fault tolerance.
+
+### Pattern 2: Real-Time Systems
+
+Low-latency, high-throughput systems.
+
+### Pattern 3: ML at Scale
+
+Production ML with monitoring and automation.
+
+## Best Practices
+
+### Code Quality
+- Comprehensive testing
+- Clear documentation
+- Code reviews
+- Type hints
+
+### Performance
+- Profile before optimizing
+- Monitor continuously
+- Cache strategically
+- Batch operations
+
+### Reliability
+- Design for failure
+- Implement retries
+- Use circuit breakers
+- Monitor health
+
+## Tools & Technologies
+
+Essential tools for this domain:
+- Development frameworks
+- Testing libraries
+- Deployment platforms
+- Monitoring solutions
+
+## Further Reading
+
+- Research papers
+- Industry blogs
+- Conference talks
+- Open source projects

.agent/skills/senior-prompt-engineer/references/llm_evaluation_frameworks.md

@@ -0,0 +1,80 @@
+# Llm Evaluation Frameworks
+
+## Overview
+
+World-class llm evaluation frameworks for senior prompt engineer.
+
+## Core Principles
+
+### Production-First Design
+
+Always design with production in mind:
+- Scalability: Handle 10x current load
+- Reliability: 99.9% uptime target
+- Maintainability: Clear, documented code
+- Observability: Monitor everything
+
+### Performance by Design
+
+Optimize from the start:
+- Efficient algorithms
+- Resource awareness
+- Strategic caching
+- Batch processing
+
+### Security & Privacy
+
+Build security in:
+- Input validation
+- Data encryption
+- Access control
+- Audit logging
+
+## Advanced Patterns
+
+### Pattern 1: Distributed Processing
+
+Enterprise-scale data processing with fault tolerance.
+
+### Pattern 2: Real-Time Systems
+
+Low-latency, high-throughput systems.
+
+### Pattern 3: ML at Scale
+
+Production ML with monitoring and automation.
+
+## Best Practices
+
+### Code Quality
+- Comprehensive testing
+- Clear documentation
+- Code reviews
+- Type hints
+
+### Performance
+- Profile before optimizing
+- Monitor continuously
+- Cache strategically
+- Batch operations
+
+### Reliability
+- Design for failure
+- Implement retries
+- Use circuit breakers
+- Monitor health
+
+## Tools & Technologies
+
+Essential tools for this domain:
+- Development frameworks
+- Testing libraries
+- Deployment platforms
+- Monitoring solutions
+
+## Further Reading
+
+- Research papers
+- Industry blogs
+- Conference talks
+- Open source projects

.agent/skills/senior-prompt-engineer/references/prompt_engineering_patterns.md

@@ -0,0 +1,80 @@
+# Prompt Engineering Patterns
+
+## Overview
+
+World-class prompt engineering patterns for senior prompt engineer.
+
+## Core Principles
+
+### Production-First Design
+
+Always design with production in mind:
+- Scalability: Handle 10x current load
+- Reliability: 99.9% uptime target
+- Maintainability: Clear, documented code
+- Observability: Monitor everything
+
+### Performance by Design
+
+Optimize from the start:
+- Efficient algorithms
+- Resource awareness
+- Strategic caching
+- Batch processing
+
+### Security & Privacy
+
+Build security in:
+- Input validation
+- Data encryption
+- Access control
+- Audit logging
+
+## Advanced Patterns
+
+### Pattern 1: Distributed Processing
+
+Enterprise-scale data processing with fault tolerance.
+
+### Pattern 2: Real-Time Systems
+
+Low-latency, high-throughput systems.
+
+### Pattern 3: ML at Scale
+
+Production ML with monitoring and automation.
+
+## Best Practices
+
+### Code Quality
+- Comprehensive testing
+- Clear documentation
+- Code reviews
+- Type hints
+
+### Performance
+- Profile before optimizing
+- Monitor continuously
+- Cache strategically
+- Batch operations
+
+### Reliability
+- Design for failure
+- Implement retries
+- Use circuit breakers
+- Monitor health
+
+## Tools & Technologies
+
+Essential tools for this domain:
+- Development frameworks
+- Testing libraries
+- Deployment platforms
+- Monitoring solutions
+
+## Further Reading
+
+- Research papers
+- Industry blogs
+- Conference talks
+- Open source projects

.agent/skills/senior-prompt-engineer/scripts/agent_orchestrator.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Agent Orchestrator
+Production-grade tool for senior prompt engineer
+"""
+
+import os
+import sys
+import json
+import logging
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+class AgentOrchestrator:
+    """Production-grade agent orchestrator"""
+    
+    def __init__(self, config: Dict):
+        self.config = config
+        self.results = {
+            'status': 'initialized',
+            'start_time': datetime.now().isoformat(),
+            'processed_items': 0
+        }
+        logger.info(f"Initialized {self.__class__.__name__}")
+    
+    def validate_config(self) -> bool:
+        """Validate configuration"""
+        logger.info("Validating configuration...")
+        # Add validation logic
+        logger.info("Configuration validated")
+        return True
+    
+    def process(self) -> Dict:
+        """Main processing logic"""
+        logger.info("Starting processing...")
+        
+        try:
+            self.validate_config()
+            
+            # Main processing
+            result = self._execute()
+            
+            self.results['status'] = 'completed'
+            self.results['end_time'] = datetime.now().isoformat()
+            
+            logger.info("Processing completed successfully")
+            return self.results
+            
+        except Exception as e:
+            self.results['status'] = 'failed'
+            self.results['error'] = str(e)
+            logger.error(f"Processing failed: {e}")
+            raise
+    
+    def _execute(self) -> Dict:
+        """Execute main logic"""
+        # Implementation here
+        return {'success': True}
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Agent Orchestrator"
+    )
+    parser.add_argument('--input', '-i', required=True, help='Input path')
+    parser.add_argument('--output', '-o', required=True, help='Output path')
+    parser.add_argument('--config', '-c', help='Configuration file')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+    
+    args = parser.parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    try:
+        config = {
+            'input': args.input,
+            'output': args.output
+        }
+        
+        processor = AgentOrchestrator(config)
+        results = processor.process()
+        
+        print(json.dumps(results, indent=2))
+        sys.exit(0)
+        
+    except Exception as e:
+        logger.error(f"Fatal error: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-prompt-engineer/scripts/prompt_optimizer.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Prompt Optimizer
+Production-grade tool for senior prompt engineer
+"""
+
+import os
+import sys
+import json
+import logging
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+class PromptOptimizer:
+    """Production-grade prompt optimizer"""
+    
+    def __init__(self, config: Dict):
+        self.config = config
+        self.results = {
+            'status': 'initialized',
+            'start_time': datetime.now().isoformat(),
+            'processed_items': 0
+        }
+        logger.info(f"Initialized {self.__class__.__name__}")
+    
+    def validate_config(self) -> bool:
+        """Validate configuration"""
+        logger.info("Validating configuration...")
+        # Add validation logic
+        logger.info("Configuration validated")
+        return True
+    
+    def process(self) -> Dict:
+        """Main processing logic"""
+        logger.info("Starting processing...")
+        
+        try:
+            self.validate_config()
+            
+            # Main processing
+            result = self._execute()
+            
+            self.results['status'] = 'completed'
+            self.results['end_time'] = datetime.now().isoformat()
+            
+            logger.info("Processing completed successfully")
+            return self.results
+            
+        except Exception as e:
+            self.results['status'] = 'failed'
+            self.results['error'] = str(e)
+            logger.error(f"Processing failed: {e}")
+            raise
+    
+    def _execute(self) -> Dict:
+        """Execute main logic"""
+        # Implementation here
+        return {'success': True}
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Prompt Optimizer"
+    )
+    parser.add_argument('--input', '-i', required=True, help='Input path')
+    parser.add_argument('--output', '-o', required=True, help='Output path')
+    parser.add_argument('--config', '-c', help='Configuration file')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+    
+    args = parser.parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    try:
+        config = {
+            'input': args.input,
+            'output': args.output
+        }
+        
+        processor = PromptOptimizer(config)
+        results = processor.process()
+        
+        print(json.dumps(results, indent=2))
+        sys.exit(0)
+        
+    except Exception as e:
+        logger.error(f"Fatal error: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

.agent/skills/senior-prompt-engineer/scripts/rag_evaluator.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Rag Evaluator
+Production-grade tool for senior prompt engineer
+"""
+
+import os
+import sys
+import json
+import logging
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+class RagEvaluator:
+    """Production-grade rag evaluator"""
+    
+    def __init__(self, config: Dict):
+        self.config = config
+        self.results = {
+            'status': 'initialized',
+            'start_time': datetime.now().isoformat(),
+            'processed_items': 0
+        }
+        logger.info(f"Initialized {self.__class__.__name__}")
+    
+    def validate_config(self) -> bool:
+        """Validate configuration"""
+        logger.info("Validating configuration...")
+        # Add validation logic
+        logger.info("Configuration validated")
+        return True
+    
+    def process(self) -> Dict:
+        """Main processing logic"""
+        logger.info("Starting processing...")
+        
+        try:
+            self.validate_config()
+            
+            # Main processing
+            result = self._execute()
+            
+            self.results['status'] = 'completed'
+            self.results['end_time'] = datetime.now().isoformat()
+            
+            logger.info("Processing completed successfully")
+            return self.results
+            
+        except Exception as e:
+            self.results['status'] = 'failed'
+            self.results['error'] = str(e)
+            logger.error(f"Processing failed: {e}")
+            raise
+    
+    def _execute(self) -> Dict:
+        """Execute main logic"""
+        # Implementation here
+        return {'success': True}
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Rag Evaluator"
+    )
+    parser.add_argument('--input', '-i', required=True, help='Input path')
+    parser.add_argument('--output', '-o', required=True, help='Output path')
+    parser.add_argument('--config', '-c', help='Configuration file')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+    
+    args = parser.parse_args()
+    
+    if args.verbose:
+        logging.getLogger().setLevel(logging.DEBUG)
+    
+    try:
+        config = {
+            'input': args.input,
+            'output': args.output
+        }
+        
+        processor = RagEvaluator(config)
+        results = processor.process()
+        
+        print(json.dumps(results, indent=2))
+        sys.exit(0)
+        
+    except Exception as e:
+        logger.error(f"Fatal error: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

.dockerignore

@@ -0,0 +1,42 @@
+# Dependencies
+node_modules
+npm-debug.log
+
+# Build output
+dist
+
+# Docker
+docker-compose*.yml
+.docker
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# Documentation
+README.md
+docs
+
+# Tests
+coverage
+.nyc_output
+test
+
+# Logs
+logs
+*.log

.env.example

@@ -0,0 +1,49 @@
+# Environment
+NODE_ENV=development
+PORT=3000
+
+# Database
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/boilerplate_db?schema=public"
+
+# JWT
+JWT_SECRET=your-super-secret-jwt-key-change-in-production
+JWT_ACCESS_EXPIRATION=15m
+JWT_REFRESH_EXPIRATION=7d
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+# i18n
+DEFAULT_LANGUAGE=en
+FALLBACK_LANGUAGE=en
+
+# Optional Features (set to "true" to enable)
+ENABLE_MAIL=false
+ENABLE_S3=false
+ENABLE_WEBSOCKET=false
+ENABLE_MULTI_TENANCY=false
+
+# Mail (Optional - only needed if ENABLE_MAIL=true)
+MAIL_HOST=smtp.example.com
+MAIL_PORT=587
+MAIL_USER=
+MAIL_PASSWORD=
+MAIL_FROM=noreply@example.com
+
+# S3/MinIO (Optional - only needed if ENABLE_S3=true)
+S3_ENDPOINT=http://localhost:9000
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin
+S3_BUCKET=uploads
+S3_REGION=us-east-1
+
+# Throttle / Rate Limiting
+THROTTLE_TTL=60000
+THROTTLE_LIMIT=100
+
+# Gemini AI (Optional - only needed if ENABLE_GEMINI=true)
+ENABLE_GEMINI=false
+GOOGLE_API_KEY=your-google-api-key
+GEMINI_MODEL=gemini-2.5-flash

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma Client
+        run: npx prisma generate
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build

.gitignore

@@ -0,0 +1,38 @@
+# compiled output
+/dist
+/node_modules
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# os
+.DS_Store
+Thumbs.db
+
+# env
+.env
+.env.test
+.env.production
+.env.local
+
+# ide
+.idea
+.vscode
+*.swp
+*.swo
+
+# test coverage
+coverage/
+junit.xml
+
+# prisma
+/prisma/*.db
+/prisma/*.db-journal
+
+dist
+
+cli-tool

.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

Dockerfile

@@ -0,0 +1,49 @@
+# Build stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Generate Prisma client
+RUN npx prisma generate
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine AS production
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies only
+RUN npm ci --only=production
+
+# Copy Prisma schema and generate client
+COPY prisma ./prisma
+RUN npx prisma generate
+
+# Copy built application
+COPY --from=builder /app/dist ./dist
+
+# Copy i18n files
+COPY --from=builder /app/src/i18n ./dist/i18n
+
+# Set environment
+ENV NODE_ENV=production
+
+# Expose port
+EXPOSE 3000
+
+# Start the application
+CMD ["node", "dist/main.js"]

README.md

@@ -0,0 +1,335 @@
+# 🚀 Enterprise NestJS Boilerplate (Antigravity Edition)
+
+[![NestJS](https://img.shields.io/badge/NestJS-E0234E?style=for-the-badge&logo=nestjs&logoColor=white)](https://nestjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Prisma](https://img.shields.io/badge/Prisma-2D3748?style=for-the-badge&logo=prisma&logoColor=white)](https://www.prisma.io/)
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white)](https://www.postgresql.org/)
+[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
+
+> **FOR AI AGENTS & DEVELOPERS:** This documentation is structured to provide deep context, architectural decisions, and operational details to ensure seamless handover to any AI coding assistant (like Antigravity) or human developer.
+
+---
+
+## 🧠 Project Context & Architecture (Read Me First)
+
+This is an **opinionated, production-ready** backend boilerplate built with NestJS. It is designed to be scalable, type-safe, and fully localized.
+
+### 🏗️ Core Philosophy
+
+- **Type Safety First:** Strict TypeScript configuration. `any` is forbidden. DTOs are the source of truth.
+- **Generic Abstraction:** `BaseService` and `BaseController` handle 80% of CRUD operations, allowing developers to focus on business logic.
+- **i18nNative:** Localization is not an afterthought. It is baked into the exception filters, response interceptors, and guards.
+- **Security by Default:** JWT Auth, RBAC (Role-Based Access Control), Throttling, and Helmet are pre-configured.
+
+### 📐 Architectural Decision Records (ADR)
+
+_To understand WHY things are the way they are:_
+
+1.  **Handling i18n Assets:**
+    - **Problem:** Translation JSON files are not TypeScript code, so `tsc` ignores them during build.
+    - **Solution:** We configured `nest-cli.json` with `"assets": ["i18n/**/*"]`. This ensures `src/i18n` is copied to `dist/i18n` automatically.
+    - **Note:** When running with `node`, ensure `dist/main.js` can find these files.
+
+2.  **Global Response Wrapping:**
+    - **Mechanism:** `ResponseInterceptor` wraps all successful responses.
+    - **Feature:** It automatically translates the "Operation successful" message based on the `Accept-Language` header using `I18nService`.
+    - **Output Format:**
+      ```json
+      {
+        "success": true,
+        "status": 200,
+        "message": "İşlem başarıyla tamamlandı", // Translated
+        "data": { ... }
+      }
+      ```
+
+3.  **Centralized Error Handling:**
+    - **Mechanism:** `GlobalExceptionFilter` catches all `HttpException` and unknown `Error` types.
+    - **Feature:** It accepts error keys (e.g., `AUTH_REQUIRED`) and translates them using `i18n`. If a translation is found in `errors.json`, it is returned; otherwise, the original message is shown.
+
+4.  **UUID Generation:**
+    - **Decision:** We use Node.js native `crypto.randomUUID()` instead of the external `uuid` package to avoid CommonJS/ESM compatibility issues.
+
+---
+
+## 🚀 Quick Start for AI & Humans
+
+### 1. Prerequisites
+
+- **Node.js:** v20.19+ (LTS)
+- **Docker:** For running PostgreSQL and Redis effortlessly.
+- **Package Manager:** `npm` (Lockfile: `package-lock.json`)
+
+### 2. Environment Setup
+
+```bash
+cp .env.example .env
+# ⚠️ CRITICAL: Ensure DATABASE_URL includes the username!
+# Example: postgresql://postgres:password@localhost:5432/boilerplate_db
+```
+
+### 3. Installation & Database
+
+```bash
+# Install dependencies
+npm ci
+
+# Start Infrastructure (Postgres + Redis)
+docker-compose up -d postgres redis
+
+# Generate Prisma Client (REQUIRED after install)
+npx prisma generate
+
+# Run Migrations
+npx prisma migrate dev
+
+# Seed Database (Optional - Creates Admin & Roles)
+npx prisma db seed
+```
+
+### 4. Running the App
+
+```bash
+# Debug Mode (Watch) - Best for Development
+npm run start:dev
+
+# Production Build & Run
+npm run build
+npm run start:prod
+```
+
+---
+
+## 🛡️ Response Standardization & Type Safety Protocol
+
+This boilerplate enforces a strict **"No-Leak"** policy for API responses to ensure both Security and Developer Experience.
+
+### 1. The `unknown` Type is Forbidden
+
+- **Rule:** Controllers must NEVER return `ApiResponse<unknown>` or raw Prisma entities.
+- **Why:** Returning raw entities risks exposing sensitive fields like `password` hashes or internal metadata. It also breaks contract visibility for frontend developers.
+
+### 2. DTO Pattern & Serialization
+
+- **Tool:** We use `class-transformer` for all response serialization.
+- **Implementation:**
+  - All Response DTOs must use `@Exclude()` class-level decorator.
+  - Only fields explicitly marked with `@Expose()` are returned to the client.
+  - Controllers use `plainToInstance(UserResponseDto, data)` before returning data.
+
+**Example:**
+
+```typescript
+// ✅ Good: Secure & Typed
+@Get('me')
+async getMe(@CurrentUser() user: User): Promise<ApiResponse<UserResponseDto>> {
+  return createSuccessResponse(plainToInstance(UserResponseDto, user));
+}
+
+// ❌ Bad: Leaks password hash & Weak Types
+@Get('me')
+async getMe(@CurrentUser() user: User) {
+  return createSuccessResponse(user);
+}
+```
+
+---
+
+## ⚡ High-Performance Caching (Redis Strategy)
+
+To ensure enterprise-grade performance, we utilize **Redis** for caching frequently accessed data (e.g., Roles, Permissions).
+
+- **Library:** `@nestjs/cache-manager` with `cache-manager-redis-yet` (Supports Redis v6+ / v7).
+- **Configuration:** Global Cache Module in `AppModule`.
+- **Strategy:** Read-heavy endpoints use `@UseInterceptors(CacheInterceptor)`.
+- **Invalidation:** Write operations (Create/Update/Delete) manually invalidate relevant cache keys.
+
+**Usage:**
+
+```typescript
+// 1. Automatic Caching
+@Get('roles')
+@UseInterceptors(CacheInterceptor)
+@CacheKey('roles_list') // Unique Key
+@CacheTTL(60000)        // 60 Seconds
+async getAllRoles() { ... }
+
+// 2. Manual Invalidation (Inject CACHE_MANAGER)
+async createRole(...) {
+  // ... create role logic
+  await this.cacheManager.del('roles_list'); // Clear cache
+}
+```
+
+---
+
+## 🤖 Gemini AI Integration (Optional)
+
+This boilerplate includes an **optional** AI module powered by Google's Gemini API. It's disabled by default and can be enabled during CLI setup or manually.
+
+### Configuration
+
+Add these to your `.env` file:
+
+```env
+# Enable Gemini AI features
+ENABLE_GEMINI=true
+
+# Your Google API Key (get from https://aistudio.google.com/apikey)
+GOOGLE_API_KEY=your-api-key-here
+
+# Model to use (optional, defaults to gemini-2.5-flash)
+GEMINI_MODEL=gemini-2.5-flash
+```
+
+### Usage
+
+The `GeminiService` is globally available when enabled:
+
+```typescript
+import { GeminiService } from './modules/gemini';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly gemini: GeminiService) {}
+
+  async generateContent() {
+    // Check if Gemini is available
+    if (!this.gemini.isAvailable()) {
+      throw new Error('AI features are not enabled');
+    }
+
+    // 1. Simple Text Generation
+    const { text, usage } = await this.gemini.generateText(
+      'Write a product description for a coffee mug',
+    );
+
+    // 2. With System Prompt & Options
+    const { text } = await this.gemini.generateText('Translate: Hello World', {
+      systemPrompt: 'You are a professional Turkish translator',
+      temperature: 0.3,
+      maxTokens: 500,
+    });
+
+    // 3. Multi-turn Chat
+    const { text } = await this.gemini.chat([
+      { role: 'user', content: 'What is TypeScript?' },
+      {
+        role: 'model',
+        content: 'TypeScript is a typed superset of JavaScript...',
+      },
+      { role: 'user', content: 'Give me an example' },
+    ]);
+
+    // 4. Structured JSON Output
+    interface ProductData {
+      name: string;
+      price: number;
+      features: string[];
+    }
+
+    const { data } = await this.gemini.generateJSON<ProductData>(
+      'Generate a product entry for a wireless mouse',
+      '{ name: string, price: number, features: string[] }',
+    );
+    console.log(data.name, data.price); // Fully typed!
+  }
+}
+```
+
+### Available Methods
+
+| Method                                      | Description                                      |
+| ------------------------------------------- | ------------------------------------------------ |
+| `isAvailable()`                             | Check if Gemini is properly configured and ready |
+| `generateText(prompt, options?)`            | Generate text from a single prompt               |
+| `chat(messages, options?)`                  | Multi-turn conversation                          |
+| `generateJSON<T>(prompt, schema, options?)` | Generate and parse structured JSON               |
+
+### Options
+
+```typescript
+interface GeminiGenerateOptions {
+  model?: string; // Override default model
+  systemPrompt?: string; // System instructions
+  temperature?: number; // Creativity (0-1)
+  maxTokens?: number; // Max response length
+}
+```
+
+## 🌍 Internationalization (i18n) Guide
+
+Unique to this project is the deep integration of `nestjs-i18n`.
+
+- **Location:** `src/i18n/{lang}/`
+- **Files:**
+  - `common.json`: Generic messages (success, welcome)
+  - `errors.json`: Error codes (AUTH_REQUIRED, USER_NOT_FOUND)
+  - `validation.json`: Validation messages (IS_EMAIL)
+  - `auth.json`: Auth specific success messages (LOGIN_SUCCESS)
+
+**How to Translate a New Error:**
+
+1.  Throw an exception with a key: `throw new ConflictException('EMAIL_EXISTS');`
+2.  Add `"EMAIL_EXISTS": "Email already taken"` to `src/i18n/en/errors.json`.
+3.  Add Turkish translation to `src/i18n/tr/errors.json`.
+4.  Start server; the `GlobalExceptionFilter` handles the rest.
+
+---
+
+## 🧪 Testing & CI/CD
+
+- **GitHub Actions:** `.github/workflows/ci.yml` handles build and linting checks on push.
+- **Local Testing:**
+  ```bash
+  npm run test        # Unit tests
+  npm run test:e2e    # End-to-End tests
+  ```
+
+---
+
+## 📂 System Map (Directory Structure)
+
+```
+src/
+├── app.module.ts           # Root module (Redis, Config, i18n setup)
+├── main.ts                 # Entry point
+├── common/                 # Shared resources
+│   ├── base/               # Abstract BaseService & BaseController (CRUD)
+│   ├── types/              # Interfaces (ApiResponse, PaginatedData)
+│   ├── filters/            # Global Exception Filter
+│   └── interceptors/       # Response Interceptor
+├── config/                 # Application configuration
+├── database/               # Prisma Service
+├── i18n/                   # Localization assets
+└── modules/                # Feature modules
+    ├── admin/              # Admin capabilities (Roles, Permissions + Caching)
+    │   ├── admin.controller.ts
+    │   └── dto/            # Admin Response DTOs
+    ├── auth/               # Authentication layer
+    ├── gemini/             # 🤖 Optional AI module (Google Gemini)
+    ├── health/             # Health checks
+    └── users/              # User management
+```
+
+---
+
+## 🛠️ Troubleshooting (Known Issues)
+
+**1. `EADDRINUSE: address already in use`**
+
+- **Fix:** `lsof -ti:3000 | xargs kill -9`
+
+**2. `PrismaClientInitializationError` / Database Connection Hangs**
+
+- **Fix:** Check `.env` `DATABASE_URL`. Ensure `docker-compose up` is running.
+
+**3. Cache Manager Deprecation Warnings**
+
+- **Context:** `cache-manager-redis-yet` may show deprecation warnings regarding `Keyv`. This is expected as we wait for the ecosystem to stabilize on `cache-manager` v6/v7. The current implementation is fully functional.
+
+---
+
+## 📃 License
+
+This project is proprietary and confidential.

docker-compose.yml

@@ -0,0 +1,89 @@
+version: '3.8'
+
+services:
+  # Application
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: builder
+    container_name: boilerplate-app
+    restart: unless-stopped
+    ports:
+      - '${PORT:-3000}:3000'
+    environment:
+      - NODE_ENV=development
+      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/boilerplate_db?schema=public
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+    env_file:
+      - .env
+    volumes:
+      - .:/app
+      - /app/node_modules
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    command: npm run start:dev
+    networks:
+      - boilerplate-network
+
+  # PostgreSQL Database
+  postgres:
+    image: postgres:16-alpine
+    container_name: boilerplate-postgres
+    restart: unless-stopped
+    ports:
+      - '5432:5432'
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: boilerplate_db
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - boilerplate-network
+
+  # Redis
+  redis:
+    image: redis:7-alpine
+    container_name: boilerplate-redis
+    restart: unless-stopped
+    ports:
+      - '6379:6379'
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - boilerplate-network
+
+  # Adminer (Database UI)
+  adminer:
+    image: adminer:latest
+    container_name: boilerplate-adminer
+    restart: unless-stopped
+    ports:
+      - '8080:8080'
+    depends_on:
+      - postgres
+    networks:
+      - boilerplate-network
+
+volumes:
+  postgres_data:
+  redis_data:
+
+networks:
+  boilerplate-network:
+    driver: bridge

eslint.config.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs', 'dist/**'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      // Disable strict any rules for dynamic Prisma model access
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+
+      // Keep these as warnings
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/require-await': 'warn',
+
+      // Prettier
+      'prettier/prettier': ['error', { endOfLine: 'auto' }],
+    },
+  },
+);

nest-cli.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true,
+    "assets": ["i18n/**/*"],
+    "watchAssets": true
+  }
+}

package.json

@@ -0,0 +1,103 @@
+{
+  "name": "my-nest-app",
+  "version": "0.0.1",
+  "description": "Generated by Antigravity CLI",
+  "private": true,
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.964.0",
+    "@google/genai": "^1.35.0",
+    "@nestjs/bullmq": "^11.0.4",
+    "@nestjs/cache-manager": "^3.1.0",
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.2",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/jwt": "^11.0.2",
+    "@nestjs/passport": "^11.0.5",
+    "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/platform-socket.io": "^11.1.11",
+    "@nestjs/swagger": "^11.2.4",
+    "@nestjs/terminus": "^11.0.0",
+    "@nestjs/throttler": "^6.5.0",
+    "@prisma/client": "^5.22.0",
+    "bcrypt": "^6.0.0",
+    "bullmq": "^5.66.4",
+    "cache-manager": "^7.2.7",
+    "cache-manager-redis-yet": "^5.1.5",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.3",
+    "helmet": "^8.1.0",
+    "ioredis": "^5.9.0",
+    "nestjs-i18n": "^10.6.0",
+    "nestjs-pino": "^4.5.0",
+    "nodemailer": "^7.0.12",
+    "passport": "^0.7.0",
+    "passport-jwt": "^4.0.1",
+    "pino": "^10.1.0",
+    "pino-http": "^11.0.0",
+    "prisma": "^5.22.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@types/bcrypt": "^6.0.0",
+    "@types/express": "^5.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.7",
+    "@types/nodemailer": "^7.0.4",
+    "@types/passport-jwt": "^4.0.1",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "globals": "^16.0.0",
+    "jest": "^30.0.0",
+    "pino-pretty": "^13.1.3",
+    "prettier": "^3.4.2",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

prisma/migrations/20260107121020_init/migration.sql

@@ -0,0 +1,185 @@
+-- CreateTable
+CREATE TABLE "User" (
+    "id" TEXT NOT NULL,
+    "email" TEXT NOT NULL,
+    "password" TEXT NOT NULL,
+    "firstName" TEXT,
+    "lastName" TEXT,
+    "isActive" BOOLEAN NOT NULL DEFAULT true,
+    "tenantId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "deletedAt" TIMESTAMP(3),
+
+    CONSTRAINT "User_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Role" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT,
+    "isSystem" BOOLEAN NOT NULL DEFAULT false,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "deletedAt" TIMESTAMP(3),
+
+    CONSTRAINT "Role_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Permission" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT,
+    "resource" TEXT NOT NULL,
+    "action" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Permission_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "UserRole" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "roleId" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "UserRole_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "RolePermission" (
+    "id" TEXT NOT NULL,
+    "roleId" TEXT NOT NULL,
+    "permissionId" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "RolePermission_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "RefreshToken" (
+    "id" TEXT NOT NULL,
+    "token" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "RefreshToken_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Tenant" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "slug" TEXT NOT NULL,
+    "isActive" BOOLEAN NOT NULL DEFAULT true,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "deletedAt" TIMESTAMP(3),
+
+    CONSTRAINT "Tenant_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Translation" (
+    "id" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "locale" TEXT NOT NULL,
+    "value" TEXT NOT NULL,
+    "namespace" TEXT NOT NULL DEFAULT 'common',
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Translation_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "User_email_key" ON "User"("email");
+
+-- CreateIndex
+CREATE INDEX "User_email_idx" ON "User"("email");
+
+-- CreateIndex
+CREATE INDEX "User_tenantId_idx" ON "User"("tenantId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Role_name_key" ON "Role"("name");
+
+-- CreateIndex
+CREATE INDEX "Role_name_idx" ON "Role"("name");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Permission_name_key" ON "Permission"("name");
+
+-- CreateIndex
+CREATE INDEX "Permission_resource_idx" ON "Permission"("resource");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Permission_resource_action_key" ON "Permission"("resource", "action");
+
+-- CreateIndex
+CREATE INDEX "UserRole_userId_idx" ON "UserRole"("userId");
+
+-- CreateIndex
+CREATE INDEX "UserRole_roleId_idx" ON "UserRole"("roleId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "UserRole_userId_roleId_key" ON "UserRole"("userId", "roleId");
+
+-- CreateIndex
+CREATE INDEX "RolePermission_roleId_idx" ON "RolePermission"("roleId");
+
+-- CreateIndex
+CREATE INDEX "RolePermission_permissionId_idx" ON "RolePermission"("permissionId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "RolePermission_roleId_permissionId_key" ON "RolePermission"("roleId", "permissionId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "RefreshToken_token_key" ON "RefreshToken"("token");
+
+-- CreateIndex
+CREATE INDEX "RefreshToken_token_idx" ON "RefreshToken"("token");
+
+-- CreateIndex
+CREATE INDEX "RefreshToken_userId_idx" ON "RefreshToken"("userId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Tenant_slug_key" ON "Tenant"("slug");
+
+-- CreateIndex
+CREATE INDEX "Tenant_slug_idx" ON "Tenant"("slug");
+
+-- CreateIndex
+CREATE INDEX "Translation_key_idx" ON "Translation"("key");
+
+-- CreateIndex
+CREATE INDEX "Translation_locale_idx" ON "Translation"("locale");
+
+-- CreateIndex
+CREATE INDEX "Translation_namespace_idx" ON "Translation"("namespace");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Translation_key_locale_namespace_key" ON "Translation"("key", "locale", "namespace");
+
+-- AddForeignKey
+ALTER TABLE "User" ADD CONSTRAINT "User_tenantId_fkey" FOREIGN KEY ("tenantId") REFERENCES "Tenant"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "UserRole" ADD CONSTRAINT "UserRole_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "UserRole" ADD CONSTRAINT "UserRole_roleId_fkey" FOREIGN KEY ("roleId") REFERENCES "Role"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "RolePermission" ADD CONSTRAINT "RolePermission_roleId_fkey" FOREIGN KEY ("roleId") REFERENCES "Role"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "RolePermission" ADD CONSTRAINT "RolePermission_permissionId_fkey" FOREIGN KEY ("permissionId") REFERENCES "Permission"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "RefreshToken" ADD CONSTRAINT "RefreshToken_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/migration_lock.toml

@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (i.e. Git)
+provider = "postgresql"

prisma/schema.prisma

@@ -0,0 +1,162 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// ============================================
+// Core Models
+// ============================================
+
+model User {
+  id            String    @id @default(uuid())
+  email         String    @unique
+  password      String
+  firstName     String?
+  lastName      String?
+  isActive      Boolean   @default(true)
+  
+  // Relations
+  roles         UserRole[]
+  refreshTokens RefreshToken[]
+  
+  // Multi-tenancy (optional)
+  tenantId      String?
+  tenant        Tenant?   @relation(fields: [tenantId], references: [id])
+  
+  // Timestamps & Soft Delete
+  createdAt     DateTime  @default(now())
+  updatedAt     DateTime  @updatedAt
+  deletedAt     DateTime?
+
+  @@index([email])
+  @@index([tenantId])
+}
+
+model Role {
+  id          String       @id @default(uuid())
+  name        String       @unique
+  description String?
+  isSystem    Boolean      @default(false)
+  
+  // Relations
+  users       UserRole[]
+  permissions RolePermission[]
+  
+  // Timestamps & Soft Delete
+  createdAt   DateTime     @default(now())
+  updatedAt   DateTime     @updatedAt
+  deletedAt   DateTime?
+
+  @@index([name])
+}
+
+model Permission {
+  id          String           @id @default(uuid())
+  name        String           @unique
+  description String?
+  resource    String           // e.g., "users", "posts"
+  action      String           // e.g., "create", "read", "update", "delete"
+  
+  // Relations
+  roles       RolePermission[]
+  
+  // Timestamps
+  createdAt   DateTime         @default(now())
+  updatedAt   DateTime         @updatedAt
+
+  @@unique([resource, action])
+  @@index([resource])
+}
+
+// Many-to-many: User <-> Role
+model UserRole {
+  id        String   @id @default(uuid())
+  userId    String
+  roleId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  role      Role     @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+
+  @@unique([userId, roleId])
+  @@index([userId])
+  @@index([roleId])
+}
+
+// Many-to-many: Role <-> Permission
+model RolePermission {
+  id           String     @id @default(uuid())
+  roleId       String
+  permissionId String
+  role         Role       @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  permission   Permission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
+  createdAt    DateTime   @default(now())
+
+  @@unique([roleId, permissionId])
+  @@index([roleId])
+  @@index([permissionId])
+}
+
+// ============================================
+// Authentication
+// ============================================
+
+model RefreshToken {
+  id        String   @id @default(uuid())
+  token     String   @unique
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  expiresAt DateTime
+  createdAt DateTime @default(now())
+
+  @@index([token])
+  @@index([userId])
+}
+
+// ============================================
+// Multi-tenancy (Optional)
+// ============================================
+
+model Tenant {
+  id        String    @id @default(uuid())
+  name      String
+  slug      String    @unique
+  isActive  Boolean   @default(true)
+  
+  // Relations
+  users     User[]
+  
+  // Timestamps & Soft Delete
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+  deletedAt DateTime?
+
+  @@index([slug])
+}
+
+// ============================================
+// i18n / Translations (Optional - DB driven)
+// ============================================
+
+model Translation {
+  id        String   @id @default(uuid())
+  key       String
+  locale    String   // e.g., "en", "tr", "de"
+  value     String
+  namespace String   @default("common") // e.g., "common", "errors", "validation"
+  
+  // Timestamps
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([key, locale, namespace])
+  @@index([key])
+  @@index([locale])
+  @@index([namespace])
+}

prompt.md

@@ -0,0 +1,124 @@
+# 🤖 AI Assistant Context - NestJS Backend
+
+> Bu dosya, AI asistanların (Claude, GPT, Gemini vb.) projeyi hızlıca anlaması için hazırlanmış bir referans dökümanıdır.
+
+---
+
+## 📚 Projeyi Anlamak İçin Önce Oku
+
+1. **README.md** dosyasını oku - Projenin mimarisi, ADR'ler, teknoloji stack'i ve kurulum adımlarını içerir.
+
+```
+README.md
+```
+
+---
+
+## 🎯 Referans Klasörü
+
+`.claude/` klasörü best practice'ler, agent tanımları ve yardımcı scriptler içerir. Görev türüne göre ilgili referansları kullan:
+
+### Skills (Beceri Setleri)
+
+| Beceri                     | Konum                                    | Ne Zaman Kullan                 |
+| -------------------------- | ---------------------------------------- | ------------------------------- |
+| **Senior Backend**         | `.claude/skills/senior-backend/`         | API geliştirme, servis yazarken |
+| **Senior Fullstack**       | `.claude/skills/senior-fullstack/`       | End-to-end feature geliştirme   |
+| **Code Reviewer**          | `.claude/skills/code-reviewer/`          | Code review yaparken            |
+| **Receiving Code Review**  | `.claude/skills/receiving-code-review/`  | Review feedback işlerken        |
+| **Senior ML Engineer**     | `.claude/skills/senior-ml-engineer/`     | ML/AI entegrasyonları           |
+| **Senior Prompt Engineer** | `.claude/skills/senior-prompt-engineer/` | LLM prompt optimizasyonu        |
+
+### Agents (Roller)
+
+| Agent                  | Konum                                  | Açıklama                    |
+| ---------------------- | -------------------------------------- | --------------------------- |
+| **TypeScript Pro**     | `.claude/agents/typescript-pro.md`     | TypeScript best practices   |
+| **Code Reviewer**      | `.claude/agents/code-reviewer.md`      | Kod review yapma            |
+| **Debugger**           | `.claude/agents/debugger.md`           | Hata ayıklama               |
+| **Security Engineer**  | `.claude/agents/security-engineer.md`  | Güvenlik analizi            |
+| **Database Optimizer** | `.claude/agents/database-optimizer.md` | DB performans optimizasyonu |
+| **API Documenter**     | `.claude/agents/api-documenter.md`     | API dokümantasyonu          |
+| **API Security Audit** | `.claude/agents/api-security-audit.md` | API güvenlik denetimi       |
+| **AI Engineer**        | `.claude/agents/ai-engineer.md`        | AI/ML entegrasyonları       |
+| **Data Scientist**     | `.claude/agents/data-scientist.md`     | Veri analizi                |
+
+---
+
+## 🔧 Teknoloji Stack'i (Özet)
+
+- **Framework:** NestJS
+- **ORM:** Prisma
+- **Database:** PostgreSQL
+- **Cache:** Redis
+- **Auth:** JWT + RBAC
+- **i18n:** nestjs-i18n
+- **Language:** TypeScript (Strict Mode)
+
+---
+
+## 🏗️ Proje Yapısı Özeti
+
+```
+src/
+├── common/           # Shared (BaseService, BaseController, Filters, Interceptors)
+├── config/           # App configuration
+├── database/         # Prisma service
+├── i18n/             # Translation files
+└── modules/          # Feature modules (auth, users, admin, health)
+```
+
+---
+
+## ✅ Görev Bazlı Referans Kullanımı
+
+**API geliştirirken:**
+
+```
+.claude/skills/senior-backend/SKILL.md
+.claude/skills/senior-backend/references/
+```
+
+**Code review yaparken:**
+
+```
+.claude/skills/code-reviewer/SKILL.md
+.claude/skills/code-reviewer/references/common_antipatterns.md
+```
+
+**Güvenlik denetimi yaparken:**
+
+```
+.claude/agents/security-engineer.md
+.claude/agents/api-security-audit.md
+```
+
+**Database optimizasyonu:**
+
+```
+.claude/agents/database-optimizer.md
+```
+
+---
+
+## 💡 Örnek Prompt'lar
+
+### Yeni Module Oluşturma
+
+> "`.claude/skills/senior-backend/` referanslarını kullanarak, `notifications` modülü oluştur. BaseService ve BaseController pattern'lerini kullan."
+
+### Code Review
+
+> "`.claude/skills/code-reviewer/references/common_antipatterns.md` dosyasına göre `src/modules/auth/` klasörünü review et."
+
+### Güvenlik Analizi
+
+> "`.claude/agents/api-security-audit.md` rolünü al ve projenin güvenlik açıklarını analiz et."
+
+### Database Optimizasyonu
+
+> "`.claude/agents/database-optimizer.md` rolünü al ve Prisma sorgularını optimize et."
+
+---
+
+**Frontend Projesi:** `../nextjs-boilerplate-full/prompt.md`

src/app.controller.spec.ts

@@ -0,0 +1,22 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+describe('AppController', () => {
+  let appController: AppController;
+
+  beforeEach(async () => {
+    const app: TestingModule = await Test.createTestingModule({
+      controllers: [AppController],
+      providers: [AppService],
+    }).compile();
+
+    appController = app.get<AppController>(AppController);
+  });
+
+  describe('root', () => {
+    it('should return "Hello World!"', () => {
+      expect(appController.getHello()).toBe('Hello World!');
+    });
+  });
+});

src/app.controller.ts

@@ -0,0 +1,12 @@
+import { Controller, Get } from '@nestjs/common';
+import { AppService } from './app.service';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get()
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}

src/app.module.ts

@@ -0,0 +1,202 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR } from '@nestjs/core';
+import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
+import { CacheModule } from '@nestjs/cache-manager';
+import { redisStore } from 'cache-manager-redis-yet';
+import { LoggerModule } from 'nestjs-pino';
+import {
+  I18nModule,
+  AcceptLanguageResolver,
+  HeaderResolver,
+  QueryResolver,
+} from 'nestjs-i18n';
+import * as path from 'path';
+
+// Config
+import {
+  appConfig,
+  databaseConfig,
+  jwtConfig,
+  redisConfig,
+  i18nConfig,
+  featuresConfig,
+  throttleConfig,
+} from './config/configuration';
+import { geminiConfig } from './modules/gemini/gemini.config';
+import { validateEnv } from './config/env.validation';
+
+// Common
+import { GlobalExceptionFilter } from './common/filters/global-exception.filter';
+import { ResponseInterceptor } from './common/interceptors/response.interceptor';
+
+// Database
+import { DatabaseModule } from './database/database.module';
+
+// Modules
+import { AuthModule } from './modules/auth/auth.module';
+import { UsersModule } from './modules/users/users.module';
+import { AdminModule } from './modules/admin/admin.module';
+import { HealthModule } from './modules/health/health.module';
+import { GeminiModule } from './modules/gemini/gemini.module';
+
+// Guards
+import {
+  JwtAuthGuard,
+  RolesGuard,
+  PermissionsGuard,
+} from './modules/auth/guards';
+
+@Module({
+  imports: [
+    // Configuration
+    ConfigModule.forRoot({
+      isGlobal: true,
+      validate: validateEnv,
+      load: [
+        appConfig,
+        databaseConfig,
+        jwtConfig,
+        redisConfig,
+        i18nConfig,
+        featuresConfig,
+        throttleConfig,
+        geminiConfig,
+      ],
+    }),
+
+    // Logger (Structured Logging with Pino)
+    LoggerModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: async (configService: ConfigService) => {
+        return {
+          pinoHttp: {
+            level: configService.get('app.isDevelopment') ? 'debug' : 'info',
+            transport: configService.get('app.isDevelopment')
+              ? {
+                  target: 'pino-pretty',
+                  options: {
+                    singleLine: true,
+                  },
+                }
+              : undefined,
+          },
+        };
+      },
+    }),
+
+    // i18n
+    I18nModule.forRootAsync({
+      useFactory: (configService: ConfigService) => ({
+        fallbackLanguage: configService.get('i18n.fallbackLanguage', 'en'),
+        loaderOptions: {
+          path: path.join(__dirname, '/i18n/'),
+          watch: configService.get('app.isDevelopment', true),
+        },
+      }),
+      resolvers: [
+        new HeaderResolver(['x-lang', 'accept-language']),
+        new QueryResolver(['lang']),
+        AcceptLanguageResolver,
+      ],
+      inject: [ConfigService],
+    }),
+
+    // Throttling
+    ThrottlerModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => [
+        {
+          ttl: configService.get('throttle.ttl', 60000),
+          limit: configService.get('throttle.limit', 100),
+        },
+      ],
+    }),
+
+    // Caching (Redis with in-memory fallback)
+    CacheModule.registerAsync({
+      isGlobal: true,
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => {
+        const useRedis = configService.get('REDIS_ENABLED', 'false') === 'true';
+
+        if (useRedis) {
+          try {
+            const store = await redisStore({
+              socket: {
+                host: configService.get('redis.host', 'localhost'),
+                port: configService.get('redis.port', 6379),
+              },
+              ttl: 60 * 1000, // 1 minute default
+            });
+            console.log('✅ Redis cache connected');
+            return {
+              store: store as unknown as any,
+              ttl: 60 * 1000,
+            };
+          } catch {
+            console.warn('⚠️ Redis connection failed, using in-memory cache');
+          }
+        }
+
+        // Fallback to in-memory cache
+        console.log('📦 Using in-memory cache');
+        return {
+          ttl: 60 * 1000,
+        };
+      },
+      inject: [ConfigService],
+    }),
+
+    // Database
+    DatabaseModule,
+
+    // Core Modules
+    AuthModule,
+    UsersModule,
+    AdminModule,
+
+    // Optional Modules (controlled by env variables)
+    GeminiModule,
+    HealthModule,
+  ],
+  providers: [
+    // Global Exception Filter
+    {
+      provide: APP_FILTER,
+      useClass: GlobalExceptionFilter,
+    },
+
+    // Global Response Interceptor
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: ResponseInterceptor,
+    },
+
+    // Global Rate Limiting
+    {
+      provide: APP_GUARD,
+      useClass: ThrottlerGuard,
+    },
+
+    // Global JWT Auth Guard
+    {
+      provide: APP_GUARD,
+      useClass: JwtAuthGuard,
+    },
+
+    // Global Roles Guard
+    {
+      provide: APP_GUARD,
+      useClass: RolesGuard,
+    },
+
+    // Global Permissions Guard
+    {
+      provide: APP_GUARD,
+      useClass: PermissionsGuard,
+    },
+  ],
+})
+export class AppModule {}

src/app.service.ts

@@ -0,0 +1,8 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Hello World!';
+  }
+}

src/common/base/base.controller.ts

@@ -0,0 +1,128 @@
+import {
+  Get,
+  Post,
+  Put,
+  Delete,
+  Param,
+  Query,
+  Body,
+  HttpCode,
+  ParseUUIDPipe,
+} from '@nestjs/common';
+import {
+  ApiOperation,
+  ApiOkResponse,
+  ApiNotFoundResponse,
+  ApiBadRequestResponse,
+} from '@nestjs/swagger';
+import { BaseService } from './base.service';
+import { PaginationDto } from '../dto/pagination.dto';
+import {
+  ApiResponse,
+  createSuccessResponse,
+  createPaginatedResponse,
+} from '../types/api-response.type';
+
+/**
+ * Generic base controller with common CRUD endpoints
+ * Extend this class for entity-specific controllers
+ *
+ * Note: Use decorators like @Controller() on the child class
+ */
+export abstract class BaseController<T, CreateDto, UpdateDto> {
+  constructor(
+    protected readonly service: BaseService<T, CreateDto, UpdateDto>,
+    protected readonly entityName: string,
+  ) {}
+
+  @Get()
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Get all records with pagination' })
+  @ApiOkResponse({ description: 'Records retrieved successfully' })
+  async findAll(
+    @Query() pagination: PaginationDto,
+  ): Promise<ApiResponse<{ items: T[]; meta: any }>> {
+    const result = await this.service.findAll(pagination);
+    return createPaginatedResponse(
+      result.items,
+      result.meta.total,
+      result.meta.page,
+      result.meta.limit,
+      `${this.entityName} list retrieved successfully`,
+    );
+  }
+
+  @Get(':id')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Get a record by ID' })
+  @ApiOkResponse({ description: 'Record retrieved successfully' })
+  @ApiNotFoundResponse({ description: 'Record not found' })
+  async findOne(
+    @Param('id', ParseUUIDPipe) id: string,
+  ): Promise<ApiResponse<T>> {
+    const result = await this.service.findOne(id);
+    return createSuccessResponse(
+      result,
+      `${this.entityName} retrieved successfully`,
+    );
+  }
+
+  @Post()
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Create a new record' })
+  @ApiOkResponse({ description: 'Record created successfully' })
+  @ApiBadRequestResponse({ description: 'Validation failed' })
+  async create(@Body() createDto: CreateDto): Promise<ApiResponse<T>> {
+    const result = await this.service.create(createDto);
+    return createSuccessResponse(
+      result,
+      `${this.entityName} created successfully`,
+      201,
+    );
+  }
+
+  @Put(':id')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Update an existing record' })
+  @ApiOkResponse({ description: 'Record updated successfully' })
+  @ApiNotFoundResponse({ description: 'Record not found' })
+  async update(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() updateDto: UpdateDto,
+  ): Promise<ApiResponse<T>> {
+    const result = await this.service.update(id, updateDto);
+    return createSuccessResponse(
+      result,
+      `${this.entityName} updated successfully`,
+    );
+  }
+
+  @Delete(':id')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Delete a record (soft delete)' })
+  @ApiOkResponse({ description: 'Record deleted successfully' })
+  @ApiNotFoundResponse({ description: 'Record not found' })
+  async delete(
+    @Param('id', ParseUUIDPipe) id: string,
+  ): Promise<ApiResponse<T>> {
+    const result = await this.service.delete(id);
+    return createSuccessResponse(
+      result,
+      `${this.entityName} deleted successfully`,
+    );
+  }
+
+  @Post(':id/restore')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Restore a soft-deleted record' })
+  @ApiOkResponse({ description: 'Record restored successfully' })
+  async restore(
+    @Param('id', ParseUUIDPipe) id: string,
+  ): Promise<ApiResponse<T>> {
+    const result = await this.service.restore(id);
+    return createSuccessResponse(
+      result,
+      `${this.entityName} restored successfully`,
+    );
+  }
+}

src/common/base/base.service.ts

@@ -0,0 +1,165 @@
+import { NotFoundException, Logger } from '@nestjs/common';
+import { PrismaService } from '../../database/prisma.service';
+import { PaginationDto } from '../dto/pagination.dto';
+import { PaginationMeta } from '../types/api-response.type';
+
+/**
+ * Generic base service with common CRUD operations
+ * Extend this class for entity-specific services
+ */
+export abstract class BaseService<T, CreateDto, UpdateDto> {
+  protected readonly logger: Logger;
+
+  constructor(
+    protected readonly prisma: PrismaService,
+    protected readonly modelName: string,
+  ) {
+    this.logger = new Logger(`${modelName}Service`);
+  }
+
+  /**
+   * Get the Prisma model delegate
+   */
+  protected get model() {
+    return (this.prisma as any)[this.modelName.toLowerCase()];
+  }
+
+  /**
+   * Find all records with pagination
+   */
+  async findAll(
+    pagination: PaginationDto,
+    where?: any,
+  ): Promise<{ items: T[]; meta: PaginationMeta }> {
+    const { skip, take, orderBy } = pagination;
+
+    const [items, total] = await Promise.all([
+      this.model.findMany({
+        where,
+        skip,
+        take,
+        orderBy,
+      }),
+      this.model.count({ where }),
+    ]);
+
+    const totalPages = Math.ceil(total / take);
+
+    return {
+      items,
+      meta: {
+        total,
+        page: pagination.page || 1,
+        limit: pagination.limit || 10,
+        totalPages,
+        hasNextPage: (pagination.page || 1) < totalPages,
+        hasPreviousPage: (pagination.page || 1) > 1,
+      },
+    };
+  }
+
+  /**
+   * Find a single record by ID
+   */
+  async findOne(id: string, include?: any): Promise<T> {
+    const record = await this.model.findUnique({
+      where: { id },
+      include,
+    });
+
+    if (!record) {
+      throw new NotFoundException(`${this.modelName} not found`);
+    }
+
+    return record;
+  }
+
+  /**
+   * Find a single record by custom criteria
+   */
+  findOneBy(where: any, include?: any): Promise<T | null> {
+    return this.model.findFirst({
+      where,
+      include,
+    });
+  }
+
+  /**
+   * Create a new record
+   */
+  create(data: CreateDto, include?: any): Promise<T> {
+    return this.model.create({
+      data,
+      include,
+    });
+  }
+
+  /**
+   * Update an existing record
+   */
+  async update(id: string, data: UpdateDto, include?: any): Promise<T> {
+    // Check if record exists
+    await this.findOne(id);
+
+    return this.model.update({
+      where: { id },
+      data,
+      include,
+    });
+  }
+
+  /**
+   * Soft delete a record (sets deletedAt)
+   */
+  async delete(id: string): Promise<T> {
+    // Check if record exists
+    await this.findOne(id);
+
+    return this.model.delete({
+      where: { id },
+    });
+  }
+
+  /**
+   * Hard delete a record (permanently removes)
+   */
+  async hardDelete(id: string): Promise<T> {
+    // Check if record exists
+    await this.findOne(id);
+
+    return this.prisma.hardDelete(this.modelName, { id });
+  }
+
+  /**
+   * Restore a soft-deleted record
+   */
+  async restore(id: string): Promise<T> {
+    return this.prisma.restore(this.modelName, { id });
+  }
+
+  /**
+   * Check if a record exists
+   */
+  async exists(id: string): Promise<boolean> {
+    const count = await this.model.count({
+      where: { id },
+    });
+    return count > 0;
+  }
+
+  /**
+   * Count records matching criteria
+   */
+  count(where?: any): Promise<number> {
+    return this.model.count({ where });
+  }
+
+  /**
+   * Execute a transaction
+   */
+  transaction<R>(fn: (prisma: PrismaService) => Promise<R>): Promise<R> {
+    return this.prisma.$transaction(async (tx) => {
+      return fn(tx as unknown as PrismaService);
+    });
+  }
+}

src/common/base/index.ts

@@ -0,0 +1,2 @@
+export * from './base.service';
+export * from './base.controller';

src/common/decorators/index.ts

@@ -0,0 +1,60 @@
+import {
+  createParamDecorator,
+  ExecutionContext,
+  SetMetadata,
+} from '@nestjs/common';
+
+/**
+ * Get the current authenticated user from request
+ */
+export const CurrentUser = createParamDecorator(
+  (data: string | undefined, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    const user = request.user;
+
+    if (data) {
+      return user?.[data];
+    }
+
+    return user;
+  },
+);
+
+/**
+ * Mark a route as public (no authentication required)
+ */
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);
+
+/**
+ * Require specific roles to access a route
+ */
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
+
+/**
+ * Require specific permissions to access a route
+ */
+export const PERMISSIONS_KEY = 'permissions';
+export const RequirePermissions = (...permissions: string[]) =>
+  SetMetadata(PERMISSIONS_KEY, permissions);
+
+/**
+ * Get tenant ID from request (for multi-tenancy)
+ */
+export const CurrentTenant = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.tenantId;
+  },
+);
+
+/**
+ * Get the current language from request headers
+ */
+export const CurrentLang = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.headers['accept-language'] || 'en';
+  },
+);

src/common/dto/pagination.dto.ts

@@ -0,0 +1,65 @@
+import { IsOptional, IsInt, Min, Max, IsString, IsIn } from 'class-validator';
+import { Transform } from 'class-transformer';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class PaginationDto {
+  @ApiPropertyOptional({ default: 1, minimum: 1, description: 'Page number' })
+  @IsOptional()
+  @Transform(({ value }) => parseInt(value, 10))
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({
+    default: 10,
+    minimum: 1,
+    maximum: 100,
+    description: 'Items per page',
+  })
+  @IsOptional()
+  @Transform(({ value }) => parseInt(value, 10))
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 10;
+
+  @ApiPropertyOptional({ description: 'Field to sort by' })
+  @IsOptional()
+  @IsString()
+  sortBy?: string = 'createdAt';
+
+  @ApiPropertyOptional({
+    enum: ['asc', 'desc'],
+    default: 'desc',
+    description: 'Sort order',
+  })
+  @IsOptional()
+  @IsIn(['asc', 'desc'])
+  sortOrder?: 'asc' | 'desc' = 'desc';
+
+  @ApiPropertyOptional({ description: 'Search query' })
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  /**
+   * Get skip value for Prisma
+   */
+  get skip(): number {
+    return ((this.page || 1) - 1) * (this.limit || 10);
+  }
+
+  /**
+   * Get take value for Prisma
+   */
+  get take(): number {
+    return this.limit || 10;
+  }
+
+  /**
+   * Get orderBy object for Prisma
+   */
+  get orderBy(): Record<string, 'asc' | 'desc'> {
+    return { [this.sortBy || 'createdAt']: this.sortOrder || 'desc' };
+  }
+}

src/common/filters/global-exception.filter.ts

@@ -0,0 +1,109 @@
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+import { I18nService, I18nContext } from 'nestjs-i18n';
+import { ApiResponse, createErrorResponse } from '../types/api-response.type';
+
+/**
+ * Global exception filter that catches all exceptions
+ * and returns a standardized ApiResponse with HTTP 200
+ */
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(GlobalExceptionFilter.name);
+
+  constructor(private readonly i18n?: I18nService) {}
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    // Determine status and message
+    let status = HttpStatus.INTERNAL_SERVER_ERROR;
+    let message = 'Internal server error';
+    let errors: string[] = [];
+
+    if (exception instanceof HttpException) {
+      status = exception.getStatus();
+      const exceptionResponse = exception.getResponse();
+
+      if (typeof exceptionResponse === 'string') {
+        message = exceptionResponse;
+      } else if (typeof exceptionResponse === 'object') {
+        const responseObj = exceptionResponse as Record<string, unknown>;
+        message = (responseObj.message as string) || exception.message;
+
+        // Handle validation errors (class-validator)
+        if (Array.isArray(responseObj.message)) {
+          errors = responseObj.message as string[];
+          message = 'VALIDATION_FAILED';
+        }
+      }
+    } else if (exception instanceof Error) {
+      message = exception.message;
+    }
+
+    // Try to translate the message
+    if (this.i18n) {
+      try {
+        const i18nContext = I18nContext.current();
+        let lang = i18nContext?.lang;
+
+        if (!lang) {
+          const acceptLanguage = request.headers['accept-language'];
+          const xLang = request.headers['x-lang'];
+
+          if (xLang) {
+            lang = Array.isArray(xLang) ? xLang[0] : xLang;
+          } else if (acceptLanguage) {
+            // Take first preferred language: "tr-TR,en;q=0.9" -> "tr"
+            lang = acceptLanguage.split(',')[0].split(';')[0].split('-')[0];
+          }
+        }
+
+        lang = lang || 'en';
+
+        // Translate validation error specially
+        if (message === 'VALIDATION_FAILED') {
+          message = this.i18n.translate('errors.VALIDATION_FAILED', { lang });
+        } else {
+          // Try dynamic translation
+          const translatedMessage = this.i18n.translate(`errors.${message}`, {
+            lang,
+          });
+          // Only update if translation exists (key is different from result)
+          if (translatedMessage !== `errors.${message}`) {
+            message = translatedMessage as string;
+          }
+        }
+      } catch {
+        // Keep original message if translation fails
+      }
+    }
+
+    // Log the error
+    this.logger.error(
+      `${request.method} ${request.url} - ${status} - ${message}`,
+      exception instanceof Error ? exception.stack : undefined,
+    );
+
+    // Build response
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    const errorResponse: ApiResponse<null> = createErrorResponse(
+      message,
+      status,
+      errors,
+      isDevelopment && exception instanceof Error ? exception.stack : undefined,
+    );
+
+    // Always return HTTP 200, actual status in body
+    response.status(200).json(errorResponse);
+  }
+}

src/common/interceptors/response.interceptor.ts

@@ -0,0 +1,74 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { ApiResponse, createSuccessResponse } from '../types/api-response.type';
+
+/**
+ * Response interceptor that wraps all successful responses
+ * in the standard ApiResponse format
+ */
+import { I18nService, I18nContext } from 'nestjs-i18n';
+
+@Injectable()
+export class ResponseInterceptor<T> implements NestInterceptor<
+  T,
+  ApiResponse<T>
+> {
+  constructor(private readonly i18n: I18nService) {}
+
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Observable<ApiResponse<T>> {
+    return next.handle().pipe(
+      map((data: unknown) => {
+        // If data is already an ApiResponse, return as-is
+        if (this.isApiResponse(data)) {
+          return data as ApiResponse<T>;
+        }
+
+        const request = context.switchToHttp().getRequest();
+
+        // Determine language
+        const i18nContext = I18nContext.current();
+        let lang = i18nContext?.lang;
+
+        if (!lang) {
+          const acceptLanguage = request.headers['accept-language'];
+          const xLang = request.headers['x-lang'];
+
+          if (xLang) {
+            lang = Array.isArray(xLang) ? xLang[0] : xLang;
+          } else if (acceptLanguage) {
+            lang = acceptLanguage.split(',')[0].split(';')[0].split('-')[0];
+          }
+        }
+
+        lang = lang || 'en';
+
+        const message = this.i18n.translate('common.success', {
+          lang,
+        });
+
+        // Wrap in success response
+        return createSuccessResponse(data as T, message);
+      }),
+    );
+  }
+
+  private isApiResponse(data: unknown): boolean {
+    return (
+      data !== null &&
+      typeof data === 'object' &&
+      'success' in data &&
+      'status' in data &&
+      'message' in data &&
+      'data' in data
+    );
+  }
+}

src/common/types/api-response.type.ts

@@ -0,0 +1,96 @@
+/**
+ * Standard API Response Type
+ * All responses return HTTP 200 with this structure
+ */
+export type ApiResponse<T = any> = {
+  errors: any[];
+  stack?: string;
+  message: string;
+  success: boolean;
+  status: number;
+  data: T;
+};
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedData<T> {
+  items: T[];
+  meta: PaginationMeta;
+}
+
+export interface PaginationMeta {
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+
+/**
+ * Create a successful API response
+ */
+export function createSuccessResponse<T>(
+  data: T,
+  message = 'Success',
+  status = 200,
+): ApiResponse<T> {
+  return {
+    success: true,
+    status,
+    message,
+    data,
+    errors: [],
+  };
+}
+
+/**
+ * Create an error API response
+ */
+export function createErrorResponse(
+  message: string,
+  status = 400,
+  errors: any[] = [],
+  stack?: string,
+): ApiResponse<null> {
+  return {
+    success: false,
+    status,
+    message,
+    data: null,
+    errors,
+    stack,
+  };
+}
+
+/**
+ * Create a paginated API response
+ */
+export function createPaginatedResponse<T>(
+  items: T[],
+  total: number,
+  page: number,
+  limit: number,
+  message = 'Success',
+): ApiResponse<PaginatedData<T>> {
+  const totalPages = Math.ceil(total / limit);
+
+  return {
+    success: true,
+    status: 200,
+    message,
+    data: {
+      items,
+      meta: {
+        total,
+        page,
+        limit,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    },
+    errors: [],
+  };
+}

src/config/configuration.ts

@@ -0,0 +1,57 @@
+import { registerAs } from '@nestjs/config';
+
+export const appConfig = registerAs('app', () => ({
+  env: process.env.NODE_ENV || 'development',
+  port: parseInt(process.env.PORT || '3000', 10),
+  isDevelopment: process.env.NODE_ENV === 'development',
+  isProduction: process.env.NODE_ENV === 'production',
+}));
+
+export const databaseConfig = registerAs('database', () => ({
+  url: process.env.DATABASE_URL,
+}));
+
+export const jwtConfig = registerAs('jwt', () => ({
+  secret: process.env.JWT_SECRET,
+  accessExpiration: process.env.JWT_ACCESS_EXPIRATION || '15m',
+  refreshExpiration: process.env.JWT_REFRESH_EXPIRATION || '7d',
+}));
+
+export const redisConfig = registerAs('redis', () => ({
+  host: process.env.REDIS_HOST || 'localhost',
+  port: parseInt(process.env.REDIS_PORT || '6379', 10),
+  password: process.env.REDIS_PASSWORD || undefined,
+}));
+
+export const i18nConfig = registerAs('i18n', () => ({
+  defaultLanguage: process.env.DEFAULT_LANGUAGE || 'en',
+  fallbackLanguage: process.env.FALLBACK_LANGUAGE || 'en',
+}));
+
+export const featuresConfig = registerAs('features', () => ({
+  mail: process.env.ENABLE_MAIL === 'true',
+  s3: process.env.ENABLE_S3 === 'true',
+  websocket: process.env.ENABLE_WEBSOCKET === 'true',
+  multiTenancy: process.env.ENABLE_MULTI_TENANCY === 'true',
+}));
+
+export const mailConfig = registerAs('mail', () => ({
+  host: process.env.MAIL_HOST,
+  port: parseInt(process.env.MAIL_PORT || '587', 10),
+  user: process.env.MAIL_USER,
+  password: process.env.MAIL_PASSWORD,
+  from: process.env.MAIL_FROM,
+}));
+
+export const s3Config = registerAs('s3', () => ({
+  endpoint: process.env.S3_ENDPOINT,
+  accessKey: process.env.S3_ACCESS_KEY,
+  secretKey: process.env.S3_SECRET_KEY,
+  bucket: process.env.S3_BUCKET,
+  region: process.env.S3_REGION || 'us-east-1',
+}));
+
+export const throttleConfig = registerAs('throttle', () => ({
+  ttl: parseInt(process.env.THROTTLE_TTL || '60000', 10),
+  limit: parseInt(process.env.THROTTLE_LIMIT || '100', 10),
+}));

src/config/env.validation.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+
+/**
+ * Helper to parse boolean from string
+ */
+const booleanString = z
+  .string()
+  .optional()
+  .default('false')
+  .transform((val) => val === 'true');
+
+/**
+ * Environment variables schema validation using Zod
+ */
+export const envSchema = z.object({
+  // Environment
+  NODE_ENV: z
+    .enum(['development', 'production', 'test'])
+    .default('development'),
+  PORT: z.coerce.number().default(3000),
+
+  // Database
+  DATABASE_URL: z.string().url(),
+
+  // JWT
+  JWT_SECRET: z.string().min(32),
+  JWT_ACCESS_EXPIRATION: z.string().default('15m'),
+  JWT_REFRESH_EXPIRATION: z.string().default('7d'),
+
+  // Redis
+  REDIS_HOST: z.string().default('localhost'),
+  REDIS_PORT: z.coerce.number().default(6379),
+  REDIS_PASSWORD: z.string().optional(),
+
+  // i18n
+  DEFAULT_LANGUAGE: z.string().default('en'),
+  FALLBACK_LANGUAGE: z.string().default('en'),
+
+  // Optional Features
+  ENABLE_MAIL: booleanString,
+  ENABLE_S3: booleanString,
+  ENABLE_WEBSOCKET: booleanString,
+  ENABLE_MULTI_TENANCY: booleanString,
+
+  // Mail (Optional)
+  MAIL_HOST: z.string().optional(),
+  MAIL_PORT: z.coerce.number().optional(),
+  MAIL_USER: z.string().optional(),
+  MAIL_PASSWORD: z.string().optional(),
+  MAIL_FROM: z.string().optional(),
+
+  // S3 (Optional)
+  S3_ENDPOINT: z.string().optional(),
+  S3_ACCESS_KEY: z.string().optional(),
+  S3_SECRET_KEY: z.string().optional(),
+  S3_BUCKET: z.string().optional(),
+  S3_REGION: z.string().optional(),
+
+  // Throttle
+  THROTTLE_TTL: z.coerce.number().default(60000),
+  THROTTLE_LIMIT: z.coerce.number().default(100),
+});
+
+export type EnvConfig = z.infer<typeof envSchema>;
+
+/**
+ * Validate environment variables
+ */
+export function validateEnv(config: Record<string, unknown>): EnvConfig {
+  const result = envSchema.safeParse(config);
+
+  if (!result.success) {
+    const errors = result.error.issues.map(
+      (err) => `${err.path.join('.')}: ${err.message}`,
+    );
+    throw new Error(`Environment validation failed:\n${errors.join('\n')}`);
+  }
+
+  return result.data;
+}

src/database/database.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+
+@Global()
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class DatabaseModule {}

src/database/prisma.service.ts

@@ -0,0 +1,134 @@
+import {
+  Injectable,
+  OnModuleInit,
+  OnModuleDestroy,
+  Logger,
+} from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+// Models that support soft delete
+const SOFT_DELETE_MODELS = ['user', 'role', 'tenant'];
+
+// Type for Prisma model delegate with common operations
+interface PrismaDelegate {
+  delete: (args: { where: Record<string, unknown> }) => Promise<unknown>;
+  findMany: (args?: Record<string, unknown>) => Promise<unknown[]>;
+  update: (args: {
+    where: Record<string, unknown>;
+    data: Record<string, unknown>;
+  }) => Promise<unknown>;
+}
+
+@Injectable()
+export class PrismaService
+  extends PrismaClient
+  implements OnModuleInit, OnModuleDestroy
+{
+  private readonly logger = new Logger(PrismaService.name);
+
+  constructor() {
+    super({
+      log: [
+        { emit: 'event', level: 'query' },
+        { emit: 'event', level: 'error' },
+        { emit: 'event', level: 'warn' },
+      ],
+    });
+  }
+
+  async onModuleInit() {
+    this.logger.log(
+      `Connecting to database... URL: ${process.env.DATABASE_URL?.split('@')[1]}`,
+    ); // Mask password
+    try {
+      await this.$connect();
+      this.logger.log('✅ Database connected successfully');
+    } catch (error) {
+      this.logger.error(
+        `❌ Database connection failed: ${error.message}`,
+        error.stack,
+      );
+      throw error;
+    }
+  }
+
+  async onModuleDestroy() {
+    await this.$disconnect();
+    this.logger.log('🔌 Database disconnected');
+  }
+
+  /**
+   * Check if model has soft delete (deletedAt field)
+   */
+  hasSoftDelete(model: string | undefined): boolean {
+    return model ? SOFT_DELETE_MODELS.includes(model.toLowerCase()) : false;
+  }
+
+  /**
+   * Hard delete - actually remove from database
+   */
+  hardDelete<T>(model: string, where: Record<string, unknown>): Promise<T> {
+    const delegate = this.getModelDelegate(model);
+    return delegate.delete({ where }) as Promise<T>;
+  }
+
+  /**
+   * Find including soft deleted records
+   */
+  findWithDeleted<T>(
+    model: string,
+    args?: Record<string, unknown>,
+  ): Promise<T[]> {
+    const delegate = this.getModelDelegate(model);
+    return delegate.findMany(args) as Promise<T[]>;
+  }
+
+  /**
+   * Restore a soft deleted record
+   */
+  restore<T>(model: string, where: Record<string, unknown>): Promise<T> {
+    const delegate = this.getModelDelegate(model);
+    return delegate.update({
+      where,
+      data: { deletedAt: null },
+    }) as Promise<T>;
+  }
+
+  /**
+   * Soft delete - set deletedAt to current date
+   */
+  softDelete<T>(model: string, where: Record<string, unknown>): Promise<T> {
+    const delegate = this.getModelDelegate(model);
+    return delegate.update({
+      where,
+      data: { deletedAt: new Date() },
+    }) as Promise<T>;
+  }
+
+  /**
+   * Find many excluding soft deleted records
+   */
+  findManyActive<T>(
+    model: string,
+    args?: Record<string, unknown>,
+  ): Promise<T[]> {
+    const delegate = this.getModelDelegate(model);
+    const whereWithDeleted = {
+      ...args,
+      where: {
+        ...(args?.where as Record<string, unknown> | undefined),
+        deletedAt: null,
+      },
+    };
+    return delegate.findMany(whereWithDeleted) as Promise<T[]>;
+  }
+
+  /**
+   * Get Prisma model delegate by name
+   */
+  private getModelDelegate(model: string): PrismaDelegate {
+    const modelKey = model.charAt(0).toLowerCase() + model.slice(1);
+
+    return (this as any)[modelKey] as PrismaDelegate;
+  }
+}

src/i18n/en/auth.json

@@ -0,0 +1,6 @@
+{
+  "registered": "User registered successfully",
+  "login_success": "Login successful",
+  "refresh_success": "Token refreshed successfully",
+  "logout_success": "Logout successful"
+}

src/i18n/en/common.json

@@ -0,0 +1,13 @@
+{
+  "welcome": "Welcome",
+  "success": "Operation completed successfully",
+  "created": "Resource created successfully",
+  "updated": "Resource updated successfully",
+  "deleted": "Resource deleted successfully",
+  "restored": "Resource restored successfully",
+  "notFound": "Resource not found",
+  "serverError": "An unexpected error occurred",
+  "unauthorized": "You are not authorized to perform this action",
+  "forbidden": "Access denied",
+  "badRequest": "Invalid request"
+}

src/i18n/en/errors.json

@@ -0,0 +1,14 @@
+{
+  "USER_NOT_FOUND": "User not found",
+  "INVALID_CREDENTIALS": "Invalid email or password",
+  "EMAIL_ALREADY_EXISTS": "This email is already registered",
+  "INVALID_REFRESH_TOKEN": "Invalid or expired refresh token",
+  "ACCOUNT_DISABLED": "Your account has been disabled",
+  "TOKEN_EXPIRED": "Your session has expired, please login again",
+  "PERMISSION_DENIED": "You do not have permission to perform this action",
+  "ROLE_NOT_FOUND": "Role not found",
+  "TENANT_NOT_FOUND": "Tenant not found",
+  "VALIDATION_FAILED": "Validation failed",
+  "INTERNAL_ERROR": "An internal error occurred, please try again later",
+  "AUTH_REQUIRED": "Authentication required, please provide a valid token"
+}

src/i18n/en/validation.json

@@ -0,0 +1,23 @@
+{
+  "email": {
+    "required": "Email is required",
+    "invalid": "Please enter a valid email address"
+  },
+  "password": {
+    "required": "Password is required",
+    "minLength": "Password must be at least 8 characters long",
+    "weak": "Password is too weak"
+  },
+  "firstName": {
+    "required": "First name is required"
+  },
+  "lastName": {
+    "required": "Last name is required"
+  },
+  "generic": {
+    "required": "This field is required",
+    "invalid": "Invalid value",
+    "minLength": "Must be at least {min} characters",
+    "maxLength": "Must be at most {max} characters"
+  }
+}

src/i18n/tr/auth.json

@@ -0,0 +1,6 @@
+{
+  "registered": "Kullanıcı başarıyla kaydedildi",
+  "login_success": "Giriş başarılı",
+  "refresh_success": "Token başarıyla yenilendi",
+  "logout_success": "Çıkış başarılı"
+}

src/i18n/tr/common.json

@@ -0,0 +1,13 @@
+{
+  "welcome": "Hoş geldiniz",
+  "success": "İşlem başarıyla tamamlandı",
+  "created": "Kayıt başarıyla oluşturuldu",
+  "updated": "Kayıt başarıyla güncellendi",
+  "deleted": "Kayıt başarıyla silindi",
+  "restored": "Kayıt başarıyla geri yüklendi",
+  "notFound": "Kayıt bulunamadı",
+  "serverError": "Beklenmeyen bir hata oluştu",
+  "unauthorized": "Bu işlemi yapmaya yetkiniz yok",
+  "forbidden": "Erişim reddedildi",
+  "badRequest": "Geçersiz istek"
+}

src/i18n/tr/errors.json

@@ -0,0 +1,14 @@
+{
+  "USER_NOT_FOUND": "Kullanıcı bulunamadı",
+  "INVALID_CREDENTIALS": "Geçersiz e-posta veya şifre",
+  "EMAIL_ALREADY_EXISTS": "Bu e-posta adresi zaten kayıtlı",
+  "INVALID_REFRESH_TOKEN": "Geçersiz veya süresi dolmuş yenileme token'ı",
+  "ACCOUNT_DISABLED": "Hesabınız devre dışı bırakılmış",
+  "TOKEN_EXPIRED": "Oturumunuz sona erdi, lütfen tekrar giriş yapın",
+  "PERMISSION_DENIED": "Bu işlemi gerçekleştirme izniniz yok",
+  "ROLE_NOT_FOUND": "Rol bulunamadı",
+  "TENANT_NOT_FOUND": "Kiracı bulunamadı",
+  "VALIDATION_FAILED": "Doğrulama başarısız",
+  "INTERNAL_ERROR": "Bir iç hata oluştu, lütfen daha sonra tekrar deneyin",
+  "AUTH_REQUIRED": "Kimlik doğrulama gerekli, lütfen geçerli bir token sağlayın"
+}

src/i18n/tr/validation.json

@@ -0,0 +1,23 @@
+{
+  "email": {
+    "required": "E-posta adresi gereklidir",
+    "invalid": "Lütfen geçerli bir e-posta adresi girin"
+  },
+  "password": {
+    "required": "Şifre gereklidir",
+    "minLength": "Şifre en az 8 karakter olmalıdır",
+    "weak": "Şifre çok zayıf"
+  },
+  "firstName": {
+    "required": "Ad gereklidir"
+  },
+  "lastName": {
+    "required": "Soyad gereklidir"
+  },
+  "generic": {
+    "required": "Bu alan gereklidir",
+    "invalid": "Geçersiz değer",
+    "minLength": "En az {min} karakter olmalıdır",
+    "maxLength": "En fazla {max} karakter olmalıdır"
+  }
+}

src/main.ts

@@ -0,0 +1,90 @@
+import { NestFactory } from '@nestjs/core';
+import { ValidationPipe, Logger as NestLogger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { AppModule } from './app.module';
+import helmet from 'helmet';
+import { Logger, LoggerErrorInterceptor } from 'nestjs-pino';
+
+async function bootstrap() {
+  const logger = new NestLogger('Bootstrap');
+
+  logger.log('🔄 Starting application...');
+
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+
+  // Use Pino Logger
+  app.useLogger(app.get(Logger));
+  app.useGlobalInterceptors(new LoggerErrorInterceptor());
+
+  // Security Headers
+  app.use(helmet());
+
+  // Graceful Shutdown (Prisma & Docker)
+  app.enableShutdownHooks();
+
+  // Get config service
+  const configService = app.get(ConfigService);
+  const port = configService.get<number>('PORT', 3000);
+  const nodeEnv = configService.get('NODE_ENV', 'development');
+
+  // Enable CORS
+  app.enableCors({
+    origin: true,
+    credentials: true,
+  });
+
+  // Global prefix
+  app.setGlobalPrefix('api');
+
+  // Validation pipe (Strict)
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      transform: true,
+      forbidNonWhitelisted: true,
+      transformOptions: {
+        enableImplicitConversion: true,
+      },
+    }),
+  );
+
+  // Swagger setup
+  const swaggerConfig = new DocumentBuilder()
+    .setTitle('TypeScript Boilerplate API')
+    .setDescription(
+      'Senior-level NestJS backend boilerplate with generic CRUD, authentication, i18n, and Redis caching',
+    )
+    .setVersion('1.0')
+    .addBearerAuth()
+    .addTag('Auth', 'Authentication endpoints')
+    .addTag('Users', 'User management endpoints')
+    .addTag('Admin', 'Admin management endpoints')
+    .addTag('Health', 'Health check endpoints')
+    .build();
+
+  logger.log('Initializing Swagger...');
+  const document = SwaggerModule.createDocument(app, swaggerConfig);
+  SwaggerModule.setup('api/docs', app, document, {
+    swaggerOptions: {
+      persistAuthorization: true,
+    },
+  });
+  logger.log('Swagger initialized');
+
+  logger.log(`Attempting to listen on port ${port}...`);
+  await app.listen(port, '0.0.0.0');
+
+  logger.log('═══════════════════════════════════════════════════════════');
+  logger.log(`🚀 Server is running on: http://localhost:${port}/api`);
+  logger.log(`📚 Swagger documentation: http://localhost:${port}/api/docs`);
+  logger.log(`💚 Health check: http://localhost:${port}/api/health`);
+  logger.log(`🌍 Environment: ${nodeEnv.toUpperCase()}`);
+  logger.log('═══════════════════════════════════════════════════════════');
+
+  if (nodeEnv === 'development') {
+    logger.warn('⚠️  Running in development mode');
+  }
+}
+
+void bootstrap();

src/modules/admin/admin.controller.ts

@@ -0,0 +1,270 @@
+import {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  Param,
+  Body,
+  Query,
+  UseInterceptors,
+  Inject,
+} from '@nestjs/common';
+import {
+  CacheInterceptor,
+  CacheKey,
+  CacheTTL,
+  CACHE_MANAGER,
+} from '@nestjs/cache-manager';
+import * as cacheManager from 'cache-manager';
+import { ApiTags, ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
+import { Roles } from '../../common/decorators';
+import { PrismaService } from '../../database/prisma.service';
+import { PaginationDto } from '../../common/dto/pagination.dto';
+import {
+  ApiResponse,
+  createSuccessResponse,
+  createPaginatedResponse,
+  PaginatedData,
+} from '../../common/types/api-response.type';
+import { plainToInstance } from 'class-transformer';
+import { UserResponseDto } from '../users/dto/user.dto';
+import {
+  PermissionResponseDto,
+  RolePermissionResponseDto,
+  RoleResponseDto,
+  UserRoleResponseDto,
+} from './dto/admin.dto';
+
+@ApiTags('Admin')
+@ApiBearerAuth()
+@Controller('admin')
+@Roles('admin')
+export class AdminController {
+  constructor(
+    private readonly prisma: PrismaService,
+    @Inject(CACHE_MANAGER) private cacheManager: cacheManager.Cache,
+  ) {}
+
+  // ================== Users Management ==================
+
+  @Get('users')
+  @ApiOperation({ summary: 'Get all users (admin)' })
+  async getAllUsers(
+    @Query() pagination: PaginationDto,
+  ): Promise<ApiResponse<PaginatedData<UserResponseDto>>> {
+    const { skip, take, orderBy } = pagination;
+
+    const [users, total] = await Promise.all([
+      this.prisma.user.findMany({
+        skip,
+        take,
+        orderBy,
+        include: {
+          roles: {
+            include: {
+              role: true,
+            },
+          },
+        },
+      }),
+      this.prisma.user.count(),
+    ]);
+
+    const dtos = plainToInstance(
+      UserResponseDto,
+      users,
+    ) as unknown as UserResponseDto[];
+
+    return createPaginatedResponse(
+      dtos,
+      total,
+      pagination.page || 1,
+      pagination.limit || 10,
+    );
+  }
+
+  @Put('users/:id/toggle-active')
+  @ApiOperation({ summary: 'Toggle user active status' })
+  async toggleUserActive(
+    @Param('id') id: string,
+  ): Promise<ApiResponse<UserResponseDto>> {
+    const user = await this.prisma.user.findUnique({ where: { id } });
+
+    const updated = await this.prisma.user.update({
+      where: { id },
+      data: { isActive: !user?.isActive },
+    });
+
+    return createSuccessResponse(
+      plainToInstance(UserResponseDto, updated),
+      'User status updated',
+    );
+  }
+
+  @Post('users/:userId/roles/:roleId')
+  @ApiOperation({ summary: 'Assign role to user' })
+  async assignRole(
+    @Param('userId') userId: string,
+    @Param('roleId') roleId: string,
+  ): Promise<ApiResponse<UserRoleResponseDto>> {
+    const userRole = await this.prisma.userRole.create({
+      data: { userId, roleId },
+    });
+    return createSuccessResponse(
+      plainToInstance(UserRoleResponseDto, userRole),
+      'Role assigned to user',
+    );
+  }
+
+  @Delete('users/:userId/roles/:roleId')
+  @ApiOperation({ summary: 'Remove role from user' })
+  async removeRole(
+    @Param('userId') userId: string,
+    @Param('roleId') roleId: string,
+  ): Promise<ApiResponse<null>> {
+    await this.prisma.userRole.deleteMany({
+      where: { userId, roleId },
+    });
+    return createSuccessResponse(null, 'Role removed from user');
+  }
+
+  // ================== Roles Management ==================
+
+  @Get('roles')
+  @UseInterceptors(CacheInterceptor)
+  @CacheKey('roles_list')
+  @CacheTTL(60 * 1000)
+  @ApiOperation({ summary: 'Get all roles' })
+  async getAllRoles(): Promise<ApiResponse<RoleResponseDto[]>> {
+    const roles = await this.prisma.role.findMany({
+      include: {
+        permissions: {
+          include: {
+            permission: true,
+          },
+        },
+        _count: {
+          select: { users: true },
+        },
+      },
+    });
+
+    // Transform Prisma structure to DTO structure
+    const transformedRoles = roles.map((role) => ({
+      ...role,
+      permissions: role.permissions.map((rp) => rp.permission),
+    }));
+
+    return createSuccessResponse(
+      plainToInstance(
+        RoleResponseDto,
+        transformedRoles,
+      ) as unknown as RoleResponseDto[],
+    );
+  }
+
+  @Post('roles')
+  @ApiOperation({ summary: 'Create a new role' })
+  async createRole(
+    @Body() data: { name: string; description?: string },
+  ): Promise<ApiResponse<RoleResponseDto>> {
+    const role = await this.prisma.role.create({ data });
+    await this.cacheManager.del('roles_list');
+    return createSuccessResponse(
+      plainToInstance(RoleResponseDto, role),
+      'Role created',
+      201,
+    );
+  }
+
+  @Put('roles/:id')
+  @ApiOperation({ summary: 'Update a role' })
+  async updateRole(
+    @Param('id') id: string,
+    @Body() data: { name?: string; description?: string },
+  ): Promise<ApiResponse<RoleResponseDto>> {
+    const role = await this.prisma.role.update({ where: { id }, data });
+    await this.cacheManager.del('roles_list');
+    return createSuccessResponse(
+      plainToInstance(RoleResponseDto, role),
+      'Role updated',
+    );
+  }
+
+  @Delete('roles/:id')
+  @ApiOperation({ summary: 'Delete a role' })
+  async deleteRole(@Param('id') id: string): Promise<ApiResponse<null>> {
+    await this.prisma.role.delete({ where: { id } });
+    await this.cacheManager.del('roles_list');
+    return createSuccessResponse(null, 'Role deleted');
+  }
+
+  // ================== Permissions Management ==================
+
+  @Get('permissions')
+  @UseInterceptors(CacheInterceptor)
+  @CacheKey('permissions_list')
+  @CacheTTL(60 * 1000)
+  @ApiOperation({ summary: 'Get all permissions' })
+  async getAllPermissions(): Promise<ApiResponse<PermissionResponseDto[]>> {
+    const permissions = await this.prisma.permission.findMany();
+    return createSuccessResponse(
+      plainToInstance(
+        PermissionResponseDto,
+        permissions,
+      ) as unknown as PermissionResponseDto[],
+    );
+  }
+
+  @Post('permissions')
+  @ApiOperation({ summary: 'Create a new permission' })
+  async createPermission(
+    @Body()
+    data: {
+      name: string;
+      description?: string;
+      resource: string;
+      action: string;
+    },
+  ): Promise<ApiResponse<PermissionResponseDto>> {
+    const permission = await this.prisma.permission.create({ data });
+    await this.cacheManager.del('permissions_list');
+    return createSuccessResponse(
+      plainToInstance(PermissionResponseDto, permission),
+      'Permission created',
+      201,
+    );
+  }
+
+  @Post('roles/:roleId/permissions/:permissionId')
+  @ApiOperation({ summary: 'Assign permission to role' })
+  async assignPermission(
+    @Param('roleId') roleId: string,
+    @Param('permissionId') permissionId: string,
+  ): Promise<ApiResponse<RolePermissionResponseDto>> {
+    const rolePermission = await this.prisma.rolePermission.create({
+      data: { roleId, permissionId },
+    });
+    // Invalidate roles_list because permissions are nested in roles
+    await this.cacheManager.del('roles_list');
+    return createSuccessResponse(
+      plainToInstance(RolePermissionResponseDto, rolePermission),
+      'Permission assigned to role',
+    );
+  }
+
+  @Delete('roles/:roleId/permissions/:permissionId')
+  @ApiOperation({ summary: 'Remove permission from role' })
+  async removePermission(
+    @Param('roleId') roleId: string,
+    @Param('permissionId') permissionId: string,
+  ): Promise<ApiResponse<null>> {
+    await this.prisma.rolePermission.deleteMany({
+      where: { roleId, permissionId },
+    });
+    // Invalidate roles_list because permissions are nested in roles
+    await this.cacheManager.del('roles_list');
+    return createSuccessResponse(null, 'Permission removed from role');
+  }
+}

src/modules/admin/admin.module.ts

@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { AdminController } from './admin.controller';
+
+@Module({
+  controllers: [AdminController],
+})
+export class AdminModule {}

src/modules/admin/dto/admin.dto.ts

@@ -0,0 +1,71 @@
+import { Exclude, Expose, Type } from 'class-transformer';
+
+@Exclude()
+export class PermissionResponseDto {
+  @Expose()
+  id: string;
+
+  @Expose()
+  name: string;
+
+  @Expose()
+  description: string | null;
+
+  @Expose()
+  resource: string;
+
+  @Expose()
+  action: string;
+
+  @Expose()
+  createdAt: Date;
+
+  @Expose()
+  updatedAt: Date;
+}
+
+@Exclude()
+export class RoleResponseDto {
+  @Expose()
+  id: string;
+
+  @Expose()
+  name: string;
+
+  @Expose()
+  description: string | null;
+
+  @Expose()
+  @Type(() => PermissionResponseDto)
+  permissions?: PermissionResponseDto[];
+
+  @Expose()
+  createdAt: Date;
+
+  @Expose()
+  updatedAt: Date;
+}
+
+@Exclude()
+export class UserRoleResponseDto {
+  @Expose()
+  userId: string;
+
+  @Expose()
+  roleId: string;
+
+  @Expose()
+  createdAt: Date;
+}
+
+@Exclude()
+export class RolePermissionResponseDto {
+  @Expose()
+  roleId: string;
+
+  @Expose()
+  permissionId: string;
+
+  @Expose()
+  createdAt: Date;
+}

src/modules/auth/auth.controller.ts

@@ -0,0 +1,78 @@
+import { Controller, Post, Body, HttpCode } from '@nestjs/common';
+import { I18n, I18nContext } from 'nestjs-i18n';
+import { ApiTags, ApiOperation, ApiOkResponse } from '@nestjs/swagger';
+import { AuthService } from './auth.service';
+import {
+  RegisterDto,
+  LoginDto,
+  RefreshTokenDto,
+  TokenResponseDto,
+} from './dto/auth.dto';
+import { Public } from '../../common/decorators';
+import {
+  ApiResponse,
+  createSuccessResponse,
+} from '../../common/types/api-response.type';
+
+@ApiTags('Auth')
+@Controller('auth')
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  @Post('register')
+  @Public()
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Register a new user' })
+  @ApiOkResponse({
+    description: 'User registered successfully',
+    type: TokenResponseDto,
+  })
+  async register(
+    @Body() dto: RegisterDto,
+    @I18n() i18n: I18nContext,
+  ): Promise<ApiResponse<TokenResponseDto>> {
+    const result = await this.authService.register(dto);
+    return createSuccessResponse(result, i18n.t('auth.registered'), 201);
+  }
+
+  @Post('login')
+  @Public()
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Login with email and password' })
+  @ApiOkResponse({ description: 'Login successful', type: TokenResponseDto })
+  async login(
+    @Body() dto: LoginDto,
+    @I18n() i18n: I18nContext,
+  ): Promise<ApiResponse<TokenResponseDto>> {
+    const result = await this.authService.login(dto);
+    return createSuccessResponse(result, i18n.t('auth.login_success'));
+  }
+
+  @Post('refresh')
+  @Public()
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Refresh access token' })
+  @ApiOkResponse({
+    description: 'Token refreshed successfully',
+    type: TokenResponseDto,
+  })
+  async refreshToken(
+    @Body() dto: RefreshTokenDto,
+    @I18n() i18n: I18nContext,
+  ): Promise<ApiResponse<TokenResponseDto>> {
+    const result = await this.authService.refreshToken(dto.refreshToken);
+    return createSuccessResponse(result, i18n.t('auth.refresh_success'));
+  }
+
+  @Post('logout')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Logout and invalidate refresh token' })
+  @ApiOkResponse({ description: 'Logout successful' })
+  async logout(
+    @Body() dto: RefreshTokenDto,
+    @I18n() i18n: I18nContext,
+  ): Promise<ApiResponse<null>> {
+    await this.authService.logout(dto.refreshToken);
+    return createSuccessResponse(null, i18n.t('auth.logout_success'));
+  }
+}

src/modules/auth/auth.module.ts

@@ -0,0 +1,37 @@
+import { Module } from '@nestjs/common';
+import { JwtModule, JwtModuleOptions } from '@nestjs/jwt';
+import { PassportModule } from '@nestjs/passport';
+import { ConfigService } from '@nestjs/config';
+import { AuthController } from './auth.controller';
+import { AuthService } from './auth.service';
+import { JwtStrategy } from './strategies/jwt.strategy';
+import { JwtAuthGuard, RolesGuard, PermissionsGuard } from './guards';
+
+@Module({
+  imports: [
+    PassportModule.register({ defaultStrategy: 'jwt' }),
+    JwtModule.registerAsync({
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService): JwtModuleOptions => {
+        const expiresIn =
+          configService.get<string>('JWT_ACCESS_EXPIRATION') || '15m';
+        return {
+          secret: configService.get<string>('JWT_SECRET'),
+          signOptions: {
+            expiresIn: expiresIn as any,
+          },
+        };
+      },
+    }),
+  ],
+  controllers: [AuthController],
+  providers: [
+    AuthService,
+    JwtStrategy,
+    JwtAuthGuard,
+    RolesGuard,
+    PermissionsGuard,
+  ],
+  exports: [AuthService, JwtAuthGuard, RolesGuard, PermissionsGuard],
+})
+export class AuthModule {}

src/modules/auth/auth.service.ts

@@ -0,0 +1,336 @@
+import {
+  Injectable,
+  UnauthorizedException,
+  ConflictException,
+} from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { ConfigService } from '@nestjs/config';
+import * as bcrypt from 'bcrypt';
+import * as crypto from 'crypto';
+import { PrismaService } from '../../database/prisma.service';
+import { RegisterDto, LoginDto, TokenResponseDto } from './dto/auth.dto';
+
+export interface JwtPayload {
+  sub: string;
+  email: string;
+  roles: string[];
+  permissions: string[];
+  tenantId?: string;
+}
+
+interface UserWithRoles {
+  id: string;
+  email: string;
+  password: string;
+  firstName: string | null;
+  lastName: string | null;
+  isActive: boolean;
+  tenantId: string | null;
+  roles: Array<{
+    role: {
+      name: string;
+      permissions: Array<{
+        permission: {
+          name: string;
+        };
+      }>;
+    };
+  }>;
+}
+
+@Injectable()
+export class AuthService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly jwtService: JwtService,
+    private readonly configService: ConfigService,
+  ) {}
+
+  /**
+   * Register a new user
+   */
+  async register(dto: RegisterDto): Promise<TokenResponseDto> {
+    // Check if email already exists
+    const existingUser = await this.prisma.user.findUnique({
+      where: { email: dto.email },
+    });
+
+    if (existingUser) {
+      throw new ConflictException('EMAIL_ALREADY_EXISTS');
+    }
+
+    // Hash password
+    const hashedPassword = await this.hashPassword(dto.password);
+
+    // Create user with default role
+    const user = await this.prisma.user.create({
+      data: {
+        email: dto.email,
+        password: hashedPassword,
+        firstName: dto.firstName,
+        lastName: dto.lastName,
+        roles: {
+          create: {
+            role: {
+              connectOrCreate: {
+                where: { name: 'user' },
+                create: { name: 'user', description: 'Default user role' },
+              },
+            },
+          },
+        },
+      },
+      include: {
+        roles: {
+          include: {
+            role: {
+              include: {
+                permissions: {
+                  include: {
+                    permission: true,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    return this.generateTokens(user as unknown as UserWithRoles);
+  }
+
+  /**
+   * Login with email and password
+   */
+  async login(dto: LoginDto): Promise<TokenResponseDto> {
+    // Find user by email
+    const user = await this.prisma.user.findUnique({
+      where: { email: dto.email },
+      include: {
+        roles: {
+          include: {
+            role: {
+              include: {
+                permissions: {
+                  include: {
+                    permission: true,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (!user) {
+      throw new UnauthorizedException('INVALID_CREDENTIALS');
+    }
+
+    // Verify password
+    const isPasswordValid = await this.comparePassword(
+      dto.password,
+      user.password,
+    );
+
+    if (!isPasswordValid) {
+      throw new UnauthorizedException('INVALID_CREDENTIALS');
+    }
+
+    if (!user.isActive) {
+      throw new UnauthorizedException('ACCOUNT_DISABLED');
+    }
+
+    return this.generateTokens(user as unknown as UserWithRoles);
+  }
+
+  /**
+   * Refresh access token using refresh token
+   */
+  async refreshToken(refreshToken: string): Promise<TokenResponseDto> {
+    // Find refresh token
+    const storedToken = await this.prisma.refreshToken.findUnique({
+      where: { token: refreshToken },
+      include: {
+        user: {
+          include: {
+            roles: {
+              include: {
+                role: {
+                  include: {
+                    permissions: {
+                      include: {
+                        permission: true,
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (!storedToken) {
+      throw new UnauthorizedException('INVALID_REFRESH_TOKEN');
+    }
+
+    if (storedToken.expiresAt < new Date()) {
+      // Delete expired token
+      await this.prisma.refreshToken.delete({
+        where: { id: storedToken.id },
+      });
+      throw new UnauthorizedException('INVALID_REFRESH_TOKEN');
+    }
+
+    // Delete old refresh token
+    await this.prisma.refreshToken.delete({
+      where: { id: storedToken.id },
+    });
+
+    return this.generateTokens(storedToken.user as unknown as UserWithRoles);
+  }
+
+  /**
+   * Logout - invalidate refresh token
+   */
+  async logout(refreshToken: string): Promise<void> {
+    await this.prisma.refreshToken.deleteMany({
+      where: { token: refreshToken },
+    });
+  }
+
+  /**
+   * Validate user by ID (used by JWT strategy)
+   */
+  async validateUser(userId: string) {
+    const user = await this.prisma.user.findUnique({
+      where: { id: userId },
+      include: {
+        roles: {
+          include: {
+            role: {
+              include: {
+                permissions: {
+                  include: {
+                    permission: true,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (!user || !user.isActive) {
+      return null;
+    }
+
+    // Remove password from user object
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { password: _, ...result } = user;
+    return result;
+  }
+
+  /**
+   * Generate access and refresh tokens
+   */
+  private async generateTokens(user: UserWithRoles): Promise<TokenResponseDto> {
+    // Extract roles and permissions
+    const roles = user.roles.map((ur) => ur.role.name);
+    const permissions = user.roles.flatMap((ur) =>
+      ur.role.permissions.map((rp) => rp.permission.name),
+    );
+
+    const payload: JwtPayload = {
+      sub: user.id,
+      email: user.email,
+      roles,
+      permissions,
+      tenantId: user.tenantId || undefined,
+    };
+
+    // Generate access token
+    const accessToken = this.jwtService.sign(payload, {
+      expiresIn: this.configService.get('JWT_ACCESS_EXPIRATION', '15m'),
+    });
+
+    // Generate refresh token
+    const refreshTokenValue = crypto.randomUUID();
+    const refreshExpiration = this.parseExpiration(
+      this.configService.get('JWT_REFRESH_EXPIRATION', '7d'),
+    );
+
+    // Store refresh token
+    await this.prisma.refreshToken.create({
+      data: {
+        token: refreshTokenValue,
+        userId: user.id,
+        expiresAt: new Date(Date.now() + refreshExpiration),
+      },
+    });
+
+    return {
+      accessToken,
+      refreshToken: refreshTokenValue,
+      expiresIn:
+        this.parseExpiration(
+          this.configService.get('JWT_ACCESS_EXPIRATION', '15m'),
+        ) / 1000, // Convert to seconds
+      user: {
+        id: user.id,
+        email: user.email,
+        firstName: user.firstName || undefined,
+        lastName: user.lastName || undefined,
+        roles,
+      },
+    };
+  }
+
+  /**
+   * Hash password using bcrypt
+   */
+  private async hashPassword(password: string): Promise<string> {
+    const saltRounds = 12;
+    return bcrypt.hash(password, saltRounds);
+  }
+
+  /**
+   * Compare password with hash
+   */
+  private async comparePassword(
+    password: string,
+    hashedPassword: string,
+  ): Promise<boolean> {
+    return bcrypt.compare(password, hashedPassword);
+  }
+
+  /**
+   * Parse expiration string to milliseconds
+   */
+  private parseExpiration(expiration: string): number {
+    const match = expiration.match(/^(\d+)([smhd])$/);
+    if (!match) {
+      return 15 * 60 * 1000; // Default 15 minutes
+    }
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+
+    switch (unit) {
+      case 's':
+        return value * 1000;
+      case 'm':
+        return value * 60 * 1000;
+      case 'h':
+        return value * 60 * 60 * 1000;
+      case 'd':
+        return value * 24 * 60 * 60 * 1000;
+      default:
+        return 15 * 60 * 1000;
+    }
+  }
+}

src/modules/auth/dto/auth.dto.ts

@@ -0,0 +1,70 @@
+import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class RegisterDto {
+  @ApiProperty({ example: 'user@example.com' })
+  @IsEmail()
+  email: string;
+
+  @ApiProperty({ example: 'password123', minLength: 8 })
+  @IsString()
+  @MinLength(8)
+  password: string;
+
+  @ApiPropertyOptional({ example: 'John' })
+  @IsOptional()
+  @IsString()
+  firstName?: string;
+
+  @ApiPropertyOptional({ example: 'Doe' })
+  @IsOptional()
+  @IsString()
+  lastName?: string;
+}
+
+export class LoginDto {
+  @ApiProperty({ example: 'user@example.com' })
+  @IsEmail()
+  email: string;
+
+  @ApiProperty({ example: 'password123' })
+  @IsString()
+  password: string;
+}
+
+export class RefreshTokenDto {
+  @ApiProperty()
+  @IsString()
+  refreshToken: string;
+}
+
+export class UserInfoDto {
+  @ApiProperty()
+  id: string;
+
+  @ApiProperty()
+  email: string;
+
+  @ApiProperty({ required: false })
+  firstName?: string;
+
+  @ApiProperty({ required: false })
+  lastName?: string;
+
+  @ApiProperty()
+  roles: string[];
+}
+
+export class TokenResponseDto {
+  @ApiProperty()
+  accessToken: string;
+
+  @ApiProperty()
+  refreshToken: string;
+
+  @ApiProperty()
+  expiresIn: number;
+
+  @ApiProperty({ type: UserInfoDto })
+  user: UserInfoDto;
+}

src/modules/auth/guards/auth.guards.ts

@@ -0,0 +1,129 @@
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  UnauthorizedException,
+  ForbiddenException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { AuthGuard } from '@nestjs/passport';
+import { Request } from 'express';
+import {
+  IS_PUBLIC_KEY,
+  ROLES_KEY,
+  PERMISSIONS_KEY,
+} from '../../../common/decorators';
+
+interface AuthenticatedUser {
+  id: string;
+  email: string;
+  roles: string[];
+  permissions: string[];
+}
+
+/**
+ * JWT Auth Guard - Validates JWT token
+ */
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  constructor(private reflector: Reflector) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    // Check if route is public
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isPublic) {
+      return true;
+    }
+
+    return super.canActivate(context);
+  }
+
+  handleRequest<TUser = AuthenticatedUser>(
+    err: Error | null,
+    user: TUser | false,
+    info: any,
+  ): TUser {
+    if (err || !user) {
+      if (info?.name === 'TokenExpiredError') {
+        throw new UnauthorizedException('TOKEN_EXPIRED');
+      }
+      throw err || new UnauthorizedException('AUTH_REQUIRED');
+    }
+    return user;
+  }
+}
+
+/**
+ * Roles Guard - Check if user has required roles
+ */
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<string[]>(
+      ROLES_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!requiredRoles || requiredRoles.length === 0) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<Request>();
+    const user = request.user as AuthenticatedUser | undefined;
+
+    if (!user || !user.roles) {
+      return false;
+    }
+
+    const hasRole = requiredRoles.some((role) => user.roles.includes(role));
+    if (!hasRole) {
+      throw new ForbiddenException('PERMISSION_DENIED');
+    }
+
+    return true;
+  }
+}
+
+/**
+ * Permissions Guard - Check if user has required permissions
+ */
+@Injectable()
+export class PermissionsGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredPermissions = this.reflector.getAllAndOverride<string[]>(
+      PERMISSIONS_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!requiredPermissions || requiredPermissions.length === 0) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<Request>();
+    const user = request.user as AuthenticatedUser | undefined;
+
+    if (!user || !user.permissions) {
+      return false;
+    }
+
+    const hasPermission = requiredPermissions.every((permission) =>
+      user.permissions.includes(permission),
+    );
+
+    if (!hasPermission) {
+      throw new ForbiddenException('PERMISSION_DENIED');
+    }
+
+    return true;
+  }
+}

src/modules/auth/guards/index.ts

@@ -0,0 +1 @@
+export * from './auth.guards';

src/modules/auth/strategies/jwt.strategy.ts

@@ -0,0 +1,38 @@
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+import { ConfigService } from '@nestjs/config';
+import { AuthService, JwtPayload } from '../auth.service';
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(
+    private readonly configService: ConfigService,
+    private readonly authService: AuthService,
+  ) {
+    const secret = configService.get<string>('JWT_SECRET');
+    if (!secret) {
+      throw new Error('JWT_SECRET is not defined');
+    }
+
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: secret,
+    });
+  }
+
+  async validate(payload: JwtPayload) {
+    const user = await this.authService.validateUser(payload.sub);
+
+    if (!user) {
+      return null;
+    }
+
+    return {
+      ...user,
+      roles: payload.roles,
+      permissions: payload.permissions,
+    };
+  }
+}

src/modules/gemini/gemini.config.ts

@@ -0,0 +1,7 @@
+import { registerAs } from '@nestjs/config';
+
+export const geminiConfig = registerAs('gemini', () => ({
+  enabled: process.env.ENABLE_GEMINI === 'true',
+  apiKey: process.env.GOOGLE_API_KEY,
+  defaultModel: process.env.GEMINI_MODEL || 'gemini-2.5-flash',
+}));

src/modules/gemini/gemini.module.ts

@@ -0,0 +1,18 @@
+import { Module, Global } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { GeminiService } from './gemini.service';
+import { geminiConfig } from './gemini.config';
+
+/**
+ * Gemini AI Module
+ *
+ * Optional module for AI-powered features using Google Gemini API.
+ * Enable by setting ENABLE_GEMINI=true in your .env file.
+ */
+@Global()
+@Module({
+  imports: [ConfigModule.forFeature(geminiConfig)],
+  providers: [GeminiService],
+  exports: [GeminiService],
+})
+export class GeminiModule {}

src/modules/gemini/gemini.service.ts

@@ -0,0 +1,240 @@
+import { Injectable, OnModuleInit, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { GoogleGenAI } from '@google/genai';
+
+export interface GeminiGenerateOptions {
+  model?: string;
+  systemPrompt?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface GeminiChatMessage {
+  role: 'user' | 'model';
+  content: string;
+}
+
+/**
+ * Gemini AI Service
+ *
+ * Provides AI-powered text generation using Google Gemini API.
+ * This service is globally available when ENABLE_GEMINI=true.
+ *
+ * @example
+ * ```typescript
+ * // Simple text generation
+ * const response = await geminiService.generateText('Write a poem about coding');
+ *
+ * // With options
+ * const response = await geminiService.generateText('Translate to Turkish', {
+ *   temperature: 0.7,
+ *   systemPrompt: 'You are a professional translator',
+ * });
+ *
+ * // Chat conversation
+ * const messages = [
+ *   { role: 'user', content: 'Hello!' },
+ *   { role: 'model', content: 'Hi there!' },
+ *   { role: 'user', content: 'What is 2+2?' },
+ * ];
+ * const response = await geminiService.chat(messages);
+ * ```
+ */
+@Injectable()
+export class GeminiService implements OnModuleInit {
+  private readonly logger = new Logger(GeminiService.name);
+  private client: GoogleGenAI | null = null;
+  private isEnabled = false;
+  private defaultModel: string;
+
+  constructor(private readonly configService: ConfigService) {
+    this.isEnabled = this.configService.get<boolean>('gemini.enabled', false);
+    this.defaultModel = this.configService.get<string>(
+      'gemini.defaultModel',
+      'gemini-2.5-flash',
+    );
+  }
+
+  onModuleInit() {
+    if (!this.isEnabled) {
+      this.logger.log(
+        'Gemini AI is disabled. Set ENABLE_GEMINI=true to enable.',
+      );
+      return;
+    }
+
+    const apiKey = this.configService.get<string>('gemini.apiKey');
+    if (!apiKey) {
+      this.logger.warn(
+        'GOOGLE_API_KEY is not set. Gemini features will not work.',
+      );
+      return;
+    }
+
+    try {
+      this.client = new GoogleGenAI({ apiKey });
+      this.logger.log('✅ Gemini AI initialized successfully');
+    } catch (error) {
+      this.logger.error('Failed to initialize Gemini AI', error);
+    }
+  }
+
+  /**
+   * Check if Gemini is available and properly configured
+   */
+  isAvailable(): boolean {
+    return this.isEnabled && this.client !== null;
+  }
+
+  /**
+   * Generate text content from a prompt
+   *
+   * @param prompt - The text prompt to send to the AI
+   * @param options - Optional configuration for the generation
+   * @returns Generated text response
+   */
+  async generateText(
+    prompt: string,
+    options: GeminiGenerateOptions = {},
+  ): Promise<{ text: string; usage?: any }> {
+    if (!this.isAvailable()) {
+      throw new Error('Gemini AI is not available. Check your configuration.');
+    }
+
+    const model = options.model || this.defaultModel;
+
+    try {
+      const contents: any[] = [];
+
+      // Add system prompt if provided
+      if (options.systemPrompt) {
+        contents.push({
+          role: 'user',
+          parts: [{ text: options.systemPrompt }],
+        });
+        contents.push({
+          role: 'model',
+          parts: [{ text: 'Understood. I will follow these instructions.' }],
+        });
+      }
+
+      contents.push({
+        role: 'user',
+        parts: [{ text: prompt }],
+      });
+
+      const response = await this.client!.models.generateContent({
+        model,
+        contents,
+        config: {
+          temperature: options.temperature,
+          maxOutputTokens: options.maxTokens,
+        },
+      });
+
+      return {
+        text: (response.text || '').trim(),
+        usage: response.usageMetadata,
+      };
+    } catch (error) {
+      this.logger.error('Gemini generation failed', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Have a multi-turn chat conversation
+   *
+   * @param messages - Array of chat messages
+   * @param options - Optional configuration for the generation
+   * @returns Generated text response
+   */
+  async chat(
+    messages: GeminiChatMessage[],
+    options: GeminiGenerateOptions = {},
+  ): Promise<{ text: string; usage?: any }> {
+    if (!this.isAvailable()) {
+      throw new Error('Gemini AI is not available. Check your configuration.');
+    }
+
+    const model = options.model || this.defaultModel;
+
+    try {
+      const contents = messages.map((msg) => ({
+        role: msg.role,
+        parts: [{ text: msg.content }],
+      }));
+
+      // Prepend system prompt if provided
+      if (options.systemPrompt) {
+        contents.unshift(
+          {
+            role: 'user',
+            parts: [{ text: options.systemPrompt }],
+          },
+          {
+            role: 'model',
+            parts: [{ text: 'Understood. I will follow these instructions.' }],
+          },
+        );
+      }
+
+      const response = await this.client!.models.generateContent({
+        model,
+        contents,
+        config: {
+          temperature: options.temperature,
+          maxOutputTokens: options.maxTokens,
+        },
+      });
+
+      return {
+        text: (response.text || '').trim(),
+        usage: response.usageMetadata,
+      };
+    } catch (error) {
+      this.logger.error('Gemini chat failed', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Generate structured JSON output
+   *
+   * @param prompt - The prompt describing what JSON to generate
+   * @param schema - JSON schema description for the expected output
+   * @param options - Optional configuration for the generation
+   * @returns Parsed JSON object
+   */
+  async generateJSON<T = any>(
+    prompt: string,
+    schema: string,
+    options: GeminiGenerateOptions = {},
+  ): Promise<{ data: T; usage?: any }> {
+    const fullPrompt = `${prompt}
+
+Output the result as valid JSON that matches this schema:
+${schema}
+
+IMPORTANT: Only output valid JSON, no markdown code blocks or other text.`;
+
+    const response = await this.generateText(fullPrompt, options);
+
+    try {
+      // Try to extract JSON from the response
+      let jsonStr = response.text;
+
+      // Remove potential markdown code blocks
+      const jsonMatch = jsonStr.match(/```(?:json)?\s*([\s\S]*?)```/);
+      if (jsonMatch) {
+        jsonStr = jsonMatch[1].trim();
+      }
+
+      const data = JSON.parse(jsonStr) as T;
+      return { data, usage: response.usage };
+    } catch (error) {
+      this.logger.error('Failed to parse JSON response', error);
+      throw new Error('Failed to parse AI response as JSON');
+    }
+  }
+}

src/modules/gemini/index.ts

@@ -0,0 +1,3 @@
+export * from './gemini.module';
+export * from './gemini.service';
+export * from './gemini.config';