Воркери та 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 template для будь-якого проекту: ніяких brand references, ніяких character names, ніяких посилань на нашу інфраструктуру.

Engineering / Core (6):

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

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

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

1. Identity — pick preset card OR "From scratch"
2. Capabilities — model + tools + smart warnings (e.g. "read-only role + Write tool = misconfig")
3. Instructions — system prompt + skills picker + live preview

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

Через CLI / API: POST /api/crm/projects/:name/workers з повним body (legacy form, "Show advanced form →" link у 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. Every new task MUST be registered via arc issue create
2. Any plan change MUST update ROADMAP.md via arc roadmap sync
3. Before starting work, read ROADMAP.md + open issues (arc issues)
4. After significant changes, sync knowledge via arc memory refresh
5. Log meaningful progress on issues via arc issue log <id> "<text>"

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

6. Priorities: P0 > P1 > P2 > P3 — always know what's next and why
7. Session report: close meaningful work with arc report --summary
8. Definition of Done includes documentation, not just commit
9. Trade-offs explicit: scope vs deadline vs quality — recommend one path + 1-2 alternatives
10. Format: concise, tables/numbers where possible, actionable beats descriptive
11. Cite sources for any fact/number; "I don't know" beats fabrication
12. No silent failures: state blockers explicitly, don't continue down wrong path
13. Honest progress: report what actually shipped (done vs attempted vs failed)
14. Convention over invention: follow existing patterns, explain deviations
15. Learnings feedback loop: append to learnings.md when corrected on recurring mistake

Effect

Через цю автоматичну ін'єкцію preset-и стали 50-70% коротші. Приклад: product-owner упав з 733 до 404 chars — лишилось тільки "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
    }
  ]
}

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