docs initial

.codex/agent-team.md

@@ -0,0 +1,87 @@
+# 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/`.