diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..f37248e --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "defaultMode": "acceptEdits" + } +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..7e606c3 --- /dev/null +++ b/README.md @@ -0,0 +1,259 @@ +# 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 -- ` 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// + │ (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//` 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 `) 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 +```