# Proposition - Passer d'un agent unique à une équipe d'agents

> Réflexion inspirée de l'article [The Collaboration Gap](https://robotscooking.substack.com/p/the-collaboration-gap) (Adam Hyde, 2026) appliquée à `collab-editor`.

## 1. Constat sur l'état actuel

Le `collab-editor` est aujourd'hui structuré autour de **deux agents isolés** :

| Agent | Fichier | Rôle |
|---|---|---|
| Article agent | `backend/src/agent/chat.ts` + `frontend/src/hooks/useAgentChat.ts` | Édite le TipTap doc via `applyDiff` / `replaceSelection` / `insertAtCursor` |
| Embed agent | `backend/src/agent/embed-chat.ts` + `frontend/src/hooks/useEmbedChat.ts` | Génère les embeds D3 |

Les deux ne se parlent pas. Ils ne partagent pas de contexte. L'utilisateur est le seul "orchestrateur", à la main, en switchant d'interface.

C'est exactement le pattern "one human, one AI, one task" que l'article pointe comme limitant.

## 2. Ce qu'on a déjà gratuitement (et que la plupart des setups multi-agents n'ont pas)

| Brique | Fichier | Pourquoi c'est un atout |
|---|---|---|
| État partagé versionné (CRDT) | Y.js + Hocuspocus | C'est LE "shared board" de l'article, déjà construit, déjà résolveur de conflits |
| Canal de messages ancrés | `frontend/src/editor/comments.ts` + `CommentsSidebar.tsx` | Communication latérale entre agents, visible par l'humain |
| Undo groupé par tour | `UndoManager` + `startAgentBatch` | Rollback atomique d'une action d'équipe |
| Tool calls structurés | `backend/src/agent/tools.ts` | Protocole déjà formalisé |
| Frontmatter store réactif | `frontend/src/editor/frontmatter/frontmatter-store.ts` | État structuré séparé du corps, parfait pour un agent dédié |

**Traduction** : on est mieux placés que Pure.Science pour implémenter ce que décrit Adam Hyde, parce que notre "bubble" existe déjà côté humain.

## 3. Proposition d'architecture - 5 rôles

Inspirée directement de Pure.Science (Wax, Ketty, Coco, Paige, Koda), mais adaptée à l'écriture scientifique web-native.

### 3.1. Rôles

| Agent | Rôle | Outils autorisés | Zones d'écriture |
|---|---|---|---|
| **Scout** | Topic Strategist : cadre le papier, propose l'angle | `setFrontmatterDraft`, `proposeOutline` (commentaire) | Commentaires uniquement |
| **Archi** | Outliner / Structurer : gère TOC, hiérarchie, sections | `applyDiff` sur headings, `insertSection` | Headings, structure |
| **Scribe** | Writer : rédige les paragraphes | `applyDiff`, `insertAtCursor` | Corps du texte |
| **Biblio** | Literature Retriever : cherche des refs, pose des citations | `addCitation`, `addBibEntry`, `commentSuggestion` | Bibliography.bib + balises `[@key]` |
| **Critic** | QA / Reviewer : relit, pointe incohérences, passe des commentaires | `comment`, `resolveComment`, `flagInconsistency` | Commentaires uniquement (read-only sur le doc) |

**Point crucial** : seuls `Archi` et `Scribe` touchent au texte. `Critic` **ne peut pas éditer**, il commente - ça force la friction que décrit l'article et évite le "yes-man loop" des LLMs.

### 3.2. Orchestrateur

Un agent léger côté backend (nouveau fichier `backend/src/agent/orchestrator.ts`) qui :

1. Reçoit le message de l'humain
2. Lit l'état du doc (+ frontmatter + commentaires ouverts)
3. Décide quel(s) agent(s) réveiller et dans quel ordre
4. Tient un journal de tâches visible (équivalent du "board" dans l'article)

L'orchestrateur n'édite jamais. Il **dispatche** et **attend**. Comme le facilitateur d'un Book Sprint.

### 3.3. Code de conduite partagé

Un prompt-système commun (nouveau `backend/src/agent/team-code-of-conduct.ts`) injecté dans **tous** les agents :

```md
1. Avant toute action, lis le board (commentaires ouverts + journal orchestrateur).
2. Reste dans ton rôle. Si une tâche sort de ton périmètre, ping l'agent compétent via un commentaire typé.
3. N'écrase pas le travail d'un autre agent sans laisser un commentaire justifiant le changement.
4. Les désaccords se résolvent par commentaire ancré, pas par écrasement silencieux.
5. Sois concis. Un message = une intention.
```

Directement dérivé du "code of conduct" Pure.Science.

## 4. Communication latérale - piggyback sur les commentaires

Plutôt qu'un bus de messages séparé, on étend le système de commentaires existant avec un champ `author` et `audience` :

```ts
interface AgentComment {
  author: "scout" | "archi" | "scribe" | "biblio" | "critic" | "human";
  audience: Array<"scout" | "archi" | "scribe" | "biblio" | "critic" | "human">;
  kind: "suggestion" | "question" | "blocker" | "task";
  anchor: { from: number; to: number };
  body: string;
}
```

Bénéfices :
- L'humain voit **tout** dans la sidebar existante (`CommentsSidebar.tsx`)
- Les agents s'adressent à un autre agent via `audience: ["scribe"]`
- Rien à construire côté infra, juste étendre le schema

## 5. UI - rendre l'équipe visible

L'article insiste sur le fait que **la valeur de la collab est invisible si on ne la montre pas**. Proposition côté UI :

### 5.1. Team activity timeline

Un petit panneau dans `TopBar.tsx` ou sous le chat :

```
[Archi]  → created section "Methodology"       2s ago
[Biblio] → suggested 3 citations in §2         5s ago
[Critic] → flagged: unsupported claim in §3    8s ago
[Scribe] → drafted paragraph in §1             12s ago
```

### 5.2. Curseurs colorés par agent

On a déjà les curseurs multi-utilisateurs via `collaboration-cursor-v3.ts`. Chaque agent devient un "utilisateur virtuel" avec sa couleur et son nom de rôle. L'humain **voit en direct** où chaque agent travaille. Zero nouvelle infra.

### 5.3. Quick actions par rôle

Remplacer le `sendQuickAction` générique de `useAgentChat.ts` par un sélecteur de rôle :

```
Ask [ Scribe ▾ ] to: [ rewrite this paragraph ]
```

## 6. Plan d'implémentation progressif

Par ordre de ROI, du plus petit au plus gros.

### Étape 1 - Split sémantique sans nouvelle infra (2-3j)

- Spécialiser le prompt actuel : le SYSTEM prompt passe de "tu es un assistant qui édite" à "tu es le Scribe, tu écris les paragraphes".
- Ajouter un prompt `Critic` qui ne fait QUE passer des commentaires (pas de tool d'édition).
- UI : un dropdown "Talk to [ Scribe / Critic ]".

Valeur : on valide l'hypothèse qu'un agent read-only qui commente améliore la qualité perçue, avant de construire l'orchestration.

### Étape 2 - Curseurs agents + timeline (2j)

- Chaque agent = user Y.js virtuel avec couleur.
- Timeline agrégée depuis les tool calls loggés.

Valeur : rend la collaboration lisible, c'est le point central d'Adam Hyde.

### Étape 3 - Biblio agent autonome (3-4j)

- Outils `addCitation`, `searchArxiv`, `addBibEntry`.
- Déclenchement automatique quand `Scribe` écrit une affirmation factuelle (via tool `requestCitation`).

Valeur : premier cas de communication latérale agent→agent concrète.

### Étape 4 - Orchestrateur (5-7j)

- Nouveau route `/api/orchestrate` qui dispatche plutôt que de `/api/chat` directement.
- Board visible dans le chat.

Valeur : vrai multi-agent, mais seulement une fois les étapes 1-3 validées.

### Étape 5 - Scout (cadrage initial) (3j)

- Agent qui intervient uniquement au début d'un nouveau doc, à partir d'un prompt court "je veux écrire sur X".
- Génère frontmatter + TOC + commentaires de cadrage.

Valeur : onboarding d'un nouvel article 10x plus fluide.

## 7. Métrique de succès

Adam Hyde souligne qu'on ne sait pas benchmarker la collaboration. Proposition de 3 mesures simples et propres à l'éditeur :

| Métrique | Comment | Pourquoi |
|---|---|---|
| **Commentaires résolus par session** | Compteur via le store de commentaires | Proxy de la qualité de la friction |
| **Ratio d'édits rollback par l'humain** | Undo après action agent / total actions agent | Mesure l'alignement |
| **Temps médian d'un article jusqu'à "publish"** | Log `published_at - created_at` côté backend | Mesure l'effet global |

Pas de benchmark LLM abstrait : on mesure **sur le produit**.

## 8. Risques et limites

- **Coût tokens ×N** : chaque tour peut réveiller 2-3 agents. À mitiger avec un routing intelligent côté orchestrateur (ne pas réveiller `Biblio` si le message est "fix grammaire").
- **LLMs d'accord avec tout** : le rôle `Critic` ne marche que si le prompt force la contradiction explicite. À itérer avec des exemples few-shot.
- **UX du bruit** : si les 5 agents commentent en permanence, la sidebar devient illisible. Prévoir un mode "muet par défaut, opt-in par rôle".
- **Complexité de debug** : logger impérativement le journal orchestrateur pour pouvoir rejouer une session.

## 9. Ce que ça apporte à ton produit

Aujourd'hui `collab-editor` est "un Notion-like pour papiers scientifiques avec un AI assistant". C'est bien, mais une dizaine de produits font ça.

Avec cette architecture, tu deviens **le premier éditeur scientifique où une équipe d'agents spécialisés co-écrit avec l'humain**, en s'appuyant sur l'infra temps-réel Y.js que tu as déjà. C'est une proposition produit claire et différenciante, directement alignée avec la thèse de l'article :

> "Les organisations qui investissent dans l'architecture de collaboration avec le même sérieux qu'elles investissent dans la capacité des modèles produiront de meilleurs résultats."

## 10. Prochaine étape concrète suggérée

Commencer par **l'étape 1** : forker `useAgentChat` en `useScribeChat` + `useCriticChat`, avec un simple toggle d'UI. C'est 2 jours de boulot, ça valide ou invalide l'hypothèse avant d'engager l'orchestrateur.