# 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: <task>"
- "Your previous analysis: <summary>"
- "Handoff results: <agent outputs>"

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