remotion_service/.codex/agent-team.md

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/.