django-project-setup

What this skill does

# Django 6.0 Project Setup

Automated setup for production-ready Django 6.0 projects with modern tooling.

## What This Skill Does

Creates a complete Django 6.0 project with:

### Modern Stack (2026)
- ✅ **uv** - Fast package manager (no pip/venv needed)
- ✅ **Django 6.0** - Latest version with Python 3.12+ support
- ✅ **PostgreSQL** - Docker Compose + Supabase support
- ✅ **Custom User Model** - UUID primary keys from day 1
- ✅ **direnv** - Automatic environment management
- ✅ **HTMX** - Modern frontend interactivity
- ✅ **OAuth** - Authentication ready (django-oauth-toolkit)
- ✅ **DRF + Pydantic** - Type-safe API schemas
- ✅ **pytest + factory_boy** - Modern testing infrastructure
- ✅ **mypy + ruff** - Type checking and linting
- ✅ **Docker Compose** - Local PostgreSQL container
- ✅ **Makefile** - Common development commands
- ✅ **Full Type Annotations** - AI tooling optimized (Copilot, Cursor, Cody)

## AI Tooling Compatibility

This project template is optimized for AI coding assistants:

- ✅ **Full Type Coverage**: All generated code has comprehensive type annotations
- ✅ **Strict mypy**: `disallow_untyped_defs = true` enforced from day 1
- ✅ **Better Completions**: AI tools understand code context and relationships
- ✅ **Fewer Errors**: Type checking catches issues before runtime
- ✅ **Improved Refactoring**: AI can suggest safer, type-aware refactorings
- ✅ **Self-Documenting**: Type hints serve as inline documentation

Compatible with: GitHub Copilot, Cursor, Cody, Continue, Tabnine, and other AI coding assistants.

### Why This Matters

When you provide full type annotations:
- AI assistants give more accurate code completions
- Auto-import suggestions are more precise
- Refactoring suggestions are type-safe
- Error detection happens as you type
- Generated documentation is more comprehensive

### Directory Structure
```
{project_name}/
├── config/              # Settings and core config
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py      # Core settings
│   │   ├── dev.py       # Development
│   │   └── prod.py      # Production
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── apps/                # Django apps
│   ├── __init__.py
│   └── core/            # Shared utilities
│       ├── models.py    # UUIDModel base class
│       └── ...
├── templates/           # Global templates
├── static/              # Global static files
├── pyproject.toml       # uv dependencies
├── pytest.ini           # Test configuration
├── conftest.py          # Test fixtures
├── docker-compose.yml   # PostgreSQL container
├── Makefile             # Development commands
├── .envrc               # Environment config
├── .env.example         # Environment template
├── manage.py
└── CLAUDE.md            # Project instructions
```

## Usage

```bash
# With Docker PostgreSQL (default)
/django-project-setup myproject

# With Supabase
/django-project-setup myproject --with-supabase
```

The skill will:
1. Parse arguments (project name and optional --with-supabase flag)
2. Ask for first app name (e.g., 'accounts', 'blog', 'api')
3. Create project structure with uv
4. Set up database (Docker Compose or Supabase instructions)
5. Configure direnv environment
6. Install all dependencies
7. Create custom User model with UUID
8. Run initial migrations (or show Supabase setup instructions)
9. Set up testing infrastructure
10. Configure HTMX, OAuth, and DRF
11. Create CLAUDE.md with project patterns

## Requirements

- **Python 3.12+** (Django 6.0 requirement - automatically installed by uv if missing)
- **uv** (will be installed if missing - handles Python version management)
- **direnv** (recommended, will prompt if missing)
- **Docker** (for local PostgreSQL)

## After Setup

### With Docker PostgreSQL (default)

```bash
# Start PostgreSQL
/usr/bin/make start-docker

# Run migrations
/usr/bin/make migrate

# Create superuser (set password in .envrc.local first)
/usr/bin/make createsuperuser

# Start development server
/usr/bin/make runserver

# Run tests
/usr/bin/make test

# Type checking
/usr/bin/make typecheck

# Linting
/usr/bin/make lint
```

Visit http://localhost:8000/admin/ to verify setup.

### With Supabase

```bash
# 1. Complete Supabase setup (see SUPABASE_SETUP.md)
# 2. Add DATABASE_URL to .env.local
# 3. Allow direnv
direnv allow

# Run migrations
uv run python manage.py migrate

# Create superuser
uv run python manage.py createsuperuser

# Start development server
uv run python manage.py runserver

# Run tests
uv run pytest

# Type checking
uv run mypy .

# Linting
uv run ruff check .
```

Visit http://localhost:8000/admin/ to verify setup.

## Execution Instructions

When this skill is invoked with a project name (e.g., `/django-project-setup myproject` or `/django-project-setup myproject --with-supabase`), follow these steps:

### Prerequisites Check

1. **Parse Arguments**:
   ```bash
   # Extract project name (first non-flag argument)
   # Check if --with-supabase flag is present
   # Set use_supabase=true if flag found, false otherwise
   ```

2. Check if uv is installed, install if missing:
   ```bash
   which uv || curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

3. Check if Python 3.12+ is available, install via uv if missing:
   ```bash
   # Check current Python version
   python3 --version 2>/dev/null | grep -q "Python 3.1[2-9]" || \
   # If not found, use uv to install Python 3.12
   uv python install 3.12
   ```

4. Verify current directory or use /tmp if not specified

### Execution Steps

**Step 1: Ask for First App Name**

Use AskUserQuestion to ask:
```
Question: "What should be the first Django app to create?"
Options:
  - "blog" (description: "Blog/content management app")
  - "accounts" (description: "User accounts and profiles")
  - "api" (description: "API endpoints")
  - "core" (description: "Core functionality only")
Header: "First App"
```

**Step 2: Initialize uv Project**

```bash
# Initialize project with Python 3.12+
uv init --python 3.12 {project_name}
builtin cd {project_name}

# Verify .python-version file was created
[ -f .python-version ] && echo "✅ Python version pinned" || echo "3.12" > .python-version
```

**Step 3: Add Core Dependencies**

```bash
uv add django psycopg[binary] django-environ
uv add djangorestframework django-oauth-toolkit django-htmx pydantic
uv add --group dev pytest pytest-django pytest-cov pytest-asyncio
uv add --group dev factory-boy pytest-factoryboy
uv add --group dev mypy django-stubs types-requests
uv add --group dev ruff django-extensions ipython
```

**Step 4: Create Django Project Structure**

```bash
uv run django-admin startproject config .
```

**Step 5: Create Directory Structure**

```bash
mkdir -p apps/core/{migrations,tests}
mkdir -p apps/{first_app_name}/{migrations,tests}
mkdir -p templates/partials
mkdir -p static
mkdir -p config/settings
```

**Step 6: Create Configuration Files**

Use the templates in `templates/` directory to create:

1. `Makefile` - Use Makefile.template (conditionally add Docker targets if use_supabase == false)
2. `.envrc` - Use .envrc.template, configure DATABASE_URL based on use_supabase
3. `.env` - Use .env.template, configure database variables based on use_supabase
4. `.env.example` - Use .env.example.template, configure based on use_supabase
5. `.envrc.local` - Use .envrc.local.template
6. `.gitignore` - Use .gitignore.template
7. `pytest.ini` - Use pytest.ini.template
8. `conftest.py` - Use conftest.py.template
9. `CLAUDE.md` - Use CLAUDE.md.template, replace {project_name} and add database-specific notes

**If use_supabase == false (Docker):**
- Create `docker-compose.yml` - Use docker-compose.yml.template, replace {project_name}

**If use_supabase == true:**
- Create `SUPABASE_SETUP.md` with instructions for Supabase project creation
- Display message: "⚠️  Supabase setup required - see SUPABASE_SETUP.md for instructions"

**Step 7: Split Settings Files**

1. Delete `config/settings.py`
2. Create `config/settings/__init__.py` (