# ${PROJECT_NAME} — Agent Context

> Patterns, gotchas, and orchestrator integration for AI agents working on this project.
> **Update this file** when you discover reusable patterns or non-obvious requirements.

## Codebase Patterns

<!-- Add project-specific patterns as you discover them -->
<!-- Examples: -->
<!-- - Use `httpx.AsyncClient` for external HTTP calls -->
<!-- - All routes require authentication via `Depends(get_current_user)` -->
<!-- - Config is loaded from environment variables via `settings.py` -->

## Common Gotchas

<!-- Add things that trip up agents -->
<!-- Examples: -->
<!-- - Remember to run migrations after schema changes -->
<!-- - Frontend env vars need NEXT_PUBLIC_ prefix -->
<!-- - Tests require a running PostgreSQL instance -->

## Quality Gates

**All must pass before any commit:**

```bash
${QUALITY_GATES}
```

## Orchestrator Integration

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

### Package/Directory Names
<!-- List key directories the orchestrator needs to know about -->

| Directory | Purpose |
|-----------|---------|
| `${SOURCE_DIR}/` | Main source code |
| `tests/` | Test files |
| `docs/scratchpads/` | Working documents |

### Worker Checklist
When completing an orchestrated task:
1. Read the finding details from the report
2. Implement the fix following existing code patterns
3. Run quality gates (ALL must pass)
4. Commit with: `git commit -m "fix({finding_id}): brief description"`
5. Report result as JSON to orchestrator

### 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

## Directory-Specific Context

<!-- Add sub-AGENTS.md files in subdirectories if needed -->
<!-- Example: -->
<!-- - `src/api/AGENTS.md` — API-specific patterns -->
<!-- - `src/components/AGENTS.md` — Component conventions -->

## Testing Approaches

<!-- Document how tests should be written for this project -->
<!-- Examples: -->
<!-- - Unit tests use pytest with fixtures in conftest.py -->
<!-- - Integration tests require DATABASE_URL env var -->
<!-- - E2E tests use Playwright -->