Simplify agent-swarm to a lite core with optional modules and evals

agent-swarm/README.ru.md

@@ -1,6 +1,8 @@
 # agent-swarm
 
-Универсальный скилл для больших задач, которые делятся на 8+ независимых кусков: код и миграции, аудиты, research, документы, данные, дизайн, инфраструктура. Лид планирует, пакует контекст, запускает волны (через `workflow`, `subagent` или последовательно — если инструмента нет) и интегрирует. Воркеры не пересекаются по файлам/артефактам, каждый получает пакет и возвращает структурный отчёт.
+Тонкий оркестрационный скилл для больших или рискованных задач: код и миграции, аудиты, research,
+документы, данные, дизайн, инфраструктура. Это **не обязательный пайплайн**, а набор режимов и
+инвариантов: direct / paired critic / swarm.
 
 ## Вызов
 
@@ -10,46 +12,76 @@
 
 или просто опишите задачу — скилл подключится по описанию.
 
-Скилл не обязателен для каждой задачи: маленькую задачу можно делать напрямую, среднюю — с независимым критиком, и только широкую — через swarm. Пользователь выбирает стек, объём и темп; скилл добавляет координацию, когда она оправдана.
+## Режимы
 
-Процесс — опциональный, quality gates — нет. Для продуктовой работы заранее выбирается профиль `prototype` или `product`. В `product` обязательны release-замеры производительности, реальный UX-сценарий, сравнение с baseline и явный вердикт пользователя. Технический `pass` verifier'а не заменяет приёмку продукта.
+| Режим | Когда | Что добавляет |
+|---|---|---|
+| Direct | одна задача, быстрый фидбек, низкий риск | ничего |
+| Paired critic | средняя задача или рискованное решение | независимую проверку |
+| Swarm | 8+ независимых кусков или ширина | ownership, параллельных воркеров, verifier |
+
+Если куски делят один экран, один дизайн-язык или один mutable-артефакт — не swarm. Один
+implementer + один critic обычно дают более цельный UI, чем параллельные владельцы панелей.
+
+## Инварианты
+
+1. Сначала outcome и quality bar, потом процесс.
+2. Один владелец на артефакт; shared-файлы — у лида/интегратора.
+3. Воркер получает пакет, а не всю историю чата.
+4. Автор не проверяет сам себя; для рискованной работы нужен свежий контекст.
+5. «Готово» — это runnable artifact, команда, цитата, метрика или рендер, а не уверенная фраза.
+6. Технический `pass` — не product acceptance. Для product/UI: release-замеры, реальный сценарий,
+   baseline и явный вердикт пользователя.
+7. Если лагает или выглядит хуже baseline — чинить, а не добавлять фичи.
+8. Для product — один milestone за раз; следующий не начинать без приёмки.
+9. Проверять prerequisites; глобальные установки/деструктив — только с разрешения.
+10. Инструкции пользователя важнее скилла: попросил быстро/прототип — убрать церемонии, оставить
+    safety и evidence.
 
 ## Что происходит
 
-1. **Fit-check.** Если задача не делится на 8+ независимых юнитов, скилл скажет не использовать swarm.
-2. **Prerequisite gate.** Скилл проверяет toolchain, runtime, сервисы, display, credentials и baseline. Ставит только project-local/pinned и только с разрешения; если обязательный prerequisite не закрывается — спрашивает пользователя **до** запуска работы. Воркеры ничего не устанавливают.
-3. **Recon.** 2–4 агента картографируют репозиторий/источники/данные; лид пишет `.swarm/brief.md`, `.swarm/profile.md` и выбирает domain-адаптер из `references/domains.md`.
-4. **План.** Задачи, владельцы файлов, контракты, критерии приёмки. Гейт: без этого волны не стартуют.
-5. **Волны.** Воркеры идут батчами по 6–8 (реальный лимит активных детей узнаётся перед запуском и записывается в `state.json`; recon не должен занимать слоты). Затем 4–6 независимых верификаторов на «замороженном» дереве, затем интегратор.
-6. **Аудит.** `scripts/audit-scope.mjs` сравнивает изменения с картой владения.
-7. **Интеграция.** Один интегратор собирает общие файлы и прогоняет полный acceptance suite.
-8. **Product gate.** Для `product`: release-замеры, реальный сценарий, baseline и вердикт пользователя. Без этого следующий milestone не начинается.
-9. **Отчёт.** `.swarm/final-report.md`.
+1. **Понять** outcome, аудиторию, quality bar и ограничения.
+2. **Проверить** окружение: toolchain, команды, сервисы, display, credentials.
+3. **Спланировать только необходимое.** Для swarm — brief, disjoint scopes, contracts, acceptance.
+   Для direct/paired — без `.swarm`-бюрократии.
+4. **Сделать** напрямую, с критиком или батчами воркеров.
+5. **Проверить** технически, затем независимым критиком; для product — performance/UX/baseline.
+6. **Принять и интегрировать.** Лид владеет shared-файлами и финальной проверкой.
 
 ## Артефакты
 
-Всё лежит в `.swarm/` в корне рабочей папки: бриф, профиль домена, план, карточки задач, отчёты, ревью, baseline, финальный отчёт. `.swarm/` можно удалить после задачи или добавить в `.gitignore`; структура подходит и для кода, и для research/контента/данных/дизайна.
+Для swarm **опционально**: `.swarm/brief.md`, `tasks/`, `reports/`, `reviews/`. Они нужны для
+координации и восстановления, а не для отчётности ради отчётности. Для direct/paired их можно не
+создавать вообще.
 
 ## Ограничения
 
-- Это инструкция, а не плагин: запуск идёт через инструмент `workflow`.
-- Одновременно выполняется столько агентов, сколько разрешает runtime (часто 8, не 14). Лимит проверяется preflight-ом; `wave.workflow.js` запускает задачи батчами, а не одним большим fan-out.
-- Дети не общаются между собой и не делегируют дальше; координация — через файлы и лида.
-- Верификаторы работают на замороженном дереве; полный разбор пишется в `.swarm/reviews/Vxx.md`, а workflow возвращает только `{task_id, verdict, summary, review_file}`.
-- `blocked`-воркер не заменяется: лид правит контракт/shared-файл и продолжает того же агента через `send_message`.
-- Evidence зависит от домена: команда и тест для кода, источник и дата для research, отрендеренный артефакт для дизайна, reproducible metric для данных.
-- Токены — потолок, а не цель: 20–30% резервируется на verify/integration и polish, после фиксов делается delta-review, а не полная перепроверка. Детали — в `references/token-economy.md`.
-- Визуальные агенты работают в отдельных Xvfb/display-окружениях, со своим HOME/config/копией проекта; общий рабочий стол для скриншотов не используется. Детали — в `references/visual-testing.md`.
-- Computer-use — крайний tier: один агент, одноразовый desktop/VM, только после детерминированных проверок и никогда как единственное evidence.
-- Стоимость: 30–40 агентов ≈ 0.5–1.5M токенов.
+- `workflow` не обязателен: есть `subagent` — используем его, нет — работаем последовательно.
+- Число одновременных агентов ограничено runtime; не запускать oversubscribed fan-out.
+- Воркеры не устанавливают зависимости и не трогают live-системы.
+- Визуальные проверки — в изолированных display; общий рабочий стол не evidence.
+- Computer-use — крайний tier: один агент, одноразовый desktop/VM, не единственное evidence.
+- Токены — потолок, а не цель: резерв на verify/integration/polish; после фиксов — delta-review.
 - Для задачи, которую один агент делает за 15 минут, swarm не нужен.
 
+## Опциональные модули
+
+Читать только по необходимости:
+
+- `references/playbook.md` — подробный runbook для больших swarm.
+- `references/packets.md` — шаблоны brief/task/verifier.
+- `references/orchestration.md` — `workflow`, батчи, ретраи.
+- `references/domains.md` — адаптеры для кода/research/контента/данных/дизайна/ops.
+- `references/prerequisites.md` — preflight и политика установки.
+- `references/token-economy.md` — бюджеты, контекст, delta-review.
+- `references/visual-testing.md` — изолированные display, скриншоты, computer-use.
+- `references/product-quality.md` — performance/UX/baseline/human acceptance.
+- `evals/` — как проверять сам скилл (baseline vs with-skill).
+
 ## Настройка
 
-- Шаблоны: `assets/`, включая `prerequisites.md.tmpl`.
-- Prerequisites: `references/prerequisites.md`.
-- Product quality: `references/product-quality.md`.
-- Подробный runbook: `references/playbook.md`.
-- Оркестрация: `references/orchestration.md`.
+- Шаблоны: `assets/`.
 - Проверка скоупа: `node scripts/audit-scope.mjs --init` перед стартом, затем `node scripts/audit-scope.mjs`.
-- Для директорий в `plan.json` используйте glob `path/**`, особенно для ещё не созданных папок.
+- Для директорий в `plan.json` используйте glob `path/**`, включая ещё не созданные папки.
+- Перед изменением скилла прочитайте `evals/README.md`; не считайте, что новая версия лучше старой
+  без сравнения.