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