Black Emperor - Orchestrateur Unifié

“Lift your skinny fists like antennas to heaven”

Références : _shared/context-protocol.md · _shared/update-protocol.md · _shared/agent-teams.md · _shared/cli-tools-protocol.md

Orchestrateur multi-mode qui lance des workflows complets selon le besoin.

Outils

CLI (prioritaire)

gh : gestion GitHub (PR, issues, releases)
vercel : déploiement et gestion Vercel
neonctl : gestion base de données Neon

MCP (fallback si CLI absent)

Figma MCP : extraction design tokens (pas de CLI complet disponible)
Notion MCP : opérations structurées (pas de CLI officiel)
Linear MCP : opérations GraphQL (pas de CLI officiel)

Vérification

Avant d’utiliser un outil externe, toujours :

command -v <tool> pour vérifier la présence
Si absent, vérifier /mcp pour un MCP configuré
Si ni l’un ni l’autre, informer l’utilisateur

Modes

Mode	Invocation	Workflow
audit	`audit-complet`	spec → [code+perf+a11y] → todo → report
legacy	`legacy-revival`	spec → audit → [simplify+perf] → fix → doc
release	`pre-release`	context → [audits] → fix → tests → GO/NO-GO
review	`review`	prompt → extraction → matrice complétude → Code Review natif → gaps → todo
ship	`blackemperor`	simplify → doc → sync → README → release

Phase 0 : Todo Check (Universelle — tous les modes)

Avant de lancer tout workflow, quel que soit le mode :

Vérifier l’existence :

test -f docs/todo.md && echo "todo:yes" || echo "todo:no"

Détecter le format (si todo.md existe) :

head -5 docs/todo.md | grep -q "kanban-plugin: board" && echo "format:kanban" || echo "format:legacy"

Actions selon mode et état :

Mode	Todo absent	Todo legacy	Todo kanban
audit	Sera créé par todo-generator en Phase 3	Convertir via kanban-converter avant Phase 3	Lire les colonnes pour contexte
legacy	Sera créé par todo-generator en Phase 5	Convertir via kanban-converter avant Phase 5	Lire les colonnes pour contexte
release	⚠️ Avertir : pas de todo à vérifier, continuer	⚠️ Avertir : format non standard	Lire colonnes Done + Blocked
review	Sera créé si score < 100%	Source possible (noter format legacy dans rapport)	Source principale + mise à jour post-review
ship	Sera mis à jour par todo-generator en Phase 2	Convertir via kanban-converter avant Phase 2	Lire + mettre à jour en Phase 2

Si format legacy ET mode nécessitant création/mise à jour (audit, legacy, ship) :

⚠️  docs/todo.md est au format legacy.
Pour garantir la compatibilité Obsidian Kanban, je vais le convertir d'abord.
Lancer kanban-converter ?
1. Oui (recommandé)
2. Non, continuer sans conversion

Mode: AUDIT (audit-complet)

Audit exhaustif d’un repository.

Workflow

Phase 1 (SEQ): spec-writer → docs/spec.md
Phase 2 (PARALLEL): code-auditor + perf-auditor + a11y-auditor
Phase 3 (SEQ): Consolidation → todo-generator
Phase 3.5 (SEQ): claude-md-optimizer → audit CLAUDE.md (score, optimisations)
Phase 4: Rapport docs/reports/audit-summary-YYYYMMDD.md

Output

Métrique	Score
Code	X/10
Performance	X/10
Accessibilité	X/10
Sécurité	X/10
CLAUDE.md	X/10

Mode: LEGACY (legacy-revival)

Remise à niveau d’un projet legacy.

⚠️ Sessions longues : Le mode legacy implique souvent des sessions longues (5-6 phases). Insérer un gandalf health check entre les phases 3 et 4 si le contexte dépasse 30%.

Workflow

Phase 0b (OPT): strange → reverse documentation complète (si demandé ou si aucune doc n’existe)
- Produit docs/rewrite/ : cahier des charges, doc technique, doc user, user stories, glossaire, architecture
- Recommandé si le projet n’a quasiment aucune documentation
Phase 1 (SEQ): spec-writer → archéologie du projet (peut exploiter docs/rewrite/ si Strange a tourné)
Phase 2 (SEQ): code-auditor → diagnostic legacy
Phase 3 (PARALLEL): /simplify (bundled natif) + perf-auditor 3b. Checkpoint contexte : Si Automemory gandalf disponible et context_zone != “green” → proposer /clear et reprendre
Phase 4 (SEQ): robocop → corrections
Phase 5 (SEQ): sync-local + todo-generator
Phase 6: Rapport avant/après

Questions Pré-Revival

Revival complète ou parties critiques ?
Reconstituer toute la documentation d’abord (Strange) ? Ou spec seulement (spec-writer) ?
Tests existants ? Créer tests d’abord ?
Breaking changes acceptés ?
Priorité : stabilité, performance, maintenabilité ?

Mode: RELEASE (pre-release)

Checklist complète avant release avec verdict GO/NO-GO.

Workflow

Phase 1 (SEQ): Détection contexte (si docs/spec.md existe, skip spec-writer)
Phase 2 (PARALLEL):
- code-auditor + perf-auditor + a11y-auditor (audits full codebase)
- /pr-review-toolkit:review-pr all parallel (review diff/PR — bugs, types, tests, erreurs silencieuses)
Phase 3 (SEQ): robocop si blockers → tests
Phase 4 (SEQ): Vérification docs (CHANGELOG, version)
Phase 5: Checklist interactive
Phase 6: Verdict GO/NO-GO

Distinction : les audits (Phase 2a) analysent le codebase entier ; /pr-review-toolkit:review-pr (Phase 2b) analyse le diff des changements récents. Les deux sont complémentaires.

Critères GO/NO-GO

Verdict	Conditions
✅ GO	Build pass, tests critiques pass, 0 blocker sécurité
⚠️ WARNINGS	Tests > 95%, perf légèrement hors target
❌ NO-GO	Build fail, tests critiques fail, blockers sécurité

Mode: REVIEW (review)

Revue de complétude du code par rapport à un prompt, une spec ou un cahier des charges.

“Le code est-il complet par rapport à ce qui a été demandé ?”

Sources acceptées

Source	Détection	Extraction
`docs/spec.md`	Présence du fichier	Sections features/requirements
GitHub issue	`#NNN` ou URL	Titre + body + acceptance criteria
Prompt utilisateur	Texte libre	Parsing des exigences
`docs/todo.md`	Présence du fichier	Tâches non cochées
PR description	`PR #NNN` ou URL	Description + checklist

Questions Pré-Review

Si aucune source n’est fournie explicitement :

Quelle est la référence pour cette review ?

1. **docs/spec.md** — Vérifier la complétude vs la spec du projet
2. **Issue GitHub** — Coller le numéro ou le lien
3. **Prompt / cahier des charges** — Coller ou décrire les exigences
4. **docs/todo.md** — Vérifier que toutes les tâches sont implémentées
5. **PR en cours** — Vérifier que le code de la branche couvre le scope

Workflow

Phase 1 (SEQ) : Extraction des exigences
- Lire la source (spec, issue, prompt)
- Découper en exigences atomiques numérotées (REQ-001, REQ-002, …)
- Classifier chaque exigence : fonctionnelle, technique, UX, test, doc
- Présenter la liste à l’utilisateur pour validation
Phase 2 (PARALLEL) : Analyse de complétude par exigence
- Pour chaque exigence, rechercher dans le code :
  - Implémentation directe (fonctions, composants, routes, etc.)
  - Tests associés
  - Documentation inline
- Classer chaque exigence :
  - ✅ Complète — Code présent, fonctionnel, testé
  - 🟡 Partielle — Code présent mais incomplet (edge cases, erreurs, tests manquants)
  - ❌ Absente — Aucune trace dans le code
  - ⚠️ Déviante — Implémentée différemment de ce qui est spécifié
Phase 2.5 (SEQ) : Code Review natif
- Lancer le Code Review natif sur le diff ou la branche en cours
- Le Code Review natif détecte des bugs, régressions et failles de sécurité au niveau PR/diff
- Intégrer les findings du Code Review dans la matrice de complétude (Phase 4)
- Distinction : Le Code Review natif vérifie la qualité du code existant ; la matrice de complétude vérifie la couverture des exigences
Phase 3 (SEQ) : Analyse des écarts
- Pour chaque exigence partielle/absente/déviante :
  - Identifier précisément ce qui manque
  - Évaluer l’effort restant (T-shirt sizing : XS, S, M, L, XL)
  - Identifier les fichiers à créer/modifier
- Détecter le code orphelin (implémenté mais non demandé)
- Intégrer les bugs détectés par Code Review comme écarts supplémentaires
Phase 4 (SEQ) : Matrice de complétude + rapport
- Générer docs/reviews/review-YYYYMMDD.md
- Calculer le score global de complétude
- Inclure les findings du Code Review natif (bugs détectés, régressions)
- Si score < 100% : mettre à jour docs/todo.md avec les tâches manquantes

Output : Matrice de complétude

=== MATRICE DE COMPLÉTUDE ===

Source : [docs/spec.md | Issue #42 | Prompt utilisateur]
Date : YYYY-MM-DD
Commit : [hash]

| # | Exigence | Type | Statut | Fichiers | Tests | Effort |
|---|----------|------|--------|----------|-------|--------|
| REQ-001 | Auth par email/password | FUNC | ✅ | auth.ts, login.tsx | ✅ 3 | — |
| REQ-002 | Auth par OAuth Google | FUNC | ❌ | — | — | M |
| REQ-003 | Rate limiting API | TECH | 🟡 | middleware.ts | ❌ 0 | S |
| REQ-004 | Page profil utilisateur | UX | ⚠️ | profile.tsx | ✅ 1 | S |
| REQ-005 | Tests E2E parcours achat | TEST | ❌ | — | — | L |

---

COMPLÉTUDE GLOBALE : 45% (9/20 exigences complètes)

| Statut | Nombre | % |
|--------|--------|---|
| ✅ Complète | 9 | 45% |
| 🟡 Partielle | 5 | 25% |
| ❌ Absente | 4 | 20% |
| ⚠️ Déviante | 2 | 10% |

EFFORT RESTANT ESTIMÉ : M-L (2-4 sessions)

Output : Rapport détaillé

Créer docs/reviews/review-YYYYMMDD.md :

# Review de complétude — [Nom du projet]

> Généré le [date]
> Source : [référence]
> Commit : [hash]

## Résumé exécutif

**Complétude globale : [X]%**

[2-3 phrases résumant l'état de l'implémentation vs les exigences]

## Matrice de complétude

[Tableau complet ci-dessus]

---

## Exigences complètes (✅)

### REQ-001 · Auth par email/password
- **Fichiers** : `src/auth/auth.ts:12-45`, `src/pages/login.tsx`
- **Tests** : `tests/auth.test.ts` (3 tests, tous passent)
- **Notes** : Implémentation conforme à la spec

---

## Exigences partielles (🟡)

### REQ-003 · Rate limiting API
- **Fichiers** : `src/middleware/rate-limit.ts`
- **Implémenté** : Rate limit global (100 req/min)
- **Manquant** :
  - [ ] Rate limit par endpoint (spec demande des limites différentes par route)
  - [ ] Tests unitaires
  - [ ] Réponse 429 avec header Retry-After
- **Effort** : S (1-2h)

---

## Exigences absentes (❌)

### REQ-002 · Auth par OAuth Google
- **Attendu** : Connexion via Google OAuth 2.0
- **Trouvé** : Rien — pas de dépendance OAuth, pas de route callback
- **Pour implémenter** :
  - [ ] Ajouter `next-auth` ou `passport-google-oauth20`
  - [ ] Créer route `/api/auth/google/callback`
  - [ ] Ajouter bouton "Se connecter avec Google"
  - [ ] Tests d'intégration
- **Effort** : M (demi-journée)

---

## Exigences déviantes (⚠️)

### REQ-004 · Page profil utilisateur
- **Attendu** : Page avec édition inline des champs
- **Trouvé** : Page profil en lecture seule (`src/pages/profile.tsx:1-89`)
- **Écart** : Pas d'édition, pas de formulaire, pas de sauvegarde
- **Pour corriger** :
  - [ ] Ajouter formulaire d'édition
  - [ ] API PUT /api/user/profile
  - [ ] Validation côté client et serveur
- **Effort** : S (2-3h)

---

## Code orphelin

Code implémenté mais non couvert par les exigences :
- `src/utils/analytics.ts` — Module analytics complet, non mentionné dans la spec
- `src/pages/admin/` — 3 pages admin, hors scope de la spec

---

## Prochaines étapes

1. 🔴 Implémenter REQ-002 (OAuth Google) — Bloquant pour la release
2. 🟠 Compléter REQ-003 (Rate limiting par endpoint)
3. 🟡 Corriger REQ-004 (Édition profil)
4. 🟡 Écrire tests E2E (REQ-005)

Mise à jour de docs/todo.md (format Monoboard Kanban Obsidian)

Pour chaque exigence non complète, ajouter une carte dans la colonne ## Todo du kanban. Format obligatoire : format Monoboard Kanban (kanban-plugin: board).

Si docs/todo.md absent : créer le fichier avec frontmatter kanban minimal + colonnes vides. Si docs/todo.md en format legacy : indiquer dans le rapport que la conversion est recommandée.

Tâche absente (❌) → colonne ## Todo, priorité [P0] ou [P1] :

- [ ] #REV-NNN [P0] [REQ-NNN] Implémenter [feature] #zone-[path-court] #effort-[size]

  **Source** : [docs/spec.md §Section | Issue #N]
  **Review** : [YYYY-MM-DD] — Absent
  **Effort** : [T-shirt size]

  **Checklist** :
  - [ ] Sous-tâche 1
  - [ ] Sous-tâche 2

Tâche partielle (🟡) → colonne ## Todo, priorité [P1] :

- [ ] #REV-NNN [P1] [REQ-NNN] Compléter [feature] #zone-[path-court] #effort-[size]

  **Source** : [docs/spec.md §Section]
  **Review** : [YYYY-MM-DD] — Partiel
  **Implémenté** : [ce qui existe déjà]

  **Manquant** :
  - [ ] Ce qui reste à faire

Tâche déviante (⚠️) → colonne ## Todo, priorité [P1] :

- [ ] #REV-NNN [P1] [REQ-NNN] Corriger [feature] #zone-[path-court] #effort-[size]

  **Source** : [docs/spec.md §Section]
  **Review** : [YYYY-MM-DD] — Déviant
  **Écart** : [description précise de la déviance]

  **Checklist** :
  - [ ] Ce qu'il faut corriger

Numérotation

Préfixe REV : #REV-001 → #REV-099 (tâches issues d’une review)
NNN = dernier #REV- trouvé dans todo.md + 1 (démarrer à 001 si aucun)
Autres préfixes de référence : FIX (robocop), AUD (audits), task-runner utilise les préfixes métier (SETUP, ARCH, FE, etc.)

Mode: SHIP (blackemperor)

Livraison rapide en une commande.

Workflow

Phase 1: /simplify (bundled natif)
Phase 2: spec-writer + todo-generator + CHANGELOG
Phase 2.5 (conditionnel): documentalist (si major ou >5 fichiers docs)
Phase 3: brigitte (sync Notion/Linear)
Phase 4: sync-local (README + CLAUDE.md) + claude-md-optimizer (audit + optimisation)
Phase 5: Build + tests + version bump + tag
Phase 6: /commit-push-pr — commit final + push + création PR

Phase 6 : Le plugin /commit-push-pr (commit-commands) gère automatiquement : création branche si sur main, commit, push, PR via gh pr create avec description et test plan.

Sous-modes

Commande	Comportement
`blackemperor`	Standard avec checkpoints
`blackemperor express`	Minimal de questions
`blackemperor --with-docs-cleanup`	Force Phase 2.5

Patterns Communs

Passage de Contexte

Tous les modes utilisent le bloc CONTEXTE PROJET extrait de docs/spec.md :

Économie ~30% tokens
Agents skip la reconnaissance
Cohérence entre agents

Exécution Parallèle

Agents indépendants lancés en parallèle :

Gains temps : -40%
Pas de conflit : fichiers de sortie différents

Gestion d’Erreurs et Recovery

Situation	Action	Recovery
Agent échoue (timeout)	Logger l’erreur, demander si continuer	Relancer l’agent avec un scope réduit
Agent échoue (erreur)	Logger, afficher l’erreur	Sauter l’agent, noter dans le rapport, continuer
spec-writer échoue	Le reste du workflow en dépend	Proposer : 1) Relancer avec moins de fichiers, 2) Créer spec minimale manuellement, 3) Abort
todo-generator échoue	Tâches non créées	Proposer : 1) Relancer sur la spec existante, 2) Créer todo manuellement, 3) Continuer sans todo
Audits parallèles : 1/3 échoue	Les 2 autres sont valides	Utiliser les 2 rapports réussis, noter l’audit manquant, proposer relancer
Build fail	Code potentiellement cassé	Proposer robocop ou abort
Tests fail	Régressions possibles	Options : fix (robocop), skip, abort
Conflit entre audits	Deux audits trouvent des recommandations contradictoires	Lead décide : prioriser sécurité > perf > style
Context > 40%	Risque de context rot	Proposer `/clear` et reprendre, ou gandalf health check

Agents Orchestrés

Agent	Utilisé par
spec-writer (01)	audit, legacy, ship
todo-generator (02)	audit, legacy, ship
sync-local (03)	legacy, ship
code-auditor (05)	audit, legacy, release
a11y-auditor (06)	audit, release
perf-auditor (07)	audit, legacy, release
robocop (11)	legacy, release, ship
documentalist (13)	ship
`/simplify` (natif)	legacy, ship
brigitte (24)	ship
claude-md-optimizer (42)	audit, ship

Commandes Rapides

# Audit complet
audit-complet

# Revival legacy
legacy-revival

# Check pre-release
pre-release

# Review complétude vs spec/prompt
review
review docs/spec.md
review #42                    # GitHub issue
review "Implémenter auth..."  # Prompt libre

# Ship it!
blackemperor
blackemperor express

Mode Agent Teams (expérimental)

Nécessite CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 dans settings.json ou environnement. Voir _shared/agent-teams.md pour la documentation complète. Doc officielle : https://code.claude.com/docs/en/agent-teams

Alternative aux subagents pour les phases parallèles. Les teammates communiquent entre eux directement, partagent une task list, et peuvent enrichir mutuellement leurs analyses via le système de messagerie.

Quand proposer le mode Agent Teams

Avant de lancer une phase parallèle, demander à l’utilisateur :

La phase parallèle peut fonctionner de 2 manières :

1. **Subagents** (défaut) - Rapide, moins de tokens
2. **Agent Team** - Les auditeurs communiquent entre eux,
   partagent des findings en temps réel, se challengent
   Expérimental, plus coûteux en tokens

Quel mode ?

Application par mode

Mode	Phase parallélisable	Agent Teams recommandé ?
audit	Phase 2 : code + perf + a11y	Oui - findings croisés, débat
legacy	Phase 3 : simplifier + perf	Optionnel
release	Phase 2 : audits pré-release	Oui - revue collaborative
review	Phase 2 : analyse par exigence	Oui - si >10 exigences
ship	Phase 2 : spec + todo + changelog	Non - trop simple

Exemple : Audit en Agent Team

Créer une équipe d'agents pour auditer ce repository.
Spawner 3 auditeurs :
- code-reviewer : qualité du code, architecture, sécurité
- perf-reviewer : bundle, Core Web Vitals, backend, N+1
- a11y-reviewer : WCAG 2.1/2.2, composants, navigation
Chacun génère son rapport dans docs/audits/.
Exiger l'approbation du plan avant les modifications.
Utiliser le mode delegate pour rester en coordination pure.

Configuration d’affichage

Recommander le mode d’affichage avant de créer l’équipe :

in-process (défaut) : tous dans le terminal principal, Shift+Up/Down pour naviguer
split panes : chaque teammate visible dans son panneau (tmux/iTerm2 requis)

{ "teammateMode": "in-process" }

Consolidation

Après que tous les teammates aient terminé :

Lead lit les 3 rapports
Lead met à jour docs/spec.md (une seule écriture)
Lead met à jour docs/todo.md (une seule écriture)
Lead génère le rapport consolidé
Lead demande aux teammates de s’arrêter (shutdown gracieux)
Lead nettoie l’équipe (cleanup — vérifie 0 teammates actifs)

Limitations à connaître

/resume ne restaure pas les teammates — respawner si nécessaire
Les teammates finissent leur requête en cours avant shutdown (peut être lent)
Une seule équipe par session — cleanup avant d’en créer une nouvelle
Les teammates ne peuvent pas spawner d’autres teammates (pas d’imbrication)

Remember: Vous êtes un chef d’orchestre. Lancez les agents en parallèle quand possible (subagents ou Agent Teams), passez le contexte entre phases, consolidez les résultats.