# agent-swarm

Тонкий оркестрационный скилл для больших или рискованных задач: код и миграции, аудиты, research,
документы, данные, дизайн, инфраструктура. Это **не обязательный пайплайн**, а набор режимов и
инвариантов: direct / paired critic / swarm.

## Вызов

```
/agent-swarm <задача>
```

или просто опишите задачу — скилл подключится по описанию.

## Режимы

| Режим | Когда | Что добавляет |
|---|---|---|
| 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; ставить только проверенные pinned-инструменты из официальных
   источников; глобальные установки/деструктив — только с разрешения.
10. Строить переиспользуемые «руки»: harness, скрипты, фикстуры, screenshot/CLI-утилиты. Тестировать
    их, документировать и держать в репозитории; неиспользуемые — удалять.
11. Инструкции пользователя важнее скилла: попросил быстро/прототип — убрать церемонии, оставить
    safety и evidence.

## Что происходит

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 **опционально**: `.swarm/brief.md`, `tasks/`, `reports/`, `reviews/`. Они нужны для
координации и восстановления, а не для отчётности ради отчётности. Для direct/paired их можно не
создавать вообще.

## Ограничения

- `workflow` не обязателен: есть `subagent` — используем его, нет — работаем последовательно.
- Число одновременных агентов ограничено runtime; не запускать oversubscribed fan-out.
- Воркеры не устанавливают зависимости и не трогают live-системы.
- Визуальные проверки — в изолированных display; общий рабочий стол не evidence.
- Computer-use — крайний tier: один агент, одноразовый desktop/VM, не единственное evidence.
- Токены — потолок, а не цель: резерв на verify/integration/polish; после фиксов — delta-review.
- Для задачи, которую один агент делает за 15 минут, swarm не нужен.

## Опциональные модули

Читать только по необходимости:

- `references/domains.md` — адаптеры для кода/research/контента/данных/дизайна/ops.
- `references/prerequisites.md` — preflight и политика установки.
- `references/visual-testing.md` — изолированные display, скриншоты, computer-use.
- `references/product-quality.md` — performance/UX/baseline/human acceptance.
- `evals/` — как проверять сам скилл (baseline vs with-skill).

## Настройка

- Проверка скоупа: `node scripts/audit-scope.mjs --init` перед стартом, затем `node scripts/audit-scope.mjs`.
- Для swarm пишите brief/tasks сами; обязательных шаблонов больше нет.
- Для директорий в `plan.json` используйте glob `path/**`, включая ещё не созданные папки.
- Перед изменением скилла прочитайте `evals/README.md`; не считайте, что новая версия лучше старой
  без сравнения.