4NK_template/docs/project/AGENTS_RUNTIME.md

Exécution des agents — 4NK_template (projet)

Ce guide décrit comment utiliser et intégrer les agents de conformité (qualité, documentation, sécurité, déploiement, etc.) fournis par le template.

1. Présentation

• Agents bash (recommandé) avec rapports Markdown
• Fallback PowerShell (Windows) produisant des contrôles simplifiés
• Intégration CI (agents-smoke, openia-agents) et garde bash-required

2. Prérequis

• bash disponible (Git Bash/WSL/Linux/macOS) pour les contrôles complets
• (Optionnel) OPENAI_API_KEY pour activer l’analyse IA
• (Option) conteneur unifié runner+agents: docker-compose.ci.yml

3. Commandes

• Bash (recommandé):

  • scripts/agents/run.sh
  • Options (facultatives): scripts/agents/run.sh [target_dir] [output_dir] [agent]
    • Par défaut: target_dir=. output_dir=tests/reports/agents agent=all

• PowerShell (fallback Windows):

  • scripts/agents/run.ps1
  • Options (facultatives): -TargetDir . -OutputDir tests/reports/agents -Agent <nom>

• Conteneur unifié:

  • Build: docker compose -f docker-compose.ci.yml build
  • Exécuter agents: docker compose -f docker-compose.ci.yml up --abort-on-container-exit
  • Lancer runner: RUNNER_MODE=runner BASE_URL=... REGISTRATION_TOKEN=... docker compose -f docker-compose.ci.yml up -d

10. Intégration dans un projet existant

bash scripts/deploy/setup.sh <git_url_du_projet> [--dest DIR] [--force]
# Compléter ~/.4nk_template/.env si besoin

4. Agents disponibles

• Documentation (documentation): fichiers essentiels et index
• Qualité technique (quality-technique): fichiers de base, lint/type-check si outillage présent
• Open source (open-source): LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, checklists
• Tests (tests): structure, logs et rapports
• Performance (performance): structure et recommandations
• Sécurité (securite): posture, CI security-audit
• Déploiement (deploiement): documentation et contrôles CI
• Dépendances (dependances): politique et mise à jour
• Compilation (compilation): étapes de build en CI
• Résolution (resolution): REX/archives
• SSH & scripts (ssh-scripts): scripts SSH et doc associée
• Frontend (frontend): principes génériques si applicable
• Gitea (gitea): templates et workflows
• Versionnage (versionnage): CHANGELOG/TEMPLATE_VERSION
• Synchronisation (sync-template): manifeste/template-sync
• Dérogations locales (derogations-locales): fichier de dérogations

5. Sorties

• Rapports Markdown: tests/reports/agents/*.md
• À relire avant PR; corriger les écarts signalés

6. Intégration CI

• agents-smoke: agents en mode sans IA (rapports artefacts)
• openia-agents: agents avec IA si OPENAI_API_KEY fourni
• bash-required: bloque si bash/runner absent
• release-guard: dépend des checks en amont
• (Option) étape pour builder/lancer docker-compose.ci.yml si utilisation du conteneur unifié

7. Paramètres IA (optionnels)

• OPENAI_API_KEY, OPENAI_MODEL, OPENAI_API_BASE, OPENAI_TEMPERATURE

8. Auto‑corrections (optionnelles)

• AUTO_FIX=1 permet aux agents d’appliquer des corrections minimales:
  • création des dossiers tests/** manquants
  • génération de squelettes Markdown basiques pour quelques fichiers de docs/
• Traçabilité: les actions sont listées dans les rapports tests/reports/agents/*.md

9. Bonnes pratiques

• Exécuter les agents avant chaque PR
• Archiver les rapports significatifs
• Documenter les décisions dans le changelog et la doc
• Si contrôle local complet: activer CI_SKIP=true côté dépôt pour ne pas consommer la CI; ajouter au besoin [skip ci] dans les commits automatisés