start-vibing-stacks 2.5.0 → 2.6.0

package/dist/detector.js

@@ -114,10 +114,8 @@ export function detectNodeFramework(projectDir) {
     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)) {
@@ -128,5 +126,10 @@ export function detectPythonFramework(projectDir) {
                 return 'flask';
         }
     }
+    // If Python project detected but no web framework, suggest scripts
+    if (existsSync(join(projectDir, 'main.py')) &&
+        !existsSync(join(projectDir, 'app', 'main.py'))) {
+        return 'scripts';
+    }
     return null;
 }

package/dist/scanner.js

@@ -322,6 +322,69 @@ function scanEslintConfig(projectDir) {
         ],
     };
 }
+// ─── Python Scanners ───────────────────────────────────────────────────────
+const PYTHON_PACKAGES = {
+    'fastapi': { category: 'framework', name: 'FastAPI framework' },
+    'django': { category: 'framework', name: 'Django framework' },
+    'flask': { category: 'framework', name: 'Flask framework' },
+    'uvicorn': { category: 'server', name: 'Uvicorn ASGI server' },
+    'gunicorn': { category: 'server', name: 'Gunicorn WSGI server' },
+    'sqlalchemy': { category: 'database', name: 'SQLAlchemy ORM' },
+    'alembic': { category: 'database', name: 'Alembic migrations' },
+    'asyncpg': { category: 'database', name: 'asyncpg (PostgreSQL async)' },
+    'psycopg': { category: 'database', name: 'psycopg (PostgreSQL)' },
+    'mariadb': { category: 'database', name: 'MariaDB connector' },
+    'pymongo': { category: 'database', name: 'PyMongo (MongoDB)' },
+    'beanie': { category: 'database', name: 'Beanie ODM (MongoDB)' },
+    'motor': { category: 'database', name: 'Motor (MongoDB async)' },
+    'pydantic': { category: 'validation', name: 'Pydantic v2 validation' },
+    'pydantic-settings': { category: 'config', name: 'Pydantic Settings' },
+    'httpx': { category: 'http', name: 'httpx HTTP client' },
+    'tenacity': { category: 'reliability', name: 'tenacity retry logic' },
+    'celery': { category: 'queue', name: 'Celery task queue' },
+    'arq': { category: 'queue', name: 'ARQ async task queue' },
+    'redis': { category: 'cache', name: 'Redis client' },
+    'pytest': { category: 'testing', name: 'pytest testing' },
+    'pytest-asyncio': { category: 'testing', name: 'pytest async support' },
+    'mypy': { category: 'quality', name: 'mypy type checker' },
+    'ruff': { category: 'quality', name: 'ruff linter + formatter' },
+    'rich': { category: 'ui', name: 'rich CLI output' },
+    'typer': { category: 'cli', name: 'Typer CLI framework' },
+    'click': { category: 'cli', name: 'Click CLI framework' },
+    'stripe': { category: 'billing', name: 'Stripe payments' },
+    'google-ads': { category: 'ads', name: 'Google Ads API' },
+    'facebook-business': { category: 'ads', name: 'Facebook/Meta Ads API' },
+    'python-wordpress-xmlrpc': { category: 'cms', name: 'WordPress XML-RPC client' },
+};
+function scanPyprojectToml(projectDir) {
+    const content = readFileIfExists(join(projectDir, 'pyproject.toml')) ||
+        readFileIfExists(join(projectDir, 'requirements.txt'));
+    if (!content)
+        return null;
+    const patterns = [];
+    const lowerContent = content.toLowerCase();
+    for (const [pkg, meta] of Object.entries(PYTHON_PACKAGES)) {
+        if (lowerContent.includes(pkg.toLowerCase())) {
+            patterns.push({
+                category: meta.category,
+                name: meta.name,
+                confidence: 95,
+                detail: `Found: ${pkg}`,
+            });
+        }
+    }
+    const pythonVersionMatch = content.match(/requires-python\s*=\s*"([^"]+)"/i);
+    if (pythonVersionMatch) {
+        patterns.push({
+            category: 'runtime',
+            name: `Python version constraint: ${pythonVersionMatch[1]}`,
+            confidence: 100,
+        });
+    }
+    if (patterns.length === 0)
+        return null;
+    return { source: 'pyproject.toml', patterns };
+}
 // ─── Shared Scanners ───────────────────────────────────────────────────────
 function scanProjectFiles(projectDir) {
     const patterns = [];
@@ -399,6 +462,33 @@ function scanProjectFiles(projectDir) {
     else if (existsSync(join(projectDir, 'yarn.lock'))) {
         patterns.push({ category: 'runtime', name: 'Yarn package manager in use', confidence: 100 });
     }
+    // ── Python: Project configs ──
+    if (existsSync(join(projectDir, 'pyproject.toml'))) {
+        patterns.push({ category: 'runtime', name: 'pyproject.toml present (modern Python)', confidence: 100 });
+    }
+    if (existsSync(join(projectDir, 'uv.lock'))) {
+        patterns.push({ category: 'runtime', name: 'uv package manager in use', confidence: 100 });
+    }
+    else if (existsSync(join(projectDir, 'Pipfile.lock'))) {
+        patterns.push({ category: 'runtime', name: 'Pipenv package manager in use', confidence: 100 });
+    }
+    if (existsSync(join(projectDir, 'mypy.ini')) || existsSync(join(projectDir, '.mypy.ini'))) {
+        patterns.push({ category: 'quality', name: 'mypy config present', confidence: 100 });
+    }
+    if (existsSync(join(projectDir, 'ruff.toml')) || existsSync(join(projectDir, '.ruff.toml'))) {
+        patterns.push({ category: 'quality', name: 'ruff config present', confidence: 100 });
+    }
+    if (existsSync(join(projectDir, 'alembic.ini'))) {
+        patterns.push({ category: 'database', name: 'Alembic migrations present', confidence: 100 });
+    }
+    if (existsSync(join(projectDir, 'pytest.ini')) || existsSync(join(projectDir, 'pyproject.toml'))) {
+        if (existsSync(join(projectDir, 'tests'))) {
+            patterns.push({ category: 'testing', name: 'pytest test directory present', confidence: 90 });
+        }
+    }
+    if (existsSync(join(projectDir, '.pre-commit-config.yaml'))) {
+        patterns.push({ category: 'quality', name: 'pre-commit hooks configured', confidence: 100 });
+    }
     // ── Deploy targets ──
     if (existsSync(join(projectDir, 'vercel.json'))) {
         patterns.push({ category: 'deploy', name: 'Vercel deployment config', confidence: 100 });
@@ -485,6 +575,7 @@ export function scanProjectStandards(projectDir) {
         scanPackageJson,
         scanTsConfig,
         scanEslintConfig,
+        scanPyprojectToml,
         scanProjectFiles,
     ];
     const results = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.5.0",
+  "version": "2.6.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/python-patterns/SKILL.md

@@ -6,11 +6,13 @@
 
 ```
 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
+├── API / Microservices       → FastAPI (async, Pydantic, fast)
+├── Full-stack / CMS / Admin  → Django (batteries-included)
+├── Lightweight web app       → Flask (minimal)
+├── AI/ML API serving         → FastAPI (Pydantic, uvicorn)
+├── Local scripts / automation → Scripts (httpx, argparse, rich)
+├── WordPress / Ads / ETL     → Scripts (no framework needed)
+└── Background workers        → Celery + any framework
 ```
 
 ## Async vs Sync
@@ -74,6 +76,20 @@ myproject/
 └── tests/
 ```
 
+### Local Scripts / Automation
+```
+project/
+├── main.py           # CLI entry (argparse + match/case)
+├── scripts/          # One module per task
+├── lib/
+│   ├── config.py     # Pydantic Settings (.env)
+│   ├── http_client.py # httpx + tenacity retry
+│   └── logger.py     # rich logging
+├── data/             # Input/output files
+├── logs/
+└── tests/
+```
+
 ## Error Handling
 
 ```python

package/stacks/python/skills/scripting-automation/SKILL.md

@@ -0,0 +1,255 @@
+# Local Scripts & Automation — Python 3.12+
+
+**ALWAYS invoke when building local scripts, CLI tools, or automation tasks.**
+
+## When to Use
+
+- WordPress API automation (create/update posts, manage media)
+- Ad campaign management (Google Ads, Facebook Ads, TikTok Ads API)
+- Data pipelines (CSV/Excel processing, database sync)
+- Web scraping and data extraction
+- File system operations and batch processing
+- Scheduled tasks and cron-like automation
+- API integrations without a web framework
+
+## Project Structure
+
+```
+project/
+├── pyproject.toml        # Dependencies + project metadata
+├── .env                  # API keys, credentials (NEVER commit)
+├── .env.example          # Template without real values
+├── scripts/
+│   ├── __init__.py
+│   ├── wordpress.py      # WordPress automation
+│   ├── ads_manager.py    # Ad campaigns
+│   └── data_sync.py      # Database sync
+├── lib/
+│   ├── __init__.py
+│   ├── http_client.py    # Reusable httpx client
+│   ├── config.py         # Pydantic Settings
+│   ├── logger.py         # Structured logging
+│   └── retry.py          # Retry with backoff
+├── data/                 # Input/output data files
+├── logs/                 # Log files
+├── tests/
+│   └── test_scripts.py
+└── main.py               # Entry point / CLI
+```
+
+## Configuration (Pydantic Settings)
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    WP_URL: str
+    WP_USER: str
+    WP_APP_PASSWORD: str
+
+    GOOGLE_ADS_DEVELOPER_TOKEN: str = ""
+    FACEBOOK_ACCESS_TOKEN: str = ""
+    TIKTOK_ACCESS_TOKEN: str = ""
+
+    DB_HOST: str = "localhost"
+    DB_PORT: int = 3306
+    DB_NAME: str
+    DB_USER: str
+    DB_PASSWORD: str
+
+    LOG_LEVEL: str = "INFO"
+    DRY_RUN: bool = False
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+settings = Settings()
+```
+
+## HTTP Client (reusable)
+
+```python
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+class ApiClient:
+    def __init__(self, base_url: str, auth: tuple[str, str] | None = None):
+        self.client = httpx.Client(
+            base_url=base_url,
+            auth=auth,
+            timeout=30.0,
+            headers={"User-Agent": "AutomationScript/1.0"},
+        )
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def get(self, path: str, **kwargs) -> dict:
+        r = self.client.get(path, **kwargs)
+        r.raise_for_status()
+        return r.json()
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def post(self, path: str, **kwargs) -> dict:
+        r = self.client.post(path, **kwargs)
+        r.raise_for_status()
+        return r.json()
+
+    def close(self):
+        self.client.close()
+```
+
+## WordPress REST API Pattern
+
+```python
+from lib.http_client import ApiClient
+from lib.config import settings
+
+wp = ApiClient(
+    base_url=f"{settings.WP_URL}/wp-json/wp/v2",
+    auth=(settings.WP_USER, settings.WP_APP_PASSWORD),
+)
+
+def create_post(title: str, content: str, status: str = "draft") -> dict:
+    return wp.post("/posts", json={
+        "title": title,
+        "content": content,
+        "status": status,
+    })
+
+def update_post(post_id: int, **fields) -> dict:
+    return wp.post(f"/posts/{post_id}", json=fields)
+
+def bulk_update_posts(posts: list[dict]) -> list[dict]:
+    results = []
+    for post in posts:
+        pid = post.pop("id")
+        result = update_post(pid, **post)
+        results.append(result)
+        logger.info(f"Updated post {pid}: {result['title']['rendered']}")
+    return results
+```
+
+## Database Access (direct, no ORM)
+
+```python
+import mariadb
+from contextlib import contextmanager
+from lib.config import settings
+
+@contextmanager
+def get_connection():
+    conn = mariadb.connect(
+        host=settings.DB_HOST,
+        port=settings.DB_PORT,
+        user=settings.DB_USER,
+        password=settings.DB_PASSWORD,
+        database=settings.DB_NAME,
+    )
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+def fetch_all(query: str, params: tuple = ()) -> list[dict]:
+    with get_connection() as conn:
+        cursor = conn.cursor(dictionary=True)
+        cursor.execute(query, params)
+        return cursor.fetchall()
+
+def execute(query: str, params: tuple = ()) -> int:
+    with get_connection() as conn:
+        cursor = conn.cursor()
+        cursor.execute(query, params)
+        conn.commit()
+        return cursor.rowcount
+```
+
+## CLI Entry Point
+
+```python
+import argparse
+import logging
+from lib.config import settings
+
+logging.basicConfig(
+    level=getattr(logging, settings.LOG_LEVEL),
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    handlers=[
+        logging.StreamHandler(),
+        logging.FileHandler("logs/script.log"),
+    ],
+)
+logger = logging.getLogger(__name__)
+
+def main():
+    parser = argparse.ArgumentParser(description="Automation Scripts")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("wp-sync", help="Sync WordPress posts")
+    sub.add_parser("ads-report", help="Generate ads performance report")
+    sub.add_parser("db-migrate", help="Run data migration")
+
+    args = parser.parse_args()
+
+    if settings.DRY_RUN:
+        logger.warning("DRY RUN mode — no changes will be saved")
+
+    match args.command:
+        case "wp-sync":
+            from scripts.wordpress import sync_posts
+            sync_posts()
+        case "ads-report":
+            from scripts.ads_manager import generate_report
+            generate_report()
+        case "db-migrate":
+            from scripts.data_sync import run_migration
+            run_migration()
+        case _:
+            parser.print_help()
+
+if __name__ == "__main__":
+    main()
+```
+
+## Essential Libraries
+
+```toml
+# pyproject.toml
+[project]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic-settings>=2.0",
+    "tenacity>=8.0",
+    "python-dotenv>=1.0",
+    "mariadb>=1.1",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "mypy>=1.8", "ruff>=0.3"]
+ads = ["google-ads>=24.0", "facebook-business>=19.0"]
+```
+
+## Logging (structured)
+
+```python
+from rich.console import Console
+from rich.logging import RichHandler
+import logging
+
+console = Console()
+logging.basicConfig(
+    level="INFO",
+    format="%(message)s",
+    handlers=[RichHandler(console=console, rich_tracebacks=True)],
+)
+```
+
+## FORBIDDEN
+
+1. **Hardcoded credentials** — use `.env` + Pydantic Settings
+2. **No error handling on API calls** — always try/except + retry
+3. **No logging** — every script must log actions and errors
+4. **`requests` library** — use `httpx` (modern, sync+async)
+5. **Print statements for output** — use `logging` or `rich`
+6. **No `--dry-run` flag** — destructive scripts must support dry run
+7. **SQL without parameterization** — always use `?` placeholders
+8. **No `.env.example`** — always provide template for credentials

package/stacks/python/stack.json

@@ -2,44 +2,97 @@
   "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 }
+  "runtime": "Python 3.12+",
+  "minVersion": "3.12.0",
+  "packageManager": "uv|pip",
+  "extensions": [".py", ".pyi"],
+  "testExtensions": ["test_*.py", "*_test.py"],
+  "detectFiles": ["pyproject.toml", "requirements.txt", "Pipfile", "setup.py", "manage.py"],
+  "commands": {
+    "test": "pytest --tb=short",
+    "lint": "ruff check .",
+    "format": "ruff format .",
+    "serve": "uvicorn app.main:app --reload",
+    "typecheck": "mypy ."
+  },
+  "qualityGates": [
+    { "name": "mypy", "command": "mypy .", "required": true, "order": 1 },
+    { "name": "ruff", "command": "ruff check .", "required": true, "order": 2 },
+    { "name": "pytest", "command": "pytest --tb=short", "required": true, "order": 3 }
   ],
   "frameworks": [
-    { "id": "fastapi", "name": "FastAPI + Uvicorn", "icon": "⚡" },
-    { "id": "django", "name": "Django 5+", "icon": "🎸" },
-    { "id": "flask", "name": "Flask", "icon": "🧪" },
-    { "id": "vanilla", "name": "Vanilla Python", "icon": "🐍" }
+    {
+      "id": "fastapi",
+      "name": "FastAPI + Uvicorn",
+      "icon": "⚡",
+      "detectFiles": ["app/main.py"],
+      "default": true,
+      "skills": ["fastapi-patterns", "async-patterns"]
+    },
+    {
+      "id": "django",
+      "name": "Django 5+",
+      "icon": "🎸",
+      "detectFiles": ["manage.py"],
+      "skills": ["django-patterns"]
+    },
+    {
+      "id": "flask",
+      "name": "Flask",
+      "icon": "🧪",
+      "detectFiles": ["app.py", "wsgi.py"],
+      "skills": []
+    },
+    {
+      "id": "scripts",
+      "name": "Local Scripts / Automation",
+      "icon": "🤖",
+      "skills": ["scripting-automation"]
+    }
   ],
   "databases": [
+    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬", "default": true },
     { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
-    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬" },
+    { "id": "sqlite", "name": "SQLite (local)", "icon": "📦" },
     { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
-    { "id": "sqlite", "name": "SQLite", "icon": "📦" }
+    { "id": "none", "name": "No database", "icon": "⬜" }
   ],
   "frontendOptions": [
-    { "id": "react", "name": "React (SPA)", "icon": "⚛️" },
-    { "id": "htmx", "name": "HTMX + Jinja2", "icon": "🔄" },
-    { "id": "none", "name": "API only (no frontend)", "icon": "🔌" }
+    { "id": "react", "name": "React (SPA)", "icon": "⚛️", "frameworks": ["fastapi", "flask", "django"] },
+    { "id": "htmx", "name": "HTMX + Jinja2", "icon": "🔄", "frameworks": ["fastapi", "flask", "django"] },
+    { "id": "none", "name": "API only / CLI only", "icon": "🔌", "default": true }
   ],
   "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" }
+  "requirements": [
+    {
+      "name": "Python",
+      "command": "python3",
+      "versionFlag": "--version",
+      "minVersion": "3.12.0",
+      "installCommand": {
+        "macos": "brew install python@3.12",
+        "linux": "sudo apt install -y python3.12 python3.12-venv"
+      },
+      "versionRegex": "Python\\s+(\\d+\\.\\d+\\.\\d+)"
+    },
+    {
+      "name": "pip",
+      "command": "pip3",
+      "versionFlag": "--version",
+      "minVersion": "23.0.0",
+      "installCommand": {
+        "macos": "python3 -m ensurepip --upgrade",
+        "linux": "python3 -m ensurepip --upgrade"
+      },
+      "versionRegex": "pip\\s+(\\d+\\.\\d+\\.?\\d*)"
+    }
   ]
 }

package/templates/CLAUDE-python.md

@@ -0,0 +1,315 @@
+# {{PROJECT_NAME}}
+
+> **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
+
+## Last Change
+
+**Branch:** main
+**Date:** {{DATE}}
+**Summary:** Initial project setup with start-vibing-stacks (Python)
+
+## 30 Seconds Overview
+
+{{PROJECT_NAME}} is a Python 3.12+ project using {{FRAMEWORK}}.
+
+## Stack
+
+| Component | Technology |
+|-----------|------------|
+| Language | Python >= 3.12 |
+| Framework | {{FRAMEWORK}} |
+| Database | {{DATABASE}} |
+| Type Checking | mypy (strict) |
+| Linting | ruff |
+| Testing | pytest + pytest-asyncio |
+| Validation | Pydantic v2 |
+| HTTP Client | httpx |
+| Package Manager | uv / pip |
+
+## Architecture
+
+### FastAPI / Flask Projects
+
+```
+project/
+├── CLAUDE.md                # This file (40k char max)
+├── pyproject.toml           # Dependencies + project config
+├── .env                     # Secrets (NEVER commit)
+├── .env.example             # Template without values
+├── .claude/
+│   ├── agents/              # 6 active subagents
+│   ├── skills/              # Skill systems (auto-injected)
+│   ├── hooks/               # Validation hooks
+│   ├── config/              # Project configuration
+│   └── commands/            # Slash commands
+├── app/
+│   ├── main.py              # App entrypoint + startup
+│   ├── api/v1/
+│   │   ├── routes/          # Endpoint modules
+│   │   └── deps.py          # Dependencies (auth, db)
+│   ├── models/              # SQLAlchemy / Beanie models
+│   ├── schemas/             # Pydantic schemas
+│   ├── services/            # Business logic layer
+│   ├── core/
+│   │   ├── config.py        # Pydantic Settings (env)
+│   │   └── security.py      # Auth, hashing
+│   └── utils/               # Helpers
+├── scripts/                 # CLI scripts / automation
+├── tests/
+│   ├── conftest.py          # Shared fixtures
+│   ├── unit/
+│   └── integration/
+└── alembic/                 # DB migrations (if SQL)
+```
+
+### Local Scripts / Automation Projects
+
+```
+project/
+├── CLAUDE.md
+├── pyproject.toml
+├── .env
+├── .env.example
+├── .claude/
+├── main.py                  # CLI entry point (argparse)
+├── scripts/
+│   ├── __init__.py
+│   ├── wordpress.py         # WordPress API automation
+│   ├── ads_manager.py       # Google/Facebook/TikTok Ads
+│   └── data_sync.py         # Database sync / ETL
+├── lib/
+│   ├── __init__.py
+│   ├── config.py            # Pydantic Settings
+│   ├── http_client.py       # Reusable httpx client
+│   ├── logger.py            # Structured logging (rich)
+│   └── retry.py             # tenacity retry logic
+├── data/                    # Input/output data files
+├── logs/                    # Log files
+└── tests/
+```
+
+### Django Projects
+
+```
+project/
+├── CLAUDE.md
+├── pyproject.toml
+├── manage.py
+├── config/                  # Settings, URLs, ASGI
+├── apps/
+│   ├── users/               # Per-app: models, views, serializers, tests
+│   └── products/
+└── tests/
+```
+
+## Critical Rules
+
+### Python 3.12+ (MANDATORY)
+
+- **Type hints on ALL public functions** — parameters, returns, class attributes
+- **Pydantic v2 for all data boundaries** — API schemas, config, external data
+- **`match/case`** for complex branching (3.10+)
+- **`type` keyword** for simple type aliases (3.12+)
+- **f-strings** everywhere, never `%` or `.format()`
+- **Structural pattern matching** over nested if/elif chains
+
+### Code Organization
+
+- **Thin routes, fat services** — business logic in `services/`, not in routes/views
+- **Repository pattern** for database access — isolate queries from business logic
+- **Dependency injection** — FastAPI `Depends()`, Django class-based views
+- **One concern per module** — a file should do one thing well
+
+### Environment Variables & Secrets (MANDATORY)
+
+```python
+# CORRECT: Pydantic Settings loads from .env
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    DATABASE_URL: str
+    SECRET_KEY: str
+    API_TOKEN: str
+    model_config = {"env_file": ".env"}
+
+settings = Settings()
+```
+
+| Rule | Reason |
+|------|--------|
+| All secrets in `.env` | Never hardcode credentials |
+| `.env` in `.gitignore` | Never commit secrets |
+| `.env.example` always present | Document required variables |
+| Pydantic Settings for loading | Typed, validated, auto-parsed |
+| `--dry-run` flag for destructive scripts | Prevent accidental data loss |
+
+### Async vs Sync
+
+| Workload | Pattern |
+|----------|---------|
+| I/O-bound (HTTP, DB, files) | `async def` + `httpx` / `asyncpg` |
+| CPU-bound (parsing, computation) | `def` + `multiprocessing` / `concurrent.futures` |
+| Local scripts (simple) | Sync is fine unless hitting APIs in bulk |
+| Bulk API calls | `async def` + `asyncio.gather` + semaphore |
+
+### Database Safety
+
+- **Parameterized queries ALWAYS** — `cursor.execute(query, params)`
+- **Connection context managers** — auto-close on exit
+- **Migrations** — Alembic (FastAPI) or Django `makemigrations`
+- **Pool connections** in production — `pool_size` + `max_overflow`
+
+## Quality Gates
+
+```bash
+mypy .                    # Type checking (MUST pass)
+ruff check .              # Linting (MUST pass)
+ruff format . --check     # Format check
+pytest --tb=short         # Tests (MUST pass)
+```
+
+## FORBIDDEN
+
+### Security (CRITICAL)
+
+| Action | Reason |
+|--------|--------|
+| Hardcoded API keys/passwords | Use `.env` + Pydantic Settings |
+| Commit `.env` files | Secrets leak to repository |
+| SQL without parameterization | SQL injection |
+| Deserializing untrusted binary data | Remote code execution risk |
+| `yaml.load()` without SafeLoader | Code injection |
+| No input validation on external data | Use Pydantic models |
+| Storing plaintext passwords | Use `passlib` / `bcrypt` |
+
+### Code Quality
+
+| Action | Reason |
+|--------|--------|
+| `import *` | Explicit imports only |
+| `requests` library | Use `httpx` (modern, sync+async) |
+| `print()` for logging | Use `logging` module or `rich` |
+| No type hints on public APIs | mypy must pass |
+| Business logic in routes/views | Use services layer |
+| Bare `except Exception` | Catch specific exceptions |
+| `time.sleep()` in async code | Use `await asyncio.sleep()` |
+| Sync HTTP in async context | Blocks the event loop |
+| Global mutable state | Use dependency injection |
+| Files > 400 lines | Split into modules |
+
+### Workflow
+
+| Action | Reason |
+|--------|--------|
+| Skip tests | Quality gate blocks commit |
+| Skip type checking | mypy catches runtime errors |
+| No `.env.example` | Others can't configure project |
+| No `--dry-run` on destructive scripts | Risk of accidental data loss |
+| Commit directly to main | Use feature branches |
+
+## CLAUDE.md Update Rules
+
+### When to Update
+
+| Change Type | What to Update |
+|-------------|----------------|
+| Any file change | Last Change section |
+| New feature | 30s Overview, Architecture if needed |
+| New pattern | Add to relevant section |
+| Gotcha discovered | Add to FORBIDDEN or NRY |
+| New dependency | Update Stack table |
+
+### Last Change Format (MANDATORY)
+
+```markdown
+## Last Change
+
+**Branch:** feature/example
+**Date:** YYYY-MM-DD
+**Summary:** 1-2 sentences describing WHAT and WHY.
+```
+
+## Agent System
+
+| Agent | Purpose |
+|-------|---------|
+| research-web | Researches best practices (MANDATORY for new features) |
+| documenter | Maps files to domains, tracks what exists |
+| domain-updater | Records problems, solutions, learnings |
+| commit-manager | Manages commits and merges |
+| tester | Creates tests with pytest |
+| claude-md-compactor | Compacts CLAUDE.md when over 40k chars |
+
+### Skills
+
+| Category | Skills |
+|----------|--------|
+| **Core** | python-patterns, pydantic-validation, pytest-testing, python-performance |
+| **Framework** | fastapi-patterns, django-patterns, async-patterns, scripting-automation |
+| **UI** | ui-ux-pro-max (auto-installed for frontend projects) |
+
+## Domain Documentation
+
+### Location
+
+```
+.claude/skills/codebase-knowledge/domains/
+├── api.md
+├── database.md
+├── scripts.md
+└── ...
+```
+
+### Documentation Agents
+
+| Agent | Role | When |
+|-------|------|------|
+| **documenter** | Maps files to domains | AFTER implementation |
+| **domain-updater** | Records problems + solutions | BEFORE commit |
+
+## Workflow
+
+```
+1. TODO LIST → Create detailed task list
+2. RESEARCH → Run research agent for new features
+3. BRANCH → Create feature/ | fix/ | refactor/ | test/
+4. IMPLEMENT → Follow skills + type everything
+5. QUALITY → mypy → ruff → pytest (all must pass)
+6. DOCUMENT → Update domains + CLAUDE.md
+7. COMMIT → Conventional commit format
+```
+
+## Commit Format
+
+```
+[type]: [description]
+
+- Detail 1
+- Detail 2
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
+
+## NRY (Never Repeat Yourself)
+
+- Always check `.claude/skills/` before implementing patterns from scratch
+- Use `tenacity` for retry logic, not hand-rolled loops
+- Use `pydantic_settings` for env config, not `os.getenv()` manually
+- Use `httpx` for HTTP, never `urllib` or `requests`
+- Use `rich` for CLI output, not bare `print()`
+
+## Configuration
+
+Project-specific settings in `.claude/config/`:
+
+- `active-project.json` — Stack, framework, database, skills
+- `security-rules.json` — Security audit rules
+- `standards-review.json` — Imported project standards (if adapted)
+
+## Setup by start-vibing
+
+This project was set up with `npx start-vibing-stacks`.
+For updates: `npx start-vibing-stacks --force`