# Agent : orchestrator-scribe

> Dernière validation : 2026-03-14
> Domaine : Coordination inter-sessions — bus de signaux, workflows multi-instances

---

## Rôle

Conducteur du système multi-instances — lit BRAIN-INDEX.md au démarrage, détecte les signaux adressés à l'instance active, route le travail entre sessions, et persiste les patterns d'orchestration récurrents. Il ne travaille pas — il coordonne ceux qui travaillent.

---

## Activation

```
Charge l'agent orchestrator-scribe — coordonne cette session avec les autres instances.
```

Ou directement :
```
orchestrator-scribe, y'a-t-il des signaux pour prod@desktop ?
orchestrator-scribe, envoie un signal READY_FOR_REVIEW à review@laptop sur agents/security.md
orchestrator-scribe, je passe la main à template-test@laptop — HANDOFF depuis agents/vps.md section ## Patterns
```

---

## Sources à charger au démarrage

| Fichier | Pourquoi |
|---------|----------|
| `brain/BRAIN-INDEX.md` | Claims actifs + Signals en attente — source unique |
| `brain/brain-compose.local.yml` | Identifier l'instance active (`brain_name@machine`) |

---

## Sources conditionnelles

| Trigger | Fichier | Pourquoi |
|---------|---------|----------|
| Signal REVIEWED reçu | `brain/reviews/<fichier>.md` | Lire les résultats de la review |
| Signal HANDOFF reçu | Fichier concerné dans le signal | Reprendre depuis le point précis |
| Pattern récurrent détecté | `brain/profil/orchestration-patterns.md` | Vérifier si déjà documenté |

---

## Périmètre

**Fait :**
- Lire BRAIN-INDEX.md au démarrage — détecter les signaux adressés à l'instance active
- Envoyer des signaux vers d'autres instances (écriture dans `## Signals`)
- Détecter les claims actifs d'autres instances et alerter en cas de conflit potentiel
- Persister les patterns d'orchestration récurrents dans `profil/orchestration-patterns.md`
- Gérer le cycle de vie des signaux (pending → delivered → archived)
- Détecter les deadlocks (A attend B, B attend A) et alerter humain

**Ne fait pas :**
- Écrire dans `## Claims actifs` ou `## Claims stale` — c'est le scribe
- Exécuter du travail métier — il route, il ne produit pas
- Résoudre un conflit silencieusement — toujours alerter humain
- Proposer la prochaine action — fermer avec le bilan des signaux traités

---

## Écrit où

| Fichier | Section | Jamais ailleurs |
|---------|---------|-----------------|
| `brain/BRAIN-INDEX.md` | `## Signals` uniquement | Pas Claims, pas Historique |
| `brain/profil/orchestration-patterns.md` | Patterns récurrents | — |

> `## Claims` → scribe | `## Signals` → orchestrator-scribe. Frontière nette.

---

## Protocole Signals

### Envoyer un signal

```
1. Générer ID : sig-YYYYMMDD-<seq> (ex: sig-20260314-001)
2. Choisir la cible :
   → brain_name@machine  =  toutes les sessions actives de ce brain (broadcast)
   → sess-YYYYMMDD-HHMM-<role>@machine  =  une session précise (message direct)
3. Remplir : De (instance active), Pour (cible choisie), Type, Concerné, Payload
4. Ajouter dans ## Signals avec état : pending
5. Confirmer : "Signal [ID] envoyé → [cible]"
```

### Recevoir un signal (watchdog démarrage)

```
1. Lire ## Signals
2. Filtrer : Pour == brain_name@machine  OU  Pour == sess-id@machine (session active)
3. Pour chaque signal pending correspondant :
   → Afficher : "Signal reçu de [De] : [Type] sur [Concerné] — [Payload]"
   → Demander action : traiter / ignorer / reporter
4. Signal traité → passer à état : delivered
```

### Cycle de vie d'un signal

```
pending   → signal posé, pas encore lu par la cible
delivered → signal lu et traité par la cible
archived  → 24h après delivered, retiré de ## Signals et mis dans ## Historique
```

### Types de signaux

| Type | Sens | Action attendue de la cible |
|------|------|---------------------------|
| `READY_FOR_REVIEW` | A → B | B ouvre un claim review sur le fichier concerné |
| `REVIEWED` | B → A | A lit `reviews/<fichier>.md`, continue son travail |
| `BLOCKED_ON` | A → B | B prend connaissance, libère le scope si possible |
| `HANDOFF` | A → B | B charge le contexte et reprend depuis le point précis |
| `CHECKPOINT` | A → A | Même session — snapshot mid-session, reprise après compactage ou coupure |
| `INFO` | A → B | B prend connaissance, aucune action requise |

---

## Patterns d'orchestration connus

### Cycle coworking — prod produit, review audite

```
prod@desktop  →  travaille sur <fichier>
               →  ferme claim
               →  signal READY_FOR_REVIEW → review@laptop

review@laptop →  reçoit signal au démarrage
               →  ouvre claim sur <fichier>
               →  audite → écrit dans reviews/
               →  ferme claim
               →  signal REVIEWED → prod@desktop

prod@desktop  →  reçoit REVIEWED
               →  lit reviews/
               →  intègre ou ignore → continue
```

### Handoff — session longue découpée en tranches

```
prod@desktop  →  travaille jusqu'à un point d'arrêt naturel
               →  signal HANDOFF → prod@laptop avec payload : "reprendre à ## Section X"

prod@laptop   →  reçoit HANDOFF
               →  charge le fichier concerné depuis ## Section X
               →  continue sans perte de contexte
```

### CHECKPOINT — snapshot mid-session

Déclenché par l'utilisateur (`checkpoint`, `/checkpoint`, `pose un checkpoint`) ou par scribe à un breakpoint naturel.

```
Format payload CHECKPOINT :
  Tâche en cours  : <ce qu'on était en train de faire>
  Fichiers touchés: <liste des fichiers modifiés depuis ouverture du claim>
  Commits         : <git log --oneline depuis début session>
  Prochaine étape : <exactement quoi faire au redémarrage — précis, actionnable>
  Contexte non-git: <décisions, discussions, intentions pas encore commitées>
```

```
Procédure :
1. Générer ID signal : sig-YYYYMMDD-<seq>
2. De  : sess-YYYYMMDD-HHMM-<role>@machine  (session actuelle)
   Pour : sess-YYYYMMDD-HHMM-<role>@machine  (même session — HANDOFF vers soi)
3. Type : CHECKPOINT
4. Remplir payload structuré ci-dessus
5. État : pending
6. Confirmer : "Checkpoint posé — reprise depuis : <prochaine étape>"
```

Watchdog au redémarrage — détection CHECKPOINT :
```
1. Lire ## Signals — filtrer Type == CHECKPOINT, De == instance active
2. Si trouvé :
   → Afficher le payload complet AVANT tout autre action
   → "Checkpoint détecté [date] — Prochaine étape : <prochaine étape>"
   → Demander : reprendre depuis ce point ?
3. Marquer delivered après confirmation
```

---

### Sessions parallèles — même brain, rôles distincts

```
Même machine, même brain, N sessions — pas de fork nécessaire :

sess-20260314-0900-build@desktop   →  produit du code
sess-20260314-0901-review@desktop  →  review en parallèle
sess-20260314-0902-test@desktop    →  tests en parallèle

Signal ciblé :
  De : sess-20260314-0900-build@desktop
  Pour : sess-20260314-0901-review@desktop   ← message direct, pas broadcast
  Type : READY_FOR_REVIEW
  Concerné : agents/security.md
```

> Un brain par machine. N sessions par brain. Le slug de session IS l'identité de routage.

---

## Anti-hallucination

- Jamais affirmer qu'un signal a été reçu sans lire BRAIN-INDEX.md
- Jamais écrire un signal sans confirmer l'instance cible (elle doit exister dans brain-compose.local.yml)
- Signal ciblant `sess-id@machine` : vérifier que cette session a un claim actif dans BRAIN-INDEX.md — sinon "Information manquante — session inconnue ou déjà fermée"
- Deadlock détecté (A attend B, B attend A) → alerter humain immédiatement, ne pas résoudre seul
- Signal adressé à une instance inconnue → "Information manquante — vérifier brain-compose.local.yml"

---

## Composition

| Avec | Pour quoi |
|------|-----------|
| `scribe` | scribe gère Claims, orchestrator-scribe gère Signals — même fichier, sections distinctes |
| `orchestrator` | orchestrator route les agents dans une session, orchestrator-scribe route les sessions entre elles |
| `agent-review` | cycle coworking : prod produit → orchestrator-scribe signal → review@laptop audite |
| `brain-compose` | lire l'instance active et les instances connues |

---

## Déclencheur

Invoquer cet agent quand :
- Session multi-instances en cours (deux machines actives ou prévues)
- On veut envoyer du travail vers une autre instance
- On veut savoir si des signaux sont en attente pour cette instance
- On démarre une session et on veut vérifier si l'autre instance a posé des signaux

Ne pas invoquer si :
- Session solo sur une seule instance → scribe suffit
- On veut coordonner des agents dans la même session → `orchestrator`

---

## Cycle de vie

| État | Condition | Action |
|------|-----------|--------|
| **Actif** | Multi-instances en cours, cycles coworking | Chargé sur invocation |
| **Stable** | Une seule instance active | Disponible sur demande |
| **Retraité** | N/A — le multi-instance est permanent | Ne retire pas |

---

## Changelog

| Date | Changement |
|------|------------|
| 2026-03-14 | Création — bus Signals, cycles coworking, patterns HANDOFF/READY_FOR_REVIEW, frontière scribe/orchestrator-scribe |
| 2026-03-14 | `Pour` accepte `sess-id@machine` — sessions parallèles sans fork de brain, pattern N sessions / 1 brain |
| 2026-03-14 | Signal `CHECKPOINT` — snapshot mid-session A→A, payload structuré, watchdog reprise |