Workers et la couche d'intelligence

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

Système de workers

Chaque worker est un agent IA distinct avec un rôle, un modèle et un ensemble d'outils définis. Les workers opèrent au sein d'un projet et sont accessibles via l'UI du Workspace ou les commandes Telegram (/c, /d, /w:worker_id).

Bibliothèque de presets canonique (12)

Tous les presets vivent dans config/workers_registry.json et sont disponibles via GET /api/crm/workers/presets. Chacun est un template générique pour tout projet : pas de références de marque, pas de noms de personnages, pas de références à notre infrastructure.

Ingénierie / Core (6) :

Ops de startup (6, ajoutés en Phase 66) :

Créer un worker dans un projet

Via l'UI (par défaut) : clique sur + Add dans la barre de pills du WorkerSelector → le WorkerCreationWizard s'ouvre avec 3 étapes :

1. Identity — choisis une carte de preset OU « From scratch »
2. Capabilities — modèle + outils + avertissements intelligents (ex. « rôle read-only + outil Write = misconfig »)
3. Instructions — system prompt + picker de skills + aperçu en direct

L'assistant auto-injecte la baseline SYSTEM_PROTOCOL (voir ci-dessous) — le preset se concentre uniquement sur l'expertise spécifique au rôle.

Via CLI / API : POST /api/crm/projects/:name/workers avec le body complet (forme legacy, lien « Show advanced form → » dans l'assistant).

Types de workers

• chat — conversation tour par tour avec l'historique de contexte complet. Le worker reçoit toute la conversation précédente et répond comme un partenaire de dialogue.
• terminal — exécution en streaming avec événements d'outils. Le worker opère comme une session terminal, lançant 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

Alors que worker.system_prompt définit l'expertise spécifique au rôle (l'analyst fait TAM/SAM/SOM, le sentinel fait des audits d'injection SQL), il y a 15 règles transversales que chaque worker doit suivre — du developer au pitch-coach. Au lieu 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.

5 règles de Workflow obligatoires

1. Chaque nouvelle tâche DOIT être enregistrée via arc issue create
2. Tout changement de plan DOIT mettre à jour ROADMAP.md via arc roadmap sync
3. Avant de commencer le travail, lis ROADMAP.md + les issues ouvertes (arc issues)
4. Après des changements significatifs, synchronise les connaissances via arc memory refresh
5. Logge une progression significative sur les issues via arc issue log <id> "<text>"

10 règles de Quality Baseline (#229)

6. Priorités : P0 > P1 > P2 > P3 — toujours savoir ce qui suit et pourquoi
7. Rapport de session : clôture le 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 deadline vs qualité — recommande une voie + 1-2 alternatives
10. Format : concis, tables/chiffres quand possible, actionnable plutôt que descriptif
11. Cite tes sources pour tout fait/chiffre ; « je ne sais pas » vaut mieux que fabriquer
12. Pas d'échecs silencieux : énonce les blocages explicitement, ne continue pas dans une mauvaise voie
13. Progression honnête : rapporte ce qui a réellement été livré (fait vs tenté vs échoué)
14. Convention plutôt qu'invention : suis les patterns existants, explique les écarts
15. Boucle de feedback des learnings : ajoute à learnings.md quand tu es 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 — seule la « User-first lens » (cadre spécifique) reste ; le reste (priorités/roadmap/issues/DoD/trade-offs) est désormais dans la baseline.

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

Binary Evals — Validation des réponses

Qu'est-ce que c'est ?

Des règles déclaratives pour vérifier la qualité des réponses des workers. Chaque règle est déterministe (pas d'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 plutôt qu'ils n'arrêtent.

6 types de règles

Format du fichier evals

Le fichier est placé à côté du 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 a un id unique, un name lisible, l'un des 6 types, une value à comparer, et une severity (warning ou info).

Context Router — Sélection automatique des skills

Comment ça marche ?

À chaque message, le Context Router note tous les skills de skills/_registry.json et sélectionne automatiquement les plus pertinents :

1. Correspondance de trigger (+2 points) — occurrence directe d'un mot trigger du message
2. Correspondance de keyword (+1 point) — proximité sémantique par mots-clés
3. Top-5 par score total, injectés 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és dans le prompt

Format du registry des skills

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

• triggers — mots qui indiquent directement le skill (haute priorité)
• keywords — termes additionnels pour l'association sémantique
• agents — quels workers peuvent utiliser ce skill
• category — classification (simple, complex, critical)

Learnings — Mémoire de corrections

Comment sont-ils créés ?

Les learnings sont des règles accumulées qui émergent du feedback :

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

Format du fichier

Le 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ébut de chaque session de worker
• Injectés dans le prompt GSD du Developer (budget — 2000 caractères)
• Les règles les plus récentes viennent en premier (priorité temporelle)
• Ils agissent comme une mémoire immunitaire — les erreurs faites une fois ne se répètent 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'auto-amélioration itérative.

Comment ça marche ?

Chaque nuit à 3h00 UTC, un pipeline automatique s'exécute :

1. Collecte des métriques — lit le quality-metrics.json de chaque projet
2. Recherche 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 du skill à partir des erreurs collectées
4. Test A/B en aveugle — 3 scénarios, ordre randomisé, double scoring :
   • Règles eval (poids 60 %) + juge LLM (poids 40 %)
5. Création de PR — si la nouvelle version gagne (new_wins > old_wins), une pull request est créée
6. Rapport au 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 quels skills ont besoin d'être améliorés et de suivre les progrès après les mises à jour.