Code/docs/ORGANISATION.md

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.