Воркери та Intelligence Layer

Arc OS використовує систему воркерів для розподілу задач між спеціалізованими AI-агентами, а Intelligence Layer забезпечує якість їхніх відповідей через чотири модулі: Binary Evals, Context Router, Learnings та Karpathy Loop.

Система воркерів

Кожен воркер — це окремий AI-агент з визначеною роллю, моделлю та набором інструментів. Воркери працюють у рамках проєкту і доступні через Workspace UI або Telegram-команди (/c, /d, /w:worker_id).

Канонічна бібліотека пресетів (12)

Усі пресети живуть у config/workers_registry.json і доступні через GET /api/crm/workers/presets. Кожен — це універсальний шаблон для будь-якого проєкту: без посилань на бренди, без імен персонажів, без посилань на нашу інфраструктуру.

Engineering / Core (6):

Startup-операції (6, додано в Phase 66):

Створення воркера в проєкті

Через UI (за замовчуванням): натисни + Add у pill-панелі WorkerSelector → відкривається WorkerCreationWizard з 3 кроками:

1. Identity — обери картку пресету АБО "From scratch"
2. Capabilities — модель + інструменти + розумні попередження (наприклад "read-only роль + інструмент Write = помилка конфігурації")
3. Instructions — system prompt + skills picker + живий preview

Майстер авто-інжектує baseline SYSTEM_PROTOCOL (див. нижче) — пресет фокусується лише на експертизі, специфічній для ролі.

Через CLI / API: POST /api/crm/projects/:name/workers з повним body (застаріла форма, посилання "Show advanced form →" у майстрі).

Типи воркерів

• chat — покрокова розмова з повною історією контексту. Воркер отримує всю попередню розмову й відповідає як співрозмовник.
• terminal — потокове виконання з подіями інструментів. Воркер працює як сесія терміналу, запускаючи інструменти послідовно й транслюючи прогрес у реальному часі.

Створення кастомного воркера

Кастомні воркери описуються у файлі config/workers_registry.json. Кожен запис визначає поведінку агента:

{
  "id": "my-worker",
  "label": "My Worker",
  "icon": "🔧",
  "type": "chat",
  "model": "claude-sonnet-4-5",
  "max_turns": 10,
  "tools": ["Read", "Glob", "Grep"],
  "system_prompt": "You are...",
  "focus_dirs": ["src/"],
  "builtin": false
}

Поля конфігурації

SYSTEM_PROTOCOL — baseline для всіх воркерів

Тоді як worker.system_prompt визначає специфічну для ролі експертизу (аналітик робить TAM/SAM/SOM, sentinel робить аудити SQL-ін'єкцій), існує 15 наскрізних правил, яких має дотримуватися кожен воркер — від developer до pitch-coach. Замість дублювання їх у кожному пресеті вони живуть в одній константі (shared/cli-routes.ts:SYSTEM_PROTOCOL) і авто-інжектуються на кожен spawn воркера через child-bot/claude-runner.ts.

5 обов'язкових правил Workflow

1. Кожна нова задача МАЄ бути зареєстрована через arc issue create
2. Будь-яка зміна плану МАЄ оновити ROADMAP.md через arc roadmap sync
3. Перед початком роботи прочитай ROADMAP.md + відкриті задачі (arc issues)
4. Після значних змін синхронізуй знання через arc memory refresh
5. Логуй значимий прогрес у задачах через arc issue log <id> "<text>"

10 правил Quality Baseline (#229)

6. Пріоритети: P0 > P1 > P2 > P3 — завжди знай, що далі й чому
7. Звіт про сесію: закривай значиму роботу через arc report --summary
8. Definition of Done включає документацію, не лише коміт
9. Явні trade-off'и: scope vs дедлайн vs якість — рекомендуй один шлях + 1-2 альтернативи
10. Формат: стисло, таблиці/цифри де можливо, actionable краще за описове
11. Цитуй джерела для будь-якого факту/числа; "я не знаю" краще за вигадку
12. Без тихих збоїв: заявляй про блокери явно, не йди хибним шляхом
13. Чесний прогрес: звітуй про те, що насправді відвантажено (done vs attempted vs failed)
14. Конвенція замість винаходу: дотримуйся наявних патернів, пояснюй відхилення
15. Петля зворотного зв'язку learnings: додавай до learnings.md, коли тебе виправили на повторюваній помилці

Ефект

Завдяки цій автоматичній інжекції пресети стали на 50-70% коротшими. Приклад: product-owner скоротився з 733 до 404 символів — залишилася лише "User-first lens" (специфічний фрейм); решта (priorities/roadmap/issues/DoD/trade-offs) тепер baseline.

Адміни можуть розширити baseline у shared/cli-routes.ts — зміна автоматично застосовується до всіх воркерів на наступному spawn.

Binary Evals — валідація відповідей

Що це?

Декларативні правила для перевірки якості відповідей воркерів. Кожне правило детерміноване (без AI), виконується миттєво й не блокує відповідь. Результати мають severity warning або info — вони інформують, а не зупиняють.

6 типів правил

Формат файлу evals

Файл розміщується поруч зі скілом: skills/{skill_name}/{skill_name}.evals.json

{
  "version": 1,
  "skill": "code-review",
  "rules": [
    {
      "id": "cr-001",
      "name": "Must return JSON verdict",
      "type": "string_contains",
      "value": "\"verdict\"",
      "severity": "warning"
    }
  ]
}

Кожне правило має унікальний id, читабельний name, один із 6 типів, value для порівняння та severity (warning або info).

Context Router — автоматичний вибір скілів

Як це працює?

На кожне повідомлення Context Router оцінює всі скіли зі skills/_registry.json і автоматично обирає найрелевантніші:

1. Збіг тригера (+2 бали) — пряме входження тригерного слова з повідомлення
2. Збіг ключового слова (+1 бал) — семантична близькість за ключовими словами
3. Топ-5 за сумарним балом інжектуються як SKILLS_HINT у промт воркера

Приклад

Повідомлення: "review the git commit for security"

• code-review: тригер "review" знайдено → +2 бали
• git-manager: ключове слово "commit" знайдено → +1 бал
• Результат: code-review (2), git-manager (1) інжектовано в промт

Формат реєстру скілів

{
  "name": "code-review",
  "triggers": ["review", "audit", "security"],
  "keywords": ["vulnerability", "OWASP", "XSS"],
  "agents": ["summer"],
  "category": ["complex"]
}

• triggers — слова, що прямо вказують на скіл (високий пріоритет)
• keywords — додаткові терміни для семантичної асоціації
• agents — які воркери можуть використовувати цей скіл
• category — класифікація (simple, complex, critical)

Learnings — пам'ять корекцій

Як вони створюються?

Learnings — це накопичені правила, що виникають із фідбеку:

1. Thumbs-down (👎) — learning із джерелом "negative" автоматично створюється на основі проблемної відповіді
2. Fix It — повторний запуск задачі генерує learning із джерелом "fixit"
3. Manual — архітектурні рішення та правила, джерело "manual" або "architecture"

Формат файлу

Файл learnings.md у корені проєкту:

# Learnings
> Auto-generated. Injected into GSD prompt at session start.

## Rules
- [2026-04-03T20:00:00Z] [architecture] Rule text here...
- [2026-04-04T10:00:00Z] [security] Another rule...

Як вони використовуються?

• Завантажуються на старті кожної сесії воркера
• Інжектуються в GSD-промт Developer'а (бюджет — 2000 символів)
• Найновіші правила йдуть першими (пріоритет за часом)
• Вони діють як імунна пам'ять — помилки, зроблені одного разу, не повторюються в наступних сесіях

Karpathy Loop — нічне самовдосконалення

Автоматичний цикл покращення скілів, натхненний ідеями Andrej Karpathy про ітеративне самовдосконалення.

Як це працює?

Щоночі о 3:00 UTC запускається автоматичний конвеєр:

1. Збір метрик — читає quality-metrics.json кожного проєкту
2. Пошук проблемних скілів — фільтрує скіли з показником успішності < 80% або з переважанням негативного фідбеку над позитивним
3. Аналіз Sage — Haiku генерує покращену версію скілу на основі зібраних помилок
4. Сліпий A/B-тест — 3 сценарії, рандомізований порядок, подвійне оцінювання:
   • Правила evals (вага 60%) + LLM judge (вага 40%)
5. Створення PR — якщо нова версія перемагає (new_wins > old_wins), створюється pull request
6. Звіт CEO — результати надсилаються в Telegram для остаточного рішення

Метрики якості

Кожен проєкт накопичує статистику в quality-metrics.json:

{
  "total_invocations": 42,
  "total_successes": 40,
  "total_feedback_positive": 35,
  "total_feedback_negative": 2,
  "avg_duration_ms": 15000,
  "skills": [
    {
      "name": "code-review",
      "applied_count": 5,
      "success_count": 4
    }
  ]
}

Ці метрики дають системі змогу об'єктивно визначати, які скіли потребують покращення, і відстежувати прогрес після оновлень.