# FabNum v2 — Organisation du travail

## Principes

Le contexte du projet va croître significativement (12 points d'évolution × specs + plans + code + tests).
Pour maintenir la cohérence dans le temps, le travail repose sur des **agents indépendants** orchestrés
depuis la conversation principale.

## Rôles

### Stéphan (humain)
- Vision produit, arbitrage, validation des spécifications
- Expertise métier (chaînes d'approvisionnement, minerais critiques, risques géopolitiques)
- Décision finale sur tous les choix

### Conversation principale (Claude Code)
- **Orchestrateur** — maintient la vision d'ensemble, briefe les agents, vérifie la cohérence entre les points
- Présente les résultats à Stéphan pour validation
- Ne fait PAS l'implémentation directement sauf cas trivial

### Agents indépendants
- **Exécutants spécialisés** — recherche, implémentation, revue, tests
- Reçoivent un brief ciblé avec uniquement le contexte nécessaire
- Lisent les fichiers de specs au moment de l'exécution (pas de contexte périmé)
- Leurs résultats sont toujours validés par Stéphan avant intégration

## Source de vérité

Les **documents écrits** (docs/) sont la source de vérité, pas les conversations.

| Document | Rôle |
| --- | --- |
| `docs/EVOLUTIONS.md` | Vision, quoi/pourquoi de chaque point |
| `docs/EVOLUTIONS-PLANIFICATION.md` | Macro-planification, phases, MVP |
| `docs/specs/point-XX-*.md` | Spécifications formelles par point |
| `docs/plans/point-XX-*.md` | Plans d'implémentation par point |
| `docs/architecture-globale.dot` | Architecture des modules |
| `CLAUDE.md` | Conventions de code et workflow |

## Cycle de travail par point

Chaque point d'évolution suit le cycle :

```
1. Brainstorming ciblé        → Stéphan + orchestrateur
   (approfondir le quoi, cas limites, choix à trancher)

2. Spécification formelle     → Agent rédacteur + validation Stéphan
   (spec précise dans docs/specs/)

3. Plan d'implémentation      → Agent planificateur + validation Stéphan
   (étapes techniques dans docs/plans/)

4. Implémentation             → Agent(s) développeur(s)
   (code, en worktree isolé si pertinent)

5. Revue indépendante         → Agent revieweur (n'a PAS participé à l'implémentation)
   (qualité, cohérence avec la spec, sécurité)

6. Validation                 → Stéphan
   (résultat final, merge si OK)
```

## Règles de briefing des agents

Un agent indépendant doit recevoir :

1. **L'objectif** — ce qu'on attend de lui (recherche, code, revue...)
2. **Les fichiers à lire** — les specs pertinentes, pas tout le projet
3. **Les contraintes** — budget zéro, open source, conventions de code
4. **Le périmètre** — ce qu'il doit faire ET ce qu'il ne doit pas toucher
5. **Le format de sortie** — rapport, code, plan, diff...

Un agent ne doit **jamais** :
- Modifier des fichiers hors de son périmètre
- Prendre des décisions architecturales sans que Stéphan ait validé
- Commiter directement (sauf instruction explicite)

## Parallélisation

Les agents peuvent travailler en parallèle sur des points indépendants.
Exemple pour la phase 1 :
- Agent A : revue de littérature pour le point 7 (niveaux)
- Agent B : spike technique sur les bases de données (point 6)

Les résultats sont consolidés par l'orchestrateur avant de passer à la phase suivante.

## Cohérence

- Après chaque implémentation significative, un **agent de cohérence** relit les specs des points adjacents pour vérifier qu'aucune décision ne les invalide.
- Les specs sont mises à jour si des découvertes en implémentation imposent des ajustements (avec validation Stéphan).
- Le fichier `EVOLUTIONS.md` reste le document de référence global et est mis à jour en conséquence.