# Coffee Project Codex Agent Team

## Project
Coffee Project is a video-captioning SaaS with three services:
- `cofee_frontend/`: Next.js 16, React 19, TypeScript, FSD architecture, SCSS Modules, Radix Themes, TanStack Query
- `cofee_backend/`: FastAPI, Python 3.11+, SQLAlchemy async, PostgreSQL, Redis, Dramatiq
- `remotion_service/`: ElysiaJS + Remotion for deterministic caption rendering and S3 integration

All UI text must be in Russian except the product name.

## Team Topology
Codex handles thread orchestration itself. Do not simulate Claude-style manual call-chain bookkeeping. Instead:
- Spawn only when the extra thread materially improves speed or quality.
- Prefer 2-3 focused agents over a full-team fan-out.
- Use leads for multi-specialist coordination inside one domain.
- Use direct specialist consultations for narrow questions.
- Respect the project `agents.max_depth = 2` setting.

## Consultation Default
The repository runs in team-first mode:
- Root Codex should consult the team before any non-trivial repo task, including analysis, implementation, review, or final recommendations.
- For cross-service, ambiguous, or high-risk work, consult `orchestrator` first.
- For single-domain work, consult the narrowest relevant lead first.
- Use direct specialist consultation only when the owner is obvious and routing through a lead would not improve the answer.
- Prefer consultation-sized asks over broad task dumps. Keep the first dispatch small and specific.
- After reading this file, every custom agent should read `.codex/agent-skills.md` and load only the skills that materially match its role and task.
- Purely mechanical actions that cannot materially change behavior, architecture, or risk may stay local.
- If the user explicitly asks to avoid delegation, follow the user instruction and note the exception.

## Roster
### Leads
- `orchestrator`: routes complex tasks and synthesizes cross-domain output
- `architecture_lead`: coordinates backend, frontend, database, remotion, and implementation architecture work
- `quality_lead`: coordinates QA, security, design audit, and performance validation
- `product_lead`: coordinates UX, docs, and ML/product strategy

### Architecture team
- `backend_architect`: backend design, service boundaries, API contracts
- `frontend_architect`: frontend design, FSD boundaries, component architecture
- `db_architect`: PostgreSQL schema, indexing, migrations, query design
- `remotion_engineer`: Remotion rendering pipeline and caption composition work
- `senior_backend_engineer`: backend implementation
- `senior_frontend_engineer`: frontend implementation

### Quality team
- `frontend_qa`: Playwright, Testing Library, accessibility, UI edge cases
- `backend_qa`: pytest, integration testing, API contract verification
- `security_auditor`: auth, input handling, trust boundaries, dependency risk
- `design_auditor`: visual consistency, accessibility, design-system drift
- `performance_engineer`: frontend and backend performance, query and rendering bottlenecks

### Product team
- `ui_ux_designer`: interaction design, visual direction, onboarding, premium UX
- `technical_writer`: documentation, ADRs, runbooks, API/feature docs
- `ml_ai_engineer`: transcription models, speech workflows, ML integration decisions

### Staff
- `devops_engineer`: Docker, CI/CD, deployment, infrastructure
- `debug_specialist`: root-cause analysis across service boundaries

## Shared Operating Rules
Every custom agent should:
- Read this file first.
- Read `.codex/agent-skills.md` next and apply the smallest relevant skill set for the task.
- Read the relevant service-level `CLAUDE.md` before deep analysis.
- Check historical notes in `.codex/memories/<agent_id>/` when that directory exists.
- Cite concrete files and modules in its conclusions.
- Recommend one best path unless the trade-off is genuinely user-facing.

## Delegation Rules
Use Codex-native delegation patterns:
- Use built-in `explorer` for codebase mapping, trace gathering, and read-heavy discovery.
- Use built-in `worker` for bounded implementation when the task does not need a specialized custom agent.
- Leads should make at least one specialist consultation on non-trivial domain work when that extra view can change the answer.
- Specialists should make one focused adjacent-domain consultation when the answer materially depends on another specialty and depth allows.
- Spawn another custom agent only when that domain expert changes the answer.
- Avoid reflexive waiting. Do useful local work while subagents run.
- Close finished agent threads when their output has been integrated.

## Role Boundaries
- Architects design and review structure; they do not default to writing production code.
- Engineers implement and validate bounded changes.
- Leads coordinate, package context, and synthesize results.
- QA, audit, and product roles default to read-only advisory work unless the parent explicitly assigns authored output such as docs.

## Memory Location
Do not use the `.claude/` directory. New persistent team notes belong under `.codex/memories/`, ideally in per-agent subdirectories named after the real agent IDs, such as `.codex/memories/orchestrator/` or `.codex/memories/quality_lead/`.