oh-my-customcodex 0.1.0

package/templates/.claude/skills/django-best-practices/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: django-best-practices
+description: Django patterns for production-ready Python web applications
+scope: core
+user-invocable: false
+---
+
+## Purpose
+
+Apply Django patterns for building production-ready, secure, and maintainable Python web applications.
+
+## Rules
+
+### 1. Project Structure
+
+```yaml
+structure:
+  settings_split: true
+  layout: "config/{settings/{base,development,production}.py,urls.py,wsgi.py} + apps/{core/,users/,<feature>/} + templates/ + static/ + requirements/{base,development,production}.txt"
+
+app_module_contents:
+  models.py: Database models
+  views.py: Request handlers
+  urls.py: URL patterns (with app_name)
+  serializers.py: DRF serializers (if API)
+  forms.py: Django forms
+  admin.py: Admin customization
+  services.py: Business logic layer
+  managers.py: Custom model managers
+  signals.py: Django signals (use sparingly)
+  tests/: Test suite (mirror app structure)
+```
+
+Reference: guides/django-best-practices/README.md
+
+### 2. Models Best Practices
+
+```yaml
+custom_user_model:
+  rule: ALWAYS create a custom User model, even if identical to default
+  location: apps/users/models.py
+  reason: Impossible to swap default User model mid-project
+  pattern: "Extend AbstractUser, set AUTH_USER_MODEL in settings"
+
+primary_key:
+  default: BigAutoField
+  settings: DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'
+
+model_meta:
+  required:
+    - __str__: human-readable representation
+    - Meta.ordering: consistent default ordering
+    - Meta.verbose_name: singular display name
+    - Meta.verbose_name_plural: plural display name
+
+query_optimization:
+  foreign_key: select_related()    # Single SQL JOIN
+  many_to_many: prefetch_related() # Separate query + Python join
+  partial_fields: only() / defer() # Load subset of fields
+  aggregations: F() and Q() objects for complex expressions
+  bulk_ops:
+    create: bulk_create(objs, batch_size=1000)
+    update: bulk_update(objs, fields, batch_size=1000)
+
+indexing:
+  - Frequently filtered fields: db_index=True
+  - Frequently ordered fields: Meta.ordering fields
+  - Multi-column: Meta.indexes with models.Index
+  - Unique together: Meta.unique_together or UniqueConstraint
+
+constraints:
+  use: Meta.constraints for database-level enforcement
+  types: "UniqueConstraint, CheckConstraint"
+
+soft_delete:
+  pattern: is_active = models.BooleanField(default=True)
+  manager: Override default manager to filter is_active=True
+
+custom_managers:
+  rule: Use managers for reusable querysets
+```
+
+Reference: guides/django-best-practices/README.md
+
+### 3. Views Best Practices
+
+```yaml
+cbv_vs_fbv:
+  cbv: Standard CRUD, predictable patterns (ListView, DetailView, etc.)
+  fbv: Complex custom logic, non-standard workflows
+
+thin_views:
+  rule: Keep views thin — delegate business logic to services/models
+
+shortcuts:
+  - get_object_or_404(Model, pk=pk): Returns 404 instead of 500
+  - get_list_or_404(Model, **kwargs): 404 if empty list
+
+mixins:
+  authentication: LoginRequiredMixin
+  permissions: PermissionRequiredMixin
+  user_pass: UserPassesTestMixin
+
+status_codes:
+  200: OK (default for success)
+  201: Created (after successful creation)
+  302: Redirect (after POST success — PRG pattern)
+  400: Bad Request (validation error)
+  403: Forbidden (permission denied)
+  404: Not Found
+  405: Method Not Allowed
+```
+
+### 4. URL Patterns
+
+```yaml
+namespacing:
+  app_name: Required in every app's urls.py
+  usage: "reverse('app_name:url_name') or {% url 'app_name:url_name' %}"
+
+syntax:
+  prefer: path() over re_path() for clarity
+  use_re_path: Only for complex regex patterns
+
+naming:
+  rule: Name ALL URL patterns
+  convention: "{resource}-{action} (e.g., article-list, article-detail)"
+
+inclusion:
+  root_urls: Use include() for app-level URLs
+```
+
+Reference: guides/django-best-practices/README.md
+
+### 5. Forms & Validation
+
+```yaml
+model_forms:
+  rule: Use ModelForm when form maps to a model
+  fields: "Explicitly list fields (never use fields = '__all__')"
+
+validation:
+  field_level: clean_<field>() method
+  cross_field: clean() method
+  built_in: Use Django validators (MaxValueValidator, RegexValidator, etc.)
+```
+
+Reference: guides/django-best-practices/README.md
+
+### 6. Security
+
+```yaml
+environment:
+  SECRET_KEY: Never hardcode — read from environment variable
+  DEBUG: False in production (MUST)
+  ALLOWED_HOSTS: Explicitly set in production (MUST)
+
+https:
+  SECURE_SSL_REDIRECT: true
+  SESSION_COOKIE_SECURE: true
+  CSRF_COOKIE_SECURE: true
+  SECURE_HSTS_SECONDS: 3600  # Start small, increase to 31536000
+  SECURE_HSTS_INCLUDE_SUBDOMAINS: true
+
+clickjacking:
+  X_FRAME_OPTIONS: DENY
+
+content_type:
+  SECURE_CONTENT_TYPE_NOSNIFF: true
+
+csrf:
+  rule: Enabled by default via CsrfViewMiddleware — do NOT disable
+
+sql_injection:
+  rule: Use ORM, avoid raw SQL; if needed, use parameterized queries
+
+xss:
+  rule: Templates auto-escape by default — never use |safe with user content
+
+deployment_check:
+  command: python manage.py check --deploy
+  run: Before every production deployment
+```
+
+### 7. Testing
+
+```yaml
+framework:
+  preferred: pytest-django (over unittest)
+  config: pytest.ini or pyproject.toml with [tool.pytest.ini_options]
+
+test_classes:
+  database: TestCase (wraps each test in transaction)
+  no_database: SimpleTestCase (faster)
+  live_server: LiveServerTestCase (for Selenium)
+
+test_data:
+  preferred: factory_boy or model_bakery
+  avoid: fixtures (hard to maintain, slow)
+
+request_testing:
+  Client: Full request/response cycle (preferred for views)
+  RequestFactory: Faster, no middleware (for unit testing views)
+
+settings_override:
+  decorator: '@override_settings(...)'
+
+coverage:
+  target: 80%+
+  exclude: migrations, admin, settings
+
+structure:
+  mirror_app: tests/test_models.py, tests/test_views.py, tests/test_forms.py
+```
+
+Reference: guides/django-best-practices/README.md
+
+### 8. Performance
+
+```yaml
+n_plus_1_prevention:
+  check: Use django-debug-toolbar in development
+  fix_fk: select_related('author', 'category')
+  fix_m2m: prefetch_related('tags', 'comments')
+  complex: Prefetch object with custom queryset
+
+partial_loading:
+  only: "only('id', 'title', 'created_at') — Load only these fields"
+  defer: "defer('body', 'metadata') — Load all except these"
+  values: "values('id', 'title') — Returns dicts (no ORM overhead)"
+  values_list: "values_list('id', flat=True) — Returns flat list"
+
+caching:
+  backend: Redis (preferred), Memcached
+  view_cache: "'@cache_page(60 * 15)' decorator"
+  template_cache: "'{% cache 500 sidebar %}' template tag"
+  low_level: cache.get/set/delete for fine-grained control
+
+pagination:
+  list_views: Always paginate large querysets
+  page_size: Set reasonable default (20-50 items)
+  drf: PageNumberPagination or CursorPagination
+
+bulk_operations:
+  create: "bulk_create(articles, batch_size=1000)"
+  update: "bulk_update(articles, ['status'], batch_size=1000)"
+  avoid: Loops calling .save() on many objects
+```
+
+### 9. Django REST Framework (DRF)
+
+```yaml
+serializers:
+  standard_crud: ModelSerializer
+  read_only: Use SerializerMethodField for computed values
+  write_validation: validate_<field>() and validate() methods
+
+viewsets:
+  standard: ModelViewSet for full CRUD
+  custom: ViewSet with explicit action methods
+  routers: DefaultRouter or SimpleRouter for URL generation
+
+authentication:
+  jwt: djangorestframework-simplejwt (recommended)
+  token: DRF built-in TokenAuthentication
+  session: SessionAuthentication (for browser clients)
+
+permissions:
+  global: DEFAULT_PERMISSION_CLASSES in settings
+  per_view: permission_classes attribute on ViewSet
+  object_level: has_object_permission() in custom permission class
+
+versioning:
+  method: NamespaceVersioning or URLPathVersioning
+
+throttling:
+  anonymous: AnonRateThrottle
+  authenticated: UserRateThrottle
+  custom: Extend BaseThrottle
+
+pagination:
+  global: DEFAULT_PAGINATION_CLASS in settings
+  types: PageNumberPagination (simple), CursorPagination (large datasets)
+```
+
+Reference: guides/django-best-practices/README.md
+
+### 10. Deployment
+
+```yaml
+wsgi_asgi:
+  wsgi: gunicorn (4 workers per CPU core)
+  asgi: uvicorn with gunicorn workers (for async/WebSocket)
+
+static_files:
+  development: Django's staticfiles
+  production: whitenoise middleware OR CDN (S3 + CloudFront)
+  command: python manage.py collectstatic --noinput
+
+database:
+  development: SQLite (acceptable)
+  production: PostgreSQL (MUST — never SQLite in production)
+  connection_pooling: Use pgBouncer or django-db-connection-pool
+
+migrations:
+  deploy: Run as part of CI/CD pipeline before server restart
+  zero_downtime: Use additive migrations (add nullable columns, backfill, then add constraint)
+
+logging:
+  config: LOGGING dict in settings
+  handler: File handler in production, console in development
+  level: WARNING in production, DEBUG in development
+
+environment_variables:
+  tool: python-decouple or django-environ
+  never: Hardcode secrets in settings files
+
+health_check:
+  endpoint: /health/ returning 200 OK
+  checks: Database connection, cache connection, disk space
+```
+
+## Application
+
+When writing Django code:
+
+1. **Always** create a custom User model before any other models
+2. **Always** split settings into base/development/production
+3. **Prefer** CBVs for standard CRUD, FBVs for custom logic
+4. **Use** select_related/prefetch_related to prevent N+1 queries
+5. **Apply** the security checklist for every production deployment
+6. **Test** with pytest-django and factory_boy
+7. **Never** use `fields = '__all__'` in ModelForms or ModelSerializer
+8. **Run** `python manage.py check --deploy` before shipping

package/templates/.claude/skills/docker-best-practices/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: docker-best-practices
+description: Docker patterns for optimized containerization
+scope: core
+user-invocable: false
+---
+
+## Purpose
+
+Apply Docker patterns for building optimized and secure container images.
+
+## Rules
+
+### 1. Layer Optimization
+
+```yaml
+principles:
+  - Combine related RUN commands
+  - Sort multi-line arguments alphabetically
+  - Clean up in same layer
+
+patterns: |
+  # GOOD: Single layer, clean cache
+  RUN apt-get update && apt-get install -y \
+      curl \
+      git \
+      vim \
+      && rm -rf /var/lib/apt/lists/*
+
+  # BAD: Multiple layers, cache remains
+  RUN apt-get update
+  RUN apt-get install -y curl
+  RUN apt-get install -y git
+```
+
+### 2. Multi-Stage Builds
+
+```yaml
+purpose:
+  - Reduce final image size
+  - Separate build and runtime dependencies
+  - Security (no build tools in production)
+
+pattern: |
+  # Build stage
+  FROM golang:1.21 AS builder
+  WORKDIR /app
+  COPY go.mod go.sum ./
+  RUN go mod download
+  COPY . .
+  RUN CGO_ENABLED=0 go build -o /app/server ./cmd/server
+
+  # Runtime stage
+  FROM gcr.io/distroless/static:nonroot
+  COPY --from=builder /app/server /server
+  USER nonroot:nonroot
+  ENTRYPOINT ["/server"]
+```
+
+### 3. Security
+
+```yaml
+principles:
+  - Run as non-root user
+  - Pin base image versions
+  - Use minimal base images
+  - Don't store secrets in images
+
+patterns: |
+  # Pin version with digest
+  FROM node:20-slim@sha256:abc123...
+
+  # Create non-root user
+  RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+  USER appuser
+
+  # Use secrets mount (BuildKit)
+  RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
+      npm install
+
+  # .dockerignore for secrets
+  # .env
+  # *.pem
+  # credentials.json
+```
+
+### 4. Image Size Reduction
+
+```yaml
+strategies:
+  - Use slim/alpine base images
+  - Remove build dependencies
+  - Use .dockerignore
+  - Multi-stage builds
+
+minimal_bases:
+  distroless: "gcr.io/distroless/static"
+  alpine: "alpine:3.19"
+  slim: "debian:12-slim"
+
+patterns: |
+  # Alpine for size
+  FROM python:3.12-alpine
+  RUN apk add --no-cache gcc musl-dev
+
+  # Distroless for security
+  FROM gcr.io/distroless/python3
+  COPY --from=builder /app /app
+```
+
+### 5. Cache Optimization
+
+```yaml
+principles:
+  - Order from least to most frequently changing
+  - Copy dependency files first
+  - Use BuildKit cache mounts
+
+patterns: |
+  # Copy dependency files first
+  COPY package.json package-lock.json ./
+  RUN npm ci
+
+  # Then copy source (changes frequently)
+  COPY . .
+  RUN npm run build
+
+  # BuildKit cache mount
+  RUN --mount=type=cache,target=/root/.cache/pip \
+      pip install -r requirements.txt
+```
+
+### 6. ENTRYPOINT vs CMD
+
+```yaml
+entrypoint:
+  purpose: Main executable
+  form: exec form ["executable"]
+
+cmd:
+  purpose: Default arguments
+  form: exec form ["arg1", "arg2"]
+
+patterns: |
+  # Fixed command with variable args
+  ENTRYPOINT ["python", "app.py"]
+  CMD ["--port", "8080"]
+
+  # docker run myapp --port 3000
+  # Executes: python app.py --port 3000
+
+  # Flexible command
+  CMD ["python", "app.py"]
+
+  # docker run myapp bash
+  # Executes: bash
+```
+
+### 7. Health Checks
+
+```yaml
+purpose: Container health monitoring
+interval: how often to check
+timeout: max time for check
+retries: failures before unhealthy
+
+pattern: |
+  HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
+      CMD curl -f http://localhost:8080/health || exit 1
+```
+
+### 8. Docker Compose
+
+```yaml
+best_practices:
+  - Use named volumes
+  - Define networks explicitly
+  - Use environment files
+  - Set resource limits
+
+pattern: |
+  version: "3.8"
+
+  services:
+    app:
+      build:
+        context: .
+        target: production
+      environment:
+        - DATABASE_URL
+      env_file:
+        - .env
+      ports:
+        - "8080:8080"
+      depends_on:
+        db:
+          condition: service_healthy
+      deploy:
+        resources:
+          limits:
+            cpus: "1"
+            memory: 512M
+      networks:
+        - backend
+
+    db:
+      image: postgres:16-alpine
+      volumes:
+        - postgres_data:/var/lib/postgresql/data
+      healthcheck:
+        test: ["CMD-SHELL", "pg_isready -U postgres"]
+        interval: 10s
+        timeout: 5s
+        retries: 5
+      networks:
+        - backend
+
+  volumes:
+    postgres_data:
+
+  networks:
+    backend:
+```
+
+### 9. Common Patterns by Language
+
+```yaml
+nodejs: |
+  FROM node:20-slim AS builder
+  WORKDIR /app
+  COPY package*.json ./
+  RUN npm ci --only=production
+
+  FROM gcr.io/distroless/nodejs20
+  WORKDIR /app
+  COPY --from=builder /app/node_modules ./node_modules
+  COPY . .
+  CMD ["server.js"]
+
+python: |
+  FROM python:3.12-slim AS builder
+  WORKDIR /app
+  RUN pip install --user -r requirements.txt
+
+  FROM python:3.12-slim
+  WORKDIR /app
+  COPY --from=builder /root/.local /root/.local
+  COPY . .
+  ENV PATH=/root/.local/bin:$PATH
+  CMD ["python", "app.py"]
+
+go: |
+  FROM golang:1.21 AS builder
+  WORKDIR /app
+  COPY go.* ./
+  RUN go mod download
+  COPY . .
+  RUN CGO_ENABLED=0 go build -o /server
+
+  FROM scratch
+  COPY --from=builder /server /server
+  ENTRYPOINT ["/server"]
+```
+
+## Application
+
+When writing Dockerfiles:
+
+1. **Always** use multi-stage builds
+2. **Always** run as non-root user
+3. **Always** pin base image versions
+4. **Prefer** minimal base images
+5. **Order** layers for cache efficiency
+6. **Clean** package caches in same layer
+7. **Use** .dockerignore
+8. **Add** health checks