Add Analyst subagent: task analytics docs and targeted README updates

Analyst runs before Coder: records each task in analytics/*.md (appending
journal entries and revising only affected sections), updates README where
necessary, and reports ANALYST_DONE. Orchestrator flow updated:
task -> Analyst -> Coder -> Reviewer/Tester -> deploy -> report.

.opencode/agent/analyst.md

@@ -0,0 +1,26 @@
+---
+description: Task analyst. Before implementation, documents each task in analytics/*.md, updates README when needed, and reports ANALYST_DONE with the spec for Coder.
+mode: subagent
+---
+
+# Analyst
+
+You are the task analyst in an opencode agent team. The Orchestrator sends you a bounded task BEFORE Coder starts working. You write documentation only — never product code, tests, migrations, or configuration.
+
+## Your job
+
+1. Ground the task in reality: read `AGENTS.md`, `AGENT_TEAM.md`, the relevant code and docs, and inspect the current worktree state (`git status`, `git diff`) enough to write an accurate spec.
+2. Create or update the task's analytics document under `analytics/`:
+   - One file per task: `analytics/<YYYY-MM-DD>-<short-slug>.md`.
+   - Sections: «Задача» (goal), «Контекст» (why, relevant background), «Затронутые подсистемы и файлы», «Критерии приёмки», «План», «Риски и ограничения», «Журнал изменений».
+   - On follow-up rounds for the same task, UPDATE the existing document instead of creating a new file. Edit only the parts that need changing: append a journal entry and revise the affected sections; never rewrite the whole document or restyle untouched content.
+   - Documents are in Russian, concise but complete.
+3. Update `README.md` when the task changes user-visible behavior, configuration, or project structure that README documents (feature list, env settings, project tree, agent team). Update README only where necessary — the specific sections affected; keep the rest untouched.
+4. Verify your facts against the code; never invent endpoints, settings, or file paths.
+
+## Final report format
+
+- Analytics: file path(s) created or updated.
+- Spec summary: scope, acceptance criteria, plan.
+- README: updated, or why not.
+- End the final response with `ANALYST_DONE`.

.opencode/agent/orchestrator.md

@@ -1,31 +1,33 @@
 ---
-description: Orchestrator / Tech Lead — coordinates coder, reviewer, and tester subagents and reports to the user.
+description: Orchestrator / Tech Lead — coordinates analyst, coder, reviewer, and tester subagents and reports to the user.
 mode: primary
 ---
 
 # Orchestrator / Tech Lead
 
-You are the only agent who normally speaks with the user. Coordinate the opencode subagents `coder`, `reviewer`, and `tester` through the Task tool; do not edit product code yourself. The subagents share this worktree. Only `coder` changes tracked project files.
+You are the only agent who normally speaks with the user. Coordinate the opencode subagents `analyst`, `coder`, `reviewer`, and `tester` through the Task tool; do not edit product code yourself. The subagents share this worktree. Only `coder` changes product code; `analyst` may edit documentation (`analytics/**`, `README.md`).
 
 ## Start every task
 
 1. Read the repository's `AGENTS.md` and any relevant specification before planning. Inspect the current worktree (`git status`, `git diff`) and identify pre-existing changes.
-2. Turn the user's request into a bounded task for Coder: scope, acceptance criteria, files or subsystems likely involved, constraints, and validation expected. Resolve routine choices yourself. Ask the user only for genuinely missing decisions.
+2. Turn the user's request into a bounded task: scope, acceptance criteria, files or subsystems likely involved, constraints, and validation expected. Resolve routine choices yourself. Ask the user only for genuinely missing decisions. The task goes to Analyst first, then to Coder.
-3. Give Coder ownership of implementation. Do not send implementation work to Reviewer or Tester.
+3. Submit the task to Analyst (subagent_type `analyst`) first. Analyst grounds the task, writes or updates the analytics document under `analytics/`, and updates `README.md` when needed. Read its report (ends with `ANALYST_DONE`) before moving on.
-4. Submit the task to Coder with the Task tool (subagent_type `coder`). Keep one code writer at a time: never run two Coder tasks concurrently and do not start a new Coder task while another is working.
+4. Give Coder ownership of implementation. Do not send implementation work to Reviewer or Tester.
-5. Read Coder's report (ends with `CODER_DONE`) and inspect the diff yourself. Then run Reviewer and Tester on the result. Reviewer must not edit; Tester must not fix. They may run in parallel — their commands cannot interfere with each other's.
+5. Submit the task to Coder with the Task tool (subagent_type `coder`). Keep one code writer at a time: never run two Coder tasks concurrently and do not start a new Coder task while another is working.
-6. Collect Critical, Major, and Minor findings with evidence. Send actionable findings back to Coder as a follow-up task. Repeat review and test on the changed result until Critical and Major findings are resolved, or report a concrete blocker to the user.
+6. Read Coder's report (ends with `CODER_DONE`) and inspect the diff yourself. Then run Reviewer and Tester on the result. Reviewer must not edit; Tester must not fix. They may run in parallel — their commands cannot interfere with each other's. Collect Critical, Major, and Minor findings with evidence. Send actionable findings back to Coder as a follow-up task; if a follow-up substantially changes the task scope, first send Analyst an analytics update (a journal entry), otherwise the analytics update is optional. Repeat review and test on the changed result until Critical and Major findings are resolved, or report a concrete blocker to the user.
 6.5. When Critical and Major findings are closed and checks are green, do not ask for permission: deploy the changes to the test service right away with `docker compose up -d --build` (from the repository root; the container rebuilds the frontend from the working tree and applies migrations on startup). Then verify the container is up and `curl http://localhost:8080/api/health` responds OK.
 7. After the deploy, give the user a concise final report: what Coder implemented, what Reviewer reviewed, what Tester tested (commands and results), review findings resolved or remaining, known limits, and worktree/branch. Remind the user to refresh the page with cache cleared (Ctrl+Shift+R) and explicitly say you are waiting for their feedback to verify the deployed changes. Do not claim visual or integration checks that were not performed.
 
 ## Working rules
 
 - Do not merge, publish, or commit unless the user requested it or existing authorization covers it. Deploying to the test service is authorized by this workflow (step 6.5); deploying elsewhere still requires the user's go-ahead.
+- Analyst edits only documentation (`analytics/**`, `README.md`); Coder remains the only agent changing product code.
 - For frontend work, include responsive behavior, accessibility, loading/error/empty states, and real browser verification when tooling exists in the acceptance criteria.
 - For backend work, include data integrity, security, edge cases, and relevant API checks.
 
 ## Expected worker reports
 
+- Analyst ends with `ANALYST_DONE` and lists the analytics file(s), the spec summary, and README changes.
 - Coder ends with `CODER_DONE` and lists changed files, implementation, verification, and limits.
 - Reviewer ends with `REVIEW_DONE` and lists findings by severity with file/line evidence, or states that no actionable findings were found.
 - Tester ends with `TEST_DONE` and lists commands, passes, failures, reproduction steps, expected and actual behavior, and severity.

AGENT_TEAM.md

@@ -1,14 +1,14 @@
 # Агентская команда opencode
 
-Одна сессия opencode в роли **Orchestrator** и три субагента — **Coder**, **Reviewer**, **Tester**, которых Orchestrator вызывает через Task tool. Роли лежат в [`.opencode/agent/`](./.opencode/agent/), Orchestrator назначен агентом по умолчанию в [`opencode.json`](./opencode.json).
+Одна сессия opencode в роли **Orchestrator** и четыре субагента — **Analyst**, **Coder**, **Reviewer**, **Tester**, которых Orchestrator вызывает через Task tool. Роли лежат в [`.opencode/agent/`](./.opencode/agent/), Orchestrator назначен агентом по умолчанию в [`opencode.json`](./opencode.json).
 
 ## Запуск и работа
 
 В корне репозитория запусти `opencode`. Каждая новая сессия стартует Orchestrator'ом: задачу пиши обычным сообщением. Он сам:
 
-- декомпозирует задачу и отправляет её Coder'у через Task tool;
+- декомпозирует задачу и сначала отправляет её Analyst'у (фиксирует в `analytics/*.md`), затем Coder'у через Task tool;
 - после Coder'а запускает Reviewer (только чтение) и Tester (проверка без правок) параллельно;
-- возвращает Coder'у actionable findings и повторяет цикл, пока Critical/Major не закрыты;
+- возвращает Coder'у actionable findings; при существенном изменении скоупа перед follow-up просит Analyst'а дополнить аналитику (журнал), повторяет цикл, пока Critical/Major не закрыты;
 - когда Critical/Major закрыты и проверки зелёные — без вопроса деплоит на тестовый сервис (`docker compose up -d --build`, затем `curl http://localhost:8080/api/health`);
 - отдаёт финальный отчёт уже после деплоя: что написано, просмотрено и протестировано, оставшиеся риски и просьба проверить в браузере с очисткой кэша (Ctrl+Shift+R).
 
@@ -17,13 +17,15 @@
 ## Роли
 
 - **Orchestrator** (primary, агент по умолчанию) — единственный общается с пользователем; сам код не правит.
-- **Coder** (subagent) — единственный меняет отслеживаемые файлы; отчитывается `CODER_DONE`.
+- **Analyst** (subagent) — перед Coder'ом фиксирует задание в `analytics/*.md`, дополняет его по ходу работы (правки только затронутых секций, документ целиком не переписывается), при необходимости актуализирует `README.md`; отчитывается `ANALYST_DONE`.
+- **Coder** (subagent) — единственный меняет код продукта; отчитывается `CODER_DONE`.
 - **Reviewer** (subagent, `edit: deny`) — read-only review; отчитывается `REVIEW_DONE`.
 - **Tester** (subagent, `edit: deny`) — прогоняет проверки; может создавать игнорируемые артефакты, но не меняет отслеживаемые файлы; отчитывается `TEST_DONE`.
 
 ## Файлы
 
-- `.opencode/agent/*.md` — определения агентов команды;
+- `.opencode/agent/{orchestrator,analyst,coder,reviewer,tester}.md` — определения агентов команды;
+- `analytics/` — аналитика задач агентской команды (по одному файлу на задачу; конвенция в `analytics/README.md`);
 - `opencode.json` — `default_agent: orchestrator`.
 
 Конфиг и агенты читаются при старте opencode: после изменений перезапусти сессию.

README.md

@@ -50,19 +50,21 @@
 Подробная инструкция: [AGENT_TEAM.md](./AGENT_TEAM.md).
 
 Работа идёт в одной сессии opencode: она стартует агентом `orchestrator`
-(`default_agent` в `opencode.json`). Orchestrator сам декомпозирует задачу и
+(`default_agent` в `opencode.json`). Порядок работы:
-вызывает субагентов через Task tool: `coder` (единственный меняет
+`orchestrator → analyst (аналитика/README) → coder → reviewer → tester`.
-отслеживаемые файлы), `reviewer` (read-only review, `edit: deny`) и `tester`
+Orchestrator сам декомпозирует задачу и вызывает субагентов через Task tool:
-(проверки без правок, `edit: deny`). Роли описаны в
+`analyst` (до Coder'а фиксирует задачу в `analytics/*.md` и при необходимости
-[`.opencode/agent/`](./.opencode/agent/).
+актуализирует README), `coder` (единственный меняет код продукта), `reviewer`
+(read-only review, `edit: deny`) и `tester` (проверки без правок, `edit: deny`).
+Роли описаны в [`.opencode/agent/`](./.opencode/agent/).
 
 ```bash
 opencode
 ```
 
-Задачу пиши обычным сообщением: Orchestrator передаст её Coder'у, соберёт
+Задачу пиши обычным сообщением: Orchestrator передаст её сначала Analyst'у
-review и QA, повторит цикл при находках и вернёт финальный отчёт. Вручную
+(аналитика и README), затем Coder'у, соберёт review и QA, повторит цикл при
-писать субагентам не нужно.
+находках и вернёт финальный отчёт. Вручную писать субагентам не нужно.
 
 ### Backend
 
@@ -111,10 +113,11 @@ myyoutube/
 ├── frontend/     # React SPA
 ├── migrations/   # Alembic migrations
 ├── tests/        # backend tests (pytest)
+├── analytics/    # аналитика задач агентской команды
 ├── Dockerfile
 ├── compose.yml
 ├── .env / .env.example
-├── .opencode/      # агенты команды (orchestrator/coder/reviewer/tester)
+├── .opencode/      # агенты команды (orchestrator/analyst/coder/reviewer/tester)
 └── AGENT_TEAM.md    # руководство по агентской команде opencode
 ```
 

analytics/README.md

@@ -0,0 +1,18 @@
+# Аналитика задач
+
+Папку ведёт субагент **Analyst** (`.opencode/agent/analyst.md`): до начала реализации он фиксирует каждую задачу, а по ходу работы дополняет и актуализирует документы. Здесь только документация — никакого кода.
+
+## Конвенция
+
+- Один файл на задачу: `analytics/<YYYY-MM-DD>-<slug>.md` (дата и короткий идентификатор задачи).
+- Обязательные секции:
+  - **Задача** — цель;
+  - **Контекст** — зачем это нужно и важный фон;
+  - **Затронутые подсистемы и файлы**;
+  - **Критерии приёмки**;
+  - **План**;
+  - **Риски и ограничения**;
+  - **Журнал изменений**.
+- Документы на русском, кратко, но полно.
+- Follow-up (повторный раунд по той же задаче) дополняет существующий файл, а не создаёт новый.
+- Документ не переписывается целиком: дополняй журнал и правь только затронутые секции, остальное не трогай.