start-vibing-stacks 1.7.4 → 1.8.0

package/dist/detector.d.ts

@@ -14,3 +14,4 @@ export declare function detectPhpFramework(projectDir: string): string | null;
  * Detect framework within a Node.js project
  */
 export declare function detectNodeFramework(projectDir: string): string | null;
+export declare function detectPythonFramework(projectDir: string): string | null;

package/dist/detector.js

@@ -4,7 +4,7 @@
  * Auto-detects project stack by scanning for known files.
  * Also detects .cursorrules, CLAUDE.md, and git presence.
  */
-import { existsSync, readdirSync } from 'fs';
+import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 const STACK_SIGNATURES = [
     // PHP
@@ -101,3 +101,20 @@ export function detectNodeFramework(projectDir) {
         return 'astro';
     return null;
 }
+export function detectPythonFramework(projectDir) {
+    // Check manage.py (Django)
+    if (existsSync(join(projectDir, 'manage.py')))
+        return 'django';
+    // Check for FastAPI in requirements or pyproject
+    for (const reqFile of ['requirements.txt', 'pyproject.toml', 'Pipfile']) {
+        const filePath = join(projectDir, reqFile);
+        if (existsSync(filePath)) {
+            const content = readFileSync(filePath, 'utf8').toLowerCase();
+            if (content.includes('fastapi'))
+                return 'fastapi';
+            if (content.includes('flask'))
+                return 'flask';
+        }
+    }
+    return null;
+}

package/dist/index.js

@@ -10,7 +10,7 @@ import { join, basename } from 'path';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import * as ui from './ui.js';
-import { detectProject, detectPhpFramework, detectNodeFramework } from './detector.js';
+import { detectProject, detectPhpFramework, detectNodeFramework, detectPythonFramework } from './detector.js';
 import { autoInstall, installComposer, installClaudeCode } from './installer.js';
 import { loadStackConfig, setupProject } from './setup.js';
 import { selectMcpServers, installMcpServers } from './mcp.js';
@@ -56,7 +56,7 @@ if (FLAGS.help) {
 const AVAILABLE_STACKS = [
     { id: 'php', name: 'PHP 8.3+', icon: '🐘', available: true },
     { id: 'nodejs', name: 'Node.js / TypeScript', icon: '📦', available: true },
-    { id: 'python', name: 'Python', icon: '🐍', available: false },
+    { id: 'python', name: 'Python 3.12+', icon: '🐍', available: true },
     { id: 'rust', name: 'Rust', icon: '🦀', available: false },
     { id: 'go', name: 'Go', icon: '🐹', available: false },
 ];
@@ -158,7 +158,9 @@ async function main() {
         ? detectPhpFramework(projectDir)
         : stackId === 'nodejs'
             ? detectNodeFramework(projectDir)
-            : null;
+            : stackId === 'python'
+                ? detectPythonFramework(projectDir)
+                : null;
     const { framework } = await inquirer.prompt([
         {
             type: 'list',

package/dist/ui.js

@@ -2,7 +2,7 @@
  * Start Vibing Stacks — Terminal UI
  */
 import chalk from 'chalk';
-const VERSION = '1.7.4';
+const VERSION = '1.8.0';
 const gradient = (text) => {
     const colors = [chalk.hex('#FF6B6B'), chalk.hex('#FF8E53'), chalk.hex('#FFBD2E'), chalk.hex('#48BB78'), chalk.hex('#4299E1'), chalk.hex('#9F7AEA')];
     return text.split('').map((c, i) => colors[i % colors.length](c)).join('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/python/skills/async-patterns/SKILL.md

@@ -0,0 +1,98 @@
+# Async Python Patterns — Concurrency & Performance
+
+**ALWAYS invoke when writing async/await code or concurrent operations.**
+
+## Core: asyncio.gather vs TaskGroup
+
+```python
+import asyncio
+
+# Gather — run multiple coroutines concurrently
+async def fetch_all():
+    results = await asyncio.gather(
+        fetch_users(),
+        fetch_products(),
+        fetch_orders(),
+    )
+    users, products, orders = results
+
+# TaskGroup (Python 3.11+) — structured concurrency with proper cancellation
+async def fetch_all_safe():
+    async with asyncio.TaskGroup() as tg:
+        t1 = tg.create_task(fetch_users())
+        t2 = tg.create_task(fetch_products())
+    return t1.result(), t2.result()
+    # If any task fails, ALL are cancelled
+```
+
+## HTTP Client (httpx)
+
+```python
+import httpx
+
+# REUSE client (connection pooling)
+async def fetch_data():
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        response = await client.get("https://api.example.com/data")
+        response.raise_for_status()
+        return response.json()
+
+# Concurrent requests
+async def fetch_many(urls: list[str]) -> list[dict]:
+    async with httpx.AsyncClient() as client:
+        tasks = [client.get(url) for url in urls]
+        responses = await asyncio.gather(*tasks)
+        return [r.json() for r in responses]
+```
+
+## Semaphore (rate limiting)
+
+```python
+# Limit concurrent operations
+sem = asyncio.Semaphore(10)  # Max 10 concurrent
+
+async def fetch_with_limit(url: str):
+    async with sem:
+        async with httpx.AsyncClient() as client:
+            return await client.get(url)
+```
+
+## Queue Pattern (producer/consumer)
+
+```python
+async def producer(queue: asyncio.Queue):
+    for item in data:
+        await queue.put(item)
+    await queue.put(None)  # Sentinel
+
+async def consumer(queue: asyncio.Queue):
+    while True:
+        item = await queue.get()
+        if item is None:
+            break
+        await process(item)
+        queue.task_done()
+
+async def main():
+    queue = asyncio.Queue(maxsize=100)  # Backpressure
+    await asyncio.gather(producer(queue), consumer(queue))
+```
+
+## Timeouts
+
+```python
+# Always add timeouts to external calls
+try:
+    result = await asyncio.wait_for(fetch_data(), timeout=5.0)
+except asyncio.TimeoutError:
+    logger.warning("External API timed out")
+    result = default_value
+```
+
+## FORBIDDEN
+
+1. **`time.sleep()` in async code** — use `await asyncio.sleep()`
+2. **Sync HTTP in async context** — use `httpx.AsyncClient`, not `requests`
+3. **No timeout on external calls** — always `asyncio.wait_for()` or `httpx.Timeout`
+4. **Creating new client per request** — reuse with `async with`
+5. **Bare `asyncio.gather` without error handling** — use `return_exceptions=True` or TaskGroup

package/stacks/python/skills/django-patterns/SKILL.md

@@ -0,0 +1,101 @@
+# Django Patterns — Full-Stack Python (Django 5+)
+
+**ALWAYS invoke when writing Django models, views, or serializers.**
+
+## Model Design (Fat Models, Thin Views)
+
+```python
+from django.db import models
+from django.utils import timezone
+import uuid
+
+class TimeStampedModel(models.Model):
+    """Abstract base — reuse in all models."""
+    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)
+
+    class Meta:
+        abstract = True
+
+class User(TimeStampedModel):
+    email = models.EmailField(unique=True, db_index=True)
+    name = models.CharField(max_length=255)
+    is_active = models.BooleanField(default=True)
+
+    # Fat model: business logic HERE
+    def deactivate(self):
+        self.is_active = False
+        self.save(update_fields=['is_active', 'updated_at'])
+
+    # Custom manager
+    objects = UserManager()
+```
+
+## QuerySet Optimization
+
+```python
+# ALWAYS use select_related for ForeignKey
+users = User.objects.select_related('profile').filter(is_active=True)
+
+# ALWAYS use prefetch_related for ManyToMany
+posts = Post.objects.prefetch_related('tags', 'comments').all()
+
+# Use .only() for specific fields
+User.objects.only('id', 'email').filter(is_active=True)
+
+# Avoid N+1 — NEVER loop queries
+# WRONG:
+for post in Post.objects.all():
+    print(post.author.name)  # N+1!
+
+# CORRECT:
+for post in Post.objects.select_related('author'):
+    print(post.author.name)  # 1 query
+```
+
+## Django REST Framework
+
+```python
+# serializers.py
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ['id', 'email', 'name', 'created_at']
+        read_only_fields = ['id', 'created_at']
+
+# views.py
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.filter(is_active=True)
+    serializer_class = UserSerializer
+    permission_classes = [IsAuthenticated]
+    pagination_class = PageNumberPagination
+```
+
+## Async Views (Django 5.0+)
+
+```python
+# Use async when calling external APIs or heavy I/O
+async def fetch_external_data(request):
+    async with httpx.AsyncClient() as client:
+        response = await client.get('https://api.example.com/data')
+    return JsonResponse(response.json())
+```
+
+## Migrations Best Practices
+
+```bash
+python manage.py makemigrations --name descriptive_name
+python manage.py migrate
+
+# Check for missing migrations in CI
+python manage.py makemigrations --check --dry-run
+```
+
+## FORBIDDEN
+
+1. **Logic in views** — fat models, thin views
+2. **N+1 queries** — always `select_related`/`prefetch_related`
+3. **`objects.all()` without limit** — paginate or `.only()`
+4. **Raw SQL without parameterization** — use ORM or `params=[]`
+5. **Skipping migrations** — always `makemigrations` after model changes

package/stacks/python/skills/fastapi-patterns/SKILL.md

@@ -0,0 +1,129 @@
+# FastAPI Patterns — High-Performance Async APIs
+
+**ALWAYS invoke when writing FastAPI routes, dependencies, or middleware.**
+
+## Route Pattern
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, status
+from app.schemas.user import UserCreate, UserResponse
+from app.services.user import UserService
+from app.api.deps import get_current_user, get_db
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(data: UserCreate, db=Depends(get_db)):
+    service = UserService(db)
+    return await service.create(data)
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(user=Depends(get_current_user)):
+    return user
+```
+
+## Dependency Injection
+
+```python
+# app/api/deps.py
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+async def get_db():
+    async with async_session() as session:
+        yield session  # Auto-cleanup
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+    db=Depends(get_db),
+) -> User:
+    user = await verify_token(credentials.credentials, db)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
+    return user
+```
+
+## Pydantic Settings (env config)
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    DATABASE_URL: str
+    SECRET_KEY: str
+    DEBUG: bool = False
+    ALLOWED_ORIGINS: list[str] = ["http://localhost:3000"]
+
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+## Middleware
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Custom middleware
+@app.middleware("http")
+async def add_request_id(request, call_next):
+    request_id = str(uuid4())
+    request.state.request_id = request_id
+    response = await call_next(request)
+    response.headers["X-Request-ID"] = request_id
+    return response
+```
+
+## SQLAlchemy 2.0 Async
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+
+engine = create_async_engine(settings.DATABASE_URL, pool_size=20, max_overflow=10)
+async_session = async_sessionmaker(engine, expire_on_commit=False)
+
+# Repository pattern
+class UserRepository:
+    def __init__(self, session):
+        self.session = session
+
+    async def get_by_id(self, id: UUID) -> User | None:
+        result = await self.session.execute(
+            select(User).where(User.id == id)
+        )
+        return result.scalar_one_or_none()
+```
+
+## Production Deployment
+
+```bash
+# uvicorn with gunicorn (production)
+gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+
+# Docker
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+CMD ["gunicorn", "app.main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000"]
+```
+
+## FORBIDDEN
+
+1. **`def` routes with async DB calls** — use `async def`
+2. **Business logic in routes** — use services layer
+3. **Hardcoded secrets** — use Pydantic Settings + `.env`
+4. **No response_model** — always specify for auto-docs
+5. **Catching bare `Exception`** — catch specific exceptions

package/stacks/python/skills/pydantic-validation/SKILL.md

@@ -0,0 +1,103 @@
+# Pydantic Validation — Runtime Type Safety for Python
+
+**ALWAYS use Pydantic for API schemas, config, and data boundaries.**
+
+## Multi-Model Pattern
+
+```python
+from pydantic import BaseModel, Field, EmailStr
+from datetime import datetime
+from uuid import UUID
+
+# Base — shared fields
+class UserBase(BaseModel):
+    name: str = Field(..., min_length=2, max_length=100)
+    email: EmailStr
+
+# Create — request body (required fields)
+class UserCreate(UserBase):
+    password: str = Field(..., min_length=8)
+
+# Update — PATCH (all optional)
+class UserUpdate(BaseModel):
+    name: str | None = Field(None, min_length=2)
+    email: EmailStr | None = None
+
+# Response — API output
+class UserResponse(UserBase):
+    id: UUID
+    created_at: datetime
+    is_active: bool
+
+    model_config = {"from_attributes": True}  # Works with ORM objects
+
+# InDB — database document (Cosmos, Mongo)
+class UserInDB(UserResponse):
+    doc_type: str = "user"
+    hashed_password: str
+```
+
+## Validators
+
+```python
+from pydantic import field_validator, model_validator
+
+class OrderCreate(BaseModel):
+    quantity: int
+    price: float
+    discount: float = 0.0
+
+    @field_validator('quantity')
+    @classmethod
+    def quantity_positive(cls, v):
+        if v <= 0:
+            raise ValueError('Quantity must be positive')
+        return v
+
+    @model_validator(mode='after')
+    def discount_not_exceed_price(self):
+        if self.discount > self.price * self.quantity:
+            raise ValueError('Discount exceeds total')
+        return self
+```
+
+## Settings (env config)
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    DATABASE_URL: str
+    SECRET_KEY: str
+    DEBUG: bool = False
+    REDIS_URL: str = "redis://localhost:6379"
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+settings = Settings()
+```
+
+## camelCase API (Python snake_case → JSON camelCase)
+
+```python
+from pydantic import ConfigDict
+
+class ApiModel(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+        alias_generator=lambda s: ''.join(
+            w.capitalize() if i else w for i, w in enumerate(s.split('_'))
+        ),
+    )
+
+class UserResponse(ApiModel):
+    first_name: str    # JSON: "firstName"
+    created_at: datetime  # JSON: "createdAt"
+```
+
+## FORBIDDEN
+
+1. **Raw dicts for API I/O** — always Pydantic models
+2. **Skipping validation** — `model_validate()` not `dict()`
+3. **Single model for everything** — use Base/Create/Update/Response pattern
+4. **No `from_attributes`** — needed for ORM integration

package/stacks/python/skills/pytest-testing/SKILL.md

@@ -0,0 +1,108 @@
+# Pytest Testing — Python Testing Patterns
+
+**ALWAYS invoke AFTER implementing any feature.**
+
+## Structure
+
+```
+tests/
+├── conftest.py          # Shared fixtures
+├── unit/
+│   ├── test_services.py
+│   └── test_models.py
+├── integration/
+│   ├── test_api.py
+│   └── test_db.py
+└── e2e/
+    └── test_flows.py
+```
+
+## Fixtures
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+from app.core.config import settings
+
+@pytest.fixture
+async def client():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac
+
+@pytest.fixture
+async def db_session():
+    async with async_session() as session:
+        yield session
+        await session.rollback()  # Cleanup
+
+@pytest.fixture
+def sample_user():
+    return {"name": "Test User", "email": f"test_{uuid4().hex[:8]}@test.com", "password": "Pass1234!"}
+```
+
+## Async Tests
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_create_user(client, sample_user):
+    response = await client.post("/api/v1/users", json=sample_user)
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == sample_user["email"]
+    assert "id" in data
+    assert "password" not in data  # Never leak passwords
+
+@pytest.mark.asyncio
+async def test_get_me_unauthorized(client):
+    response = await client.get("/api/v1/users/me")
+    assert response.status_code == 401
+```
+
+## Parameterized Tests
+
+```python
+@pytest.mark.parametrize("email,expected", [
+    ("valid@test.com", 201),
+    ("invalid-email", 422),
+    ("", 422),
+])
+async def test_email_validation(client, email, expected):
+    response = await client.post("/api/v1/users", json={"name": "Test", "email": email, "password": "Pass1234!"})
+    assert response.status_code == expected
+```
+
+## Mocking
+
+```python
+from unittest.mock import AsyncMock, patch
+
+@pytest.mark.asyncio
+async def test_external_api_failure(client):
+    with patch("app.services.external.fetch_data", new_callable=AsyncMock) as mock:
+        mock.side_effect = ConnectionError("API down")
+        response = await client.get("/api/v1/data")
+        assert response.status_code == 503
+```
+
+## Commands
+
+```bash
+pytest                       # Run all
+pytest -x                    # Stop on first failure
+pytest --tb=short            # Short traceback
+pytest -k "test_create"      # Filter by name
+pytest --cov=app --cov-report=html  # Coverage
+pytest -n auto               # Parallel (pytest-xdist)
+```
+
+## FORBIDDEN
+
+1. **No fixtures for cleanup** — always rollback/cleanup
+2. **Hardcoded test data** — use factories/uuid
+3. **Testing implementation** — test behavior, not internals
+4. **Skipping async tests** — use `pytest-asyncio`
+5. **No coverage in CI** — `--cov --cov-fail-under=70`

package/stacks/python/skills/python-patterns/SKILL.md

@@ -0,0 +1,110 @@
+# Python Patterns — Architecture & Decision-Making
+
+**ALWAYS invoke when making Python architecture decisions.**
+
+## Framework Selection
+
+```
+What are you building?
+├── API / Microservices     → FastAPI (async, Pydantic, fast)
+├── Full-stack / CMS / Admin → Django (batteries-included)
+├── Simple / Script         → Flask (minimal)
+├── AI/ML API serving       → FastAPI (Pydantic, uvicorn)
+└── Background workers      → Celery + any framework
+```
+
+## Async vs Sync
+
+```
+I/O-bound (waiting for DB, HTTP, files) → async def
+CPU-bound (computing, parsing)          → def + multiprocessing
+
+Don't:
+├── Mix sync and async carelessly
+├── Use sync libraries in async code (blocks event loop!)
+└── Force async for CPU work
+```
+
+### Async Library Selection
+
+| Need | Library |
+|------|---------|
+| HTTP client | `httpx` |
+| PostgreSQL | `asyncpg` |
+| Redis | `redis[async]` |
+| File I/O | `aiofiles` |
+| ORM | SQLAlchemy 2.0+ async, Tortoise |
+
+## Type Hints (MANDATORY for public APIs)
+
+```python
+from typing import Optional
+
+def find_user(id: int) -> Optional[User]: ...
+def process(data: str | dict) -> None: ...
+def get_items() -> list[Item]: ...
+```
+
+## Project Structure
+
+### FastAPI
+```
+app/
+├── main.py           # FastAPI app + startup
+├── api/v1/
+│   ├── routes/       # Endpoints
+│   └── deps.py       # Dependencies (auth, db)
+├── models/           # SQLAlchemy / Beanie models
+├── schemas/          # Pydantic schemas
+├── services/         # Business logic
+├── core/
+│   ├── config.py     # Pydantic Settings
+│   └── security.py   # Auth helpers
+└── tests/
+```
+
+### Django
+```
+myproject/
+├── manage.py
+├── config/           # Settings, URLs, ASGI/WSGI
+├── apps/
+│   ├── users/        # Per-app: models, views, serializers, tests
+│   └── products/
+└── tests/
+```
+
+## Error Handling
+
+```python
+# Custom exceptions in services
+class NotFoundError(Exception):
+    def __init__(self, resource: str, id: str):
+        self.resource = resource
+        self.id = id
+
+# FastAPI exception handler
+@app.exception_handler(NotFoundError)
+async def not_found_handler(request, exc):
+    return JSONResponse(status_code=404, content={
+        "error": "not_found",
+        "message": f"{exc.resource} {exc.id} not found"
+    })
+```
+
+## Background Tasks
+
+| Solution | Best For |
+|----------|----------|
+| `BackgroundTasks` | Simple, in-process, fire-and-forget |
+| `Celery` | Distributed, retries, complex workflows |
+| `ARQ` | Async, Redis-based, lightweight |
+| `Dramatiq` | Actor-based, simpler than Celery |
+
+## FORBIDDEN
+
+1. **Business logic in routes/views** — use services layer
+2. **Sync libraries in async code** — blocks event loop
+3. **No type hints on public APIs** — always type
+4. **Raw SQL without parameterization** — injection risk
+5. **`import *`** — explicit imports only

package/stacks/python/skills/python-performance/SKILL.md

@@ -0,0 +1,109 @@
+# Python Performance — Profiling & Optimization
+
+**ALWAYS invoke when optimizing slow Python code.**
+
+## Profiling Tools
+
+```bash
+# CPU profiling
+python -m cProfile -s cumulative app.py
+
+# Line profiling (pip install line-profiler)
+kernprof -l -v script.py
+
+# Memory profiling (pip install memory-profiler)
+python -m memory_profiler script.py
+
+# py-spy (production-safe, no code changes)
+py-spy top --pid 12345
+py-spy record -o profile.svg --pid 12345
+```
+
+## Common Optimizations
+
+### Data Structures
+```python
+# Use set for membership testing (O(1) vs O(n))
+# SLOW:
+if item in large_list: ...
+# FAST:
+large_set = set(large_list)
+if item in large_set: ...
+
+# Use dict.get() instead of try/except
+value = data.get('key', default)
+
+# Use collections for specialized needs
+from collections import defaultdict, Counter, deque
+```
+
+### Generators (memory)
+```python
+# WRONG — loads everything in memory
+def get_all():
+    return [process(x) for x in huge_dataset]
+
+# CORRECT — lazy evaluation
+def get_all():
+    for x in huge_dataset:
+        yield process(x)
+
+# Or generator expression
+total = sum(x.price for x in orders)  # Not [x.price for x in orders]
+```
+
+### String Operations
+```python
+# SLOW — string concatenation in loop
+result = ""
+for s in strings:
+    result += s  # O(n²)
+
+# FAST — join
+result = "".join(strings)  # O(n)
+```
+
+### Database (SQLAlchemy / Django ORM)
+```python
+# Bulk operations (not one-by-one)
+# SLOW:
+for item in items:
+    db.add(Item(**item))
+
+# FAST:
+db.add_all([Item(**item) for item in items])
+await db.commit()
+
+# Django bulk
+Item.objects.bulk_create([Item(**item) for item in items], batch_size=1000)
+```
+
+### Caching
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=256)
+def expensive_computation(n: int) -> int:
+    return sum(range(n))
+
+# Async caching with Redis
+import redis.asyncio as redis
+
+cache = redis.from_url("redis://localhost")
+
+async def get_user(id: str) -> User:
+    cached = await cache.get(f"user:{id}")
+    if cached:
+        return User.model_validate_json(cached)
+    user = await db.get(User, id)
+    await cache.setex(f"user:{id}", 300, user.model_dump_json())
+    return user
+```
+
+## FORBIDDEN
+
+1. **Premature optimization** — profile FIRST, optimize SECOND
+2. **`+` for string concatenation in loops** — use `"".join()`
+3. **`list` for membership testing** — use `set`
+4. **Loading entire dataset in memory** — use generators/pagination
+5. **Individual DB inserts in loop** — use bulk operations

package/stacks/python/stack.json

@@ -0,0 +1,45 @@
+{
+  "id": "python",
+  "name": "Python 3.12+",
+  "icon": "🐍",
+  "runtime": "python",
+  "requirements": [
+    { "command": "python3", "minVersion": "3.12.0", "install": "brew install python@3.12" },
+    { "command": "pip3", "minVersion": "23.0", "install": "python3 -m ensurepip --upgrade" },
+    { "command": "uv", "minVersion": "0.1.0", "install": "curl -LsSf https://astral.sh/uv/install.sh | sh", "optional": true }
+  ],
+  "frameworks": [
+    { "id": "fastapi", "name": "FastAPI + Uvicorn", "icon": "⚡" },
+    { "id": "django", "name": "Django 5+", "icon": "🎸" },
+    { "id": "flask", "name": "Flask", "icon": "🧪" },
+    { "id": "vanilla", "name": "Vanilla Python", "icon": "🐍" }
+  ],
+  "databases": [
+    { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
+    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬" },
+    { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
+    { "id": "sqlite", "name": "SQLite", "icon": "📦" }
+  ],
+  "frontendOptions": [
+    { "id": "react", "name": "React (SPA)", "icon": "⚛️" },
+    { "id": "htmx", "name": "HTMX + Jinja2", "icon": "🔄" },
+    { "id": "none", "name": "API only (no frontend)", "icon": "🔌" }
+  ],
+  "deployTargets": [
+    { "id": "github", "name": "GitHub (git push)", "icon": "🐙" }
+  ],
+  "skills": [
+    "python-patterns",
+    "fastapi-patterns",
+    "django-patterns",
+    "pydantic-validation",
+    "pytest-testing",
+    "async-patterns",
+    "python-performance"
+  ],
+  "qualityGates": [
+    { "name": "mypy", "command": "mypy .", "description": "Type checking" },
+    { "name": "ruff", "command": "ruff check .", "description": "Linting" },
+    { "name": "pytest", "command": "pytest --tb=short", "description": "Tests" }
+  ]
+}