Worker und Intelligence Layer

Arc OS nutzt ein Worker-System, um Aufgaben auf spezialisierte KI-Agenten zu verteilen. Der Intelligence Layer sichert die Antwortqualität durch vier Module: Binary Evals, Context Router, Learnings und Karpathy Loop.

Das Worker-System

Jeder Worker ist ein eigenständiger KI-Agent mit definierter Rolle, Modell und Werkzeugset. Worker arbeiten innerhalb eines Projekts und sind über die Workspace UI oder Telegram-Befehle (/c, /d, /w:worker_id) erreichbar.

Kanonische Preset-Bibliothek (12)

Alle Presets leben in config/workers_registry.json und sind über GET /api/crm/workers/presets verfügbar. Jedes ist ein generisches Template für beliebige Projekte: keine Brand-Referenzen, keine Charakternamen, keine Verweise auf unsere Infrastruktur.

Engineering / Core (6):

Startup Operations (6, hinzugefügt in Phase 66):

Worker im Projekt erstellen

Über die UI (Default): Klick auf + Add in der WorkerSelector-Pill-Bar → der WorkerCreationWizard öffnet sich mit 3 Schritten:

1. Identity — Preset-Karte wählen ODER „From scratch"
2. Capabilities — Modell + Tools + Smart Warnings (z. B. „read-only Rolle + Write-Tool = Fehlkonfiguration")
3. Instructions — System-Prompt + Skills-Picker + Live-Vorschau

Der Wizard injiziert die SYSTEM_PROTOCOL-Baseline automatisch (siehe unten) — das Preset konzentriert sich nur auf die rollenspezifische Expertise.

Über CLI / API: POST /api/crm/projects/:name/workers mit vollständigem Body (Legacy-Formular, Link „Show advanced form →" im Wizard).

Worker-Typen

• chat — Turn-basiertes Gespräch mit vollständigem Kontextverlauf. Der Worker erhält den gesamten bisherigen Chatverlauf und antwortet wie ein Gesprächspartner.
• terminal — Streaming-Ausführung mit Tool-Events. Der Worker arbeitet wie eine Terminal-Sitzung, führt Werkzeuge sequenziell aus und überträgt den Fortschritt in Echtzeit.

Eigenen Worker erstellen

Benutzerdefinierte Worker werden in der Datei config/workers_registry.json beschrieben. Jeder Eintrag definiert das Verhalten des Agenten:

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

Konfigurationsfelder

SYSTEM_PROTOCOL — Baseline für alle Worker

Während worker.system_prompt die rollenspezifische Expertise definiert (der Analyst macht TAM/SAM/SOM, der Sentinel macht SQL-Injection-Audits), gibt es 15 Cross-Cutting-Regeln, die jeder Worker einhalten muss — vom Developer bis zum Pitch Coach. Statt sie in jedem Preset zu duplizieren, leben sie in einer einzigen Konstante (shared/cli-routes.ts:SYSTEM_PROTOCOL) und werden bei jedem Worker-Spawn über child-bot/claude-runner.ts automatisch injiziert.

5 Regeln des 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 Regeln der 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

Effekt

Durch diese automatische Injektion wurden die Presets 50-70% kürzer. Beispiel: product-owner fiel von 733 auf 404 Zeichen — übrig blieb nur die „User-first lens" (der spezifische Frame), der Rest (Priorities/Roadmap/Issues/DoD/Trade-offs) ist jetzt Baseline.

Admins können die Baseline in shared/cli-routes.ts erweitern — die Änderung gilt automatisch für alle Worker beim nächsten Spawn.

Binary Evals — Antwortvalidierung

Was ist das?

Deklarative Regeln zur Qualitätsprüfung von Worker-Antworten. Jede Regel ist deterministisch (ohne KI), läuft sofort durch und blockiert die Antwort nicht. Ergebnisse haben den Schweregrad warning oder info — sie informieren, stoppen aber nicht.

6 Regeltypen

Dateiformat für Evals

Die Datei liegt neben dem Skill: 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"
    }
  ]
}

Jede Regel hat eine eindeutige id, einen menschenlesbaren name, einen der 6 Typen, einen value für den Vergleich und einen severity-Wert (warning oder info).

Context Router — Automatische Skill-Auswahl

Wie funktioniert das?

Bei jeder Nachricht bewertet der Context Router alle Skills aus skills/_registry.json und wählt automatisch die relevantesten aus:

1. Trigger-Treffer (+2 Punkte) — direktes Vorkommen eines Trigger-Worts aus der Nachricht
2. Keyword-Treffer (+1 Punkt) — semantische Nähe anhand von Schlüsselwörtern
3. Top-5 nach Punktzahl werden als SKILLS_HINT in den Worker-Prompt injiziert

Beispiel

Nachricht: "review the git commit for security"

• code-review: Trigger "review" gefunden → +2 Punkte
• git-manager: Keyword "commit" gefunden → +1 Punkt
• Ergebnis: code-review (2), git-manager (1) in den Prompt injiziert

Format des Skill-Registers

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

• triggers — Wörter, die eindeutig auf einen Skill hinweisen (hohe Priorität)
• keywords — zusätzliche Begriffe für semantische Zuordnung
• agents — welche Worker diesen Skill verwenden können
• category — Klassifizierung (simple, complex, critical)

Learnings — Korrektur-Gedächtnis

Wie entstehen Learnings?

Learnings sind akkumulierte Regeln, die aus Feedback entstehen:

1. Thumbs-down (👎) — es wird automatisch ein Learning mit der Quelle "negative" auf Basis der problematischen Antwort erstellt
2. Fix It — ein erneuter Durchlauf der Aufgabe erzeugt ein Learning mit der Quelle "fixit"
3. Manuell — Architekturentscheidungen und Regeln, Quelle "manual" oder "architecture"

Dateiformat

Datei learnings.md im Projektstamm:

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

Wie werden sie verwendet?

• Werden beim Start jeder Worker-Sitzung geladen
• In den GSD-Prompt des Developer injiziert (Budget: 2000 Zeichen)
• Neueste Regeln zuerst (Priorität nach Zeit)
• Wirken als Immungedächtnis — einmal gemachte Fehler werden in späteren Sitzungen nicht wiederholt

Karpathy Loop — Nächtliche Selbstoptimierung

Ein automatischer Skill-Verbesserungszyklus, inspiriert von Andrej Karpathys Ideen zum iterativen Self-Improvement.

Wie funktioniert das?

Jede Nacht um 3:00 UTC startet eine automatische Pipeline:

1. Metriken sammeln — liest quality-metrics.json jedes Projekts
2. Problematische Skills finden — filtert Skills mit einer Erfolgsrate < 80 % oder mehr negativem als positivem Feedback
3. Sage-Analyse — Haiku generiert eine verbesserte Skill-Version auf Basis der gesammelten Fehler
4. Blinder A/B-Test — 3 Szenarien, randomisierte Reihenfolge, duales Scoring:
   • Eval-Regeln (60 % Gewicht) + LLM-Judge (40 % Gewicht)
5. PR erstellen — gewinnt die neue Version (new_wins > old_wins), wird ein Pull Request erstellt
6. CEO-Bericht — Ergebnisse werden per Telegram für die finale Entscheidung zugestellt

Qualitätsmetriken

Jedes Projekt akkumuliert Statistiken in 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
    }
  ]
}

Diese Metriken ermöglichen es dem System, objektiv zu bestimmen, welche Skills verbessert werden müssen, und den Fortschritt nach Updates zu verfolgen.