Перейти к основному содержимому

Агенты

Агенты в oh-my-agent — это специализированные инженерные роли. У каждого агента определён домен, знания о технологическом стеке, файлы ресурсов, шлюзы качества и ограничения выполнения. Агенты — не универсальные чат-боты, а сфокусированные исполнители, которые работают в рамках своей зоны ответственности и следуют структурированным протоколам.

Категории агентов​

КатегорияАгентыОтветственность
Идеацияoma-brainstormИсследование идей, предложение подходов, создание документов проектирования
Архитектураoma-architectureГраницы системы/модуля/сервиса, анализ в стиле ADR/ATAM/CBAM, записи о компромиссах
Планированиеoma-pmДекомпозиция требований, разбиение на задачи, API-контракты, назначение приоритетов
Реализацияoma-frontend, oma-backend, oma-mobile, oma-dbНаписание продакшн-кода в соответствующих доменах
Дизайнoma-designДизайн-системы, DESIGN.md, токены, типографика, цвет, анимация, доступность
Инфраструктураoma-tf-infraМульти-облачное развёртывание Terraform, IAM, оптимизация затрат, политики как код
DevOpsoma-dev-workflowРаннер задач mise, CI/CD, миграции, координация релизов, автоматизация монорепозитория
Наблюдаемостьoma-observabilityКонвейеры наблюдаемости, маршрутизация трассировки, сигналы MELT+P (metrics/logs/traces/profiles/cost/audit/privacy), управление SLO, криминалистика инцидентов, настройка транспорта
Качествоoma-qaАудит безопасности (OWASP), производительность, доступность (WCAG), ревью качества кода
Отладкаoma-debugВоспроизведение ошибок, анализ корневых причин, минимальные исправления, регрессионные тесты
Локализацияoma-translatorКонтекстно-зависимый перевод с сохранением тона, регистра и доменных терминов
Координацияoma-orchestrator, oma-coordinationАвтоматическая и ручная мультиагентная оркестрация
Gitoma-scmГенерация Conventional Commits, разбиение коммитов по фичам
Поиск и извлечениеoma-searchМаршрутизатор поиска на основе намерения с оценкой доверия (документы Context7, веб, код gh/glab, Serena локально)
Ретроспективаoma-recapАнализ истории бесед между инструментами и тематические сводки работы
Обработка документовoma-hwp, oma-pdfКонвертация HWP/HWPX/HWPML и PDF в Markdown для LLM/RAG

Подробный справочник по агентам​

oma-brainstorm​

Домен: Идеация по принципу «сначала дизайн» перед планированием или реализацией.

Когда использовать: Исследование новой идеи фичи, понимание намерения пользователя, сравнение подходов. Используйте перед /plan для сложных или неоднозначных запросов.

Когда НЕ использовать: Чёткие требования (переходите к oma-pm), реализация (переходите к доменным агентам), ревью кода (переходите к oma-qa).

Основные правила:

  • Никакой реализации или планирования до утверждения дизайна
  • Один уточняющий вопрос за раз (не пакетами)
  • Всегда предлагать 2-3 подхода с рекомендованным вариантом
  • Посекционная проработка дизайна с подтверждением пользователя на каждом шаге
  • YAGNI — проектируйте только то, что нужно

Рабочий процесс: 6 фаз: Исследование контекста, Вопросы, Подходы, Дизайн, Документация (сохранение в docs/plans/), Переход к /plan.

Ресурсы: Использует только общие ресурсы (clarification-protocol, reasoning-templates, quality-principles, skill-routing).

oma-architecture​

Домен: Архитектура ПО/систем — границы модулей и сервисов, анализ компромиссов, синтез мнений заинтересованных сторон, протоколы решений.

Когда использовать: Выбор или ревью системной архитектуры, определение границ модуля/сервиса/ответственности, сравнение архитектурных вариантов с явными компромиссами, исследование архитектурных болей (амплификация изменений, скрытые зависимости, неудобные API), приоритизация архитектурных инвестиций или рефакторингов, написание архитектурных рекомендаций или ADR.

Когда НЕ использовать: Визуальные/дизайн-системы (используйте oma-design), планирование фич и декомпозиция задач (используйте oma-pm), реализация Terraform (используйте oma-tf-infra), диагностика багов (используйте oma-debug), ревью безопасности/производительности/доступности (используйте oma-qa).

Методологии: Диагностическая маршрутизация, сравнение design-twice, анализ рисков в стиле ATAM, приоритизация в стиле CBAM, протоколы решений в стиле ADR.

Основные правила:

  • Диагностируйте архитектурную проблему до выбора метода
  • Используйте самую лёгкую достаточную методологию для текущего решения
  • Отделяйте архитектурный дизайн от UI/визуального дизайна и от поставки через Terraform
  • Консультируйтесь с агентами-стейкхолдерами только когда решение достаточно сквозное, чтобы оправдать затраты
  • Качество рекомендации важнее театра консенсуса: консультируйтесь широко, решайте явно
  • Каждая рекомендация должна указывать предположения, компромиссы, риски и шаги валидации
  • По умолчанию учитывайте стоимость: стоимость внедрения, эксплуатационную стоимость, сложность для команды, стоимость будущих изменений

Ресурсы: SKILL.md, каталог resources/ с методологическими руководствами (diagnostic-routing, design-twice, ATAM, CBAM, шаблоны ADR).

oma-pm​

Домен: Управление продуктом — анализ требований, декомпозиция задач, API-контракты.

Когда использовать: Разбиение сложных фич, определение целесообразности, приоритизация работ, определение API-контрактов.

Основные правила:

  • API-first дизайн: определить контракты до задач реализации
  • Каждая задача имеет: агент, название, критерии приёмки, приоритет, зависимости
  • Минимизировать зависимости для максимального параллельного выполнения
  • Безопасность и тестирование — часть каждой задачи (не отдельные фазы)
  • Задачи должны быть выполнимы одним агентом
  • Вывод: JSON-план + task-board.md для совместимости с оркестратором

Вывод: .agents/results/plan-{sessionId}.json, .agents/brain/current-plan.md, запись в память для оркестратора.

Ресурсы: execution-protocol.md, examples.md, iso-planning.md, task-template.json, ../_shared/core/api-contracts/.

Лимит ходов: По умолчанию 10, максимум 15.

oma-frontend​

Домен: Веб-UI — React, Next.js, TypeScript с FSD-lite архитектурой.

Когда использовать: Создание пользовательских интерфейсов, компонентов, клиентской логики, стилизации, валидации форм, интеграции с API.

Технологический стек:

  • React + Next.js (Server Components по умолчанию, Client Components для интерактивности)
  • TypeScript (strict)
  • TailwindCSS v4 + shadcn/ui (только чтение примитивов, расширение через cva/обёртки)
  • FSD-lite: корень src/ + фича src/features/*/ (без кросс-фичевых импортов)

Библиотеки:

НазначениеБиблиотека
Датыluxon
СтилиTailwindCSS v4 + shadcn/ui
Хукиahooks
Утилитыes-toolkit
URL-состояниеnuqs
Серверное состояниеTanStack Query
Клиентское состояниеJotai (минимизировать использование)
Формы@tanstack/react-form + Zod
Аутентификацияbetter-auth

Основные правила:

  • shadcn/ui в первую очередь, расширение через cva, никогда не модифицировать components/ui/* напрямую
  • Маппинг дизайн-токенов 1:1 (никогда не хардкодить цвета)
  • Proxy вместо middleware (Next.js 16+ использует proxy.ts, не middleware.ts для логики прокси)
  • Без prop drilling более 3 уровней — используйте атомы Jotai
  • Абсолютные импорты с @/ обязательны
  • Цель FCP < 1 сек
  • Адаптивные брейкпоинты: 320px, 768px, 1024px, 1440px

Ресурсы: execution-protocol.md, tech-stack.md, tailwind-rules.md, component-template.tsx, snippets.md, error-playbook.md, checklist.md, examples/.

Чек-лист шлюза качества:

  • Доступность: ARIA-лейблы, семантические заголовки, навигация с клавиатуры
  • Мобильные устройства: проверено на мобильных вьюпортах
  • Производительность: без CLS, быстрая загрузка
  • Отказоустойчивость: Error Boundaries и Loading Skeletons
  • Тесты: логика покрыта Vitest
  • Качество: проходят typecheck и lint

Лимит ходов: По умолчанию 20, максимум 30.

oma-backend​

Домен: API, серверная логика, аутентификация, операции с базами данных.

Когда использовать: REST/GraphQL API, миграции баз данных, аутентификация, серверная бизнес-логика, фоновые задачи.

Архитектура: Router (HTTP) -> Service (бизнес-логика) -> Repository (доступ к данным) -> Models.

Определение стека: Читает манифесты проекта (pyproject.toml, package.json, Cargo.toml, go.mod и т.д.) для определения языка и фреймворка. Использует директорию stack/ при наличии или просит пользователя запустить /stack-set.

Основные правила:

  • Чистая архитектура: никакой бизнес-логики в обработчиках маршрутов
  • Все входные данные валидируются библиотекой валидации проекта
  • Только параметризованные запросы (никакой строковой интерполяции в SQL)
  • JWT + bcrypt для аутентификации; ограничение частоты запросов на эндпоинтах аутентификации
  • Асинхронность где поддерживается; аннотации типов на всех сигнатурах
  • Пользовательские исключения через централизованный модуль ошибок
  • Явная стратегия загрузки ORM, границы транзакций, безопасный жизненный цикл

Ресурсы: execution-protocol.md, examples.md, orm-reference.md, checklist.md, error-playbook.md. Стеко-специфичные ресурсы в stack/ (генерируются /stack-set): tech-stack.md, snippets.md, api-template.*, stack.yaml.

Лимит ходов: По умолчанию 20, максимум 30.

oma-mobile​

Домен: Кроссплатформенные мобильные приложения — Flutter, React Native.

Когда использовать: Нативные мобильные приложения (iOS + Android), мобильные UI-паттерны, платформенные функции (камера, GPS, push-уведомления), offline-first архитектура.

Архитектура: Clean Architecture: domain -> data -> presentation.

Технологический стек: Flutter/Dart, Riverpod/Bloc (управление состоянием), Dio с интерсепторами (API), GoRouter (навигация), Material Design 3 (Android) + iOS HIG.

Основные правила:

  • Riverpod/Bloc для управления состоянием (без raw setState для сложной логики)
  • Все контроллеры освобождаются в методе dispose()
  • Dio с интерсепторами для API-вызовов; корректная обработка offline
  • Цель 60fps; тестирование на обеих платформах

Ресурсы: execution-protocol.md, tech-stack.md, snippets.md, screen-template.dart, checklist.md, error-playbook.md, examples.md.

Лимит ходов: По умолчанию 20, максимум 30.

oma-db​

Домен: Архитектура баз данных — SQL, NoSQL, векторные базы данных.

Когда использовать: Проектирование схем, ER-диаграммы, нормализация, индексация, транзакции, планирование ёмкости, стратегия резервного копирования, проектирование миграций, архитектура векторных БД/RAG, обзор анти-паттернов, проектирование с учётом требований (ISO 27001/27002/22301).

Рабочий процесс по умолчанию: Исследование (определение сущностей, паттернов доступа, объёмов) -> Проектирование (схема, ограничения, транзакции) -> Оптимизация (индексы, секционирование, архивация, анти-паттерны).

Основные правила:

  • Сначала выбрать модель, потом движок
  • 3НФ по умолчанию для реляционных; документировать компромиссы BASE для распределённых
  • Документировать все три слоя схемы: внешний, концептуальный, внутренний
  • Целостность — первоклассная сущность: entity, domain, referential, business-rule
  • Конкурентность никогда не бывает неявной: определить границы транзакций и уровни изоляции
  • Векторные БД — инфраструктура поиска, а не источник истины
  • Никогда не считать векторный поиск заменой лексического поиска

Обязательные артефакты: Резюме внешней схемы, концептуальная схема, внутренняя схема, таблица стандартов данных, глоссарий, оценка ёмкости, стратегия резервного копирования/восстановления. Для векторных/RAG: политика версий эмбеддингов, политика чанкинга, стратегия гибридного поиска.

Ресурсы: execution-protocol.md, document-templates.md, anti-patterns.md, vector-db.md, iso-controls.md, checklist.md, error-playbook.md, examples.md.

oma-design​

Домен: Дизайн-системы, UI/UX, управление DESIGN.md.

Когда использовать: Создание дизайн-систем, лендингов, дизайн-токенов, цветовых палитр, типографики, адаптивных макетов, обзор доступности.

Рабочий процесс: 7 фаз: Настройка (сбор контекста) -> Извлечение (опционально, из URL-ссылок) -> Улучшение (расширение нечётких промптов) -> Предложение (2-3 дизайн-направления) -> Генерация (DESIGN.md + токены) -> Аудит (адаптивность, WCAG, Nielsen, проверка ИИ-мусора) -> Передача.

Применение анти-паттернов («без ИИ-мусора»):

  • Типографика: системный стек шрифтов по умолчанию; без Google Fonts по умолчанию без обоснования
  • Цвет: без фиолетово-синих градиентов, без орбов/капель с градиентом, без чистого белого на чистом чёрном
  • Макет: без вложенных карточек, без десктоп-only макетов, без шаблонных макетов с 3 метриками
  • Анимация: без bounce easing повсюду, без анимаций > 800 мс, обязательное уважение prefers-reduced-motion
  • Компоненты: без glassmorphism повсюду, все интерактивные элементы должны иметь альтернативы для клавиатуры/тача

Основные правила:

  • Сначала проверить .design-context.md; создать при отсутствии
  • Системный стек шрифтов по умолчанию (CJK-совместимые шрифты для ko/ja/zh)
  • Минимум WCAG AA для всех дизайнов
  • Responsive-first (мобильные по умолчанию)
  • Представить 2-3 направления, получить подтверждение

Ресурсы: execution-protocol.md, anti-patterns.md, checklist.md, design-md-spec.md, design-tokens.md, prompt-enhancement.md, stitch-integration.md, error-playbook.md, плюс директория reference/ (типографика, цвет и контраст, пространственный дизайн, анимация, адаптивный дизайн, паттерны компонентов, доступность, шейдеры и 3D) и examples/ (design-context-example, landing-page-prompt).

oma-tf-infra​

Домен: Инфраструктура как код с Terraform, мульти-облако.

Когда использовать: Развёртывание на AWS/GCP/Azure/Oracle Cloud, конфигурация Terraform, аутентификация CI/CD (OIDC), CDN/балансировщики нагрузки/хранилище/сети, управление состоянием, инфраструктура соответствия ISO.

Определение облака: Читает провайдеры и префиксы ресурсов Terraform (google_* = GCP, aws_* = AWS, azurerm_* = Azure, oci_* = Oracle Cloud). Включает полную таблицу маппинга ресурсов мульти-облака.

Основные правила:

  • Провайдер-агностичный: определять облако из контекста проекта
  • Удалённое состояние с версионированием и блокировкой
  • OIDC-first для аутентификации CI/CD
  • Всегда plan перед apply
  • IAM с минимальными привилегиями
  • Тегировать всё (Environment, Project, Owner, CostCenter)
  • Никаких секретов в коде
  • Пинить версии всех провайдеров и модулей
  • Без auto-approve в продакшене

Ресурсы: execution-protocol.md, multi-cloud-examples.md, cost-optimization.md, policy-testing-examples.md, iso-42001-infra.md, checklist.md, error-playbook.md, examples.md.

oma-dev-workflow​

Домен: Автоматизация задач в монорепозитории и CI/CD.

Когда использовать: Запуск dev-серверов, выполнение lint/format/typecheck по приложениям, миграции баз данных, генерация API, i18n-сборки, продакшн-сборки, оптимизация CI/CD, валидация pre-commit.

Основные правила:

  • Всегда использовать задачи mise run вместо прямых команд пакетного менеджера
  • Запускать lint/test только для изменённых приложений
  • Валидировать сообщения коммитов с помощью commitlint
  • CI должен пропускать неизменённые приложения
  • Никогда не использовать прямые команды пакетного менеджера, если существуют задачи mise

Ресурсы: validation-pipeline.md, database-patterns.md, api-workflows.md, i18n-patterns.md, release-coordination.md, troubleshooting.md.

oma-observability​

Домен: Роутер наблюдаемости и трассировки на основе намерения, охватывающий уровни, границы и сигналы.

Когда использовать: Настройка конвейера наблюдаемости (OTel SDK + Collector + бэкенд вендора), трассировка через границы сервисов и доменов (W3C-пропагаторы, baggage, мультитенантность, мульти-облако), настройка транспорта (пороги UDP/MTU, OTLP gRPC vs HTTP, топология Collector DaemonSet vs sidecar, рецепты сэмплирования), криминалистика инцидентов (6-мерная локализация: code / service / layer / host / region / infra), выбор категории вендора (OSS full-stack vs коммерческий SaaS vs специалист по высокой кардинальности vs специалист по профилированию), observability-as-code (дашборды Grafana Jsonnet, CRD PrometheusRule, YAML OpenSLO, алерты SLO burn-rate), мета-наблюдаемость (самочувствие конвейера, расхождение часов, ограждения кардинальности, матрица хранения), покрытие сигналов MELT+P (metrics, logs, traces, profiles, cost, audit, privacy), миграция с устаревших инструментов (Fluentd -> Fluent Bit или OTel Collector).

Когда НЕ использовать: Наблюдаемость LLM ops / gen_ai (использовать Langfuse, Arize Phoenix, LangSmith, Braintrust), происхождение данных в data-конвейерах (OpenLineage + Marquez, dbt test, Airflow lineage), телеметрия физического уровня IoT / дата-центра (Nlyte, Sunbird, Device42), оркестрация chaos engineering (Chaos Mesh, Litmus, Gremlin, ChaosToolkit), GPU- / TPU-инфраструктура (NVIDIA DCGM Exporter), цепочка поставки ПО (sigstore, in-toto, SLSA), рабочий процесс реагирования на инциденты / пейджинг (PagerDuty, OpsGenie, Grafana OnCall), настройка одного вендора, уже покрываемая его собственным скиллом.

Основные правила:

  • Классифицировать намерение до маршрутизации: setup | migrate | investigate | alert | trace | tune | route
  • Сначала категория, а не реестр вендоров: делегировать вендор-специфичным скиллам через resources/vendor-categories.md; не дублировать документацию вендора
  • Настройка транспорта — это ров: пороги UDP/MTU, выбор протокола OTLP, топология Collector и рецепты сэмплирования — это глубина, которую другие скиллы не покрывают
  • Мета-наблюдаемость не обсуждается: проверить самочувствие конвейера, синхронизацию часов (< 100 мс дрейфа), кардинальность и хранение до объявления настройки завершённой
  • Предпочтение CNCF-first: Prometheus, Jaeger, Thanos, Fluent Bit, OpenTelemetry, Cortex, OpenCost, OpenFeature, Flagger, Falco
  • Fluentd устарел (CNCF 2025-10): рекомендовать Fluent Bit или OTel Collector для новых задач и миграций
  • W3C Trace Context как пропагатор по умолчанию; транслировать в зависимости от облака (AWS X-Ray X-Amzn-Trace-Id, GCP Cloud Trace, Datadog, Cloudflare, Linkerd)
  • Приватность раньше функций: редактирование PII, правила baggage с учётом сэмплирования, неизменяемый аудит SOC2/ISO + удаление GDPR/PIPA применяются на этапе сбора, а не только в хранилище

Ресурсы: SKILL.md, resources/execution-protocol.md, resources/intent-rules.md, resources/vendor-categories.md, resources/matrix.md, resources/checklist.md, resources/anti-patterns.md, resources/examples.md, resources/meta-observability.md, resources/observability-as-code.md, resources/incident-forensics.md, resources/standards.md, плюс углублённые ресурсы в resources/layers/ (L3-network, L4-transport, L7-application, mesh), resources/signals/ (metrics, logs, traces, profiles, cost, audit, privacy), resources/transport/ (collector-topology, otlp-grpc-vs-http, sampling-recipes, udp-statsd-mtu) и resources/boundaries/ (cross-application, multi-tenant, release, slo).

oma-qa​

Домен: Обеспечение качества — безопасность, производительность, доступность, качество кода.

Когда использовать: Финальное ревью перед деплоем, аудиты безопасности, анализ производительности, проверка доступности, анализ покрытия тестами.

Приоритет ревью: Безопасность > Производительность > Доступность > Качество кода.

Уровни серьёзности:

  • CRITICAL: Нарушение безопасности, риск потери данных
  • HIGH: Блокирует запуск
  • MEDIUM: Исправить в этом спринте
  • LOW: Бэклог

Основные правила:

  • Каждое замечание должно содержать файл:строка, описание и исправление
  • Сначала запускать автоматические инструменты (npm audit, bandit, lighthouse)
  • Без ложных срабатываний — каждое замечание должно быть воспроизводимым
  • Предоставлять код исправления, а не только описания

Ресурсы: execution-protocol.md, iso-quality.md, checklist.md, self-check.md, error-playbook.md, examples.md.

Лимит ходов: По умолчанию 15, максимум 20.

oma-debug​

Домен: Диагностика и исправление ошибок.

Когда использовать: Ошибки, о которых сообщают пользователи, падения, проблемы производительности, перемежающиеся сбои, состояния гонки, регрессионные ошибки.

Методология: Сначала воспроизведи, потом диагностируй. Никогда не угадывай исправления.

Основные правила:

  • Определить корневую причину, а не просто симптом
  • Минимальное исправление: менять только необходимое
  • Каждое исправление сопровождается регрессионным тестом
  • Искать похожие паттерны в других местах
  • Документировать в .agents/brain/bugs/

Используемые инструменты Serena MCP:

  • find_symbol("functionName") — найти функцию
  • find_referencing_symbols("Component") — найти все использования
  • search_for_pattern("error pattern") — найти похожие проблемы

Ресурсы: execution-protocol.md, common-patterns.md, debugging-checklist.md, bug-report-template.md, error-playbook.md, examples.md.

Лимит ходов: По умолчанию 15, максимум 25.

oma-translator​

Домен: Контекстно-зависимый мультиязычный перевод.

Когда использовать: Перевод UI-строк, документации, маркетинговых текстов, ревью существующих переводов, создание глоссариев.

4-этапный метод: Анализ источника (регистр, намерение, доменные термины, культурные отсылки, эмоциональные коннотации, маппинг образной речи) -> Извлечение смысла (снять структуру источника) -> Реконструкция на целевом языке (естественный порядок слов, соответствие регистра, разбиение/объединение предложений) -> Проверка (рубрика естественности + проверка анти-ИИ паттернов).

Опциональный 7-этапный режим для публикационного качества: дополнен стадиями Критического обзора, Ревизии и Полировки.

Основные правила:

  • Сначала просканировать существующие файлы локализации для соответствия соглашениям
  • Переводить смысл, а не слова
  • Сохранять эмоциональные коннотации
  • Никогда не создавать пословный перевод
  • Никогда не смешивать регистры внутри текста
  • Сохранять доменную терминологию как есть

Ресурсы: translation-rubric.md, anti-ai-patterns.md.

oma-orchestrator​

Домен: Автоматизированная координация мультиагентной системы через запуск CLI.

Когда использовать: Сложные фичи, требующие нескольких агентов параллельно, автоматизированное выполнение, fullstack-реализация.

Настройки по умолчанию:

НастройкаПо умолчаниюОписание
MAX_PARALLEL3Максимум параллельных субагентов
MAX_RETRIES2Количество попыток при ошибке
POLL_INTERVAL30 секИнтервал проверки статуса
MAX_TURNS (impl)20Лимит ходов для backend/frontend/mobile
MAX_TURNS (review)15Лимит ходов для qa/debug
MAX_TURNS (plan)10Лимит ходов для pm

Фазы рабочего процесса: Планирование -> Настройка (ID сессии, инициализация памяти) -> Выполнение (запуск по приоритетному уровню) -> Мониторинг (опрос прогресса) -> Верификация (автоматическая + цикл кросс-ревью) -> Сбор (компиляция результатов).

Цикл ревью агент-агент:

  1. Самопроверка: агент проверяет свой diff по критериям приёмки
  2. Автоматическая верификация: oma verify {agent-type} --workspace {workspace}
  3. Кросс-ревью: QA-агент проверяет изменения
  4. При сбое: замечания возвращаются для исправления (максимум 5 итераций цикла)

Мониторинг Clarification Debt: Отслеживает пользовательские коррекции во время сессий. События оцениваются: clarify (+10), correct (+25), redo (+40). CD >= 50 запускает обязательный RCA. CD >= 80 приостанавливает сессию.

Ресурсы: subagent-prompt-template.md, memory-schema.md.

oma-scm​

Домен: Генерация Git-коммитов в формате Conventional Commits.

Когда использовать: После завершения изменений кода, при запуске /scm.

Типы коммитов: feat, fix, refactor, docs, test, chore, style, perf.

Рабочий процесс: Анализ изменений -> Разбиение по фичам (если > 5 файлов с разными областями) -> Определение типа -> Определение области -> Написание описания (императив, < 72 символа, строчные буквы, без точки в конце) -> Немедленное выполнение коммита.

Правила:

  • Никогда не использовать git add -A или git add .
  • Никогда не коммитить файлы с секретами
  • Всегда указывать файлы при индексации
  • Использовать HEREDOC для многострочных сообщений коммитов
  • Co-Author: First Fluke <our.first.fluke@gmail.com>

oma-coordination​

Домен: Руководство по ручной пошаговой координации мультиагентной системы.

Когда использовать: Сложные проекты, где требуется контроль человека в цикле на каждом шлюзе, ручное руководство по запуску агентов, пошаговые рецепты координации.

Когда НЕ использовать: Полностью автоматизированное параллельное выполнение (использовать oma-orchestrator), задачи в пределах одного домена (использовать доменного агента напрямую).

Основные правила:

  • Всегда представлять план на подтверждение пользователем перед запуском агентов
  • Один приоритетный уровень за раз -- ждать завершения перед следующим уровнем
  • Пользователь одобряет каждый переход через шлюз
  • QA-ревью обязательно перед слиянием
  • Цикл устранения для замечаний CRITICAL/HIGH

Рабочий процесс: PM планирует → Пользователь подтверждает → Запуск по приоритетному уровню → Мониторинг → QA-ревью → Исправление проблем → Поставка.

Отличие от oma-orchestrator: Coordination — ручное и управляемое (пользователь контролирует темп), orchestrator — автоматизированное (агенты запускаются и работают с минимальным вмешательством пользователя).

Домен: Маршрутизатор поиска на основе намерения с оценкой доверия домена — направляет запросы в Context7 (документы), нативный веб-поиск, gh/glab (код), Serena (локально).

Когда использовать: Поиск официальной документации библиотек/фреймворков, веб-исследование по туториалам/примерам/сравнениям/решениям, поиск кода в GitHub/GitLab по шаблонам реализации, любые запросы, где канал поиска неясен (автомаршрутизация), другие навыки, которым нужна инфраструктура поиска (общий вызов).

Когда НЕ использовать: Исследование только локального кода (используйте Serena MCP напрямую), анализ истории Git или blame (используйте oma-scm), полное архитектурное исследование (используйте oma-architecture, который может внутренне вызывать этот навык).

Основные правила:

  • Классифицируйте намерение перед поиском — каждый запрос сначала проходит через IntentClassifier
  • Один запрос — одна лучшая маршрутизация — избегайте избыточной мульти-маршрутизации, если намерение не неоднозначно
  • Оцените доверие к каждому результату — все нелокальные результаты получают метки доверия домена из реестра
  • Флаги переопределяют классификатор: --docs, --code, --web, --strict, --wide, --gitlab
  • Fail forward: если основной маршрут падает, изящно откатывайтесь (docs→web, web→стратегии oma search fetch)
  • Дополнительный MCP не требуется: Context7 для документов, runtime-native для веба, CLI для кода, Serena для локального
  • Нейтральный относительно вендора веб-поиск: используйте то, что предоставляет текущий runtime (WebSearch, Google, Bing)
  • Доверие только на уровне домена — никаких оценок на уровне подпути или страницы

Ресурсы: SKILL.md, каталог resources/ с классификатором намерений, определениями маршрутов и реестром доверия.

oma-recap​

Домен: Анализ истории бесед из нескольких AI-инструментов (Claude, Codex, Gemini, Qwen, Cursor) с тематическими дневными/периодическими сводками работы.

Когда использовать: Суммирование дня или периода рабочей активности, понимание потока работы между несколькими AI-инструментами, анализ паттернов переключения инструментов между сессиями, подготовка ежедневных стендапов / еженедельных ретро / рабочих логов.

Когда НЕ использовать: Ретроспектива изменений кода на основе Git-коммитов (используйте oma retro), мониторинг агентов в реальном времени (используйте oma dashboard), метрики продуктивности (используйте oma stats).

Процесс:

  1. Разрешить дату или временной диапазон из ввода на естественном языке (today, yesterday, last Monday, явная дата)
  2. Получить данные беседы через oma recap --date YYYY-MM-DD или --since / --until
  3. Сгруппировать по инструменту и сессии
  4. Извлечь темы (над чем работали, какие баги исправлены, какие инструменты изучены)
  5. Отрендерить тематическую дневную/периодическую сводку

Ресурсы: SKILL.md — делегирует тяжёлую работу CLI oma recap.

oma-hwp​

Домен: Конвертация HWP / HWPX / HWPML (корейский текстовый процессор) → Markdown с использованием kordoc.

Когда использовать: Преобразование корейских HWP-документов (.hwp, .hwpx, .hwpml) в Markdown, подготовка корейских государственных/корпоративных документов для контекста LLM или RAG, извлечение структурированного контента (таблицы, заголовки, списки, изображения, сноски, гиперссылки) из HWP.

Когда НЕ использовать: PDF-файлы (используйте oma-pdf), XLSX/DOCX (вне области), генерация/редактирование HWP (вне области), уже текстовые файлы (используйте инструмент Read напрямую).

Основные правила:

  • Используйте bunx kordoc@latest для запуска — установка не требуется; всегда передавайте @latest или закреплённую версию
  • Формат вывода по умолчанию — Markdown
  • Если каталог вывода не указан, вывод идёт в тот же каталог, что и вход
  • kordoc обеспечивает сохранение структуры (заголовки, таблицы, вложенные таблицы, сноски, гиперссылки, изображения)
  • Защиты безопасности (ZIP-бомба, XXE, SSRF, XSS) обеспечиваются kordoc — не добавляйте свои
  • Для зашифрованных или защищённых DRM HWP чётко сообщите пользователю об ограничении
  • Выполните постобработку через resources/flatten-tables.ts, чтобы преобразовать HTML-блоки <table> в GFM pipe-таблицы и удалить символы Private Use Area шрифта Hancom

Ресурсы: SKILL.md, config/, resources/flatten-tables.ts.

oma-pdf​

Домен: Конвертация PDF в Markdown с использованием opendataloader-pdf.

Когда использовать: Преобразование PDF-документов в Markdown для контекста LLM или RAG, извлечение структурированного контента (таблицы, заголовки, списки) из PDF, подготовка PDF-данных для потребления AI.

Когда НЕ использовать: Генерация/создание PDF (используйте соответствующие инструменты документирования), редактирование существующих PDF (вне области), простое чтение уже текстовых файлов (используйте инструмент Read напрямую).

Основные правила:

  • Используйте uvx opendataloader-pdf для запуска — установка не требуется
  • Формат вывода по умолчанию — Markdown
  • Если каталог вывода не указан, вывод идёт в тот же каталог, что и входной PDF
  • Сохраняйте структуру документа (заголовки, таблицы, списки, изображения)
  • Для сканированных PDF используйте гибридный режим с OCR
  • Всегда запускайте uvx mdformat на выходе, чтобы нормализовать форматирование Markdown
  • Валидируйте, что выходной Markdown читаем и хорошо структурирован
  • Сообщайте пользователю о любых проблемах конвертации (отсутствующие таблицы, искажённый текст)

Ресурсы: SKILL.md, config/, resources/.

Предполётная проверка устава (CHARTER_CHECK)​

Перед написанием любого кода каждый агент реализации должен вывести блок CHARTER_CHECK:

CHARTER_CHECK:
- Clarification level: {LOW | MEDIUM | HIGH}
- Task domain: {домен агента}
- Must NOT do: {3 ограничения из области задачи}
- Success criteria: {измеримые критерии}
- Assumptions: {применённые умолчания}

Назначение:

  • Декларирует, что агент будет и не будет делать
  • Предотвращает расширение объёма до написания кода
  • Делает допущения явными для проверки пользователем
  • Предоставляет тестируемые критерии успеха

Уровни уточнения:

  • LOW: Ясные требования. Продолжить с указанными допущениями.
  • MEDIUM: Частично неоднозначно. Перечислить варианты, продолжить с наиболее вероятным.
  • HIGH: Очень неоднозначно. Установить статус «заблокировано», перечислить вопросы, НЕ писать код.

В режиме субагента (запущенного через CLI) агенты не могут спрашивать пользователей напрямую. LOW продолжает, MEDIUM сужает и интерпретирует, HIGH блокируется и возвращает вопросы оркестратору для передачи.

Двухуровневая загрузка навыков​

Знания каждого агента разделены на два уровня:

Уровень 1 — SKILL.md (~800 байт): Всегда загружен. Содержит фронтматтер (имя, описание), когда использовать / не использовать, основные правила, обзор архитектуры, список библиотек и ссылки на ресурсы Уровня 2.

Уровень 2 — resources/ (загружается по требованию): Загружается только при активной работе агента и только ресурсы, соответствующие типу и сложности задачи:

СложностьЗагружаемые ресурсы
ПростаяТолько execution-protocol.md
Средняяexecution-protocol.md + examples.md
Сложнаяexecution-protocol.md + examples.md + tech-stack.md + snippets.md

Дополнительные ресурсы загружаются по мере необходимости:

  • checklist.md — на этапе верификации
  • error-playbook.md — только при возникновении ошибок
  • common-checklist.md — для финальной верификации сложных задач

Ограниченное выполнение​

Агенты работают в строгих доменных границах:

  • Фронтенд-агент не будет модифицировать бэкенд-код
  • Бэкенд-агент не будет трогать UI-компоненты
  • БД-агент не будет реализовывать API-эндпоинты
  • Агенты документируют внедоменные зависимости для других агентов

Когда в процессе выполнения обнаруживается задача из другого домена, агент документирует её в файле результатов как элемент эскалации, вместо того чтобы пытаться обработать самостоятельно.

Стратегия рабочих пространств​

Для мультиагентных проектов отдельные рабочие пространства предотвращают конфликты файлов:

./apps/api      -> рабочее пространство бэкенд-агента
./apps/web      -> рабочее пространство фронтенд-агента
./apps/mobile   -> рабочее пространство мобильного агента

Рабочие пространства указываются флагом -w при запуске агентов:

oma agent:spawn backend "Implement auth API" session-01 -w ./apps/api
oma agent:spawn frontend "Build login form" session-01 -w ./apps/web

Поток оркестрации​

При запуске мультиагентного рабочего процесса (/orchestrate или /work):

  1. PM-агент декомпозирует запрос в доменные задачи с приоритетами (P0, P1, P2) и зависимостями
  2. Инициализация сессии — генерация ID сессии, создание orchestrator-session.md и task-board.md в памяти
  3. Задачи P0 запускаются параллельно (до MAX_PARALLEL параллельных агентов)
  4. Мониторинг прогресса — оркестратор опрашивает файлы progress-{agent}.md каждые POLL_INTERVAL
  5. Задачи P1 запускаются после завершения P0, и так далее
  6. Цикл верификации запускается для каждого завершённого агента (самопроверка -> автоматическая верификация -> кросс-ревью QA)
  7. Сбор результатов из всех файлов result-{agent}.md
  8. Финальный отчёт с резюме сессии, изменёнными файлами, оставшимися проблемами

Определения агентов​

Агенты определены в двух местах:

.agents/agents/ — Содержит 7 файлов определений субагентов:

  • backend-engineer.md
  • frontend-engineer.md
  • mobile-engineer.md
  • db-engineer.md
  • qa-reviewer.md
  • debug-investigator.md
  • pm-planner.md

Эти файлы определяют идентичность агента, ссылку на протокол выполнения, шаблон CHARTER_CHECK, резюме архитектуры и правила. Они используются при запуске субагентов через Task/Agent tool (Claude Code) или CLI.

.claude/agents/ — IDE-специфичные определения субагентов, ссылающиеся на файлы .agents/agents/ через символические ссылки или прямые копии для совместимости с Claude Code.

Оперативное состояние (Serena Memory)​

Во время сессий оркестрации агенты координируются через общие файлы памяти в .serena/memories/ (настраивается через mcp.json):

ФайлВладелецНазначениеДля остальных
orchestrator-session.mdОркестраторID сессии, статус, время начала, отслеживание фазТолько чтение
task-board.mdОркестраторНазначения задач, приоритеты, обновления статусаТолько чтение
progress-{agent}.mdКонкретный агентПрогресс по ходам: выполненные действия, прочитанные/изменённые файлы, текущий статусОркестратор читает
result-{agent}.mdКонкретный агентФинальный вывод: статус (completed/failed), резюме, изменённые файлы, чек-лист критериев приёмкиОркестратор читает
session-metrics.mdОркестраторОтслеживание Clarification Debt, прогрессия Quality ScoreQA читает
experiment-ledger.mdОркестратор/QAОтслеживание экспериментов при активном Quality ScoreВсе читают

Инструменты памяти настраиваются. По умолчанию используется Serena MCP (read_memory, write_memory, edit_memory), но пользовательские инструменты можно настроить в mcp.json:

{
  "memoryConfig": {
    "provider": "serena",
    "basePath": ".serena/memories",
    "tools": {
      "read": "read_memory",
      "write": "write_memory",
      "edit": "edit_memory"
    }
  }
}

Дашборды (oma dashboard и oma dashboard:web) наблюдают за этими файлами памяти для мониторинга в реальном времени.