Files
epic-devteam/README.md
T

260 lines
14 KiB
Markdown
Raw Normal View History

2026-11-15 18:19:01 +01:00
# epic-devteam — Workflow TDD multi-agent piloté par OpenSpec
`epic-devteam` est une équipe d'agents IA qui transforme un besoin exprimé en langage naturel en code testé et relu. Le workflow suit deux principes :
- **OpenSpec comme source de vérité** : chaque évolution commence par un *changement* OpenSpec (proposition, spécifications, conception, tâches) validé par vous avant toute ligne de code.
- **TDD strict (Red → Green → Refactor)** : les tests sont écrits d'abord, à partir de la spécification, par un agent dédié. Ils sont ensuite figés par un commit, et l'implémentation n'a pas le droit d'y toucher.
Chaque rôle (concevoir, tester, implémenter, relire) est tenu par un agent distinct, avec des permissions limitées. Ce cloisonnement empêche un agent de « tricher », par exemple en modifiant un test pour le faire passer.
Le workflow fonctionne avec **Claude Code** (`.claude/agents/`) et **OpenCode** (`.opencode/agents/`). Les deux jeux d'agents ont les mêmes instructions ; seuls les en-têtes (modèle, permissions) changent.
---
## Sommaire
- [Prérequis](#prérequis)
- [Installation dans un projet](#installation-dans-un-projet)
- [Les agents](#les-agents)
- [Les étapes du workflow](#les-étapes-du-workflow)
- [Utilisation](#utilisation)
- [Bonnes pratiques et pièges](#bonnes-pratiques-et-pièges)
- [Structure du dépôt](#structure-du-dépôt)
---
## Prérequis
| Dépendance | Rôle | Vérification |
|---|---|---|
| **OpenSpec CLI** (v2.x) | Gestion des changements et des specs, utilisée par les skills `openspec-*` | `openspec --version` |
| **git** | Commit de la phase rouge et contrôle d'intégrité des tests | `git --version` |
| **Claude Code** ou **OpenCode** | Exécution des agents | `claude --version` / `opencode --version` |
### Installer OpenSpec
```bash
npm install -g @fission-ai/openspec@latest
openspec --version
```
> **Important** : les agents ne fonctionnent pas sans OpenSpec. L'architecte s'appuie sur les skills `openspec-explore` et `openspec-propose`, le développeur sur `openspec-apply-change`, et l'archivage final sur `openspec-archive-change`. Ces skills appellent la CLI `openspec`, qui doit donc être dans le `PATH`.
---
## Installation dans un projet
1. **Initialiser OpenSpec** à la racine du projet cible :
```bash
cd mon-projet
openspec init
```
Sélectionnez Claude Code et/ou OpenCode comme outils. La commande crée :
- `openspec/` : `config.yaml`, `specs/` (specs durables) et `changes/` (changements en cours et archivés) ;
- `.agents/skills/openspec-*` : les skills OpenSpec, liés dans `.claude/skills/` pour Claude Code.
2. **Copier les agents** de ce dépôt :
```bash
# Claude Code
cp -r epic-devteam/.claude/agents mon-projet/.claude/
# OpenCode
cp -r epic-devteam/.opencode/agents mon-projet/.opencode/
```
3. **(Optionnel) Renseigner `openspec/config.yaml`** : ajoutez les contraintes que les agents ne peuvent pas déduire du code (langue des artefacts, plateformes cibles, règles par artefact, etc.).
4. **(Optionnel) Ajuster les modèles** dans l'en-tête de chaque agent (voir [Les agents](#les-agents)).
Vous n'avez pas besoin de créer `ARCHITECTURE.md` ni `TDD.md` vous-même : l'architecte les fait générer par `@repo-scout` au premier lancement.
---
## Les agents
| Agent | Rôle | Phase | Peut modifier | Modèle Claude Code | Modèle OpenCode |
|---|---|---|---|---|---|
| **`architect`** | Chef d'orchestre : spécifie avec vous, délègue, **valide lui-même chaque phase** en lançant les tests | Toutes | Specs OpenSpec, `AGENTS.md` | `inherit` | `glm-5.3` |
| **`repo-scout`** | Analyse le dépôt : pile, conventions, commandes | Préparation | `ARCHITECTURE.md`, `TDD.md` uniquement | `sonnet` | `glm-5.3` |
| **`test-writer`** | Écrit les tests rouges à partir de la spec, puis les commite | Rouge | Tests + squelettes vides | `haiku` | `glm-5.3-flash` |
| **`developer`** | Implémente le code de production jusqu'au vert | Vert / Refactor | Code de production (**jamais les tests**) | `haiku` | `glm-5.3-flash` |
| **`code-reviewer`** | Vérifie l'intégrité des tests, relit le code et propose des refactors | Refactor | Rien (lecture seule) | `sonnet` | `glm-5.3` |
| **`diff-summarizer`** | Résume un diff existant pour une prise de contexte rapide | Au besoin | Rien | `haiku` | `glm-5.3-flash` |
### `architect` — l'orchestrateur
C'est **le seul agent avec lequel vous dialoguez**. Il :
- explore le besoin avec vous (`openspec-explore`), puis rédige le changement (`openspec-propose`) ;
- n'écrit **jamais** de code, mais exécute lui-même les tests pour constater le rouge, le vert et le maintien du vert ;
- conserve le **hash du commit de la phase rouge**, qui sert de référence d'intégrité des tests ;
- arbitre les désaccords (un test jugé incorrect par le développeur repart vers `test-writer`, jamais vers `developer`) ;
- propose l'archivage du changement à la fin.
Il doit tourner en **session principale**, car seul l'agent principal peut déléguer à des sous-agents.
### `repo-scout` — la cartographie
Il produit et tient à jour deux fichiers à la racine du dépôt, que tous les autres agents utilisent :
- **`ARCHITECTURE.md`** : pile détectée (avec fichiers de preuve), conventions, points chauds, patterns à faire et à éviter ;
- **`TDD.md`** : commandes **exactes** pour lancer toute la suite, un test isolé, les linters et vérificateurs de types, plus l'organisation des tests.
Il n'installe rien et n'accède pas au réseau.
### `test-writer` — la phase rouge
1. Vérifie que la **base est verte** (tous les tests existants passent). Si elle ne l'est pas, il n'écrit rien et alerte l'architecte.
2. Écrit des tests **boîte noire** (via les interfaces publiques), positifs et négatifs, dont les valeurs attendues viennent de la spec.
3. Ajoute au besoin des **squelettes vides** pour que le code compile (langages typés), sans aucune logique.
4. Vérifie que chaque nouveau test échoue **pour la bonne raison** (pas pour une erreur d'import ou de syntaxe).
5. Commite **uniquement ses fichiers** avec un message `test: …` et transmet le hash.
### `developer` — la phase verte
- Implémente via le skill `openspec-apply-change`, en prenant les tests comme critère d'acceptation.
- **Interdiction absolue** d'ajouter, modifier, désactiver ou affaiblir un test.
- Pas de triche : il ne doit ni détecter les tests, ni coder en dur les valeurs attendues.
- Respecte YAGNI et les conventions du dépôt, et lance linters et vérificateurs de types avant de déclarer avoir terminé.
- Ne commite pas : **c'est vous qui gérez les commits d'implémentation**.
### `code-reviewer` — la phase refactor
1. **Contrôle bloquant** : `git diff <hash-rouge> -- <fichiers de tests>` doit être vide.
2. Vérifie la conformité au changement OpenSpec (objectifs, périmètre, non-objectifs).
3. Relit l'exactitude, la robustesse et la sécurité de base.
4. Propose des **refactors sans changement de comportement** (lisibilité, duplication, nommage).
5. Signale les scénarios à risque qui ne sont pas couverts, pour qu'un test complémentaire soit écrit.
Il ne produit **que des demandes de modification actionnables** (quoi, pourquoi, où) ou une approbation.
### `diff-summarizer` — l'utilitaire
Appelé par l'architecte quand des modifications existent déjà (copie de travail, diff de PR). Il renvoie un résumé court au format `type / scope / summary / files`.
---
## Les étapes du workflow
```
Vous ──► @architect
│
A. Skills │ chargement des skills pertinents pour la pile
│
B. Spec │ openspec-explore ⇄ openspec-propose
│ ──► openspec/changes/<nom-du-changement>/
│ (proposal.md, specs/, design.md, tasks.md)
│
▼ ⛔ attend le mot « approuvé »
C.0 Prép. │ @repo-scout ──► ARCHITECTURE.md + TDD.md
│
C.1 ROUGE │ @test-writer : base verte ? ─non─► stop, décision avec vous
│ └─oui─► tests rouges ──► commit `test: …` (hash H)
│ @architect vérifie lui-même le rouge
│
C.2 VERT │ @developer : implémente jusqu'au vert (tests intouchables)
│ @architect vérifie le vert + aucun test modifié depuis H
│
C.3 REFAC │ @code-reviewer : intégrité vs H, revue, demandes de refactor
│ └─► @developer applique ──► @architect revérifie le vert
│ (boucle jusqu'à l'approbation du reviewer)
│ (test manquant ? ──► retour à @test-writer, puis C.2)
│
D. Retour │ résumé, compromis, suggestion d'archivage
▼
openspec-archive-change ──► openspec/specs/ mis à jour
```
### A. Découverte des skills
Chaque agent charge les skills disponibles qui correspondent à la pile du projet et indique lesquels il a chargés. S'il n'en trouve aucun, il continue avec ses connaissances générales.
### B. Spécification (OpenSpec)
- **Exploration** quand le besoin est flou : questions ciblées, une ou deux à la fois.
- **Proposition** quand l'intention est claire : création de `openspec/changes/<nom>/` avec proposition, delta de specs, conception et tâches.
- L'architecte peut passer d'un mode à l'autre et vous dit toujours dans lequel il se trouve.
- **Porte de validation** : l'implémentation ne démarre que sur le mot exact **« approuvé »**. Une formule comme « ok » ou « vas-y » ne suffit pas.
### C. Boucle TDD
| Étape | Qui agit | Qui valide | Condition de sortie |
|---|---|---|---|
| 0. Préparation | `repo-scout` | `architect` | `ARCHITECTURE.md` et `TDD.md` existent et sont fiables |
| 1. Rouge | `test-writer` | `architect` (exécute les tests) | Nouveaux tests en échec, anciens au vert, commit `test:` créé |
| 2. Vert | `developer` | `architect` (exécute les tests + contrôle du diff des tests) | Suite entièrement verte, tests inchangés depuis le hash rouge |
| 3. Refactor | `code-reviewer` → `developer` | `architect` (revalide après chaque application) | Approbation du reviewer, vert maintenu |
### D. Retour et archivage
L'architecte résume ce qui a été fait et les éventuels écarts, puis propose `openspec-archive-change`. Cette commande fusionne le delta de specs dans `openspec/specs/` et déplace le changement dans `openspec/changes/archive/`.
---
## Utilisation
### Lancer l'architecte
**Claude Code** : l'architecte doit être l'agent principal de la session.
```bash
claude --agent architect
```
**OpenCode** : `architect` est déclaré `mode: primary`. Sélectionnez-le comme agent principal au démarrage de la session.
### Exemple de session
```
Vous > Je veux ajouter un export CSV des factures, filtrable par date.
architect > [explore] Quelques questions avant de proposer :
1. L'export doit-il inclure les factures annulées ?
2. Quel format de date en entrée ?
Vous > Non. ISO 8601.
architect > [propose] Changement `add-invoice-csv-export` créé :
proposal.md, specs/invoices/spec.md, design.md, tasks.md.
Relisez-le. Répondez « approuvé » pour lancer l'implémentation.
Vous > approuvé
architect > TDD.md absent → @repo-scout…
Phase rouge → @test-writer… 6 tests rouges, commit a1b2c3d.
Rouge vérifié. Phase verte → @developer…
Vert vérifié, tests intacts depuis a1b2c3d.
Revue → @code-reviewer : 2 refactors demandés… appliqués, vert maintenu.
Approuvé par le reviewer. Résumé : … Archiver le changement ?
```
### Reprendre ou ajuster un changement
- Pour **modifier la spec** en cours de route, demandez-le à l'architecte. Il utilisera `openspec-update-change` et redemandera votre approbation si les décisions changent.
- Pour **synchroniser les specs** sans archiver : skill `openspec-sync-specs`.
- Les changements en cours se trouvent dans `openspec/changes/` et peuvent être repris dans une nouvelle session.
---
## Bonnes pratiques et pièges
- **Démarrez sur une copie de travail propre.** `test-writer` ne commite que ses propres fichiers, mais une base propre rend le contrôle d'intégrité (`git diff <hash>`) beaucoup plus lisible.
- **Ne réécrivez pas l'historique** (rebase, amend, squash) pendant un cycle : le hash du commit rouge doit rester valide jusqu'à la fin de la revue.
- **Commitez l'implémentation vous-même** une fois le cycle terminé : `developer` ne commite pas.
- **Ayez une base verte.** Si des tests échouent déjà, la phase rouge est bloquée et l'architecte vous demandera de choisir : réparer d'abord, ignorer les échecs en le justifiant, ou abandonner.
- **Relisez la proposition OpenSpec** avant d'écrire « approuvé » : les tests en découlent directement, et une spec floue donne des tests flous.
- **Gardez `TDD.md` exact.** Si vous changez de runner ou de commandes, demandez à l'architecte de relancer `@repo-scout`.
- **Projet sans tests ?** `repo-scout` l'indiquera dans `TDD.md`. Il faut mettre en place un runner de tests avant de pouvoir lancer la boucle TDD.
- **Permissions Claude Code** : `.claude/settings.json` active `acceptEdits` par défaut pour fluidifier la boucle. Adaptez ce réglage à votre niveau de confiance.
---
## Structure du dépôt
```
.
├── .claude/
│ ├── agents/ # Agents pour Claude Code
│ ├── skills/ # Liens symboliques vers .agents/skills/
│ └── settings.json # Permissions par défaut (acceptEdits)
├── .opencode/
│ └── agents/ # Mêmes agents pour OpenCode (modèles OpenRouter)
├── .agents/
│ └── skills/ # Skills OpenSpec générés par `openspec init`
└── openspec/
├── config.yaml # Schéma `spec-driven` + contexte/règles optionnels
├── specs/ # Specs durables (alimentées par l'archivage)
└── changes/ # Changements en cours
└── archive/ # Changements archivés
```