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