remotion_service/.claude/agents-shared/team-protocol.md

Coffee Project — Agent Team Protocol

Project

Video captioning SaaS. Three services in a monorepo:

• Frontend (cofee_frontend/): Next.js 16, React 19, TypeScript, FSD architecture, SCSS Modules, Radix Themes, TanStack Query
• Backend (cofee_backend/): FastAPI, Python 3.11+, SQLAlchemy async, PostgreSQL, Redis, Dramatiq
• Remotion (remotion_service/): ElysiaJS + Remotion for deterministic caption rendering, S3 integration

All UI text in Russian (except brand name "Cofee Project").

Backend modules (11): users, projects, media, files, transcription, captions, jobs, notifications, tasks, webhooks, system. Each module: __init__.py, models.py, schemas.py, repository.py, service.py, router.py. No extras.

Cross-service flow: Frontend → Backend API (JWT auth) → Dramatiq (Redis) → Remotion → S3 → WebSocket notification back to Frontend.

Team Roster

Agent	What they do	New Tools	Request when
Orchestrator	Task decomposition, agent routing, context packaging	—	You don't — main session dispatches you
Frontend Architect	Next.js/React/FSD patterns, component architecture	Chrome browser, knip	Frontend architecture decisions, component design
Backend Architect	FastAPI/Python patterns, service design, API contracts	Redis MCP, Postgres MCP, radon, curl	Backend architecture, API design, module structure decisions
DB Architect	PostgreSQL schema, query optimization, migrations	Postgres MCP, squawk	Schema design, query performance, migration strategy
UI/UX Designer	Visual design, interaction patterns, premium aesthetics	Chrome browser, GIF recording	New UI flows, design direction, UX patterns
Design Auditor	Visual consistency, component compliance, accessibility	Chrome browser, Lighthouse MCP, pa11y, knip	Review existing UI, consistency checks, accessibility audits
Frontend QA	Playwright E2E, React testing, edge case discovery	Playwright MCP (all tools)	Frontend test planning, test case design, testing strategy
Backend QA	pytest, integration tests, API contracts, edge cases	Playwright MCP, schemathesis, curl	Backend test planning, test case design, testing strategy
Remotion Engineer	Compositions, animation, video processing, captions	ffprobe, mediainfo, ffmpeg	Remotion code, video processing, caption styling
Security Auditor	OWASP, auth, data protection, dependency auditing	semgrep, bandit, pip-audit, gitleaks	Security review, auth patterns, vulnerability assessment
Performance Engineer	Profiling, caching, bundle analysis, query performance	Chrome browser, Lighthouse MCP, Postgres MCP, k6, hyperfine	Performance issues, optimization, load patterns
Debug Specialist	Root cause analysis, cross-service debugging	Chrome browser, Redis MCP	Bug investigation, root cause analysis
DevOps Engineer	CI/CD, Docker, K8s, infrastructure	Docker MCP	Infrastructure, deployment, CI/CD setup
Product Strategist	Monetization, conversion, feature prioritization, growth	Chrome browser	Business decisions, pricing, feature priority
Technical Writer	Feature docs, API docs, architecture decision records	—	Documentation needs
ML/AI Engineer	Speech-to-text, transcription models, ML deployment	—	Transcription, ML model decisions

Handoff Format

When you need another agent's expertise, include this in your output:

## Handoff Requests

### → <Agent Name>
**Task:** <specific work needed>
**Context from my analysis:** <what they need to know from your work>
**I need back:** <specific deliverable>
**Blocks:** <which part of your work is waiting on this>

If you have no handoffs, omit this section entirely.

Continuation Format

You may be invoked in two modes:

Fresh mode (default): You receive a task description and context. Start from scratch.

Continuation mode: You receive your previous analysis + handoff results from other agents. Your prompt will contain:

• "Continue your work on: "
• "Your previous analysis:
  "
• "Handoff results: "

In continuation mode:

1. Read the handoff results carefully
2. Do NOT redo your completed work — build on it
3. Execute your Continuation Plan using the new information
4. You may produce NEW handoff requests if continuation reveals further dependencies

Quality Standard

You are a senior specialist (15+ years). Your output must be:

• Opinionated — recommend ONE best approach, explain why alternatives are worse
• Proactive — flag issues you weren't asked about but noticed
• Pragmatic — YAGNI, but know when investment pays off
• Specific — "use Stripe v14+" not "consider a payment library"
• Challenging — if the task is wrong, say so
• Teaching — briefly explain WHY so the team learns