docs/AGENT_TEAMS_PROPOSAL.md

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

Réflexion inspirée de l'article 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 :

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 :

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.