Workers et Intelligence Layer

Arc OS utilise un système de workers pour distribuer les tâches entre des agents IA spécialisés, tandis que l'Intelligence Layer garantit la qualité de leurs réponses via quatre modules : Binary Evals, Context Router, Learnings et Karpathy Loop.

Système de workers

Chaque worker est un agent IA indépendant avec un rôle défini, un modèle et un ensemble d'outils. Les workers opèrent dans le cadre d'un projet et sont accessibles via le Workspace UI ou les commandes Telegram (/c, /d, /w:worker_id).

Bibliothèque canonique de presets (12)

Tous les presets vivent dans config/workers_registry.json et sont accessibles via GET /api/crm/workers/presets. Chacun est un template générique pour n'importe quel projet : aucune référence de marque, aucun nom de personnage, aucune référence à notre infrastructure.

Engineering / Core (6) :

Startup operations (6, ajoutés en Phase 66) :

Créer un worker dans un projet

Via l'UI (par défaut) : clic sur + Add dans la pill bar du WorkerSelector → ouvre le WorkerCreationWizard en 3 étapes :

1. Identity — choisir une carte de preset OU "From scratch"
2. Capabilities — modèle + tools + avertissements intelligents (p. ex. "rôle read-only + outil Write = misconfig")
3. Instructions — prompt système + sélecteur de skills + aperçu live

Le wizard auto-injecte le baseline SYSTEM_PROTOCOL (voir plus bas) — le preset se concentre uniquement sur l'expertise propre au rôle.

Via CLI / API : POST /api/crm/projects/:name/workers avec le body complet (formulaire legacy, lien "Show advanced form →" dans le wizard).

Types de workers

• chat — conversation en mode tour par tour avec l'historique de contexte complet. Le worker reçoit tous les échanges précédents et répond comme un interlocuteur.
• terminal — exécution en streaming avec des events d'outils. Le worker fonctionne comme une session terminal, exécutant les outils séquentiellement et diffusant la progression en temps réel.

Créer un worker personnalisé

Les workers personnalisés sont décrits dans le fichier config/workers_registry.json. Chaque entrée définit le comportement de l'agent :

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

Champs de configuration

SYSTEM_PROTOCOL — Baseline pour tous les workers

Tandis que worker.system_prompt définit l'expertise propre au rôle (l'analyst fait du TAM/SAM/SOM, le sentinel fait des audits d'injection SQL), il existe 15 règles transverses que tout worker doit respecter — du developer au pitch-coach. Plutôt que de les dupliquer dans chaque preset, elles vivent dans une seule constante (shared/cli-routes.ts:SYSTEM_PROTOCOL) et sont auto-injectées à chaque spawn de worker via child-bot/claude-runner.ts.

Les 5 règles du 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>"

Les 10 règles du Quality Baseline (#229)

6. Priorities : P0 > P1 > P2 > P3 — toujours savoir quoi faire ensuite et pourquoi
7. Session report : clore tout travail significatif avec arc report --summary
8. Definition of Done inclut la documentation, pas seulement le commit
9. Trade-offs explicites : périmètre vs délai vs qualité — recommander une voie + 1-2 alternatives
10. Format : concis, tableaux/chiffres autant que possible, l'actionnable prime sur le descriptif
11. Citer les sources pour tout fait/chiffre ; "je ne sais pas" vaut mieux qu'une invention
12. Pas d'échecs silencieux : énoncer les blocages explicitement, ne pas continuer sur une mauvaise voie
13. Progrès honnête : rapporter ce qui a réellement été livré (done vs attempted vs failed)
14. Convention plutôt qu'invention : suivre les patterns existants, expliquer les écarts
15. Boucle de feedback learnings : ajouter à learnings.md quand on est corrigé sur une erreur récurrente

Effet

Grâce à cette injection automatique, les presets sont devenus 50-70 % plus courts. Exemple : product-owner est passé de 733 à 404 caractères — il ne reste que la "User-first lens" (cadre spécifique), le reste (priorities/roadmap/issues/DoD/trade-offs) est désormais dans le baseline.

Les admins peuvent étendre le baseline dans shared/cli-routes.ts — le changement s'applique automatiquement à tous les workers au prochain spawn.

Binary Evals — Validation des réponses

C'est quoi ?

Des règles déclaratives pour vérifier la qualité des réponses des workers. Chaque règle est déterministe (sans IA), s'exécute instantanément et ne bloque pas la réponse. Les résultats ont une sévérité warning ou info — ils informent, ils n'arrêtent pas.

6 types de règles

Format du fichier evals

Le fichier est placé à côté de la 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"
    }
  ]
}

Chaque règle possède un id unique, un name lisible par un humain, l'un des 6 types, une value de comparaison et une severity (warning ou info).

Context Router — Sélection automatique des skills

Comment ça fonctionne ?

À chaque message, le Context Router score toutes les skills de skills/_registry.json et sélectionne automatiquement les plus pertinentes :

1. Trigger match (+2 points) — correspondance directe d'un mot déclencheur du message
2. Keyword match (+1 point) — proximité sémantique via les mots-clés
3. Top-5 par score total, injectées comme SKILLS_HINT dans le prompt du worker

Exemple

Message : "review the git commit for security"

• code-review : trigger "review" trouvé → +2 points
• git-manager : keyword "commit" trouvé → +1 point
• Résultat : code-review (2), git-manager (1) injectées dans le prompt

Format du registre de skills

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

• triggers — mots qui indiquent clairement une skill (haute priorité)
• keywords — termes supplémentaires pour l'association sémantique
• agents — quels workers peuvent utiliser cette skill
• category — classification (simple, complex, critical)

Learnings — Mémoire des corrections

Comment sont-ils créés ?

Les Learnings sont des règles accumulées qui émergent des retours d'expérience :

1. Thumbs-down (👎) — un learning est automatiquement créé avec la source "negative" à partir de la réponse problématique
2. Fix It — relancer une tâche génère un learning avec la source "fixit"
3. Manuels — décisions architecturales et règles, source "manual" ou "architecture"

Format du fichier

Fichier learnings.md à la racine du projet :

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

Comment sont-ils utilisés ?

• Chargés au démarrage de chaque session de worker
• Injectés dans le prompt GSD du Developer (budget — 2000 caractères)
• Les règles les plus récentes en premier (priorité par date)
• Agissent comme une mémoire immunitaire — les erreurs commises une fois ne se reproduisent pas dans les sessions suivantes

Karpathy Loop — Auto-amélioration nocturne

Un cycle automatique d'amélioration des skills, inspiré des idées d'Andrej Karpathy sur l'amélioration itérative.

Comment ça fonctionne ?

Chaque nuit à 3h00 UTC, un pipeline automatique se lance :

1. Collecte de métriques — lit le quality-metrics.json de chaque projet
2. Détection des skills problématiques — filtre les skills avec un taux de succès < 80% ou plus de feedback négatif que positif
3. Analyse Sage — Haiku génère une version améliorée de la skill à partir des erreurs collectées
4. Test A/B en aveugle — 3 scénarios, ordre randomisé, double scoring :
   • Règles Eval (60% du poids) + juge LLM (40% du poids)
5. Création de PR — si la nouvelle version l'emporte (new_wins > old_wins), une pull request est créée
6. Rapport CEO — les résultats sont envoyés sur Telegram pour la décision finale

Métriques de qualité

Chaque projet accumule des statistiques dans 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
    }
  ]
}

Ces métriques permettent au système de déterminer objectivement quelles skills nécessitent une amélioration, et de suivre les progrès après les mises à jour.