Workery i Intelligence Layer

Arc OS używa systemu workerów do rozdziału zadań między wyspecjalizowane agenty AI, a Intelligence Layer zapewnia jakość ich odpowiedzi przez cztery moduły: Binary Evals, Context Router, Learnings i Karpathy Loop.

System workerów

Każdy worker to osobny agent AI z określoną rolą, modelem i zestawem narzędzi. Workery działają w ramach projektu i są dostępne przez Workspace UI lub komendy Telegram (/c, /d, /w:worker_id).

Kanoniczna biblioteka presetów (12)

Wszystkie presety żyją w config/workers_registry.json i są dostępne przez GET /api/crm/workers/presets. Każdy to generyczny szablon dla dowolnego projektu: żadnych odwołań do marki, żadnych imion postaci, żadnych odniesień do naszej infrastruktury.

Engineering / Core (6):

Operacje startupowe (6, dodane w Phase 66):

Tworzenie workera w projekcie

Przez UI (domyślnie): kliknięcie + Add w pasku WorkerSelector → otwiera się WorkerCreationWizard z 3 krokami:

1. Identity — wybór karty presetu LUB "From scratch"
2. Capabilities — model + narzędzia + inteligentne ostrzeżenia (np. "rola read-only + narzędzie Write = misconfig")
3. Instructions — system prompt + wybór skilli + podgląd na żywo

Wizard automatycznie wstrzykuje baseline SYSTEM_PROTOCOL (zob. niżej) — preset skupia się wyłącznie na ekspertyzie specyficznej dla roli.

Przez CLI / API: POST /api/crm/projects/:name/workers z pełnym body (forma legacy, link "Show advanced form →" w wizardzie).

Typy workerów

• chat — rozmowa turn-based z pełną historią kontekstu. Worker otrzymuje całą poprzednią korespondencję i odpowiada jak rozmówca.
• terminal — strumieniowe wykonanie z tool events. Worker działa jak sesja terminala, wykonując narzędzia sekwencyjnie i strumieniując postęp w czasie rzeczywistym.

Tworzenie własnego workera

Niestandardowe workery opisuje się w pliku config/workers_registry.json. Każdy wpis definiuje zachowanie agenta:

{
  "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
}

Pola konfiguracji

SYSTEM_PROTOCOL — Baseline dla wszystkich workerów

Podczas gdy worker.system_prompt definiuje ekspertyzę specyficzną dla roli (analyst robi TAM/SAM/SOM, sentinel robi audyt SQL injection), istnieje 15 przekrojowych reguł, których musi przestrzegać każdy worker — od developera po pitch-coacha. Zamiast duplikować je w każdym presecie, żyją w jednej stałej (shared/cli-routes.ts:SYSTEM_PROTOCOL) i są automatycznie wstrzykiwane przy każdym spawnie workera przez child-bot/claude-runner.ts.

5 reguł Mandatory Workflow

1. Każde nowe zadanie MUSI być zarejestrowane przez arc issue create
2. Każda zmiana planu MUSI aktualizować ROADMAP.md przez arc roadmap sync
3. Przed rozpoczęciem pracy przeczytaj ROADMAP.md + otwarte zgłoszenia (arc issues)
4. Po istotnych zmianach synchronizuj wiedzę przez arc memory refresh
5. Loguj znaczący postęp na zgłoszeniach przez arc issue log <id> "<text>"

10 reguł Quality Baseline (#229)

6. Priorytety: P0 > P1 > P2 > P3 — zawsze wiedz, co następne i dlaczego
7. Raport sesji: zamykaj znaczącą pracę przez arc report --summary
8. Definition of Done obejmuje dokumentację, nie tylko commit
9. Jawne trade-offy: zakres vs termin vs jakość — rekomenduj jedną ścieżkę + 1-2 alternatywy
10. Format: zwięźle, tabele/liczby gdzie się da, actionable bije opisowe
11. Cytuj źródła dla każdego faktu/liczby; "nie wiem" bije konfabulację
12. Żadnych cichych porażek: nazywaj blokery wprost, nie brnij w złą ścieżkę
13. Uczciwy postęp: raportuj, co faktycznie zostało dostarczone (done vs attempted vs failed)
14. Konwencja ponad inwencję: trzymaj się istniejących wzorców, wyjaśniaj odstępstwa
15. Pętla learnings: dopisuj do learnings.md, gdy zostaniesz poprawiony w powtarzającym się błędzie

Efekt

Dzięki tej automatycznej iniekcji presety stały się o 50-70% krótsze. Przykład: product-owner spadł z 733 do 404 znaków — została tylko "User-first lens" (specyficzna rama), reszta (priorytety/roadmap/zgłoszenia/DoD/trade-offy) to teraz baseline.

Administratorzy mogą rozszerzyć baseline w shared/cli-routes.ts — zmiana zastosuje się automatycznie do wszystkich workerów przy następnym spawnie.

Binary Evals — Walidacja odpowiedzi

Czym jest?

Deklaratywne reguły sprawdzania jakości odpowiedzi workerów. Każda reguła jest deterministyczna (bez AI), działa natychmiastowo i nie blokuje odpowiedzi. Wyniki mają severity warning lub info — informują, ale nie zatrzymują.

6 typów reguł

Format pliku evals

Plik umieszcza się obok skilla: 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"
    }
  ]
}

Każda reguła ma unikalny id, czytelną dla człowieka nazwę name, jeden z 6 typów, value do porównania i severity (warning lub info).

Context Router — Automatyczny dobór skilli

Jak działa?

Przy każdej wiadomości Context Router ocenia wszystkie skille z skills/_registry.json i automatycznie dobiera najbardziej trafne:

1. Trigger match (+2 punkty) — bezpośrednie wystąpienie słowa-triggera z wiadomości
2. Keyword match (+1 punkt) — semantyczna bliskość na podstawie słów kluczowych
3. Top-5 według sumy punktów jest wstrzykiwane jako SKILLS_HINT do promptu workera

Przykład

Wiadomość: "review the git commit for security"

• code-review: trigger "review" znaleziony → +2 punkty
• git-manager: keyword "commit" znaleziony → +1 punkt
• Wynik: code-review (2), git-manager (1) wstrzyknięte do promptu

Format rejestru skilli

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

• triggers — słowa jednoznacznie wskazujące na skill (wysoki priorytet)
• keywords — dodatkowe terminy do powiązania semantycznego
• agents — które workery mogą korzystać z tego skilla
• category — klasyfikacja (simple, complex, critical)

Learnings — Pamięć korekt

Jak powstają?

Learnings to skumulowane reguły wynikające z informacji zwrotnej:

1. Thumbs-down (👎) — automatycznie tworzy learning ze źródłem "negative" na podstawie problematycznej odpowiedzi
2. Fix It — ponowne uruchomienie zadania generuje learning ze źródłem "fixit"
3. Ręczne — decyzje architektoniczne i reguły, źródło "manual" lub "architecture"

Format pliku

Plik learnings.md w katalogu głównym projektu:

# 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...

Jak są używane?

• Ładowane przy starcie każdej sesji workera
• Wstrzykiwane do GSD promptu Developer (budżet — 2000 znaków)
• Najnowsze reguły — jako pierwsze (priorytet według czasu)
• Działają jak pamięć immunologiczna — błędy popełnione raz nie powtarzają się w kolejnych sesjach

Karpathy Loop — Nocne samodoskonalenie

Automatyczny cykl ulepszania skilli, zainspirowany ideami Andreja Karpathy'ego o iterative self-improvement.

Jak działa?

Co noc o 3:00 UTC uruchamia się automatyczny pipeline:

1. Zbieranie metryk — odczytuje quality-metrics.json każdego projektu
2. Wyszukiwanie problematycznych skilli — filtruje skille z success rate < 80% lub liczbą negative > positive feedback
3. Analiza Sage — Haiku generuje ulepszoną wersję skilla na podstawie zebranych błędów
4. Ślepy test A/B — 3 scenariusze, losowa kolejność, dual scoring:
   • Reguły Eval (60% wagi) + LLM judge (40% wagi)
5. Tworzenie PR — jeśli nowa wersja wygrywa (new_wins > old_wins), tworzony jest pull request
6. Raport CEO — wyniki trafiają na Telegram do ostatecznej decyzji

Metryki jakości

Każdy projekt akumuluje statystyki w 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
    }
  ]
}

Te metryki pozwalają systemowi obiektywnie określać, które skille wymagają poprawy, i śledzić postęp po aktualizacjach.