rpa_vision_v3/docs/coordination

Coordination multi-agents

But: échanger par fichiers courts, ciblés et auditables entre Codex, Claude, Gemini et Dom, tout en capitalisant les décisions, erreurs, corrections et résultats de tests.

Arborescence

• inbox_codex/ Messages que Codex doit lire et arbitrer.
• inbox_claude/ Messages que Claude doit lire.
• inbox_gemini/ Messages que Gemini doit lire quand le canal est utilisé.
• outbox_gemini/ Messages déposés pour Gemini quand son inbox directe n'est pas le canal actif.
• active/ Etat courant, files ouvertes, risques et prochaine action.
• syntheses/ Synthèses datées, lisibles par un humain qui reprend le projet.
• registre/ Registre des décisions, validations, échecs utiles et reports.
• index/ Index manuel ou généré des messages importants.
• archive/YYYY-MM-DD/ Messages traités et sortis du flux actif. Ne pas archiver une conversation en cours sans confirmation Codex.
• templates/ et TEMPLATE_MESSAGE.md Modèles de message.

Convention

1. Une question = un fichier.
2. L'émetteur écrit dans l'inbox du destinataire.
3. Le destinataire répond dans l'inbox de l'émetteur.
4. Le nom de fichier suit: YYYY-MM-DD_HHMM_sender-to-recipient_slug.md
5. Chaque message contient au minimum: Contexte, Constat, Question précise, Contraintes, Attendu, Statut.
6. Statut usuels: open, ACK, NACK, patched, validated, blocked, archived.
7. Une réponse doit citer le fichier source dans Répond à.
8. Quand la boucle est terminée, déplacer les fichiers dans archive/YYYY-MM-DD/. Tant qu'un agent peut encore répondre, laisser le fil dans les inbox.

Style attendu

• court et factuel
• références de fichiers/fonctions explicites
• pas de prose longue
• pas de code dans les messages de coordination sauf extrait très court si indispensable

Workflow actif

1. Codex pose une mission dans l'inbox du collègue.
2. Le collègue répond dans inbox_codex/ avec ACK/NACK.
3. Codex lit, vérifie, teste, arbitre.
4. Codex répond dans l'inbox du collègue.
5. Une synthèse ou une décision durable est recopiée dans syntheses/ ou registre/ avant archivage.

Même règle en sens inverse si Claude initie la demande.

Surveillance automatique

coordination_loop.sh surveille les inbox et cree un declencheur persistant a chaque nouveau message detecte.

Cette surveillance est obligatoire au debut de chaque session pour Codex, Claude et Qwen. Aucun handoff ne doit omettre ce pre-check.

Pre-check debut de session :

1. docs/coordination/coordination_loop.sh ensure
2. Lire les messages pertinents pour l'agent courant.
3. Apres traitement : docs/coordination/coordination_loop.sh ack

Si le watcher ne peut pas etre lance ou verifie, c'est un blocage de reprise a signaler explicitement.

Commandes utiles :

• docs/coordination/coordination_loop.sh ensure : lance si besoin, scanne, affiche pending.
• docs/coordination/coordination_loop.sh start 15 : demarre la surveillance.
• docs/coordination/coordination_loop.sh service-install : installe/met a jour et redemarre le watcher systemd utilisateur persistant.
• docs/coordination/coordination_loop.sh service-stop : arrete et desactive le watcher systemd utilisateur.
• docs/coordination/coordination_loop.sh status : etat, compteurs et file unread.
• docs/coordination/coordination_loop.sh pending : messages detectes non ACK localement.
• docs/coordination/coordination_loop.sh ack : vide la file unread locale.
• docs/coordination/coordination_loop.sh events : derniers evenements detectes.

Artefacts crees :

• .loop_state/unread_messages.tsv : file des messages a traiter.
• .loop_state/unread_digest.md : digest lisible au debut de session.
• .loop_state/latest_message.trigger : dernier declencheur.
• .loop_state/message_events.tsv : journal evenements machine-readable.
• .loop_state/triggers/*.trigger : un fichier declencheur par message.

Un hook externe peut etre branche avec COORD_LOOP_TRIGGER_CMD. Le hook recoit COORD_MESSAGE_DIR, COORD_MESSAGE_FILE, COORD_MESSAGE_PATH, COORD_MESSAGE_STATUS et COORD_TRIGGER_FILE.

Règle de capitalisation

Un message de coordination est un flux. Une synthèse ou un registre est une mémoire.

Chaque avancée importante doit être convertie en au moins un des artefacts :

• décision durable dans registre/ ;
• synthèse de reprise dans syntheses/ ;
• état courant dans active/ ;
• entrée d'index dans index/.

Ne pas supprimer les messages bruts : ils servent d'audit trail.