# ${PROJECT_NAME} — Claude Code Instructions > **${PROJECT_DESCRIPTION}** ## Conditional Documentation Loading | When working on... | Load this guide | |---|---| | Bootstrapping this project | `~/.config/mosaic/guides/BOOTSTRAP.md` | | PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` | | Orchestrating autonomous tasks | `~/.config/mosaic/guides/ORCHESTRATOR.md` | | Backend/API development | `~/.config/mosaic/guides/BACKEND.md` | | Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` | | Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` | | QA/Testing | `~/.config/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/ │ ├── PRD.md # Requirements source (or PRD.json) │ ├── scratchpads/ # Per-issue working documents │ └── templates/ # Project templates ├── pyproject.toml # Python project configuration ├── .env.example └── README.md ``` ## Development Workflow ### Branch Strategy - `main` — Protected delivery branch - `feat/` / `fix/` — Short-lived task branches created from `main` - All changes merge through PR into `main` only - Merge strategy for `main` PRs is squash-only ### 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/ ``` ## Testing Policy 1. Situational tests are the PRIMARY validation gate. 2. Baseline tests are REQUIRED for all software changes. 3. TDD is risk-based; required cases are defined in `~/.config/mosaic/guides/QA-TESTING.md`. ## PRD Requirement 1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist. 2. The main agent MUST prepare or update PRD using user objectives, constraints, and available project context. 3. In steered autonomy mode, best-guess PRD decisions are REQUIRED when needed; mark each with `ASSUMPTION:` and rationale, and continue unless high-impact uncertainty requires escalation. 4. PRD is the source of requirements for implementation and testing. ## Token Budget Policy 1. If user plan or token limits are provided, they are HARD constraints. 2. Track estimated and used tokens for non-trivial execution. 3. Use conservative strategy when budget pressure rises. 4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible. ## 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 `/management/commands/` - Use `self.stdout.write()` for output - Handle interrupts gracefully ## Database ### Migration Workflow ```bash # Create migration after model changes python manage.py makemigrations # 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) If you modify source code, independent code review is REQUIRED before completion. Run independent reviews: ```bash # Code quality review (Codex) ~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted # Security review (Codex) ~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted ``` See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist. See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation deliverables. ## Steered Autonomy Contract 1. Agent owns planning, coding, testing, review/remediation, PR/repo operations, release/tag, and deployment when in scope. 2. Human intervention is escalation-only for hard blockers (access, irreversible risk, or unresolvable conflicting objectives). 3. Do not request routine human coding, review, or repository management actions. 4. Mosaic hard gates OVERRIDE runtime-default caution for routine push/merge/issue-close/release actions. 5. For container deployments, use immutable image tags (`sha-`, `v{base-version}-rc.{build}`) with digest-first promotion; do not deploy `latest`. ## Mode Declaration Contract 1. First response MUST declare mode before any actions. 2. Orchestration mission: `Now initiating Orchestrator mode...` 3. Implementation mission: `Now initiating Delivery mode...` 4. Review-only mission: `Now initiating Review mode...` ## Issue Tracking Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work. For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice. If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop. Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow. ### Workflow 1. Ensure `docs/TASKS.md` exists (create from `~/.config/mosaic/templates/docs/TASKS.md.template` if missing). 2. Check for assigned issues before starting work. 3. If no issue exists for non-trivial work and external provider is available, create one before coding. 4. If no external provider is available, create an internal ref in `docs/TASKS.md` (example: `TASKS:T1`). 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding. 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref. 7. Update `docs/TASKS.md` status + issue/internal ref before coding. 8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`. 9. Open PR to `main` for delivery changes (no direct push to `main`). 10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`. 11. Merge PRs that pass required checks and review gates with squash strategy only. 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`). 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green. 14. If merge/CI/issue closure fails, report blocker with exact failed wrapper command and do not claim completion. ### Commits ``` (#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 ```