# AGENTS.md ## Table des matières - [Introduction](#introduction) - [Principes communs](#principes-communs) - [Agents fondamentaux](#agents-fondamentaux) - [Agents spécialisés documentation](#agents-spécialisés-documentation) - [Agents spécialisés tests](#agents-spécialisés-tests) - [Agents techniques](#agents-techniques) - [Agents frontend](#agents-frontend) - [Agents open source et CI](#agents-open-source-et-ci) - [Agents de synchronisation et dérogations](#agents-de-synchronisation-et-d%C3%A9rogations) - [Matrice de coordination](#matrice-de-coordination) - [Conclusion](#conclusion) --- ## Introduction Ce document définit les agents, leurs rôles et leurs responsabilités dans le projet `4NK/4NK_node` et, par extension, tout dépôt dérivé de `4NK_project_template`. Il impose une coordination stricte entre code, documentation, tests, dépendances, CI/CD, synchronisation de template et gouvernance open source. Les règles opérationnelles détaillées sont précisées dans `.cursor/rules/` (notamment `41-ssh-automation.mdc` et `42-template-sync.mdc`). --- ## Principes communs - Langue exclusive : français. - Pas d’exemples de code applicatif injectés dans la base. - Toute contribution doit contenir une introduction et/ou une conclusion. - Interdiction de secrets en clair dans le dépôt. - Confirmation nécessaire avant `push` et `tag`. - Toute modification impactant des éléments normatifs doit mettre à jour la documentation et le changelog. --- ## Agents fondamentaux ### Agent Fondation (Responsable) **Missions** - Garantir la conformité éditoriale : français, pas d’exemples applicatifs, introduction/conclusion. - Vérifier la cohérence terminologique. **Artefacts** - Tous fichiers. --- ### Agent Structure (Responsable) **Missions** - Maintenir l’arborescence canonique (incluant `.cursor/`, `.gitea/`, `scripts/`, `docs/SSH_UPDATE.md`). - Archiver le contenu obsolète dans `archive/` avec métadonnées. - Interdire toute suppression non tracée. **Artefacts** - `archive/`, `docs/**`, `tests/**`, `.cursor/**`, `.gitea/**`, `scripts/**`, `CHANGELOG.md`. --- ## Agents spécialisés documentation ### Agent Documentation (Responsable) **Missions** - Mettre à jour `docs/**` selon l’impact des changements. - Tenir `docs/INDEX.md` comme table des matières centrale. - Produire des REX techniques dans `archive/` en cas d’investigations multiples. **Artefacts** - `docs/**`, `README.md`, `archive/**`. --- ### Agent Données CSV (Responsable) **Missions** - Traiter les CSV comme source des modèles de données (en-têtes multi-lignes inclus). - Exiger une définition complète de toutes les colonnes. - Corriger et documenter les incohérences de types. **Artefacts** - `docs/API.md`, `docs/ARCHITECTURE.md`, `docs/USAGE.md`. --- ### Agent Documents bureautiques (Consulté) **Missions** - Lire `.docx` via `docx2txt`; proposer des alternatives en cas d’échec. - Documenter les imports dans `docs/INDEX.md`. **Artefacts** - `docs/**`, `archive/**`. --- ## Agents spécialisés tests ### Agent Tests (Responsable) **Missions** - Couvrir `unit`, `integration`, `connectivity`, `performance`, `external`. - Gérer `tests/logs` et `tests/reports`. - Exiger des tests verts avant commit. **Artefacts** - `tests/**`, `docs/TESTING.md`. --- ### Agent Performance (Consulté) **Missions** - Réaliser des benchmarks reproductibles. - Valider l’impact performance avant fusion. **Artefacts** - `tests/performance/`, `tests/reports/`, `docs/TESTING.md`. --- ## Agents techniques ### Agent Dépendances (Responsable) **Missions** - Ajouter les dépendances manquantes lorsque justifié. - Vérifier les dernières versions stables. - Documenter les impacts dans `ARCHITECTURE.md`, `CONFIGURATION.md`, `CHANGELOG.md`. **Artefacts** - `docs/ARCHITECTURE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md`. --- ### Agent Compilation (Responsable) **Missions** - Compiler très régulièrement et aux étapes critiques. - Bloquer toute progression en cas d’erreurs de build/runtime. **Artefacts** - Artefacts de build, scripts d’outillage. --- ### Agent Résolution (Responsable) **Missions** - Conduire la boucle de diagnostic complète : reproduction minimale, logs, bissection, hypothèses, tests ciblés, correctif, non-régression. - Produire un REX quand plusieurs hypothèses ont été testées. **Artefacts** - `tests/**`, `archive/**` --- ### Agent SSH & scripts (Responsable) **Missions** - Garantir la présence et l’usage correct de `scripts/auto-ssh-push.sh`, `scripts/init-ssh-env.sh`, `scripts/setup-ssh-ci.sh`. - Assurer permissions d’exécution, idempotence, journalisation non sensible, gestion d’erreurs robuste. - Interdire secrets en clair, gérer via secrets CI et variables d’environnement. - Exiger la mise à jour de `docs/SSH_UPDATE.md` à toute évolution des scripts ou des flux SSH. **Artefacts** - `scripts/**`, `.gitea/workflows/ci.yml`, `docs/SSH_UPDATE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md`. --- ## Agents frontend ### Agent Frontend (Responsable) **Missions** - Mettre en place `React.lazy`/`Suspense` (code splitting). - Centraliser l’état (Redux ou Context API). - Abstraire les services de données. **Artefacts** - `docs/ARCHITECTURE.md`, `docs/TESTING.md`. --- ## Agents open source et CI ### Agent Open Source (Responsable) **Missions** - Maintenir : `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `docs/OPEN_SOURCE_CHECKLIST.md`. - Vérifier l’alignement continu avec `4NK_node`. **Artefacts** - Fichiers de gouvernance cités ci-dessus. --- ### Agent Gitea (Responsable) **Missions** - Garantir `.gitea/ISSUE_TEMPLATE/*`, `PULL_REQUEST_TEMPLATE.md`, `.gitea/workflows/ci.yml`. - Documenter la configuration distante dans `docs/GITEA_SETUP.md`. - Déclencher les étapes CI pertinentes (tests, lint, sécurité, vérifs `scripts/`). **Artefacts** - `.gitea/**`, `docs/GITEA_SETUP.md`. --- ### Agent Versionnage (Responsable) **Missions** - Tenir `CHANGELOG.md` comme source unique de vérité. - Proposer un bump sémantique justifié. - Demander confirmation avant push et tag. **Artefacts** - `CHANGELOG.md`, `docs/RELEASE_PLAN.md`, `docs/ROADMAP.md`. --- ## Agents de synchronisation et dérogations ### Agent Synchronisation de template (Accountable) **Références** - `.4nk-sync.yml` (manifeste), `TEMPLATE_VERSION` (pointeur), `.gitea/workflows/template-sync.yml` (CI dédiée). - Règles Cursor : `.cursor/rules/42-template-sync.mdc` et `.cursor/rules/10-project-structure.mdc`. **Missions** - Assurer l’alignement automatique sur le template pour : `.cursor/**`, `.gitea/**`, `AGENTS.md`, `scripts/**`, `docs/SSH_UPDATE.md`. - Déclencher/valider la PR `[template-sync]` créée par la CI. - Exiger la mise à jour de `CHANGELOG.md` et `docs/INDEX.md` après synchronisation. - Vérifier l’intégrité (`manifest_checksum`, checksums de fichiers si publiés), les permissions, l’absence de secrets. - Mettre à jour `TEMPLATE_VERSION` dans la PR. **Artefacts** - `.4nk-sync.yml`, `TEMPLATE_VERSION`, `.cursor/**`, `.gitea/**`, `AGENTS.md`, `scripts/**`, `docs/SSH_UPDATE.md`, `CHANGELOG.md`. --- ### Agent Dérogations locales (Responsable) **Références** - `LOCAL_OVERRIDES.yml` (facultatif, mais recommandé). **Missions** - Enregistrer toute divergence locale dans le périmètre synchronisé (path, raison, propriétaire, échéance). - Faire respecter : seules les dérogations listées et non expirées sont tolérées par la CI. - Auditer périodiquement et résorber les dérogations. **Artefacts** - `LOCAL_OVERRIDES.yml`, `CHANGELOG.md` (mentionner les dérogations significatives). --- ## Matrice de coordination | Type de changement | Agents impliqués | Artefacts principaux | Validation obligatoire | |----------------------------------|----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------| | Ajout de fonctionnalité | Documentation, Tests, Dépendances, Frontend | `docs/API.md`, `docs/USAGE.md`, `docs/ARCHITECTURE.md`, `tests/unit`, `tests/integration`, `CHANGELOG.md` (*Added*) | Oui | | Correction de bug | Résolution, Tests, Documentation | `tests/unit`, `docs/TESTING.md`, `archive/` (REX si nécessaire), `CHANGELOG.md` (*Fixed*) | Oui | | Refactorisation / amélioration | Structure, Documentation, Compilation | `docs/ARCHITECTURE.md`, `archive/`, `CHANGELOG.md` (*Changed*) | Oui | | Dépendance ajoutée/mise à jour | Dépendances, Compilation, Documentation | `docs/ARCHITECTURE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md` (*Dependencies*) | Oui | | Données CSV modifiées | Données CSV, Documentation, Tests | `docs/API.md`, `docs/ARCHITECTURE.md`, `docs/USAGE.md`, `tests/unit`, `CHANGELOG.md` (*Data model update*) | Oui | | Migration / breaking change | Documentation, Tests, Résolution, Versionnage | `docs/MIGRATION.md`, `docs/INSTALLATION.md`, `docs/RELEASE_PLAN.md`, `docs/ROADMAP.md`, `tests/integration`, `CHANGELOG.md` (*Breaking*) | Oui | | Sécurité / audit | Documentation, Tests, Open Source, Sécurité proactive | `docs/SECURITY_AUDIT.md`, `tests/external`, `tests/connectivity`, `CHANGELOG.md` (*Security*) | Oui | | Préparation open source / CI | Open Source, Gitea, Versionnage, Documentation communautaire, Contributeurs externes | `.gitea/**`, `docs/GITEA_SETUP.md`, `docs/OPEN_SOURCE_CHECKLIST.md`, `CHANGELOG.md` (*CI/CD* / *Governance*) | Oui | | Optimisation performance | Performance, Tests, Documentation | `tests/performance`, `tests/reports`, `docs/ARCHITECTURE.md`, `CHANGELOG.md` (*Performance*) | Oui | | Évolution frontend | Frontend, Documentation, Tests | `docs/ARCHITECTURE.md`, `docs/USAGE.md`, `tests/integration`, `CHANGELOG.md` (*Frontend*) | Oui | | Évolution CI/CD ou scripts SSH | SSH & scripts, Gitea, Versionnage, Documentation | `scripts/**`, `.gitea/workflows/ci.yml`, `docs/SSH_UPDATE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md` (*CI/CD*) | Oui | | **Synchronisation de template** | **Synchronisation de template**, Gitea, Versionnage, Structure, Documentation, SSH & scripts | `.4nk-sync.yml`, `TEMPLATE_VERSION`, `.cursor/**`, `.gitea/**`, `AGENTS.md`, `scripts/**`, `docs/SSH_UPDATE.md`, `CHANGELOG.md` | **Oui** | | Dérogation locale contrôlée | Dérogations locales, Gitea, Synchronisation de template, Versionnage | `LOCAL_OVERRIDES.yml`, `CHANGELOG.md` (mention), CI tolérante uniquement sur chemins listés et non expirés | Oui | --- ## Conclusion Ce `AGENTS.md` mis à jour introduit l’**Agent Synchronisation de template** et l’**Agent Dérogations locales**, renforce l’**Agent SSH & scripts**, et rattache l’ensemble aux règles Cursor et à la CI Gitea. La matrice de coordination formalise les validations obligatoires pour chaque type de changement, garantissant cohérence structurelle, qualité documentaire, sécurité, traçabilité et stabilité à long terme sur tous les projets issus de `4NK_project_template`.