Воркери та Intelligence Layer

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

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

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

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

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

Engineering / Core (6):

Startup operations (6, додано у Phase 66):

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

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

1. Identity — вибір preset card АБО "From scratch"
2. Capabilities — модель + інструменти + smart warnings (напр. "read-only роль + Write tool = misconfig")
3. Instructions — system prompt + вибір навичок + live preview

Wizard автоматично інжектить SYSTEM_PROTOCOL baseline (див. нижче) — preset фокусується лише на role-specific експертизі.

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

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

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

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

Кастомні воркери описуються у файлі 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 визначає role-specific експертизу (analyst робить TAM/SAM/SOM, sentinel робить SQL injection audit), є 15 cross-cutting правил, яких повинен дотримуватись будь-який воркер — від developer до pitch-coach. Замість дублювання їх у кожному preset, вони живуть в одній константі (shared/cli-routes.ts:SYSTEM_PROTOCOL) і auto-injected на кожен worker spawn через child-bot/claude-runner.ts.

5 правил Mandatory Workflow

1. Кожна нова задача MUST бути зареєстрована через arc issue create
2. Будь-яка зміна плану MUST оновити 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. Session report: закривати значущу роботу через arc report --summary
8. Definition of Done включає документацію, а не лише коміт
9. Явні trade-offs: scope vs дедлайн vs якість — рекомендувати один шлях + 1-2 альтернативи
10. Формат: стисло, таблиці/цифри де можливо, actionable важливіше за descriptive
11. Цитувати джерела для будь-якого факту/цифри; "я не знаю" краще за вигадку
12. Без тихих провалів: явно повідомляти про блокери, не йти мовчки хибним шляхом
13. Чесний прогрес: звітувати про те, що реально зашиплено (done vs attempted vs failed)
14. Convention over invention: слідувати наявним патернам, пояснювати відхилення
15. Learnings feedback loop: дописувати у learnings.md, коли виправили повторювану помилку

Ефект

Завдяки цій автоматичній ін'єкції preset-и стали на 50-70% коротші. Приклад: product-owner упав з 733 до 404 символів — лишилась тільки "User-first lens" (specific frame), решта (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. Trigger match (+2 бали) — пряме входження слова-тригеру з повідомлення
2. Keyword match (+1 бал) — семантична близькість за ключовими словами
3. Top-5 за сумою балів injected як SKILLS_HINT у промпт воркера

Приклад

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

• code-review: trigger "review" знайдено → +2 бали
• git-manager: keyword "commit" знайдено → +1 бал
• Результат: code-review (2), git-manager (1) injected у промпт

Формат реєстру навичок

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

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

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

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

Learnings — це accumulated правила, що виникають із зворотного зв'язку:

1. Thumbs-down (👎) — автоматично створюється learning з source "negative" на основі проблемної відповіді
2. Fix It — повторний запуск задачі генерує learning з source "fixit"
3. Ручні — архітектурні рішення та правила, source "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...

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

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

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

Автоматичний цикл покращення навичок, натхненний ідеями Андрія Карпаті про iterative self-improvement.

Як працює?

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

1. Збір метрик — зчитує quality-metrics.json кожного проєкту
2. Пошук проблемних навичок — фільтрує навички з success rate < 80% або кількістю negative > positive feedback
3. Sage аналіз — Haiku генерує покращену версію навички на основі зібраних помилок
4. Blind A/B тест — 3 сценарії, рандомізований порядок, dual scoring:
   • Eval rules (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
    }
  ]
}

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