@smicolon/ai-kit 0.3.1 → 0.4.0

package/packs/django/skills/migration-safety-checker/SKILL.md

@@ -1,375 +0,0 @@
----
-name: migration-safety-checker
-description: This skill should be used when the user asks to "create a migration", "run makemigrations", "modify a model field", "rename a column", or mentions "schema change", "alter table", "database migration". Validates migrations are production-safe.
----
-
-# Migration Safety Checker
-
-Validates Django migrations are production-safe before they cause data loss.
-
-## Activation Triggers
-
-This skill activates when:
-- Running `makemigrations`
-- Modifying model fields
-- Mentioning "migration", "schema", "alter table"
-- Adding/removing/renaming fields
-- Changing field types
-- Creating or modifying migration files
-
-## Safety Requirements
-
-All migrations MUST be:
-- ✅ **Reversible** - Can roll back safely
-- ✅ **No data loss** - Preserve existing data
-- ✅ **Tested** - Run on staging first
-- ✅ **Safe for production** - No downtime operations
-- ✅ **Documented** - Explain what changes and why
-
-## High-Risk Operations
-
-These operations require special attention:
-
-### 🔴 CRITICAL RISK - Data Loss Possible
-
-1. **Dropping columns** without data migration
-2. **Renaming fields** without data migration
-3. **Changing field types** (data conversion issues)
-4. **Adding non-nullable fields** without default
-5. **Removing tables** with data
-
-### 🟡 MEDIUM RISK - Requires Careful Planning
-
-1. **Adding indexes** on large tables (use `CONCURRENTLY`)
-2. **Adding unique constraints** (check for duplicates first)
-3. **Changing `max_length`** (data truncation risk)
-
-### 🟢 LOW RISK - Generally Safe
-
-1. **Adding nullable fields**
-2. **Adding fields with defaults**
-3. **Creating new tables**
-4. **Adding non-unique indexes**
-
-## Validation Process
-
-### Step 1: Analyze Migration File
-
-When migration is created:
-
-```python
-# Generated migration
-class Migration(migrations.Migration):
-    operations = [
-        migrations.RemoveField(
-            model_name='user',
-            name='old_email',  # 🔴 DATA LOSS RISK!
-        ),
-    ]
-```
-
-### Step 2: Identify Risks
-
-Detect:
-- Operation type: `RemoveField`
-- Field: `old_email`
-- **Risk:** 🔴 CRITICAL - Dropping column loses data!
-
-### Step 3: Block Unsafe Migration
-
-> **⛔ UNSAFE MIGRATION DETECTED**
->
-> **Operation:** `RemoveField(model_name='user', name='old_email')`
->
-> **Risk:** 🔴 CRITICAL - Data loss!
->
-> **Problem:**
-> - Drops `old_email` column immediately
-> - All existing email data will be PERMANENTLY LOST
-> - Cannot be rolled back after data is gone
->
-> **Safe Approach:**
-> Use 3-step migration pattern:
-> 1. Data migration: Archive `old_email` data
-> 2. Wait for deployment
-> 3. Drop column in separate migration
->
-> Should I generate the safe migration sequence?
-
-### Step 4: Generate Safe Migration
-
-If user approves, create:
-
-```python
-# Migration 1: Archive data
-class Migration(migrations.Migration):
-    dependencies = [('users', '0001_initial')]
-
-    operations = [
-        migrations.RunPython(archive_old_emails, reverse_code=restore_old_emails),
-    ]
-
-def archive_old_emails(apps, schema_editor):
-    """Archive old_email data before dropping."""
-    User = apps.get_model('users', 'User')
-    EmailArchive = apps.get_model('users', 'EmailArchive')
-
-    for user in User.objects.all():
-        if user.old_email:
-            EmailArchive.objects.create(
-                user_id=user.id,
-                email=user.old_email
-            )
-
-def restore_old_emails(apps, schema_editor):
-    """Restore old_email data on rollback."""
-    User = apps.get_model('users', 'User')
-    EmailArchive = apps.get_model('users', 'EmailArchive')
-
-    for archive in EmailArchive.objects.all():
-        User.objects.filter(id=archive.user_id).update(
-            old_email=archive.email
-        )
-
-# Migration 2: Drop column (run after deployment)
-class Migration(migrations.Migration):
-    dependencies = [('users', '0002_archive_emails')]
-
-    operations = [
-        migrations.RemoveField(
-            model_name='user',
-            name='old_email',
-        ),
-    ]
-```
-
-## Safe Migration Patterns
-
-### Pattern 1: Renaming Field (3 Steps)
-
-**❌ UNSAFE:**
-```python
-operations = [
-    migrations.RenameField('user', 'email', 'email_address'),  # ❌ Risky!
-]
-```
-
-**✅ SAFE (3-Step):**
-```python
-# Step 1: Add new field
-operations = [
-    migrations.AddField('user', 'email_address',
-                       models.EmailField(null=True))
-]
-
-# Step 2: Data migration (copy old → new)
-operations = [
-    migrations.RunPython(copy_email_to_email_address)
-]
-
-# Step 3: Drop old field (separate deployment)
-operations = [
-    migrations.RemoveField('user', 'email')
-]
-```
-
-### Pattern 2: Changing Field Type (3 Steps)
-
-**❌ UNSAFE:**
-```python
-operations = [
-    migrations.AlterField('product', 'price',
-                         models.DecimalField(max_digits=10, decimal_places=2))
-]
-```
-
-**✅ SAFE:**
-```python
-# Step 1: Add new field with new type
-operations = [
-    migrations.AddField('product', 'price_decimal',
-                       models.DecimalField(max_digits=10, decimal_places=2, null=True))
-]
-
-# Step 2: Data migration (convert & copy)
-operations = [
-    migrations.RunPython(convert_price_to_decimal)
-]
-
-# Step 3: Drop old field, rename new field
-operations = [
-    migrations.RemoveField('product', 'price'),
-    migrations.RenameField('product', 'price_decimal', 'price')
-]
-```
-
-### Pattern 3: Adding Non-Nullable Field (2 Steps)
-
-**❌ UNSAFE:**
-```python
-operations = [
-    migrations.AddField('user', 'organization',
-                       models.ForeignKey('Organization'))  # ❌ No default!
-]
-```
-
-**✅ SAFE:**
-```python
-# Step 1: Add as nullable
-operations = [
-    migrations.AddField('user', 'organization',
-                       models.ForeignKey('Organization', null=True))
-]
-
-# Step 2: Populate + make non-nullable
-operations = [
-    migrations.RunPython(assign_default_organizations),
-    migrations.AlterField('user', 'organization',
-                         models.ForeignKey('Organization', null=False))
-]
-```
-
-### Pattern 4: Adding Unique Constraint (Check First)
-
-**❌ UNSAFE:**
-```python
-operations = [
-    migrations.AlterField('user', 'email',
-                         models.EmailField(unique=True))  # ❌ Fails if duplicates!
-]
-```
-
-**✅ SAFE:**
-```python
-# Step 1: Check for duplicates
-operations = [
-    migrations.RunPython(check_and_fix_duplicate_emails)
-]
-
-# Step 2: Add unique constraint
-operations = [
-    migrations.AlterField('user', 'email',
-                         models.EmailField(unique=True))
-]
-```
-
-## Production-Safe Practices
-
-### Use CONCURRENT Index Creation
-
-```python
-from django.db import migrations
-from django.contrib.postgres.operations import AddIndexConcurrently
-
-class Migration(migrations.Migration):
-    atomic = False  # Required for CONCURRENT operations
-
-    operations = [
-        AddIndexConcurrently(
-            model_name='user',
-            index=models.Index(fields=['email'], name='user_email_idx')
-        )
-    ]
-```
-
-### Data Migration Template
-
-```python
-def forward_migration(apps, schema_editor):
-    """
-    Safe data migration with batching.
-    """
-    Model = apps.get_model('app', 'Model')
-    batch_size = 1000
-
-    total = Model.objects.count()
-    for offset in range(0, total, batch_size):
-        batch = Model.objects.all()[offset:offset + batch_size]
-        for obj in batch:
-            # Transform data
-            obj.new_field = transform(obj.old_field)
-            obj.save(update_fields=['new_field'])
-
-def reverse_migration(apps, schema_editor):
-    """
-    Reverse the migration.
-    """
-    Model = apps.get_model('app', 'Model')
-    Model.objects.all().update(new_field=None)
-
-class Migration(migrations.Migration):
-    operations = [
-        migrations.RunPython(forward_migration, reverse_migration)
-    ]
-```
-
-## Migration Testing Checklist
-
-Before applying migration:
-
-- ✅ Run on copy of production database
-- ✅ Verify data integrity after migration
-- ✅ Test rollback works
-- ✅ Check migration duration (< 5 minutes ideal)
-- ✅ Review SQL with `sqlmigrate`
-- ✅ Confirm no downtime required
-- ✅ Have rollback plan ready
-
-## Validation Commands
-
-Suggest running:
-
-```bash
-# Review SQL before applying
-python manage.py sqlmigrate users 0002
-
-# Check for issues
-python manage.py makemigrations --check
-
-# Dry run
-python manage.py migrate --plan
-
-# Apply to staging first
-python manage.py migrate --database=staging
-```
-
-## Integration with CI/CD
-
-```yaml
-# .github/workflows/migrations.yml
-- name: Check migrations safety
-  run: |
-    python manage.py makemigrations --check --dry-run --no-input
-    python manage.py migrate --plan
-```
-
-## Success Criteria
-
-✅ No data loss migrations
-✅ All migrations tested on staging
-✅ Rollback plan exists
-✅ Large table migrations use CONCURRENT
-✅ Data migrations properly batched
-✅ Reversible migrations
-
-## Behavior
-
-**Proactive enforcement:**
-- Analyze migrations without being asked
-- Block unsafe migrations immediately
-- Suggest safe 3-step patterns
-- Generate data migration code
-- Explain WHY the migration is risky
-
-**Never:**
-- Allow data loss migrations
-- Let users skip safety checks
-- Apply migrations without review
-- Just warn without blocking unsafe operations
-
-**When migration is unsafe:**
-- Stop the process
-- Explain the risk
-- Provide safe alternative
-- Generate corrected migration code
-- User must acknowledge before proceeding

package/packs/django/skills/model-entity-validator/SKILL.md

@@ -1,298 +0,0 @@
----
-name: model-entity-validator
-description: This skill should be used when the user asks to "create a model", "add a Django model", "create database table", "add entity", "define schema", or when writing class definitions inheriting from models.Model. Validates BaseModel inheritance pattern.
----
-
-# Model/Entity Validator
-
-Enforces Smicolon's BaseModel inheritance pattern for all Django models.
-
-## Activation Triggers
-
-This skill activates when:
-- Creating new model files
-- Modifying existing models
-- Mentioning "model", "database", "schema", "table"
-- Writing class inheriting from `models.Model`
-- Running migrations
-- Discussing data structure
-
-## Core Principle: BaseModel Inheritance
-
-**NEVER repeat UUID/timestamp fields.** All models inherit from BaseModel.
-
-```python
-# ❌ WRONG - Repeating fields
-class User(models.Model):
-    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
-    created_at = models.DateTimeField(auto_now_add=True)
-    updated_at = models.DateTimeField(auto_now=True)
-    is_deleted = models.BooleanField(default=False)
-    email = models.EmailField()
-
-# ✅ CORRECT - Inherit from BaseModel
-import core.models as _core_models
-
-class User(_core_models.BaseModel):
-    email = models.EmailField(unique=True)
-```
-
-## Validation Process
-
-### Step 1: Check if BaseModel Exists
-
-Before any action, check if the project has a BaseModel:
-
-```python
-# Search for BaseModel in (in order):
-# 1. core/models.py
-# 2. shared/models.py
-# 3. common/models.py
-# 4. {app}/base.py
-```
-
-**If BaseModel found:** Suggest inheritance (Step 2a)
-**If BaseModel NOT found:** Create BaseModel first (Step 2b)
-
-### Step 2a: BaseModel Exists - Suggest Inheritance
-
-When seeing:
-```python
-class Product(models.Model):
-    name = models.CharField(max_length=255)
-```
-
-Fix to:
-```python
-import core.models as _core_models
-
-class Product(_core_models.BaseModel):
-    """Product model - inherits id, timestamps, soft delete from BaseModel."""
-
-    name = models.CharField(max_length=255)
-    price = models.DecimalField(max_digits=10, decimal_places=2)
-
-    class Meta:
-        db_table = 'products'
-```
-
-### Step 2b: BaseModel NOT Found - Create It First
-
-If no BaseModel exists, create it:
-
-```python
-# core/models.py
-import uuid
-from django.db import models
-
-class BaseModel(models.Model):
-    """
-    Abstract base model providing:
-    - UUID primary key
-    - Automatic timestamps (created_at, updated_at)
-    - Soft delete support (is_deleted)
-
-    All models MUST inherit from this class.
-    """
-
-    id = models.UUIDField(
-        primary_key=True,
-        default=uuid.uuid4,
-        editable=False
-    )
-    created_at = models.DateTimeField(auto_now_add=True)
-    updated_at = models.DateTimeField(auto_now=True)
-    is_deleted = models.BooleanField(default=False)
-
-    class Meta:
-        abstract = True
-        ordering = ['-created_at']
-
-    def soft_delete(self) -> None:
-        """Soft delete the record."""
-        self.is_deleted = True
-        self.save(update_fields=['is_deleted', 'updated_at'])
-
-    def restore(self) -> None:
-        """Restore a soft-deleted record."""
-        self.is_deleted = False
-        self.save(update_fields=['is_deleted', 'updated_at'])
-
-
-class ActiveManager(models.Manager):
-    """Manager that excludes soft-deleted records."""
-
-    def get_queryset(self):
-        return super().get_queryset().filter(is_deleted=False)
-```
-
-Report to developer:
-> **BaseModel Created**
->
-> Created `core/models.py` with BaseModel. All models should now inherit from it:
-> ```python
-> import core.models as _core_models
->
-> class YourModel(_core_models.BaseModel):
->     # Your fields here - DO NOT add id, created_at, updated_at, is_deleted
-> ```
-
-### Step 3: Detect Duplicate Fields
-
-If seeing a model with explicit id/timestamp fields that inherits from BaseModel:
-
-```python
-# ❌ WRONG - Duplicate fields
-class User(_core_models.BaseModel):
-    id = models.UUIDField(...)  # Already in BaseModel!
-    created_at = models.DateTimeField(...)  # Already in BaseModel!
-    email = models.EmailField()
-```
-
-Remove them:
-```python
-# ✅ CORRECT - Only custom fields
-class User(_core_models.BaseModel):
-    email = models.EmailField(unique=True)
-```
-
-### Step 4: Validate Indexes
-
-Check if appropriate indexes exist:
-
-```python
-class Product(_core_models.BaseModel):
-    name = models.CharField(max_length=255)
-    sku = models.CharField(max_length=100, unique=True)
-
-    class Meta:
-        db_table = 'products'
-        indexes = [
-            models.Index(fields=['sku']),  # Suggest for unique lookups
-            models.Index(fields=['name']),  # Suggest for search
-        ]
-```
-
-## Complete Model Examples
-
-### Standard Model
-
-```python
-# products/models.py
-from django.db import models
-import core.models as _core_models
-
-class Product(_core_models.BaseModel):
-    """Product model."""
-
-    name = models.CharField(max_length=255)
-    description = models.TextField(blank=True)
-    price = models.DecimalField(max_digits=10, decimal_places=2)
-    sku = models.CharField(max_length=100, unique=True, db_index=True)
-    is_active = models.BooleanField(default=True)
-
-    class Meta:
-        db_table = 'products'
-        verbose_name = 'Product'
-        verbose_name_plural = 'Products'
-        indexes = [
-            models.Index(fields=['name']),
-            models.Index(fields=['is_active', 'is_deleted']),
-        ]
-
-    def __str__(self):
-        return self.name
-```
-
-### User Model (with AbstractUser)
-
-```python
-# users/models.py
-import uuid
-from django.db import models
-from django.contrib.auth.models import AbstractUser
-
-class User(AbstractUser):
-    """
-    Custom User model with UUID and timestamps.
-
-    Note: For User, override AbstractUser directly since it has its own
-    ID handling. Add the standard fields manually.
-    """
-
-    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
-    created_at = models.DateTimeField(auto_now_add=True)
-    updated_at = models.DateTimeField(auto_now=True)
-    is_deleted = models.BooleanField(default=False)
-
-    email = models.EmailField(unique=True)
-
-    USERNAME_FIELD = 'email'
-    REQUIRED_FIELDS = []
-
-    class Meta:
-        db_table = 'users'
-```
-
-### Through Model (Many-to-Many)
-
-```python
-# users/models.py
-import core.models as _core_models
-
-class UserOrganization(_core_models.BaseModel):
-    """Through model for user-organization relationship."""
-
-    user = models.ForeignKey('User', on_delete=models.CASCADE)
-    organization = models.ForeignKey('Organization', on_delete=models.CASCADE)
-    role = models.CharField(max_length=50)
-
-    class Meta:
-        db_table = 'user_organizations'
-        unique_together = [['user', 'organization']]
-```
-
-## Custom Managers
-
-BaseModel provides soft delete. Add a custom manager for convenience:
-
-```python
-import core.models as _core_models
-
-class Product(_core_models.BaseModel):
-    name = models.CharField(max_length=255)
-
-    objects = models.Manager()  # All records
-    active = _core_models.ActiveManager()  # Excludes soft-deleted
-
-# Usage
-Product.active.all()  # Only non-deleted
-Product.objects.all()  # All including deleted
-```
-
-## Validation Checklist
-
-When reviewing a model, check:
-
-1. ✅ Inherits from `BaseModel` (or has explicit required fields for special cases)
-2. ✅ Does NOT duplicate fields from BaseModel
-3. ✅ Uses absolute import: `import core.models as _core_models`
-4. ✅ Has appropriate `db_table` name (singular or plural, snake_case)
-5. ✅ Has indexes on frequently queried fields
-6. ✅ Foreign keys have `on_delete` specified
-7. ✅ Has docstring explaining the model
-8. ✅ Has `__str__` method for admin display
-
-## Behavior
-
-**Proactive enforcement:**
-- Check if BaseModel exists FIRST
-- Suggest inheritance instead of field duplication
-- Remove duplicate fields automatically
-- Create BaseModel if missing
-- Explain WHY inheritance is better
-
-**Never:**
-- Add duplicate id/timestamp fields to models
-- Let developers repeat base fields
-- Ignore existing BaseModel in the project