# AGENTS.md ## Table des matières - [Introduction](#introduction) - [Principes communs](#principes-communs) - [Agents fondamentaux](#agents-fondamentaux) - [Agents spécialisés documentation](#agents-specialises-documentation) - [Agents spécialisés tests](#agents-specialises-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-derogations) - [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. - Le flux de publication applique un garde de release (tests/doc/build/alignement version/changelog/tag, latest vs wip). --- ## 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 Qualité technique (Responsable) #### Missions - Définir et faire respecter les standards de qualité: lint, formatage, conventions de code, revues. - Superviser l’analyse statique (types, duplication, complexité, sécurité basique) et corriger les écarts. - Assurer l’exécution automatique des contrôles qualité dans la CI et bloquer en cas d’échec. #### Artefacts - `.gitea/workflows/ci.yml` (jobs de lint/format/type-check), `CHANGELOG.md`, `docs/ARCHITECTURE.md` (section standards). --- ### 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. - Orchestrer le `release-guard` (CI + scripts) et consigner latest vs wip. #### Artefacts - `CHANGELOG.md`, `docs/RELEASE_PLAN.md`, `docs/ROADMAP.md`. --- ### Agent Sécurité (Responsable) #### Missions - Assurer une vigilance continue sécurité sur le code, la config et la CI. - Orchestrer l’audit de sécurité automatisé: `scripts/security/audit.sh` (cargo audit, npm audit, scan secrets). - Interdire l’introduction de secrets en clair et exiger la rotation des secrets CI. - Valider les permissions sensibles (clés, cookies, conf) et la non-exposition d’endpoints privés. - Bloquer toute release si l’audit de sécurité échoue (intégré au `release-guard`). #### Artefacts - `scripts/security/audit.sh`, `.gitea/workflows/ci.yml` (job `security-audit`), `docs/SECURITY_AUDIT.md`, `docs/CONFIGURATION.md`. --- ### Agent Déploiement (Responsable) #### Missions - Définir et documenter la stratégie de déploiement (environnements, prérequis, secrets, rollbacks). - Vérifier la présence et la cohérence des artefacts de déploiement et des variables d’environnement requises. - Intégrer des contrôles CI « deployment-checks » avant toute release; coordonner avec `release-guard`. #### Artefacts - `docs/DEPLOYMENT.md`, `.gitea/workflows/ci.yml` (job `deployment-checks`), `CHANGELOG.md`, `docs/RELEASE_PLAN.md`. --- ### Agent Gouvernance du Template (Accountable) #### Missions - Garantir la cohérence d’ensemble du template (règles Cursor, CI, scripts, docs). - Examiner les issues « Template Feedback », arbitrer et prioriser. - Orchestrer la montée de version du template (`TEMPLATE_VERSION`) et le `CHANGELOG.md`. - Communiquer les changements aux projets consommateurs. #### Artefacts - `.cursor/rules/**`, `.gitea_template/**`, `docs/TEMPLATE_*`, `TEMPLATE_VERSION`, `CHANGELOG.md`. --- ### Agent Adaptation Projet (Responsable) #### Missions - Accompagner l’adaptation locale du template (CI, docs, `AGENTS.md`). - S’assurer que `security-audit` et `release-guard` ne sont pas retirés. - Remonter en feedback toute amélioration générique. #### Artefacts - `.gitea/workflows/ci.yml`, `docs/INDEX.md`, `docs/SECURITY_AUDIT.md`, `AGENTS.md`, `LOCAL_OVERRIDES.yml` (si utilisé). --- ## 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 | | Déploiement | Déploiement, Versionnage, Sécurité, Documentation | `docs/DEPLOYMENT.md`, `.gitea/workflows/ci.yml` (deployment-checks), `CHANGELOG.md` (*Deployment*) | 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 | --- ## Requetes complexes Quand tu fais une commande ou un requète complexe, explique là avant de la lancer. ## 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é. Ainsi que la stabilité à long terme sur tous les projets issus de `4NK_project_template`.