centralize guides and rails under mosaic with runtime compatibility links

templates/agent/projects/django/CLAUDE.md.template

@@ -0,0 +1,168 @@
+# ${PROJECT_NAME} — Claude Code Instructions
+
+> **${PROJECT_DESCRIPTION}**
+
+## Conditional Documentation Loading
+
+| When working on... | Load this guide |
+|---|---|
+| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
+| Backend/API development | `~/.mosaic/guides/backend.md` |
+| Code review | `~/.mosaic/guides/code-review.md` |
+| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Backend** | Django / Django REST Framework |
+| **Database** | PostgreSQL |
+| **Task Queue** | Celery + Redis/Valkey |
+| **Testing** | pytest + pytest-django |
+| **Linting** | ruff |
+| **Type Checking** | mypy |
+| **Deployment** | Docker + docker-compose |
+
+## Repository Structure
+
+```
+${PROJECT_DIR}/
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific patterns and gotchas
+├── ${SOURCE_DIR}/         # Django project root
+│   ├── manage.py
+│   ├── ${PROJECT_SLUG}/   # Django settings module
+│   │   ├── settings.py
+│   │   ├── urls.py
+│   │   └── wsgi.py
+│   └── apps/              # Django applications
+├── tests/                 # Test files
+├── docs/
+│   ├── scratchpads/       # Per-issue working documents
+│   └── templates/         # Project templates
+├── pyproject.toml         # Python project configuration
+├── .env.example
+└── README.md
+```
+
+## Development Workflow
+
+### Branch Strategy
+- `main` — Production-ready code
+- `develop` — Integration branch (if used)
+- `feat/<name>` — Feature branches
+- `fix/<name>` — Bug fix branches
+
+### Starting Work
+```bash
+git pull --rebase
+uv sync                        # or pip install -e ".[dev]"
+```
+
+### Building / Running
+```bash
+python manage.py runserver     # Development server
+python manage.py migrate       # Apply migrations
+python manage.py shell          # Django shell
+```
+
+### Testing
+```bash
+pytest tests/                  # Run all tests
+pytest tests/ -x               # Stop on first failure
+pytest tests/ --cov            # With coverage
+```
+
+### Linting & Type Checking
+```bash
+ruff check .                   # Lint
+ruff format .                  # Format
+mypy .                         # Type check
+```
+
+## Quality Gates
+
+**All must pass before committing:**
+
+```bash
+ruff check . && mypy . && pytest tests/
+```
+
+## Django Conventions
+
+### Models
+- All tunable parameters stored in the database with `get_effective_*()` fallback patterns
+- Always create migrations for model changes: `python manage.py makemigrations`
+- Include migrations in commits
+- Use `models.TextChoices` or `models.IntegerChoices` for enum-like fields
+
+### Views / API
+- Use Django REST Framework for API endpoints
+- Use serializers for validation
+- Use ViewSets for standard CRUD
+- Use permissions classes for authorization
+
+### Management Commands
+- Place in `<app>/management/commands/`
+- Use `self.stdout.write()` for output
+- Handle interrupts gracefully
+
+## Database
+
+### Migration Workflow
+```bash
+# Create migration after model changes
+python manage.py makemigrations <app_name>
+
+# Apply migrations
+python manage.py migrate
+
+# Check for missing migrations
+python manage.py makemigrations --check
+```
+
+### Rules
+- Always create migrations for schema changes
+- Include migrations in commits
+- Use `RunPython` for data migrations
+- Use transactions for multi-table operations
+
+## Code Review
+
+### Independent Review (Automated)
+After completing code changes, run independent reviews:
+
+```bash
+# Code quality review (Codex)
+~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+
+# Security review (Codex)
+~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+```
+
+## Issue Tracking
+
+### Workflow
+1. Check for assigned issues before starting work
+2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
+3. Reference issues in commits: `Fixes #123` or `Refs #123`
+4. Close issues after successful testing
+
+### Commits
+```
+<type>(#issue): Brief description
+
+Fixes #123
+```
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
+
+## Secrets Management
+
+**NEVER hardcode secrets.**
+
+```bash
+# .env.example is committed (with placeholders)
+# .env is NOT committed (contains real values)
+# Load via python-dotenv or django-environ
+```