create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/product/data/roi-calculation-guide.md

@@ -0,0 +1,142 @@
+# ROI Calculation Guide
+
+**Purpose:** How to calculate real cost savings from design system
+**Agent:** Brad / Design System
+**Method:** Pattern-weighted cost analysis
+
+---
+
+## Formula Base
+
+```python
+monthly_cost = patterns × hours_per_pattern × hourly_rate
+
+annual_savings = (cost_before - cost_after) × 12
+
+roi_ratio = annual_savings / implementation_cost
+```
+
+---
+
+## Pattern Weights (Critical!)
+
+**Problem:** Not all patterns cost the same to maintain.
+
+**Solution:** Weight by complexity and change frequency.
+
+```python
+pattern_weights = {
+    'button': 1.0,        # Baseline (2h/month)
+    'input': 1.5,         # Validation logic
+    'form': 4.0,          # Complex state, validation
+    'modal': 2.0,         # Overlay logic, accessibility
+    'dropdown': 2.5,      # Complex interactions
+    'card': 0.8,          # Mostly layout
+    'color': 0.2,         # Trivial (just CSS)
+    'spacing': 0.3,       # Low complexity
+    'typography': 0.5,    # Medium complexity
+}
+
+weighted_hours = sum(
+    pattern_count × weight × base_hours
+    for pattern, count in patterns.items()
+)
+```
+
+---
+
+## Example Calculation
+
+### Before Consolidation
+
+```yaml
+patterns:
+  buttons: 47 × 1.0 = 47 units
+  inputs: 23 × 1.5 = 34.5 units
+  forms: 12 × 4.0 = 48 units
+  colors: 89 × 0.2 = 17.8 units
+  spacing: 19 × 0.3 = 5.7 units
+
+total_units: 153 units
+hours_per_unit: 2h/month
+monthly_hours: 306h
+hourly_rate: $150/h
+monthly_cost: $45,900
+annual_cost: $550,800
+```
+
+### After Consolidation
+
+```yaml
+patterns:
+  buttons: 3 × 1.0 = 3 units
+  inputs: 5 × 1.5 = 7.5 units
+  forms: 3 × 4.0 = 12 units
+  colors: 12 × 0.2 = 2.4 units
+  spacing: 7 × 0.3 = 2.1 units
+
+total_units: 27 units
+monthly_hours: 54h
+monthly_cost: $8,100
+annual_cost: $97,200
+```
+
+### Savings
+
+```yaml
+monthly_savings: $37,800
+annual_savings: $453,600
+
+implementation_cost: $15,000
+
+roi_ratio: 30.2x
+breakeven: 0.4 months (12 days)
+```
+
+---
+
+## Conservative vs Aggressive Estimates
+
+### Conservative (Recommended)
+
+- Base hours: 2h/month
+- Hourly rate: $150/h
+- Include only direct maintenance (bugs, updates)
+
+### Aggressive
+
+- Base hours: 3h/month
+- Include code reviews, discussions, decision time
+- Include opportunity cost of inconsistency
+
+**Brad recommends:** Use conservative numbers for stakeholders.
+
+---
+
+## Beyond Direct Cost
+
+### Velocity Impact
+
+```python
+feature_velocity_multiplier = 3-6x
+
+# Conservative estimate: 4x
+time_saved_per_feature = 75%  # 16h → 4h
+
+features_per_sprint = baseline_features × 4
+```
+
+### Quality Improvements
+
+- Fewer bugs (consistent patterns)
+- Better accessibility (system enforces WCAG)
+- Easier onboarding (single source of truth)
+
+**Hard to quantify but real value.**
+
+---
+
+## Brad says:
+
+"Conservative ROI = credible ROI.
+Underpromise, overdeliver."

package/template/.aiox-core/product/data/supabase-patterns.md

@@ -0,0 +1,330 @@
+# Supabase Architecture Patterns
+
+**Purpose:** Reference guide for Supabase implementation patterns
+**Agent:** Dan (Data Engineer)
+**Platform:** Supabase (PostgreSQL + Auth + Storage + Realtime)
+
+---
+
+## PROJECT STRUCTURE
+
+### Recommended Organization
+```
+project/
+├── supabase/
+│   ├── migrations/         # Database migrations
+│   │   ├── 00001_initial_schema.sql
+│   │   └── 00002_add_rls_policies.sql
+│   ├── functions/          # Edge Functions
+│   │   └── function-name/
+│   │       └── index.ts
+│   ├── seed.sql            # Seed data for development
+│   └── config.toml         # Supabase CLI config
+├── src/
+│   ├── lib/
+│   │   └── supabase.ts     # Supabase client initialization
+│   └── types/
+│       └── database.ts     # Generated types from schema
+└── .env.local              # Environment variables
+```
+
+---
+
+## CLIENT INITIALIZATION
+
+### Browser Client (Public)
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '@/types/database'
+
+export const supabase = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+)
+```
+
+### Server Client (Service Role)
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '@/types/database'
+
+// Only use server-side, never expose to client
+export const supabaseAdmin = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  {
+    auth: {
+      autoRefreshToken: false,
+      persistSession: false
+    }
+  }
+)
+```
+
+---
+
+## AUTHENTICATION PATTERNS
+
+### Sign Up with Email
+```typescript
+const { data, error } = await supabase.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password',
+  options: {
+    data: {
+      full_name: 'User Name',
+      // Additional user metadata
+    }
+  }
+})
+```
+
+### Sign In
+```typescript
+const { data, error } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password'
+})
+```
+
+### OAuth Provider
+```typescript
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: 'github',
+  options: {
+    redirectTo: `${window.location.origin}/auth/callback`
+  }
+})
+```
+
+### Session Management
+```typescript
+// Get current session
+const { data: { session } } = await supabase.auth.getSession()
+
+// Listen to auth changes
+supabase.auth.onAuthStateChange((event, session) => {
+  if (event === 'SIGNED_IN') {
+    // Handle sign in
+  } else if (event === 'SIGNED_OUT') {
+    // Handle sign out
+  }
+})
+```
+
+---
+
+## DATABASE PATTERNS
+
+### Type-Safe Queries
+```typescript
+// Fetch with type safety
+const { data, error } = await supabase
+  .from('profiles')
+  .select('id, username, avatar_url')
+  .eq('id', userId)
+  .single()
+
+// Insert with return
+const { data, error } = await supabase
+  .from('posts')
+  .insert({ title, content, author_id: userId })
+  .select()
+  .single()
+
+// Update
+const { data, error } = await supabase
+  .from('profiles')
+  .update({ username: newUsername })
+  .eq('id', userId)
+  .select()
+  .single()
+
+// Delete
+const { error } = await supabase
+  .from('posts')
+  .delete()
+  .eq('id', postId)
+```
+
+### Relationships
+```typescript
+// Fetch with foreign key relation
+const { data, error } = await supabase
+  .from('posts')
+  .select(`
+    id,
+    title,
+    content,
+    author:profiles(id, username, avatar_url)
+  `)
+  .eq('id', postId)
+  .single()
+```
+
+### Pagination
+```typescript
+const pageSize = 10
+const page = 1
+
+const { data, count, error } = await supabase
+  .from('posts')
+  .select('*', { count: 'exact' })
+  .order('created_at', { ascending: false })
+  .range((page - 1) * pageSize, page * pageSize - 1)
+```
+
+---
+
+## REALTIME PATTERNS
+
+### Subscribe to Changes
+```typescript
+const channel = supabase
+  .channel('posts-changes')
+  .on(
+    'postgres_changes',
+    {
+      event: '*',
+      schema: 'public',
+      table: 'posts',
+      filter: `author_id=eq.${userId}`
+    },
+    (payload) => {
+      console.log('Change received:', payload)
+    }
+  )
+  .subscribe()
+
+// Cleanup
+channel.unsubscribe()
+```
+
+### Presence (Online Status)
+```typescript
+const channel = supabase.channel('room:lobby')
+
+channel
+  .on('presence', { event: 'sync' }, () => {
+    const state = channel.presenceState()
+    console.log('Online users:', state)
+  })
+  .subscribe(async (status) => {
+    if (status === 'SUBSCRIBED') {
+      await channel.track({ user_id: userId, online_at: new Date() })
+    }
+  })
+```
+
+---
+
+## STORAGE PATTERNS
+
+### Upload File
+```typescript
+const { data, error } = await supabase.storage
+  .from('avatars')
+  .upload(`${userId}/avatar.png`, file, {
+    cacheControl: '3600',
+    upsert: true
+  })
+```
+
+### Get Public URL
+```typescript
+const { data } = supabase.storage
+  .from('avatars')
+  .getPublicUrl(`${userId}/avatar.png`)
+
+const publicUrl = data.publicUrl
+```
+
+### Signed URL (Private)
+```typescript
+const { data, error } = await supabase.storage
+  .from('private-docs')
+  .createSignedUrl(`${userId}/document.pdf`, 3600) // 1 hour
+```
+
+---
+
+## EDGE FUNCTIONS
+
+### Function Structure
+```typescript
+// supabase/functions/hello-world/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+serve(async (req) => {
+  const supabaseClient = createClient(
+    Deno.env.get('SUPABASE_URL') ?? '',
+    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
+    {
+      global: {
+        headers: { Authorization: req.headers.get('Authorization')! }
+      }
+    }
+  )
+
+  // Get user from JWT
+  const { data: { user } } = await supabaseClient.auth.getUser()
+
+  return new Response(
+    JSON.stringify({ message: `Hello ${user?.email}` }),
+    { headers: { 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+---
+
+## TYPE GENERATION
+
+### Generate Types from Schema
+```bash
+# Install Supabase CLI
+npm install -g supabase
+
+# Generate types
+supabase gen types typescript --project-id your-project-id > src/types/database.ts
+
+# Or from local
+supabase gen types typescript --local > src/types/database.ts
+```
+
+### Usage
+```typescript
+import type { Database } from '@/types/database'
+
+type Profile = Database['public']['Tables']['profiles']['Row']
+type InsertProfile = Database['public']['Tables']['profiles']['Insert']
+type UpdateProfile = Database['public']['Tables']['profiles']['Update']
+```
+
+---
+
+## ERROR HANDLING
+
+### Standard Pattern
+```typescript
+async function fetchProfile(userId: string) {
+  const { data, error } = await supabase
+    .from('profiles')
+    .select('*')
+    .eq('id', userId)
+    .single()
+
+  if (error) {
+    console.error('Error fetching profile:', error)
+    throw new Error(`Failed to fetch profile: ${error.message}`)
+  }
+
+  return data
+}
+```
+
+---
+
+**Reviewer:** ________ **Date:** ________
+**Quality Gate:** [ ] PASS [ ] NEEDS REVIEW

package/template/.aiox-core/product/data/test-levels-framework.md

@@ -0,0 +1,149 @@
+<!-- Powered by AIOX™ Core -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+