4nk/docv
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
docv/AGENTS.md
Sadrinho27 aedd3b9f10
Some checks failed
4NK Template Sync / check-and-sync (push) Failing after 1s
Details
first commit
2025-09-29 16:57:49 +02:00

13 KiB
Raw Blame History

AGENTS.md

Table des matières

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 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

  • Mettre en place et exécuter scripts/security/audit.sh (npm audit, cargo audit si applicable, scan de secrets).
  • Interdire les secrets en clair; assurer la rotation des secrets CI.
  • Vérifier permissions et non‑exposition d’endpoints privés.
  • Bloquer la release si l’audit échoue (intégré au release-guard).

Artefacts

  • scripts/security/audit.sh, .gitea/workflows/ci.yml (job security-audit), docs/SECURITY_AUDIT.md, SECURITY.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.