4nk/sdk-signer-client
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
sdk-signer-client/AGENTS.md

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

Exécution locale et neutralisation de la CI

  • Les contrôles CI peuvent être remplacés par l’exécution locale des agents: scripts/agents/run.sh avec AUTO_FIX=1, SCOPE=changed|all.
  • La CI peut être neutralisée par défaut via CI_SKIP=true dans le workflow; ponctuellement via des commits [skip ci].
  • Des hooks sont fournis pour automatiser le flux local:
    • scripts/local/precommit.sh et scripts/local/prepush.sh
    • installation: bash scripts/local/install_hooks.sh
  • Un conteneur unifié (runner+agents) permet une exécution reproductible: docker-compose.ci.yml.