# ${PROJECT_NAME} — Agent Context

> Guidelines for AI agents working on this Django project.
> **Update this file** when you discover reusable patterns or non-obvious requirements.

## Codebase Patterns

- **Django project:** Standard Django project layout
- **Database:** PostgreSQL with Django ORM
- **API:** Django REST Framework for REST endpoints
- **Tasks:** Celery for background/async tasks
- **Config:** Environment variables via `.env` / `python-dotenv`

## Common Gotchas

- **Run migrations** after model changes: `python manage.py makemigrations && python manage.py migrate`
- **Import order matters:** Django setup must happen before model imports
- **Celery tasks** must be importable from `tasks.py` in each app
- **Settings module:** Check `DJANGO_SETTINGS_MODULE` environment variable
- **Test database:** Tests use a separate database — check `TEST` config in settings
- **Static files:** Run `collectstatic` before deployment

## Context Management

| Strategy | When |
|----------|------|
| **Spawn sub-agents** | Isolated coding tasks, research |
| **Batch operations** | Group related operations |
| **Check existing patterns** | Before writing new code |
| **Minimize re-reading** | Don't re-read files you just wrote |

## Quality Gates

**All must pass before any commit:**

```bash
ruff check . && mypy . && pytest tests/
```

## Orchestrator Integration

### Task Prefix
Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).

### Worker Checklist
1. Read the finding details from the report
2. Implement the fix following existing patterns
3. Run quality gates (ALL must pass)
4. Commit: `git commit -m "fix({finding_id}): brief description"`
5. Push: `git push origin {branch}`
6. Report result as JSON

### Post-Coding Review
After implementing changes, the orchestrator will run:
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
3. If blockers/critical findings: remediation task created
4. If clean: task marked done

## Key Files

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Project overview and conventions |
| `pyproject.toml` | Python dependencies and tool config |
| `${SOURCE_DIR}/manage.py` | Django management entry point |
| `.env.example` | Required environment variables |

## Testing Approaches

- Unit tests: `pytest` with fixtures in `conftest.py`
- API tests: DRF's `APITestCase` or pytest with `api_client` fixture
- Database tests: Use `@pytest.mark.django_db` decorator
- Mocking: `unittest.mock.patch` for external services
- Minimum 85% coverage for new code

---

_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._