From 750d1325522d000a3c1762f36fb9a24f8a4197ef Mon Sep 17 00:00:00 2001 From: Tetardtek Date: Sat, 14 Mar 2026 01:53:50 +0100 Subject: [PATCH] feat: initial brain-template - 30+ agents, profil universel, BSI, README installation --- BRAIN-INDEX.md | 38 ++++ PATHS.md | 64 ++++++ README.md | 165 ++++++++++++++ agents/AGENTS.md | 91 ++++++++ agents/PHILOSOPHY.md | 66 ++++++ agents/PLAN-REVIEW-AGENTS.md | 298 +++++++++++++++++++++++++ agents/_brief-brain-compose.md | 381 ++++++++++++++++++++++++++++++++ agents/_template.md | 166 ++++++++++++++ agents/agent-review.md | 200 +++++++++++++++++ agents/aside.md | 169 ++++++++++++++ agents/brain-compose.md | 312 ++++++++++++++++++++++++++ agents/brainstorm.md | 205 +++++++++++++++++ agents/capital-scribe.md | 165 ++++++++++++++ agents/ci-cd.md | 205 +++++++++++++++++ agents/coach-scribe.md | 174 +++++++++++++++ agents/coach.md | 243 ++++++++++++++++++++ agents/code-review.md | 158 +++++++++++++ agents/config-scribe.md | 206 +++++++++++++++++ agents/debug.md | 208 +++++++++++++++++ agents/doc.md | 190 ++++++++++++++++ agents/frontend-stack.md | 227 +++++++++++++++++++ agents/git-analyst.md | 184 +++++++++++++++ agents/helloWorld.md | 193 ++++++++++++++++ agents/i18n.md | 184 +++++++++++++++ agents/interprete.md | 181 +++++++++++++++ agents/mail.md | 171 ++++++++++++++ agents/mentor.md | 186 ++++++++++++++++ agents/migration.md | 190 ++++++++++++++++ agents/monitoring.md | 231 +++++++++++++++++++ agents/optimizer-backend.md | 158 +++++++++++++ agents/optimizer-db.md | 161 ++++++++++++++ agents/optimizer-frontend.md | 157 +++++++++++++ agents/orchestrator.md | 183 +++++++++++++++ agents/pm2.md | 235 ++++++++++++++++++++ agents/recruiter.md | 215 ++++++++++++++++++ agents/refacto.md | 184 +++++++++++++++ agents/scribe.md | 282 +++++++++++++++++++++++ agents/security.md | 194 ++++++++++++++++ agents/testing.md | 194 ++++++++++++++++ agents/todo-scribe.md | 161 ++++++++++++++ agents/toolkit-scribe.md | 193 ++++++++++++++++ agents/vps.md | 165 ++++++++++++++ profil/CLAUDE.md.example | 60 +++++ profil/anti-hallucination.md | 119 ++++++++++ profil/bsi-spec.md | 190 ++++++++++++++++ profil/collaboration.md.example | 112 ++++++++++ profil/context-hygiene.md | 103 +++++++++ profil/memory-architecture.md | 120 ++++++++++ profil/memory-integrity.md | 126 +++++++++++ profil/scribe-pattern.md | 76 +++++++ profil/scribe-system.md | 112 ++++++++++ 51 files changed, 8951 insertions(+) create mode 100644 BRAIN-INDEX.md create mode 100644 PATHS.md create mode 100644 README.md create mode 100644 agents/AGENTS.md create mode 100644 agents/PHILOSOPHY.md create mode 100644 agents/PLAN-REVIEW-AGENTS.md create mode 100644 agents/_brief-brain-compose.md create mode 100644 agents/_template.md create mode 100644 agents/agent-review.md create mode 100644 agents/aside.md create mode 100644 agents/brain-compose.md create mode 100644 agents/brainstorm.md create mode 100644 agents/capital-scribe.md create mode 100644 agents/ci-cd.md create mode 100644 agents/coach-scribe.md create mode 100644 agents/coach.md create mode 100644 agents/code-review.md create mode 100644 agents/config-scribe.md create mode 100644 agents/debug.md create mode 100644 agents/doc.md create mode 100644 agents/frontend-stack.md create mode 100644 agents/git-analyst.md create mode 100644 agents/helloWorld.md create mode 100644 agents/i18n.md create mode 100644 agents/interprete.md create mode 100644 agents/mail.md create mode 100644 agents/mentor.md create mode 100644 agents/migration.md create mode 100644 agents/monitoring.md create mode 100644 agents/optimizer-backend.md create mode 100644 agents/optimizer-db.md create mode 100644 agents/optimizer-frontend.md create mode 100644 agents/orchestrator.md create mode 100644 agents/pm2.md create mode 100644 agents/recruiter.md create mode 100644 agents/refacto.md create mode 100644 agents/scribe.md create mode 100644 agents/security.md create mode 100644 agents/testing.md create mode 100644 agents/todo-scribe.md create mode 100644 agents/toolkit-scribe.md create mode 100644 agents/vps.md create mode 100644 profil/CLAUDE.md.example create mode 100644 profil/anti-hallucination.md create mode 100644 profil/bsi-spec.md create mode 100644 profil/collaboration.md.example create mode 100644 profil/context-hygiene.md create mode 100644 profil/memory-architecture.md create mode 100644 profil/memory-integrity.md create mode 100644 profil/scribe-pattern.md create mode 100644 profil/scribe-system.md diff --git a/BRAIN-INDEX.md b/BRAIN-INDEX.md new file mode 100644 index 0000000..bc8dc05 --- /dev/null +++ b/BRAIN-INDEX.md @@ -0,0 +1,38 @@ +# BRAIN-INDEX.md — Registre de claims + +> Système de locking optimiste — Brain Session Index (BSI). +> Mis à jour par le **scribe uniquement**. Ne jamais éditer manuellement. +> Spec complète : `brain/profil/bsi-spec.md` + +--- + +## Claims actifs + +| Session | Portée | Niveau | Ouvert le | Expire le | État | +|---------|--------|--------|-----------|-----------|------| +| — | — | — | — | — | — | + +*Aucun claim actif.* + +--- + +## Claims stale — contrôle humain requis + +| Session | Portée | Expiré le | Action requise | +|---------|--------|-----------|----------------| + +*Aucun claim stale.* + +--- + +## Historique — 30 derniers jours + +| Session | Portée | Ouvert | Fermé | Statut | +|---------|--------|--------|-------|--------| + +*Aucun historique.* + +--- + +> **Règle watchdog :** au démarrage de chaque session brain, le scribe scanne ce fichier. +> TTL expiré → déplacer vers "Claims stale". Jamais auto-release — contrôle humain toujours. diff --git a/PATHS.md b/PATHS.md new file mode 100644 index 0000000..c6d0478 --- /dev/null +++ b/PATHS.md @@ -0,0 +1,64 @@ +# PATHS.md — Résolution des chemins machine + +> ⚠️ Fichier machine-spécifique — seul fichier à mettre à jour lors d'un export ou changement de machine. +> Tous les agents utilisent les noms sémantiques ci-dessous. Ne jamais hardcoder un chemin absolu ailleurs. + +--- + +## Chemins actifs + +| Nom sémantique | Chemin réel | Remote | Gitignored dans brain | +|----------------|-------------|--------|----------------------| +| `brain/` | `` | `//brain` | — (repo racine) | +| `toolkit/` | `/toolkit/` | `//toolkit` | ✅ | +| `progression/` | `/progression/` | `//progression-coach` | ✅ | +| `reviews/` | `/reviews/` | `//brain-agent-review` | ✅ | +| `profil/` | `/profil/` | `//brain-profil` | ✅ | +| `todo/` | `/todo/` | `//brain-todo` | ✅ | +| `projects/` | `` | GitHub | — | +| `home/` | `` | — | — | + +## Architecture satellite repos + +Les repos gitignorés dans `brain/` sont des **satellites autonomes** — chacun a son propre remote. + +```bash +git clone :/brain.git +git clone :/toolkit.git /toolkit +git clone :/progression-coach.git /progression +git clone :/brain-agent-review.git /reviews +git clone :/brain-profil.git /profil +git clone :/brain-todo.git /todo +``` + +--- + +## Règle anti-hallucination — obligatoire pour tous les agents + +> Si un chemin n'est pas dans cette table → **ne pas deviner**. +> Écrire : `"Information manquante — vérifier PATHS.md"` + +--- + +## Procédure — nouvelle machine + +```bash +# 1. Cloner brain-template ou tous les satellites +git clone :/brain.git +# ... (voir ci-dessus) + +# 2. Installer CLAUDE.md +cp /profil/CLAUDE.md.example ~/.claude/CLAUDE.md +sed -i 's|||g' ~/.claude/CLAUDE.md + +# 3. Mettre à jour ce fichier PATHS.md avec les chemins réels +# 4. Done — le brain est opérationnel +``` + +--- + +## Historique machines + +| Machine | OS | `brain/` | Actif | +|---------|----|----------|-------| +| *(à remplir)* | | | | diff --git a/README.md b/README.md new file mode 100644 index 0000000..b71d5f6 --- /dev/null +++ b/README.md @@ -0,0 +1,165 @@ +# brain-template + +> Système de mémoire versionnée pour Claude — template universel. +> Cloner ce repo pour démarrer un brain depuis zéro. + +--- + +## Ce que c'est + +Un brain est un **système de contexte persistant** pour les sessions Claude — git + agents calibrés + gestion de contexte. Chaque session repart d'un état connu, pas de zéro. + +``` +MVCC (git) + agents calibrés + gestion de contexte += IA qui ne répète pas les mêmes erreurs + et devient plus précise avec le temps +``` + +--- + +## Installation — 15 minutes + +### Prérequis + +- Git +- Claude Code (ou Claude avec accès aux fichiers) +- Un compte Gitea ou GitHub (pour les remotes) + +### Étape 1 — Cloner le template + +```bash +git clone git@:/brain-template.git ~/Dev/Docs +cd ~/Dev/Docs +``` + +### Étape 2 — Configurer CLAUDE.md + +```bash +cp profil/CLAUDE.md.example ~/.claude/CLAUDE.md +# Remplacer par ton chemin réel +sed -i 's||/home//Dev/Docs|g' ~/.claude/CLAUDE.md +``` + +### Étape 3 — Configurer PATHS.md + +Ouvrir `PATHS.md` et remplacer tous les placeholders : + +| Placeholder | Remplacer par | +|-------------|---------------| +| `` | Chemin absolu du brain (ex: `/home/alice/Dev/Docs`) | +| `` | URL de ton Gitea (ex: `git@git.example.com`) | +| `` | Ton username Gitea | +| `` | Dossier de tes projets (ex: `/home/alice/Dev/Github`) | +| `` | Ton home (ex: `/home/alice`) | + +### Étape 4 — Configurer la collaboration + +```bash +cp profil/collaboration.md.example profil/collaboration.md +# Éditer profil/collaboration.md — personnaliser langue, ton, règles spécifiques +``` + +### Étape 5 — Créer les satellites (optionnel mais recommandé) + +```bash +# Créer sur Gitea : brain-profil, brain-todo, toolkit, brain-agent-review, progression-coach +# Puis : +git clone :/toolkit.git ~/Dev/Docs/toolkit +git clone :/brain-profil.git ~/Dev/Docs/profil +git clone :/brain-todo.git ~/Dev/Docs/todo +git clone :/brain-agent-review.git ~/Dev/Docs/reviews +git clone :/progression-coach.git ~/Dev/Docs/progression +``` + +### Étape 6 — Vérification cold boot + +Ouvrir une session Claude et vérifier : +``` +Bonjour — démarre le brain (helloWorld) +``` + +Signal de succès : contexte posé en < 3 échanges sans redemander qui tu es. + +--- + +## Structure + +``` +brain/ +├── README.md ← ce fichier +├── PATHS.md ← chemins machine (à personnaliser) +├── BRAIN-INDEX.md ← registre BSI (locking sessions parallèles) +├── agents/ +│ ├── _template.md ← template pour créer un agent +│ ├── AGENTS.md ← index complet des agents +│ ├── coach.md ← présence permanente — coaching progression +│ ├── scribe.md ← gardien du brain +│ ├── brainstorm.md ← exploration et décisions +│ ├── aside.md ← convention /btw +│ └── [30+ agents spécialisés] +└── profil/ + ├── CLAUDE.md.example ← bootstrap Claude (copier vers ~/.claude/) + ├── collaboration.md.example ← règles de travail (à personnaliser) + ├── memory-architecture.md ← TTL, Sectionnarisation, Stratification + ├── bsi-spec.md ← Brain Session Index — spec locking sessions + ├── context-hygiene.md ← chargement sélectif du contexte + ├── anti-hallucination.md ← règles globales anti-hallucination + ├── memory-integrity.md ← règles d'écriture dans le brain + ├── scribe-pattern.md ← pattern Scribe — agents écrivants + └── scribe-system.md ← cartographie des scribes +``` + +--- + +## Agents inclus + +| Catégorie | Agents | +|-----------|--------| +| **Présence permanente** | `coach` | +| **Brain maintenance** | `scribe`, `todo-scribe`, `toolkit-scribe`, `coach-scribe` | +| **Navigation** | `orchestrator`, `interprete`, `aside`, `helloWorld` | +| **Exploration** | `brainstorm`, `mentor`, `recruiter`, `agent-review` | +| **Code** | `code-review`, `security`, `testing`, `debug`, `refacto` | +| **DevOps** | `vps`, `ci-cd`, `monitoring`, `pm2`, `migration` | +| **Frontend** | `frontend-stack`, `optimizer-frontend`, `i18n`, `doc` | +| **Backend** | `optimizer-backend`, `optimizer-db` | +| **Infrastructure mail** | `mail` | +| **Capital / CV** | `capital-scribe`, `git-analyst` | +| **Configuration** | `config-scribe`, `brain-compose` | + +--- + +## Architecture — pourquoi ça marche + +**3 couches combinées :** + +1. **Git = MVCC gratuit** — toute décision versionnée, traçable, réversible +2. **Agents calibrés** — chaque agent a un scope déclaré, des sources conditionnelles, un cycle de vie +3. **Brain = couche de coordination** — chargement sélectif, mémoire sectionnarisée, procédures de reprise + +Voir `profil/memory-architecture.md` pour les 3 piliers (TTL, Sectionnarisation, Stratification). + +--- + +## Personnalisation + +Après installation, créer à la racine : + +``` +focus.md ← état de tes projets actifs +projets/ ← une fiche par projet (template dans profil/memory-architecture.md) +infrastructure/ ← config VPS, Docker, etc. +``` + +--- + +## Brain Session Index (BSI) + +Le `BRAIN-INDEX.md` permet de travailler sur plusieurs machines en parallèle sans collision. +Le scribe gère les claims — voir `profil/bsi-spec.md`. + +--- + +## Licence + +MIT — utilise, forke, adapte. diff --git a/agents/AGENTS.md b/agents/AGENTS.md new file mode 100644 index 0000000..06b6bdc --- /dev/null +++ b/agents/AGENTS.md @@ -0,0 +1,91 @@ +# Agents spécialisés — Tetardtek + +> Index des agents disponibles. +> Charger un agent = lire son fichier en début de session pour injecter son contexte. +> Stratification Chaud/Froid — voir `brain/profil/memory-architecture.md` Pillier 3. + +--- + +## 🔴 Agents chauds — auto-détectés sur trigger domaine + +> Chargés automatiquement quand le domaine est détecté. Jamais au boot. + +| Agent | Domaine | Statut | +|-------|---------|--------| +| `coach` | Progression — tutorat, suivi, coaching code + agents | 🔄 permanent | +| `vps` | Infra, Apache, Docker, SSL | 🔄 | +| `mail` | Stalwart, DNS, protocoles | 🔄 | +| `code-review` | Qualité, sécurité, dette technique | ✅ 2026-03-12 | +| `security` | Auth, tokens, OWASP | ✅ 2026-03-12 | +| `testing` | Jest, Vitest, DDD, coverage | ✅ 2026-03-12 | +| `debug` | Débogage local + prod | ✅ 2026-03-12 | +| `refacto` | Refactorisation — architecture + code | ✅ 2026-03-12 | +| `monitoring` | Observabilité — Kuma, logs VPS | ✅ 2026-03-12 | +| `ci-cd` | Pipelines GitHub Actions + Gitea CI | ✅ 2026-03-12 | +| `optimizer-backend` | Perf Node.js | ✅ 2026-03-12 | +| `optimizer-db` | Perf MySQL — N+1, index | ✅ 2026-03-12 | +| `optimizer-frontend` | Perf React — bundle, re-renders | ✅ 2026-03-12 | +| `pm2` | Process manager Node.js prod | 🧪 forgé 2026-03-13 | +| `migration` | TypeORM migrations — schéma, deploy safe | 🧪 forgé 2026-03-13 | +| `frontend-stack` | Architecture frontend — stack, libs UI, patterns pro | 🧪 forgé 2026-03-13 | +| `i18n` | Internationalisation — audit traductions, clés manquantes | 🧪 forgé 2026-03-13 | +| `doc` | Documentation — README, API Swagger, cohérence doc ↔ code | 🧪 forgé 2026-03-13 | + +--- + +## 🔵 Agents stables — invocation manuelle uniquement + +> Ne se chargent pas automatiquement. Invoqués explicitement par l'utilisateur ou sur signal d'un agent chaud. + +| Agent | Domaine | Statut | +|-------|---------|--------| +| `orchestrator` | Coordination — diagnostic et délégation multi-agents | ✅ 2026-03-12 | +| `scribe` | Maintenance du brain | ✅ 2026-03-12 | +| `mentor` | Pédagogie — explication, garde-fou | ✅ 2026-03-12 | +| `recruiter` | Meta-agent — conception d'agents | 🔄 | +| `agent-review` | Audit du système d'agents — gaps, patches, vue système | ✅ 2026-03-13 | +| `interprete` | Clarification d'intention — demandes ambiguës, scope drift | 🧪 forgé 2026-03-13 | +| `brainstorm` | Exploration et structuration de décisions — avocat du diable | 🧪 forgé 2026-03-13 | +| `aside` | Parenthèse de session — répond au pattern /btw, 2-3 lignes, retourne à session | 🧪 forgé 2026-03-14 | +| `toolkit-scribe` | Persistance patterns — gardien du toolkit/ | 🧪 forgé 2026-03-13 | +| `coach-scribe` | Persistance progression — journal/skills/milestones | 🧪 forgé 2026-03-13 | +| `todo-scribe` | Persistance intentions — gardien de brain/todo/ | 🧪 forgé 2026-03-13 | +| `helloWorld` | Bootstrap intelligent — briefing + chargement sélectif | 🧪 forgé 2026-03-13 | +| `git-analyst` | Historique git sémantique — conventions, synthèse commits | 🧪 forgé 2026-03-13 | +| `capital-scribe` | Capital CV — milestones → formulations recruteur | 🧪 forgé 2026-03-13 | +| `config-scribe` | Configuration brain — wizard first run, hydration Sources | 🧪 forgé 2026-03-13 | +| `brain-compose` | Multi-instances brain — symlinks kernel, registre machine | 🧪 forgé 2026-03-13 | + +--- + +## Template + +Créer un nouvel agent : copier `_template.md`, remplir, ajouter dans la bonne section (🔴 ou 🔵). + +--- + +## Workflows multi-agents connus + +| Workflow | Agents | Description | +|----------|--------|-------------| +| Nouveau service VPS | `vps` | Deploy Docker + Apache + SSL | +| Audit infra + code | `vps` + `code-review` | Vérification complète avant mise en prod | +| Déploiement mail | `vps` + `mail` | Setup Stalwart depuis zéro | +| Audit perf full-stack | `optimizer-backend` + `optimizer-db` + `optimizer-frontend` | Riri Fifi Loulou | +| Audit perf backend | `optimizer-backend` + `optimizer-db` | API + DB — sans toucher au frontend | +| Validation avant prod | `code-review` + `ci-cd` | Review code + pipeline avant déploiement | +| Nouveau projet complet | `vps` + `ci-cd` | Déploiement serveur + pipeline CI/CD | +| Problème non identifié | `orchestrator` → agents détectés | Diagnostic + délégation automatique | +| Audit système d'agents | `agent-review` → `recruiter` | Review + détection gaps → forge si besoin | +| Exploration / décision archi | `brainstorm` → `recruiter` ou agent métier | Explorer + challenger → construire | +| Question hors-scope en session | `aside` | /btw → 2-3 lignes → retour session | +| Fin de session complète | `scribe` + `toolkit-scribe` + `coach-scribe` + `todo-scribe` | Brain + toolkit + progression + intentions | +| Feature livrée en prod | `git-analyst` + `capital-scribe` | Commits synthétisés + capital CV mis à jour | +| Projet multi-langue | `i18n` + `frontend-stack` | Audit traductions + intégration lib | +| Release / PR importante | `doc` + `code-review` | Doc à jour + code validé | +| Audit complet avant prod | `security` + `code-review` + `testing` | Validation complète feature sensible | +| Bug prod complexe | `debug` + `vps` | Isolation + infra | +| Refacto sécurisée | `refacto` + `testing` + `code-review` | Tests avant, refacto, review après | +| Incident prod | `monitoring` + `vps` + `debug` | Alerte → diagnostic infra → debug applicatif | +| Nouveau déploiement | `ci-cd` + `monitoring` | Pipeline + sondes de surveillance | +| Dream team perf | `orchestrator` → `optimizer-*` | Audit perf full-stack via orchestrateur | diff --git a/agents/PHILOSOPHY.md b/agents/PHILOSOPHY.md new file mode 100644 index 0000000..cad5608 --- /dev/null +++ b/agents/PHILOSOPHY.md @@ -0,0 +1,66 @@ +# Philosophie du système d'agents + +> Écrit : 2026-03-12 — à relire avant de créer ou modifier un agent + +--- + +## Pourquoi ce système existe + +Éviter de réexpliquer le même contexte à chaque session. +Un agent chargé arrive avec sa connaissance métier complète — zéro ré-onboarding. + +--- + +## Principes fondateurs + +**1. Ancré dans la réalité** +Chaque agent lit des fichiers brain/toolkit qui existent vraiment. +Aucun pattern inventé — si ce n'est pas dans les sources, ce n'est pas dans l'agent. + +**2. Un agent = une responsabilité** +Trois domaines → trois agents en composition, pas un agent monstre. +La complexité minimale pour le besoin réel actuel — pas pour les besoins hypothétiques. + +**3. Coordinateur pur vs agent métier** +L'orchestrator ne produit rien. Le mentor n'exécute rien. Le scribe ne code pas. +Chaque agent connaît sa limite et la respecte. + +**4. Anti-hallucination non négociable** +Fait non vérifié → "Information manquante". +Incertitude → niveau de confiance explicite. +Jamais inventer : commandes, ports, chemins, métriques. + +**5. CLAUDE.md = bootstrap, brain = connaissance** +CLAUDE.md pointe. Le brain contient. +Si tu clones le brain sur une nouvelle machine, l'environnement se reconstruit. + +--- + +## Décisions de design importantes + +| Décision | Pourquoi | +|----------|----------| +| Optimizers en trio (backend/db/frontend) | Un domaine = un spécialiste. Composables ensemble ("Riri Fifi Loulou") | +| Testing unifié (Jest + Vitest) | Même stratégie, outils proches — split = overhead sans valeur | +| Debug unifié | Méthodologie universelle > spécialisation domaine | +| Orchestrator coordinateur pur | S'il agit, il sort de son rôle et devient imprévisible | +| Scribe en fin de session | Le brain qui dérive = connaissance perdue | +| Mentor 3 modes | Pédagogie adaptative > agent spécialisé par type de question | + +--- + +## Ce que ce système n'est pas + +- Un remplacement au travail réel — les agents guident, tu décides et tu fais +- Une garantie de qualité — un agent non testé est un agent théorique +- Figé — chaque review en conditions réelles l'améliore + +--- + +## Boucle d'amélioration + +``` +Forger → Tester → Capturer (reviews/) → Améliorer (recruiter) → Re-tester +``` + +Le système s'améliore par l'usage. Pas par la théorie. diff --git a/agents/PLAN-REVIEW-AGENTS.md b/agents/PLAN-REVIEW-AGENTS.md new file mode 100644 index 0000000..19a1813 --- /dev/null +++ b/agents/PLAN-REVIEW-AGENTS.md @@ -0,0 +1,298 @@ +# Plan de review des agents — conditions réelles + +> ⚠️ Ce fichier concerne la qualité des AGENTS, pas les tests du code applicatif. +> Tests code → Jest/Vitest dans chaque projet. + +--- + +## La boucle en une phrase + +> Lancer → Capturer → Évaluer → Patcher → Documenter. + +Chaque review laisse l'agent **meilleur qu'avant** et le brain **plus riche qu'à son départ**. + +--- + +## Phrases d'invocation — copier-coller direct + +### 1. Lancer la review (session projet) + +``` +Charge l'agent . + +``` + +Exemple réel : +``` +Charge l'agent monitoring. +Audite la couverture de surveillance actuelle sur Uptime Kuma. +Identifie ce qui manque et propose les sondes à créer. +``` + +### 2. Patcher avec le recruiter (après évaluation) + +``` +Charge l'agent recruiter. +Lis brain/agents/reviews//-v1.md. +Améliore l'agent en intégrant les gaps identifiés. +``` + +### 3. Fermer la boucle avec le scribe (fin de session) + +``` +Charge l'agent scribe. +On vient de faire la review de — mets le brain à jour. +``` + +### Phrase complète — session de review dédiée + +``` +On review l'agent . +Projet de test : . +Cas soumis : . +Prépare le template, lance-le, évalue, patche avec recruiter, scribe en fin. +``` + +--- + +## Philosophie — progression hexagonale + +Comme en architecture hexagonale : chaque couche doit être **solide avant d'en ajouter une autre**. + +``` +Review 1 (security) → identifie les patterns manquants +Review 2 (code-review) → confirme le pattern → correction systématique +Review 3 (testing) → le pattern est acquis, on cherche d'autres gaps +... +Review N (scribe) → le scribe lui-même est reviewé avec les mêmes critères +``` + +**Ce que chaque review apporte :** +- Un agent testé en conditions réelles (pas en théorie) +- Un gap documenté = une règle qui ne sera plus oubliée +- Un pattern transversal détecté = tous les agents suivants en bénéficient +- Un changelog qui raconte l'histoire des améliorations + +**Signal de progression réelle :** quand les gaps trouvés en v1 disparaissent en v2. +Pas parce qu'on les a ignorés — parce que l'agent a vraiment appris. + +--- + +## Procédure complète — step by step + +### Étape 1 — Préparer le fichier de capture + +```bash +cp brain/agents/reviews/_template.md brain/agents/reviews//-v1.md +``` + +Remplir l'en-tête : agent reviewé, date, projet, cas soumis. + +### Étape 2 — Lancer l'agent dans une session Claude Code + +Ouvrir une session dans le projet concerné, charger l'agent, lui soumettre le cas. +→ Voir "Phrases d'invocation" + "Use cases concrets" ci-dessous. + +### Étape 3 — Capturer l'output + +Copier-coller l'intégralité de la réponse de l'agent dans `reviews//-v1.md`. +Section "Output brut de l'agent" du template. + +### Étape 4 — Évaluer + +Remplir les sections ✅ ❌ ⚠️ 📐 du template. +Identifier les gaps concrets : qu'est-ce qui manquait ? qu'a-t-il inventé ? a-t-il débordé ? + +### Étape 5 — Améliorer l'agent (si gaps) + +``` +Charge l'agent recruiter. +Lis brain/agents/reviews//-v1.md. +Améliore l'agent en intégrant les gaps identifiés. +``` + +### Étape 6 — Scribe + re-tester + +``` +Charge l'agent scribe. +On vient de faire la review de — mets le brain à jour. +``` + +Répéter étapes 2-4 → sauvegarder dans `-v2.md`. +Comparer v1 / v2 — noter dans le changelog de l'agent. + +--- + +## Use cases concrets — prompts exacts + +### `orchestrator` — "Je ne sais pas par où commencer" + +``` +Charge l'agent orchestrator. +Je veux préparer Super-OAuth pour un déploiement en production. +Je ne sais pas par où commencer ni quels agents charger. +Dis-moi ce qui doit être fait et dans quel ordre. +``` + +**Ce qu'on vérifie :** identifie-t-il les bons domaines ? Propose-t-il un ordre logique ? +Reste-t-il coordinateur (ne code pas, ne déploie pas) ? +**Statut :** ✅ Testé 2026-03-12 — RÉUSSI + +--- + +### `security` — Audit avant prod + +``` +Charge l'agent security. +Audite la branche feature/security-hardening de Super-OAuth. +Focus sur : JWT blacklist Redis, CSRF, CSP nonce, device fingerprinting. +Dis-moi si l'implémentation est correcte et ce qui manque. +``` + +**Ce qu'on vérifie :** connaît-il les mécanismes déjà en place (ne les re-propose pas) ? +Trouve-t-il de vrais gaps ? Respecte-t-il les priorités d'audit dans l'ordre ? + +--- + +### `code-review` — Review d'un fichier + +``` +Charge l'agent code-review. +Review ce fichier : [coller le contenu ou donner le chemin] +Projet : Super-OAuth, architecture DDD. +``` + +**Ce qu'on vérifie :** format adapté (inline si court, rapport si long) ? +Explique-t-il le *pourquoi* de chaque finding ? Respecte-t-il le périmètre ? + +--- + +### `testing` — Stratégie coverage + +``` +Charge l'agent testing. +Analyse la couverture actuelle de Super-OAuth. +Identifie les zones critiques non couvertes (priorité : couches DDD auth flows). +Propose une stratégie pour atteindre une couverture suffisante avant prod. +``` + +**Ce qu'on vérifie :** connaît-il la structure DDD par couche ? +Distingue-t-il les tests unitaires des tests d'intégration ? Propose-t-il TDD ou rétroactif selon le contexte ? + +--- + +### `debug` — Diagnostic d'une erreur + +``` +Charge l'agent debug. +J'ai cette erreur : [coller la stack trace ou décrire le symptôme] +Projet : Super-OAuth, stack Express + TypeORM + Redis. +Aide-moi à isoler la cause. +``` + +**Ce qu'on vérifie :** suit-il la méthode en 5 étapes (reproduire → isoler → hypothèses → vérifier → corriger) ? +Formule-t-il des hypothèses ordonnées par probabilité ? + +--- + +### `ci-cd` — Créer un pipeline + +``` +Charge l'agent ci-cd. +Je veux créer le pipeline de déploiement prod pour Super-OAuth. +CI actuel : tests seulement (ci.yml). À ajouter : build + SSH deploy + migration TypeORM. +Stack : Node.js 22, TypeScript, Docker. +``` + +**Ce qu'on vérifie :** adapte-t-il au type de projet (Node.js + Docker) ? +Connaît-il les secrets VPS ? Propose-t-il d'ajouter le template dans toolkit/ ? + +--- + +### `monitoring` — Audit couverture Kuma + +``` +Charge l'agent monitoring. +Audite la couverture de surveillance actuelle sur Uptime Kuma. +Identifie ce qui manque et propose les sondes à créer. +``` + +**Ce qu'on vérifie :** connaît-il l'infra réelle (containers, sous-domaines, monitoring.md) ? +Détecte-t-il les gaps entre ce qui est surveillé et ce qui devrait l'être ? + +--- + +### `scribe` — Bilan de session + +``` +Charge l'agent scribe. +Fais le bilan de cette session et mets le brain à jour. +``` + +**Ce qu'on vérifie :** identifie-t-il les bons fichiers à mettre à jour ? +Propose-t-il validation avant les changements importants ? + +--- + +### `mentor` — Interpréter un plan + +``` +Charge l'agent mentor. +L'orchestrator vient de proposer ce plan : [coller l'output]. +Explique-moi pourquoi security passe avant code-review. +Vérifie que j'ai bien compris la logique avant qu'on continue. +``` + +**Ce qu'on vérifie :** explique-t-il le *pourquoi* (pas juste le *quoi*) ? +Pose-t-il une question de vérification sans surcharger ? + +--- + +### `refacto` — Audit dette technique + +``` +Charge l'agent refacto. +Audite OriginsDigital — identifie la dette technique principale. +Propose un plan de refacto en étapes atomiques. +Règle absolue : aucune logique métier ne doit disparaître. +``` + +**Ce qu'on vérifie :** produit-il un plan en étapes, du moins risqué au plus risqué ? +Demande-t-il validation avant de passer à l'exécution ? + +--- + +## Ordre recommandé + +| # | Agent | Projet | Statut | +|---|-------|--------|--------| +| 1 | `orchestrator` | Super-OAuth | ✅ 2026-03-12 | +| 2 | `security` | Super-OAuth | ✅ 2026-03-12 | +| 3 | `code-review` | Super-OAuth | ✅ 2026-03-12 | +| 4 | `testing` | Super-OAuth | ✅ 2026-03-12 | +| 5 | `debug` | Super-OAuth | ✅ 2026-03-12 | +| 6 | `ci-cd` | Super-OAuth | ✅ 2026-03-12 | +| 7 | `monitoring` | Infra | ✅ 2026-03-12 | +| 8 | `scribe` | Brain | ✅ 2026-03-12 | +| 9 | `mentor` | Super-OAuth | ✅ 2026-03-12 | +| 10 | `optimizer-db` | Super-OAuth | ✅ 2026-03-12 | +| 11 | `refacto` | Super-OAuth | ✅ 2026-03-12 | +| 12 | `optimizer-backend` | Super-OAuth | ✅ 2026-03-12 | +| 13 | `optimizer-frontend` | Portfolio | ✅ 2026-03-12 | + +--- + +## Critères de validation d'un agent + +- ✅ Output utile et ancré dans la réalité (pas d'invention) +- ✅ Anti-hallucination : dit "Information manquante" quand nécessaire +- ✅ Périmètre respecté : ne déborde pas, délègue ce qui ne le concerne pas +- ✅ Format adapté au cas soumis + +--- + +## Notation changelog après review + +``` +| 2026-XX-XX | Review réelle — : ✅ / ❌ / 🔧 | +``` diff --git a/agents/_brief-brain-compose.md b/agents/_brief-brain-compose.md new file mode 100644 index 0000000..860ab46 --- /dev/null +++ b/agents/_brief-brain-compose.md @@ -0,0 +1,381 @@ +# Brief — brain-compose + +> Document de préparation à la forge. À lire par `recruiter` avant la session. +> Décisions actées en session 2026-03-13 — ne pas re-débattre. + +--- + +## L'intention + +Le brain est un OS. Jusqu'ici il tournait en mono-instance — une machine, une config, un +contexte. C'est suffisant pour commencer. Ce n'est pas suffisant pour grandir. + +`brain-compose` est la couche qui rend le brain **modulaire** : plusieurs instances du même +kernel, chacune avec sa propre config et son propre état, sur une ou plusieurs machines. + +Ce n'est pas une feature. C'est une architecture. + +--- + +## Le problème qu'il résout + +``` +Aujourd'hui Avec brain-compose +──────────────────────────────── ────────────────────────────────── +1 machine = 1 brain 1 machine = N brains indépendants +1 contexte à la fois Sessions parallèles possibles +Infra hardcodée dans les Sources Config par instance, kernel propre +Fork = tout reconfigurer à la main Fork = kernel + config-scribe → opérationnel +Pas de portabilité entre machines brain-compose.local.yml = registre machine +``` + +--- + +## L'architecture — trois couches, une règle + +``` +KERNEL agents/, profil/, templates/ + Universel. Partagé entre toutes les instances. + Mis à jour une fois → profite à tout le monde. + Versionné dans le repo principal. + +INSTANCE infrastructure/*.md, PATHS.md, projets/, todo/, focus.md + Personnel. Propre à chaque instance. + Écrit par config-scribe et les scribes métier. + Jamais dans le kernel. + +PERSONNEL progression/, capital.md + Intime. Jamais partagé, jamais exporté. + Appartient à une personne, pas à un brain. +``` + +**La règle :** le kernel ne connaît pas les instances. Les instances connaissent le kernel. +Dépendance unidirectionnelle. C'est ce qui permet de mettre à jour le kernel sans casser +quoi que ce soit en dessous. + +--- + +## Kernel partagé — comment concrètement + +**Décision actée :** le kernel est partagé, pas dupliqué. + +``` +~/Dev/ +├── Docs/ ← kernel + instance perso (brain principal) +│ ├── agents/ ← kernel +│ ├── profil/ ← kernel +│ ├── infrastructure/ ← instance perso (écrit par config-scribe) +│ ├── projets/ ← instance perso +│ └── PATHS.md ← instance perso +│ +├── client-xyz/ ← instance client +│ ├── agents/ → symlink vers ~/Dev/Docs/agents/ (kernel partagé) +│ ├── profil/ → symlink vers ~/Dev/Docs/profil/ +│ ├── infrastructure/ ← config propre (écrit par config-scribe) +│ ├── projets/ ← état propre +│ └── PATHS.md ← chemins propres +│ +└── brain-compose.local.yml ← registre de toutes les instances sur cette machine +``` + +**Pourquoi symlinks plutôt que clones ?** +Un `git pull` sur le kernel = toutes les instances à jour instantanément. +Pas de sync manuel. Pas de divergence silencieuse. + +**Limite à documenter :** sur Windows ou certains systèmes de fichiers, les symlinks ont +des contraintes. À vérifier lors de la forge. + +--- + +## Les deux fichiers clés + +### `brain-compose.yml` — la spec (versionnée dans le kernel) + +Ce fichier définit ce qu'une instance brain PEUT être. C'est le schema, pas l'état. + +```yaml +# brain-compose.yml +version: "1.0" + +# Agents disponibles dans ce kernel +agents: + core: + - scribe + - coach + - recruiter + - config-scribe + - helloWorld + metier: + - vps + - mail + - ci-cd + - debug + - security + - testing + - refacto + - monitoring + - optimizer-backend + - optimizer-db + - optimizer-frontend + - pm2 + - migration + - frontend-stack + - i18n + - doc + scribes: + - todo-scribe + - toolkit-scribe + - coach-scribe + - capital-scribe + - git-analyst + meta: + - orchestrator + - agent-review + - mentor + - interprete + - brainstorm + +# Feature flags — quels agents sont actifs selon le tier +features: + free: + - core + - debug + pro: + - core + - metier + - scribes + full: + - core + - metier + - scribes + - meta +``` + +> Ce fichier est exportable. Il fait partie du `claude-brain-template`. +> Il définit les possibilités — `brain-compose.local.yml` définit l'état réel. + +--- + +### `brain-compose.local.yml` — le registre machine (non versionné, gitignored) + +Ce fichier enregistre les instances actives sur cette machine. + +```yaml +# brain-compose.local.yml +# Ne pas versionner — contient des chemins et configs locaux + +machine: + +instances: + perso: + path: ~/Dev/Docs/ + kernel: ~/Dev/Docs/ + feature_set: full + config_status: hydrated # ou: empty, partial + last_setup: 2026-03-13 + + client-xyz: + path: ~/Dev/client-xyz/ + kernel: ~/Dev/Docs/ # pointe vers le même kernel + feature_set: pro + config_status: partial + last_setup: ~ + +active: perso +``` + +--- + +## Les opérations (via l'agent brain-compose) + +``` +brain-compose new Crée une nouvelle instance : + → crée le dossier + → symlink vers le kernel + → invoque config-scribe pour hydrater la config + → ajoute l'entrée dans brain-compose.local.yml + +brain-compose list Liste toutes les instances avec leur statut + +brain-compose status [] État d'une instance : + → config complète ou placeholders résiduels ? + → kernel à jour ? + +brain-compose sync kernel Met à jour le kernel (git pull) + → toutes les instances profitent instantanément + +brain-compose diff Compare les configs de deux instances + → utile avant de migrer un projet d'une instance à l'autre +``` + +> **Convention plutôt que CLI** : ces opérations sont réalisées par l'agent brain-compose +> via Claude Code. Pas d'outil externe à installer. Claude Code est le runtime. + +--- + +## Relation avec config-scribe + +`brain-compose` et `config-scribe` sont des partenaires, pas des concurrents. + +``` +brain-compose new + │ + ├── crée la structure (dossier, symlinks, brain-compose.local.yml) + │ + └── invoque config-scribe + │ + └── wizard par catégories → hydrate infrastructure/*.md + PATHS.md + → confirme : "Instance opérationnelle" +``` + +config-scribe ne sait pas qu'il est dans une instance. Il fait son travail. +brain-compose orchestre. config-scribe exécute. + +--- + +## Feature gating — la vision produit + +``` +claude-brain-template (open-source) + → brain-compose.yml livré avec feature_set: free + → agents core + debug disponibles + → les autres agents existent dans le kernel mais ne sont pas invoquables + +Fork personnel + → feature_set: full + → tout est disponible, aucune restriction + +Brain-as-a-Service + → feature_set par compte utilisateur + → tier free → pro → full selon l'abonnement + → brain-compose.yml est le contrat de service +``` + +> Les agents "bloqués" ne sont pas absents — ils sont dans le kernel. +> C'est `brain-compose.yml` qui contrôle l'accès, pas la présence des fichiers. +> Même kernel pour tout le monde. Personnalité différente par les feature flags. + +--- + +## Ce qui reste à décider en session forge + +1. **Symlinks vs autre mécanisme** — valider que les symlinks tiennent sur toutes les + plateformes cibles. Alternative : git submodules, git worktrees. + +2. **brain-compose.yml dans CLAUDE.md** — comment helloWorld lit les feature flags pour + savoir quels agents proposer au démarrage. + +3. **Scope exact de l'agent brain-compose** — agent Claude pur, ou besoin de scripts bash + pour créer les symlinks / dossiers ? + +4. **Que se passe-t-il si le kernel évolue et casse une instance ?** — stratégie de + migration (semver sur brain-compose.yml ?). + +--- + +## Plan de la session forge + +``` +1. Recruiter lit ce brief +2. Questions QCM sur les 4 points ouverts ci-dessus +3. Forge brain-compose agent (depuis _template.md enrichi) +4. Mise à jour brain-compose.yml schema si nécessaire +5. Mise à jour config-scribe — ajouter la génération brain-compose.local.yml +6. Scribe → AGENTS.md + CLAUDE.md + todo brain-compose Phase 2 ✅ +``` + +--- + +## Ce qu'on ne fera PAS dans cette session + +- Écrire du code bash pour les symlinks → documenter le pattern, pas l'implémenter +- Décider du modèle économique Brain-as-a-Service → c'est une session séparée +- Toucher à helloWorld → découplé, session dédiée + +--- + +## Vision produit — brain CLI (capturée 2026-03-13, à brainstormer) + +> Ne pas implémenter dans cette session. Capturer l'intention complète. + +```bash +brain new # crée une instance locale, lance config-scribe + # opérationnel SANS connexion — kernel local + +brain sync -p # prompt password → auth serveur Brain-as-a-Service + # valide l'abonnement → renvoie le feature_set + # sync contexte distant (progression/, positions, config) + # brain-compose.local.yml → tier mis à jour + # "Mode actif : pro. 12 agents débloqués." +``` + +**Ce que ça implique :** + +- `brain new` = usage local pur, pas de compte requis. Le kernel est local. +- `brain sync` = pont entre l'instance locale et le service distant. +- Le serveur gère : auth, abonnements, feature_set par compte, sync contexte. +- L'instance locale tourne sans connexion — sync = optionnel, pas obligatoire. + +--- + +## Modèle tokens — décision actée (BYOK) + +**Le service ne gère pas les tokens Claude. TOTO apporte son propre accès Claude.** + +``` +TOTO → abonnement Claude.ai Pro/Max ou clé API Anthropic (son affaire) +TOTO → abonnement Brain-as-a-Service (feature_set + sync) + +Tokens Claude → 100% sur le compte Claude de TOTO +Brain-as-a-Service → vend les features et le sync, pas la puissance de calcul +``` + +**Ce que Brain-as-a-Service vend :** + +``` +✅ Accès aux features selon le tier (feature_set free / pro / full) +✅ Sync du contexte entre machines (progression/, positions, config) +✅ Kernel maintenu et mis à jour +✅ Structure brain prête à l'emploi + +❌ Tokens Claude — jamais +❌ Transit de données utilisateur via la clé du service — jamais +``` + +**Parcours TOTO :** + +``` +1. TOTO a Claude.ai Pro (ou clé API Anthropic) +2. TOTO crée un compte Brain-as-a-Service +3. brain sync -p toto → auth Super-OAuth → valide abonnement → renvoie feature_set +4. brain-compose.local.yml → tier mis à jour +5. Tokens Claude → toujours sur le compte de TOTO. Le service n'y touche pas. +``` + +**Pourquoi BYOK est la seule direction raisonnable :** + +``` +Risque financier → zéro. Ce n'est pas le service qui paie les tokens de TOTO. +Risque légal → zéro. Pas de transit de données via une clé master. +Risque technique → zéro. Pas de quota à gérer, pas de billing tokens à implémenter. +Marge → 100% prévisible. Abonnement = accès features. Point. +``` + +**CLI vs convention — réponse finale :** +``` +Usage perso (power user) → convention pure + agent Claude. Pas de CLI. +Produit distribué → CLI `brain` obligatoire. brain new + brain sync. +Les deux coexistent. +``` + +**L'ironie magnifique :** +`brain sync` tourne sur Super-OAuth pour l'auth. +Le brain s'authentifie avec l'outil que tu as construit. +JWT + Redis + OAuth2 — déjà en prod. La boucle est bouclée. + +**Prérequis pour cette vision :** +- brain-compose agent forgé et stable ✅ (cette session) +- config-scribe validé en conditions réelles +- Super-OAuth exposé comme fournisseur d'auth externe +- Serveur Brain-as-a-Service (API sync + gestion abonnements) +- CLI `brain` packagée (npm global ou binaire) diff --git a/agents/_template.md b/agents/_template.md new file mode 100644 index 0000000..6d0646a --- /dev/null +++ b/agents/_template.md @@ -0,0 +1,166 @@ +# Agent : + +> Dernière validation : +> Domaine : + +--- + +## Rôle + + + — reçoit les signaux de , structure et persiste."> + +--- + +## Activation + +``` +Charge l'agent — lis brain/agents/.md et applique son contexte. +``` + +Ou en combinaison : + +``` +Charge les agents et pour cette session. +``` + +--- + +## Sources à charger au démarrage + +| Fichier | Pourquoi | +|---------|----------| +| `brain/profil/collaboration.md` | Règles de travail globales | + +> **Règle invocation-only (scribes et agents ponctuels) :** zéro source au démarrage — tout +> se décide sur le signal reçu. Supprimer cette section et tout mettre en conditionnel. +> +> **Règle environnementalisation :** jamais de valeur personnelle hardcodée (IP, domaine, +> chemin, projet spécifique). Utiliser des placeholders `` et pointer vers les Sources. +> Les données personnelles transitent UNIQUEMENT via les Sources conditionnelles. + +--- + +## Sources conditionnelles + +Fichiers chargés uniquement sur trigger — pas au démarrage. + +| Trigger | Fichier | Pourquoi | +|---------|---------|----------| +| Signal reçu (toujours) | `brain/infrastructure/.md` | Contexte infra du domaine | +| Projet identifié | `brain/projets/.md` | Stack, état, contraintes projet | +| Si disponible | `toolkit//` | Patterns validés en prod — chemin réel dans PATHS.md | + +> Principe : charger le minimum au démarrage, enrichir au moment exact où c'est utile. +> Voir `brain/profil/context-hygiene.md` pour la règle complète. +> +> **Pour les scribes :** remplacer par `| Rapport reçu (toujours) | | Lire avant d'écrire |` +> et référencer `brain/profil/scribe-system.md` dans les Sources au démarrage. + +--- + +## Périmètre + +**Fait :** +- +- + +**Ne fait pas :** +- +- +- Proposer la prochaine action après son travail → fermer avec un résumé/bilan, laisser l'utilisateur décider + +--- + +## Toolkit + +> **Section obligatoire pour les agents métier. Supprimer pour les scribes.** + +- Début de session : charger `toolkit//` si disponible — proposer les patterns validés en prod +- En session : pattern validé et réutilisable → signaler `toolkit-scribe` en fin de session +- Jamais proposer un pattern non testé en prod dans cette session + +--- + +## Écrit où + +> **Section obligatoire pour les scribes. Supprimer pour les agents métier.** +> Voir `brain/profil/scribe-system.md` pour l'idéologie fondatrice. + +| Repo | Fichiers cibles | Jamais ailleurs | +|------|----------------|-----------------| +| `/` | `` | | + +--- + +## Anti-hallucination + +> Règles globales (R1-R5) → `brain/profil/anti-hallucination.md` + +Règles domaine-spécifiques : + +- Si : "Information manquante — vérifier dans " +- Jamais inventer : +- Niveau de confiance explicite si incertain : `Niveau de confiance: faible/moyen/élevé` + +--- + +## Ton et approche + +-