diff --git a/AGENTS.md b/AGENTS.md index ca45d38..bec6d95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -156,3 +156,91 @@ Le projet suit un plan séquentiel en **15 jalons** (M1-M15) décrits dans [`TOD |----------|------| | [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md) | Spécification complète (architecture, modèles, parsing, déploiement) | | [`TODO.md`](./TODO.md) | Plan de développement détaillé (15 jalons) | + +--- + +## 9. Agents OpenCode + +Cette section s'applique uniquement lorsque le travail est exécuté avec le système d'agents d'OpenCode. + +Les rôles d'agents disponibles pour ce projet sont les suivants : + +- `@architect` : Arbitrages d'architecture et choix techniques structurants pour le pipeline `pronote-sync`. +- `@coder` : Opérations de développement et changements de code dans le projet. +- `@debugger` : Reproduction d'un symptôme et établissement de sa cause profonde (ex. : échec de synchronisation, repli iCal/pronotepy). +- `@explorer` : Exploration du dépôt en lecture seule et fourniture de contexte factuel. +- `@orchestrator` : Compréhension globale du projet, définition des jalons, coordination et garantie du résultat. +- `@planner` : Transformation d'une demande complexe en unités exécutables avec frontières et dépendances claires. +- `@reviewer` : Revues indépendantes de correction, régression, contrats et maintenabilité. +- `@security-auditor` : Audit indépendant d'une surface de sécurité désignée (ex. : gestion des secrets, masquage des données). +- `@tech-writer` : Rédaction et maintenance de documentation technique exacte et vérifiable. +- `@test-engineer` : Conception, écriture et exécution de tests ciblés (unitaires, intégration, mocks). +- `@ui-designer` : conception et implémentation d'interfaces Web et terminal. +- `@verifier` : Vérification indépendante du comportement livré, des régressions et du respect des conventions (idempotence, mode dégradé). +- `@web-explorer` : Recherche et extraction de sources Web vérifiables (ex. : documentation Pronote, CalDAV, XMPP). + +> **Note** : Ne pas utiliser `@coder` pour les tâches de documentation (`@tech-writer`) ni pour les tests (`@test-engineer`). + +--- + +## 10. Workflow de modification + +1. Lire la demande, [`TODO.md`](./TODO.md), `git status` et les fichiers concernés. +2. Préserver les changements existants de l'utilisateur. +3. Pour une correction, reproduire d'abord le défaut avec un test automatisé lorsque c'est raisonnable. +4. Faire une modification étroite et cohérente, en respectant les conventions du projet (idempotence, mode dégradé, repli iCal/pronotepy). +5. Vérifier le comportement nominal et les cas d'erreur, notamment : + - Succès de la synchronisation Pronote → CalDAV/XMPP. + - Repli vers iCal en cas d'échec de `pronotepy`. + - Gestion des erreurs explicites. +6. Mettre à jour la documentation et les exemples dans le même changement si leur comportement public évolue. +7. Cocher dans [`TODO.md`](./TODO.md) uniquement les éléments entièrement réalisés et validés. +8. Terminer avec un *handoff* concis : fichiers modifiés, validations exécutées, limites et prochaine étape. + +> **Pour les changements larges ou risqués** : Produire d'abord un audit ou un aperçu. +> **Règle de commit** : Ne pas committer sans autorisation explicite. Une autorisation de commit ne vaut pas autorisation de push. + +--- + +## 11. Branches et commits + +- Une évolution cohérente se fait sur une **branche dédiée**. +- Nommer les branches selon le format `/`, où `` est l'un des suivants : + `feature`, `fix`, `docs`, `chore` ou `refactor`. +- Partir de l'état validé de la branche principale (`main` ou `dev`), sauf demande explicite. +- Garder **un commit atomique par objectif vérifiable**. Utiliser les préfixes conventionnels pour les messages de commit : + - `feat:` pour une nouvelle fonctionnalité. + - `fix:` pour une correction de bug. + - `docs:` pour une mise à jour de documentation. + - `chore:` pour une tâche de maintenance. + - `refactor:` pour une refactorisation de code. +- Quand un agent a contribué au changement, ajouter un *trailer* Git standard au commit : + ``` + Co-authored-by: / + ``` +- Avant un commit autorisé, vérifier : + - `git status` (fichiers modifiés attendus). + - Le diff complet (`git diff`). + - L'absence de secret ou de configuration locale dans le diff. + - Les validations pertinentes (`ruff`, `mypy`, `pytest`, `bandit`). + - `git diff --check` (pas de problèmes d'espaces blancs). +- Après le commit, rapporter : + - Le hash du commit. + - Le contenu du commit. + - Les validations exécutées. + +> **Règle absolue** : Ne jamais pousser (`git push`) sans demande distincte et explicite. + +--- + +## 12. Définition de terminé + +Un changement est considéré comme **terminé** lorsque : + +- Le cas nominal et les échecs pertinents sont testés (ex. : synchronisation réussie, repli iCal, erreurs explicites). +- Les outils de validation (`ruff`, `mypy`, `pytest`, `bandit`) passent sans erreur. +- Aucun secret ni configuration locale n'apparaît dans le diff ou les fichiers suivis. +- La documentation reste cohérente avec le code (ex. : mise à jour des exemples, des contrats ou des décisions d'architecture). +- Le *handoff* distingue clairement : + - Ce qui a été vérifié localement (ex. : tests unitaires, linter). + - Ce qui nécessite encore une vérification manuelle (ex. : tests d'intégration avec un serveur CalDAV réel).